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:
Specifies an embedded variable that is declared as CHAR type (5 bytes, fixed).
The specified value should be the environment variable group identifier (5 bytes, fixed, including null characters) that is specified in the character string for the xa_open function.
Common rules
Notes
Example
Allocate a connection handle with a PDCNCTHDL-type variable CnctHdl, return code receiving variable GetchdlRtn, and environment variable group identifier variable GroupName:
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;
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:
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()