The API provider Gradle plug-in properties and options for CICS

Define attributes in the z/OS® Connect API provider Gradle plug-in options.yaml file before you run the build from the command line. The following API provider Gradle plug-in properties and options are available to customize the generation of your API provider artifacts from an OpenAPI 2.0 document or an OpenAPI 3.0 document.

zosConnect-3.0 Applies to zosConnect-3.0.

Started task Applies to z/OS Connect Servers run by using a z/OS started task procedure.

Mandatory attributes

ccsid: Specifies the CCSID that is used at run time to encode character data in the application data structure. By default, the CCSID is set to 037. The CCSID list that the z/OS Connect Gradle plug-in supports is the same as the one supported by the CICS conversion program.
For more information about the supported list, see CICS-supported conversions in the CICS Transaction Server for z/OS 6.x documentation.
connectionRef: The ID of the zosconnect_cicsIpicConnection or the zosconnect_cicsJcicsConnection element that defines the connection to CICS.
language: Specifies the language for the code generation. Valid values are COBOL or PLI.
program: Only applicable for CICS z/OS Assets. The name of the CICS program to invoke.
Note: In an API-first scenario like this, the program typically does not exist yet. Choose the name of the new program.
programInterface: Only applicable for CICS z/OS Assets. The program interface for the CICS program. This value must be set to CHANNEL.
projectType: Specifies the properties and options to customize the generation of your artifacts from an OpenAPI definition. Valid value for an API project is provider.
provider: Must be set to cics to build an API project that is implemented by a CICS program.

Optional attributes

additionalPropertiesSize

Specifies the maximum size for each of the additional JSON properties that are not explicitly defined in the properties section of an OpenAPI document. The value of this parameter can be a positive integer in the range of 16 - 32767. The default value is 255. A field of the specified size is generated into the language structures that are produced by the Gradle plug-in. The generated language structures are able to support up to 20 additional properties.

characterMultiplier

Specifies the number of bytes allowed for each character. The value of this parameter can be a positive integer in the range of 1 - 2,147,483,647. All nonnumeric character-based mappings are subject to this multiplier. Binary, numeric, zoned, and packed decimal fields are not subject to this multiplier. The default value is 1.

This parameter can be useful if, for example, you are planning to use DBCS characters where you might opt for a multiplier of 3 to allow space for potential shift-out and shift-in characters around every double-byte character at run time.

When you set ccsid=1200 (indicating UTF-16), the only valid values for characterMultiplier are 2 or 4. When you use UTF-16, the default value is 2. Use characterMultiplier=2 when you expect application data to contain characters that require one UTF-16 encoding unit. Use characterMultiplier=4 when you expect application data to contain characters that require two UTF-16 encoding units.

Note: Setting characterMultiplier to 1 does not preclude the use of DBCS characters, and setting it to 2 does not preclude the use of UTF-16 surrogate pairs. However, if wide characters are routinely used, then some valid values will not fit into the allocated field. If a larger characterMultiplier value is used, it might be possible to store more characters in the allocated field than are valid in the JSON. Take care to conform to the appropriate range restrictions.

characterVarying

Specifies how variable-length character data is mapped to the language structure.

NO: Variable-length character data is mapped as fixed-length strings.

NULL: Variable-length character data is mapped to null-terminated strings. This value must be in quotation marks. For example, "NULL".

YES: In COBOL, variable-length character data is mapped to an equivalent representation that consists of two related elements: the data-length and the data.

The default is YES.

characterVaryingLimit

Specifies the maximum size of binary data and variable-length character data that is mapped to the language structure.

When characterVarying is set to NO or NULL the value of this parameter can be a positive integer in the range of 1 to 16777214.

When characterVarying is set to YES the value of this parameter can be a positive integer in the range of 1 to 32767.

The default is 32767.

characterWhitespace

Specify how to handle white space in values of type String.

COLLAPSE: Leading, trailing, and embedded white space is removed and all tabs, new lines, and consecutive spaces are replaced with single space characters.

REPLACE: Any tabs or new lines are replaced with the appropriate number of spaces.

PRESERVE: Retains any white space in the data value.

TRIM: Leading and trailing white space is removed.

The default is COLLAPSE

Note: This parameter does not apply to fields with a format of date-time, uri, base64Binary, or hexBinary, where white space is always collapsed.

dataScreening

Specifies whether application-supplied data is screened for errors.

ENABLED: Any application-supplied runtime data that is inconsistent with the language structure is treated as an error, and message DFHPI1010 is issued. An error response is returned to the application.

DISABLED: Data values in application-supplied runtime data that is inconsistent with the language structure are replaced by default values. For example, a zero replaces a bad value in a numeric field. Message DFHPI1010 is not issued and a normal response is returned to the application. This feature can be used to avoid INVALID_PACKED_DEC and INVALID_ZONED_DEC error responses that are generated from uninitialized output fields.

The default is ENABLED. Messages with the DFH prefix might refer to this property as DATA-SCREENING.

dataTruncation

