Validate Parmlib Syntax

PUT /zosmf/parmlib/<version>/<membertype>/validate

Where:

<version>

Is the URI path variable that identifies the version of the z/OS parmlib member syntax validation service.

The following value is valid: v1.

<membertype>

Is the URI path variable that identifies the member type of the z/OS parmlib member syntax validation service. For example, BPXPRM is the member type for BPXPRM01.

The value must be uppercase.

Required.

<system>

Is the URI parameter that identifies the remote system name. This remote system must be in the same sysplex and share DASD with the current system.

Optional.

<deep>

Is the URI parameter that identifies whether you need to validate all the members of all the parmlib member types from LOAD.

The variable type is boolean, and the default value is false. The value can be true only when the <membertype> is LOAD.

Optional.

<member>

Is the URI parameter that identifies a member name. For example, LOAD01.

• If the <member> variable is not used, <dataset> and <volser> also cannot be used.
• If the <member> variable is used, <dataset> is required. If the <dataset> is not cataloged, <volser> is required. If the <dataset> is cataloged, <volser> is ignored.

Optional.

<dataset>

Is the URI parameter that identifies a PDS data set name. For example, SYS0.IPLPARM is where the <member> is located.

Optional.

<volser>

Is the URI path variable that identifies volume information for <dataset>.

Optional.

<memLOAD>

Is the URI parameter that identifies a member name of LOAD. For example, LOAD01.

• If <memLOAD> is not used, then <dsnLOAD> and <volsLOAD> also cannot be used.
• If <memLOAD> is used, <dsnLOAD> is required. If <dsnLOAD> is not cataloged, <volsLOAD> is required. If <dsnLOAD> is cataloged, <volsLOAD> is ignored.

Optional.

<dsnLOAD>

Is the URI parameter that identifies a PDS data set name. For example, SYS0.IPLPARM is where <memLOAD> is defined.

Optional.

<volsLOAD>

Is the URI parameter that identifies the volume information for <dsnLOAD>.

Optional.

On successful completion, the service returns a response body, which contains a JSON object as described in Table 1 (by default). When an error occurred, reference to Table 9 and Table 10 for the description of the error response body.

Response for Scenario 1 and Scenario 2:

For successful completion response content, reference Table 8. For error response content, such as when the parmlib member can not be found in Scenario 3-1, reference Table 10 and Table 11.

Table 10 and Table 11 describe the error response body.

If you need to validate Parmlib syntax with this REST API, one of the following is suggested:

1. If you need to validate syntax on only one specific parmlib content, put the parmlib content into the request body or set <member>&<dataset>&<volser> for the specific parmlib member.
2. If you need to validate syntax on all of the members of one specified parmlib member type, use <memLOAD>&<dsnLOAD>&<volsLOAD>. The API analyzes the <memLOAD> member, finds out the specific members for this member type, and validates all of them. If <memLOAD>&<dsnLOAD>&<volsLOAD> is not set, the API analyzes the active LOADxx that is used in the current system. The data set that is used to save the LOADxx member must be cataloged.
3. If you need to validate the syntax on all the members of the supported parmlib member types, set <membertype> to LOAD and <deep> to true. If <memLOAD>&<dsnLOAD>&<volsLOAD> were set, the API analyzes the <memLOAD> member, find out all the specific members for all the supported member types and validate them all. If <memLOAD>&<dsnLOAD>&<volsLOAD> are not set, the API analyzes the active LOADxx that is used in the current system. The data set that is used to save the LOADxx member must be cataloged.

1. If you want to validate one ALLOC parmlib member content, one way is to put content directly into the request body:

   URI: 
   PUT /zosmf/parmlib/v1/ALLOC/validate
   Request body:
   TIOT SIZE(64)
   UNIT ERROR_FIELD NAME(SYSDA)
   VOLUME_MNT POLICY(WTOR)
   SPEC_WAIT       MAXNWAIT(10)
                   POLICY(WAITHOLD)
                   POLICYNW(WTOR)
   ALLC_OFFLN POLICY(WAITNOH)
                   MAXNWAIT(10)
                   POLICYNW(WTOR)
   

   In this example, we intentionally input an invalid field called “ERROR_FIELD”. The API found this error and this is the response:

   {
       "result": "failed",
       "numberOfMembers": 1,
       "numberOfFailedMembers": 1,
       "details": {
           "validationResult": "failed",
           "numOfFailure": 1,
           "failures": [
               {
                   "index": 1,
                   "location": {
                       "line": 2,
                       "position": 6
                   },
                   "currentField": "ERROR_FIELD",
                   "expectedField": [
                       "NAME"
                   ],
                   "afterField": "UNIT",
                   "input": "UNIT ERROR_FIELD NAME ( SYSDA ) ",
                   "message": "SYNTAX ERROR 1 START AT LINE 2, POSITION 6: \n CURRENT FIELD : ERROR_FIELD \n EXPECT NAME AFTER UNIT \n"
               }
           ]
       }
   }
   

   Another way to validate one specific parmlib member is to set <member>&<dataset> in the URI, and nothing else in the request body. For example:

   PUT /zosmf/parmlib/v1/ALLOC/validate?dataset=SYS1.PARMLIB&member=ALLOC01.

