Invoking SPZAP dynamically

You can run SPZAP from selected macros. SPZAP can be invoked by an application program at run time through the use of the CALL, LINK, XCTL, or ATTACH macro. The program must supply a list of alternate DDNAMEs of data sets to be used by SPZAP if the standard DDNAMEs are not used.

A program must be running APF authorized in order to update a VTOC through SPZAP. Other SPZAP functions do not require the calling program to be authorized.

The following diagram shows the general form of these macros when used to invoke SPZAP.

(anyname)   CALL AMASPZAP,(oplist,ddnamlst),VL
(anyname)   XCTL EP=AMASPZAP
(anyname)   LINK EP=AMASPZAP,PARAM=(oplist,ddnamlst),VL=1
(anyname)   ATTACH EP=AMASPZAP,PARAM=(oplist,ddnamlst),VL=1

anyname

Indicates an optional statement label on the macro statement.

EP

The entry point for the SPZAP program.

PARAM

Specifies, as a sublist, parameters to be passed from the program to SPZAP.

oplist

Specifies the name of either a halfword of zeros (indicating no options) or a non-zero halfword followed by a character string whose length is given in bytes. For the possible parameter value, see the information about the EXEC statement in JCL statements.

ddnamlst

Specifies the name of a variable-length list containing alternate ddnames for data sets to be used during SPZAP processing. If all the standard ddnames (SYSPRINT, SYSLIB, and SYSIN) are used, then you can omit this parameter.

The DDNAME list must begin on a halfword boundary. The first two bytes contain a count of the number of bytes in the rest of the list. The format of the list is fixed, with each entry having eight bytes. Any name of less than eight bytes must be left justified and padded with blanks. If a name is left out in the list, the entry must contain binary zeros; the standard name is then assumed. Names can be omitted from the end of the ddname list by shortening the list.

The sequence of 8-byte entries in the list is as follows:

Entry

Standard name

0-7

not applicable

8-15

not applicable

16-23

not applicable

24-31

SYSLIB

32-39

SYSIN

40-47

SYSPRINT

VL | VL=1

Indicates that the high-order bit is to be set to 1 in the last word of the address parameter list.

Note: If you do not supply the name of a DDNAME list, you must ensure that the high-order bit of the oplist address is set on. Coding VL|VL=1 sets the bit correctly.

Figure 1 is an example of two functionally-equivalent dynamic invocations of SPZAP.

         EXSPZAP  CSECT
         USING *,15            ASSUME REG15 IS BASE
         MODID                 MODULE ID AND DATE IN PROLOG
         SAVE  (14,12)         SAVE REGISTERS
         BALR  12,0            ESTABLISH BASE REGISTER
         USING *,12
         ST    13,SAVEAREA+4   CHAIN NEW SAVEAREA TO PREVIOUS
         LR    2,13            TEMPORARILY SAVE ADDRESS OF OLD SAVEAREA
         LA    13,SAVEAREA     INIT REG13 WITH ADDRESS OF NEW SAVEAREA
         ST    13,8(0,2)       CHAIN PREVIOUS SAVEAREA TO NEW
*************************************************************************
*                                                                       *
*   THIS EXAMPLE SHOWS TWO FUNCTIONALLY EQUIVALENT DYNAMIC              *
*   INVOCATIONS OF SPZAP.                                            *
*           NO OPTIONS ARE PASSED.                                      *
*           THE DDNAME FOR THE SYSLIB FILE IS CHANGED TO TESTLIBR.      *
*           THE DDNAME FOR THE SYSIN FILE IS NOT CHANGED.               *
*           THE DDNAME FOR THE SYSPRINT FILE IS CHANGED TO PRINTOUT.    *
*                                                                       *
*************************************************************************
LINKZAP1 LINK  EP=AMASPZAP,PARAM=(OPTLIST,DDLIST),VL=1
LINKZAP2 LINK  EP=AMASPZAP,PARAM=(0,DDLIST),VL=1
         L     13,SAVEAREA+4   LOAD ADDRESS OF PREVIOUS SAVEAREA
         RETURN (14,12),T,RC=0 RETURN TO CALLER
OPTLIST  DC    H'0'            NO OPTIONS ARE PASSED TO AMASPZAP
DDLIST   DS    0H              ALIGN DDNAMES TO HALFWORD BOUNDARY
         DC    H'48'           LENGTH OF THE CHARACTER STRING
*                               CONTAINING DDNAME OVERRIDES
         DC    24XL1'00'       FIRST 24 CHARACTERS ARE IGNORED
         DC    CL8'TESTLIBR'   CHANGE SYSLIB FILE TO DDNAME OF TESTLIBR
         DC    8XL1'00'        USE SYSIN FILE FOR INPUT OF CONTROL
*                               STATEMENTS
         DC    CL8'PRINTOUT'   CHANGE SYSPRINT FILE TO DDNAME OF
*                               PRINTOUT
SAVEAREA DC    18F'0'          REGISTER SAVEAREA
         END