Example 8: Read a CICS VSAM file sequentially

In the following example, Z Data Tools Service Provider REST API calls are issued to start a persistent session to read records in a CICSĀ® VSAM data set, using a template to map fields in each record.

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=zdtExample4
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" : true
    }
}

This request will read one record from the beginning of the VSAM file MYKSDS in CICS region CICSR01. Any records read will be mapped in the response by the template that was found in MY.TEMPLATE(MYKSDS) when the SAR file was created.

The service provider will persist a Z Data Tools session because session is set to true. The session will remain active until a subsequent request is made with session set to false, or a timeout period of 300 seconds (5 minutes) elapses with no activity on the session. This timeout period is preset in the service archive.

The caller can expect a token to be returned on an initial request when session is set to true, and can use the token on subsequent calls without the need to pass a Basic Authorization header.

Successful response

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

{
    "records" : 
    [
        {
            "layouts" : 
            [
                {
                    "CUSTOMER-ADDRESS" :
                    {
                        "CUSTOMER-NO" : 5788,
                        "CUSTOMER-STREET" : "177A BLEEKER STREET",
                        "CUSTOMER-CITY" : "NEW YORK",
                        "CUSTOMER-COUNTRY" : "USA"    
                    }
                }
            ]
        }
    ] ,
    "token" : "zhRKQMhg8fXy8PX39/D3+GDx9vHz+PA="
}

Subsequent read requests

The API caller can now make subsequent requests using the response token and reuse the Z Data Tools session maintained by the service provider. For example:

{
    "operation" :
    {
        "numRecords" : 1,
        "session" : true,
        "token" : "zhRKQMhg8fXy8PX39/D3+GDx9vHz+PA="
    }
}

The API caller can continue to read one or more records at a time until a response record object has last set to true, indicating that the last record has been read. For example:

{
    "records" : 
    [
        {
            "last" : true, 
            etc.
        }
    ]
}

Ending the session

At this point, the API caller sends a request to terminate the active Z Data Tools session.

{
    "operation" :
    {
        "numRecords" : 0,
        "session" : false,
        "token" : "zhRKQMhg8fXy8PX39/D3+GDx9vHz+PA="
    }
}

Sending a request with session set to false will always terminate the Z Data Tools session, providing the token is valid. Since the caller has already read the last record, setting "numRecords" : 0 tells the service provider not to attempt to read any more records.