Legacy Record to XML Converter Service (com.ibi.agents.XDLegacyRecordToXMLAgent)

Topics: Additional Usage Examples for the Copybook Option File

The copybook option file is an XML document that allows the following data handling options to be set:

1. Error handling options for packed (COMP-3), zoned, alphanumeric, and binary fields in bytes to XML conversion.
   • Special Character Handling. High values (X'FFFFFFFF'), low values (X'00000000'), blanks (X'40404040'), ampersands (X'50505050'), and number or pound signs (X'7b7b7b7b') may represent expected input in a customer application. These values may be handled by a custom rule rather than be parsed (and possibly throw an error) according to the type of the field.
   • Invalid Data Handling. Data that is Invalid, but does not match the special character handling types indicated above, may also be handled by a rule. This can return an arbitrary string as the contents of the field, optionally reporting the raw error bytes as an attribute. Finally, it may be specified that invalid data should throw exceptions.
2. Leading zeros option for packed and zoned fields.

The Copybook option file is identified by the Copybook Option File Location parameter during the service configuration (com.ibi.agents.XDLegacyRecordToXMLAgent).

The format of the copybook option file is an XML file.

Alternatively, the service checks for the presence of a file with the full path of the copybook and if the _option suffix is appended. This copybook option file is then used. For example, if the copybook is c:\copybook.cbl, then c:\copybook.cbl_option would be its associated copybook option file.

The following is an example of a copybook option file.

<?xml version=1.0" ?>
<Options>
  <FieldRules>
    <FieldRule>
      <GroupName>ExtremValueTEST</GroupName>
      <FieldName>Account</FieldName>
      <FieldType>COMP-3</FieldType>
      <Actions>
        <AcceptAs onValue="HIGHVALUE">1000<?acceptAs>
        <AcceptAs onValue="LOWVALUE"/>
        <AcceptAs onValue="INVALID" reportRawData="YES">
      </Actions>
    </FieldRule>
    <!--
      A general rule.
      If no "GroupName" and "FieldName", the rule applies to all the fields of
      the filed type specified.
    -->
    <FieldRule>
      <!-- required -->
      <FieldType>COMP-3</FieldType>
      <Actions>
        <AcceptAs onValue="LOWVALUE"/>
        <AcceptAs onValue="BLANK"></AcceptAs>
        <AcceptAs onValue="AMPERSAND"></AcceptAs>
        <AcceptAs onValue="POUND"></AcceptAs>
        <ThrowException onValue="INVALID"></ThrowException>
      </Actions>
    </FieldRule>
  </FieldRules>
</Options>

The root element is <Options>. You can define multiple <FieldRule> elements under the <FieldRules> parent element. The combination of these three elements, <GroupName>, <FieldName>, and <FieldType>, define the specific level of a rule. If a rule does not specify <GroupName> and <FieldName>, then it applies to all the fields of a particular field type. Currently the supported types are COMP-3, Zoned (PIC 9), Alpha (PIC X), and binary (PIC 9 COMP). The <FieldType> element is required.

In the above sample copybook option file, the first <FieldRule> element is more specific than the second <FieldRule> element, because it only applies to one specific COMP-3 field with name Account under the ExtremValueTEST group. The second <FieldRule> element applies to all the COMP-3 fields in a COBOL record.

A <FieldRule> can have one <Actions> element, which can have multiple elements of the following types:

• <AcceptAs onValue="PATTERN" reportRawData="YES">nn</AcceptAs>

  Requires the onValue attribute. If the value of a field matches "PATTERN", substitute the value with nn. If nn is not provided, default to an empty XML element. The attribute, reportRawData, is optional. If this attribute is set to "YES" and a field value matches the "PATTERN", the raw hex data of the value will be reported as an attribute, rawData, to the field in the XML output document. For example:

  <Account rawData="0x10E000"></Account>

  This provides a mechanism for an application to inspect invalid input and handle it programmatically. If this attribute is omitted, the raw data value of a field will not be reported in the XML document.

• <ThrowException onValue="PATTERN"></ThrowException>

  Requires the onValue attribute. If the value of a field matches "PATTERN", then an exception is generated.

