Service-level data conversion customization

For each service, you can specify to exclude special, non-printable control characters or suppress low values or empty tags from the JSON response messages. You can also specify whether and how to initialize fields in the input message.

These options can be configured per service by clicking Advanced Options in the service project editor.

Note:

Service-level data conversion occurs after input message fields are read. During runtime, input message field data is determined by using following order of precedence:

The JSON response value.
The default value from API mapping, which is specified in the API toolkit API editor.
The default value from service definition, which is specified in the API toolkit service interface editor.
Values that are specified through Service-level data conversion customization options.

Table 1. Input options
Option	Description
Initialize fields	Select this option to initialize fields in the input data structure if a default value is not specified and either the field is omitted from the input interface, or the field is included but the respective JSON tag is not received at run time. When this option is selected, the fields are initialized based on the data type: Non-numeric data fields are initialized with spaces. Numeric data fields are initialized with zeros. Numeric fields with USAGE DISPLAY are initialized as EBCDIC representation of zeros. Composite fields are initialized with low values. By default, fields are not initialized.
Enforce minimum array occurrence	Enforces the minimum number of array occurrence in the input data structure as defined in the copybook. By default, minimum array occurrences are enforced.
Imported IMS large data structure starts with `LLZZTRANCODE` fields	When disabled, the imported request IMS large data structure does not declare leading LL, ZZ, TRANCODE fields and therefore generated LL, ZZ, TRANCODE fields are used when creating the first message segment to send to IMS. This is the default option. When enabled, the imported request IMS large data structure declares leading LL, ZZ, TRANCODE fields and therefore the existing LL, ZZ, TRANCODE fields are used when creating the first message segment to send to IMS. This option applies only to request service interfaces in IMS Service and IMS LDS projects. Whether enabled or disabled, the values of LL and TRANCODE are set by IBM® z/OS® Connect . Note: If the structure does declare these leading fields, and this option is disabled, request data will appear shifted by up to 12 bytes to the right. If the structure does not declare these leading fields, and this option is enabled, request data will appear shifted by up to 12 bytes to the left. This option is provided by the IMS large data structure support capability. To learn more, see Capabilities compatibility.
Truncate last character field in IMS large data structure or Truncate last character field in IMS message segment	When enabled, the last field of the last data structure in the request IMS large data structure or message segment will be truncated based on the length of the corresponding request JSON, or by a default value. To learn more about how the default value is determined, see Defining service fields. Note: This option applies only to the last field of the last data structure for the following types of services: IMS Large Data Structure IMS message segment This option only applies when the last field is of type CHAR, is not a redefining item, is not an array, and is not contained by an array. This option is provided by the ibm.services.wvservice.truncateInputLastCharField capability. To learn more, see Capabilities compatibility.

Table 2. Output options
Option	Description
Trim leading whitespace	Select this option to trim leading whitespace from JSON property values in the output messages. By default, leading whitespace is not trimmed.
Trim trailing whitespace	Select this option to trim trailing whitespace from JSON property values in output messages. By default, trailing whitespace is trimmed.
Escape control characters	Select this option to escape non-printable control characters, such as tokens or control blocks, in JSON property values as `\uNNNN` for necessary internal processing, instead of removing them. By default, control characters are omitted, not escaped. For the list of machine-dependent control characters, see Special characters removed in JSON responses by default.
Omit fields with uniform byte values	Select this option to omit the JSON name-value pair for a non-numeric field from the JSON output message when the data for the field is composed of the same byte value repeated throughout, such as all 0x00 or all 0xFF. By default, this option is not selected. Specify the hexadecimal value that all bytes in a non-numeric field must contain to be omitted in the Value to use for field omission field. The default value is 00.
Omit empty fields	Select this option to omit JSON tags that contain an empty string (`"tag":""`) from JSON output messages after whitespace and control characters are processed. By default, empty tags are not omitted.
Enforce minimum array occurrence	Enforces the minimum number of array occurrence in the output data structure as defined in the copybook. By default, minimum array occurrences are enforced.
Imported IMS large data structure starts with `LLZZ` fields	When disabled, the imported response IMS large data structure does not declare leading LL, ZZ fields and therefore the response data is assumed to start at the first byte of the DATA portion of the first message segment received from IMS. This is the default option. When enabled, the imported response IMS large data structure declares leading LL, ZZ fields and therefore the response data is assumed to start at the fifth byte of the DATA portion of the first message segment received from IMS. This option applies only to response service interfaces in IMS Service and IMS LDS projects. Note: If the structure does declare these leading fields, and this option is disabled, response data will appear shifted 4 bytes to the right. If the structure does not declare these leading fields, and this option enabled, response data may appear to be shifted 4 bytes to the left. The LL field in the response data structure is not interpreted as the length of the segment. This option is provided by the IMS large data structure support capability. To learn more, see Capabilities compatibility.