POST — Signal event completion

Description

Use the POST macro to set an event control block (ECB) to indicate the occurrence of an event. If this event satisfies the requirements of an outstanding WAIT or EVENTS macro, the waiting task is taken out of the wait state and dispatched according to its priority. POST processing sets the bits in the ECB as follows:
  • Bit 0 to 0 (wait bit)
  • Bit 1 to 1 (complete bit)
  • Bits 2 through 31 to the specified completion code.
Note: After the bits in the ECB are set, the ECB is considered posted and the awaited event can be recognized as having occurred by programs running in the system. If a program issues another POST against an ECB that is already posted, the other POST has no effect.

For more information on how to use the POST macro to synchronize tasks, see z/OS MVS Programming: Assembler Services Guide.

Environment

The requirements for callers of POST are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key
Dispatchable unit mode: Task
Cross memory mode: One of the following:
  • For LINKAGE=SVC: PASN=HASN=SASN
  • For LINKAGE=SYSTEM: PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks:
  • For LINKAGE=SVC: No locks held and no enabled unlocked task (EUT) functional recovery routines (FRR) established
  • For LINKAGE=SYSTEM: No locks held
Control parameters: The event control block (ECB) must be in the primary address space.

Programming requirements

None.

Restrictions

None.

Input register information

Before issuing the POST macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller the general purpose registers (GPRs) contain:
Register
Contents
0-1
Used as work registers by the system
2-13
Unchanged
14
Used as a work register by the system
15
One of the following:
  • If LINKAGE=SVC is specified: Used as a work register by the system
  • If LINKAGE=SYSTEM is specified: Return code of 0

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The POST macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␣ One or more blanks must precede POST.
   
POST  
   
␣ One or more blanks must follow POST.
   
ecb addr ecb addr: RX-type address, or register (1) or (2) - (12).
   
   ,comp code comp code: Symbol, decimal digit, or register (0) or (2) - (12).
  Range of values: 0 to (230 − 1)
  Default: 0
   
   ,LINKAGE=SVC Default: LINKAGE=SVC
   ,LINKAGE=SYSTEM  
   
   ,RELATED=value value: Any valid macro keyword specification.
   

Parameters

The explanation of the parameters is as follows:

ecb addr
Specifies the address of the fullword event control block representing the event.
,comp code
Specifies the completion code to be placed in the event control block upon completion.
,LINKAGE=SVC
,LINKAGE=SYSTEM
Specifies the type of linkage that the caller is using to invoke the POST service routine.

For LINKAGE=SVC, the linkage is through an SVC instruction. This linkage is valid only when the caller is in primary mode and the primary, home, and secondary address spaces are the same.

For LINKAGE=SYSTEM, the linkage uses a non-SVC entry. This linkage is valid in cross memory mode or in non-cross memory mode. The ECB must be in the caller's primary address space. LINKAGE=SYSTEM is intended to be used by programs in cross memory mode.

The default is LINKAGE=SVC.

,RELATED=value
Specifies information used to self-document macros by ‘relating’ functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user and may be any valid coding values.

The RELATED parameter is available on macros that provide opposite services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and LOAD/DELETE) and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).

The RELATED parameter may be used, for example, as follows: 
WAIT1   WAIT    1,ECB=ECB,RELATED=(RESUME1,'WAIT FOR EVENT')
  .
  .
  .
RESUME1 POST    ECB,0,RELATED=(WAIT1,'RESUME WAITER')

Return and reason codes

For LINKAGE=SYSTEM, the return code in register 15 is always zero. Otherwise, the POST macro has no return codes.

Example 1

Signal event completion with a default completion code. POSTECB is the address of an ECB. 
POST     POSTECB

Example 2

Signal event completion with a completion code of X‘7FF’. POSTECB is the address of an ECB. 
POST     POSTECB,X'7FF'