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:
  1. 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.
  2. 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:
  1. 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.
  2. 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.

Table 2. RESPONSE and REASON values for SUSPEND
RESPONSE REASON
OK None
EXCEPTION None
DISASTER None
INVALID None
KERNERROR None
PURGED TASK_CANCELLED
TIMED_OUT
Note:
  1. For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
  2. TASK_CANCELLED means that the task has been canceled by operator action or by an application command.
  3. 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.
  4. 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.


dfha33x.html | Timestamp icon Last updated: Monday, 5 June 2017