SCRATCH Command for TSO/E, ISPF and Batch

Overview

The SCRATCH utility command deletes PDS members and empties libraries in the TSO/E on-line and batch environments of MVS/ESA V5, OS/390 and z/OS. SCRATCH uses the same protection scheme as ISPF and the linkage-editor to prevent concurrent updates to the partitioned data set it updates. SCRATCH can be used to delete a single member, multiple members, or all the members in the specified PDS or PDSE.

SCRATCH helps application programmers, systems programmers and consultants delete members from specified libraries or reset them to empty status in a safe manner using DISP=SHR.

SCRATCH is an affordable product. A free, time-limited version is available for evaluation.

Command Syntax

SCRATCH is a TSO/E command and standard TSO/E rules for command syntax apply. Below is a list of options and parameters which can be specified. Please refer to the sample JCL for coding examples.

SCRATCH	(defaults)
dsname	Mandatory
VOLUME(volser)	catalog
SHR\|OLD\|LLAREFRESH	SHR
MEMBERS(member filters)	n/a
EXCLUDEMEMBERS(member filters 2)	n/a
RESET\|NORESET\|COMPRESS	n/a
TEST\|NOTEST	NOTEST
LIST\|NOLIST	see note
IMS	see note
SETMSG	n/a

'dsname' specifies the data set name of the PDS or PDSE to process. If 'dsname' is not enclosed in apostrophes, it is prefixed with the TSO prefix. 'dsname' may include a fully-qualified member name in parentheses, in which case the corresponding member is scratched - see Specifying Member Names below.
'volser' is the optional volume serial number of an uncatalogued data set. If 'volser' is not specified, the volume serial is retrieved from the catalog.
SHR and OLD are mutually exclusive key-words which indicate whether DISP=SHR or DISP=OLD should be used to allocate the library. SHR is the default. LLAREFRESH specifies that the LLACOPY macro should be issued for each member successfully scratched from the specified PDS - see LLAREFRESH Option below.
'member filters' is a list of fully-qualified or partially-qualified member (or alias) names that should be scratched. 'member filters' is required if the specified data set name does not contain a member name (see "Specifying Member Names" below). The following formats are valid:
1. ABCDEF represents a fully qualified name
2. ABC* lists all members whose name begins with the characters ABC
3. ABC%EF* lists all members whose names are at least 6-characters long, beginning with ABC and having the characters EF in 5th and 6th positions.
4. *JKL* lists all members whose names contain the characters JKL.
'member filters 2' is a list of fully-qualified or partially-qualified member names that should not be scratched. The format of this operand is the same as 'member filters' above. XMEMBERS is an alias for this key-word.
RESET, NORESET and COMPRESS are optional key-words which are ignored when the specified PDS is a PDSE. RESET specifies that the PDS is reset to empty (as if it had just been allocated) if there are no members left in it after the specified members have been deleted. RESET is the default option for an empty PDS, i.e. an empty PDS is reset unless NORESET is specified. When RESET is specified without any member name, MEMBERS(*) is assumed and all the members are deleted. RESET is ignored if the PDS is not empty after the scratch operation. When COMPRESS is specified, SCRATCH invokes IEBCOPY to compress the remaining members after a partial Scratch operation; COMPRESS affects the behaviour of the LLAREFRESH option - see LLAREFRESH Option below.
TEST specifies that SCRATCH should run in simulation mode and the directory should not be updated. NOTEST is the default. UPDATE is equivalent to NOTEST.
LIST specifies that the names of the scratched members should be displayed along with the return-code from the STOW macro. NOLIST is the default when MEMBERS(*) is specified; LIST is the default otherwise.
IMS specifies that an IMS-compatible ENQ/DEQ should be issued; by default, ENQ/DEQ are compatible with ISPF and the Linkage-Editor.
SETMSG is an optional parameter instructing SCRATCH to display statistics using the ISPF SETMSG service when the partitioned data set is closed.

Specifying Member Names

Al least one member name must be specified in the SCRATCH command, otherwise processing terminates. The user specifies which member (or members) should be scratched as follows:

A single member name can be specified as part of the data-set name of the load-library: SCRATCH 'STAGE.PARMLIB(DATECARD)'
A list of member names can be specified in the MEMBERS parameter: SCRATCH 'STAGE.PARMLIB' MEMBERS(DATECARD,LPARNAME,%MB*,BPX*)
A list of generic member names can be specified in the MEMBERS parameter: SCRATCH 'STAGE.PARMLIB' MEMBERS(DATEC*,%MB*)
The above options can be mixed: SCRATCH 'STAGE.PARMLIB(DATECARD)' MEMBERS(LPARNAME,DATEC*,%MB*)
No members is scratched when MEMBERS is not specified and the data-set name does not contain a member name.
All members are scratched when MEMBERS(*) is specified

LLAREFRESH Option

When LLAREFRESH is specified, SCRATCH issues the LLACOPY macro for each member successfully scratched from the specified PDS. Furthermore, when COMPRESS and LLAREFRESH are both specified, SCRATCH also issues LLACOPY after the end of the compress operation for each member remaining in the PDS or PDSE. The LLAREFRESH option only applies to load-libraries and is ignored if the RECFM of the PDS or PDSE is not equal to U.

LLAREFRESH requires special authorisation, i.e. the SCRATCH command must be:

