ARDC - DSUTIL DOC

DSUTIL - Utility for Maintaining Data Sets in the USC System

Introduction
Utilization
Authorization and Access Commands
Data Set Information Commands
Data Set and Tape Volume Manipulation Commands
Common Applications
Related Documentation
DSUTIL Command Summary

Introduction

DSUTIL is a utility program developed at the University of South Carolina for maintaining datasets in the USC computer system. Topics covered include basic JCL for using DSUTIL, DSUTIL commands, examples of DSUTIL commands, and documentation.
A general knowledge of data processing and Job Control Language (JCL) is required for understanding the material presented here.
For information concerning JCL and related topics, consult the Related Documentation

This documentation was produced by the Academic Research and Data Center of USC. Questions about its content should be directed to a consultant at 777-6865.

Utilization

DSUTIL (Data Set UTILity) is used to:

set authorization and access levels for disk data sets and tape volumes

rename disk datasets

delete and uncatalog RACF entries for disk datasets

delete RACF catalog entries for tape datasets (uncatalog)

list the contents of disk datasets

list tape and disk dataset entries in the RACF system catalog

list tape dataset entries in the tape management system

delete tape dataset entries from the tape management system

group tape volumes on RACF to contain multi-volume datasets

Job Setup:

The basic job set-up for using DSUTIL is:


   //  ( JOB statements )
   // EXEC DSUTIL
   //SYSIN DD *
    DSUTIL commands (start in column 2)
   //

DSUTIL Commands

A DSUTIL command is a word that directs DSUTIL to perform a specified operation. Associated with each command are parameters, which modify the effect of the command in specific ways.

DSUTIL commands are coded beginning in column 2. Each command is followed immediately by a space, then the parameters, which may be coded through column 71. With the exception of a single space separating the parameters from the command name, no spaces are allowed in DSUTIL commands. To continue a statement, end the first line at a comma and begin the continuation line in column 16. Any number of commands can be included in a job. Note that commands are executed sequentially, and failure of one command does not prevent execution of those following it.

The following sections describe individual commands and their parameters. Please note the following conventions used in this documentation when the format of a command is presented:

1) optional parameters appear in parentheses (these parentheses should NOT be included when coding the DSUTIL command
2) parameters in lower case represent options to be coded by the user as described following the command format
3) multiple parameters coded within vertical bars indicates that one of the parameters is required.

Authorization and Access Commands

When a dataset is first written to disk or tape it can be accessed only with the userid used in creating it (this userid is considered the 'owner'). This 'owner' userid is required if the dataset or tape volume is to be read or modified. The status of the dataset or tape volume can be changed so that other userids can be used for accessing or changing the dataset by using one of the following two DSUTIL commands.

PERMIT Command

The PERMIT command is used to allow a specific userid a certain level of access to a disk dataset or tape volume. The general format of the PERMIT command is:

   PERMIT |DSN=datasetname,|authority,USER=userid
          |VOL=volume,     |

datasetname - specifies the name of a disk dataset whose status is to be changed.
volume - the VOL=SER of the tape volume whose access level is to be changed.
authority - should be one of the following keywords:
   READ - Gives authority only to read the disk dataset or tape, not to modify it.
   UPDATE - Gives authority to read or write to a disk dataset, not to delete or rename it. It is NOT valid for tape volumes
   ALTER - Gives authority to read or write to a tape volume, and to read, write to, rename, or delete a disk dataset.
   DELETE - Removes the specified 'userid' from all authorization levels for a disk dataset or tape volume.
userid - the userid to be granted or denied access to the disk dataset or tape volume.

STATUS Command

The STATUS command is used to allow all userids defined to RACF (identified by the keyword 'PUBLIC') a given level of authority over a disk dataset or tape volume, or to list individual userids that have authority over a disk dataset. The general format of the STATUS command is:

   STATUS |DSN=datasetname,|authority(,pubacc)
          |VOL=volume,     |

datasetname - specifies the name of a disk dataset whose status is to be changed.
volume - the VOL=SER of the tape volume whose access level is to be changed.
authority - should be one of the following keywords:
   LIST - Outputs a list of the current authorizations to a disk dataset or a tape volume, including userids and levels of authority for each one. LIST also lists any other tapes grouped with the specified volume on RACF if the tape contains a multi-volume dataset.
   READ - Gives authority to read a disk dataset or tape volume, not to modify it.
   UPDATE - Gives authority to read or write to a disk dataset, not to delete or rename it. It is NOT valid for tape volumes.
   ALTER - Gives authority to read or write to a tape volume, or to read, write to, rename, or delete a disk dataset.
   Note: the READ, UPDATE, and ALTER keywords 'give' authority if the value for 'pubacc' is PUBLIC, and 'remove' authority if NOPUBLIC is specified. See the discussion of 'pubacc' below.
