Change RDB Directory Entry (CHGRDBDIRE)
The Change Relational Database Directory Entry (CHGRDBDIRE) command allows you to change an entry in the relational database (RDB) directory. Values for any of the RDB's parameters, except its name and alias, can be changed.
Note: Changes to an entry do not affect any connections that are using the RDB directory when the change is made. Changes take effect the next time a CONNECT operation is performed.
Restrictions:
- You must have execute (*EXECUTE) authority to the program specified for the Application requester driver (ARDPGM) parameter.
| Keyword |
Description |
Choices |
Notes |
| RDB |
Entry |
Element list |
Required, Key, Positional 1 |
| Element 1: Relational database |
Character value |
| Element 2: Relational database alias |
Character value, *NONE |
| RMTLOCNAME |
Remote location |
Single values: *ARDPGM, *LOOPBACK Other values: Element list |
Optional, Positional 2 |
| Element 1: Name or address |
Character value, *SAME, *LOCAL |
| Element 2: Type |
*SAME, *SNA, *IP |
| PORT |
Port number or service program |
Character value, *SAME, *DRDA |
Optional |
| RMTAUTMTH |
Remote authentication method |
Element list |
Optional |
| Element 1: Preferred method |
*SAME, *USRID, *USRIDPWD, *USRENCPWD, *ENCUSRPWD, *KERBEROS, *ENCRYPTED |
| Element 2: Allow lower authentication |
*SAME, *ALWLOWER, *NOALWLOWER |
| ENCALG |
Encryption algorithm |
*SAME, *DES, *AES |
Optional |
| SECCNN |
Secure connection |
*SAME, *NONE, *SSL |
Optional |
| DEV |
Device |
Element list |
Optional |
| Element 1: APPC device description |
Name, *SAME, *LOC |
| LCLLOCNAME |
Local location |
Communications name, *SAME, *LOC, *NETATR |
Optional |
| RMTNETID |
Remote network identifier |
Communications name, *SAME, *LOC, *NETATR, *NONE |
Optional |
| MODE |
Mode |
Communications name, *SAME, *NETATR |
Optional |
| TNSPGM |
Transaction program |
Character value, *SAME, *DRDA |
Optional |
| ARDPGM |
Application requester driver |
Single values: *SAME, *DRDA Other values: Element list |
Optional |
| Element 1: Program |
Qualified object name |
| Qualifier 1: Program |
Name |
| Qualifier 2: Library |
Name, *LIBL, *CURLIB |
| TEXT |
Text |
Character value, *SAME, *BLANK |
Optional |
Entry (RDB)
Specifies the relational database name information.
This is a required parameter.
Note: Valid relational database names and aliases can contain any of the following: A-Z, 0-9, @, #, $ and _.
Element 1: Relational database
-
- character-value
- Specify the relational database name as identified at the remote location. You can specify a maximum of 18 characters for the name; however, DB2 UDB for z/OS relational database names are limited to 16 characters.
Element 2: Relational database alias
-
- *NONE
- There is no local alias for the relational database.
- character-value
- Specify the relational database alias. The alias is used for locally identifying the relational database specified above. You can specify a maximum of 18 characters for the alias. A relational database alias name is not valid when specified with a *LOCAL remote location name.
Remote location (RMTLOCNAME)
Specifies the remote location name of the system on which the relational database (RDB) is located.
Single values
-
- *SAME
- The remote location name does not change.
- *ARDPGM
- The RDB is accessed by using the application requester driver program specified on the ARDPGM parameter. A remote location name is not used to locate the RDB.
Note: If *ARDPGM is specified, the PORT, DEV, LCLLOCNAME, RMTNETID, MODE, and TNSPGM parameters are ignored.
- *LOOPBACK
- This value is an alias for the IP address of the host system.
Note: If *LOOPBACK is specified, the DEV, LCLLOCNAME, RMTNETID, MODE, TNSPGM and ARDPGM parameters are ignored, and the value of the second element is forced to *IP.
Element 1: Name or address
-
- *LOCAL
- This entry is the system database (system ASP and any basic ASPs) on this system. You can specify *LOCAL for only one entry in the RDB directory.
Note: If *LOCAL is specified, the DEV, LCLLOCNAME, RMTNETID, MODE, TNSPGM and ARDPGM parameters are ignored, and the value of the second element is forced to *IP. A relational database alias name is not valid when specified with a *LOCAL remote location name.
- character-value
- The first element of this parameter can be specified in several forms:
- SNA remote location name (LU name). Specify a maximum of 8 characters for the remote location name. If this form is used, the second element of this parameter must be *SNA (the default).
- SNA remote network identifier and remote location name separated by a period. Specify a maximum of 8 characters for the remote location name, and a maximum of 8 characters for the remote network identifier. If this form of the parameter is used, the second element of this parameter must be *SNA (the default), and any value specified for the RMTNETID parameter must agree. If the RMTNETID parameter is not specified, the RMTNETID value will be set to agree with the RMTLOCNAME parameter.
- IP version 4 address in dotted decimal form. Specify an internet protocol version 4 address in the form nnn.nnn.nnn.nnn where each nnn is a number in the range 0 through 255. If this form is used, the second element of this parameter must be specified as *IP.
- IP version 6 address in colon hexadecimal form. Specify an internet protocol version 6 address in the form xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx where each xxxx is a hex number in the range 0 through FFFF. If this form is used, the second element of this parameter must be specified as *IP. IP version 6 includes the IPv4-mapped IPv6 address form (for example, ::FFFF:1.2.3.4). For IP version 6, the compressed form of the address is allowed.
- IP host domain name. Specify an internet host domain name of up to 254 characters in length. If this form is used, the second element of this parameter must be specified as *IP.
If *IP is specified for the second element, the DRDA server at the remote location must support the use of TCP/IP, and the DEV, LCLLOCNAME, RMTNETID, MODE, and TNSPGM parameters will be ignored.
If *SNA is specified for the second element, the server must support SNA connectivity. More information about SNA remote location names can be found in the APPC Programming book, SC41-5443 and the APPN information in the Networking category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
Element 2: Type
-
- *SNA
- The RDB system is accessed using a Systems Network Architecture (SNA) address and protocol.
- *IP
- The RDB system is found using a host name or an internet address over a TCP/IP connection.
Port number or service program (PORT)
Specifies the TCP/IP port that is used at the remote location to communicate with the system on which the RDB is located. This parameter will be ignored if *IP is not specified in the RMTLOCNAME parameter.
-
- *SAME
- The value does not change.
-
- *DRDA
- The DRDA well-known port of 446 will be used.
- port-number
- Specify a number ranging from 1 through 65535.
- service-name
- Specify a maximum of 14 characters for the service name. This name must be registered in the service database file.
Remote authentication method (RMTAUTMTH)
Specifies the preferred remote authentication method on a DDM/DRDA TCP/IP connection request. The actual method used depends on the outcome of the negotiation process between client and server, which depends on the cryptographic support available and the server security configuration. The CHGDDMTCPA (Change DDM TCP/IP Attributes) command can be used to configure DDM/DRDA TCP/IP security on i5/OS systems. This parameter will be ignored if *IP is not specified in the Remote location (RMTLOCNAME parameter).
Element 1: Preferred method
Specifies the initial authentication method proposed to the server. Based on the authentication methods supported by the server and the value specified for the Allow lower authentication element of this parameter, an authentication method is negotiated that is acceptable to both the client and server.
-
- *SAME
- This value does not change.
- *USRID
- User ID only is sent on a DDM connection request. This is the lowest authentication method.
- *USRIDPWD
- User ID and associated password is sent on a DDM connection request. Passwords are not encrypted if this authentication method is used.
- *USRENCPWD
- User ID and associated encrypted password is sent on a DDM connection request. Cryptographic support must be available on both systems for this authentication method to be used.
- *ENCUSRPWD
- Encrypted user ID and associated encrypted password is sent on a DDM connection request. Cryptographic support must be available on both systems for this authentication method to be used.
- *KERBEROS
- Authentication occurs using Kerberos. The RDB name must map to a target principal name in the Enterprise Identity Mapping (EIM) environment. Kerberos needs to be configured on both systems for this authentication method to be used.
Note: The following value is only supported for compatibility with the releases earlier than Version 5 Release 5 Modification 0 of the operating system.
-
- *ENCRYPTED
- User ID and associated encrypted password is sent on a DDM connection request. Cryptographic support must be available on both systems for this authentication method to be used. It is recommended to use value *USRENCPWD in place of value *ENCRYPTED.
Element 2: Allow lower authentication
Specifies whether an authentication method lower than what was specified for the Preferred method element of this parameter will be accepted during negotiation with the server. If the server is configured to require a higher authentication method than the value specified for the Preferred method element of this parameter and the Application Requester system can support a higher authentication method, the negotiated authentication method can always be higher than the Preferred method. From highest to lowest, the authentication methods are:
- *KERBEROS
- *ENCUSRPWD
- *USRENCPWD or *ENCRYPTED
- *USRIDPWD
- *USRID
-
- *SAME
- This value does not change.
- *ALWLOWER
- Allow negotiation of a lower authentication method than what was specified for the Preferred method element of this parameter.
- *NOALWLOWER
- Do not allow negotiation of a lower authentication method than what was specified for the Preferred method element of this parameter.
Encryption algorithm (ENCALG)
Specifies the encryption algorithm to be initially used on a DDM/DRDA TCP/IP connection request when encrypting the userid and password. The actual encryption algorithm used depends on the outcome of the negotiation process between client and server, which depends on the cryptographic support available and the server security configuration. The CHGDDMTCPA (Change DDM TCP/IP Attributes) command can be used to configure DDM/DRDA TCP/IP security on i5/OS systems. This parameter will be ignored if *IP is not specified in the Remote location (RMTLOCNAME parameter). The possible values are:
-
- *SAME
- This value does not change.
- *AES
- Advanced Encryption Standard (AES) is to be initially used. If the server supports AES, the connection will negotiate to use AES. If the server does not support AES, the connection will be refused. If it is known that the server supports AES, it is recommended that the user specify *AES on the ENCALG keyword on the ADDRDBDIRE (Add RDB Directory Entry) command or CHGRDBDIRE (Change DDM TCP/IP Attributes) command to avoid a re-negotiation flow that may occur when *DES is specified.
- *DES
- Data Encryption Standard (DES) is to be initially used. Setting to *DES does not guarantee that DES will be used. If the server supports AES, the server may force re-negotiation with the client to upgrade to AES, or it may use DES. If the server only supports AES, the server may force re-negotiation with the client to upgrade to AES, or the server may refuse the connection. If it is known that the server supports AES, it is recommended that the user specify *AES on the ENCALG keyword on the ADDRDBDIRE (Add RDB Directory Entry) command or CHGRDBDIRE (Change DDM TCP/IP Attributes) command to avoid a re-negotiation flow that may occur when *DES is specified.
From highest to lowest strength, the encryption algorithms are:
Secure connection (SECCNN)
Indicates whether Secure Sockets Layer (SSL) is to be used on a DDM/DRDA TCP/IP connection request. The possible values are:
-
- *SAME
- This value does not change.
- *NONE
- Secure sockets layer is not used.
- *SSL
- Secure sockets layer is used.
Device (DEV)
Specifies the advanced program-to-program communications (APPC) device description on this system that is used with this relational database (RDB) entry.
More information is in the APPC Programming book, SC41-5443, and the APPN information in the Networking category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
-
- *SAME
- The name of the device description does not change.
- *LOC
- If APPC is being used, the system determines which device description is used. If advanced peer-to-peer networking (APPN) is being used, the system ignores this parameter.
- name
- Specify a maximum of 10 characters for the name of a device description.
Local location (LCLLOCNAME)
Specifies the local location name by which this system is identified to the system on which the RDB is located. The local location name cannot be the same as the remote location name.
More information on local location names is in the APPC Programming book, SC41-5443.
-
- *SAME
- The local location name does not change.
- *LOC
- If advanced program-to-program communications (APPC) is being used, the system determines which local location name is used. If advanced peer-to-peer networking (APPN) is being used, the system uses the default local location name defined in the network attributes.
-
- *NETATR
- The LCLLOCNAME value specified in the system network attributes is used.
-
- communications-name
- Specify a maximum of 8 characters for the local location name.
Remote network identifier (RMTNETID)
Specifies the remote network identifier of the system on which the RDB is located. If this parameter is specified, the RMTLOCNAME parameter must be consistent with this RMTNETID parameter. If the RMTLOCNAME parameter specified a network ID, this parameter must agree (otherwise, an error message will be issued). If the RMTLOCNAME parameter does not specify any network ID, there is no possibility of conflict with this parameter.
More information on remote network identifiers is in the APPC Programming book, SC41-5443.
-
- *SAME
- The value does not change.
-
- *LOC
- If advanced program-to-program communications (APPC) is being used, the system determines which remote network identifier is used. If advanced peer-to-peer networking (APPN) is used, the system uses the local network identifier defined in this system's network attributes for the remote network identifier.
-
- *NETATR
- The LCLNETID value specified in the system network attributes is used.
-
-
- *NONE
- No remote network identifier (ID) is used.
-
- communications-name
- Specify a maximum of 8 characters for the remote network identifier.
More information on remote network identifiers is in the APPC Programming book, SC41-5443.
Mode (MODE)
Specifies the mode name to use with the remote location name to communicate with the system on which the RDB is located.
-
- *SAME
- The mode name does not change.
-
- *NETATR
- The mode in the network attributes is used.
-
- BLANK
- A mode name of all blanks is used.
- communications-name
- Specify a maximum of 8 characters for the mode name.
More information on mode names is in the APPC Programming book, SC41-5443.
Transaction program (TNSPGM)
Specifies the name of the transaction program to use with the RDB entry.
-
- *SAME
- The transaction program does not change.
- *DRDA
- The distributed relational database architecture (DRDA) transaction program name, X'07F6C4C2', is used. DRDA is a means by which RDBs communicate with each other over a network.
-
- name
- Specify the name of the transaction program in one of the following formats:
- A 4-byte hexadecimal name, which is entered by enclosing the 8 hexadecimal digits in single quotation marks with a prefix of X. For example, X'07F6C4C2' is a 4-byte hexadecimal name.
- An 8-byte character name.
Application requester driver (ARDPGM)
Specifies the application requester driver that is the program to be called to process SQL requests directed to the RDB. The program must exist in a library that is located in the system database (system ASP or a configured basic user ASP) on this system, and must be of the object type *PGM.
Single values
-
- *SAME
- The application requester driver program is not changed.
- *DRDA
- The Distributed Relational Database Architecture (DRDA) application requester is used.
Qualifier 1: Program
-
- name
- Specify the name of the application requester driver program to be called to process the SQL requests.
Qualifier 2: Library
-
- *LIBL
- All libraries in the library list for the current thread are searched until the first match is found.
- *CURLIB
- The current library for the thread is searched. If no library is specified as the current library for the thread, the QGPL library is searched.
- name
- Specify the name of the library where the program is located.
Text (TEXT)
Specifies the text that briefly describes the object.
-
- *SAME
- The text does not change.
- *BLANK
- The text is changed to blanks.
- character-value
- Specify no more than 50 characters of text enclosed in single quotation marks.
Example 1: Changing an Entry for *SNA type
CHGRDBDIRE RDB(YOURRDB) RMTLOCNAME(NEWARK)
This command changes a directory entry to use Newark as the new remote location name to access YOURRDB.
Example 2: Changing an Entry for *IP type
CHGRDBDIRE RDB(MYRDB) RMTLOCNAME(ROCHESTER.XYZ.COM *IP)
This command changes a directory entry to use an internet protocol domain name to access MYRDB. The second element of RMTLOCNAME indicates that TCP/IP is to be used for connections.
*ESCAPE Messages
- CPF3EC1
- Change relational database directory entry failed.