Generic method responses for z/OS files

A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.

Z Data Tools Service Provider generates the following JSON format in response to successful generic method requests to access z/OS files:

{
    "records" : 
    [
        {
            "last" : boolean,
            "layouts" : 
            [
                {
                    "layout" : "string",
                    "fields" : 
                    [
                        {
                            "field" : "string",
                            "type" : "string",
                            "dimension" : integer,
                            "value" : "string-number-array-or-null",
                            "error" : "string"
                        }
                    ]
                }
            ]
        }
    ] ,
    "token" : "string"
}

Key fields for a generic method response are explained in the following table:

Key Description
records An array of 0 or more record objects.
last Indicates whether the record is the last in the data source. This key is only present if the value is true.
layouts An array of 1 or more Z Data Tools layouts associated with the record.
layout The name of the record layout as in the Z Data Tools template or copybook.
fields An array of 1 or more data fields within the layout.
field The name of the data field. If no template or copybook was specified when connecting to the data source, the name DATA is used.
type The Z Data Tools data type of the field. For a list of data types, see Dynamic Template panel.
dimension If the field is an array, the dimension of the array. For example, a value of 2 represents a two-dimensional array. This key is only present if the data field is an array.
value The value of the data field. Can be a string, a number, an array, or null. A null value means the value could not be determined and an error key-value pair is generated.
error Short error text explaining why the field value is null. For example:
  • The field is mapped past the end of the record.
  • The field is truncated.
  • The field does not contain data in a format that matches the data type.
token A Z Data Tools session token. A token is returned when a request sets "session" : true and does not also pass a token value. The token represents a Z Data Tools session running in the z/OSĀ® environment and can be used by subsequent requests when multiple reads by a client are required.

To end the Z Data Tools session, the client must send a request with the token and "session" : false, otherwise the session will eventually time out if inactive.