pubacc - should be one of the following keywords:
   PUBLIC - Grants all userids to RACF the status specified by the 'authority' parameter.
   NOPUBLIC - Negates PUBLIC status for the 'authority' level specified. Use of this keyword does not affect the status of individual userid access levels issued by previous PERMIT commands.

Examples:

Following are examples of DSUTIL commands using PERMIT and STATUS. The first set of examples apply to the disk dataset 'N123456.MY'; the second to the tape volume '123456'.

Disk Data Sets:
The disk dataset 'N123456.MY' was created and cataloged on RACF under userid N123456. Note that the userid used in creating a dataset automatically has authority to alter it; this userid and its associated password must be on the JOB statement of the DSUTIL job that changes authorization for a disk dataset.

1. The following command allows userid N987654 to be used to read the dataset but not to modify it:

   PERMIT DSN=N123456.MY,READ,USER=N987654

2. The following command allows all userids to be used to read the dataset:

   STATUS DSN=N123456.MY,READ,PUBLIC

3. The following command allows userid N987654 to be used to rename, write to, or delete the dataset:

   PERMIT DSN=N123456.MY,ALTER,USER=N987654

4. The following command removes the authority granted in Examples 1 and 3:

   PERMIT DSN=N123456.MY,DELETE,USER=N987654

5. After executing each of the above commands in sequence:
  - Userid N123456 could be used to read, modify, rename, or delete the dataset because it was used in creating the dataset.
  - Userid N987654 could be used to read the dataset since it is included in 'PUBLIC', but it could not be used to alter the dataset because authority was removed in Example 4.
  - All userids could be used to read the dataset.

Tape Volumes:
The tape volume '123456' was entered into the tape library by userid N123456. This userid and its associated password must be used on the JOB statement of the DSUTIL job that changes authorization levels to the tape.

1. The following command allows the tape's owner N123456 to change the access level on his tape from ALTER to READ to write-protect his data:

   PERMIT VOL=123456,READ,USER=N123456

2. The following command when issued by N123456 allows user N222222 read access to tape 123456:

   PERMIT VOL=123456,READ,USER=N222222

3. The following command allows the tape's owner ALTER authority to his tape so that he may add datasets:

   PERMIT VOL=123456,ALTER,USER=N123456

4. To write-protect the tape again, the owner executes the following command:

   PERMIT VOL=123456,READ,USER=N123456

5. To deny user N222222 access to tape 123456, the owner executes the following command:

   PERMIT VOL=123456,DELETE,USER=N222222

6. To make tape 123456 available to all users of the USC system for read-only access, owner N654321 executes the following command:

   STATUS VOL=123456,READ,PUBLIC

7. To remove public access to tape 123456, N654321 executes the following command:

   STATUS VOL=123456,READ,NOPUBLIC

Data Set Information Commands

Following are descriptions of three commands which enable the user to find the location, contents, and ownership of a dataset, or a group of datasets, which have been cataloged under RACF on disk or tape.

LISTCAT Command

The LISTCAT command lists all datasets cataloged as specified by the parameters.

NOTE Entire data set names must be used in the LISTCAT ENTRIES statement. For most academic users, DSSLIST will list sufficient information for DASD data sets. TAPEINFO will list creation dates for tape data sets.
The general format of this command is:

   LISTCAT DSN=datasets(,LASTDSN=chars)(,VOL=vol)

datasets - a string restricting the listing of cataloged datasets to those that begin with the characters specified. For example, DSN=N123456 would list datasets beginning with the characters 'N123456'; DSN=N123456.NEW would list datasets beginning with the characters 'N123456.NEW', etc.
chars - the initial characters of the name of the last dataset in the range of datasets to be listed. For example, 'DSN=N123456.AB,LASTDSN=N123456.CD' would list datasets named N123456.ABOY, N123456.B.E.D, N123456.CAP, and N123456.CDTEST, but not N123456.AAB or N123456.CERTS. If LASTDSN is not used, all datasets beginning with the characters specified for 'datasets' are listed.
vol - Restricts the listing to datasets cataloged under RACF on the tape volume specified.

Example:

The following illustrates use of the LISTCAT command:

   LISTCAT DSN=N345678.DATA,LASTDSN=N345678.DATA.LAST

This command lists all datasets beginning with the characters 'N345678.DATA' through datasets beginning with the characters 'N345678.DATA.LAST' (inclusive).

As of Jan. 1, 2000, LISTCAT no longer lists the catalog date for data sets on DASD or magnetic tape.

The following IDCAMS job setup will list information on cataloged data sets including creation date:


// EXEC   PGM=IDCAMS
//SYSIN   DD *
 LISTCAT ENTRIES('JANEDOE.DATASET1') ALL
 LISTCAT ENTRIES('JANEDOE.DATASET2') ALL
//SYSPRINT DD SYSOUT=*
//

DSSLIST Command

The DSSLIST command provides a listing of information concerning the data set(s) specified in the command, including device, vol=ser, creation date, date last referenced, physical organization, tracks allocated and actual tracks used, the number of 2k blocks (unit used for billing purposes), and, optionally, the account number associated with the dataset(s)queried. The general format of this command is:

   DSSLIST DSN=datasets(,LASTDSN=chars)(,ACCT)

datasets - a string restricting the listing of datasets to those that begin with the characters specified. For example, DSN=N123456 would list datasets beginning with the characters 'N123456'; DSN=N123456.NEW would list datasets beginning with the characters 'N123456.NEW', etc.
chars - the initial characters of the name of the last dataset in the range of datasets to be listed.

For example:

   DSN=N123456.AB,LASTDSN=N123456.CD

would list datasets named N123456.ABOY, N123456.B.E.D, N123456.CAP, and N123456.CDTEST, but not N123456.AAB or N123456.CERTS. If LASTDSN is not used, all datasets beginning with the characters specified for 'datasets' are listed.

ACCT - this optional parameter returns the account number associated with the dataset(s). If this option is coded, the field 'Billable Account#' replaces the 'Tracks Allocated/Tracks Used' field on the report generated.

LISTDS Command

The LISTDS command lists the contents of a disk dataset. The general format of this command is:


LISTDS DSN=name(,HEX)(,START=n1)(,LIMIT=n2)(,NOHEAD)(,SELECT=spec)

name - the name of the dataset whose contents are to be listed.
HEX - requests that the data be listed in hexadecimal format.
n1 - an integer from 1 to 9999999 representing the logical record number in the dataset where the listing is to begin. The default for the START= parameter is 1.
n2 - an integer from 1 to 100 representing the number of logical records to be listed from the dataset. The default for the LIMIT= parameter is 10.
NOHEAD - if specified, prevents the position designation from appearing on the listing.
spec - selection criteria for the listing. One or more of the following four statements may be supplied for the value of 'spec' if the SELECT= parameter is coded:


   SELECT=EQ/len/stcol/data/
   SELECT=NE/len/stcol/data/
   SELECT=GT/len/stcol/data/
   SELECT=LT/len/stcol/data/

len - the length of the field.
stcol - the starting column in the record.
data - the string of data being selected.

Up to six SELECT parameters may be specified.

Examples:

Following are examples of the LISTDS command:

   LISTDS DSN=N234567.DATA1,START=400,LIMIT=100,NOHEAD

This example lists 100 records of dataset 'N234567' beginning with record 400 and suppresses the position designation from appearing in the output.

   LISTDS DSN=N345678.DATA2,SELECT=EQ/6/1/DELETE

This example lists 10 records of the dataset 'N345678.DATA2'. The records are listed only if the string 'DELETE' is found beginning in column 1.

TAPEINFO Command

The TAPEINFO command can be used to list the tape management system's directory information for each dataset on a library tape. TAPEINFO requires READ access to the tape queried. (NOTE: Library tapes created prior to 05-14-90 will not have dataset entries stored in the tape management system directory; dataset information on these tapes may be added to the tape management system directory by executing the SETDSNB procedure discussed in the TAPES documentation.)
The general format of the TAPEINFO command is:

   TAPEINFO VOL=nnnnnn

nnnnnn - the tape's six digit volser

