Defining service fields

Before you begin

zosConnect-2.0 Applies to zosConnect-2.0.

If the service interface file is not already opened in the service project interface in Project Explorer, go to the service-interfaces/ folder for your project and double-click the service interface file (.si).

From the service project interface, you can edit service fields by using the Edit field wizard. Access the Edit field wizard for a given service field by right-clicking a service field, and selecting Edit field. You can also access the Edit field wizard by selecting a service field, and then clicking the Edit field icon in the Service Interface Editor.

Overview of the Edit Field wizard

Defining array counters

Array counters can be used to optimize the request and response JSON for services that use arrays. For request interfaces, an array counter is automatically set to the number of array entries received in the request JSON for the respective array. For response interfaces, an array counter indicates the number of array entries to include in the response JSON from the respective array.

Array counters are defined by specifying a numeric service field to be used as a counter for fixed-length or variable-length arrays.

The following example of a service interface demonstrates where an array counter, F_COMMENT_CNT, can be used to define the number of F_COMMENT array entries within a service interface. Also included in this example is a fixed-length array, F_ROUTINGCODE, which is counted by F_ROUTINGCODE_CNT.

Defining Boolean fields

Service fields can be exposed in JSON payloads as type Boolean to create more easily consumable APIs. Boolean service fields allow for the definition of specific request and response conditions to process true or false values for a given service field, while leaving the underlying COBOL or PL/I application field values unchanged.

To expose a given service field as Boolean, select the Boolean option in the Override data type property of the Edit Field wizard.

Specify the following properties using the Edit Field wizard to define and use Boolean service fields.

• Under the Request tab:
  • The True value type and False value type field properties determine how service request JSON values are transformed into application data. True and false request values can be defined with the following options:
    • Single values use a precise value to determine if a service field value is true or false. Single values must be of the same datatype as the Original data type, unless hexadecimal values are used.
    • High values are byte values consisting of all 0xFF .
    • Low values are byte values consisting of all 0x00.
• Under the Response tab:
  • The True value type and False value type field properties define how service field values are determined as true for an API response. In addition to Single values, High values, and Low values options, true and false response values can be defined with the following additional options:
    • Range of values uses a specified lower and upper bound value to determine if a service field value is true or false. Value ranges are inclusive and must be of the same data type as the Original data type, unless hexadecimal values are used.
    • Multiple values consist of a delimited set of values that determine if a service field value is true or false. You can choose the delimiter that is used between values.

Once a service field has been overridden as type Boolean, it is marked in the Data Type column of the service project interface as Boolean, in parentheses. Also, when looking at service fields by using the API field-mapping editor, fields that are overridden as type Boolean are listed as Boolean fields.

The following example demonstrates how a service field that is overridden as type Boolean appears in the Service Interface Editor. In this example, the F_AVAILABLE service field is overridden to express a CHAR value as a Boolean data type in the resulting API request and response JSON.

Defining Date fields

Service fields can be exposed and consumed in JSON payloads as date string patterns in order to create effective APIs that use validated dates. Date service fields allow for the exposing of host dates as OpenAPI™ 2.0 compliant dates, while leaving the underlying COBOL or PL/I application field values unchanged.

To override a given service field as a Date, select the Date option in the Override data type property of the Edit Field wizard.

The following table contains a list of accepted host date patterns:

The following table contains all COBOL fields that are acceptable for a Date override. Only the following COBOL field types might be used for a Date override:

The following table contains all PL/I fields that are acceptable for a Date override. Only the following PL/I field types may be used for a Date override:

Numeric date override example

04 F-YYYYDDD-COMP PIC 9(07) COMP.

The following override is applied to the service field:

"F_YYYYDDD_COMP" : {
   "type" : "string",
   "format" : "date"
}

"F_YYYYDDD_COMP" : "2020-02-29"

For the request, the service takes the JSON date value of "2020-02-29" and converts it to a host date value of 2020060 using the pattern yyyyDDD. For the response, the host date value of 2020060 is converted to a JSON date value of "2020-02-29" using the same pattern, yyyyDDD.

Character date override example

04 F-DD-MM-YYYY-SBCS PIC X(10) DISPLAY.

The following override is applied to the service field:

"F_DD_MM_YYYY_SBCS" : {
   "type" : "string",
   "format" : "date"
}

"F_DD_MM_YYYY_SBCS" : "2020-02-29"

For the request, the service takes a JSON date value of "2020-02-29" and converts it to a host date value of 29/02/2020 using the pattern dd/MM/yyyy. For the response, the host date value of 29/02/2020 is converted to a JSON date value of "2020-02-29" using the same pattern, dd/MM/yyyy.

Group date override example

04 F-DD-MM-YYYY-DETAIL-SBCS.
 04 F-MM    PIC 9(02) DISPLAY.
 04 FILLER  PIC X(01) VALUE '/'.
 04 F-DD    PIC 9(02) DISPLAY.
 04 FILLER  PIC X(01) VALUE '/'.
 04 F-YYYY  PIC 0(04) DISPLAY.

The STRUCT is overridden as a character field group in the service interface editor by right-clicking the STRUCT and selecting the Redefine as CHAR field function.

The following override is applied to the service field group:

"detailSBCS_MM/dd/yyyy" : {
   "type" : "string",
   "format" : "date"
}

"detailSBCS_MM/dd/yyyy" : "2020-02-29"

For the request, the service takes the JSON date value of "2020-02-29" and converts it to a host date value of 02/29/2020 by using the pattern MM/dd/yyyy. For the response, the host date value of 02/29/2020 is converted to a JSON payload of "2020-02-29" by using the same pattern, MM/dd/yyyy.