PDSUTIL - Multi-Function Utility Program for PDS Members and Libraries

                 
 

Overview

PDSUTIL is a multi-function utility program designed as a high-performance replacement for IEBUPDTE, IEBCOPY, and other utility programs or on-line utility functions commonly used to load or update partitioned data sets. PDSUTIL runs as a batch program in the MVS/ESA, OS/390 and z/OS environment. To preserve the integrity of updated data sets, PDSUTIL uses the same protection scheme as that used by ISPF, the linkage-editor or IMS utility programs.

PDSUTIL processes PDS data one track at a time and writes short blocks to maximise track usage and reduce disk space requirements. Because it uses the EXCP access method, PDSUTIL provides limited support for PDSEs which are only supported for SYSIN (LOAD function), SELDD and EXCLDD..

           

Executing PDSUTIL

PDSUTIL is entirely controlled via the PARM field of the EXEC statement and does not use control cards. As a result, a PDSUTIL invocation can only perform a single function. However, it is possible to perform several PDSUTIL functions in a single TMP job step (TSO Batch); see example below.

The format of the PARM field is as follows:

	PARM=(function<,options>) 

FUNCTIONS

The function is mandatory and must be specified at the beginning of the PARM field. The functions supported by PDSUTIL are:

OPTIONS

Options are optional and must followed the function in the PARM field, using the comma as a separator.

SPF Statistics on ./ ADD cards

Input to the LOAD function may be in PDSLOAD or STARTOOL format, where SPF statistics present on the ./ ADD cards are loaded into the corresponding directory entries. The two formats, which only differ in the length of the Julian dates they contain, are shown below:

  1. PDSLOAD format (5-digit date)
    	         1         2         3         4         5         6         7
    	123456789012345678901234567890123456789012345678901234567890123456789012
    	./ ADD NAME=<member> 0101-95027-98130-1551-00096-00048-00082-MVSCONV 
  2. STARTOOL format (7-digit date)
    	         1         2         3         4         5         6         7
    	123456789012345678901234567890123456789012345678901234567890123456789012
    	./ ADD NAME=<member> 0101-1995027-1998130-1551-00096-00048-00082-MVSCONV 

Notes:

Protection of the output PDS with ENQ

PDSUTIL protects the output PDS using standard ENQ conventions. When RECFM=F (or FB) or RECFM=V (or VB), PDSUTIL uses the same ENQ/DEQ rules as ISPF. When RECFM=U (generally, a load-library), PDSUTIL uses the same rules as the MVS linkage-editor or Binder, unless the IMS option is specified, in which case it uses the same ENQ/DEQ rules as IMS utility programs. Using these types of ENQ allows a PDS to be updated when it is allocated with DISP=SHR, which is much safer than the well-known dangerous situation which exists with several IBM utility programs, such as IEBCOPY or IEBUPDTE.

COPY function with STATS option

When the STATS option is used in conjunction with the COPY function, SPF statistics that exist in the input PDS are ignored. When the input members are in PACKED format, the number of lines (init and current) is the number of packed records, except when the PACK=OFF option is also specified.

Member Selection using the SELDD and EXCLDD data sets

