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. |
The UEPFUNC Field
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. |