Table 40 lists the parameters for the routines described in this chapter.
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
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 |
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
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
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 |
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
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
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.
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. |