JSON document specifications for z/OS data set and file REST interface requests

This section describes the contents of the JSON documents that are used with z/OS® data set and file REST interface requests.

For more information about the properties described in these JSON documents, see z/OS ISPF Services Guide, SC34-4819.

The following JSON documents are described:

Data set list document
Data set list with attributes document
PDS/PDSE member list with attributes document
Create a sequential and partitioned data set document
File list document
Unix file and directory list with attributes document
Mount and unmount a file system document
Create a UNIX file document
Error report document.

Data set list document

Table 1 shows the contents of the JSON data set list document.

For more information about these properties, see the dialog variables for the YES|NO|PRT parameter of LMDLIST (list data sets) in z/OS ISPF Services Guide, SC34-4819.

Table 1. Contents of the JSON data set list document
Property	Description	Required
items	An array where each element contains the following key:value pairs	Yes
dsname	Data set name.	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	No
JSONversion	Version number of this JSON document.	Yes
vol	Volume serial	No
used	Percentage of used tracks or pages (PDSE)	No
extx	Number of extents used, long format (5 bytes)	No
cdate	Creation date	No
edate	Expiration date	No
rdate	Date last referenced	No
migr	Whether the data set is migrated (YES or NO) based on the value of the `VOLUME_OF_MIGRATED_DATA_SETS` keyword in the ISPF configuration table. If the volume name of the data set matches the value of `VOLUME_OF_MIGRATED_DATA_SETS, ZDLMIGR` is set to YES, otherwise it is set to NO.	No
dsntp	Dsname type (PDS, LIBRARY, or ’ ’)	No
spacu	Space units	No
mvol	Whether the data set is multivolume (Y) or not (N)	No
ovf	Space overflow indicator (YES or NO)	No
dsorg	Data set organization	No
recfm	Record format	No
lrecl	Logical record length	No
blksz	Block size	No
sizex	Data set size in tracks, long format (12 bytes)	No
catnm	Name of the catalog where the data set is located	No
dev	Device type	N0

Data set list with attributes document

Data set list with attributes document shows the attributes of the JSON data set list document.

For more information about these properties, see the dialog variables for the YES|NO|PRT parameter of LMDLIST (list data sets) in z/OS ISPF Services Guide, SC34-4819.

Table 2. X-IBM-Attributes=vol
Property	Description	Required
items	An array where each element contains the following key:value pairs dsname Data set name. vol Volume in which the data set resides.	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	No
JSONversion	Version number of this JSON document.	Yes

Table 3. X-IBM-Attributes=dsname
Property	Description	Required
items	An array where each element contains the following key:value pairs dsname Data set name.	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	Optional property; set to true when more rows can be returned.	No
totalRows	Total number of rows that match the request.	No
JSONversion	Version number of this JSON document.	Yes

Table 4. X-IBM-Attributes=base
Property	Description	Required
items	An array where each element contains the following key:value pairs Table 5	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	No
JSONversion	Version number of this JSON document.	Yes

Table 5. Items key:value pairs
Property	Description	Required
dsname	Data set name.	Yes
blksz	Block size.	No
catnm	Name of the catalog in which the data set was located.	No
cdate	Creation date.	No
dev	Device type.	No
dsntp	Percentage of used tracks or pages(PDSE).	No
dsorg	Data set organization.	No
edate	Expiration date.	No
extx	Number of extents used, long format (5 bytes).	No
lrecl	Logical record length.	No
migr	Whether the data set is migrated (YES or NO) based on the value of the VOLUME_OF_MIGRATED_DATA_SETS keyword in the ISPF configuration table. If the volume name of the data set matches the value of VOLUME_OF_MIGRATED_DATA_SETS, ZDLMIGR is set to YES, otherwise it is set to NO.	No
mvol	Whether the data set is multivolume (Y) or not (N).	No
ovf	Space overflow indicator (YES or NO).	No
rdate	Date last referenced.	No
recfm	Record format.	No
sizex	Data set size in tracks, long format (12 bytes).	No
spacu	Space units.	No
used	Percentage of used tracks or pages (PDSE).	No
vol	Volume serial.	No

