Connect to EDRS Server (QxdaConnectEDRS) API

The Connect to EDRS Server (QxdaConnectEDRS) API is used to initiate a connection between the local system (requesting system), and a server system. The connection can be local, where the server system is the local system. For non-local connections, a corresponding shadow job is started on the server system. If the input structure format used is the basic input structure (CDBI0100), then the shadow job is swapped to run under the same user profile, using the same job description, coded character set identifier (CCSID), and job priority as the client system job. The user profile, user password, and job description must be identical on both systems for a successful connection. If the input structure format used is CDBI0200, then the shadow job will run under the specified user profile name. It will use the specified user profile's associated job description and job priority. The CCSID will be set to the CCSID of the server job field in the input structure.

For TCP/IP or UNIX domain sockets connections, a controller job must be started on the server system before calling the QxdaConnectEDRS API on the client system. The controller job can be started by using the STRTCPSVR command, specifying the *EDRSQL server.

If a TCP/IP or UNIX domain socket connection is being requested, the password level (QPWDLVL system value) of the server system must be compatible with the requesting server. If the password level is 0 or 1, or is a pre-V5R1 system, then the requesting system should be 0 or 1. Likewise, if the V5R1 server system's password level is 2 or 3, the V5R1 requesting system should also be set to 2 or 3. Failure to coordinate the password level in this fashion will prevent a successful connection, resulting in the CPI2A5A message.

Note that the CDBI0200 format cannot be used when the connection type is 'O' (Opticonnect). CDBI0200 is intended for use only with TCP/IP and UNIX socket connections. For additional restrictions that apply to OptiConnect connections, see the OptiConnect API documentation.

The connection handle returned by this API is valid only in the same job and activation group in which it was generated. A connection cannot span multiple jobs or activation groups.

If a relational database (RDB) name is specified for either the CDBI0100 or CDBI0200 format, it must be blank padded to 18 characters, the maximum length of an RDB name. If the server system does not have any active independent ASPs, the only RDB that can be connected is the *LOCAL RDB. All other RDB names will cause the CPFB752 message to be sent to the caller. The *LOCAL RDB can be determined by viewing the 'remote location' column when executing the WRKRDBDIRE command.

If XA commitment control is specified for either the CDBI0100 or CDBI0200 format, the Transaction Manager Information field must be blank padded to 10 characters, the maximum length, and a Lock Timeout Value should be given. Specifying a *LOCAL connection type along with a *XA commit scope value will cause the CPFB754 with reason code 2 message to be sent to the caller. Likewise, specifying a N commitment control value along with a *XA commit scope value will cause the CPFB754 with reason code 3 message to be sent to the caller. XA commitment control can only be specified over TCP/IP, UNIX domain sockets, or OPTI-CONNECT. The QxdaXA* API's use the connection as the XA thread of control, opposed to the XA API's, which use the thread as the XA thread of control.

If thread safety has been specified, prior to the CONNECT (via the QxdaSetOptions API), all threads must specify connection type U or connection type T.

Authorities and Locks

None.

Required Parameter Group

Input structure

INPUT; CHAR(*)

The structure in which to pass information about the connection. For the format of this parameter, see the CDBI0100 Format or the CDBI0200 Format.

Input structure format

INPUT; CHAR(8)

The format of the input structure template being used. The possible value is:

CDBI0100	Basic input structure
CDBI0200	Basic input structure with user profile and password fields

Receiver variable

OUTPUT; CHAR(*)

The structure in which to return information about the connection. For the format of this parameter, see CDBO0100 Format.

Length of receiver variable

INPUT; BINARY(4)

The number of bytes that the calling program provides for the receiver variable data.

Receiver variable format

INPUT; CHAR(8)

The format of the receiver variable template being used. The possible value is:

CDBO0100

Basic receiver variable

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

CDBI0100 Format

The following table shows the information to pass in the CDBI0100 format. For more details about the fields in this table, see Field Descriptions.

CDBI0200 Format

The following table shows the information to pass in the CDBI0200 format. For more details about the fields in this table, see Field Descriptions.

CDBO0100 Format

The following table shows the information returned in the CDBO0100 format. For more details about the fields in the following table, see Field Descriptions.

