Defining service fields

Before you begin

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

From the service interface editor, 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 button in the Service interface editor.

Overview of the Edit Field wizard

Tip: For service-level data conversion customization, see Service-level data conversion customization.

Important:

• Response service interfaces cannot contain default values in fields. If a default value is specified for a response service interface, a message will be issued in the Problems view to assist problem resolution.
• The default value can be overridden if a value is assigned in the API editor during API creation. If a value is specified in the payload at run time, the runtime value will always override the value that was specified at development time. To prevent the assigned default value from being overridden at run time, set the field to be omitted from the interface.
• The Code page conversion check box is only visible when the Data type field has a value of CHAR. To convert the code page for the CHAR type, select the Code page conversion check box; otherwise, clear it.

Defining array counters

Array counters can be used to optimize the request and response JSON for services which utilize 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.

For fixed-length or variable-length arrays, specify the following array properties using the Edit Field wizard to define and use array counters.

• Counted by indicates a numeric field that specifies the number of sequential entries used in the array. This count always starts from the first entry of the array.

  To change a counted array back to a non-counted array, select the empty line provided at the top of the drop-down list for the Counted by field.

• Minimum items defines the minimum number of expected array entries. This minimum is expressed as minItems in the JSON schema that corresponds to the service interface.

Important:

• Counters specify the number of sequential array entries in use by a service, starting with and including the first entry.
• When setting a counter for an array, the minimum expected number of array entries can be customized. This minimum is reflected in the generated JSON schema (minItems).
  • To enforce the minimum number of array occurrences for API requests and responses, you must enable the Enforce minimum array occurrence options in your service project. To learn how to enforce minimum array occurrences, see Service-level data conversion customization.

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 hex 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 datatype as the Original data type, unless hex values are used.
    • Multiple values consist of a delimited set of values which 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 will be marked in the Data Type column of the service interface editor as Boolean, in parenthesis. Also, when looking at service fields using the API field mapping editor, fields that are overridden as type Boolean will be 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 utilize 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 may 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 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" using the same pattern, MM/dd/yyyy.