Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

The SYNCH macro takes a synchronous exit to a processing program. After the processing program has been executed, the program that issued the SYNCH macro regains control. The SYNCH macro is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP with the exception of the KEYADDR, STATE, KEYMASK, and XMENV parameters. These parameters are restricted to programs in supervisor state, key 0-7, or APF-authorized.

If you are executing in 31-bit addressing mode, you must use the MVS/SP Version 2 of this macro, or a later version.

The SYNCH macro is intended for use by primary mode programs only. If your program runs in access register (AR) mode, use SYNCHX, which provides the same function as SYNCH. Descriptions of SYNCH and SYNCHX are:

The standard form of the SYNCH macro, which includes general information about the SYNCH and SYNCHX macros and some specific information about the SYNCH macro. The syntax of the SYNCH macro is presented, and all SYNCH parameters are explained.
The standard form of the SYNCHX macro, which presents information specific to the SYNCHX macro and callers in AR mode.
The list form of the SYNCH and SYNCHX macros.
The execute form of the SYNCH and SYNCHX macros.

If the caller is in AR mode, the system passes the following values, unchanged, to the processing program:

ARs 0-13
Bits 16 and 17 of the current PSW indicating the ASC mode (primary or AR mode, where primary=secondary=home)
Extended authorization index (EAX)

Parameters for SYNCH and SYNCHX must be in the caller's primary address space. Callers in AR mode must initialize AR 1 to zero before issuing SYNCHX.

Register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Values the processing program placed there before it returned to the caller
2-13: If RESTORE=YES, unchanged
If RESTORE=NO, values the processing program placed there before it returned to the caller
14: Used as a work register by the system
15: Value the processing program placed there before it returned to the caller

Syntax

The SYNCH macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede SYNCH.

SYNCH

␢	One or more blanks must follow SYNCH.

`entry point addr`	`entry point addr`: RX-type address, or register (2) - (12) or (15).

,RESTORE=NO	Default: RESTORE=NO
,RESTORE=YES

,KEYADDR=`addr`	`addr`: RS-type address, or register (2) - (12).
,KEYADDR=NOKEYADDR	Default: KEYADDR=NOKEYADDR
	(The key in the TCB is used.)

,STATE=PROB	Default: STATE=PROB
,STATE=SUPV

,KEYMASK=`addr`	`addr`: RX-type address, or register (0) - (12).
,XMENV=`addr`	`addr`: RX-type address or register (0) - (12).

,AMODE=24	Default: AMODE=CALLER
,AMODE=31	Note: AMODE=DEFINED can only be specified if the entry point is provided in a register.
,AMODE=DEFINED
,AMODE=CALLER

Parameters

The parameters are explained as follows:

entry point addr

Specifies the address of the entry point of the processing program to receive control.

,RESTORE=NO

,RESTORE=YES

Specifies whether registers 2-13 are to be restored when control is returned to the issuer of SYNCH.

,KEYADDR=addr

,KEYADDR=NOKEYADDR

addr specifies the address of a one-byte area that contains the key in which the exit is to receive control. The key must be in bits 0-3; bits 4-7 must be zero. If KEYADDR=addr is not specified, the key in the TCB is used as the default.

,STATE=PROB

,STATE=SUPV

Specifies the state in which the requested program receives control. PROB specifies problem state and SUPV specifies supervisor state.

,KEYMASK=addr

Specifies the address of a halfword, which along with the protect key of the currently active TCB, will be an operand in an OR instruction. The results of that instruction produce the PKM of the routine to which your program will take a synchronous exit.

If you specify KEYMASK, do not specify XMENV.

,XMENV=addr

Specifies the address of a parameter list that the caller passes to the SYNCH macro service. The parameter list contains values that set up a cross memory environment for the new PRB. The parameter list consists of either a 10-byte or 20-byte list of values that determine some of the characteristics the PRB will have when it receives control. The parameter list must reside in the primary address space and the AR that qualifies the address must be set be set to zero. The format of the parameter list is indicated by the length field in the first two bytes.

If the length field in the first two bytes indicates a 10 (X'0A') byte parameter list, the format is as follows (mapped by DSECT XMENV in data area CSVXMENV):

Bytes	Content of field
0-1	The value X‘0A’
2-3	PKM value, which along with the protect key of the currently active TCB, will be an operand in an OR instruction. The results of that instruction produce the PKM of the routine to which the synchronous is to be taken.
4-5	SASN - defining the secondary address space for the exit routine
6-7	Extended authorization index (EAX) for the exit routine
8-9	PASN - defining the primary address space for the exit routine

If the length field in the first two bytes indicates a 20 (X'14') byte parameter list, the format is as follows (mapped by DSECT XMENV1 in data area CSVXMENV):

Bytes	Content of field
0-1	The value X'14'
2-3	PKM value, which along with the protect key of the currently active TCB, will be an operand in an OR instruction. The results of that instruction produce the PKM of the routine to which the synchronous is to be taken.
4-5	SASN - defining the secondary address space for the exit routine
6-7	Extended authorization index (EAX) for the exit routine
8-9	PASN - defining the primary address space for the exit routine
10–11	Reserved for IBM® use
12–15	The primary ASTE instance number
16–19	The secondary ASTE instance number

If you specify XMENV, do not specify KEYMASK.

,AMODE=24

,AMODE=31

,AMODE=DEFINED

,AMODE=CALLER

Specifies the addressing mode in which the requested program is to receive control.

If AMODE=24 is specified, the requested program will receive control in 24-bit addressing mode.

If AMODE=31 is specified, the requested program will receive control in 31-bit addressing mode.

If AMODE=DEFINED is specified, the user must provide the entry point using a register, not an RX-type address. The requested program will receive control in the addressing mode indicated by the high-order bit of the entry point address. If the bit is off, the requested program will receive control in 24-bit addressing mode; if the bit is set, the requested program will receive control in 31-bit addressing mode.

If AMODE=CALLER is specified, the requested program will receive control in the addressing mode of the caller.

Example 1

Take a synchronous exit to a processing program whose entry point address is specified in register 8.

SYNCH (8)

Example 2

Take a synchronous exit to a processing program labeled SUBRTN and restore registers 2-13 when control is returned.

SYNCH SUBRTN,RESTORE=YES

Example 3

Take a synchronous exit to a processing program whose entry point address is specified in register 5, modify the program's protect key by the KEYADDR and KEYMASK values, and restore registers 2-13 when control returns.

SYNCH (5),RESTORE=YES,KEYADDR=KEYBYTE,KEYMASK=MSKADDR
   .
   .
   .
KEYBYTE DC X'80'
MSKADDR DC X'0080'

Example 4

Take a synchronous exit to the program located at the address given in register 8 and restore registers 2-13 when control returns. Indicate that this program is to execute in 24-bit addressing mode.

SYNCH (8),RESTORE=YES,AMODE=24