ADDRDBDIRE (Add Relational Database Directory Entry) Command Description
ADDRDBDIRE Command syntax diagram
Purpose
The Add Relational Database Directory Entry (ADDRDBDIRE) command adds a relational database entry to the relational database directory.
Each entry describes the method of accessing a relational database. One special entry must exist which names the local relational database located on the system auxiliary storage pool (ASP number 1) and configured basic user ASPs (ASP numbers 2-32). This entry has *LOCAL in the RMTLOCNAME parameter first element.
Entries for auxiliary storage pool groups (with ASP numbers > 32) will be added by the system the first time the ASP group is varied on, if not already present. The value of the RMTLOCNAME parameter first element for the automatically added entries will be *LOOPBACK, which maps to an IP address associated with the host system. If some other IP address is required for an ASP group, it will have to be specified manually either before it is varied on, by means of the ADDRDBDIRE command, or afterward by means of the CHGRDBDIRE command.
One entry naming each remote relational database or application requester driver program must also be added.
Each relational database name must be unique within the relational database directory and within the distributed network.
For more information on the relational database directory, refer to the Distributed Database Programming topic in the Information Center.
Restriction: If adding an entry for an SQLCI application requester driver (ARD) program using the ARDPGM parameter, have execute authority to the application requester driver program and library to specify the ARD program on this command.
Required Parameters
- RDB
- Specifies the name of the relational database being added. Each name entered into the directory must be unique. Because relational databases communicate with each other over a distributed network, each name must also be unique among other relational databases on the network. The system can determine whether a relational database name is unique in the directory, but determine whether it is unique among relational databases on the network. A maximum of 18 characters can be specified for the relational database name. If a DB2* for MVS relational database is identified, only 16 characters are allowed.
Note: Valid RDB names must begin with a letter and consist of uppercase A-Z, 0-9, and underscore.
- RMTLOCNAME
- Specifies the name or address of the system on which the relational database is located.
*LOCAL: The relational database is located on the system auxiliary storage pool (ASP number 1) and configured basic user ASPs (ASP numbers 2-32) on this system. You can specify *LOCAL for only one entry in the relational database directory.
Note: If *LOCAL is specified, the DEV, LCLLOCNAME, RMTNETID, MODE, TNSPGM, and ARDPGM parameters will be ignored, and the value of the second element is forced to *IP. *LOOPBACK: The relational database is accessed using the internet protocol loopback or LOCAL HOST address. The use of *LOOPBACK allows a DRDA connection to a database on the local system.
Note: If *LOOPBACK is specified, the DEV, LCLLOCNAME, RMTNETID, MODE, TNSPGM, and ARDPGM parameters will be ignored, and the value of the second element is forced to *IP.
*ARDPGM: The relational database is located by using the application requester driver program specified on the ARDPGM parameter. A remote location name is not used to locate the relational database.
Note: If *ARDPGM is specified, the PORT, DEV, LCLLOCNAME, RMTNETID, MODE, and TNSPGM parameters will be ignored. remote-location-name: The first element of this parameter can take 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 address in dotted decimal form. Specify an internet protocol 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 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 application 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 *IP is not specifed, the application server must support SNA connectivity. More information about SNA remote location names can be found in the APPC, APPN, and HPR topic in the Information Center.
Optional Parameters
- TEXT
- Specifies text that briefly describes the relational database.
*BLANK: No text is associated with the new relational database.
'description': Specify no more than 50 characters of text, enclosed in apostrophes.
- PORT
- Specifies the TCP/IP port that is used at the remote location to communicate with the system on which the relational database is located. This parameter will be ignored if *IP is not specified in the RMTLOCNAME parameter.
*DRDA: The DRDA well-known port of 446 will be used.
port-number: Specify a number in the range 1-65535.
service-name: Specify a maximum of 14 characters for the service name. This name must be registered in the service database file.
- 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 iSeries servers. 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 Application Requester and Application Server systems.
Possible values are:
*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.
*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.
*KERBEROS Authentication occurs using Kerberos. The relational database 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.
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 Application Server system. If the Application Server system 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
- *ENCRYPTED
- *USRIDPWD
- *USRID
Possible values are:
*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.
- DEV
- Specifies the name of the advanced program-to-program communications (APPC) device description on the local system that is used to access this relational database. The device description does not need to exist when the relational database directory entry is added.
More information on device names is in the APPC, APPN, and HPR topic in the Information Center.
*LOC: If APPC is being used, the system determines which device description is used. If the advanced peer-to-peer networking (APPN) function is being used, the system ignores this parameter.
device-description-name: Specify a maximum of 10 characters for the name of a device description.
- LCLLOCNAME
- Specifies the local location name by which the local system is identified to the system on which the relational database 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, APPN, and HPR topic in the Information Center.
*LOC: If APPC is being used, the system determines which local location name is used. If the APPN function is being used, the system uses the default local location name specified in the network attributes.
*NETATR: The local location name defined in the network attributes is used.
local-location-name: Specify a maximum of 8 characters for the local location name.
- RMTNETID
- Specifies the remote network identifier of the system on which the relational database 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, APPN, and HPR topic in the Information Center.
*LOC: If APPC is being used, the system determines which remote network identifier is used. If the APPN function is being used, the system uses the local network identifier defined in the system's network attributes for the remote network identifier.
*NETATR: The local network identifier defined in the local system's network attributes is used for the remote network identifier.
*NONE: No remote network identifier is used.
remote-network-identifier: Specify a maximum of 8 characters for the remote network identifier.
- MODE
- Specifies the mode name that is used with the remote location name to communicate with the system on which the relational database is located.
*NETATR: The mode name defined in the network attributes is used.
mode-name: Specify a maximum of 8 characters for the mode name.
More information on mode names is in the APPC, APPN, and HPR topic in the Information Center.
- TNSPGM
- Specifies the name of the transaction program to use with the relational database entry.
*DRDA: The Distributed Relational Database Architecture* (DRDA*) transaction program name, X'07F6C4C2', is used. DRDA is a means by which relational databases communicate with each other over a distributed network.
transaction-program-name: Specify the transaction program name in either of the following formats:
- A 4-byte hexadecimal name, which is entered by enclosing the 8 hexadecimal digits in apostrophes with a prefix of X. For example, X'07F6C4C2' is a 4-byte hexadecimal name.
- An 8-byte character name, which is entered by specifying the name in its 8-character form.
- ARDPGM
- Specifies the qualified name of the application requester driver (ARD) that is the program to be called to process SQL requests directed to the relational database. The program must exist and must be of the object type *PGM.
*DRDA: The Distributed Relational Database Architecture (DRDA) application requester is used (that is, no ARD program is used).
The possible library values are:
*LIBL: The library list when the directory entry is added is used to locate the program name.
*CURLIB: The current library when the directory entry is added is used to locate the program name. If no library is specified as the current library for the job, the QGPL library is used.
library-name: Specify the name of the library where the program name is located.
program-name: Specify the name of the application requester driver program to be called to process the SQL requests.
Examples for ADDRDBDIRE
Example 1: Adding an Entry
ADDRDBDIRE RDB(MYRDB) RMTLOCNAME(*LOCAL)This command adds an entry to the relational database directory. The entry identifies the local relational database. In an SQL program, this relational database name is used when referring to the local relational database.
Example 2: Adding an Entry
ADDRDBDIRE RDB(YOURRDB) RMTLOCNAME(NEWYORK)This command adds an entry to the relational database directory. The entry identifies a remote location, NEW YORK.
Example 3: Adding an Entry for an Application Requester Driver Program
ADDRDBDIRE RDB(YOURRDB) RMTLOCNAME(*ARDPGM) ARDPGM(MYLIB/MYPGM)This command adds an entry to the relational database directory. The entry indicates that access to relational database YOURRDB will be done by an application requester driver program named MYPGM in the library MYLIB.
Example 4: Adding an Entry for TCP/IP usage
ADDRDBDIRE RDB(TCPRDB) RMTLOCNAME(ROCHESTER.XYZ.COM *IP) PORT(*DRDA)This command adds an entry to the relational database directory. The entry specifies that the remote RDB associated with the RDB name of TCPRDB uses TCP/IP and is on the host with the domain name of ROCHESTER.XYZ.COM, and listens on the standard DRDA port of 446 (*DRDA is the default port so the PORT parameter is unneccessary in this case).
Example 5: Adding an Entry for TCP/IP using dotted decimal IP address and a numeric port number
ADDRDBDIRE RDB(DB2DSYS) RMTLOCNAME('9.5.36.17' *IP) PORT(5021)This command adds an entry to the relational database directory. The entry specifies that the remote RDB associated with the RDB name of DB2DSYS uses TCP/IP and is on the host with an IP address of 9.5.36.17, and listens on port 5021. A System/390 MVS installation, for example, can have multiple DB2 subsystems, and TCP/IP can support only one server at each port number, so port numbers other than 446 are sometimes required.
Example 6: Adding an Entry for TCP/IP using a service name for the port identification
ADDRDBDIRE RDB(DB2ESYS) RMTLOCNAME(ROCHESTER.XYZ.COM *IP) PORT(DB2ESYS_PORT)This command uses a service name to specify the port number when adding a new entry. OS/400 will attempt to resolve the name DB2ESYS_PORT to a port number by use of the TCP/IP Service Table. In order for the name to be properly resolved, an entry for DB2ESYS_PORT must exist in the TCP/IP Service Table. The WRKSRVTBLE or CFGTCP command can be used to update the service table.
Error messages for ADDRDBDIRE
*ESCAPE Messages
- CPF3EC0
- Add relational database directory entry failed.