This general macro can be used to lock E-type programs in storage or to
retrieve information on an E-type program. GETPC inspects the program
allocation table (PAT) to determine if a program needs to be retrieved from
file in order to lock it into storage. When the file resident program
is no longer needed, it should be unlocked using the RELPC macro. A
core resident program cannot be unlocked once a GETPC is issued.
A program's file or storage address can also be obtained from the PAT
and returned.
Format
- label
- A symbolic name can be assigned to the macro statement.
- prog
- The name of the program that is to be locked in storage or located.
- NAME
- Besides using a positional parameter, the name of the program can also be
provided using the NAME parameter.
- Note:
- Either the prog parameter or the NAME parameter must be specified for
E-type programs. These parameters are optional for C-type
programs. If neither the prog or NAME parameter is specified for C-type
programs, only a dsect for the GETPC parameter list is generated.
- prog
- The name of the program that is to be locked in storage or located.
- (Rx)
- A register (R0-R7) that contains the name of the program that is to be
locked in storage or located.
- LOADSET=Rw
- A register (R1-R7) that contains the address of an 8-byte character
string. This character string is left justified, padded with blanks,
and specifies the name of the loadset that contains the version of the program
that is to be locked in storage or located.
If the character string contains all blank characters or if you do not
specify this parameter, the version of the program associated with the
requesting ECB is locked in storage or located. In this case, the name
of the loadset that contains the version of the program associated with the
requesting ECB is placed in the 8-byte character string.
- Note:
- This option requires Restricted authorization.
- LOCK
- An option that specifies whether or not the program will be locked in
storage.
- YES
- The requested program will be locked in storage. This is the
default.
Programs allocated as PRIVATE can not have locks set.
- NO
- The requested program will not be locked in storage. When LOCK=NO,
FILE or CORE must be coded.
- SPECIAL
- Specifies whether or not the program is to have the special lock indicator
set.
Special locks set by GETPC must be unlocked using UNLOCK=SPECIAL in the
RELPC macro. Programs allocated as PRIVATE can not have special locks
set.
Programs locked through ZAPGM and ZRPGM have the special lock indicator
set.
- Note:
- This option requires Restricted authorization.
- FILE
- An optional data level (D0-DF) whose File Address Reference Word (FARW)
will receive the file address of the requested program.
When the FILE parameter is used, LOCK=NO should also be specified (to
override the default of LOCK=YES). Without the LOCK=NO specification
serious main storage depletion may result.
- Dx
- Data level index (D0-DF).
- (Ry)
- A register (R0-R7) which contains the data level index. Can not be
the same as coded for Rx above.
- CORE=Rz
- An optional register (R0-R7) that will receive the storage address of the
requested program.
- ERROR=label1
- This optional label specifies a location where control is transferred if
the program name being requested either cannot be found, was allocated as
PRIVATE or already had a special lock indicator set. Register R15 will
contain an error code indicating the type of error.
- IDLOC
- An option that specifies whether the request will be serviced using the
program base ID or the data base ID.
- PBI
- The request will be serviced using the program base ID located in the
entry control block field CE1PBI. This is the default.
- DBI
- The request will be serviced using the data base ID located in the entry
control block field CE1DBI. IDLOC=DBI is not valid when coded with
LOCK=YES.
Entry Requirements
R9 must contain the address of the ECB being processed.
Return Conditions
- Control is returned to the next sequential instruction (NSI).
- The register specified by the CORE keyword will contain the storage
address of the requested program, with the following exception. When
LOCK=NO, the register specified by the CORE keyword will return with 0 if the
program is not already in storage, or the program is in storage and allocated
as Private.
- The content of R14 and R15, except on an error condition when ERROR is
coded, is unknown. The remaining operational registers are saved during
the execution of the GETPC macro.
- If FILE was coded, then the specified FARW will be initialized with the
program records generic ID and file address.
- If ERROR was coded and an error occurs, the indicated error routine is
executed. Also, register R15 will contain an error indicator
code. The following tags
are generated by the GETPC macro and should be used for interrogating this
error code:
IG_LS_ERR - The specified version of the program was not found.
IG_NF_ERR - The requested program was not found.
IG_PP_ERR - The requested program was allocated as PRIVATE.
IG_RT_ERR - A program retrieval error has occurred.
IG_SL_ERR - The SPECIAL lock indicator is already set.
- Note:
- For special lock errors, processing will still return the requested data to
the user.
Programming Considerations
- This macro can be executed on any I-stream.
- Only one program at a time may be locked through this macro.
Separate requests must be made for each program required.
- GETPC may be called with parameters to get a program or without parameters
to generate a dsect. GETPC with parameters is primarily meant for
E-type programs. A GETPC call with parameters generates an SVC.
Consequently, C-type programs implementing SVC service routines should not use
GETPC to get a program. C-type programs executing in problem state in
an EVM space, however, may use GETPC to get a program. When C-type
programs use GETPC to get programs, the NAME parameter must be used to specify
the program name. The dsect provides labels for the GETPC parameter
list and is used only by C-type programs.
- This macro does not attach the program to any ECB.
- GETPC will bring either core resident or file resident programs into
storage.
- Private programs may not be locked in storage. When the requested
program is allocated as PRIVATE and either LOCK=YES or LOCK=SPECIAL, a system
error will result if ERROR is not coded.
- If LOCK=YES
- and the specified program is file resident, then the program remains in
storage until the RELPC macro is issued.
- and the specified program is core resident, then the program is in storage
and will remain there until the next IPL.
- If LOCK=SPECIAL
- and the program is file resident, it will be locked into a common
block. If the program is already in storage other than a common block
it will be moved to a common block. The special indicator will be
set. The common block will remain in storage until a RELPC
UNLOCK=SPECIAL macro is issued.
- and the program is in VFA, the program is moved to a common block.
- The SPECIAL lock will only be set once. Additional SPECIAL lock
requests will return the error indicator IG_SL_ERR.
Examples
None.