Specifies whether variable-length data is tolerated in a fixed-length field structure.

DISABLED: If the data is less than the fixed length that z/OS Connect is expecting, z/OS Connect rejects the truncated data and issues an error message.

ENABLED: If the data is less than the fixed length that z/OS Connect is expecting, z/OS Connect tolerates the truncated data and processes the missing data as null values.

The default is DISABLED.

dateTimeFormat

Specifies how JSON date-time elements are mapped to the data structure.

PACKED15: Any JSON date-time element is processed as a timestamp and is mapped to an absolute format.

STRING: The JSON date-time element is processed as text.

The default is PACKED15.

defaultCharacterMaxLength

Specifies the default array length of character data for mappings where no length is implied in the JSON schema document.

When characterVarying is set to YES, the value of this parameter can be a positive integer in the range of 1 to 32767.

When characterVarying is set to NO or NULL the value of this parameter can be a positive integer in the range of 1 to 16777214.

The default is 255.

defaultFractionDigits

Specifies the default number of fraction digits to use on a JSON decimal schema type. For COBOL, the valid range is 0-17, or 0-30 if parameter wideComp3 is set.

The default value is 3.

extendFieldNames

The default is false.

When long JSON property names are represented in generated language structures the maximum size is two less than the language limit, which is 30 for COBOL or 31 for PL/I. This is to allow a two-character space to be used for a numerical suffix when field names clash.

Setting extendFieldNames to true will allow generated language structure fields to use the full language length. However, should a field name clash be detected, then the field name is trimmed by two and the numerical suffix added.

groupSuffix

The default is false.

In generated COBOL language structures where fields represent JSON object properties, the JSON property name can be used in multiple locations, particularly for variable length strings. In this case, a numerical suffix is added to the clashing field name.

For example,

06 myProperty.
 09 myProperty-length PIC S9999.
 09 myProperty2 PIC X(255).

For code readability, it may be desirable to have the actual string field that is named after the JSON property.

To avoid this name clash, set groupSuffix to true. This option sets the group level language structure element suffix with Grp and simple type arrays with the Arr suffix. As a result, the string field representing the JSON property available to use the JSON property name as the field name, subject to programming language rules.

For example,

06 myPropertyGrp.
 09 myProperty-length PIC S9999.
 09 myProperty PIC X(255).

inlineMaxOccursLimit

Specifies the size limit for an array before it is changed to be stored in a container. The default value is 1. If you specify inlineMaxOccursLimit=5, and the array has three elements, it remains an array. If the array has seven elements, it is transformed into a container instead.

mappingOverrides

Only applicable for API provider.

Specifies whether the default behavior is overridden when generating language structures. One or more of the options can be specified in a comma-separated list.

SAME-AS-MAPPING-LEVEL: This option generates language structures in the default style.

UNDERSCORES-AS-HYPHENS: For COBOL only. This option converts any underscores in the JSON schema to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures. If any field name clashes occur, the fields are numbered to ensure that they are unique.

INTEGER-AS-PIC9: For COBOL only. This option generates language structures that contain integer values from the JSON schema as numerals rather than alphanumeric characters.

LESS-DUP-NAMES: This option generates nonstructural structure field names with _value at the end of the name to enable direct referencing to the field.

The default is UNDERSCORES-AS-HYPHENS for COBOL.

nameTruncation

Only applicable for CICS z/OS Assets.

Specifies how JSON names are truncated. nameTruncation can be set LEFT or RIGHT. By default, names are truncated from the RIGHT.

providerExtension

Only applicable for CICS z/OS Assets.

Specifies a file extension for the generated request and response language structures. For example, if language is specified as COBOL and providerExtension is specified as cpy the following files are generated for the first operation: API00P01.cpy and API00Q01.cpy.

The default is no file extension.

providerPrefix

Specifies a prefix for the generated language structures. The value of this parameter has a maximum length of 3 characters. The first character must be either a letter or one of the following three special characters: # @ $. The remaining characters can be letters, numbers, or one of the following special characters: # @ $.

The default is API.

transId

Specifies the CICS transaction name. This value is available to the CICS Program in the EXEC Interface Block.

If this parameter is not specified, the Transaction ID value in the connection is used.

Note: A Transaction ID set on a z/OS Asset is not applied in a JCICS connection.

transIdUsage

Specifies how the transaction ID value is used. Valid values are EIB_ONLY and EIB_AND_MIRROR. If EIB_AND_MIRROR is specified, then the value of transId is used as the mirror transaction in CICS, otherwise the value is only available in the EXEC Interface Block.

If this value is not specified, the Transaction ID usage value in the connection is used.

wideComp3

For COBOL only. Specifies the maximum size of the packed decimal variable length in the COBOL data structure.

NO: The packed decimal variable length is limited to 18 when the COBOL data structure type COMP-3 is generated. If the packed decimal size is greater than 18, message DFHPI9022W is issued to indicate that the specified type is restricted to a total of 18 digits.

YES: The maximum size of 31 is supported when the COBOL data structure type COMP-3 is generated.

The default is NO.