15.10 - Parameters of CLIv2 Routines: Tabular Summary - 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

Table 40 lists the parameters for the routines described in this chapter.

 

Table 40: Parameters of CLIv2 Routines 

Routines

Parameters

DBCHME

ReturnCode

ContextArea

MasterECB

Parameter Area

DBCHMEC

ReturnCode

ContextArea

MasterECB

DBCHPEC

ReturnCode

UserECB

DBCHSAD

ReturnCode

Target Address

Source Value

DBCHUE

ReturnCode

Context Area

UserECB

Parameter Area

DBCHUEC

ReturnCode

Context Area

UserECB

DBCHWAT

ReturnCode

ContextArea

ConnectionNumber

Request‑token

DBCHWL

ReturnCode

ContextArea

SessionList

ConnectionNumber

Request‑token

Purpose  

Called by the application to establish a master event in place of individual session events.

Interface

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

DBCHME(ReturnCode,ContextArea,MasterECB,FunctionCode)

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.

MasterECB

When defining a master event (DBCHMEP function code 1), the area allocated by the application for use as the master ECB.

When deleting a master event (DBCHMEP function code 2), this parameter must be present but is not used by DBCHME.

FunctionCode

The DBCHMEP area.

Usage Notes  

  • Set Wait For Response to N.
  • DBCHME may only be used when no sessions exist; that is, either before any session has been connected or after all sessions have been disconnected.
  • After the call, the return code variable contains a return code.
  • After the call, CLIv2 changes ContextArea for its own purposes.
  • For more information on ECBs, see IBM manuals.

    Master Event Parameters (MEP)

    The following table defines the DBCHMEP area. The field is set by the application.

    The field names in all languages are the same, except that the C field names are case-sensitive.

     

    Field Name

    Offset

    Length

    Description

    MEPFUNC
    (mepFunc)

    00

    4

    Unsigned numeric function to be performed.

    Valid function codes and their descriptions are listed in the table following this table.

    In the MEPFUNC field, the following are valid function codes:

     

    Function Code

    Name

    Mnemonic for All Languages, Including C

    Description

    1

    Define

    MEPFDEF

    Define a master event.

    2

    Delete

    MEPFDEL

    Delete a master event.

    Purpose  

    A deprecated routine now replaced by DBCHME.

    Interface

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

    DBCHMEC(ReturnCode,ContextArea,MasterECB)

    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.

    MasterECB

    The area allocated by the application for use as the master ECB.

    Purpose  

    Posts an ECB, including the one established by DBCHUE.

    Note: The alternate six-character name for DBCHPEC is DBCHPE.

    Interface

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

    DBCHPEC(ReturnCode,ECB)

    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.

    ECB

    The application allocated area for use as the ECB.

    Usage Notes  

  • After control returns from DBCHPEC, the variable contains a code whose value represents success or failure. 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 contains a return code.
  • For more information on ECBs, see IBM manuals.
  • Purpose  

    Stores the address of a variable at a specified location.

    Note: The alternate six-character name for DBCHSAD is DBCHSA.

    Interface

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

    DBCHSAD(ReturnCode,Target,Source)

    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.

    Target

    The area where the source address will be stored.

    Source

    Address to be stored.

    Usage Notes  

    DBCHSAD is intended for use in COBOL and other languages that do not support pointer manipulation.

    Purpose  

    Called by the application to add a user‑provided event to CLIv2’s internal wait list.

    Interface

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

    DBCHUE(ReturnCode,ContextArea,User event,DBCHUEP)

    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.

    UserECB

    When defining a user event (DBCHUEP function code 1), address of the application allocated area for use as the User ECB. When deleting a user event (DBCHUEP function code 2), this parameter must be present but is not used by DBCHUE.

    For CICS applications, the User ECB must be in SHARED storage.

    DBCHUEP

    User Event Parameters (UEP)

    Usage Notes  

  • The DBCHUE routine does not itself wait for completion of any event.
  • Only one User ECB is honored at a time; only the last one added has an effect.
  • For compatibility with the DBCHUEC service, the User ECB may be deleted by specifying a User ECB address of binary zeroes. The preferred method to delete a user event is to use a function code of 2.
  • The User ECB remains in effect until explicitly removed.
  • CLIv2 reflects the completion of the event associated with the User ECB by a return code of 160. Any time CLIv2 must wait for the completion of an event, the User ECB is checked. Before reflecting this return code to the application, the indicator that it has been posted in the User ECB is cleared.
  • After the call, the return code variable will contain a return code.
  • After the call, CLIv2 will change ContextArea for its own purposes.
  • User Event Parameters

    The following table defines the DBCHUEP area. The field is set by the application.

    The field names in all languages are the same, except that the C field names are case-sensitive.

     

    Field Name

    Offset

    Length

    Description

    UEPFUNC
    (uepFunc)

    00

    4

    Unsigned numeric function to be performed.

    Valid function codes and their descriptions are listed in the table following this table.

    In the UEPFUNC field, the following are valid function codes:

     

    Function Code

    Name

    Mnemonic for All Languages, Including C

    Description

    1

    Define

    UEPFDEF

    Define a user event.

    2

    Delete

    UEPFDEL

    Delete a user event.

    Purpose  

    A deprecated routine now replaced by DBCHUE.

    Interface

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

    DBCHUEC(ReturnCode,ContextArea,UserECB)

    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.

    UserECB

    The application allocated area for use as the User ECB.

    For CICS applications, the User ECB must be in SHARED storage.

    Usage Notes  

  • The DBCHUEC routine does not itself wait for completion of any event.
  • The user ECB may be cancelled by specifying a User ECB address of binary zeroes.
  • Purpose  

    Waits for an event, such as the arrival of a response from the Teradata Database or some other occurrence defined by the application.

    Note: The alternate six-character name for DBCHWAT is DBCHWT.

    Interface

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

    DBCHWAT(ReturnCode,ContextArea,ConnectionNumber,Request‑token)

    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.

    ConnectionNumber

    An area to receive a four-byte unsigned integer representing the logical session id of the first active request to complete.

    Request‑token

    An area to receive a four-byte unsigned integer user‑supplied token associated with the first active request to complete.

    Usage Notes  

  • Each call to DBCHWAT reflects completion of one event. If multiple events have completed, none are lost. Rather, their completions are reflected on subsequent calls to DBCHWAT. Each completed event is reflected only once.
  • For example, if two events complete, the first call to DBCHWAT reflects one event, the second call reflects the second event, and the third call waits for completion of another event, if any responses are pending. When multiple responses have arrived, they are reflected to the application in the order in which their requests were initiated, not the order in which they arrived. This ensures that repeated use of a request that completes quickly does not prevent reflection of longer-running responses.

  • If DBCHUE has been used to provide a User‑event, its completion is reflected before the arrival of any response.
  • DBCHWAT is normally used when an application has multiple sessions, allowing the application to be notified immediately of the first completion.
  • If there are no responses whose arrival is pending, a return code 123 results. If DBCHUE has been used to provide a User‑event, it is ignored. That is, when there are no pending responses, the User‑event is neither checked for completion nor does suspension occur for the event's completion. A User‑event is honored only when a request has been issued but not yet completed.
  • When the DBCHME service has been used to include Teradata requests in another event, DBCHWAT never waits. If no events have completed, a return code 162 is reflected, allowing the application to wait for the master event using an operating system service.
  • After the call, the return code variable contains a return code.
  • After the call, CLIv2 changes ContextArea for its own purposes.
  • Requests for sessions that specify the Wait‑exclusion option are ignored by DBCHWAT.
  • Purpose  

    Waits for one of a list of events, such as the completion of a response from the Teradata Database or some user event defined by the application.

    Interface

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

    DBCHWL(ReturnCode,ContextArea,SessionList,ConnectionNumber,
    	 	 Request‑token)

    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.

    SessionList

    a list of contiguous 12 byte entries, each consisting of three unsigned integer fields. The first contains the connection number of a session; the other two are unused and should be initialized to zero; the last entry in the list must contain a connection number of binary zeroes.

    ConnectionNumber

    A 4 byte unsigned integer field into which the connection number associated with a completed request will be placed by CLIv2 if a request completes; if a user event completes binary zeroes will be returned.

    Request‑token

    A 4 byte unsigned integer field into which the DBCAREA Request‑token when the request was initiated will be placed by CLIv2 if a request completes; if a user event completes binary zeroes will be returned.

    Usage Notes  

  • Each call to DBCHWL reflects completion of one event. If multiple events have completed, none are lost. Rather, their completions are reflected on subsequent calls to DBCHWL. Each completed event is reflected only once. For example, if two events complete, the first call to DBCHWL reflects one event, the second call reflects the second event, and the third call waits for completion of another event, if any responses are pending.
  • When multiple responses have completed, they are reflected to the application in the order in which their requests were initiated, not the order in which they completed. This ensures that repeated use of a request that completes quickly does not prevent reflection of longer-running responses.
  • The session list may contain any valid connection number, whether or not a response is pending for that session. Each time DBCHWL is called, any connection number for which no response is pending is ignored.
  • If DBCHUEC has been used to provide a user event, its completion is reflected before the completion of any response.
  • If there are no responses whose completion is pending, a return code 123 results. If DBCHUEC has been used to provide a user event, it is ignored. That is, when there are no pending responses, the user event is neither checked for completion nor does suspension occur for the event's completion. A user event is honored only when a request has been issued but not yet completed.
  • When the DBCHME service has been used to include Teradata requests in another event, DBCHWL never waits. If no events have completed, a return code 162 is reflected, allowing the application to wait for the master event using an operating system service.
  • After the call, the return code field contains a return code.
  • After the call, CLIv2 may have changed the ContextArea field for its own purposes.