Example 2: Read a keyed record from a CICS VSAM data set

In the following example, Z Data Tools Service Provider REST API calls are issued to access a CICS® VSAM data set using a template, and read one record from a specified key position.

Initial request

An initial API call to read data from a data resource requires an HTTP Basic Authorization header so that the caller can be authenticated for subsequent access to z/OS® data resources. For example:

Authorization : Basic dXNlcmlkOnBhc3N3b3Jk

where the string after the Basic keyword represents a Base64 encoding of userid:password.

All requests with a JSON payload also require a Content-Type header with a value of application/json.

The initial request also requires the name of the data resource and optionally the name of a Z Data Tools template or copybook to map the data:

{
    "resource" : 
    {
        "resourceName" : "FI:CICSR01:MYKSDS"
    },
    "template" :
    {
        "templateName" : "MY.TEMPLATE(MYKSDS)"
    },
    "operation" :
    {
        "numRecords" : 1,
        "session" : false
    },
    "position" :
    {
        "key" : "X’0007331C’"
    }
}

This request attempts to access a CICS file called MYKSDS in the CICSR01 region, position at a key with hex value X'0007331C', and read one record. The service provider will not maintain a Z Data Tools session or return a token because session is set to false.

Successful response

A successful response (HTTP Status Code 200) will be similar to the following:

{
    "records" : 
    [
        {
            "layouts" : 
            [
                {
                    "layout" : "CUSTOMER-ADDRESS",
                    "fields" : 
                    [
                        {
                            "field" : "CUSTOMER-NO",
                            "type" : "PD",
                            "value" : 7331
                        },
                        {
                            "field" : "CUSTOMER-STREET",
                            "type" : "AN",
                            "value" : "2 MACQUARIE STREET"
                        },
                        {
                            "field" : "CUSTOMER-CITY",
                            "type" : "AN",
                            "value" : "SYDNEY"
                        },
                        {
                            "field" : "CUSTOMER-COUNTRY",
                            "type" : "AN",
                            "value" : "AUSTRALIA"
                        }
                    ]
                }
            ]
        }
    ]
}

The caller does not need to issue a second request to terminate the Z Data Tools session because no session was maintained by the service provider.