The IEFPPSCN macro provides a way to retrieve information, for report generation, about programs that are listed in the program properties table (PPT). IEFPPSCN allows the calling program to scan each entry in the PPT or to search the PPT for a specific program.
The installation controls what programs are listed in the PPT. An installation can specify a list of programs that require special attributes by using the SCHEDxx parmlib member with the PPT statement. The system then creates entries for these programs in the PPT. See z/OS MVS Initialization and Tuning Reference for information about using the SCHEDxx parmlib member.
The contents of the PPT can be dynamically changed through the SET command. Using the IEFPPSCN macro to retrieve information from the PPT prevents the system from dynamically updating the PPT while you are scanning it. If you scan the PPT without using IEFPPSCN, and the system updates the PPT while you are scanning it, your program will abnormally end.
Requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Supervisor state and PSW key 0 |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN |
AMODE: | 24- or 31-bit |
ASC mode: | Primary |
Interrupt status: | Enabled or disabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | Must be in the primary address space |
None.
After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the caller issued the macro. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.
None.
The standard form of the IEFPPSCN macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede IEFPPSCN. |
IEFPPSCN | |
␢ | One or more blanks must follow IEFPPSCN. |
REQUEST=RETRIEVE | |
REQUEST=NEXT | |
REQUEST=END | |
,PPTINFO=ppt_info | ppt_info: RX-type address or register (2) - (12). |
Required for REQUEST=RETRIEVE and REQUEST=NEXT. Not valid for REQUEST=END. | |
,PROGRAM= | program_name: RX-type address or register (2) - (12). |
program_name | |
Required for REQUEST=RETRIEVE. | |
Not valid for REQUEST=NEXT or REQUEST=END. | |
,TOKEN=token | token: RX-type address or register (2) - (12). |
Required for REQUEST=NEXT and REQUEST=END. | |
Not valid for REQUEST=RETRIEVE. | |
,RETCODE=rc | rc: RX-type address or register (2) - (12). |
The parameters are explained as follows:
Specify REQUEST=RETRIEVE to request information about a specific program. You must specify the name of the program on the PROGRAM parameter. You must also specify the PPTINFO parameter. Do not specify the TOKEN parameter.
If you want to scan all program entries sequentially, use the REQUEST=NEXT parameter together with the REQUEST=END parameter. Each time you specify REQUEST=NEXT, the system retrieves information about the next program entry. The first time you specify REQUEST=NEXT, you must put zero in the field you provide on the TOKEN parameter. On return to the caller, the system places a value in this field. After the first call, when you specify REQUEST=NEXT you must specify TOKEN and supply the value provided by the system on the previous call. With REQUEST=NEXT, you must also specify the PPTINFO parameter. Do not specify the PROGRAM parameter.
When control returns to the calling program with a return code of 4 in GPR 15, you have reached the end of the table and must then specify REQUEST=END. If you use REQUEST=NEXT and do not specify REQUEST=END, the system might not free common storage that could have been freed.
When you specify REQUEST=END, you must also specify the TOKEN parameter, supplying the value returned on the last REQUEST=NEXT. Do not specify the PROGRAM or PPTINFO parameters.
Upon return, the system places the length of the requested PPTENTRY in the first two bytes of the area, and places the requested PPTENTRY itself in the remainder of the area.
This area must have a storage key that matches the PSW key of the issuer of IEFPPSCN. If the area provided is too small, the information is truncated. PPTINFO is required for REQUEST=RETRIEVE and REQUEST=NEXT. Do not specify PPTINFO with REQUEST=END.
Do not specify PROGRAM with REQUEST=NEXT or with REQUEST=END.
Do not specify TOKEN with REQUEST=RETRIEVE.
When control returns from IEFPPSCN, GPR 15 (and rc, if you coded RETCODE) contains one of the following return codes:
Hexadecimal Return Code | Meaning and Action |
---|---|
00 | Meaning: Program found. Action: No action required. |
04 | Meaning: End of table. Action: Issue IEFPPSCN with REQUEST=END. |
08 | Meaning: The program name you specified
is not listed in the PPT, indicating that the installation did not
specify any special attributes for that program. Action: No action required. |
0C | Meaning: The token passed was not the token
created by this macro. Action: Check that the application is coded to pass the correct token. |
10 | Meaning: Request not valid. Action: Check that you did not change the expanded assembler code. |
14 | Meaning: System error. The system was
not able to obtain the required storage. Your program might issue
a message indicating incomplete scanning of the PPT. Action: Reissue the request. If the error persists, contact your IBM® support personnel. |
Sequentially scan the PPT and write the program name of each entry to the console. In your own code, you might wish to format the non-EBCDIC portions of the PPT entry for inclusion in the WTO.
The code in this example is nonreentrant. The caller is APF-authorized, and is initially in problem state with PSW key 8. The caller changes to supervisor state with PSW key 0 before issuing IEFPPSCN, and returns to problem state with PSW key 8 on completion of processing.
TITLE 'SHOWPPT - Show all entries in Current PPT'
SHOWPPT CSECT Module entry point
SHOWPPT AMODE 31
SHOWPPT RMODE ANY
*
* Body of nonreentrant module which prints program names in the PPT
*
STM 14,12,12(13) Standard module linkage
LR 12,15
USING SHOWPPT,12
ST 13,SAVEAREA+4
LR 2,13
LA 13,SAVEAREA
ST 13,8(2)
*
MODESET MODE=SUP,KEY=ZERO Need supervisor state, key 0
*
* Set up for looking at PPT entries
*
LA 2,PPTENT Point to copy of PPT entry
USING PPTENTRY,2 Set up addressability
XC SCNTOKEN,SCNTOKEN Clear token
*
LOOP DS 0H Loop getting PPT entries
IEFPPSCN REQUEST=NEXT,TOKEN=SCNTOKEN,PPTINFO=PPTE
LTR 15,15 Check whether entry was returned
BNZ ENDLOOP
MVC TEXT2(8),PPTNAME Copy program name to message
WTO TEXT=ENTRYTXT
B LOOP Get next entry, if any
*
ENDLOOP DS 0H Finished with PPT
IEFPPSCN REQUEST=END,TOKEN=SCNTOKEN
MODESET MODE=PROB,KEY=NZERO Return to problem state
*
* Return to the calling program with the return code last passed by
* IEFPPSCN.
*
L 13,SAVEAREA+4 Return linkage
L 14,12(13)
LM 0,12,20(13)
BR 14
*
**** Local storage definitions ****
SCNTOKEN DC A(0) PPT scan token
PPTE DC AL2(L'PPTENTRY) Length of a PPT entry
PPTENT DS CL(L'PPTENTRY) PPT entry return area
SAVEAREA DC 18F'0'
*
* The following areas are used to print the program name within the
* PPT. Additional formatting is required to make all the
* information readable.
*
ENTRYTXT DS 0F Area for printing
TEXTL DC H'32' Message length
TEXT1 DC C'SHOWPPT: Program Name = ' Constant portion of message
TEXT2 DS CL8 Variable portion (program name)
*
* The following mapping macros are required for the IEFPPSCN macro.
*
CVT DSECT=YES
IEFJESCT
IEFZB610
END SHOWPPT End of SHOWPPT