Description

Requirements for the caller are:

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:

The parameters are explained as follows:

REQUEST=RETRIEVE

REQUEST=NEXT

REQUEST=END

The required parameter that specifies what kind of request the caller is making.

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.

,PPTINFO=ppt_info

Specifies the area provided by the caller to contain the requested program information. The caller must provide this area as follows:

• The length of the area must be the length of the PPTENTRY field of the PPT plus two bytes. The PPT is mapped by the IEFZB610 mapping macro. See PPT in z/OS MVS Data Areas in the z/OS Internet library for the PPT mapping.
• Initialize the first two bytes of the area to the length of the PPTENTRY field.
• Define the length of the remainder of the area to be equal to the length of the PPTENTRY field.

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.

,PROGRAM=program_name

Specifies the 8-character field containing the name of the program you want to retrieve when you specify REQUEST=RETRIEVE. If the program name is less than 8 characters, left justify the name and pad on the right with blanks.

Do not specify PROGRAM with REQUEST=NEXT or with REQUEST=END.

,TOKEN=token

Specifies the 4-byte field to contain the token that the system returns when you specify REQUEST=NEXT. Set the value of the token to zero before the first call. On subsequent calls made with REQUEST=NEXT or REQUEST=END, use the value of the token returned by the system on the previous REQUEST=NEXT.

Do not specify TOKEN with REQUEST=RETRIEVE.

,RETCODE=rc

Specifies the location where the system is to store the return code. The return code is also in GPR 15.

When control returns from IEFPPSCN, GPR 15 (and rc, if you coded RETCODE) contains one of the following return codes:

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