2. If you want to validate one parmlib type , such as all members of CONSOL based LOADAC, which is in SYS1.PARMLIB, you can use this URI:

   /zosmf/parmlib/v1/CONSOL/validate?memLOAD=LOADAC&dsnLOAD=SYS1.PARMLIB

   The response is as follows:

   {
       "result": "failed",
       "numberOfMembers": 1,
       "numberOfFailedMembers": 1,
       "parmlibDatasets": [
           {
               "volser": "null",
               "dataset": "XESCT.PARMLIB"
           },
           {
               "volser": "null",
               "dataset": "SYS1.PARMLIB"
           },
           {
               "volser": "null",
               "dataset": "SYS1.PARMLIB.POK"
           },
           {
               "volser": "null",
               "dataset": "SYS1.PARMLIB.INSTALL"
           }
       ],
       "details": {
           "CONSOLxx": [
               {
                   "member": "CONSOLXI",
                   "dataset": "SYS1.PARMLIB",
                   "specifiedVia": [
                       "DEFAULT",
                       "SYS1.PARMLIB(IEASYS00)"
                   ],
                   "validationResult": "failed",
                   "numOfFailure": 2,
                   "failures": [
                       {
                           "index": 1,
                           "location": {
                               "line": 16,
                               "position": 23
                           },
                           "currentField": "ALTERNATE",
                           "expectedField": [
                               "INIT",
                               "HARDCOPY",
                               "CONSOLE",
                               "DEFAULT"
                           ],
                           "afterField": ")",
                           "input": "ALTERNATE ( 3D4 ) ROUTCODE ( ALL ) AREA ( 10 ) PFKTAB ( 12 ) RTME ( 1/4 ) RBUF ( 15 ) AUTH ( MASTER ) DEL ( R ) UNIT ( 3270-X ) MFORM ( S ) ",
                           "message": "SYNTAX ERROR 1 START AT LINE 16, POSITION 23 :\nCURRENT FIELD : ALTERNATE\n  EXPECT ONE OF THE FOLLOWINGS AFTER ) : \n    [INIT, HARDCOPY, CONSOLE, DEFAULT] \n"
                       },
                       {
                           "index": 2,
                           "location": {
                               "line": 22,
                               "position": 23
                           },
                           "currentField": "ALTERNATE",
                           "expectedField": [
                               "INIT",
                               "HARDCOPY",
                               "CONSOLE",
                               "DEFAULT"
                           ],
                           "afterField": ")",
                           "input": "ALTERNATE ( 3E0 ) ROUTCODE ( ALL ) AREA ( 14 ) PFKTAB ( 24 ) RBUF ( 15 ) AUTH ( ALL ) UNIT ( 3270-X ) MFORM ( S ) ",
                           "message": "SYNTAX ERROR 2 START AT LINE 22, POSITION 23 :\n CURRENT FIELD : ALTERNATE \n  EXPECT ONE OF THE FOLLOWINGS AFTER ) : \n    [INIT, HARDCOPY, CONSOLE, DEFAULT]\n"
                       }
                   ]
               }
           ]
       }
   }
   

3. If you want to validate members of all parmlib types based on specified LOADxx, use:

   PUT/zosmf/parmlib/v1/LOAD/validate?memLOAD=LOADAC&dsnLOAD=SYS1.PARMLIB&deep=true

   The response includes all the supported parmlib type validation results.

{
    "errorData": {
        "reason": "3",
        "messages": "The \"membertype\" value \"ALLOC0\" is not valid. Correct this value and try the request again."
    }
}