Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 2 The COBOL Copybook Palette : Copybook Schema

Copybook Schema
Shared Configuration
The Copybook Schema shared configuration resource describes the schema to use when parsing or rendering COBOL data. This resource allows you to load a COBOL Copybook file by using the Import Copybook Schema button to choose a file containing the schema. These files typically have a .cpy, .cob, or .cbl extension.
Configuration
The configuration tab has the following fields.
Specifies whether the data is in COBOL fixed or free format. When checked, the data is expected to be in COBOL fixed format where columns 0-6 are reserved for line numbers. When unchecked, the data can be in COBOL free format where the COBOL code can be within columns 0-6.
Import Copybook Schema Button
The Import Copybook Schema button brings up a dialog that allows you to choose the file containing the COBOL Copybook schema you wish to import. Once the file is chosen, the COBOL schema appears in the Copybook tab and the XSD schema appears in the XML Schema tab.
Copybook
The Copybook tab displays the COBOL Copybook schema loaded into this resource.
XML Schema
The XML Schema tab displays the XSD that will be used to parse and render COBOL Copybook data.
Test Parsing Button
This button tests the COBOL Copybook schema and returns the results. When an error is encountered, the line number and column number of the error are displayed.
Configure REDEFINES
The COBOL REDEFINES clause allows different data description entries to describe the same storage area, similar to a union in most programming languages. The data description entries for REDEFINES are converted to a choice element in the XSD.
After you import the Copybook schema, you must configure the data description entries for the REDEFINES group. The configuration helps determine the unique data description entry for the group.
To configure the REDEFINES group, use one of the following methods:
Assign a data description entry from the REDEFINES group as the default entry. The setting maps the data content of storage area to this default data description entry at run-time.
Assign a data description entry (known as control field) to the REDEFINES group. At run-time, the value of this control field determines the data description entry to be used to map the data content of redefined storage area.
If a REDEFINES group is not configured at all (that is, neither a default data description entry nor a control field is assigned), at runtime, the first data description entry from the REDEFINES group is used to map data content of the redefined storage area.
For example, the following Copybook has a control field named UNIT-PRICE-CONTROL that determines whether the next field is ACTUAL or CONVERTED.
 
01 PURCHASE-ORDER.
   02 HEADER.
      03 DOCUMENT-DEP PIC 9.
      03 DOCUMENT-DATE-TIME PIC X(20) VALUE IS SPACES.
   02 LINEITEM.
      03 ORDERITEM-DEP PIC 9.
      03 QUANTITY PIC 9(4).
      03 UNIT-PRICE.
         04 UNIT-PRICE-CONTROL PIC X.
         04 ACTUAL.
            05 CURRENCY PIC X(10) VALUE IS SPACES.
            05 FILLER PIC 99.
         04 CONVERTED REDEFINES ACTUAL.
            05 CURRENCY PIC X(10).
            05 CONVERSION-FACTOR PIC 99.
The Configure REDEFINES button brings up a dialog that allows you to specify how the contents of the control field determine which data element occurs. To use this dialog, follow this procedure:
1.
Click the Configure REDEFINES button and select the REDEFINES clause from the list on the left that you wish to configure. There may be more than one REDEFINES clause in your COBOL Copybook schema, and this dialog lets you configure them individually.
2.
3.
4.
Figure 4 Setting the control field
5.
Select each row in the Control Field Value column of the table below the schema tree. Enter the value in the control field that signifies the data element. For example, if the UNIT-PRICE-CONTROL contains the value "actual", then ACTUAL is the data element. If the field contains "converted", then CONVERTED is the data element. Enter the correct value for each data element.
You can enter multiple values in the Control Field Value column if more than one value can be used. For example, you may enter actual;act;a if the ACTUAL data element should be selected when the control field value is actual or act or a. Use a semicolon (;) to separate each potential value.
For text control fields, you can enter values that have whitespaces in them. During execution, these values will be processed based on the Parse Activity Trim Whitespaces from String Values. If checked, whitespaces will be trimmed from strings in the data as well as control field values (the spaces in the control field values will not be significant). When Trim Whitespaces from String Values is unchecked, then the unchanged values from data and unchanged control field values will be used for comparison (the spaces in the control field values will be significant). For additional details on Trim Whitespaces, see Parse Copybook Data.
For control fields that are converted to numeric types, the control field values are being checked in a typed manner. For example, a control value '0003' will match data value 3 for fields converted to integer type, and '3E4' will match with '0.3E5' for float and double types.
6.
Check the Default checkbox to assign one of the data elements to be the default element when the control field value matches none of the specified values. The default is the first data element in the redefines group.
7.
Click the Finish button. Figure 5 illustrates the completed REDEFINES configuration for the example COBOL Copybook schema.
Figure 5 Completed REDEFINES configuration
The configuration of the REDEFINES clause in the example above would result in the following choice element in the XSD:
 