For multi-volume tapes, information on all tapes associated with the volser is listed.
The TAPEINFO command lists the following information associated with the volume requested:
volser, label type, density, userid and account number of the owner, and, for each datasetname, the file number, creation jobname, creation date, record length, blocksize, record format, block count, and occurrences of read and/or write errors.

TAPEINFO does not mount the tape volume, but lists information stored by the tape management system.

Example:

   TAPEINFO VOL=012345

This example lists directory information for all datasets written on library tape 0123456.

Data Set and Tape Volume Manipulation Commands

The following commands enable the authorized userid to delete and rename disk datasets, and to delete the RACF catalog entry for tape datasets.

DELETE Command

The DELETE command deletes, and uncatalogs RACF entries, for disk datasets, and uncatalogs RACF entries for tape datasets (tape datasets are not deleted, only the entry for the dataset in the RACF system catalog is removed).

The general format of the DELETE command is:

   DELETE DSN=datasetname

datasetname - the name of the dataset to be removed from the RACF catalog (and deleted if the dataset is stored on disk).

Example:

The following example illustrates use of the DELETE command:

   DELETE DSN=N123456.OLD.DATA

This example deletes and uncatalogs the RACF entry for the disk dataset named 'N123456.OLD.DATA'.

RENAME Command

The RENAME command renames a disk dataset. The general format of this command is:

   RENAME DSN=old,NEWDSN=new

old - the name of the dataset to be renamed.
new - the new name of the dataset.

Examples:

The following illustrate use of the RENAME command:


   RENAME DSN=N123456.MARCH.FILES,NEWDSN=N123456.APRIL.FILES

Executing this command changes the name of the dataset 'N123456.MARCH.FILES' to 'N123456.APRIL.FILES'.
The RENAME command can be used to transfer ownership of a dataset.
The userid used in creating the dataset should be used in a PERMIT command to give another userid ALTER authority. Ownership can then be transferred with a RENAME command by beginning the new dataset name with the userid given ALTER authority. For example, the following two jobs change ownership of a dataset:


1. //   JOB statements (run under account N1234567, userid N123456)
   // EXEC DSUTIL
   //SYSIN DD *
    PERMIT DSN=N123456.EXAMPLE,ALTER,USER=N654321
   //


2. //   JOB statements (run under account N6543210, userid N654321)
   // EXEC DSUTIL
   //SYSIN DD *
    RENAME DSN=N123456.EXAMPLE,NEWDSN=N654321.EXAMPLE
   //

SCRATCH Command

The SCRATCH command is used to delete library tape dataset entries from the tape management system. SCRATCH also deletes the RACF catalog entry for cataloged tape data sets.
SCRATCH must be run before the tape management system will allow you to write over library tape files. SCRATCH requires ALTER access to the tape volume selected. SCRATCH must also be run in the event you check out a CS library tape, record data on it at another computing installation, and then reenter it into the CS tape library; this procedures scratches the old inaccurate dataset information associated with the tape in the tape management system so that it may then be updated using the cataloged procedure SETDSNB (refer to the TAPES documentation for details).

The general format of the command is:

   SCRATCH VOL=nnnnnn,F=fn(,ALL)

nnnnnn - the six digit volser of the tape
fn - the file number where the scratch action is to begin: all directory information on the file number coded and those following it on the tape is scratched from the directory.
ALL - the optional parm ALL must be coded to scratch dataset information for tapes which are part of a multi-volume set. NOTE: If the tape is part of a multi-volume set, SCRATCH cannot be used to selectively scratch particular dataset information: information on all files in the multi-volume set must be scratched (code SCRATCH VOL=nnnnnn,F=1,ALL).

Example:

   SCRATCH VOL=012345,F=2

In this example, the directory for file 2 and any subsequent files on the tape 012345 would be scratched, and a job could then be executed to write a new file(s) after the first file on the tape.

TAPEGRP Command

The TAPEGRP command should be used to group a set of tape volumes in RACF in order to write a multi-volume dataset. The TAPEGRP command may also be used to 'ungroup' tapes.
NOTE: TAPEGRP must be used to group library tapes which have been entered in the tape management system directory (tapes entered into the CS tape library as of May 14, 1990, or library tapes entered prior to this date which were added to the tape management system with the SETDSNB procedure (refer to the TAPES documentation for details)).
If any tapes to be grouped contain datasets already recorded in the tape management system, the DSUTIL SCRATCH command should be run against the tape(s) prior to grouping them with the TAPEGRP command.
The syntax of the TAPEGRP command is:


   TAPEGRP VOL=(volser1,volser2,volser3,volser4,volser5)