specified in the AUTHTSF section of the IKJTSOxx member of SYS1.PARMLIB, and
executed out of an APF-authorised library

Sample JCL

SCRATCH runs in four different modes:

as a TSO command
- on-line
- in batch.
as a batch program
- on-line
- in batch.

Running SCRATCH as a TSO command in batch

The following sample job stream shows how to set up a TMP job step to execute several SCRATCH commands in a batch job.

 //SCRATCH1 JOB (acct#),'SCRATCH PDS Members',CLASS=U,MSGCLASS=H
 //*
 //*      Scratch PDS Members - Examples
 //*
 //SCRATCH EXEC PGM=IKJEFT01
 //STEPLIB  DD DSN=<SCRATCH Load Library>,DISP=SHR
 //SYSTSPRT DD SYSOUT=*
 //SYSTSIN  DD *

  /* Scratch a single member */

 SCRATCH 'GSFSOFT.FILE183.PDS(FASTPATH)'

  /* Scratch several members and compress */

 SCRATCH 'GSFSOFT.FILE183.PDS' +
         MEMBERS(FASTPATH,COMPR*,ROUTE*) +
         COMPRESS

  /* Empty (reset) a load-library and compress it */

 SCRATCH 'GSFSOFT.TEST.LOAD' MEMBERS(*)

  /* Delete specified load-modules and remove them from LLA */

 SCRATCH 'STAGE.LINKLIB2' MEMBERS(ABC* *JKL*) XMEM(*123 ABC%%EE) LLA

 /*

Running SCRATCH as a batch program

SCRATCH can also run as a batch program with reduced JCL requirements. When running as a batch program, the following functions are not available: COMPRESS, SHR, OLD, LLAREFRESH, SETMSG, VOLUME. Other options can be specified in the PARM field as shown in the examples below.

The following sample job stream shows how to delete a single PDS member, or several members in a batch job.

 //SCRATCH2 JOB (acct#),'SCRATCH PDS Member',CLASS=U,MSGCLASS=H
 //JOBLIB   DD DSN=<SCRATCH Load Library>,DISP=SHR
 //*
 //*      Scratch single PDS Member
 //*
 //SINGLE   EXEC PGM=SCRATCH
 //SYSLIB   DD DSN=GSFSOFT.FILE183.PDS(FASTPATH),DISP=SHR
 //*
 //*      Scratch multiple PDS Members in TEST mode
 //*
 //MULTIPLE EXEC PGM=SCRATCH,PARM='MEM(ABC* *JKL*) XMEM(*PROD) TEST'
 //SYSLIB   DD DSN=GSFSOFT.FILE183.PDS,DISP=SHR
 //*
 //*      Empty a PDS or PDSE
 //*
 //RESET    EXEC PGM=SCRATCH,PARM='MEM(*)'
 //SYSLIB   DD DSN=GSFSOFT.FILE183.PDS,DISP=SHR
 //*
 //*      Empty a PDS (alternate PARM)
 //*
 //RESET2   EXEC PGM=SCRATCH,PARM=RESET
 //SYSLIB   DD DSN=GSFSOFT.FILE183.PDS,DISP=SHR

Messages

SCR006E LOCATE failed for dsname, return code is rc.

SCR007E dsname is not a disk data set.

SCR008E dsname not found on volume, OBTAIN RC=rc.

SCR009E dsname is not a partitioned data set.

SCR012W Member member was not found in the PDS directory.

SCR013W Pattern member did not match any PDS directory entry.

SCR017I Member member successfully deleted.

SCR018I Member member successfully deleted per filter(filter)

SCR019W Member member could not be deleted, STOW RC=nn

SCR021W PDS successfully reset using STOW.

SCR022W PDSE successfully reset using STOW.

SCR051E Invalid PARM Address: xxxxxxxx

SCR052E IKJTSOEV Failed, RETCODE=rc, REASON=reason, INFO=info

SCR052E RDJFCB Failed for DDN=SYSLIB, RC=nn

SCR073I PDS was successfully compressed - IEBCOPY RC=0

SCR074E COMPRESS failed for dsname, IKJEFTSR R15=rc, RETCODE=return-code, REASON=reason, ABEND=abend-code

SCR075I <IEBCOPY SYSPRINT message>

SCR091I SCRATCH successful for dsname, now nnn% full.

Search key-words: ibm mainframe main-frame mvs esa os/390 z/os os390 zOS TSO ISPF CLIST REXX IEHPROGM IEBUPDTE IDCAMS mass delete through JCL deleting deletion scratch scratching erase erasing except member exception including retrieve 1 2 3 4 5 6 7 8 9 members pds clearpds pdsclear pdse pdses DSORG=PO directory corrupt directories empty emptying reset resetting clear clearing remove removing select selecting selected exclude excluded library libraries dataset datasets file files enq spfedit sysiewlp load-library load-libraries loadlib lib load-module load-modules program library utility program object objects pdsempty pdsreset pds/e binder linkage editor linkedit link edit lked load object module modules generic delmbr scrmbr mbrdel mbrscr scrpds scratchm mscratch scrtch via wildcard wildcards wild-card wild-cards partially-qualified fully-qualified start pdsman pdsfast tips löschen over write overwrite dienstprogramm utilitario utilitaire need specific zero clean-up clean-out ieb ieh