<xs:choice>
  <xs:element cobol:byteLength="12" cobol:isDefault="true"
  cobol:controlFieldValue="actual" cobol:byteOffset="27"
  cobol:controlField="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.UNIT-
    PRICE-CONTROL"
  name="ACTUAL" minOccurs="0">
    <xs:complexType>
      <xs:sequence>
        <xs:element cobol:byteLength="10" cobol:picture="X(10)"
        cobol:fullName="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.
          ACTUAL.CURRENCY"
        cobol:byteOffset="27" cobol:usage="DISPLAY"
        name="CURRENCY" default="SPACES" minOccurs="0">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:maxLength value="10"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element cobol:byteLength="2" cobol:picture="99"
        cobol:fullName="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.
          ACTUAL.FILLER"
        cobol:byteOffset="37" cobol:usage="DISPLAY"
        name="FILLER" minOccurs="0">
          <xs:simpleType>
            <xs:restriction base="xs:unsignedShort">
              <xs:totalDigits value="2"/>
              <xs:minInclusive value="0"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element cobol:byteLength="12"
  cobol:controlFieldValue="converted" cobol:byteOffset="27"
  cobol:controlField="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.UNIT-
    PRICE-CONTROL"
  name="CONVERTED" minOccurs="0">
    <xs:complexType>
      <xs:sequence>
        <xs:element cobol:byteLength="10" cobol:picture="X(10)"
        cobol:fullName="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.
          CONVERTED.CURRENCY"
        cobol:byteOffset="27" cobol:usage="DISPLAY"
        name="CURRENCY" minOccurs="0">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:maxLength value="10"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element cobol:byteLength="2" cobol:picture="99"
        cobol:fullName="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.
          CONVERTED.CONVERSION-FACTOR"
        cobol:byteOffset="37" cobol:usage="DISPLAY"
        name="CONVERSION-FACTOR" minOccurs="0">
          <xs:simpleType>
            <xs:restriction base="xs:unsignedShort">
              <xs:totalDigits value="2"/>
              <xs:minInclusive value="0"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:choice>
 
If the control field is a repeating field, then the value used to determine the actual choice is the last value processed before the xs:choice element.
OCCURS ... DEPENDING ON Clause
The COBOL OCCURS ... DEPENDING ON clause defines a repeating data element whose number of occurrences depends upon a numeric element. This type of element is automatically converted to a repeating element in the XSD.
For example, the following Copybook contains an element named ORDERITEM that occurs between 0 and 10 times. The number of times the element occurs is determined by the ORDERITEM-DEP field.
 
01 PURCHASE-ORDER.
   02 HEADER.
      03 DOCUMENT-DEP PIC 9.
      03 DOCUMENT-DATE-TIME PIC X(20) VALUE IS SPACES.
   02 LINEITEM.
      03 ORDERITEM-DEP PIC 9.
      03 ORDERITEM OCCURS 0 TO 10 TIMES DEPENDING ON ORDERITEM-DEP.
         04 ITEM-TYPE PIC X(10) VALUE IS SPACES.
         04 DESCR PIC X(40) VALUE IS SPACES.
         04 SERIAL-NUM PIC 9999.
      03 QUANTITY PIC 9(4).
      03 UNIT-PRICE.
         04 UNIT-PRICE-CONTROL PIC X.
