com.ibm.zosconnect.buildtoolkit

Class BindfileGenerator

  • java.lang.Object
    • com.ibm.zosconnect.buildtoolkit.BindfileGenerator


  • public class BindfileGenerator
    extends java.lang.Object
    Objects of this type are used to generate WSBind file and JSON schemas for use with the z/OS Connect supplied data transformer.
    • Constructor Detail

      • BindfileGenerator

        public BindfileGenerator(java.lang.String requestFile,
                                 java.lang.String responseFile,
                                 java.lang.String languageStructureCodePage,
                                 BindfileGenerator.Language language,
                                 BindfileGenerator.ProgramInterface pgmInt,
                                 java.lang.String program,
                                 java.lang.String structure,
                                 BindfileGenerator.CharVarying charVar,
                                 java.lang.Boolean truncateArrays,
                                 java.lang.String truncateArraysValues,
                                 java.lang.Boolean dataTruncation,
                                 java.lang.String ccsid)
                          throws java.io.IOException
        Generates a WSBind file and JSON schemas using input language structures.
        Parameters:
        requestFile - Specifies the relative or absolute path to the file or PDS containing the language structure for the request.
        responseFile - Specifies the relative or absolute path to the file or PDS containing the language structure for the response.
        languageStructureCodePage - Specifies the Java character set name for the source language structures specified by requestFile parameter, responseFile parameter. For example, for IBM® Latin-1 EBCDIC, the value is IBM037.
        language - The language for the language structures specified by the requestFile and responseFile parameters.
        pgmInt - The system of record application's interface, see BindfileGenerator.ProgramInterface for more information.
        program - The name of the target system of record application.
        structure - Specifies the names of the high-level language structures that are contained in the files that are specified in the requestFile and responseFile parameters. This parameter is valid only for C and C++ languages. The value of this parameter has the format (request,response). For example the value (ReqStruct,RespStruct) would specify a request structure named ReqStruct in the file or PDS specified by requestFile and a response structure named RespStruct in the file or PDS specified by responseFile. The default request structure name is DFHREQUEST and the default response structure name is DFHRESPONSE.
        charVar - Specifies how character fields in the language structure are mapped. See BindfileGenerator.CharVarying for more information.
        truncateArrays - Specifies whether z/OS Connect EE will attempt to recognize empty records within an array. If true and if five consecutive empty array records are detected, the array is truncated at the first such record when generating JSON. This truncation capability is only enabled for arrays with structured content, arrays of simple primitive fields are not subject to truncation. Truncation of arrays can result in a more concise representation of the data in JSON, but is not without risk. If five consecutive data records are misidentified as uninitialised storage (perhaps because they legitimately contain low values), data loss can be experienced. If truncateArrays is true and truncateArraysValues is null, then the default value for truncateArraysValues is used.
        truncateArraysValues - Specifies which values are treated as empty for truncateArrays processing. If all of the bytes of storage within a record of a structured array contain nulls then the entire record is considered to be empty. One or more of the NULL, SPACE and ZERO values can be specified in a comma separated list. Any matching combination of the selected bytes within a structured array record will cause the entire record to be identified as empty. If truncateArraysValues has a value defined, then truncateArrays must be true. Possible values are:
        • NULL The null character (0x00) is treated as empty.
        • SPACE An SBCS EBCDIC Space (0x40) is treated as empty.
        • ZERO An unsigned zoned decimal zero (0xF0) is treated as empty.
        The default is NULL.
        dataTruncation - Specifies if variable length data is tolerated in a fixed-length field structure.
        ccsid - Specifies the CCSID that is used at run time to encode character data in COMMAREA and BIT container application data structures. The default is 037 (EBCDIC).
        Throws:
        java.io.IOException - Thrown if there is a problem writing to or reading from the temporary workspace, or reading the generated WSBind and JSON schema files.
      • BindfileGenerator

        public BindfileGenerator(java.lang.String requestFile,
                                 java.lang.String responseFile,
                                 java.lang.String languageStructureCodePage,
                                 java.lang.Boolean usesCdd,
                                 BindfileGenerator.Language language,
                                 BindfileGenerator.ProgramInterface pgmInt,
                                 java.lang.String program,
                                 java.lang.String structure,
                                 BindfileGenerator.CharVarying charVar,
                                 java.lang.String charUsage,
                                 java.lang.String charOccurs,
                                 java.lang.Boolean truncateArrays,
                                 java.lang.String truncateArraysValues,
                                 java.lang.Boolean dataTruncation,
                                 java.lang.Boolean dataScreening,
                                 BindfileGenerator.DateTime dateTime,
                                 java.lang.String ccsid)
                          throws java.io.IOException
        Generates a WSBind file and JSON schemas using input language structures.
        Parameters:
        requestFile - Specifies the relative or absolute path to the file or PDS containing the language structure for the request.
        responseFile - Specifies the relative or absolute path to the file or PDS containing the language structure for the response.
        languageStructureCodePage - Specifies the Java™ character set name for the source language structures specified by requestFile parameter, responseFile parameter. For example, for IBM® Latin-1 EBCDIC, the value is IBM037. When this property is used both the requestStructure and responseStructure must name members in the same partitioned dataset.
        usesCdd - This must be set to false. The z/OS Connect supplied data transformer only supports single request and response containers specified by requestFile and responseFile.
        language - The language for the language structures specified by the requestFile and responseFile parameters. Valid values are COBOL, C, CPP, PLI-ENTERPRISE or PLI-OTHER.
        pgmInt - The system of record application's interface, see BindfileGenerator.ProgramInterface for more information.
        program - The name of the target system of record application.
        structure - Specifies the names of the high-level language structures that are contained in the files that are specified in the requestFile and responseFile parameters. This parameter is valid only for C and C++ languages. The value of this parameter has the format (request,response). For example the value (ReqStruct,RespStruct) would specify a request structure named ReqStruct in the file or PDS specified by requestFile and a response structure named RespStruct in the file or PDS specified by responseFile. The default request structure name is DFHREQUEST and the default response structure name is DFHRESPONSE.
        charVar - Specifies how character fields in the language structure are mapped. See BindfileGenerator.CharVarying for more information.
        charUsage - In COBOL, the national data type, PIC N, can be used for UTF-16 or DBCS data. This setting is controlled by the NSYMBOL compiler option. You must set the charUsage parameter to the same value as the NSYMBOL compiler option to ensure that the data is handled appropriately. This is typically set to NATIONAL when you use UTF-16.
        • DBCS Data from PIC ( n ) fields is treated as DBCS encoded data.
        • NATIONAL Data from PIC ( n ) fields is treated as UTF-16 encoded data.
        The default is NATIONAL.
        charOccurs - Specifies how character arrays in the language structure are mapped. For example, PIC X OCCURS 20. This parameter is only for use by COBOL language. The default is STRING.
        • ARRAY Character arrays are mapped to a JSON array. This means that every character is mapped as an individual JSON value.
        • STRING Character arrays are mapped to an JSON string. This means that the entire COBOL array is mapped as a single JSON string.
        truncateArrays - Specifies whether z/OS Connect EE will attempt to recognize empty records within an array. If true and if five consecutive empty array records are detected, the array is truncated at the first such record when generating JSON. This truncation capability is only enabled for arrays with structured content, arrays of simple primitive fields are not subject to truncation. Truncation of arrays can result in a more concise representation of the data in JSON, but is not without risk. If five consecutive data records are misidentified as uninitialised storage (perhaps because they legitimately contain low values), data loss can be experienced. If truncateArrays is true and truncateArraysValues is null, then the default value for truncateArraysValues is used.
        truncateArraysValues - Specifies which values are treated as empty for truncateArrays processing. If all of the bytes of storage within a record of a structured array contain nulls then the entire record is considered to be empty. One or more of the NULL, SPACE and ZERO values can be specified in a comma separated list. Any matching combination of the selected bytes within a structured array record will cause the entire record to be identified as empty. If truncateArraysValues has a value defined, then truncateArrays must be true. Possible values are:
        • NULL The null character (0x00) is treated as empty.
        • SPACE An SBCS EBCDIC Space (0x40) is treated as empty.
        • ZERO An unsigned zoned decimal zero (0xF0) is treated as empty.
        The default is NULL.
        dataTruncation - Specifies if variable length data is tolerated in a fixed-length field structure.
        dataScreening - Specifies whether application supplied data is screened for errors. The default is ENABLED.
        • 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 are 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.
        dateTime - Specifies if potential ABSTIME fields in the high-level language structure are mapped as timestamps.
        • PACKED15 Packed decimal fields of length 15 (8 bytes) are treated as CICS ABSTIME fields, and mapped as timestamps.
        • UNUSED Packed decimal fields of length 15 (8 bytes) are not treated as timestamps.
        The default is UNUSED.
        ccsid - Specifies the CCSID that is used at run time to encode character data in COMMAREA and BIT container application data structures. The default is 037 (EBCDIC).
        Throws:
        java.io.IOException - Thrown if there is a problem writing to or reading from the temporary workspace, or reading the generated WSBind and JSON schema files.
      • BindfileGenerator

        public BindfileGenerator(java.lang.String requestSchemaString,
                                 java.lang.String responseSchemaString,
                                 java.lang.String generatedRequestStructure,
                                 java.lang.String generatedResponseStructure,
                                 java.lang.String languageStructureCodePage,
                                 BindfileGenerator.Language language,
                                 BindfileGenerator.ProgramInterface pgmInt,
                                 java.lang.String program,
                                 java.lang.String structure,
                                 BindfileGenerator.CharVarying charVarying,
                                 java.lang.Boolean dataTruncation,
                                 java.lang.Boolean dataScreening,
                                 java.lang.String ccsid,
                                 java.lang.Integer characterMultiplier,
                                 java.lang.Integer characterVaryingLimit,
                                 java.lang.String characterWhitespace,
                                 BindfileGenerator.DateTime dateTime,
                                 java.lang.Integer defaultCharacterMaxLength,
                                 java.lang.Integer inlineMaxOccursLimit,
                                 java.lang.String mappingOverrides,
                                 BindfileGenerator.NameTruncation nameTruncation,
                                 java.lang.String wideCompThree)
                          throws java.io.IOException
        Generates a WSBind file and language structures using input JSON schemas.
        Parameters:
        requestSchemaString - Specifies the relative or absolute path to the JSON schema for the request.
        responseSchemaString - Specifies the relative or absolute path to the JSON schema for the response.
        generatedRequestStructure - Specifies the relative or absolute path to the file or PDS that contains the high-level language structures for the request that is generated from the JSON schema.
        generatedResponseStructure - Specifies the relative or absolute path to the file or PDS that contains the high-level language structures for the response that is generated from the JSON schema.
        languageStructureCodePage - Specifies the Java character set name for the generated language structures specified by generatedRequestStructure parameter, generatedResponseStructure parameter. For example, for IBM® Latin-1 EBCDIC, the value is IBM037.
        language - The language of the system of record application. Valid values are COBOL, C, CPP, PLI-ENTERPRISE or PLI-OTHER.
        pgmInt - The system of record application's interface, see BindfileGenerator.ProgramInterface for more information.
        program - The name of the target system of record application.
        structure - Specifies the names of the high-level language structures that are contained in the files that are specified in the generatedRequestStructure and generatedResponseStructure parameters. This parameter is valid only for C and C++ languages. The value of this parameter has the format (request,response). For example the value (ReqStruct,RespStruct) would specify a request structure named ReqStruct in the file or PDS specified by requestFile and a response structure named RespStruct in the file or PDS specified by responseFile. The default request structure name is DFHREQUEST and the default response structure name is DFHRESPONSE.
        charVarying - Specifies how character fields in the language structure are mapped. See BindfileGenerator.CharVarying for more information.
        dataTruncation - Specifies if variable length data is tolerated in a fixed-length field structure.
        dataScreening - Specifies whether application supplied data is screened for errors. The default is ENABLED.
        • 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 are 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.
        ccsid - Specifies the CCSID that is used at run time to encode character data in COMMAREA and BIT container application data structures. The default is 037 (EBCDIC).
        characterMultiplier - Specifies the number of bytes to allow for each character. The value of this parameter can be a positive integer in the range of 1 - 2147483647. All nonnumeric character-based mappings, are subject to this multiplier. Binary, numeric, zoned, and packed decimal fields are not subject to this multiplier.

        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 1 UTF-16 encoding unit. Use characterMultiplier=4 when you expect application data to contain characters that require 2 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 can be possible to store more characters in the allocated field than are valid in the JSON. Care must be taken to conform to the appropriate range restrictions.

        The default is 1.
        characterVaryingLimit - Specifies the maximum size of binary data and variable-length character data that is mapped to the language structure. If the character or binary data is larger than the value specified in this parameter, it is mapped to a container and the container name is used in the generated language structure. The value can range from 0 to the default 32767 bytes.
        characterWhitespace - Specifies how white space in values of type string is handled by z/OS Connect EE.
        • 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.
        • PRESERVCE Retains any white space in the data value.
        The default value is COLLAPSE.
        dateTime - Specifies how JSON date-time format properties are mapped to the language structure.
        • PACKED15 JSON date-time format properties are processed as a time stamp and is mapped to CICS ABSTIME format.
        • STRING JSON date-time format properties are processed as text.
        The default is PACKED15.
        defaultCharacterMaxLength - Specifies the default array length of character data in characters for mappings where no length is implied in the JSON schema. The value of this parameter can be a positive integer in the range of 1 - 2147483647. The default is 255.
        inlineMaxOccursLimit - Specifies whether inline variable repeating content is used based on the maxItems JSON schema keyword. Variably repeating content that is mapped inline is placed in the current container with the rest of the generated language structure. The variably repeating content is stored in two parts, as a counter that stores the number of occurrences of the data and as an array that stores each occurrence of the data. The alternative mapping for variably repeating content is container-based mapping, which is not supported by the z/OS Connect supplied data transformer.

        The value of inlineMaxOccursLimit can be a positive integer in the range of 1 - 32767. A value of 1 ensures that optional elements are mapped inline, otherwise the value of the maxItems JSON schema property must be less than the value of inlineMaxOccursLimit.

        The default is 1.
        mappingOverrides - Specifies whether the default behaviour 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 they are unique.
        • INTEGER-AS-PIC9 For COBOL only. This option generates language structures which contain integer values from the JSON schema as numerals rather than alphanumeric characters.
        • LESS-DUP-NAMES This option generates non-structural structure field names with _value at the end of the name to enable direct referencing to the field.

        For example, in the following PLI language structure, when mappingOverrides=LESS-DUP-NAMES is specified, level 12 field streetName is suffixed with _value:

          09 streetName,
         12 streetName CHAR(255) VARYING
         UNALIGNED,
         12 filler BIT (7),
         12 attr_nil_streetName_value BIT (1), 
                    
        The resulting structure is as follows:
          09 streetName,
         12 streetName_value CHAR(255) VARYING
         UNALIGNED,
         12 filler BIT (7),
         12 attr_nil_streetName_value BIT (1), 
                    
        The default is UNDERSCORES-AS-HYPHENS for COBOL and SAME-AS-MAPPING-LEVEL for other languages.
        nameTruncation - Specifies whether JSON names are truncated from the left or the right. The build toolkit truncates JSON names to the appropriate length for the high-level language specified; by default names are truncated from the right.
        • RIGHT Names are truncated from the right.
        • LEFT Names are truncated from the left.
        wideCompThree - Controls the maximum size of the packed decimal variable length in the generated COBOL or PL/I language structure.
        • YES The build toolkit supports the maximum size of 31 when generating the COBOL language structure type COMP-3.
        • {code NO} The build toolkit limits the packed decimal variable length to 18 when generating the COBOL language structure type COMP-3. If the packed decimal size is greater than 18, message DFHPI9022W is issued to indicate that the specified type is being restricted to a total of 18 digits.
        The default is YES.
        Throws:
        java.io.IOException - Thrown if there is a problem writing to or reading from the temporary workspace, or generating the WSBind file.
    • Method Detail

      • getBindFile

        public byte[] getBindFile()
        Returns the generated WSBind file.
        Returns:
        The contents of the WSBind file in a byte[].
      • getRequestSchema

        public java.lang.String getRequestSchema()
        Returns a String containing the request JSON schema for the generated WSBind file.
        Returns:
        A JSON schema.
      • getResponseSchema

        public java.lang.String getResponseSchema()
        Returns a String containing the response JSON schema for the generated WSBind file.
        Returns:
        A JSON schema.