Example 9: 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.

This example assumes that a service archive has been created and deployed that maps a CICS® VSAM file with a matching template or copybook. For example, the service archive could be created using the following properties file:

name=zdtExample5
description=CICSR01:MYKSDS MAPPED BY MY.TEMPLATE(MYKSDS)
version=1.0
provider=zdatatools
host=10.1.1.2
port=9043
userid=admin
passwd=s3cr3t
file=FI:CICSR01:MYKSDS
template=MY.TEMPLATE(MYKSDS)
timeout=300
connid=default

This example maps a CICS VSAM file MYKSDS in CICS region CICSR01 with a template found in MY.TEMPLATE(MYKSDS). This example assumes that the generated SAR file and APIs built in association have been deployed to your z/OS® Connect WLP server.

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 does not need to name the data resource or provide template information because this information is already contained in the service archive associated with the API. Therefore, the API caller only needs to provide the optional operation and position parameters, if required:

{
    "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" : 
            [
                {
                    "CUSTOMER-ADDRESS" :
                    {
                        "CUSTOMER-NO" : 7331,
                        "CUSTOMER-STREET" : "2 MACQUARIE STREET",
                        "CUSTOMER-CITY" : "SYDNEY",
                        "CUSTOMER-COUNTRY" : "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.