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:

C language
Normal allocation:
p_rdb_RC_NORM
Invalid connection handle value:
p_rdb_RC_ERRPARM
Insufficient memory:
p_rdb_RC_MEMERR
These values are defined in the pdberrno.h file.
COBOL language
Normal allocation:
P-RDB-RC-NORM
Invalid connection handle value:
P-RDB-RC-ERRPARM
Insufficient memory:
P-RDB-RC-MEMERR
These values are defined in the PDBSQLCAMTH.CBL file.

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

  1. ALLOCATE CONNECTION HANDLE should be issued before the CONNECT statement.
  2. The embedded variables to be used must be declared in the embedded SQL declare section.
  3. If allocation of a connection handle fails, the system sets the error code in the return code-receiving variable.
  4. The connection PDHOST variable and the connection PDNAMEPORT variable should be declared either together or not at all. If these variables are omitted, the system connects to a database on the basis of a value specified in the client environment definition.
  5. A null character must be used at the end of the host name specified in the connection PDHOST variable.

Note

  1. Connection handles that have been allocated are not released when a DISCONNECT statement is issued. To release a connection handle, a FREE CONNECTION HANDLE statement must be issued.
  2. When setting a value for the connection PDHOST variable and environment variable group name variable in COBOL, a null character must be used at the end of the value.
  3. When specifying the connection PDHOST variable and connection PDNAMEPORT variable, if a high-speed connection or an FES host direct connection is specified in the client environment definition, the connection to the HiRDB server will be made using the connection type specified in the client environment definition. For details about how to select the connection type, see Environment variables and connection types for HiRDB servers in the HiRDB Version 9 UAP Development Guide.

Example

  1. The following are examples of using a PDCNCTHDL type variable:
    C language

    EXEC SQL BEGIN DECLARE SECTION;
     PDCNCTHDL   CnctHdl;
     long        AlchdlRtn;
    EXEC SQL END DECLARE SECTION;
    EXEC SQL ALLOCATE CONNECTION HANDLE :CnctHdl,
                                       :AlchdlRtn;

    COBOL language

    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.

  2. The following are examples of using a connection PDHOST variable and a connection PDNAMEPORT variable:
    C language

    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;

    COBOL language

    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.

  3. The following are examples of using an environment variable group name:
    C language

    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;

    COBOL language

    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.