Request notification when a specified time has expired.
POST .-INTERVAL(0)------------------------. >>-POST--+------------------------------------+--SET(ptr-ref)---> +-INTERVAL(hhmmss)-------------------+ +-TIME(hhmmss)-----------------------+ | .-------------------------. | | V | | +-AFTER----+-HOURS(data-value)---+-+-+ | +-MINUTES(data-value)-+ | | '-SECONDS(data-value)-' | | .-------------------------. | | V | | '-AT----+-HOURS(data-value)---+-+----' +-MINUTES(data-value)-+ '-SECONDS(data-value)-' >--+-------------+--------------------------------------------->< '-REQID(name)-'
Conditions: EXPIRED, INVREQ
Note for dynamic transaction routing: Using POST if later CANCELed by another task could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See Affinity for more information about transaction affinities.
Description
POST requests notification that a specified time has expired. In response to this command, CICS makes a timer-event control area available for testing. This 4-byte control area is initialized to binary zeros, and the pointer reference specified in the SET option is set to its address.
- By checking the timer-event control area at intervals. You must give CICS the opportunity to post the area; that is, the task must relinquish control of CICS before you test the area. Normally, this condition is satisfied as a result of other commands being issued; if a task is performing a long internal function, you can force control to be relinquished by issuing a SUSPEND command.
- By suspending task activity by a WAIT EVENT or WAIT EXTERNAL command until the timer-event control area is posted. This action is similar to issuing a DELAY command but, with a POST and WAIT EVENT or WAIT EXTERNAL command sequence, you can do some processing after issuing the POST command; a DELAY command suspends task activity at once. No other task should attempt to wait on the event set up by a POST command.
- By using WAITCICS.
- Subsequent POST commands
- A CANCEL of the POST
- A local START command
A START command that names a transaction on a remote system does not affect the event set up by the POST command, unless the transaction is defined with LOCALQ set to YES and local queuing is performed.
- Subsequent DELAY commands
- The POST time expires.
- Another transaction issues a CANCEL using the POST REQID.
The timer-event control area can be released for a variety of reasons. If this happens, the result of any other task issuing a WAIT command on the event set up by the POST command is unpredictable.
However, other tasks can cancel the event if they have access to the REQID associated with the POST command. (See the CANCEL command and the description of the REQID option.)
A task can have only one POST command active at any given time. Any DELAY or POST command, or a START command naming a transaction in the local system, supersedes a POST command previously issued by the task.
The default is INTERVAL(0), but for C the default is AFTER HOURS(0) MINUTES(0) SECONDS(0).
Options
- AFTER
- specifies
the interval of time to elapse. There are two ways to enter the time under AFTER and AT.
- A combination of at least two of HOURS(0–99), MINUTES(0–59), and SECONDS(0–59). HOURS(1) SECONDS(3) would mean one hour and three seconds (the minutes default to zero).
- As one of HOURS(0–99), MINUTES(0–5999), or SECONDS(0–359 999). HOURS(1) means one hour. MINUTES(62) means one hour and two minutes. SECONDS(3723) means one hour, two minutes, and three seconds.
- AT
- specifies the time of expiring. For the ways to enter the time, see the AFTER option.
- HOURS(data-value)
- specifies a fullword binary value in the range 0–99. This is a suboption of the AFTER and AT options. For its use and meaning, see the AFTER option.
- INTERVAL(hhmmss)
- specifies
an interval of time that is to elapse from the time at which the POST command
is issued. The mm and ss are in the range 0–59. The time specified
is added to the current clock time by CICS when the command is executed to
calculate the expiration time.
This option is used to specify when the posting of the timer-event control area should occur.
When using the C language, you are recommended to use the AFTER/AT HOURS, MINUTES, and SECONDS options as C does not provide a packed decimal data type. You may use INTERVAL, but if the value specified is not an integer constant, the application is responsible for ensuring that the value passed to CICS is in packed decimal format.
- MINUTES(data-value)
- specifies a fullword binary value in the range 0–59, when HOURS or SECONDS are also specified, or 0–5999 when MINUTES is the only option specified. This is a suboption of the AFTER and AT options. For its use and meaning, see the AFTER option.
- REQID(name)
- specifies
a name (1–8 characters), which should be unique, to identify the POST request.
Using this option to specify an application-defined name is one way to enable
another transaction to cancel the POST request.
If you do not specify your own REQID, CICS generates a unique request identifier for you in the EIBREQID field of the EXEC interface block. This, like your own REQID, can be used by another transaction to cancel the POST request.
To enable other tasks to cancel unexpired POST requests, you must make the request identifier dynamically available. For example, storing it in a TS queue, whose name is known to other applications that may want to cancel the POST request, is one way you can pass a request identifier to other transactions.
- SECONDS(data-value)
- specifies a fullword binary value in the range 0–59, when HOURS or MINUTES are also specified, or 0–359 999 when SECONDS is the only option specified. This is a suboption of the AFTER and AT options. For its use and meaning, see the AFTER option.
- SET(ptr-ref)
- specifies
the pointer reference to be set to the address of the 4-byte timer-event control
area generated by CICS. This area is initialized to binary zeros; on expiration
of the specified time, the first byte is set to X'40', and the third
byte to X'80'.
The timer-event control area always resides below the 16MB line in shared dynamic storage (SDSA).
- TIME(hhmmss)
- specifies
the time when the posting of the timer-event control area should occur.
When using the C language, you are recommended to use the AFTER/AT HOURS, MINUTES, and SECONDS options as C does not provide a packed decimal data type. You may use TIME, but if the value specified is not an integer constant, the application is responsible for ensuring that the value passed to CICS is in packed decimal format. See the section about expiration times in Interval control .
Conditions
- 31 EXPIRED
- occurs
if the time specified has already expired when the command is issued.
Default action: ignore the condition.
- 16 INVREQ
- RESP2
values:
- 4
- Hours are out of range.
- 5
- Minutes are out of range.
- 6
- Seconds are out of range.
also occurs (RESP2 not set) in any of the following situations:- The POST command is not valid for processing by CICS.
Default action: terminate the task abnormally.
Examples
EXEC CICS POST
INTERVAL(30)
REQID('RBL3D')
SET(PREF)EXEC CICS POST
TIME(PACKTIME)
SET(PREF)