The XSD element for the LINEITEM element would be the following:
 
<xs:element cobol:byteLength="546" cobol:byteOffset="21"
name="LINEITEM" minOccurs="0">
  <xs:complexType>
    <xs:sequence>
      <xs:element cobol:byteLength="1" cobol:picture="9"
      cobol:fullName="PURCHASE-ORDER.LINEITEM.ORDERITEM-DEP"
      cobol:byteOffset="21" cobol:usage="DISPLAY"
      name="ORDERITEM-DEP" minOccurs="0">
        <xs:simpleType>
          xs:restriction base="xs:unsignedShort">
            <xs:totalDigits value="1"/>
            <xs:minInclusive value="0"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element cobol:byteLength="54" cobol:occursMin="0"
      cobol:occursMax="10" cobol:byteOffset="22"
      cobol:occursDepending="PURCHASE-ORDER.LINEITEM.ORDERITEM-
        DEP"
      name="ORDERITEM" minOccurs="0" maxOccurs="10">
        <xs:complexType>
          <xs:sequence>
            <xs:element cobol:byteLength="10"
            cobol:picture="X(10)"
            cobol:fullName="PURCHASE-ORDER.LINEITEM.ORDERITEM.
              ITEM-TYPE"
            cobol:byteOffset="22" cobol:usage="DISPLAY"
            name="ITEM-TYPE" default="SPACES" minOccurs="0">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:maxLength value="10"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
            <xs:element cobol:byteLength="40"
            cobol:picture="X(40)"
            cobol:fullName="PURCHASE-ORDER.LINEITEM.ORDERITEM.
              DESCR"
            cobol:byteOffset="32" cobol:usage="DISPLAY"
            name="DESCR" default="SPACES" minOccurs="0">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:maxLength value="40"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
            <xs:element cobol:byteLength="4" cobol:picture="9999"
            cobol:fullName="PURCHASE-ORDER.LINEITEM.ORDERITEM.
              SERIAL-NUM"
            cobol:byteOffset="72" cobol:usage="DISPLAY"
            name="SERIAL-NUM" minOccurs="0">
              <xs:simpleType>
                <xs:restriction base="xs:unsignedShort">
                  <xs:totalDigits value="4"/>
                  <xs:minInclusive value="0"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element cobol:byteLength="4" cobol:picture="9(4)"
      cobol:fullName="PURCHASE-ORDER.LINEITEM.QUANTITY"
      cobol:byteOffset="-1" cobol:usage="DISPLAY" name="QUANTITY"
      minOccurs="0">
        <xs:simpleType>
          <xs:restriction base="xs:unsignedShort">
            <xs:totalDigits value="4"/>
            <xs:minInclusive value="0"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element cobol:byteLength="1" cobol:byteOffset="-1"
      name="UNIT-PRICE" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element cobol:byteLength="1" cobol:picture="X"
            cobol:fullName="PURCHASE-ORDER.LINEITEM.UNIT-PRICE.
              UNIT-PRICE-CONTROL"
            cobol:byteOffset="-1" cobol:usage="DISPLAY"
            name="UNIT-PRICE-CONTROL" minOccurs="0">
              <xs:simpleType>
                <xs:restriction base="xs:string">
                  <xs:maxLength value="1"/>
                </xs:restriction>
              </xs:simpleType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>
</xs:element>
 
The DEPENDING ON clause object that defines the actual number of occurrences does not have to be of either integer or short type. The number of occurrences will be determined without errors if the actual value (after parsing or before rendering) can be converted to an integer. For example, a PIC X(4) field containing the value '0003' will mean 3 occurrences. If the value cannot be converted to a number, than parsing fails.
Whitespaces are always trimmed prior to the further processing. For example, a PIC X(4) field with the value '03' yields 3 occurrences.
If a field used in the OCCURS ... DEPENDING ON clause is a repeating field, the value that will be used for determining the actual number of occurrences is the last value processed before this OCCURS ... DEPENDING ON clause.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved