Description

Use the POST macro to set a specified 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.

The bits in the ECB are set as follows:

The POST macro is also described in z/OS MVS Programming: Assembler Services Reference IAR-XCT with the exception of the parameters ASCB, ERRET, ECBKEY, and LINKAGE=BRANCH. For further information on how to use POST to serialize parallel tasks, see z/OS MVS Programming: Authorized Assembler Services Guide.

Parent topic: POST — Signal event completion

Environment

The requirements for callers of POST with LINKAGE=SVC are:

Environmental factor Requirement
Minimum authorization: Problem state with any PSW key. For the ASCB, ERRET, and ECBKEY parameters, one or more of the following:
  • Supervisor state
  • PSW key 0-7
  • APF-authorized
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: If the caller specifies the ASCB parameter, the event control block (ECB) must be addressable from the address space identified by the ASCB parameter. If the caller does not specify the ASCB parameter, the ECB must be in the home address space.

The requirements for callers of POST with LINKAGE=SYSTEM are:

Environmental factor Requirement
Minimum authorization: Problem state with any PSW key. For the ASCB, ERRET, and ECBKEY parameters, one or more of the following:
  • Supervisor state
  • PSW key 0-7
  • APF-authorized
Dispatchable unit mode: Task or SRB
Cross memory mode: Any PASN, any HASN, any SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: If the caller specifies the ASCB parameter, the event control block (ECB) must be addressable from the address space identified by the ASCB parameter. If the caller does not specify the ASCB parameter, the ECB must be in the caller's primary address space.

The requirements for callers of POST with LINKAGE=BRANCH are:

Environmental factor Requirement
Minimum authorization: Supervisor state and PSW key 0
Dispatchable unit mode: Task or SRB
Cross memory mode:
  • If the caller specifies the ASCB parameter: any PASN, any HASN, any SASN
  • If the caller does not specify ASCB and is in primary ASC mode: PASN=HASN with any SASN
  • If the caller does not specify ASCB and is in secondary ASC mode: SASN=HASN with any PASN.
AMODE: 24- or 31-bit
ASC mode: Primary or secondary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: The caller must hold the local lock, unless the caller specifies the ASCB parameter, in which case the local lock can be held but is not required.
Control parameters: If the caller specifies the ASCB parameter, the event control block (ECB) must be addressable from the address space identified by the ASCB parameter. If the caller does not specify the ASCB parameter, the ECB must be in the home address space.

Programming requirements

For LINKAGE=BRANCH or BRANCH=YES, the caller must include the CVT mapping macro.

Restrictions

Callers that specify LINKAGE=SVC cannot have any enabled unlocked task (EUT) functional recovery routines (FRR) established.

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

For LINKAGE=SVC, 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-15
Used as work registers by the system
For LINKAGE=SYSTEM, 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
Return code
For LINKAGE=BRANCH, when control returns to the caller the general purpose registers (GPRs) contain one of the following:
  • If the ASCB parameter is not specified:
    Register
    Contents
    0-9
    Unchanged
    10-11
    Used as work registers by the system
    12-13
    Unchanged
    14-15
    Used as work registers by the system
  • If the ASCB parameter is specified, the LOCAL lock is held and MEMREL=YES is specified (or defaulted):
    Register
    Contents
    0
    One of the following:
    • If the ECBKEY parameter is not specified: Unchanged
    • If the ECBKEY parameter is specified: Used as a work register by the system
    1-9
    Unchanged
    10-15
    Used as work registers by the system
  • If the ASCB parameter is specified, the LOCAL lock is not held or MEMREL=NO is specified:
    Register
    Contents
    0-8
    Used as work registers by the system
    9
    Unchanged
    10-15
    Used as work registers by the system

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 standard form of 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 (2) - (12), except (10).
   
   ,comp code comp code: Symbol, decimal or hexadecimal digit, or register (0), (2) - (9), (10), or (12).
 

Range of values: 0 to (230 − 1)
Default: 0
   
   ,ASCB=addr,ERRET=err rtn  
   ,ASCB=addr,ERRET=err rtn,ECBKEY=key  
  addr: RX-type address, or register (2) - (9), (12).
  : RX-type address, or address in register (2) - (9), (12).
  key: Symbol, decimal or hexadecimal digit, or register (2) - (9), (12).
  Range of values: 0 - 15 (decimal), Default: None.

Note: If the register form is specified, bits 24-27 of the register must contain the key.
   
   ,LINKAGE=SVC Default: LINKAGE=SVC
   ,LINKAGE=BRANCH  
   ,LINKAGE=BRANCH,  
      ECBKEY=key key: Symbol, decimal or hexadecimal digit, or register (2) - (9), (12).
  Range of values: 0 - 15 (decimal), Default: None.Note: If the register form is specified, bits 24-27 of the register must contain the key.
   ,LINKAGE=SYSTEM  
   ,LINKAGE=SYSTEM,  
      ERRET=err rtn : RX-type address, or address in register (2) - (9), (12).
   
   ,BRANCH=NO Default: BRANCH=NO
   ,BRANCH=YES  
   
   ,MEMREL=YES Default: MEMREL=YES
   ,MEMREL=NO Note: MEMREL can be coded only if LINKAGE=BRANCH and the ASCB and ERRET parameters are coded.
   
   ,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.
