ZOAU JSON schema and examples
Starting with release 1.3, ZOAU uses the z/OS JSON parser to enable JSON support for the utilities dcat, ddls, dhead, dinfo,
dtail, jls, opercmd, and pjdd.
In previous versions of ZOAU, the utilities apfadm, dmod, dsed, and zinfo, supported limited JSON output with a schema that
is now obsolete. These utilities are updated to use the new schema provided by ZOAU v1.3.
Version 1.3.1 adds JSON support to mvscmd, mvscmdauth, dtouch, dwhence, and dgrep.
All JSON-enabled utilities have the following command line options available:
-
The
-joption prints a serialized JSON string with no added whitespace. -
The
-Joption prints the same JSON output as-j, and adds line breaks and indentation to enhance readability.
Base JSON schema
ZOAU v1.3 uses the same base JSON schema to provide output for all supported utilities. The base schema is as follows:
{
"data": {},
"program": "<PROGRAM_NAME>",
"options": "COMMAND_OPTIONS",
"rc": "<RETURN_CODE>"
}
The base schema has the following behaviors:
-
The value for
datais always an object and can contain different name-value pairs for different utilities. -
The
optionsstring contains all the options and arguments passed to the command, and always includes a trailing space. -
Use of the
-Joption implicitly enables-j, which means that theoptionsstring returned by-Jalso contains the output provided by-j. -
The
rcvalue is always a string.
Base schema examples
Each utility populates the base schema data object with its own specific name-value pairs. The following examples show the overall JSON schema structure and the specific name-value pairs relevant for each utility.
apfadm example
The JSON schema structure for apfadm is as follows:
{
"data": {
"format": <string>,
"header": [<string>, ...],
"datasets": [
{
"ds": <string>,
"vol": <string>
},
...
]
},
"program": <string>,
"options": <string>,
"rc": <string>,
"dataset_count": <number>
}
In this example, the following command returns the datasets in the APF list in JSON format.
apfadm -J -l
The resulting JSON output is as follows:
{
"data": {
"format": "DYNAMIC",
"header": ["ABC 2023285 11:59:41.00 ISF031I CONSOLE IBMU0000 ACTIVATED",
"ABC 2023285 11:59:41.00 -D PROG,APF",
"ABC 2023285 11:59:41.00 CSV450I 11.59.40 PROG,APF DISPLAY 029",
" FORMAT=DYNAMIC",
" ENTRY VOLUME DSNAME"],
"datasets": [
{
"ds": "SYS1.BPN.SBPNLOAD",
"vol": "000000"
},
...
]
},
"program": "apfadm",
"options": " -J -l",
"rc": "0",
"dataset_count": 988
}
dcat, dhead, and dtail examples
The dcat, dhead, and dtail utilities share the following common JSON schema structure:
{
"data": {
"content": <string>
},
"binary_mode": <boolean>,
"suppress_newline": <boolean>,
"program": <string>,
"options": <string>,
"rc": <string>,
"records": <number>,
"content_length": <number>
}
Specific behaviors are as follows:
-
The
contentstring escapes all double quote characters (") as follows: \\\" -
When
suppress_newlineis true, any newline characters within the record and at the end of each line are escaped as follows: \\n -
recordsreports the count of records read from the dataset. If records contain newline characters, the number of records might not match the number of lines printed.
In this example, the following command prints all records from dataset IBMUSER.DATA:
dcat -J IBMUSER.DATA
The resulting JSON output is as follows:
{
"data": {
"content": "0001 TEST data
0002 TEST data
0003 TEST data
0004 TEST data
0005 TEST data\\\"WITH DOUBLE QUOTES\\\"
"
},
"binary_mode": false,
"suppress_newline": false,
"program": "dcat",
"options": "-J ",
"rc": "0",
"records": 10,
"content_length": 816
}
In this next example, the following command prints all records from dataset IBMUSER.DATA, and escapes the newline characters between each record:
dcat -J -l IBMUSER.DATA
The resulting JSON output is as follows:
{
"data": {
"content": "0001 TEST data \\n0002 TEST data \\n0003 TEST data \\n0004 TEST data \\n0005 TEST data \\\"WITH DOUBLE QUOTES\\\" \\n"
},
"binary_mode": false,
"suppress_newline": true,
"program": "dcat",
"options": "-J -l ",
"rc": "0",
"records": 10,
"content_length": 836
}
ddls example
The JSON schema structure for ddls is as follows:
{
"data": {
"dd_list": [
{
"dsid": <number>,
"step_name": <string>,
"procstep": <string>,
"record_format": <string>,
"record_length": <number>,
"records": <number>,
"dd_name": <string>
},
...
]
},
"program": <string>,
"options": <string>,
"rc": <string>,
"dds_found": <number>
}
In this example, the following command lists the datasets that are used and generated by job J0410764:
ddls -J J0410764
The resulting JSON output is as follows:
{
"data": {
"dd_list": [
{
"dsid": 2,
"step_name": "JES2",
"procstep": "-",
"record_format": "UA",
"record_length": 133,
"records": 36,
"dd_name": "JESMSGLG"
},
{
"dsid": 3,
"step_name": "JES2",
"procstep": "-",
"record_format": "V",
"record_length": 136,
"records": 5,
"dd_name": "JESJCL"
},
{
"dsid": 4,
"step_name": "JES2",
"procstep": "-",
"record_format": "VA",
"record_length": 137,
"records": 23,
"dd_name": "JESYSMSG"
}
]
},
"program": "ddls",
"options": "-J ",
"rc": "0",
"dds_found": "3"
}
dgrep examples
The JSON schema structure for dgrep is as follows:
{
"data": {
<sequential DS name>: <string>,
<partitioned DS name>: {
<member name>: <string>,
...
},
...
},
"program": <string>,
"options": <string>,
"rc": <string>,
}
Specific behaviors are as follows:
- When you specify only one member of a PDS, such as "IBMUSER.SAMPLE(MEMBER1)",
dgrepreturns results in the same name-value pair format as it does for a sequential data set. - The
dataobject contains a name-value pair for each dataset, where the key is the dataset name and the value is the records found. - When the
-coption is enabled:- Even though the value is numerical, it is encoded as a string.
- A zero value (0) indicates that no matches are found in any PDS members.
- When the
-coption is not enabled, the output only includes datasets with matched records.- The value is a single string that contains all matched records. Each record is separated by an escaped newline character (\n).
Use **dgrep -J** to display search results in JSON format:
dgrep -J test IBMUSER.DATA.*
The resulting JSON output is as follows:
{
"data": {
"IBMUSER.DATA.SEQ": "test line\ntest line\ntest line",
"IBMUSER.DATA.PDS": {
"MEMBER1": "test line\ntest line\ntest line",
"MEMBER2": "test line\ntest line\ntest line",
"MEMBER3": "test line\ntest line\ntest line"
}
},
"program": "dgrep",
"options": "-j",
"rc": "0"
}
You can specify -J with other dgrep options on dgrep in any order. The following command shows the number of records that contain "test" in JSON format:
dgrep -J -c test IBMUSER.DATA.*
The resulting JSON output displays the results of -c for each dataset and member where matches are found:
{
"data": {
"IBMUSER.TEST.SEQ": "4",
"IBMUSER.TEST.PDS": {
"MEMBER1": "4",
"MEMBER2": "4",
"MEMBER3": "20"
}
},
"program": "dgrep",
"options": "-j",
"rc": "0"
}
dinfo example
The JSON schema structure for dinfo is as follows:
{
"data": {
"datasets": [
{
"name": <string>,
"ref_date": <string>,
"dsorg": <string>,
"recfm": <string>,
"lrecl": <string>,
"blksize": <string>,
"volume": <string>,
"used": <string>,
"alloc": <string>,
},
...
]
},
"program": <string>,
"options": <string>,
"rc": <string>,
"datasets_found": <number>
}
Specific behaviors are as follows:
-
Each dictionary in the
datasetsarray contains only the attributes requested with any of the following options:-blsu. -
The
ref_datevalue has the same format as the regular list output (YYYY/MM/DD). -
Some numerical values are always printed as strings because an unknown value is represented by "??". This behavior matches that of regular list output.
In this example, the following command shows details for dataset IBMUSER.DATA in JSON format:
dls -J -u IBMUSER.DATA
The resulting JSON output is as follows:
{
"data": {
"datasets": [
{
"name": "IBMUSER.DATA",
"ref_date": "2023/10/09",
"dsorg": "PS",
"recfm": "VB",
"lrecl": "137",
"volume": "000000"
}
]
},
"program": "dinfo",
"options": "-j -J -u ",
"rc": "0",
"datasets_found": 1
}
dmod and dsed example
The dmod and dsed utilities share the following common JSON schema structure:
{
"data": {
"changed": <boolean>,
"found": <number>,
"commands": [
<string>,
...
]
},
"program": <string>,
"options": <string>,
"rc": <string>,
"encoding": <string>
}
In this example, the following command performs string substitution in the dataset IBMUSER.DATA, and shows some execution details in JSON format:
dmod -J 's/b/a/g' IBMUSER.DATA
The resulting JSON output is as follows:
{
"data": {
"changed": true,
"found": 10,
"commands": [
"s/b/a/g"
]
},
"program": "dmod",
"options": "-J ",
"rc": "0",
"encoding": "IBM-1047"
}
dtouch examples
The JSON schema structure for dtouch is as follows:
{
"data": {
"dsname": <string>,
"dsorg": <string>,
"recfm": <string>,
"dsntype": <string>,
"primary": <number>,
"secondary": <number>,
"lrecl": <number>,
"blksize": <number>,
"dirblks": <number>,
"keylength": <number>,
"keyoffset": <number>
},
"program": <string>,
"options": <string>,
"rc": <string>,
}
Specific behaviors are as follows:
- The values for
primaryandsecondaryare the number of tracks allocated, after being converted from the unit specified in-sand-eoptions. blksizeonly has a non-zero value when-bis specified, otherwise 0 is used to let the system determine the block size.dirblks,keylength, andkeyoffsetentries are only present for partitioned or VSAM types accordingly.storclass,mgntclass, anddataclassentries are only present when options-c,-Dor-mare specified.- The value for
dsorgis"???"for VSAM types.
The following command shows JSON output for a new sequential data set with a logical record length (lrecl) of 120 and a fixed blocked record format:
dtouch -J -tseq -l120 -rFB IBMUSER.TEST.NEW
The resulting JSON output is as follows:
{
"data": {
"dsname": "IBMUSER.TEST.NEW",
"dsorg": "PS",
"recfm": "FB",
"dsntype": "BASIC",
"primary": 100,
"secondary": 10,
"lrecl": 120,
"blksize": 0
},
"program": "dtouch",
"options": "-J -t SEQ -l 120 -r FB ",
"rc": "0"
}
In this example, the following command shows JSON output for a Key Sequenced Data Set:
dtouch -J -tsKSDS -k 10:5 IBMUSER.TEST.NEW
The resulting JSON output is as follows:
{
"data": {
"dsname": "IBMUSER.TEST.NEW",
"dsorg": "???",
"recfm": "FB",
"dsntype": "EXTPREF",
"primary": 100,
"secondary": 10,
"lrecl": 120,
"blksize": 0,
"keylength": 10,
"keyoffset": 5
},
"program": "dtouch",
"options": "-J -t KSDS -l 120 -k 10:5 ",
"rc": "4"
}
dwhence examples
The JSON schema structure for dwhence is as follows:
{
"data": {
"found": <boolean>,
"result": <string>,
"member": <string>,
"search_list": [
<string>,
...
]
},
"program": "dwhence",
"options": "-J ",
"rc": "0"
}
Specific behaviors are as follows:
resultis the name of the first dataset that contains the member, and is only present when the member was successfully found andfoundistrue.
In this example, the following command looks for member 'DATA' in a concatenation and show results in JSON format:
dwhence -J DATA DATASET.ONE:DATASET.TWO:DATASET.THREE
The resulting JSON output is as follows:
{
"data": {
"found": true,
"result": "DATASET.ONE",
"member": "DATA",
"search_list": [
"DATASET.ONE",
"DATASET.TWO",
"DATASET.THREE"
]
},
"program": "dwhence",
"options": "-J ",
"rc": "0"
}
If the member is not found, the resulting JSON output is as follows:
{
"data": {
"found": false,
"member": "DATA",
"search_list": [
"DATASET.ONE",
"DATASET.TWO",
"DATASET.THREE"
]
},
"program": "dwhence",
"options": "-J ",
"rc": "8"
}
jls examples
The JSON schema structure for jls is as follows:
{
"data": {
<JOB ID string> : {
"owner": <string>,
"name": <string>,
"id": <string>,
"status": <string>,
"ccode": <string>,
"jobclass": <string>,
"serviceclass": <string>,
"priority": <string>,
"asid": <string>,
"creationdate": <string>,
"creationtime": <string>,
"queueposition": <string>,
"programname": <string>,
"jobtype": <string>,
},
...
},
"program": <string>,
"options": <string>,
"rc": <string>,
"jobs_found": <number>
}
In this example, the following command shows all available information for job J0410764 in JSON format:
jls -J -l J0410764
The resulting JSON output is as follows:
{
"data": {
"J0410764": {
"owner": "IBMUSER",
"name": "JOBNAME",
"id": "J0410764",
"status": "CC",
"ccode": "0000",
"jobclass": "A",
"serviceclass": "?",
"priority": "1",
"asid": "0",
"creationdate": "2023/10/11",
"creationtime": "11:05:25",
"queueposition": "699",
"programname": "BPXBATCH",
"jobtype": "JOB"
}
},
"program": "jls",
"options": "-J -l ",
"rc": "0",
"jobs_found": "1"
}
In this next example, the following command shows only the ID, name, and job class attributes for job J0410764 in JSON format:
jls -J -o id,name,jobclass J0410764
The resulting JSON output is as follows:
{
"data": {
"J0410764": {
"id": "J0410764",
"name": "JOBNAME",
"jobclass": "A"
}
},
"program": "jls",
"options": "-J -o id,name,jobclass ",
"rc": "0",
"jobs_found": "1"
}
mvscmd and mvscmdauth examples
The JSON schema structure for mvscmd and mvscmdauth is as follows:
{
"data": {
"program": <string>,
"STEPLIB": <string>,
"DDs": [
{
"type": <string>,
"ddname": <string>,
"dsname": <string>,
"name": <string>,
"path": <string>,
"status": <string>,
"retained": <boolean>,
"list": [
{
"type": <string>,
"ddname": <string>,
"dsname": <string>,
"path": <string>,
"name": <string>,
"status": <string>,
},
...
],
},
...
]
},
"program": <string>,
"options": <string>,
"rc": <string>
}
Specific behaviors are as follows:
STEPLIBis a single string that contains the value of the STEPLIB environment variable, including the value for argument--STEPLIBif it was specified. The value is"none"when no STEPLIB is used.DDsis a list of objects, one for each Data Definition added as a--<ddname>=<value>option in the command.- Each object in this list contains the
typeandddnameattributes, and additional attributes are added according to the type of Data Definition. - For concatenations, the
listvalue is a list of objects.
- Each object in this list contains the
In this example, the following command invokes program IEFBR14 and allocates a dummy Data Definition, and a dataset concatenation:
mvscmd -J --pgm=iefbr14 --mydd=dummy --myconcat=IBMUSER.DATA.A:IBMUSER.DATA.B
The resulting JSON output is as follows:
{
"data": {
"program": "IEFBR14",
"STEPLIB": "none",
"DDs": [
{
"type": "dummy",
"ddname": "MYDD"
},
{
"type": "concatenation",
"ddname": "MYCONCAT",
"list": [
{
"dsname": "IBMUSER.DATA.A",
"type": "dataset",
"status": "SHR"
},
{
"dsname": "IBMUSER.DATA.B",
"type": "dataset",
"status": "SHR"
}
]
}
]
},
"program": "mvscmd",
"options": "-J --pgm=iefbr14 --mydd=dummy --myconcat=IBMUSER.DATA.A:IBMUSER.DATA.B ",
"rc": "0"
}
opercmd example
The JSON schema structure for opercmd is as follows:
{
"data": {
"output": <string>
},
"timestamp": <string>,
"timeout": <number>,
"command": <string>,
"console": <string>,
"program": <string>,
"options": <string>,
"rc": <string>
}
Specific behaviors are as follows:
-
The
timestampstring has the same format as the regular output (YYYYDDD HH:MM:SS.00). -
The
timeoutvalue is expressed in hundredths of a second. -
The
timeoutandconsoleentries are only added when-Tor-care specified.
In this example, the following command shows the output from command 'D IPLINFO' in JSON format, including the generated console ID and specified timeout:
opercmd -J -c 111 -T 200 'd iplinfo'
The resulting JSON output is as follows:
{
"data": {
"output": "IEE254I 17.51.56 IPLINFO DISPLAY 808\n SYSTEM IPLED AT 10.51.53 ON 10/05/2023\n RELEASE z/OS 02.05.00 LICENSE = z/OS\n USED LOADQ5 IN SYS0.IPLPARM ON 0A5C0\n ARCHLVL = 2 MTLSHARE = N\n VALIDATED BOOT: NO\n IEASYM LIST = (X9,R5,U9,L)\n IEASYS LIST = (ST,LN,RA,X9,LZ) (OP)\n IODF DEVICE: ORIGINAL(0ABCD) CURRENT(0ABCD)\n IPL DEVICE: ORIGINAL(0ABCD) CURRENT(0ABCD) VOLUME(00000)\n"
},
"timestamp": "2023284 17:51:56.00",
"timeout": 200,
"command": "D IPLINFO",
"console": "USER0111",
"program": "opercmd",
"options": "-J -c 111 -T 200 ",
"rc": "0"
}
pjdd example
The JSON schema structure for pjdd is as follows:
{
"data": {
"content": <string>
},
"program": <string>,
"options": <string>,
"rc": <string>,
"content_length": <number>
}
Specific behaviors are as follows:
-
The
contentstring escapes all newline (\n) and double quote (") to enable serializing of the JSON output. -
If a DD is empty, the
contentstring contains a single space (" ") andcontent_lengthis set to 0. -
When the output contains records from more than one DD, all records are printed in the order that they are read, with no separation between them. This can occur when you filter by step name or use wildcards.
In this example, the following command prints the content of DD JESJCL for job J0410764:
pjdd -J J0410764 JESJCL
The resulting JSON output is as follows:
{
"data": {
"content": " 1 //JOBNAME JOB ,IBMUSER,MSGLEVEL=(1,1), J0410764\\n // MSGCLASS=A,CLASS=A,NOTIFY=&SYSUID\\n IEFC653I SUBSTITUTION JCL - ,IBMUSER,MSGLEVEL=(1,1),MSGCLASS=A,CLASS=A,NOTIFY=IBMUSER\\n 2 //STEP1 EXEC PGM=BPXBATCH,PARM='PGM /bin/sleep 5'\\n 3 //SYSIN DD * GENERATED STATEMENT\\n"
},
"program": "pjdd",
"options": "-J ",
"rc": "0",
"content_length": "364"
}
zinfo example
The JSON schema structure for zinfo is as follows:
{
"data": {
<string>: {
<string>: <string>,
...
},
...
},
"program": <string>,
"options": <string>,
"rc": <string>
}
Specific behaviors are as follows:
datacontains an object for each of the data types requested, where the key is the information type.
In this example, the following command shows the system details in JSON format:
zinfo -J -t sys
The resulting JSON output is as follows:
{
"data": {
"sys_info": {
"arch_level": "2",
"product_owner": "IBM CORP",
"product_name": "z/OS",
"product_version": "02",
"product_release": "05",
"product_mod_level": "00",
"sys_name": "ZOAU9",
"hw_name": "Z00",
"lpar_name": "ZOAU9",
"vm_name": "",
"sysplex_name": "ZPLEX9",
"primary_jes": "JES2",
"ipl_volume": "ZOAUV",
"smf_name": "ZOAU9"
}
},
"program": "zinfo",
"options": "-J -t sys ",
"rc": "0"
}