PDS/PDSE member list with attributes document

Contents of the JSON PDS/PDSE member list document shows the contents of the JSON member list document.

For more information about these properties, see the dialog variables for the YES|NO parameter description of LMMFIND (find a library member) in z/OS ISPF Services Guide, SC34-4819.

Table 6. Contents of the JSON PDS/PDSE member list document
Property	Description	Required
items	An array where each element contains the following key:value pairs member Member name	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	No
JSONversion	Version number of this JSON document.	Yes

Table 7. X-IBM-Attributes=base and data set RECFM=F or V
Property	Description	Required
items	An array where each element contains the following key:value pairs. See Table 8.	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	No
JSONversion	Version number of this JSON document.	Yes

Table 8. Items key:value pairs for data set RECFM=F or V
Property	Description	Required
member	member name.	Yes
vers	Version number; a number from 1 to 99.	No
mod	Modification level; a number from 0 to 99.	No
c4date	Creation date in 4-character year format	No
m4date	Last change date in 4-character year format	No
cnorc	Current number of records; a number from 0 to 65 535.	No
inorc	Beginning number of records; a number from 0 to 65 535.	No
mnorc	Number of changed records; a number from 0 to 65 535.	No
mtime	Last change time; a character value in the format hh:mm.	No
msec	Seconds value of the last change time. This is a two character field.	No
user	User ID of last user to change the given member; an alphanumeric field with a maximum length of 7 characters.	No
sclm	Indicates whether the member was last modified by SCLM or ISPF. A value of Y indicates the last update was made through SCLM. A value of N indicates that the last update was made.	No

Table 9. X-IBM-Attributes=base and data set RECFM=U
Property	Description	Required
items	An array where each element contains the following key:value pairs. See Table 10.	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	No
JSONversion	Version number of this JSON document.	Yes

Table 10. Items key:value pairs for data set RECFM=U
Property	Description	Required
member	member name.	Yes
ac	A 2-character field containing the authorization code of the member.	No
alias-of	An 8-character field containing the name of the real member that this member is an alias of. If the member is not an alias this field is blank.	No
amode	A 3-character field containing the AMODE of the member.	No
attr	A 20-character field containing the load module attributes. The attributes are 2-character strings separated by blanks. These strings can appear in the attribute string: NX Not executable OL Only Loadable OV Overlay RF Refreshable RN Reentrant RU Reusable SC Scatter Load TS Test	No
rmode	A 3-character field containing the RMODE of the member.	No
size	An 8-character field containing the load module size in hex.	No
ttr	A 6-character field containing the TTR of the member.	No
ssi	An 8-character field containing the SSI information for a load module.	No

Create a sequential and partitioned data set document

Table 11shows the contents of the JSON sequential and partitioned data set document.

For more information about these properties, see the dialog variables for the YES|NO parameter description of LMMFIND (find a library member) in z/OS ISPF Services Guide, SC34-4819.

Table 11. Contents of the create a sequential and partitioned data set document
Property	Description	Required
volser	Volume serial number of the device a data set will reside on.	No
unit	Unit name of the device that the data set will reside on.	No
dsorg	Unit name of the device that the data set will reside on.	No
alcunit	Unit of space allocation.	No
primary	Primary space allocation for the data set.	No
secondary	Secondary space allocation for the data set.	No
dirblk	Number of directory blocks for a partitioned data set.	No
avgblk	Specifies the unit of space allocations to be blocks and sets the average block length.	No
recfm	Record format of a data set: Current support: F: fixed V: variable U: undefined B: block FB: fixed blocked VB: variable blocked	No
blksize	Block size of the data set.	No
lrecl	Record length of data set.	No
storclass	Specifies the storage class of system managed storage.	No
mgntclass	Specifies the management class of the data set.	No
dataclass	Specifies the data class of the data set.	No

File list document

