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.

All JSON-enabled utilities have the following command line options available:

  • The -j option prints a serialized JSON string with no added whitespace.

  • The -J option 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 data is always an object and can contain different key-value pairs for different utilities.

  • The options string contains all the options and arguments passed to the command, and always includes a trailing space.

  • Use of the -J option implicitly enables -j, which means that the options string returned by -J also contains the output provided by -j.

  • The rc value is always a string.



Base schema examples

Each utility populates the base schema data object with its own specific key-value pairs. The following examples show the overall JSON schema structure and the specific key-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 content string escapes all double quote characters (") as follows: \\\"

  • When suppress_newline is true, any newline characters within the record and at the end of each line are escaped as follows: \\n

  • records reports 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"
}


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 datasets array contains only the attributes requested with any of the following options: -blsu.

  • The ref_date value 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"
}


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>,
        },
        ...
    },
    "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"
        }
    },
    "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"
}


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 timestamp string has the same format as the regular output (YYYYDDD HH:MM:SS.00).

  • The timeout value is expressed in hundredths of a second.

  • The timeout and console entries are only added when -T or -c are 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 content string escapes all newline (\n) and double quote (") to enable serializing of the JSON output.

  • If a DD is empty, the content string contains a single space (" ") and content_length is 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:

  • data contains 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"
}