POST

Requests notification when the specified expiration time for exclusive control on a record is reached.

Syntax


POST

>>-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: INTERVAL and TIME are not supported for C or C++ programs.

Description

The POST command 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 that is specified in the SET option is set to its address.

When the specified time has expired, the timer-event control area is posted; that is, its first byte is set to X'40', and its third byte is set to X'80'. You can test posting in either of the following ways:

By checking the timer-event control area. 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 use of a WAIT EVENT command to suspend task activity until the timer-event control area is posted. This action is similar to issuing a DELAY command, but with a POST and WAIT EVENT command sequence, you can do some processing after issuing the POST command; a DELAY command suspends task activity immediately. No other task should attempt to wait on the event that is set up by a POST command.

The timer-event control area can be released for a variety of reasons. If it is released, the result is unpredictable of any other task that is issuing a WAIT command on the event that is set up by the POST command.

Other tasks can cancel the event if they have access to the REQID that is associated with the POST command. (See the CANCEL command and the description of the REQID option.) A timer-event control area that is provided for a task is not released or changed, except as described above, until one of the following events occurs:

The task issues a subsequent DELAY, POST, or START command.
The task issues a CANCEL command to cancel the POST command.
The task is terminated, normally or abnormally.
Any other task issues a CANCEL command for the event that is set up by the POST command.
A task finishes a WAIT for the event that is set up by the POST command.
Thirty minutes after the event that is set up by the POST command expires.

A task can have only one POST command active at any time. Any DELAY, POST, or START command supersedes a POST command that was previously issued by the task.

Options

AFTER

Together with one or more of the HOURS, MINUTES, and SECONDS options, specifies the interval of time to elapse.

The time can be entered in two ways under AFTER:

Use a combination of at least two of HOURS (0 through 99), MINUTES (0 through 59), or SECONDS (0 through 59). HOURS (1) SECONDS (3) means one hour and three seconds; the minutes default to zero.
Use one of HOURS (0 through 99), MINUTES (0 through 5999), or SECONDS (0 through 359999). HOURS (1) means one hour. MINUTES (62) means one hour and two minutes. SECONDS (3723) means one hour, two minutes, and three seconds.

The default is AFTER HOURS (0) MINUTES (0) SECONDS (0).

This option must be used instead of INTERVAL in C or C++ programs.

AT

Together with one or more of the HOURS, MINUTES, and SECONDS options, specifies the expiration time. See the AFTER option for a discussion on the ways to enter the time. This option must be used instead of TIME in C or C++ programs.

HOURS (data-value)

Specifies a 32-bit binary value in the range 0 through 99. This is a suboption of the AFTER and AT options. See the AFTER option for discussion on its use and meaning.

INTERVAL (hhmmss)

(This option is for COBOL only.) Specifies a time interval that is to elapse from the time when the POST command is issued. The values for mm and ss are in the range 0 through 59. When the command is executed, CICS calculates the expiration time by adding the specified interval to the current clock time. This option is used to specify the time when the timer-event control area is to be posted. The default is INTERVAL (0).

The INTERVAL option is not supported for C or C++ programs. Use the AFTER HOURS, MINUTES, and SECONDS options instead.

MINUTES (data-value)

Specifies a 32-bit binary value. When MINUTES is the only option that is specified, the range is 0 through 5999; when the options of HOURS or SECONDS are also specified, this value is in the range 0 through 59. This is a suboption of the AFTER and AT options. See the AFTER option for discussion on its use and meaning.

REQID (name)

Specifies a unique name (1 through 8 characters) 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 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, you can store it in a TS queue whose name is known to other applications that possibly need to cancel the POST request.

SECONDS (data-value)

Specifies a 32-bit binary value. When SECONDS is the only option that is specified, the range is 0 through 359999; when the options of HOURS or MINUTES are also specified, this value is in the range 0 through 59. This is a suboption of the AFTER and AT options. See the AFTER option for discussion on its use and meaning.

SET (ptr-ref)

Specifies the pointer reference that is to be set to the address of the 4-byte timer-event control area that is 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 is set to X'80'.

TIME (hhmmss)

(This option is for COBOL only.) Specifies the time when the posting of the timer-event control area is to occur.

The TIME option is not supported for C or C++ programs. Use the AT HOURS, MINUTES, and SECONDS options instead.

Conditions

EXPIRED

Occurs if the time that is specified has already expired when the command is issued.

Default action: Ignores the condition.

INVREQ

Occurs for the following conditions when RESP2 is set:

RESP2 values:

Hours are out of range (RESP2=4).
Minutes are out of range (RESP2=5).
Seconds are out of range (RESP2=6).

Also occurs in the following condition when RESP2 is not set:

The POST command is not valid for processing by CICS (likely because of an internal error).

Default action: Terminates the task abnormally.

Examples

The following example shows how to request a timer-event control area for a task that is to be posted after a 30-second interval:

EXEC CICS POST
           INTERVAL(30)
           REQID('RBL3D')
           SET(PREF)

The following example shows how to ask to be notified when the specified time of day is reached. Because no request identifier is specified in the command, CICS automatically assigns one and returns it to the application program in the EIBREQID field in the EIB.

EXEC CICS POST
           TIME(PACKTIME)
            SET(PREF)