Field Descriptions

Allow job suspension. Whether or not to allow this job to be suspended or switched to run to a backup server if there is a server system failure or backup. The possible values are:

Bytes available. The length of the information available to the API to return, in bytes.

Bytes returned. The actual length of information returned to the caller of the API.

CCSID of password. The CCSID of the password. The possible values are:

CCSID of server job The CCSID of the job on the server system. The possible values are:

Commit scope. The commitment definition scope. A value must be specified regardless of the commit level. The possible values are:

Commitment control. The commit level to be used. The possible values are:

Connection type. The communications type to use for the connection. The possible values are:

L	Local connection: Only one local connection per job may be open at a time. If a second local connection is attempted in the job, the connection actually will be made over UNIX domain sockets.
O	OptiConnect
T	TCP/IP sockets
U	UNIX domain sockets. If thread safety is on, each thread must use connection type U or connection type T.

Connection type used. The connection type that was actually used for the connection.

Connection handle. A unique handle number for the connection. The maximum number of connections per job that may be open at one time is 30.

Convert endian data. Whether integer data should be converted from i5/OS big-endian format to Windows PC little-endian format. The field is only used by the Client Access Express version of this API when returning data into the SQL Descriptor Area (SQLDA). The possible values are:

Job-associated user data. Data to associate with the server job that allows the job to be found using the QxdaFindJob API.

Job-suspension user data. Data associated with the current job to allow the job to be suspended independent of an entire system suspension.

Length of job-associated user data. The length of the job-associated data passed.

Length of job-suspension user data. The length of the job-suspension user data passed. This parameter must be set to 0 if the allow job suspension parameter is N.

Length of password associated with user profile. The length of the user profile password passed. The maximum length for the password is 512 bytes. Passwords can have a maximum of 128 characters. 512 bytes can accommodate 128 double bytes characters with a shift-in, shift-out pairing.

Length of user profile data. The length of the user profile data passed.

Lock timeout value. Timeout value for locks in seconds.

Offset to job-associated user data. The offset from the beginning of the input structure to the job-associated user data in the input structure, in bytes.

Offset to job-suspension user data. The offset from the beginning of the input structure to the job-suspension user data in the input structure, in bytes. This value must be 0 if the allow job suspension parameter is set to N.

Offset to password associated with user profile. The offset from the beginning of the input structure to the password associated with the user profile in the input structure, in bytes.

Offset to user profile data. The offset from the beginning of the input structure to the user profile data in the input structure, in bytes.

Password associated with user profile data. The password to be used in conjunction with the user profile to connect to the server system.

Relational database (RDB) nameThe relational database on the server system to which the connection should be made. This field should be blank padded to 18 characters or unpredictable results may occur. If the field is set to all blanks, the connection will be made to the *LOCAL (SYSBAS) RDB on the server system. If the server system does not have any active independent ASPs, an error will be signaled for any RDB that is not defined as the the *LOCAL RDB.

Relational database (RDB) specifiedSpecifies whether the relational database (RDB) name field was provided. Possible values are:

Reserved. Reserved field; it must be initialized to 0x00.

Server job name. The job name of the database server job. If this is a local connection, this will be the current job name.

Server job number. The job number of the database server job. If this is a local connection, this will be the current job number.

Server job user name. The user name of the database server job's initial user. If this is a local connection, this will be the current job's initial user.

Server system name. The null-terminated name of the system to which to connect. For connection type O, this is the current system name as displayed on the Display Network Attributes (DSPNETA) display on the server system. For connection type T, this is the server system name as displayed in the TCP/IP host table. It must be initialized to blanks for all other connection types. If the server system name is the local system, the connection actually will be made locally.

SQL hexadecimal constants. This corresponds to the SET OPTION SQLCURRULE option and controls how hexadecimal constants are treated within SQL statements.

SQLDA cache size. The number of SQL descriptor areas to store for later reuse. An improvement in performance will be seen if an SQL descriptor area can be reused.

Transaction manager information. Transaction manager name.

User profile data. The name of the user profile to use to connect to the server system.

Usage Notes

This function may be called from the initial thread of a job only.

Error Messages