Example 12: Read from a position within an IMS database

In the following example, Z Data Tools Service Provider REST API calls are issued to access an IMS™ database mapped by a ZDT/IMS view, and read one segment from a specified key position.

This example assumes that a service archive has been created and deployed that maps an IMS database with a matching view. For example, the service archive could be created using the following properties file:

name=fmExample12
description=IFB2:HDOU#1 MAPPED BY MY.IMS.VIEW(HDOU#1)
version=1.0
provider=zdatatools
host=10.1.1.2
port=9043
userid=admin
passwd=s3cr3t
ssid=IFB2
database=HDOU#1
psbMember=PHDOU#1
pcbNumber=1
regionType=BMP
view=MY.IMS.VIEW(HDOU#1)
timeout=300
connid=default

This example maps an IMS database HDOU#1 in subsystem IFB2 with PSB member PHDOU#1. The pcbNumber=1 tells Z Data Tools to use the first PCB in the PSB member. The region type is BMP and the database is mapped by the ZDT/IMS view found in MY.IMS.VIEW(HDOU#1). 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 an IMS data resource requires an HTTP Basic Authorization header so that the caller can be authenticated for subsequent access to IMS 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 view 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" : 
    {
        "numSegments" : 1,
        "session" : false
    } ,
    "position" : 
    {
        "segmentKeys" :
        [
            {
                "segmentName" : "PARTROOT",
                "keyValue" : "02922399-001",
                "operator" : "EQ"
            }
        ]
    }  
}

This request reads one segment from the nominated position within the IMS database HDOU#1 in IMS subsystem IFB2. The request will use the ZDT/IMS view IMS.VIEW(HDOU#1) to map out the segment fields in the response.

The service provider will not persist a ZDT/IMS session because session is set to false.

Successful response

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

{
    "segments": 
    [
        {
            "PARTROOT": 
            {
                "PARTROOT": 
                {
                    "ROOT-KEY": "922399-001",
                    "ROOT-SPACES": " ",
                    "ROOT-TYPE": "02",
                    "ROOT-WOSNAME": "CONNECTOR"
                }
            }
        }
    ]
}