15.10 - Summary of CLIv2 Routine Parameters - Call-Level Interface Version 2

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

prodname
Call-Level Interface Version 2
vrm_release
15.10
category
Programming Reference
featnum
B035-2417-035K

The following table lists the parameters for the routines in this chapter

 

Table 11: Parameters of CLIv2 Routines

Routine

Parameters

DBCHINI

ReturnCode Address

ContextArea Address

DBCAREA Address

DBCHCL

ReturnCode Address

ContextArea Address

DBCAREA Address

DBCHCLN

ReturnCode Address

ContextArea Address

Purpose  

Sets up the CLIv2 environment.

The application must provide the DBCAREA and then call DBCHINI to initialize it.

Note: The alternate six-character name for DBCHINI is DBCHIN.

Interface

This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

DBCHINI(ReturnCode,ContextArea,DBCAREA)

In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

The parameters for this routine are:

 

Argument

Content

ReturnCode

A 4 byte unsigned integer field into which the return code will be placed by CLIv2.

ContextArea

A 4 byte unsigned integer field for internal use by CLIv2.

DBCAREA

The DBCAREA structure.

Usage Notes  

  • The application must declare or allocate the DBCAREA and call DBCHINI to initialize the fields prior to using CLIv2 functions.
  • Total Length must be filled in by the application before calling DBCHINI. DBCHINI verifies this value prior to any initialization attempt. The length must be at least 384, the size of the smallest DBCAREA. If the length is at least 640, the Level 1 enlarged DBCAREA will be formatted. If the length is at least 1024, the Level 2 enlarged DBCAREA will be formatted. For lengths greater than 384 but less than 640, greater than 640 but less than 1024, or greater than 1024, the excess is assumed to be an application appendage to the DBCAREA: it will be zeroed by DBCHINI but is otherwise unused by CLIv2. When not appending fields to the DBCAREA, mnemonics should be used to set the Total‑length field to the largest DBCAREA. When appending fields to the DBCAREA, depending on the application development environment it may be better to use hard-coded values rather than mnemonics. For example, if the total size of the DBCAREA plus application fields must be less than some size, it might be unwise to allow the DBCAREA size to increase.
  • DBCHINI obtains default values from the HSHSPB currently available to the application.
  • The return code will either be 0 (if the initialization is completed successfully) or 126 if the Total Length value is insufficient for the smallest DBCAREA (384 bytes). After the call, the return code variable contains a return code.
  • After the call, CLIv2 changes ContextArea for its own purposes.
  • DBCHINI initializes the DBCAREA allocated by the application with the length specified in DBCSIZE. DBCHINI does not initialize any DBCAREA extensions addressed by the DBCAXP DBCAREA field.
  • Purpose  

    Calls the functions to be used by the application.

    An overview of the functions relative to DBCHCL is given in the first table in the section “Summary of CLIv2 Routine Parameters” on page 241. Each function is described in detail later in this chapter.

    Process

    Before each call to DBCHCL, the application modifies the DBCAREA to specify the action requested and to fill in the input fields relevant to that action. DBCHCL carries out the function specified by the function code in the DBCAREA, then passes back to the caller the DBCAREA, which contains, among other things, a return code. The application checks the return code in the DBCAREA, which is where CLIv2 and TDP indicate any problem they find.

    If the call results in a delivery of parcels to the response buffer, the program checks the first parcel, which may be one of the following:

  • Success
  • Error
  • StatementError
  • Failure
  • Interface

    This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

    DBCHCL(ReturnCode,ContextArea,DBCAREA)

    In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

    The parameters for this routine are:

     

    Argument

    Content

    ReturnCode

    A 4 byte unsigned integer field into which the return code will be placed by CLIv2.

    ContextArea

    A 4 byte unsigned integer field for internal use by CLIv2.

    DBCAREA

    The DBCAREA structure.

    Usage Notes  

  • Before DBCHCL is called, the application must have called DBCHINI to initialize the DBCAREA to be used by DBCHCL.
  • After the call, CLIv2 will change ContextArea for its own purposes.
  • The DBCAREA address must always be passed to DBCHCL.
  • In addition, the function code must be supplied.
  • Other fields in the DBCAREA must be set as appropriate to the function requested.
  • If Wait for Response is set to N (set and used by the Connect, Initiate Request, Command, Initiate with Protocol, and RunStartUp functions; used by the Fetch, Abort, Rewind, End Request, and Disconnect functions) and CLIv2 is waiting for a response from the Teradata Database, the application will receive a return code of 150 (busy).
  • The application may handle the busy response by calling routine DBCHWAT and waiting for control to return to the application.
  • If the return code is 0, resubmit the DBCHCL function that initially returned the busy indication.
  • If Return Code is nonzero for any function, the Message Length and Message Text fields of the DBCAREA will be set.
  • This section describes the DBCHCL functions listed below.

     

    Function Name

    Description

    CON

    Connect

    RSUP

    RunStartUp Request

    IRQ

    Initiate Request

    IWPF

    Initiate With Protocol‑Function

    CRQ

    Continue Request

    CMD

    Command

    ABT

    Abort

    FET

    Fetch

    REW

    Rewind and Fetch

    ERQ

    End Request

    DSC

    Disconnect

    General Notes

    For each function, there is a list of the required and optional input and output arguments and a general description of how DBCHCL processes the function.

    The interpretation of some of the arguments may depend on the setting of the DBCAREA options (for more information, see “Setting DBCAREA Options” on page 46.

    For instance, input/output string pointers may be variable strings. For output strings, DBCHCL will provide an address and length if Locate mode is in effect; otherwise, DBCHCL expects that the application has set the address of the area to which DBCHCL is to move the string.

    If DBCHCL detects an error while processing, various fields will be set to help the user interpret and handle the error.

    Purpose  

    CON (Connect) logs on to the Teradata Database and arranges to have the specified services available for all requests on that session.

    Connect also allocates internal control structures that CLIv2 uses to store session context.

    Usage Notes  

  • If no Logon String is supplied or logon mechanism, a TDP logon exit must furnish the necessary information to complete the logon request. If a TDP logon exit does not exist or is disabled, the connect will be rejected by TDP.
  • The application should call the ERQ function after processing the CON function, regardless of the success or failure of the connect. This releases internal resources used during connect processing.
  • DSC must be performed for each CON request. If the CON results in a nonzero return code, DSC should be called immediately. Otherwise, DSC should be called when the application has completed all work for the session.
  • If Return Code is 0, the application must invoke the FET function to obtain the final status of the connect call.
  • If Connect Type was R, the FET call results in a Return Code of 33 if the connect was successful.
  • If Connect Type was C, the parcels must be processed to determine success or failure of the connect.
  • The FET returns three additional DBCAREA fields set only when CON is being processed. These fields are:
  • Output TDP Path
  • Output TDP Session Id
  • Output Host Id.
  • Additional fields will be set as normal by the FET call.
  • For a discussion of the call and the fields used, see “DBCHCL FET Function” on page 265.

    DBCAREA Input Fields

    Before using the Connect function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 12: DBCAREA Input Fields Optional for the Connect Function 

    DBCAREA Input Fields Optional for the Connect Function

    2PC

    Anticipated Number of Concurrent Sessions

    Automatic‑redrive

    Change Options

    Character Set Pointer

    Connect Type

    Country Id

    C2S Conversion

    Data‑encryption

    Date Form

    Delegate‑user‑identity

    Extended‑load

    Input TDP Path

    Keep Response

    Language Conformance

    Language Id

    Locate Mode

    Logon Length

    Logon Pointer

    Maximum Parcel

    Mechanism‑data‑encoding

    Mechanism‑data‑len

    Mechanism‑data‑ptr

    Mechanism‑name

    Message Area Pointer

    Message Area Length

    Parcel Mode

    Request Buffer Length

    Request Mode

    Request‑parcel‑format

    Request Processing Option

    Request‑token

    Response Buffer Length

    Response Mode

    Return Time

    Run Length

    Run Pointer

    Save Response Buffer

    Session‑desc‑length

    Session‑desc‑pointer

    Set Character Set

    Statement‑status

    S2C Conversion

    Tell‑if‑delay

    Transaction Semantics

    Two Response Buffers

    Use‑default‑conn

    Use Presence Bits

    Utility‑workload

    Variable Length Fetch

    Variable Length Request

    Wait‑during‑delay

    Wait‑exclusion

    Wait For Response

    Workload‑length

    Workload‑pointer

    DBCAREA Output Fields

    Upon completion of the Connect function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 13: DBCAREA Output Fields Always Set for the Connect Functions 

    DBCAREA Output Fields Always Set for the Connect Functions

    Message Return Code

    Message Length

    Message Text

    Message Text Length

    Current Response Buffer Length

    Output CLIv2 Request Id

    Output CLIv2 Connection Id

    Return Code

     

    Table 14: DBCAREA Output Fields Set by Successful Connect Functions 

    DBCAREA Output Fields Set by Successful Connect Functions

    Current Request Buffer Length

    Mechanism‑name

    Open Requests

    Session Status

    TDP Request Number

     

    Purpose  

    RSUP (RunStartUp) sends a request to the Teradata Database to execute the startup request stored on the Teradata Database.

    Usage Notes

  • The application should call the ERQ function after processing RunStartUp, regardless of the success or failure of the startup. This will release internal resources used during startup processing.
  • If RunStartUp is called without first calling Connect, RunStartUp will perform the Connect. In this case, the information needed for a Connect call should be supplied when doing the RunStartUp call.
  • If Return Code is 0, the application must invoke the FET function to process the response.
  • DBCAREA Input Fields

    Before using the Run Start‑up function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 15: DBCAREA Input Fields Required for the RunStartup Function 

    DBCAREA Input Fields Required for the RunStartup Function

    Function

    Input CLIv2 Connection Id

     

    Table 16: DBCAREA Output Fields Optional for the RunStartup Function 

    DBCAREA Output Fields Optional for the RunStartup Function

    Anticipated Number of Concurrent Sessions

    APH‑response‑OK

    Array‑Transforms‑Off

    Change Options

    Column‑info

    C2S Conversion

    Continued‑character‑state

    Data‑encryption

    Inhibit-buffer-expansion

    Input TDP Path

    Keep Response

    Locate Mode

    Logon Length

    Logon Pointer

    Max‑decimal‑returned

    Maximum Parcel

    Multi‑statement‑errors

    Parcel Mode

    Period‑as‑Struct

    Refresh‑cached‑data

    Request Buffer Length

    Request‑parcel‑format

    Request Processing Option

    Request‑token

    Response Buffer Length

    Response Mode

    Return Time

    Return‑identity‑data

    Result‑sets‑OK

    Return‑result‑to

    Return‑statement‑info

    Row‑count

    Run Length

    Run Pointer

    Save Response Buffer

    S2C Conversion

    Tell‑if‑delay

    Transforms‑off

    Trusted‑request

    Two Response Buffers

    Use Presence Bits

    Variable Length Request

    Variable Length Fetch

    Wait‑during‑delay

    Wait‑exclusion

    Wait For Response

    XML‑response‑format

     

    DBCAREA Output Fields

    Upon completion of the Run Start‑up function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 17: DBCAREA Output Fields Always Set by the RunStartup Function 

    DBCAREA Output Fields Always Set by the RunStartup Function

    Current Response Buffer Length

    Message Return Code

    Message Text

    Message Text Length

    Output CLIv2 Request Id

    Return Code

     

    Table 18: DBCAREA Output Fields Set by Successful RunStartup Functions 

    DBCAREA Output Fields Set by Successful RunStartup Functions

    Current Request Buffer Length

    Message Return Code

    Message Text

    Message Text Length

    Open Requests

    TDP Request Number

    Purpose  

    IRQ (Initiate Request) sends a request to the Teradata Database to be processed.

    Usage Notes

  • If Initiate Request is called without first calling CON, Initiate Request performs the CON. In this case, the information needed for a CON call should be supplied when doing the Initiate Request call.
  • If Return Code is 0, the application must invoke the FET function to process the response. After the response has been totally processed, the application must invoke the ERQ function to release resources used by the Initiate Request.
  • When initiating a request in a 2PC session, Initiate Request will be rejected if the session has a 2PC vote or terminate activity in progress.
  • After they are started, activities such as vote and terminate must be completed by the coordinator.
  • The vote can result from a previous Initiate with Protocol‑Function (IWPF) function.
  • The terminate could have resulted from an Abort or Logoff or from any response that contained a Failure parcel.
  • If any of these occur, the coordinator must be requested to perform a syncpoint.
  • DBCAREA Input Fields

    Before using the Initiate Request function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 19: DBCAREA Input Fields Required for the Initiate Request Function 

    DBCAREA Input Fields Required for the Initiate Request Function

    Function

    Input CLIv2 Connection Id

    Request Length

    Request Pointer

     

    Table 20: DBCAREA Input Fields Optional for the Initiate Request Function 

    DBCAREA Input Fields Optional for the Initiate Request Function

    Anticipated Number of Concurrent Sessions

    APH‑response‑OK

    Array‑Transforms‑Off

    Change Options

    Character Set

    C2S Conversion

    Column‑info

    Continued‑character‑state

    Data‑encryption

    Extension Pointer

    Inhibit-buffer-expansion

    Input TDP Path

    Keep Response

    Locate Mode

    Logon Length

    Logon Pointer

    Max‑decimal‑returned

    Maximum Parcel

    Message Area Length

    Message Area Pointer

    Multi‑statement‑errors

    Parcel Mode

    Period‑as‑Struct

    Pointer

    Refresh‑cached‑data

    Request Buffer Length

    Request Mode

    Request‑parcel‑format

    Request Processing Option

    Request‑token

    Response Buffer Length

    Response Mode

    Result‑sets‑OK

    Return‑identity‑data

    Return‑result‑to

    Return‑statement‑info

    Return Time

    Row‑count

    Run Length

    Run Pointer

    Save Response Buffer

    Session Id

    Set Character Set

    Statement‑status

    S2C Conversion

    Tell‑if‑delay

    Transforms‑off

    Trusted‑request

    Two Response Buffers

    Using Data Pointer

    Using Data Length

    Use Presence Bits

    Variable Length Fetch

    Variable Length Request

    Wait‑during‑delay

    Wait‑exclusion

    Wait For Response

    XML‑response‑format

    DBCAREA Output Fields

    Upon completion of the Initiate Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    DBCAREA Output Fields always set by the Initiate Request Function

    Current Response Buffer Length

    Message Return Code

    Message Text

    Message Text Length

    Output CLIv2 Request Id

    Return Code

     

    DBCAREA Output Fields set by Successful Initiate Request Functions

    Current Request Buffer Length

    Open Requests

    TDP Request Number

     

    Purpose  

    IWPF (Initiate with Protocol‑Function) enables an application to send a request to the Teradata Database.

    It contains additional protocol functions for 2PC sessions, for use in specialized applications.

    Note: This function can not be used when ANSI transaction semantics are enabled.

    Usage Notes  

  • A 2PC request can be initiated using the Initiate with Protocol‑Function.
  • The IWPF function is similar to the Initiate Request (Initiate Request) function, except for the following differences:
  • IWPF does not support the Locate mode.
  • When IWPF is used with 2PC sessions, the additional protocol functions of vote, and vote and terminate can be used to optimize syncpoint processing in specialized applications.
  • In IWPF, you can set the following:
  •  

    Code

    Meaning

    N

    No protocol function.

    This is the default.

    V

    Vote protocol function to be appended.

    T

    Vote & Terminate protocol function to be appended.

    DBCAREA Input Fields

    Before using the Initiate With Protocol‑function function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 21: DBCAREA Input Fields Required for Initiate With Protocol‑function 

    DBCAREA Input Fields Required for the Initiate With Protocol‑function Function

    Function

    Input CLIv2 Connection Id

    Request Length

    Request Pointer

     

    Table 22: DBCAREA Input Fields Optional for Initiate With Protocol‑function 

    DBCAREA Input Fields Optional for the Initiate With Protocol‑function Function

    Anticipated Number of Concurrent Sessions

    APH‑response‑OK

    Array‑Transforms‑Off

    Change Options

    Character Set

    C2S Conversion

    Column‑info

    Continued‑character‑state

    Extension Pointer

    Inhibit-buffer-expansion

    Input TDP Path

    Keep Response

    Length

    Logon Length

    Logon Pointer

    Max‑decimal‑returned

    Maximum Parcel

    Message Area Length

    Message Area Pointer

    Multi‑statement‑errors

    Parcel Mode

    Period‑as‑Struct

    Pointer

    Protocol Function

    Refresh‑cached‑data

    Request Buffer Length

    Request Mode

    Request‑parcel‑format

    Request Processing Option

    Request‑token

    Response Buffer

    Response Mode

    Result‑sets‑OK

    Return‑identity‑data

    Return‑result‑to

    Return‑statement‑info

    Return Time

    Row‑count

    Run Length

    Run Pointer

    Save Response Buffer

    Session Id

    Set Character Set

    Statement‑status

    S2C Conversion

    Tell‑if‑delay

    Transforms‑off

    Trusted‑request

    Two Response Buffers

    Using Data Length

    Using Data Pointer

    Use Presence Bits

    Variable Length Fetch

    Variable Length Request

    Wait‑during‑delay

    Wait‑exclusion

    Wait For Response

    XML‑response‑format

    DBCAREA Output Fields

    Upon completion of the Initiate With Protocol‑function function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 23: DBCAREA Output Fields always set by Initiate With Protocol‑function 

    DBCAREA Output Fields always set by the Initiate With Protocol‑function Function

    Message Return Code

    Current Response Buffer Length

    Message Length

    Message Text

    Message Text Length

    Output CLIv2 Request Id

    Return Code

     

     

    Table 24: DBCAREA Output Fields Set by Successful Initiate With Protocol‑function 

    DBCAREA Output Fields set by Successful Initiate With Protocol‑function Functions

    Current Request Buffer Length

    Open Requests

    TDP Request Number

     

    Purpose  

    CRQ (Continue Request) sends data requested by the Teradata Database to complete an SQL request. The need for such completion must be indicated by one of the following SQL requests:

  • A USING row descriptor that specifies CLOB or BLOB AS DEFERRED. The result is one of the following:
  • An ElicitData parcel in the response that contains the token specified as the Using‑data for the AS DEFERRED field.
  • An ElicitDataByName parcel in the response which contains the name specified in the BY NAME phrase.
  • A CREATE or REPLACE for an executable item, such as FUNCTION, that specifies the EXTERNAL NAME clause. The result is an ElicitFile parcel that contains the filename specified by the EXTERNAL clause.
  • When either parcel is received, the application then sends data to complete the SQL request using the ContinueRequest function.

    Usage Notes  

    The application should call the CRQ function after processing an ElicitData or ElicitFile response parcel. If return Code is zero, the application must invoke the FET function to process the response. If more data exists, these steps are repeated as many times as necessary.

    DBCAREA Input Fields

    Before using the Continue Request function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 25: DBCAREA Input Fields Required for the Continue Request Function 

    DBCAREA Input Fields Required for the Continue Request Function

    Continued‑data

    Function

    Input CLIv2 Connection Id

    Input CLIv2 Request Id

    Request Length

    Request Pointer

    When processing an ElicitData parcel, the Request‑pointer addresses data for the Large Object (LOB). The LOB begins with an 8‑byte unsigned integer that contains the length, in bytes, of the data. If the length is not known when the start of the LOB is sent, the length field might be zero.

    When processing an executable item, the Request‑pointer addresses its statements, which do not begin with a length field.

     

    Table 26: DBCAREA Input Fields Optional for the Continue Request Function 

    DBCAREA Input Fields Optional for the Continue Request Function

    Change Options

    C2S Conversion

    Fetch Buffer Length

    Locate Mode

    Maximum Parcel

    Message Area Length

    Message Area Pointer

     

    DBCAREA Output Fields

    Upon completion of the Continue Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 27: DBCAREA Output Fields always set by the Continue Request Function 

    DBCAREA Output Fields always set by the Continue Request Function

    Message Length

    Message Return Code

    Message Return Code

    Message Text

    Message Text Length

    Message Return Code

    Return Code

     

     

    Table 28: DBCAREA Output Fields set by Successful Continue Request Functions 

    DBCAREA Output Fields set by Successful Continue Request Functions

    Current Request Buffer Length

    Current Response Buffer Length

    Purpose  

    CMD (Command) issues a TDP command within a CLIv2 program.

    This function is used to send the TDP command, specifying a buffer and length that contain the command text.

    Usage Notes

  • Use the CMD function to send a TDP command, specifying a buffer and length for the command text.
  • If the Return Code is 0, a pseudo‑connection number and a request number are returned.
  • To process the response, issue a FETch function with the returned pseudo‑connection number and request number.

    The response data is composed of various parcels in the following order:

    1 A Success parcel with an activity count that indicates the number of subsequent Record parcels

    2 The Record parcels themselves (one Record parcel for each line of command output)

    3 An End Statement parcel

    4 An End Request parcel

  • After the response has been completely processed, the application must invoke the ERQ function to release the fetch buffer used by the CMD.
  • Since the application doesn‘t establish a connection, no DISCONN function may be used for the pseudo‑connection number. Rewind and Abort functions are not supported.

    If the specified response buffer is too small for the entire response, a code of 535 is returned, either as a warning code in the Success parcel or as a return code from the CLIv2 call.

    DBCAREA Input Fields

    Before using the Command function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 29: DBCAREA Input Fields Required for the Command Function 

    DBCAREA Input Fields Required for the Command Function

    Function

     

     

    Table 30: DBCAREA Input Fields Optional for the Command Function 

    DBCAREA Input Fields Optional for the Command Function

    Anticipated Number of Concurrent Sessions

    Change Options

    Character Set

    Inhibit-buffer-expansion

     

    Input TDP Path

    Length

    Locate Mode

    Maximum Parcel

    Message Area Length

    Message Area Pointer

    Parcel Mode

    Pointer

    Request Buffer

    Request Length

    Request Mode

    Request Pointer

    Request Processing Option

    Response Buffer Length

    Response Mode

    Return Time

    Set Character Set

    Tell‑if‑delay

    Request‑token

    Two Response Buffers

    Use Presence Bits

    Variable Length Fetch

    Variable Length Request

    Wait‑during‑delay

    Wait‑exclusion

    Wait For Response

     

    DBCAREA Output Fields

    Upon completion of the Command function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 31: DBCAREA Output Fields always set by the Command Function 

    DBCAREA Output Fields always set by the Command Function

    Current Response Buffer Length

    Message Length

    Message Return Code

    Message Text

    Message Text Length

    Output CLIv2 Request Id

    Output CLIv2 Connection Id

    Return Code

     

    Table 32: DBCAREA Output Fields set by Successful Command Functions 

    DBCAREA Output Fields set by Successful Command Functions

    Current Request Buffer Length

    Open Requests

    TDP Request Number

     

    Purpose  

    ABT (Abort) attempts to abort a request and the transaction in which it is embedded. This is known as an asynchronous abort.

    Abort may be used within an External Stored Procedure to indicate that the results of a request initiated with the DBCAREA Return‑result‑to option will not be reflected to the CALLer or the application.

    Usage Notes  

  • If the Return Code is 0, the abort has been sent to the Teradata Database. However, 0 does not mean the request has been aborted. The application must perform FET to check the final disposition of the original request and ERQ to release the request context.
  • If the abort reaches the Teradata Database before it completes the request, the request will be aborted and the containing transaction rolled back. Storage associated with the request is kept until ERQ is issued for the request.
  • If the abort reaches the Teradata Database after the request has completed, the abort is ignored.
  • If the application has an active transaction and is between requests, issue Initiate Request with a ROLLBACK statement rather than calling ABT to perform the abort.
  • If the session is running in 2PC mode, ABT ensures that the current session is aborted at syncpoint. This occurs even if the abort had no effect (for example, if the request completed before ABT could abort it).
  • DBCAREA Input Fields

    Before using the Abort function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    DBCAREA Input Fields Required for the Abort Function

    Function

    Input CLIv2 Request Id

    Input CLIv2 Connection Id

     

     

    DBCAREA Input Fields Optional for the Abort Function

    Message Area Length

    Message Area Pointer

    DBCAREA Output Fields

    Upon completion of the Abort function, CLIv2 will always set DBCAREA fields in the table.

     

    DBCAREA Output Fields always set by the Abort Function

    Message Return Code

    Message Length

    Message Text

    Message Text Length

    Return Code

     

    Purpose  

    FET (Fetch) delivers a pointer to the next parcel of the response.

    Usage Notes  

  • If Return Code is 0, the application may process the response from the Teradata Database. FET may be invoked repeatedly until the entire response has been processed.
  • For 2PC sessions, Fetch ensures that the current session is aborted at syncpoint if a failure parcel is received in response to a request.
  • In addition, the first FET after a CON call will return the following fields:
  • Output TDP Path
  • Output TDP Session Id
  • Output Host Id
  • DBCAREA Input Fields

    Before using the Fetch function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    DBCAREA Input Fields Required for the Fetch Function

    Function

    Input CLIv2 Connection Id

    Input CLIv2 Request Id

     

     

    DBCAREA Input Fields Optional for the Fetch Function

    Fetch Data Pointer

    Fetch Maximum Data Length

    Message Area Length

    Message Area Pointer

    Positioning‑action

    Positioning‑statement‑number

    Positioning‑value

    Row‑count

    DBCAREA Output Fields

    Upon completion of the Fetch function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 33: DBCAREA Output Fields always set by the Fetch Function 

    DBCAREA Output Fields always set by the Fetch Function

    Current Response

    Return Code

    Session Status

    Message Length

    Message Return Code

    Message Text

     

    Table 34: DBCAREA Output Fields set by Successful Fetch Functions 

    DBCAREA Output Fields set by Successful Fetch Functions

    Buffer Length

    Data Length

    Fetch Data Pointer

    Fetch Parcel Flavor

    Fetch Returned

    Message Text Length

    Output TDP

    Output Host Id

    TDP‑receipt‑timestamp

    Time1

    Time1‑status

    Time2

    Time2‑status

    Time3

    Time3‑status

    Time4

    Time4‑status

    Time5

    Time5‑status

     

    Purpose  

    ERQ (End Request) explicitly closes a request, discard its response, and deallocated internal data structures related to the request.

    Usage Notes  

  • If Return Code is 0, the ERQ has successfully completed.
  • CLIv2 will keep the response buffer if Save Response Buffer was Y when the request was submitted. This permits CLIv2 to reuse the response buffer for the next Initiate Request without allocating a new one.
  • DBCAREA Input Fields

    Before using the End Request function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    Table 35: DBCAREA Input Fields Required for the EndRequest Function 

    DBCAREA Input Fields Required for the EndRequest Function

    Function

    Input CLIv2 Request Id

    Input CLIv2 Connection Id

     

     

    Table 36: DBCAREA Input Fields Optional for the EndRequest Functions 

    DBCAREA Input Fields Optional for the EndRequest Functions

    Message Area Length

    Message Area Pointer

    DBCAREA Output Fields

    Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    Table 37: DBCAREA Output Fields Always Set for the EndRequest Function 

    DBCAREA Output Fields Always Set for the EndRequest Function

    Message Text

    Message Length

    Message Text Length

    Return Code

     

    Table 38: DBCAREA Output Fields Set by Successful EndRequest Functions 

    DBCAREA Output Fields Set by Successful EndRequest Functions

    Open Requests

    Message Return Code

    Purpose  

    REW (Rewind) repositions to the beginning of the response from the Teradata Database.

    Keep Response must have been set to Y at the time of the Initiate Request for the request. Since Keep‑response does not apply to Connect requests, the response to a Connect cannot be rewound.

    Usage Notes  

    If Return Code is 0, the application may use FET to process the response.

    DBCAREA Input Fields

    Before using the Rewind function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    DBCAREA Input Fields Required for the Rewind Function

    Function

    Input CLIv2 Request Id

    Input CLIv2 Connection Id

     

     

    DBCAREA Input Fields Optional for the Rewind Function

    Message Area Length

    Message Area Pointer

    DBCAREA Output Fields

    Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the first table and will set those in the second table if the function was successful.

     

    DBCAREA Output Fields always set by the Rewind Function

    Message Return Code

    Message Text

    Message Length

    Message Text Length

    Return Code

     

    Purpose  

    DSC (Disconnect) logs a session off the Teradata Database.

    Usage Notes  

  • Check the Return Code; if zero, the disconnect was successfully completed.
  • If the session has a pending request, a return code of 336 (request may be aborted) is returned to the application. The session is still logged off but the response is lost.
  • If there is an active transaction at the time of the DSC, the Teradata Database rolls back all work performed within that transaction prior to completing the logoff.
  • DSC should be used to clean up session context even if the connect was not successful (initial or final status).
  • In 2PC mode, Disconnect ensures that the current session is aborted at syncpoint if the session has performed any uncommitted Teradata SQL requests.
  • DBCAREA Input Fields

    Before using the Disconnect function, the application must set the DBCAREA fields in the first table and may optionally set those in the second table depending on the application's requirements.

     

    DBCAREA Input Fields Required for the Disconnect Function

    Function

    Input CLIv2 Connection Id

     

    DBCAREA Input Fields Optional for the Disconnect Function

    Message Area Length

    Message Area Pointer

    DBCAREA Output Fields

    Upon completion of the End Request function, CLIv2 will always set DBCAREA fields in the table.

     

    DBCAREA Output Fields always set by the Disconnect Function

    Message Return Code

    Message Length

    Message Text

    Message Text Length

    Purpose  

    Logs off all sessions and free all internal memory and context information allocated by CLIv2.

    Note: The alternate six-character name for DBCHCLN is DBCHCN.

    Interface

    This routine is called with the following parameters, stylistically presented (the actual syntax varies according to the programming language being used):

    DBCHCLN(ReturnCode,ContextArea)

    In high-level languages, the details of the parameter list are handled by the compiler. For Assembler, the parameter list consists of contiguous 4 byte entries, each containing the 31 bit address of a parameter. The last address has the first bit set to one to indicate the end of the list.

    The parameters for this routine are:

     

    Argument

    Content

    ReturnCode

    A 4 byte unsigned integer field into which the return code will be placed by CLIv2.

    ContextArea

    A 4 byte unsigned integer field for internal use by CLIv2.

    Usage Notes  

  • The application invokes the DBCHCLN routine when all processing requiring interfacing with the Teradata Database is complete.
  • DBCHCLN does the following:
  • logs off any idle sessions
  • awaits completion of any active sessions and then logs them off
  • frees all internal memory and context information allocated by CLIv2.
  • DBCHCLN deallocates internal data structures that were allocated by DBCHINI.
  • DBCHCLN returns control to the application after all sessions have been logged off and all internal context has been cleaned up.
  • After control returns from DBCHCLN, the variable contains a code whose value represents success or failure to clean up.
  • A return code of zero indicates success.

    A nonzero return code indicates failure, and the value specifies the reason for the failure.

    After the call, the return code variable will contain a return code.

  • After the call, CLIv2 changes ContextArea for its own purposes.
  • The call to DBCHCLN does not deallocate the DBCAREA.
  • The application may itself deallocate the DBCAREA if the programming language provides that ability.

  • Termination of the application has the same effect as DBCHCLN, but it is good programming practice to call DBCHCLN for cleanup.