Generic method requests for IMS

The Z Data Tools Service Provider accepts the following JSON for generic method requests for access to IMS™ data.

{
    "resource" :
    {
        "ssid" : "string",
        "database" : "string",
        "psbMember" : "string",
        "pcbNumber" : "string",
        "pcbName" : "string",
        "regionType" : "string",
        "dataCcsid" : integer,
        "dbcsCcsid" : integer
    },
    "view" : 
    {
        "viewName" : “string”,
        "viewCcsid" : integer
    },
    "operation" : 
    {
        "numSegments" : integer,
        "session" : Boolean,
        "token" : “string”,
        "timeout" : integer
    },
    "position" : 
    {
        "segmentKeys" :
        [
            {
                "segmentName" : "string",
                "keyValue" : "string",
                "operator" : "string"
            }
        ]
    }  
}

Key fields for generic method requests are explained in the following table.

Note: Parameters flagged as (Required) are only required for an initial request.
Key Description
resource (Required) Parameters associated with the IMS data resource. Resource parameters are only required when performing a single or initial read from a data resource. Resource parameters are not required on subsequent read requests when a token is passed.
ssid (Required) The IMS subsystem identifier.
database (Required) The name of the IMS database.
psbMember The IMS Program Specification Block (PSB) member name. This is a member in the Z Data Tools PSB data set concatenation. If psbMember is not specified Z Data Tools will attempt to generate a dynamic PSB (if this is permitted).
pcbNumber The Program Communication Block (PCB) number. This is the relative position of the PCB within the PSB member and must be numeric. The relevant PCB can be identified using pcbNumber or pcbName. The default is 1.
pcbName Program Communication Block (PCB) name. This is the PCB label name within the PSB member. The relevant PCB can be identified using pcbNumber or pcbName.
regionType (Required) The IMS region type. Must be "BMP" or "DLI".
dataCcsid CCSID of resource alphanumeric data. Default is 037.
dbcsCcsid CCSID of graphic or double-byte data. Default is 930. This could be the same as dataCcsid and is needed to support GRAPHIC and DBCS fields.
view (Required) View parameters map the IMS database segments. View parameters are required when performing a single or initial read from an IMS resource. View parameters are not required on subsequent read requests when a token is passed.
viewName (Required) Name of a ZDT/IMS view. Example: MVS.DATASET(MYVIEW).
viewCcsid CCSID of the view. Default is 037.
operation Operation parameters affect the behavior of the service provider. All operation parameters are optional, but for performance reasons it is helpful to understand the correct use of the session and token parameters.
numSegments The number of database segments to retrieve. The acceptable range is 0 - 10000. The default is 1.
session Indicates whether to persist or end a ZDT/IMS session. A value of true instructs the service provider to start the session (if it is not already started) and keep it active for subsequent API calls. A value of false instructs the service provider to end the session when the API call is complete.
token A session token, as returned in a previous API response. The token represents an active ZDT/IMS session and can be used for subsequent reads following an initial read that sets "session" : true. A successful initial read request with "session" : true returns a token in the response.
timeout Time in seconds for which the ZDT/IMS view session can be inactive before it is terminated. Can be any value from 0 to 28800 (eight hours). The default is 300 (5 minutes).

If the value is greater than the max_timeout in the server.xml configuration, the timeout value is ignored and the max_timeout value is used instead.

position Position parameters affect the read position within the IMS database. Positioning requires knowledge of the name of and hierarchical path to the relevant database segments and the length of the segment keys. Positioning occurs before the read request is satisfied.
segmentKeys An array of database segment names and associated key values. Specify array elements in database hierarchical order. Note that the last segment listed in the array will be the segment that is positioned on.
segmentName The name of the database segment to position on or after.
keyValue The required value for the segment’s key to position on or after.
operator Logical operator for positioning based on segment/key value elements in the segmentKeys array. The operator can be EQ (equal) or GE (greater than or equal). The default is EQ.

The operator parameter only takes effect when it is specified on the last element of the segmentKeys array (that is, the segment that is being positioned on) but applies to all segment/key value assignments that are specified in the array.

  • If EQ is specified, all segment/key value elements in the array are checked for equality when positioning.
  • If GE is specified and the database root segments are key sequenced, the test "if greater than or equal to" is applied to all segment/key value elements in the array when positioning.
  • If GE is specified and the database root segments are not key sequenced, the root segment is checked for equality and the test "if greater than or equal to" is applied to all other segment/key value elements in the array when positioning.