# DSNINFO (Data Set Information)

## Syntax:

    DSNINFO(dsname[,volser][,option])

## Arguments:

dsname
  is the 1 to 64 character name of the data set for which you want information. If a member name is supplied, it is ignored. A relative generation name may be specified using the standard notation (e.g., mygdg(-3)). If you fully qualify the data set name, you must enclose it in single quotes (see examples below). If dsname is not enclosed in single quotes, the userid (as determined by IRXUID) will be appended to the front. For more information on specifying data set names see "Specifying Data Set Names".

  Note: If the data set is not cataloged, you must specify the volser argument.

volser
  is the 1 to 6 character volume serial number identifying the volume upon which the data set resides. If the data set is not cataloged, you must specify this argument. If the data set is cataloged, you do not need to specify volser; a catalog search will find the correct volume for you.
option
  indicates the type of processing desired. The valid options are:
  'B'
    indicates basic information is to be returned (see "Returned Information" below). This is the default.
  'F'
    indicates full information is to be returned.

## Module Name:

SWXDSNIF

## Service Description:

The DSNINFO function is used to retrieve catalog, VTOC, allocation, space, directory, and SMS information for single volume, DASD data sets.

Notes:

1. If more than one volume is associated with the data set, only information about the first volume is returned.
2. For VSAM data sets, only the following are returned:
   - Catalog group.
   - DSORG of the VTOC group (DSORG=VS).
   - Allocation group.

   All other items will contain question marks.

3. If the data set is not allocated, allocation information will not be present.
4. If the data set is not managed, SMS information will not be present.
5. If the data set is not partitioned, directory information will not be present.
6. If directory information is requested, but the user is not authorized to open the data set for input, directory information will not be present. No error indication is given.
7. If directory information is requested, but another user holds an exclusive enqueue for the data set (i.e., it is allocated DISP=OLD), directory information will not be present. No error indication is given.
8. If allocation units cannot be determined, tracks is assumed. In this situation, the units value will be "TRACKS?".
9. The values for blocks/track, tracks/cylinder, and cylinders/volume are obtained from the TRKCALC and DEVTYPE macros. For more information on this topic, refer to DFP System Programming Reference, or DFSMS Using Advanced Services for Data Sets.
10. When allocation units is "BLOCKS", the number of blocks allocated is determined by adding up the total number of tracks allocated and dividing the result by the number of blocks per track. However, this number is only an estimate, because the data set may contain short blocks (blocks less than BLKSIZE length).
11. The number of units used is based on the DS1LSTAR field of the format 1 DSCB (Data Set Control Block). DS1LSTAR has 2 parts, the number of tracks and the number of records (blocks). The computation for units used is as follows:
    - For cylinder allocations, the tracks part of DS1LSTAR is converted to cylinders. If the records portion of DS1LSTAR is not zero, the used cylinders value is increased by one.
    - For track allocations, the tracks part of DS1LSTAR is used as is. If the records portion of DS1LSTAR is not zero, the used tracks value is increased by one.
    - For block allocations, the tracks part of DS1LSTAR IS multiplied by the number of blocks per track, and the records portion is added in to obtain blocks used. The lesser of blocks used or blocks allocated is returned (i.e., blocks used will never exceed blocks allocated).
12. MVS/SP 4.2 and DFP/MVS 3.3 are the minimum software levels for DSNINFO. If your software is older than this, some data items may not be available.
13. An example of DSNINFO is contained in the DSINFO exec of the REXXTOOL.EXEC library. This example contains a complete parsing templet for DSNINFO.

## Returned Information:

The DSNINFO function returns a string containing the return code and data set information or an error message.

When the return code is zero, the fields below are returned (the fields are separated by one blank).

