The WAIT_MVS call
WAIT_MVS requests a wait on an MVS™ event control block (ECB) or on a list of MVS ECBs. For example, you could issue the WAIT_MVS to wait for completion of an MVS task for which you have issued ATTACH and provided a task-completion ECB.
The dispatcher does not clear the ECBs when a WAIT_MVS request is received. If any ECB is already posted, control is returned immediately to the exit program with a response of ‘OK'.
A single ECB must not be the subject of more than one wait at a time. If any ECB is already being waited on when a WAIT_MVS request is received, the request is rejected. The RESPONSE code is ‘DSSR_INVALID', and the REASON code ‘DSSR_ALREADY_WAITING'.
WAIT_MVS
DFHDSSRX [CALL,]
[CLEAR,]
[IN,
FUNCTION(WAIT_MVS),
{ECB_ADDRESS(name4 | (Ra)) | ECB_LIST_ADDRESS(name4 | (Ra)),}
PURGEABLE(YES|NO),
[INTERVAL(name4 | (Rn)),]
[RESOURCE_NAME(name16 | string | 'string'),]
[RESOURCE_TYPE(name8 | string | 'string'),]]
[TIME_UNIT(SECOND|MILLI_SECOND),]
[WLM_WAIT_TYPE,]
[OUT,
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- ECB_ADDRESS(name4 | (Ra))
- Specifies the address of the ECB to be waited on.
- name4
- The name of a location that contains an ECB address.
- (Ra)
- A register that contains the address of an ECB.
- ECB_LIST_ADDRESS(name4 | (Ra))
- Specifies the address of a list of ECB addresses to be waited
on.
- name4
- The name of a location that contains an ECB address, possibly followed by more ECB addresses. The last address word in the list has the high-order bit set to 1.
- (Ra)
- A register pointing to an address list as previously described.
- INTERVAL(name4 | (Rn))
- Specifies in seconds or milliseconds the time after which the
task is automatically resumed and given a RESPONSE value of ‘PURGED'
and a REASON value of ‘TIMED_OUT'. The time unit used on
the INTERVAL option depends on the setting of the TIME_UNIT option.
The INTERVAL value overrides any timeout (DTIMOUT) value specified for the transaction.
- name4
- The name of a 4-byte area, which is interpreted as a binary fullword
- (Rn)
- A register containing the interval value, a binary fullword.
- PURGEABLE(YES|NO)
- Specifies whether your code can cope with the request being abnormally
terminated as a result of a purge. There are four types of purge,
as shown in Table 1. Specifying PURGEABLE(NO)
tells the dispatcher:
- To reject any attempt to PURGE the task
- To suppress the deadlock timeout (DTIMOUT) facility (if applicable to this task) for the duration of this request.
Table 1. SUSPEND call - RESPONSE(PURGED) REASON CONDITION PURGEABLE (NO) PURGEABLE (YES) TASK_CANCELLED PURGE Canceled Proceeds normally FORCEPURGE Proceeds normally Proceeds normally TIMED_OUT DTIMOUT Canceled Proceeds normally INTERVAL Proceeds normally Proceeds normally Note: A FORCEPURGE always assumes that the user wants the task to be purged, and so overrides the PURGEABLE(NO) option. If the user has set an INTERVAL, then this, too, overrides the PURGEABLE(NO) option. - RESOURCE_NAME(name16 | string | "string")
- Specifies a 16-character string that can be used to document and
trace the resource involved in suspend and resume processing. You
cannot use register notation to specify the address of the string.
- name16
- The name of the location where a 16-byte value is stored.
- string
- A string of characters without intervening blanks; if it is not 16 bytes long, it is extended with blanks or truncated as required.
- "string"
- A string of characters enclosed in quotation marks. Blanks are permitted in the enclosed string. If you want to document a name (label) in your program, use this form.
Note: CICS® does not use the RESOURCE_NAME information but includes it in trace entries, and displays it on appropriate CEMT screens to help you to see what your task is doing. CICS internal requests specify values, and you should use different values to avoid ambiguity. CICS internal request values are documented in The resources on which CICS system tasks can wait. - RESOURCE_TYPE(name8 | string | "string")
- Specifies an 8-character string that can be used to document and
trace the resource involved in suspend and resume processing. You
cannot use register notation to specify the address of the string.
- name
- The name of the location where an 8-byte value is stored.
- string
- A string of characters without intervening blanks; if it is not 8 bytes long, it will be extended with blanks or truncated as required.
- "string"
- A string of characters enclosed in quotation marks. Blanks are permitted in the enclosed string. If you want to document a name (label) in your program, use this form.
Note: CICS does not use the RESOURCE_TYPE information but includes it in trace entries, and displays it on appropriate CEMT screens to help you to see what your task is doing. CICS internal requests specify values, and you should use different values to avoid ambiguity. CICS internal request values are documented in The resources on which CICS system tasks can wait. - TIME_UNIT(SECOND | MILLI_SECOND)
- Specifies the time unit used on the INTERVAL option.
- SECOND
- The INTERVAL option specifies the number of seconds before timeout.
- MILLI_SECOND
- The INTERVAL option specifies the number of milliseconds before timeout.
- WLM_WAIT_TYPE(name1)
- Specifies, in a 1-byte location, the reason for suspending the
task. This indicates the nature of the task's wait state to the MVS workload
manager.
The equated values for the type of wait are as follows:
- CMDRESP
- Waiting on a command response.
- CONV
- Waiting on a conversation.
- DISTRIB
- Waiting on a distributed request.
- IDLE
- A CICS task, acting as a work manager, that has no work request that is allowed to service within the monitoring environment. For example, journaling code that suspends itself when there are no journaling I/O operations to perform.
- IO
- Waiting on an I/O operation or indeterminate I/O-related operation (locks, buffer, string, and so on).
- LOCK
- Waiting on a lock.
- MISC
- Waiting on an unidentified resource. This is the default reason given to the wait if you suspend a task and do not specify the WLM_WAIT_TYPE parameter.
- OTHER_PRODUCT
- Waiting on another product to complete its function; for example, when the workload has been passed to DB2®.
- SESS_LOCALMVS
- Waiting on the establishment of a session in the MVS image on which this CICS region is running.
- SESS_NETWORK
- Waiting on the establishment of a session elsewhere in the network (that is, not on this MVS image).
- SESS_SYSPLEX
- Waiting on establishment of a session somewhere in the sysplex (that is, not on this MVS image).
- TIMER
- Waiting on the timeout of a timer (for example, a task that puts itself to sleep).
If you are running CICS in an MVS goal-mode workload management environment (that is, you are using goal-oriented performance management), you are recommended to specify the reason for suspending the task on the WLM_WAIT_TYPE parameter.
| RESPONSE | REASON |
|---|---|
| OK | None |
| EXCEPTION | None |
| DISASTER | None |
| INVALID | None |
| KERNERROR | None |
| PURGED | TASK_CANCELLED |
| TIMED_OUT |
- For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
- TIMED_OUT is returned if the INTERVAL expires, or if a deadlock timeout interval expires.
- TASK_CANCELLED means that the task has been canceled by operator action or by an application command.