The SUSPEND call
SUSPEND suspends execution of a running task.
Suspended tasks can be resumed in one of two ways. You can issue the XPI RESUME call, or the task is resumed automatically if the INTERVAL value that you specify on the DFHDSSRX macro expires. Suspended tasks can also be purged by the operator, or by an application, or by the deadlock timeout facility.
SUSPEND
DFHDSSRX [CALL,]
[CLEAR,]
[IN,
FUNCTION(SUSPEND),
PURGEABLE(YES|NO),
SUSPEND_TOKEN(name4 | (Rn)),
[INTERVAL(name4 | (Rn)),]
[RESOURCE_NAME(name16 | string | 'string'),]
[RESOURCE_TYPE(name8 | string | 'string'),]
[TIME_UNIT(SECOND|MILLI_SECOND),]
[WLM_WAIT_TYPE,]]
[OUT,
[COMPLETION_CODE(name1 | (Rn)),]
RESPONSE(name1 | *),
REASON(name1 | *)]
This command is threadsafe.
- COMPLETION_CODE (name1 | (Rn))
- Returns a user-defined “reason for action” code during
suspend and resume processing.
- name1
- The name of a 1-byte area to receive the code. The value in this field is user-defined, and is ignored by CICS®.
- (Rn)
- A register in which the low-order byte contains the completion code and the other bytes are zero.
- 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 described in The resources on which CICS system tasks can wait.
- If RESOURCE_NAME is not specified, the default value, if any, from ADD_SUSPEND is used.
- 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.
- name8
- 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 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_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.
- If RESOURCE_TYPE is not specified, the default value, if any, from ADD_SUSPEND is used.
- SUSPEND_TOKEN(name4 | (Rn))
- Specifies a token assigned by the system to identify the SUSPEND/RESUME
pair of operations used on the task.
- name4
- The name of a location where you have a 4-byte token previously obtained as output from an ADD_SUSPEND call
- (Rn)
- A register containing the token value.
- 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 reason indicates the nature of the 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. Note: This value 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), 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 |
Note:
- For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
- TASK_CANCELLED means that the task has been canceled by operator action or by an application command.
- After a PURGED response, the suspend token must not be reused in another SUSPEND until it has been reset by a RESUME corresponding to the purged SUSPEND.
- TIMED_OUT means that the task has been automatically resumed because the specified INTERVAL (or the timeout value specified at task attach) has expired. The token, however, remains suspended and must be the object of a RESUME before it can be the object of a DELETE_SUSPEND.