<AcceptAs> and <ThrowException> should not both be specified for the same pattern for the same field.

The predefined "PATTERN" strings for the onValue attribute include:

• HIGHVALUE. All bytes are 0xFF.
• LOWVALUE. All bytes are 0x00.
• BLANK. All bytes are 0x40.
• AMPERSAND. All bytes are 0x50.
• POUND. All bytes are 0x7b.
• INVALID. Not a valid data according to the field type.

In the above copybook option file example, if the Account field has a value with all 0xFF bytes, then the value of the field is set to 1000. If the field has a value with all 0x00 bytes, then the field is set to empty. If the field has a blank value, then the field is set to empty. The blank rule is defined in the second <FieldRule> element.

If an options file has multiple actions that are applicable to a field, then the actions that are defined in the most specific field rule applies. If the Account field has all 0xFF bytes, then the value of the field is set to 1000. This is because the first <FieldRule> element is more specific than the second <FieldRule> element.

If two applicable actions are defined at the same level in terms of field rule specificity, then the action that appears first in the options file will be applied. Once exception to this is the INVALID pattern. The INVALID pattern will be checked after the other patterns even if it appears before the other patterns.

If there is no options file or no rules are defined for a field, then an exception is generated if the field value is not valid data.

<PreserveLeadingZeros> only applies to COMP-3 and Zoned fields. This action type specifies whether the leading zeros in a number should be retained for the length of the field type. The default behavior is to truncate any leading zeros. If you want to keep leading zeros to all the COMP-3 and Zoned fields, then add the following <FieldRule> elements to an options file:

<FieldRule>
  <FieldType>COMP-3</FieldType>
  <Actions>
    <PreserveLeadingZeros>YES</PreserveLeadingZeros>
  </Actions>
</FieldRule>

<FieldRule>
  <FieldType>Zoned</FieldType>
  <Actions>
    <PreserveLeadingZeros>Y</PreserveLeadingZeros>
  </Actions>
</FieldRule>

If a copybook option file does not have <PreserveLeadingZeros> defined or if the value of <PreserveLeadingZeros> is not YES or Y, then the leading zeros of COMP-3 and Zoned fields are not preserved.

If only specific fields should preserver leading zeros, more specific <FieldRule> elements are required. To make a <FieldRule> element more specific, you need to specify <GroupName> and/or <FieldName>.

For example, if you want all of the Zoned fields to have leading zeros except one field balance, you must create the rules shown in the following example:

<?xml version=1.0" ?>
<Options>
  <FieldRules>
    <FieldRule>
      <GroupdName>BankAccount</GroupName>
      <FieldName>balance</FieldName>
      <FieldType>Zoned</FieldType>
      <Actions>
        <PreserveLeadingZeros>NO</PreserveLeadingZeros>
      </Actions>
    </FieldRule>

    <!-- more general rule -->
    <FieldRule>
      <FieldType>Zoned</FieldType>
      <Actions>
        <PreserveLeadingZeros>Y</PreserveLeadingZeros>
      </Actions>
    </FieldRule>
  </FieldRules>
</Options>

The more specific rule for the balance field will take precedence over the general rule. Therefore, the leading zeros of this field are not preserved.

<?xml version="1.0" ?>
<Options>
  <FieldRules>
    <FieldRule>
      <FieldType>COMP-3</FieldType>
      <Actions>
        <AcceptAs onValue="LOWVALUE"/>
        <AcceptAs onValue="HIGHVALUE"></AcceptAs>
        <AcceptAs onValue="BLANK"</AcceptAs>
      </Actions>
    </FieldRule>
  </FieldRules>
</Options>

<?xml version="1.0" ?>
<Options>
  <FieldRules>
    <FieldRule>
      <FieldName>PACKED02</FieldName>
      <FieldType>COMP-3</FieldType>
      <Actions>
        <AcceptAs onValue="BLANK">0</AcceptAs>
        <AcceptAs reportRawData="YES" onValue="INVALID"></AcceptAs>
      </Actions>
    </FieldRule>
  </FieldRules>
</Options>