volser1, etc., represents the tape volumes to be grouped. Up to 5 tapes may be grouped in a given execution of TAPEGRP; you may rerun the TAPEGRP command to group additional tapes in a previously created group by simply including one volser in the previously created tape group.

When using TAPEGRP, the first volser coded is the primary tape: PERMITs should be issued against this primary tape. Any previous PERMITs for tapes other than the primary tape in the tape group are deleted, but any existing permits for the primary tape are preserved and applied to all tapes in the group created.
NOTE: If the primary tape in the list is already a member of a tape group, the effect of the TAPEGRP command will be to add the remaining volumes to the old group.

To ungroup a volume, the syntax is:

 TAPEGRP VOL=volser

'Ungrouping' a volume from a tapegroup also deletes any permits to the ungrouped tape. The tape owner should re-issue appropriate permits for the tape after removing it from the group.
The STATUS command can be run against any volume in the group to determine what tapes are grouped together.

Common Applications

Following are additional examples of DSUTIL commands. They are based on the assumption that userid N123456 has created and cataloged the dataset N123456.TEST under RACF on disk storage.

1. To authorize the public to read the dataset:


        STATUS DSN=N123456.TEST,READ,PUBLIC

2. To rename the dataset 'N123456.NEW':


        RENAME DSN=N123456.TEST,NEWDSN=N123456.NEW

3. To delete and remove the RACF catalog entry for a disk dataset named N123456.NEW:


        DELETE DSN=N123456.NEW

4. To list RACF accounting and format information on a dataset named N123456.NEW:


        DSSLIST DSN=N123456.NEW

DSUTIL Command Summary

Following is a summary of the DSUTIL commands covered in this documentation. For each command, one of the parameters in the set enclosed in bars (for example, |DSN= | ) is required. Parameters enclosed in parentheses are optional. Single parameters not enclosed in bars or parentheses are required. The summary is subset for commands applicable to tape, and commands applicable to disk.
NOTE: in all DSUTIL commands UNIT= is equivalent to DEVICE= .

Tape Command Summary:


DELETE   DSN=
DSSLIST   DSN=    (,LASTDSN=)  (,ACCT)
LISTCAT   DSN=    (,LASTDSN= )   (,VOL= )
PERMIT    DSN=    |,READ,  |  USER=
                  |,ALTER, |
                  |,DELETE,|
STATUS  VOL=    |,READ, |  (PUBLIC)
                |,ALTER,|  (NOPUBLIC)
                |,LIST  |
SCRATCH VOL=    ,F=        (,ALL)
TAPEGRP VOL=
TAPEINFO VOL=

Disk Command Summary:


DELETE   DSN=
DSSLIST   DSN=   (,LASTDSN= )  (,ACCT)>
LISTCAT   DSN=   (,LASTDSN= )
LISTDS    DSN=   (,HEX )         (,START= ) (,LIMIT= ) (,NOHEAD)
                         |EQ|
                         |NE|
              (,SELECT=  |LT| /LENGTH/LOCATION/CONSTANT)
                         |GT|
PERMIT  DSN=     |,READ,  |  USER=
                 |,UPDATE,|
                 |,ALTER, |
                 |,DELETE,|
RENAME   DSN=   ,NEWDSN=
STATUS   DSN=    |,ALTER, |   (PUBLIC)
                 |,READ,  |   (NOPUBLIC)
                 |,UPDATE,|
                 |,LIST   |

ARDC Documentation ARDC Home Page USC Home Page

This page updated 13 January 2000 by Amy W. Yarbrough, Academic Research and Data Center.
Copyright © 1999, The Board of Trustees of the University of South Carolina.
URL http://www.sc.edu/ardc/docs/dsutil.html

DSUTIL - Utility for Maintaining Data Sets in the USC System

This page updated 13 January 2000 by Amy W. Yarbrough, Academic Research and Data Center. Copyright © 1999, The Board of Trustees of the University of South Carolina. URL http://www.sc.edu/ardc/docs/dsutil.html

This page updated 13 January 2000 by Amy W. Yarbrough, Academic Research and Data Center.
Copyright © 1999, The Board of Trustees of the University of South Carolina.
URL http://www.sc.edu/ardc/docs/dsutil.html