ALLOCATE CONNECTION HANDLE (Allocate connection handle)
Function
ALLOCATE CONNECTION HANDLE allocates a connection handle to be used by a UAP in an environment where a multi-connection function is used.
Format
ALLOCATE CONNECTION HANDLE :PDCNCTHDL-type-variable,
:return-code-receiving-variable
[, {:connection-PDHOST-variable,
:connection-PDNAMEPORT-variable
|:environment-variable-group-name-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 the destination host name using an embedded variable declared as CHARACTER type (area length of 511 bytes). Specify the host name in the format specified in PDHOST in the client environment definition.
Character sets other than the default character set cannot be specified.
Specifies the port number to connect to as an embedded variable declared as SMALLINT type. Specify the port number in the format specified in PDNAMEPORT specified in the client environment definition.
Specifies an embedded variable that is declared as a CHAR type (area length of 256 bytes).
Character sets other than the default character set cannot be specified.
In the UNIX environment, specify the file name of the regular file in which the environment variable is coded in terms of an absolute path name (a maximum of 256 bytes including the null character).
In a Windows environment, specify the group name registered using the environment variable registration tool (a maximum of 31 bytes including the null character), or the absolute path name of the environment variable group file name (a maximum of 256 bytes including the null character). All environment variable group file name specifications are assumed to begin with drive-name:\. Environment variable group files in a Windows environment are based on the Windows ini file specification. In a Windows environment, even when specifying environment variable group files using long path names that include spaces, do not enclose the path name in double quotation marks (").
For details about environment variable groups, see the HiRDB Version 9 UAP Development Guide.
Common rules
Note
Example
EXEC SQL BEGIN DECLARE SECTION;
PDCNCTHDL CnctHdl;
long AlchdlRtn;
EXEC SQL END DECLARE SECTION;
EXEC SQL ALLOCATE CONNECTION HANDLE :CnctHdl,
:AlchdlRtn;
DATA DIVISION.
WORKING-STORAGE SECTION.
EXEC SQL
BEGIN DECLARE SECTION
END-EXEC.
01 CNCTHDL SQL TYPE IS PDCNCTHDL.
01 ALCHDLRTN PIC S9(9) COMP.
EXEC SQL
END DECLARE SECTION
END-EXEC.
:
PROCEDURE DIVISION.
:
EXEC SQL
ALLOCATE CONNECTION HANDLE :CNCTHDL,
:ALCHDLRTN;
END-EXEC.
EXEC SQL BEGIN DECLARE SECTION;
PDCNCTHDL CnctHdl;
long AlchdlRtn;
char CnctHost[31];
short CnctPort;
EXEC SQL END DECLARE SECTION;
strcpy(CnctHost,"HOST01");
EXEC SQL ALLOCATE CONNECTION HANDLE :CnctHdl,
:AlchdlRtn,
:CnctHost,
:CnctPort;
DATA DIVISION.
WORKING-STORAGE SECTION.
EXEC SQL
BEGIN DECLARE SECTION
END-EXEC.
01 CNCTHDL SQL TYPE IS PDCNCTHDL.
01 ALCHDLRTN PIC S9(9) COMP.
01 CNCTHOST PIC X(31).
01 CNCTPORT PIC S9(4) COMP.
EXEC SQL
END DECLARE SECTION
END-EXEC.
:
PROCEDURE DIVISION.
:
MOVE 'HOST01' & X'00' TO CNCTHOST.
EXEC SQL
ALLOCATE CONNECTION HANDLE :CNCTHDL,
:ALCHDLRTN,
:CNCTHOST,
:CNCTPORT;
END-EXEC.
EXEC SQL BEGIN DECLARE SECTION;
PDCNCTHDL CnctHdl;
long AlchdlRtn;
char GroupName[31];
EXEC SQL END DECLARE SECTION;
strcpy(GroupName,"HRD01");
EXEC SQL ALLOCATE CONNECTION HANDLE :CnctHdl,
:AlchdlRtn,
:GroupName;
DATA DIVISION.
WORKING-STORAGE SECTION.
EXEC SQL
BEGIN DECLARE SECTION
END-EXEC.
01 CNCTHDL SQL TYPE IS PDCNCTHDL.
01 ALCHDLRTN PIC S9(9) COMP.
01 GROUPNAME PIC X(31).
EXEC SQL
END DECLARE SECTION
END-EXEC.
:
PROCEDURE DIVISION.
:
MOVE 'HRD01' & X'00' TO GROUPNAME.
EXEC SQL
ALLOCATE CONNECTION HANDLE :CNCTHDL,
:ALCHDLRTN,
:GROUPNAME
END-EXEC.