Description

Description

z/OS MVS Programming: Assembler Services Reference ABE-HSP
SA23-1369-00

The CALL macro passes control to a control section at a specified entry point as follows:

OVERLAY: The overlay segment containing the designated entry point is brought into virtual storage if required, and control is passed to the segment.
Refer to z/OS MVS Program Management: User's Guide and Reference and z/OS MVS Program Management: Advanced Facilities for details on overlay.
NONOVERLAY: If a symbol is designated, the linkage editor includes the load module containing that entry point in the same load module containing the CALL instruction. When the CALL macro is executed, control is passed to the control section at the specified entry point.

The linkage relationship established when control is passed is the same as that created by a BAL instruction; that is, the issuing program expects control to be returned. The control program is not involved in passing control, so the reusability of the called program must be ensured by the user.

An address parameter list can be constructed and a calling sequence identifier can be provided.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	Problem state and any PSW key
Dispatchable unit mode:	Task or SRB
Cross memory mode:	PASN=HASN=SASN or PASN¬=SASN¬=HASN
AMODE:	24- or 31- or 64- bit
ASC mode:	Primary or Access register (AR)
Interrupt status:	No requirement
Locks:	No requirement
Control parameters:	Must be in the caller's primary address space or be in an address or data space that is addressable through a public entry on the caller's dispatchable unit access list (DU-AL).

Programming requirements

If your program is to execute in 31-bit addressing mode, you must use the MVS/SP Version 2 macro expansion or a later version. You cannot use the CALL macro to pass control to a program in a different addressing mode.

AR mode programs and primary mode programs can invoke the CALL macro. Before an AR mode program invokes this macro, the program must issue SYSSTATE ASCENV=AR to tell the CALL macro to generate code that is appropriate for AR mode. Before a 64-bit Amode program invokes this macro, the program must issue SYSSTATE AMODE64=YES to tell the CALL macro to generate code that is appropriate for Amode 64.

IBM® recommends that you do not use asynchronous exit routines in an overlay program. If you choose to do so, you must ensure that:

The overlay segment containing the asynchronous exit routine is already in storage at the time the system invokes the routine, and this segment will not be overlaid by another segment during the routine's execution.
If the asynchronous exit routine calls a routine in an overlay segment, that segment is already in storage and will not be overlaid by another segment during the called routine's execution.

Register information

On entry to the called program, the register contents are as follows:

Register: Contents
1: Address of the parameter list, if present
14: Return address
15: Entry address of the called program

Syntax

The standard form of the CALL macro is written as follows:

Syntax	Description

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

␢	One or more blanks must precede CALL.

CALL

␢	One or more blanks must follow CALL.

`entry name`	`entry name`: Symbol or register (2) - (12), (15).

,(`addr`)	`addr`: A-type address, or register (2) - (12).
,(`addr`),VL	Note: `addr` is one or more addresses, separated by commas. For example, (`addr,addr,addr`)

,PLIST4=YES	Default: None.
,PLIST4=NO

,PLIST8=YES	Default: None.
,PLIST8=NO

,PLIST8ARALETS=NO	Default: PLIST8ARALETS=NO
,PLIST8ARALETS=YES

,ID=`id nmbr`	`id nmbr`: Symbol or decimal digit, with a maximum value of 4095.

,LINKINST=`instruction`	Default: LINKINST=BALR

Parameters

The parameters are explained as follows:

entry name

Specifies the entry name to be given control. When a register is specified via (n), the contents of that register are put into register 15 prior to the linkage. When (15) is specified, the system assumes that the user has set register 15 so does not do so again.

,(addr)

,(addr),VL

Specifies an address or addresses to be passed to the called program. CALL expands each address inline to a fullword boundary and builds a parameter list with the addresses in the order specified. When the called program receives control, register 1 contains the address of the parameter list. If this parameter is not coded, register 1 is not altered.

When an AR mode caller uses either:

a parameter list with 4 bytes per entry; or
a parameter list with 8 bytes per entry and specifies PLIST8ARALETS=YES,

the addresses passed to the subtask are in the first part of the parameter list and their associated ALETs are in the second part. For a non-AR mode caller, or for an AR mode caller using a parameter list with 8 bytes per entry without PLIST8ARALETS=YES, ALETs are not passed in the parameter list. When ALETs are passed in the parameter list, the ALETs occupy consecutive 4-byte fields, whether the parameter list is 4 or 8 bytes per entry. See the description of the PLIST4 and PLIST8 keywords below for more information about controlling the bytes-per-entry in the parameter list. See the description of the PLIST8ARALETS keyword below for more information about ALETs and 8-bytes-per-entry parameter lists. See User parameters for an example of passing a parameter list in AR mode.

When using a 4-bytes-per-entry parameter list, specify VL when you pass a variable number of parameters. VL results in setting the high-order bit of the last address to 1. The 1 in the high-order bit identifies the last address parameter (which is not the last word in the list when the ALETs are also saved). When using an 8-bytes-per-entry parameter list, VL is not valid.

Note: If you specify only one address for PARAM= and you are not using register notation, you do not need to enter the parentheses.

,PLIST4=YES

,PLIST4=NO

,PLIST8=YES

,PLIST8=NO

Defines the size of the parameter list entries for a parameter list to be built by CALL based on the address or addresses to be passed to the called program.

PLIST4 and PLIST8 cannot be specified together. If neither is specified, the default is:

If running AMODE 64, PLIST8=YES
If not running AMODE 64, PLIST4=YES

If running AMODE 64 and PLIST4=YES is specified, the system builds a 4-bytes-per-entry parameter list just as it would if the program were running AMODE 24 or AMODE 31 and did not specify PLIST4 or PLIST8.

If running AMODE 24 or AMODE 31 and PLIST8 is specified, the system builds an 8-bytes-per-entry parameter list just as it would if the program were running AMODE 64 and did not specify PLIST4 or PLIST8.

,PLIST8ARALETS=NO

,PLIST8ARALETS=YES

If there is to be an 8-byte-per-entry parameter list and the invoker is in AR mode, indicates if the parameter list is also to contain the ALETs associated with the addresses. Otherwise, this parameter is ignored.

,PLIST8ARALETS=NO

Indicates that the 8-byte-per-entry parameter list is to consist of just the 8-byte addresses.

,PLIST8ARALETS=YES

Indicates that the 8-byte-per-entry parameter list is to consist of the following two parts:

All the 8-byte addresses,
All the associated ALETs in consecutive 4-byte fields.

,ID=id nmbr

Specifies a 2-byte identifier useful for debugging purposes only. The last fullword of the macro expansion is a NOP instruction containing the identifier value in bytes 3 and 4.

,LINKINST=instruction

Specifies the linkage instruction to use in this macro. The default is LINKINST=BALR.

Return and reason codes

The CALL macro does not generate any return codes. A return code in GPR 15 or AR 15 is placed there by the called program.

Example

Call the entry point contained in register 15, and pass three addresses to the control program.

CALL     (15),(ADDR1,ADDR2,ADDR3)