Table 12 shows the contents of the JSON file list document for UNIX files.

For more information about these properties, see the column-list parameter of the DIRLIST (directory list service) in z/OS ISPF Services Guide, SC34-4819.

Table 12. Contents of the JSON file list document
Property	Description
items	JSON array of member entries containing the properties that follow in the remainder of this table.
filename	File name
returnedRows	Number of rows that were returned for this request.
moreRows	Optional property; set to true when more rows can be returned.
totalRows	Total number of rows that match the request.

Unix file and directory list with attributes document

Contents of the unix file and directory shows the contents of the JSON file list document for UNIX files.

For more information about these properties, see the column-list parameter of the DIRLIST (directory list service) in z/OS ISPF Services Guide, SC34-4819.

Table 13. Contents of the unix file and directory
Property	Description	Required
items	An array where each element contains the following key:value pairs. See Unix items key:value pairs.	Yes
returnedRows	Number of rows that were returned for this request.	Yes
moreRows	True, if more rows are available to return.	No
totalRows	Total number of data sets found matching the dslevel and volser criteria. If you specify ",total" as suffix in X-IBM-Attributes header, like "dsname,total", or "base,total", or "vol,total".	Yes
JSONversion	Version number of this JSON document	Yes

Table 14. Unix items key:value pairs
Property	Description	Required
name	File or directory name.	Yes
mode	indicating the permissions.	No
size	For regular files, the file's size in bytes. For other kinds of files, the value of this field is unspecified.	No
uid	The numeric user ID (UID) of the file's owner.	No
user	The user name of the file's owner got by UID.	No
gid	The numeric group ID (GID) of the file's group.	No
group	The group name of the file's group got by GID.	No
mtime	The most recent time the contents of the file were changed.	No
target	If the file is synlink, this indicates the really file/directory	No

Mount and unmount a file system document

Contents of the Mount and unmount a file system document shows the contents of the JSON file list document for UNIX files.

For more information about these properties, see the column-list parameter of the DIRLIST (directory list service) in z/OS ISPF Services Guide, SC34-4819.

Table 15. Contents of the Mount and unmount a file system document
Property	Description	Required
action	Current support value: mount: you are going to mount an UNIX file system on the specified directory. unmount: you are going to unmount a specified directory.	Yes
mount-point	Specify the mount point you are going to mount/unmount, generally, it is directory.	No
fs-type	Specify the file system type you are going to mount, --the name must match the TYPE aperand on a FILESYSTYPE statement in the BPXPRMxx parmlib member for the file system. For the mount action, this is required; but it is not required for the unmount action.	No
mode	Specify the mode you intend to mount the file system: Support Value: rdonly: read only rdwr: read write --all the values are case insensitive	No

Create a UNIX file document

Contents of the create a UNIX file document shows the contents of the JSON file list document for UNIX files.

For more information about these properties, see the column-list parameter of the DIRLIST (directory list service) in z/OS ISPF Services Guide, SC34-4819.

Table 16. Contents of the create a UNIX file document
Property	Description	Required
type	The request type, support value: directory or dir: you are going to create a directory. file: you are going to create a file.	No
mode	The mode specifies the file/directory permission bits to be used in creating the file/directory. rwxrwxrwx The 9 characters are in three groups of 3; they describe the permissions on the file. The first group of 3 describes owner permissions; the second describes group permissions; the third describes other (or “world”) permissions. Characters that might appear are: r: Permission to read the file w: Permission to write on the file x: Permission to execute the file -: No such a permission	No

Error report document

Table 17 shows the contents of the JSON error report document for z/OS data set and file REST interface requests.

Table 17. Contents of the JSON error report document
Property	Description
category	Error category. This field is integer data type.
rc	Return code. This field is integer data type.
reason	Reason code. This field is integer data type.
message	Message that describes the error.
details	(optional) Array of strings containing additional message details.
stack	Stack trace of the exception.

For the meanings of the category, rc, and reason fields, see Error reporting categories.