GETPC–Fetch program into memory

Use this general macro to fetch a program into memory.

Last updated

Changed for PUT10.
Changed for PUT09.
Changed for PUT07.
Changed for PUT05 (information only; no code change).
Changed for PUT00.

Format

label

is a symbolic name that can be assigned to the macro statement.

progname

is the 4-character alphanumeric name of a program or BAL shared object (BSO) entry point.

NAME

specifies the name of a program or BSO entry point, where:

progname: is the 4-character alphanumeric name of the program or BSO entry point.
(reg1): is a register (R0–R7) that contains the 4-character alphanumeric name of the program or BSO entry point.

LOCK

specifies whether a program is permanently locked in core resident program area (CRPA) storage. If a program is permanently locked in CRPA storage, the CRPA sweeper cannot sweep the program from storage. Specify one of the following options:

NO: specifies that the program is not permanently locked in CRPA storage and can be swept by the CRPA sweeper.
YES: specifies that the program is permanently locked in CRPA storage and cannot be swept by the CRPA sweeper.
SPECIAL: specifies that the program is permanently locked in CRPA storage and cannot be swept by the CRPA sweeper.

FETCHONLY

specifies whether a program is fetched into memory by using dynamic linkage, where:

NO: specifies that dynamic linkage occurs when the program is fetched into memory.
YES: specifies that the program is fetched into memory that is deferring dynamic linkage until run time.
Note: This option is reserved for IBM® use.

LOADSET=reg2

specifies the address of an 8-byte character string, where reg2 is a register (R1 – R7). This character string is left-aligned, padded with blanks, and specifies the name of the loadset that contains the version of the program to fetch into memory. To fetch the base version of the program into memory, specify BASE. If you specify this parameter with a value of other than BASE, the loadset must be active.

If the character string contains all blank characters, or if this parameter is not specified, the version of the program that is associated with the requesting entry control block (ECB) is fetched into memory. In addition, the name of the loadset that contains the version of the program that is associated with the requesting ECB is placed in the 8-byte character string.

Note: This parameter requires restricted authorization.

ADDR=reg3

specifies the register that receives the address of the program that is fetched into memory, where reg3 is a register (R0 – R7). For data programs the address is the start of the data. For all other programs it is the address of the program fetch block that precedes the program.

IDLOC

specifies whether the request is serviced by using the program base ID or the database ID.

PBI: specifies that the request is serviced by using the program base ID that is in the CE1PBI field of the ECB.
DBI: specifies that the request is serviced by using the database ID that is in the CE1DBI field of the ECB.

ERROR=label1

specifies the location to which control is given if the program cannot be fetched into memory. If this parameter is not specified and the program cannot be fetched into memory, a dump is issued.

Entry requirements

R9 must contain the address of the ECB being processed.

Return conditions

If the name of a BSO entry point is specified, the BSO (or program) containing that BSO entry point is fetched into memory.
Control is returned to the next sequential instruction (NSI) if the program is fetched into memory. If the program is not fetched into memory, control is given to the label specified for the ERROR parameter, and R15 contains one of the following error codes:

IG_LS_ERR

The specified version of the program was not found.

IG_NF_ERR

The specified program was not found.

IG_RT_ERR

An error occurred while program is fetched into memory.

IG_31_ERR

A program that is running in 31–bit addressing mode requested the address of a program that resides above the 2 GB bar.

If an error occurs and the ERROR parameter is not specified, the z/TPF system issues a dump.
The contents of R14 and R15 are unknown, except if an error occurs and the ERROR parameter was specified. The contents of all the other registers are preserved, except for the register that is specified for the ADDR parameter.
If the program is not in memory already, it is fetched into memory.

Programming considerations

For information about macro register conventions, see Register conventions.
This macro can be run on any I-stream.
The GETPC macro does not return the address of a subsystem-shared program if the ECB is running in a non-BSS subsystem. If you want to fetch a subsystem-shared program or obtain its address from a program that is running a non-BSS subsystem, use the CEBIC macro to switch to the BSS subsystem, then use the DBI parameter on the GETPC macro.
For compatibility purposes, you can specify the CORE parameter with the GETPC macro on the z/TPF system. However, it is recommended that you use the ADDR parameter.
The GETPC macro must be running in 64-bit mode to fetch the address of programs that are above the 2 GB bar into memory.

Examples

The following example fetches (if it is not fetched already) program ABCD, which is associated with loadset TESTLOAD, into memory and returns its address in R4. If an error occurs during GETPC macro processing, a jump to label ERRORS occurs.

*         return in R4, the address of the program pointed to by R5
*                     if an error occurs, jump to label 'ERRORS'
           LA          R5,=C'ABCD'
           LA          R6,=C'TESTLOAD '
           GETPC NAME=(R5),ADDR=R4,LOADSET=R6,ERROR=ERRORS

The following example fetches the program that is referenced by R6 into memory and places its address into R5. The Data Base ID that is used to locate the program is in field CE1DBI. If an error occurs during GETPC processing, a SERRC general macro is issued because the ERROR parameter was not specified.
```
*         return in R5, the address of the program pointed to by R6
*                     use the Data Base ID located in CE1DBI
           getpc name=(r6),addr=r5,idloc=dbi
```

Related information

None.