FETCH (Fetch a Phase) Macro

The macro loads and gives control to the phase specified in the first operand.

If the phase is in the SVA, it is not loaded into the partition, but control is given to the phase. For information about how to load phases into the SVA and how to write SVA-eligible (reenterable) phases refer to Understanding and Using z/VSE System Functions.

Note:

Both the expanded code and the parameter lists must be below 16 MB, otherwise the request is canceled.
The addresses are not validated by the macro expansion. Depending on the macro call, only 3 bytes of a passed 4-byte address might be passed to the SVC service. This might cause unpredictable results, since the address cannot be validated properly.

The AMODE bit in the PSW is updated depending on the AMODE attribute of the phase:

If AMODE=31, the phase gets control in AMODE 31.
If AMODE=24, the phase gets control in AMODE 24.
If AMODE=ANY, the phase gets control in the AMODE of its caller.

Restriction: The load point plus the size of the phase must be below the start of the GETVIS area.

Format

Requirements for the caller

AMODE:: 24 or 31
RMODE:: 24
ASC Mode:: Primary

Parameters

phasename | (S,address) | (1)

For phasename specify the name of the required phase. The address is regarded as either a 24-bit or 31-bit address, depending on the AMODE of the caller. If the caller has AMODE 31 and the address points to a storage location above 16 MB, the requestor is canceled.

If the DE operand is omitted or DE=NO is specified, the address as specified in (S,address) or as loaded into a register points to an 8-byte field that contains the phase name.

For DE=YES or DE=VSE or VSEFORM, the operand has a different meaning; refer to the discussion of the DE operand.

entrypoint | (S,entrypoint) | (0)

Control is passed to the address specified for entrypoint. This entry point overwrites the entry point determined a link-edit time. The entry point is regarded either as 24-bit or 31-bit address, depending on the AMODE of the caller, but since the phase must be located totally below 16 MB, an entry point above 16 MB is regarded as invalid. Apart from that, no further validity checking is done.

If this operand is not specified, control is passed to the entry point determined at link-edit time.

If entrypoint is given in register notation, register 1 must not be used. You preload the register with the entry-point address.

With S-type notation, the entry point is derived from base register and displacement, for example (S, offset (reg)). If, instead, a symbolic name is used for entrypoint, the macro expansion results in a V-type address constant. The entry point does not must be identified by an EXTRN statement.

LIST=listname | (S,listname) | (r1)

For listname specify the name of the local directory list that is generated in the partition by the GENL macro. When this operand is included, the system scans the local directory list for the required phase name before it initiates a search for this phase name in the directories of the accessible sublibraries.

If the phase has been found in the local directory list, general register 0 points to the related directory entry; otherwise, register 0 is set to zero.

The local directory list must be located below 16 MB (only 3 bytes are used in the macro expansion).

If LIST is specified, a specification of YES or VSE (or VSEFORM) for DE= is invalid.

SYS=YES

If this is specified, the system scans the system directory list (SDL) in the SVA and the system sublibrary before any private sublibraries. If the operand is omitted, the SDL and the private sublibraries are searched first.

DE=NO | YES | VSE | VSEFORM

By specifying DE=YES or DE=VSE | VSEFORM, you can generate your own local directory entry for a frequently used phase in order to save a time-consuming library directory search for that phase. A specification of YES or VSE|VSEFORM is invalid if LIST is specified.

DE=NO: Indicates that no local directory entry is to be generated.
DE=YES: Indicates a conventional 38-byte directory entry in the old librarian format (prior to VSE/Advanced Functions Version 2).
DE=VSE | VSEFORM: Indicates a 40-byte directory entry in the new librarian format (starting with VSE/Advanced Functions Version 2). VSE is a short form of VSEFORM.

For DE=YES or DE=VSE, the MAPDNTRY macro can be used to interpret the information that is returned by the FETCH (or LOAD) macro. Among other information, the local directory entry shows the AMODE/RMODE assigned to the phase. The directory entry must be located below 16 MB (see explanation for phasename).

The local directory entry is activated by the first FETCH request; all further FETCH requests are executed without any directory search.

If the first operand is written as phasename (instead of S-type or register notation), a directory entry is generated within the macro expansion. The generated directory entry contains the phasename in the first 8 bytes.

If you use S-type or register notation for the first operand, you must set aside the 38-byte (or 40-byte) field for the directory entry yourself and point to it via this operand. The directory entry must contain the phase name in the first 8 bytes (left-justified and padded with blanks) and have the following format:

For DE=YES:

    Byte    Contents
      0     CL8'PHASENAM'
      8     XL3'0'
     11     XL1' '     NO. OF HALFWORDS FOLLOWING
     12     XL26'0'

For DE=VSE | VSEFORM:

    Byte    Contents
      0     CL8'PHASENAM'
      8     XL3'FFFFFF'    ID FOR NEW FORMAT
     11     XL1' '         NO. OF HALFWORDS FOLLOWING
     12     XL28'0'

MFG=area | (S,area) | (r2)

The operand is required if the program, which issues the FETCH macro is to be reenterable. It specifies the address of a 64-byte dynamic storage area, that is, storage which your program obtained through a GETVIS macro. This area is required for system use during execution of the macro.

RET=NO | YES

By specifying RET=YES you can cause control to be returned to your program in any case (both in normal and error situations). Register 15 contains one of the following return codes:

Return Codes in Register 15

0

FETCH completed successfully.

4

Phase not found. This return code is also issued, if a user directory entry is found and the corresponding phase has already been deleted or re-cataloged.

8

Irrecoverable I/O error during FETCH processing.

12

Invalid library or sublibrary structure that is detected during FETCH processing.

16

Invalid address range that is detected during FETCH processing ─ Either of the following:

Local directory entry outside the partition.
Phase does not fit into the partition.
Entry point of phase is not below 16 MB. (In case RET=NO is specified, the program is canceled with 'invalid address'.)

20

Security violation.

24

Inconsistent user directory state: FETCH found an inconsistency between your program 's local directory entry and the corresponding entry in the directory of the related sublibrary. The local directory entry is overwritten by the entry that is read from the directory of the sublibrary. FETCH checks the following:

Length of phase
Relocation state
Difference between the load point and the partition-start address
Difference between the load point and the entry point

28

Partition is too small (or phase does not fit into the logical transient area).