The optional SELDD and EXCLDD data sets contain lists of member names used to limit processing to specified members. Member lists may be specified in three different formats:

  1. as a sequential data set, containing member names in pos 1 through 8 of each record. Several sequential data sets or PDS members may be concatenated to form the list. The sequential data set can contain variable-length records, including short ones. Example:
    	1.......9..........
    	//SELDD  DD  *
    	ABCDEF
    	XDSFHHR
    	CDDDEEEE
    	QQQQQQQQ
    	/* 
  2. as a partitioned data set; MBRLIST reads the PDS directory and internally builds a member list. Concatenation is supported. Example:
    	1.......9..........
    	//EXCLDD  DD  DSN=PRISMCS.LOCAL.VASMMAC,DISP=SHR
    	//	  DD  DSN=PRISMCS.LOCAL.VASMCOP,DISP=SHR 
  3. as a combination of #1 and #2 above. The sequential data set contains member names and indirect specification of PDS directories via the DDN key-word. Example:
    	1.......9..........
    	//SELDD   DD  *
    	MEMBER1		member name
    	DDN=ASMLIB	ddname of a PDS
    	MEMBER2 	member name
    	//	  DD  DSN=PRISMCS.LOCAL.USERLIB(MYLIST),DISP=SHR
    	//*
    	//ASMLIB  DD  DSN=PRISMCS.LOCAL.VASMMAC,DISP=SHR
    	//	  DD  DSN=PRISMCS.LOCAL.VASMCOP,DISP=SHR 

Notes:

JCL Examples

Reset the SYSUT2 PDS to empty, then LOAD members from an IEBUPDTE-style input data set.

	//LOADPROC EXEC PGM=PDSUTIL,PARM='LOAD,RESET'
	//SYSPRINT  DD   SYSOUT=*
	//SYSIN     DD        ....... IEBUPDTE-style input
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VSEPROCS,DISP=SHR 

LOAD members from IEBUPDTE-style input, set SPF statistics for loaded members, replace like-named members.

	//LOADJCL  EXEC PGM=PDSUTIL,PARM=(LOAD,REPLACE,STATS)
	//SYSPRINT  DD   SYSOUT=*
	//SYSIN     DD        ....... IEBUPDTE-style input
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.MVSJCL,DISP=SHR 

UNLOAD members whose names start with ABC from the SYSUT1 PDS to SYSUT2 as a sequential data set in IEBUPDTE/PDSLOAD input format.

	//UNLOAD   EXEC PGM=PDSUTIL,PARM='UNLOAD,MEMBER=ABC*'
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT1    DD   DSN=PRISMCS.LOCAL.MVSJCL,DISP=SHR
	//SYSUT2    DD        ....... IEBUPDTE/PDSLOAD format 

SCRATCH all the members whose name starts with 'PAW'.

	//SCRPAW   EXEC PGM=PDSUTIL,PARM='SCRATCH,MEMBER=PAW*'
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.LOADLIB,DISP=SHR 

Scratch SYSUT2 members that are present in a concatenation of libraries, specified with the 'SELECT' ddname, except those that start with 'PAWP'.

	//SCRMOD   EXEC PGM=PDSUTIL,
	//  PARM=(SCRATCH,'EXCLUDE=PAWP*,SELDD=SELECT')
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.LOADLIB,DISP=SHR
	//SELECT    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR
	//          DD   DSN=PRISMCS.LOCAL.LOADLIB,DISP=SHR 

Copy all the GSF* load-modules (but two) to a VIO data set:

	//COPYVIO  EXEC PGM=PDSUTIL,
	//  PARM=(COPY,'SELECT=GSF*,EXCLDD=EXCLUDE')
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT1    DD   DSN=PRISMCS.LOCAL.LOADLIB,DISP=SHR
	//SYSUT2    DD   DSN=&&TEMPLOAD,DISP=(,PASS),UNIT=VIO,SPACE=(CYL,(5,,25))
	//EXCLUDE   DD   *
	GSF2PZSM
	GSF2PSCR 

Move members according to an inclusion list; do not copy PXY0855 nor any member already present in SYSUT2.

	//MOVECOB  EXEC PGM=PDSUTIL,
	//  PARM='MOVE,NOREPLACE,SELDD=INCLUDE,EXCLUDE=PXY0855'
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT1    DD   DSN=CUSTOMER.INPUT.COBOL,DISP=SHR
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR
	//INCLUDE   DD   DSN=PRISMCS.LOCAL.TABLES(NREFXX),DISP=SHR 

Compress a PDS

	//COMPRESS EXEC PGM=PDSUTIL,PARM=COMPRESS
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR 

COMPRESS a PDS and delete some members at the same time

	//COMPRDEL EXEC PGM=PDSUTIL,PARM='COMPRESS,EXCLDD=DD2'
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR
	//DD2       DD   DSN=PRISMCS.LOCAL.TABLES(NREFCM),DISP=SHR 

COPY a PDS and unpack the members

	//COMPRDEL EXEC PGM=PDSUTIL,PARM='COPY,PACK=OFF'
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT1    DD   DSN=CUSTOMER.PACKED.COBOL,DISP=SHR
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR 

LOAD duplicate members under the names ZZZZ0001 through ZZZZ9999.

	//LOADDUPL EXEC PGM=PDSUTIL,PARM='LOAD,DUPLICATES=ZZZZ'
	//SYSPRINT  DD   SYSOUT=*
	//SYSIN     DD        ....... IEBUPDTE-style input
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR 

LOAD members and rename some of them

	//LOADDUPL EXEC PGM=PDSUTIL,PARM='LOAD,RENDD=NEWNAMES'
	//SYSPRINT  DD   SYSOUT=*
	//SYSIN     DD        ....... IEBUPDTE-style input
	//SYSUT2    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR
	//NEWNAMES  DD   *
	MEM1     NEWNAME1
	MEM2     NOUVEAU2 

Generate a directory list on SYSUT2 of all M* members except MEM1 & MEM2

	//LOADDUPL EXEC PGM=PDSUTIL,PARM='LISTDIR,SELECT=M*,EXCLDD=EXCLDD'
	//SYSPRINT  DD   SYSOUT=*
	//SYSUT1    DD   DSN=PRISMCS.LOCAL.VCBLMOD,DISP=SHR
	//SYSUT2    DD   SYSOUT=*
	//EXCLDD    DD   *
	MEM1
	MEM2 

Execute two PDSUTIL functions in a single job step

	//MULTIPLE EXEC PGM=IKJEFT01
	//SYSTSPRT  DD   SYSOUT=*
	//SYSPRINT  DD   SYSOUT=*
	//OUTPDS1   DD   DSN=PRISMCS.LOCAL.MCBLMOD,DISP=SHR
	//OUTPDS2   DD   DSN=PRISMCS.LOCAL.MCBLCOP,DISP=SHR
	//SYSTSIN   DD   *
	CALL *(PDSUTIL) 'RESET,OUTDD=OUTPDS1'
	CALL *(PDSUTIL) 'RESET,OUTDD=OUTPDS2' 

Messages

The following is a list of all the messages that may be written to SYSPRINT by PDSUTIL. Please see below for a sample SYSPRINT report.

PU001I FUNCTION REQUESTED: <function>, ADDITIONAL OPTIONS: NONE

PU002I FUNCTION REQUESTED: <fun ctions>, ADDITIONAL OPTIONS: <options>

PU003E SYNTAX ERROR IN PARAMETER FIELD: <parm>.

PU004E FUNCTION <function> IS UNKNOWN.

PU005E OPTION <option> IS UNKNOWN.

PU006E OPTION <option> DOES NOT APPLY TO FUNCTION <function>.

PU007E INVALID LENGTH FOR OPTION <option>.

PU008E DUPLICATE OR CONFLICTING <option> OPTION.

PU011I <data set attributes for SYSIN>

PU012I <data set attributes for RENDD>

PU013I <data set attributes for RENAMES>

PU014I <data set attributes for SELDD>

PU015I <data set attributes for EXCLDD>

PU021I INPUT DATA SET IS DDNAME=<ddname>,DSNAME=<dsname>,VOL=33x0=<volser>

PU022I OUTPUT DATA SET IS DDNAME=<ddname>,DSNAME=<dsname>,VOL=33x0=<volser>

PU023I BACKUP DATA SET IS DDNAME=<ddname>,DSNAME=<dsname>,VOL=33x0=<volser>

PU025E <ddname> VALIDATION ERROR:
					CONCATENATION NOT ALLOWED
					DD MISSING
					DSORG IS NOT PO
					ERROR IN IEFEB4UV
					INCONSISTENT DCB SUBPARAMETERS
					INVALID LRECL/RECFM/BLKSIZE OVERRIDE
					NON-DASD DEVICE
					NON-ZERO KEYLEN OR TRACK OVERFLOW
					NULL RECFM AND/OR BLKSIZE
					OBTAIN FAILED
					OPEN ERROR
					OPTIONS INCOMPATIBLE WITH UNDEFINED RECORDS
					RDJFCB FAILED
					RECFM=U NOT SUPPORTED FOR THIS FUNCTION
					TRKCALC FAILED

PU031E CURRENT FUNCTION TERMINATED DUE TO ABOVE ERROR.

PU038E NO SELECT/EXCLUDE LIST OR MEMBER SPECIFICATION.

PU072E UNEXPECTED END OF DIRECTORY FOUND AT CCHHR=X'cccchhrr', DDNAME IS <ddname>.

PU073W END OF DATA SET REACHED WHILE READING THE DIRECTORY FOR DDNAME <ddname>.

PU074E INVALID FIRST DIRECTORY RECORD AT CCHHR X'cchhr' FOR DDNAME <ddname>

PU075E INVALID DIRECTORY EOF RECORD AT ADDRESS X''', (TRACKLBP,,X),''', CCHHR IS X''',

PU076E *** ERROR *** DIRECTORY IS TOO SHORT: ', (RDIRBLKN,F,L),' BLOCKS AVAILABLE, ',

PU077W **DEBUG - GETR READ AHEAD <member> <ttr1> <ttr2>

PU078E TTR CONVERSION ERROR IN GETREC ROUTINE, TTR0 IS X'ttr', MEMBER IS <member>.

PU079E <standard error message from SYNAD>

PU091I CLOSING STATISTICS FOR DDNAME <ddname>:
               DATA SET NAME: <dsname>
                        UNIT: 33x0        VOLUME: volser       CREATED: yyyy-mm-dd
                       RECFM: recfm        LRECL: lrecl        BLKSIZE: block-size
            TRACKS ALLOCATED: nnnnn         USED: nnnnn (nnn%)    FREE: nnnnn (nnn%)
  DIRECTORY BLOCKS ALLOCATED: nnnnn         USED: nnnnn (nnn%)    FREE: nnnnn (nnn%)
                     MEMBERS: nnnnn      ALIASES: nnnnn
  EXTENT LIST:
           0  X'cccchhhh-cccchhhh'   ccccc/hh-ccccc/hh      nnnnn TRACKS

PU098I ELAPSED TIME FOR THIS RUN: sss.hh SECONDS      CPU TIME: sss.hh SECONDS       CHANNEL CONNECT TIME: nnnnn

PU099I END OF JOB - RETURN CODE IS <rc>. 
Function=LOAD

PU112E FIRST SYSIN RECORD MUST BE A ./ ADD STATEMENT.

PU115I THE FOLLOWING MEMBERS HAVE BEEN LOADED INTO THE OUTPUT DATA SET:

PU117I n1 DUPLICATE MEMBERS HAVE BEEN RENAMED/IGNORED. 
Function=COPY/MOVE/COMPRESS

PU141I THE FOLLOWING MEMBERS HAVE BEEN SELECTED:

PU146W MEMBER <member> HAS MORE THAN 1 USER TTR

PU147W ALIAS <alias> DOES NOT CORRESPOND TO A MEMBER

PU151I n1 MEMBERS MOVED/COPIED, n2 MEMBERS NOT REPLACED.

PU152W NO MEMBERS COPIED/MOVED, n2 MEMBERS NOT REPLACED.

PU153I THE OUTPUT DATA SET HAS BEEN RESET; NO MEMBERS HAVE BEEN COPIED/MOVED.

PU154W NO MEMBERS COPIED/MOVED.

PU155I n1 MEMBERS NOT COPIED/MOVED DUE TO 'TEST' OPTION.

PU156E n1 ADDITIONAL TRACKS NEEDED FOR THIS OPERATION.

PU157I n1 MEMBERS COPIED/MOVED, n2 MEMBERS REPLACED.

PU158I THE OUTPUT DATA SET HAS BEEN RESET; n1 MEMBERS HAVE BEEN COPIED/MOVED.

PU168I THE OUTPUT DATA SET HAS BEEN COMPRESSED. 
Function=REBUILD

PU177I A ONE-TRACK DIRECTORY HAS BEEN SUCCESSFULLY WRITTEN AT THE BEGINNING OF THE OUTPUT DATA SET. 
Function=SCRATCH

PU221I THE FOLLOWING MEMBERS WILL/WOULD BE SCRATCHED:

PU222W NO MEMBERS SCRATCHED, n1 MEMBERS KEPT.

PU223I n1 MEMBERS SCRATCHED, n2 MEMBERS KEPT.

PU224W NO MEMBERS SCRATCHED, LIBRARY IS EMPTY.

PU225W n1 MEMBERS NOT SCRATCHED DUE TO 'TEST' OPTION. 
Function=RESET

PU232I THE OUTPUT DATA SET HAS BEEN RESET; IT PREVIOUSLY CONTAINED n1 MEMBER(S) AND n2 ALIAS(ES).

PU233I THE OUTPUT PDSE HAS BEEN RESET.

PU235I The output PDSE was not reset, STOW Failed with RC=nn. 
Function=LISTDIR

PU241I THE FOLLOWING MEMBERS HAVE BEEN SELECTED:

PU242I n1 MEMBERS LISTED. 
Function=UNLOAD

PU251I THE FOLLOWING MEMBERS HAVE BEEN SELECTED:

PU252I n1 MEMBERS UNLOADED. 

Sample SYSPRINT Output Report

1GSF UTILITIES - PDSUTIL R316M                        Tuesday 11 Jul 2006  (06.192)  17:14        SYS1       PAGE 0001
-PU002I FUNCTION REQUESTED: 'COPY    '   ADDITIONAL OPTIONS: 'INDD=NEWDD,OUTDD=OLDDD'
0PU021I INPUT DATA SET IS DDNAME=NEWDD,DSNAME=SYS06192.T171419.RA000.GILBERT6.NEWDD.H01,VOL=3390=PRIM12
0PU022I OUTPUT DATA SET IS DDNAME=OLDDD,DSNAME=PRISMCS.LOCAL.MVSJCL,VOL=3390=WORK02,CREDT=20060710
-PU141I THE FOLLOWING MEMBERS HAVE BEEN SELECTED:
0            AINJCL66  BINJHATI  CINJL67A  DINJL67H  EINJL67T  FOPEPADO  GOPPREIJ
-PU151I      7 MEMBERS COPIED, 0 MEMBERS NOT REPLACED.
-PU091I CLOSING STATISTICS FOR DDNAME OLDDD:
0               DATA SET NAME: PRISMCS.LOCAL.MVSJCL
                         UNIT: 3390         VOLUME: WORK02      CREATED: 2006-07-10
                        RECFM: FB            LRECL: 80          BLKSIZE: 27920
             TRACKS ALLOCATED: 48             USED: 45 (93%)       FREE: 3 (7%)
   DIRECTORY BLOCKS ALLOCATED: 80             USED: 45 (56%)       FREE: 35 (44%)
                      MEMBERS: 267         ALIASES: 0
0  EXTENT LIST:
0           0  X'08F60000-08F80005'    2294/00-2296/05     36 TRACKS
            1  X'08FA0000-08FA0005'    2298/00-2298/05      6 TRACKS
            2  X'08FA000B-08FB0001'    2298/11-2299/01      6 TRACKS  (EOF)
-PU098I ELAPSED TIME FOR THIS RUN:    0.11 SECONDS        CPU TIME:    0.06 SECONDS       CHANNEL CONNECT TIME: 0
0PU099I END OF JOB - RETURN CODE IS 0. 

Search key-words: ibm mainframe software mvs os/390 z/os os390 zos entire pds complete pdse pds/e member creation library create members libraries wildcard wild-card mass renaming en-masse erase fast erasing rapid delete quick deleting deleteing empty emptying reset resetting clear clearing remove removing recover multiple punch directory list content records sequential DSORG PS file files dataset datasets load-module BLDL STOW IEHPROGM IEHLIST IEBUPDTE ISPF statistics IEBCOPY alternative IEBPTPCH IEHMOVE PDSMAN FASTCOPY PDSFAST PDSCOPY PDSMOVE IEBMOVE MBRCOPY MBRMOVE COPYMBR MOVEMBR scrtch ENQ SPFEDIT SYSDSN manual reference documentation resetds resetpds