Explicitly Establishing a Session - Teradata Tools and Utilities

Teradata® Call-Level Interface Version 2 Reference for Mainframe-Attached Systems - 17.20

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
Lake
VMware
Product
Teradata Tools and Utilities
Release Number
17.20
Published
June 2022
ft:locale
en-US
ft:lastEdition
2023-11-17
dita:mapPath
oxw1641281447623.ditamap
dita:ditavalPath
obe1474387269547.ditaval
dita:id
vfj1470443597526
Product Category
Teradata Tools and Utilities

Before the database can process requests, one or more sessions must be established on the database. If a large number of sessions need to be simultaneously connected by an application, the DBCISMAX setting should reflect this when the first session is connected. Doing so will improve performance by allowing CLIv2 to optimize its internal processing. To establish a session, an application must perform the following:

  1. Modify the DBCAREA.
    1. Set the Function to CONNECT.
    2. Optionally, set the following:

      Mechanism-name

      As required by that name, sets the following:

      - Mechanism-data-len

      - Mechanism-data-ptr

      - Mechanism-data-encoding

      - Delegate-user-identity

    3. If required, set the Logon-pointer.
    4. If required, set the Logon-length.
    5. Optionally set the following:

      Request-buffer-length

      Request-parcel-format

      Response-buffer-length

      Anticipated-number-of-concurrent-sessions

      Request-token

      Input TDPpath

      Run-pointer

      Run-length

      Message-area-pointer

      Message-area-length

      Session-desc-pointer

      Session-desc-length

      Workload-pointer

      Workload-length

      Any option values required

  2. Call DBCHCL to perform the Connect function.
  3. Check the return code from DBCHCL.
    • If the return code is anything but 0:

      Process the return code and DBCAREA message.

      Call DBCHCL to perform the Disconnect function (see Terminating a Session).

    • If the return code is 0, call DBCHCL to perform a Fetch function (see Fetching the Response for a Request) to get the final status of the connect request:
    Connect-type Return- code Result
    R 33 A session is established and the Teradata SQL processing can continue.
    0 Process the failure/error parcels.
    anything else An abnormal situation occurred. Use the Fetch function (Fetching the Response for a Request) to process.
    C 0

    Process parcels from the database.

    If a success parcel returns, then a session is established and Teradata SQL processing can continue.

    If anything else returns, process the failure/error parcel.

    anything else An abnormal situation occurred. Use the Fetch function (Fetching the Response for a Request) to process.
  4. Call DBCHCL to perform the End Request function (see Ending a Request).

If the Connect attempt is not successful at any point, the program can retry the Connect after calling DBCHCL for the End Request function.

If the application requires multiple active requests, multiple sessions can be established by following the aforementioned steps for each session desired.

In addition, the Output-CLIv2-connection-number field in the DBCAREA should be saved to request Teradata SQL processing for that session at a later time.