Example 4: Read an IMS™ database sequentially

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 also requires the name of the IMS™ subsystem, the IMS™ database name, an IMS™ region type, and a File Manager/IMS view to map the data:

{
    "resource" :
    {
        "ssid" : "IFB2",
        "database" : "HDOU#1",
        "regionType" : "DLI"
    },
    "view" :
    {
        "viewName" : "IMS.VIEW(HDOU#1)"
    },
    "operation" : 
    {
        "numSegments" : 1,
        "session" : true
    }
}

This request reads one segment from the beginning of IMS™ database HDOU#1 in IMS™ subsystem IFB2 as filtered by a File Manager/IMS view that is stored in IMS.VIEW(HDOU#1). The request uses a dynamic PSB because a psbMember is not specified, and the request stipulates a region type of DLI. The request uses IMS.VIEW(HDOU#1) to map out the segment fields in the response.

The service provider will persist a File Manager/IMS session because session is set to true. The session remains active until a subsequent request is made with session set to false, or the default timeout period (5 minutes) elapses with no activity on the session.

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 resource or view parameters, or a Basic Authorization header.

Successful response

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

{
    "segments": 
    [
        {
            "segment": 
            {
                "layout": "PARTROOT",
                "segname": "PARTROOT",
                "fields":
                [
                    {
                        "field": "ROOT-TYPE",
                        "type": "AN",
                        "value": "02"
                    },
                    {
                        "field": "ROOT-KEY",
                        "type": "AN",
                        "value": "922399-001"
                    },
                    {
                        "field": "ROOT-SPACES",
                        "type": "AN",
                        "value": " "
                    },
                    {
                        "field": "ROOT-WOSNAME",
                        "type": "AN",
                        "value": "CONNECTOR"
                    }
                ]
            }
        }
    ],
    "token": "5Umys+Ng8fX18Pjx9fjy82D28/Lw9PA=" 
}

Subsequent read requests

The API caller can now make subsequent requests using the response token and reuse the FM/IMS session maintained by the service provider. For example:

{
    "operation" :
    {
        "numSegments" : 1,
        "session" : true,
        "token": "5Umys+Ng8fX18Pjx9fjy82D28/Lw9PA="
    }
}

When passing a token, the caller does not need to pass resource or view parameters as these are already known by the session that is associated with the token.

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

{
    "segments" :
    [
        {
            "last" : true,
    … other response fields
        }
    ]
}

Ending the session

At this point, the API caller sends a request to terminate the active FM/IMS session.

{
    "operation" :
    {
        "numSegments" : 0,
        "session" : false,
        "token": "5Umys+Ng8fX18Pjx9fjy82D28/Lw9PA="
    }
}

Sending a request with session set to false will always terminate the FM/IMS session, providing the token is valid. Since the caller has already read the last segment, setting "numSegments" : 0 tells the service provider not to attempt to read any more segments.