GET CONNECTION HANDLE (Get connection handle)

Function

When the multi-connection facility is used under the X/Open XA interface environment, GET CONNECTION HANDLE allocates the connection handle to be used by a UAP.

Format

GET CONNECTION HANDLE:PDCNCTHDL-type-variable,
             :return-code-receiving-variable,
             :environment-variable-group-identifier-variable

Operands

Specifies an embedded variable that was declared as a PDCNCTHDL-type.

Specifies an embedded variable that was declared as an INT type.

The following values are returned to the return code receiving variable:

C language
Normal receipt:
p_rdb_RC-NORM
Error:
Error code associated with the particular error
These values are defined in the pdberrno.h file.
COBOL language
Normal receipt:
P-RDB-RC-NORM
These values are defined in the SQLCAMTH.CBL file.

Specifies an embedded variable that is declared as CHAR type (five bytes, fixed).

Character sets other than the default character set cannot be specified.

The specified value should be the environment variable group identifier (five bytes, fixed, including null characters) that is specified in the character string for the xa_open function.

Common rules

  1. The variables must be declared in the embedded variables declaration section.
  2. If acquisition of the connection handle fails, the resulting error code is set in the return code receiving variable.

Notes

  1. When an SQL statement that uses the connection handle acquired in this section is issued, the connection handle to be used must be declared by specifying DECLARE CONNECTION HANDLE SET.
  2. For the COBOL language, when assigning a value to the environment variable group identifier, the last character in the assigned value should be the null character.

Example

Allocate a connection handle with a PDCNCTHDL-type variable CnctHdl, return code receiving variable GetchdlRtn, and environment variable group identifier variable GroupName:

C language

EXEC SQL BEGIN DECLARE SECTION;
 PDCNCTHDL   CnctHdl;
 long        GetchdlRtn;
 char        GroupId[5];
EXEC SQL END DECLARE SECTION;
strcpy(GroupId,"HR01") ;
EXEC SQL GET CONNECTION HANDLE  :CnctHdl,
                               :GetchdlRtn,
                               :GroupId;

COBOL language

DATA DIVISION.
WORKING-STORAGE SECTION.
 EXEC SQL
   BEGIN DECLARE SECTION
 END-EXEC.
01 CNCTHDL     SQL TYPE IS PDCNCTHDL.
01 GETCHDLRTN  PIC S9(9) COMP.
01 GROUPID     PIC X(5).
 EXEC SQL
   END DECLARE SECTION
 END-EXEC.
       :
PROCEDURE DIVISION.
       :
 MOVE 'HR01' & X'00' TO GROUPID.
 EXEC SQL
   GET CONNECTION HANDLE :CNCTHDL,
                         :GETCHDLRTN,
                         :GROUPID;
 END-EXEC.

Additional notes

If HiRDB does not support the multi-connection facility, SQL statements cannot be executed at that HiRDB using multiple connection handles from one transaction. If such a transaction is executed, the HiRDB server aborts with the Pac2354 code and the transaction is rolled back. Therefore, SQL statements that use multiple connection handles cannot be executed simultaneously within a single transaction.

For different copies of HiRDB that are connected to different sites, multiple connection handles can be used within a single transaction.

Following is an example of an incorrect specification:

HiRDB 1 registered in both RM01 and RM02

tx_begin()
strcpy(grpnm, "RM01")
GET CONNECTION HANDLE;
hCnct,:rc,:grpnm;
DECLARE CONNECTION HANDLE SET :hCnct;

SQL execution

strcpy(grpnm, "RM02")
GET CONNECTION HANDLE :hCnct,:rc,:grpnm;
DECLARE CONNECTION HANDLE SET :hCnct;

SQL execution

tx_commit()