Welcome
Working with Z Data Tools
Z Data Tools Service Provider for z/OS® Connect Enterprise Edition
Z Data Tools Service Provider for IBM® z/OS® Connect Enterprise Edition enables client applications to access IBM Z data sources using z/OS Connect.
Requests and responses
The Z Data Tools Service Provider expects JSON payloads from z/OS® Connect-defined APIs representing requests, and passes back JSON payloads as responses to these requests.
Generic method responses for IMS™
A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.

PDF documentation
About this document
Summary of changes
Working with Z Data Tools
- Z Data Tools overview
- Getting started with Z Data Tools
- Viewing and changing data sets
  To view data stored in a supported data set, use the View Utility or the Edit Utility.
- Creating and editing templates
  For many tasks performed with Z Data Tools, you can manipulate your view of a data set by applying a template.
- Working with the Template List
  Display a list of templates and perform actions on them.
- Filtering records with templates
- Managing data sets
- Using Z Data Tools utilities
- Tape Specific Functions
- Disk/VSAM Data Functions
- OAM Functions
- Using UNIX™ System Services and the Hierarchical File System
- Introduction to programming with Z Data Tools functions
- Enhancing Z Data Tools processing
  You can enhance normal processing of a number of Z Data Tools tasks by supplying a procedure that runs in conjunction with the Z Data Tools process.
- Redefines criteria
  Redefines criteria can be specified for a field with a REDEFINES clause, or a field that is the target of a REDEFINES clause.
- Enhanced ISPF: Reference List, Search, Change, and PDSE Workbench
  Z Data Tools provides several enhancements to the basic facilities that are available in an ISPF session: Enhanced Reference List, Enhanced Search, Enhanced Change, Indexed Search, and PDSE Workbench.
- Z Data Tools Service Provider for z/OS® Connect Enterprise Edition
  Z Data Tools Service Provider for IBM® z/OS® Connect Enterprise Edition enables client applications to access IBM Z data sources using z/OS Connect.
  - Methods for accessing IBM Z data sources
    Z Data Tools Service Provider supports two methods for accessing data: generic and specific.
  - Single reads versus multiple reads
    Regardless of which method for accessing data is used (generic or specific), the Z Data Tools Service Provider starts a Z Data Tools “view” session to read records from a given data resource.
  - Requests and responses
    The Z Data Tools Service Provider expects JSON payloads from z/OS® Connect-defined APIs representing requests, and passes back JSON payloads as responses to these requests.
    - Generic method requests for z/OS® files
      The Z Data Tools Service Provider accepts the following JSON for generic method requests to access z/OS® files.
    - Generic method requests for IMS™
      The Z Data Tools Service Provider accepts the following JSON for generic method requests for access to IMS™ data.
    - Generic method requests for Db2®
      The Z Data Tools Service Provider accepts the following JSON for generic method requests for access to Db2® data.
    - Generic method responses for z/OS® files
      A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.
    - Generic method responses for IMS™
      A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.
    - Generic method responses for Db2®
      A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.
    - Specific method requests for z/OS® files
    - Specific method requests for IMS™
      The Z Data Tools Service Provider accepts the following JSON for specific method requests for IMS™ data.
    - Specific method requests for Db2®
    - Specific method responses for z/OS® files
      A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.
    - Specific method responses for IMS™
      A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.
    - Specific method responses for Db2®
      A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.
  - Creating z/OS® Connect APIs
    Installing the z/OS® Connect EE API Editor into your Eclipse environment adds a perspective that allows you to create a z/OS Connect EE API Project.
  - Using the Build Toolkit plug-in
    z/OS® Connect provides a Build Toolkit (zconbt) for creating service archive (SAR) files. SAR files are used during z/OS Connect API creation to associate APIs with service providers such as Z Data Tools Service Provider.
  - Swagger documentation
    The z/OS® Connect API Editor automatically generates Swagger documentation during API creation. A swagger.json file is created within the API project.
  - Security
    The Z Data Tools Service Provider for z/OS® Connect EE requires an API caller to pass an HTTP Basic Authorization header that identifies the user ID and password of the caller.
  - Troubleshooting
    Use this information to troubleshoot Z Data Tools API request failures.
  - Example scenarios
    The following examples illustrate the sequence of Z Data Tools Service Provider REST API calls used to process some common file types under different scenarios.
- Function and panel reference lists
Z Data Tools Reference
Messages
XML definitions for a template
Accessibility features for Z Data Tools
Accessibility features assist users who have a disability, such as restricted mobility or limited vision, to use information technology content successfully.
Notices
Glossary

Generic method responses for IMS™

A successful response generates an HTTP status code of 200. Failures produce an appropriate status code and an error message describing the cause of the failure.

Z Data Tools Service Provider generates the following JSON format in response to a successful generic method request for IMS™ data:

{
    "segments" :
    [
        {
            "last" : boolean,
            "layout" : “string”,
            “segname” : “string”,
            "fields" :
            [
                {
                    “field" : "string",
                    "type" : "string",
                    "dimension" : integer,
                    "value" : "string-number-array-or-null",
                    "error" : "string"
                }
            ]
        }
    ] ,
    "token" : "string"
}

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


Key	Description
segments	An array of 0 or more segments from the IMS™ data resource.
last	If present, is indicates that the segment is last in the IMS™ resource.
layout	The name of the segment layout that was used to map this segment.
segname	The name of the IMS™ database segment.
fields	Each segment is represented as an array of 1 or more fields.
field	The name of the layout field.
type	The Z Data Tools data type of the field. For a list of data types, see Dynamic Template panel.
dimension	If the field is an array, the dimension of the array. For example, a value of 2 represents a two-dimensional array.
value	The value of the data field. A null value means the value could not be determined.
error	Short error text explaining why the field value is null (that is, why the value could not be determined.
token	A Z Data Tools session token. A token is returned when a request sets `"session" : true` and does not also pass a token value. The token represents a Z Data Tools/IMS session running in the z/OS® environment and can be used by subsequent requests when multiple accesses by a client are required. To end the ZDT/IMS session, the client must send a request with the token and `"session" : false`, otherwise the session will eventually time out if inactive.