Purpose
Waits for one of a list of events, such as the completion of a response from the 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 | Four-byte unsigned integer field into which the return code is placed by CLIv2. |
| ContextArea | Four-byte unsigned integer field for internal use by CLIv2. |
| SessionList | 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 | Four-byte unsigned integer field into which the connection number associated with a completed request is placed by CLIv2 if a request completes; if a user event completes binary zeroes will be returned. |
| Request-token | Four-byte unsigned integer field into which the DBCAREA Request-token when the request was initiated is 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 database 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.