CALL description
- 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.
- 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
- 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 without specifying PLISTARALETS=NO; or
- a parameter list with 8 bytes per entry and specifies PLIST8ARALETS=YES,
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.
- ,PLISTARALETS=SYSTEM
- ,PLISTARALETS=NO
- If the invoker is in AR mode, indicates whether the parameter
list is also to contain the ALETs associated with the addresses. If
the invoker is not in AR mode, this parameter is ignored.
- ,PLISTARALETS=SYSTEM
- Indicates to follow the default system rules that for an AR mode
invoker:
- For AMODE 24/31, the parameter list is also to contain the ALETs.
- For AMODE 64 with PLIST8ARALETS=YES, the parameter list is also to contain the ALETs.
- For other cases, the parameter list is not to contain the ALETs.
- ,PLISTARALETS=NO
- Indicates that the parameter list is not also to contain the ALETs. Do not specify this parameter with PLIST8ARALETS=YES.
- ,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 (15),(ADDR1,ADDR2,ADDR3)