Word | Data Item | Option | Group | Description
--- | --- | --- | --- | ---
1. | rc | B | N.A. | Return code.
2. | dsname | B | Catalog | The data set name (fully qualified, no quotes).
3. | volser | B | Catalog | Volume serial number. If the data set spans volumes, only the first volser is reported.
4. | unit | B | Catalog | Type of unit (e.g., "3390"). If the data set spans volumes, only the first unit is reported.
5. | dsorg | B | VTOC | Data set organization. PDSE data sets are indicated with the "PO-E" designation.
6. | recfm | B | VTOC | The record format.
7. | lrecl | B | VTOC | The logical record length.
8. | blksize | B | VTOC | The block size.
9. | keylen | B | VTOC | Hardware key length (not usually present).
10. | rkp | B | VTOC | Relative key position (not usually present).
11. | created | B | VTOC | Date of creation.
12. | expires | B | VTOC | Date the data set expires (is deleted).
13. | referenced | B | VTOC | Date most recently opened.
14. | password | B | VTOC | READ Password required for reading and writing. WRITE Password required to write but not read. ? No password required.
15. | updated | B | VTOC | 1 Data set opened for other than INPUT since last back-up. 0 Data set only opened for INPUT since last back-up.
16. | racfprof | B | VTOC | 1 Data set is protected by a discrete profile. 0 Data set's protection is unknown.
17. | managed | B | VTOC | 1 Data set is managed. 0 Data set is not managed.
18. | ddname | B | Alloc. | The data definition name.
19. | status | B | Alloc. | The allocation status.
20. | ndisp | B | Alloc. | The normal disposition.
21. | cdisp | B | Alloc. | The conditional disposition.
22. | units | F | Space | The units by which the data set is allocated (CYLINDERS, TRACKS, BLOCKS).
23. | alloc | F | Space | Number of units presently allocated.
24. | used | F | Space | Number of units presently used.
25. | extents | F | Space | Number of extents presently allocated.
26. | primary | F | Space | Number of units specified for primary allocation.
27. | secondary | F | Space | Number of units specified for secondary allocations.
28. | blkstrk | F | Space | Number of blksize blocks that will fit on a track on this volume.
29. | trkscyl | F | Space | Number of tracks per cylinder for this volume
30. | cylsvol | F | Space | Number of cylinders for this volume
31. | adirblks | F | Dirctry | Number of directory blocks allocated. Not available for PDSEs.
32. | udirblks | F | Dirctry | Number of directory blocks in use.
33. | members | F | Dirctry | Number of members.
34. | dsntype | F | SMS | The SMS data set type.
35. | storclass | F | SMS | SMS storage class.
36. | mgmtclass | F | SMS | SMS management class.
37. | dataclass | F | SMS | SMS data class.

If a data item is unavailable, the interface supplies a single question mark (?) as a placeholder. This ensures that the word position of all data items remains constant.

If the return code is not zero, the following data items are returned.

Word | Data Item | Description
--- | --- | ---
1. | rc | Return code.
2. | dsname | The data set name (fully qualified, no quotes).
3. | reason | The reason code in printable hex, or 8 zeros if not applicable.
| message | A textual error message describing the service detecting the error, and the nature of the error. The message can (and usually does) contain embedded blanks.

If you CALL the DSNINFO function, the returned value is contained in the RESULT special variable. The RC variable is unchanged (unless you assign the return code to it). A return code of zero always indicates success.

## Examples:

1. Retrieve full information for a cataloged data set. The userid will be automatically appended to the dsname argument:

       parse value dsninfo("user.data",,'f') with rc info
       if rc = 0 then
         parse var info dsname volser unit dsorg recfm lrecl,
           blksize keylen rkp created expires referenced,
           password updated racfprof managed ddname,
           status ndisp cdisp units alloc used extents,
           primary secondary blkstrk trkscyl cylsvol,
           adirblks udirblks members dsntype sclass mclass,
           dclass
       else
         parse var info dsname reason message

2. Retrieve basic information for a data set that is not cataloged. The userid will not be automatically appended to the dsname argument:

       parse value dsninfo("'sys1.lib1'",'mvs001') with rc info
       if rc = 0 then
         parse var info dsname volser unit dsorg recfm lrecl,
           blksize keylen rkp created expires referenced,
           password updated racfprof managed ddname,
           status ndisp cdisp
       else
         parse var info dsname reason message

© Copyright 1998 by Open Software Technologies, Inc.