,ASCB=addr,ERRET=err rtn
,ASCB=addr,ERRET=err rtn,ECBKEY=key
Specifies the address of the ASCB of the address space containing the ECB being posted, and a pointer to the address of the routine that receives control when an error condition resulting from a POST failure is detected. The ASCB must reside in 24-bit addressable storage.

The ERRET routine is further described in Asynchronous Cross Memory POST in z/OS MVS Programming: Authorized Assembler Services Guide.

,LINKAGE=SVC
,LINKAGE=BRANCH
,LINKAGE=BRANCH,ECBKEY=key
,LINKAGE=SYSTEM
,LINKAGE=SYSTEM,ERRET=err rtn
Specifies the type of linkage from the caller to a system service routine that POST invokes. The default is LINKAGE=SVC.

For LINKAGE=SVC, the linkage is through an SVC instruction. This linkage is valid only when the caller is in task mode and primary ASC mode, where primary, home, and secondary are the same address space. For SVC callers, registers 2-14 are preserved.

For LINKAGE=BRANCH, the linkage is through a branch entry. This linkage is valid when the caller is in primary or secondary ASC mode. The calling requirements and the registers that are preserved depend on the other parameters specified, as follows:
  • If ASCB is not specified, the caller must hold the local lock and be in noncross memory mode. Registers 0-9, 12, and 13 are preserved.
  • If ASCB is specified, the MEMREL parameter and the LOCAL lock determine the calling requirements and registers saved.
    • If the LOCAL lock is held and MEMREL=YES is specified (or defaulted), then the current address space must be the home address space and registers 1-9 are preserved. If the ECBKEY parameter is not specified, register 0 is also preserved.
    • If the LOCAL lock is not held or MEMREL=NO is specified, then only register 9 is preserved. The current address space can be any address space.

With LINKAGE=BRANCH, you can also specify the storage protection key of the ECB to be posted using the ECBKEY parameter. The system checks the storage key of the ECB against the ECBKEY before posting it.

Note: BRANCH=YES and BRANCH=NO are still supported by the system, but LINKAGE is the recommended parameter.
For LINKAGE=SYSTEM, the linkage uses a non-SVC entry. Callers must be enabled, unlocked, and in primary ASC mode. This linkage is valid for callers in both noncross memory and cross memory mode. If you specify the ASCB parameter, the ECB must be addressable from the address space identified by ASCB. If you do not specify ASCB, the ECB must be in the caller's primary address space. When you specify LINKAGE=SYSTEM and ASCB, you must also specify ECBKEY.
  • ERRET=err_rtn specifies the routine that gets control when the system detects a POST failure after control has been returned to the issuer of POST. If the caller is not authorized, the error routine does not receive control. When the ASCB parameter is specified, the ERRET routine is used only when asynchronous cross-memory POST fails in the address space identified by the ASCB. The ERRET routine is further described in Asynchronous Cross Memory POST in z/OS MVS Programming: Authorized Assembler Services Guide.
  • When you issue LINKAGE=SYSTEM, the POST macro service issues the return codes described in Return codes.

    LINKAGE=SYSTEM without the ASCB parameter is intended to be used by programs in cross memory mode.

,MEMREL=YES
,MEMREL=NO
Specifies the address space in which the routine specified on the ERRET parameter is to run. MEMREL can be specified with LINKAGE=BRANCH only:
  • Specify MEMREL=YES (or accept the default of MEMREL=YES) if you want the ERRET routine to run in the caller's home address space.
  • Specify MEMREL=NO if you want the ERRET routine to run in the master scheduler's address space.
Note: You cannot specify MEMREL=YES if you hold the local lock and you are running in cross memory mode. Therefore, if you do not know that the primary and home address spaces are the same, you should specify MEMREL=NO.
,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.

ABEND codes

POST might abnormally terminate with one of the following abend codes:
  • X'102'
  • X'202'
  • X'302'
  • X'402'
  • X'502'
  • X'602'
  • X'702'

These hexadecimal codes are described in z/OS MVS System Codes.

Return codes

When you issue LINKAGE=SYSTEM, the POST macro service issues the following hexadecimal return codes.

Table 1. Return Codes for the POST Macro
Return Code Meaning and Action
00 Meaning: Indicates a synchronous POST was done, as requested.

Action: None.
04 Meaning: Environmental error. Indicates an asynchronous POST is in progress. If you specified ERRET and a failure occurs before the POST completes, the error routine that you specified will receive control. If you did not specify ERRET and a failure occurs before the POST completes, no error routine exists to receive control.

Action: None required. However, you might take some action based upon your application.
08 Meaning: Environmental error. Indicates an asynchronous POST is in progress. You specified ERRET; however, if an error occurs before POST completes, the error routine that you specified will not receive control.

Action: None required. However, you might take some action based upon your application.

Example 1

Post an event control block whose address is ECB, where the address space containing the ECB has an ASCB specified by register 5, and where ERRRTN is the routine to be given control on error conditions. 
POST ECB,ASCB=(REG5),ERRET=ERRRTN

Example 2

Post the ECB from example 1 with a hexadecimal completion code of 3FF. 
POST ECB,X'3FF',ASCB=(REG5),ERRET=ERRRTN

Example 3

Post the ECB from example 1 using a stacking PC for linkage. The address of the error routine is in register 3. 
POST ECB,LINKAGE=SYSTEM,ECBKEY=0,ASCB=(REG5),ERRET=(REG3)