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 an embedded variable that was declared as a CHAR type (area size: 511 bytes).

Specifies an embedded variable that was declared as a SMALLINT type.

Specifies an embedded variable that is declared as a CHAR type (area length of 256 bytes).

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).

drive-name\.ini"HiRDB Version 8 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. The last character in the host name that is assigned in the connection PDHOST variable must be the null character.

Note

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.

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.