POST

Purpose

Use the POST macro to signal a task that the event it is waiting for has taken place.

A task that has issued the WAIT macro cannot continue until a certain event has taken place. See WAIT. It is the responsibility of the program effecting this event to inform the waiting task that the event has occurred.

Each such event is associated with an event control block (ECB). This ECB defines the event that is to occur and indicates to the waiting task whether it has occurred.

Use the POST macro to inform a task that the event it is waiting for has taken place.

Parameters

ecb_address

Specifies the address of the event control block associated with the event that has occurred.

You can write this parameter as an RX-type address or as register (1) through (12).

completion_code

Specifies the code describing the manner which the event in question took place.

These codes have significance only to the programmers at your installation (and to the programs they write). Each installation must define the meaning of some or all of these completion codes and document them.

A completion code may be any number from 0 to 2³⁰-1. If you omit this parameter, a completion code of 0 is assumed, by default. The completion code may be specified as a constant or as register (0) through (15).

RELATED

Specifies documentation data that you are using to relate this macro to a WAIT macro. The value you assign to this parameter has nothing to do with the execution of the macro itself. It merely relates one macro (POST) to another instruction that provides an opposite, though related, service (WAIT).

The format and content of this parameter are at your discretion, and can be any valid coding values.

Usage

1. The task issuing the WAIT macro and the task issuing the POST instruction provide storage for each event control block. Each ECB is a fullword on a fullword boundary.
2. Bit 0 of the ECB is called the WAIT bit. If this bit is set to 1, then it means that some task is waiting for the event associated with that ECB to occur.
3. Bit 1 of the ECB is called the POST bit. The POST macro sets the POST bit of the appropriate ECB to 1 and then resets the WAIT bit to 0. These actions signal the waiting task that the event in question has taken place.
4. The remaining 30 bits of the ECB hold the completion code, after the ECB is posted.
5. Tasks are not always placed in the WAIT state after having issued the WAIT macro. Because the task is immediately satisfied, there is no reason for it to go into the WAIT state.
6. It is possible for a program to perform a branch entry into the POST macro code.

   Those programmers who find it necessary to perform such a branch entry must be disabled for interrupts and be running in supervisor state and in key 0. They must do the following before taking this branch:

   1. Provide a save area in virtual storage that is 224 bytes long. In the first word of this save area you must store the number 152. In the third word of this save area you must store the sum of the address of the save area plus 72.
   2. You must be certain that the registers contain the following information:

      Register	Contents
      0	The COMPLETION CODE in the low-order 30 bits.
      1	The address of the ECB in question.
      13	The address of the 224-byte save area.
      14	The return address within your program.
      15	The address of the entry point in the POST macro to which you are branching.

   3. Because the point to which you will branch will be in low storage, use the FLS macro to generate the FLS DSECT. See FLS. Include the

      USING FLS,0

      instruction in your program, and branch to the address stored at the address associated with the label FLSPOST.
7. Be certain that none of your tasks change any of the bits in an ECB for which a WAIT instruction has been issued. Only after the POST bit has been set to 1 and its contents analyzed is it safe to alter an ECB.

Return Codes and ABEND Codes

Note that these return codes are possible only when a branch entry to the POST macro is involved.

Note that these ABEND codes are possible only during a usual SVC call from the POST macro.