Generic method requests for z/OS® files

The File Manager Service Provider accepts the following JSON for generic method requests to access z/OS® files.

{
    "resource" :
    {
        "resourceName" : "string",
        "volser" : "string",
        "dataCcsid" : number,
        "dbcsCcsid" : number,
    },
    "template" :
    {
        "templateName" : "string",
        "tmplCcsid" : number,
        "copybookName" : "string",
        "language" : "string",
        "options" : "string"
    },
    "operation" :
    {
        "numRecords" : integer,
        "session" : boolean,
        "token"   : "string"
        "timeout" : number
    },
    "position" :
    {
        "record" : integer,
        "key" : "string"
    }
}

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

Key Description
resource Parameters associated with the 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.
resourceName Name of the data resource. Examples: MVS.DATASET, /uss/data.dat, FI:APPLID:CICSFILE, TD:APPLID:CICSTDQ, TS:APPLID:CICSTSQ, MQ:QMGR:QNAME

where APPLID represents the application ID of the target CICS region, and QMGR represents the MQ system.
volser Data resource volume serial, if applicable.
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.
template Template parameters map the data resource and can be a File Manager template or a copybook. Template parameters are only required when performing a single or initial read from a data resource. Template parameters are not required on subsequent read requests when a token is passed.
templateName Name of a File Manager template that maps the data resource. Example: MVS.DATASET(TEMPLATE).
tmplCcsid CCSID of template or copybook. Default is 037.
copybookName Name of a copybook that maps the data resource. A copybook can be used to map a data resource instead of a File Manager template.
language Language of the copybook. Can be COBOL, PLI, HLASM, or AUTO. AUTO can be used when the copybook language is either COBOL or PLI.
options Compilation options for the copybook. To map data using a copybook, File Manager compiles the copybook to determine field offsets. In some cases, special compiler options are required to accurately determine these offsets. The options parameter can be used for this purpose. The following options are supported:
  • COBOL:

    DBCS=,CDPC=,CAE=,MIXED=,CBLMAXRC=,RFROMn=,RTOn=

  • PLI:

    BIN63=,DEC31=,GRAPHIC=,UNALIGNED=,PLIMAXRC=,PLILIBS=

  • HLASM:

    DBCS=,NOALIGN=,ASMMAXRC=,ASMLIBS=

For full details of the supported options refer to File Manager functions.

Multiple options can be comma separated. The options parameter is ignored if the language parameter is not specified.
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.
numRecords The number of records to retrieve. The acceptable range is 0 - 10000. The default is 1.
session Indicates whether to persist or end a File Manager 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 File Manager 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 File Manager 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 of the data resource. Can be a relative record position or a key position (if KSDS).
record Relative record read position. If requested, the service provider will position to the nominated relative record position before reading records. The default is 1 for an initial read, or the current record position for a subsequent read. A read is considered a subsequent read if a valid token is passed.
key Record key read position for KSDS. If requested, the service provider will position to the nominated key position or the next higher key position before reading records. The default is the first record for an initial read, or the current record position for a subsequent read. A read is considered a subsequent read if a valid token is passed.

The key value can be expressed as a string, for example: "ABC", "C'ABC DEF'", "X'C1F7'". The C'string' format must be used if the key value contains spaces or lowercase characters.

The key and record parameters are mutually exclusive.