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:

If more than one volume is associated with the data set, only information about the first volume is returned.
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.
If the data set is not allocated, allocation information will not be present.
If the data set is not managed, SMS information will not be present.
If the data set is not partitioned, directory information will not be present.
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.
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.
If allocation units cannot be determined, tracks is assumed. In this situation, the units value will be "TRACKS?".
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.
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).
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).
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.
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.

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.

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:

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

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