Please find below a list of tips and tricks for configuring the XML and XSL files for a record type transformation.

• Tips for XML Interface Descriptions
• Tips for XSL Transformation Style Sheets

Types of Interface Descriptions

The xBus knows three different types of interface structure descriptions in XML. They can be distinguished by their application area:

Record transfer with transformation

In Configuring a Record Transformation the exact format of the involved interface descriptions is explained.

Record transfer on byte array basis without transformation

The interface descriptions for this case are structured like the first ones. But they contain less information about the fields - only their lengths. Furthermore they offer less possibilities for identifying record types in an interface file. The only supported method is using record type identifiers in the records.

AS400 program calls

Input and output parameters are stored in XML structures. These are Described by program-specific DTD's.

Record Identification

• Using record type identifier is the easiest and fastest way to find out the type a record. It is advisable to use it whenever possible.
• If the RecordIdentification attribute of the <Lines> section in a structure description is set to TypeIdentifier, only this identifier parsed from the record line is used to determine the record type during parsing. Order and cardinality information is ignored in this setting.
• The simple structure description format for byte array transmission without record transformation only allows the identification by type identifiers. In this setting a bypass may be used to process interface files which contain only one record type but this record type does not contain a type identifier. The identifier length has to be set simply to zero and the identifying string to the empty one.
• The full-fashioned structure description for record transformation situations does not allow setting the identifier length to zero.

Field Specification

Roughly spoken two opposite approaches to specify the record type fields are possible:

1. Each field is defined according to the underlying interface specification.
2. Fields are grouped and specified as one single item if they can be transfered as a group without modification and without worrying about system-dependent string lengths or line breaks in the field contents.

The first alternative leads to easy-to-read specifications in the sense that its structure is just like the interface specification documents. Furthermore most transformations can be defined without dividing field values into substrings.

If performance is an important issue, the second alternative is better. Furthermore the resulting XML structure description are easy-to read that the contain less elements.

Remember that the field specification is just for the internal processing. Field names carry not semantics in sense of particular system behavior. This is only achieved by characterizing the fields using the attributes like "Format". The separation into fields can be chosen freely to support the desired transformation or the treatment of system-dependent string lengths and "in-field" line breaks efficiently.

Field Length Correction

• The first remark on field lengths is:
  The specified field lengths in the interface descriptions may rely on character or byte counting - depending which data type is used for data transmission. Cf. General transmitted data types
  But in XSL style sheets the field contents are always treated as strings and counting refers to characters.
• "Simple" length corrections are carried out by the record type transformer automatically without the necessity to specify them in the XSL script:
  • Values in numerical fields are trimmed during parsing.
  • Length extensions are performed during serializing by adding zeros to numbers and blanks to strings.
  • Length reductions are performed during serializing by deleting non-significant zeros in numbers and by trimming strings.
• Only length reductions in a particular fashion or ones forced even with loss of information must be specified in the XSL style sheet.

  Example:

     <DealerOrderNumber>
        <xsl:value-of
           select="substring(normalize-space(DealerOrderNumber),
              string-length(normalize-space(DealerOrderNumber))-6,7)" />
     </DealerOrderNumber>
  

  The last 7 characters of the source dealer order number are taken. Note that the substring function works properly even if the start index for the substring extraction is smaller than 1. For shorter strings it will just return the string itself.

• Trimming strings in XSL is done easily with the XPATH function normalize-space function. But attention: All sequences of white space characters WITHIN the string will be replaced by one single blank, too. This allows for example replacing line breaks in field value by blanks.

Value Mappings

A typical situation when connecting systems by already existing interfaces is the following: Certain field values are expressed by keys but the keys are different in the connected systems.

In this situation the xBus value mapping facility is extremely useful. These value mappings are among the things executed in the second transformation step. The XSLT script for the first transformation step just needs to insert a XBUS_Stylet node for the value mapping. This refers to the mapping table.

Example:

   <WarrantyIdentifier>
      <xsl:if test="normalize-space(WarrantyClass)!=''">
         <xsl:element name="XBUS_Stylet">
            <xsl:attribute name="Name">Value</xsl:attribute>
            <xsl:attribute name="Section">WarrantyTypeAL2IMPHDL</xsl:attribute>
            <xsl:attribute name="Key">
               <xsl:value-of select="WarrantyClass" />
            </xsl:attribute>
         </xsl:element>
      </xsl:if>
   </WarrantyIdentifier>

If the warranty class field in the source does not contain only whitespace characters, the mapping called WarrantyTypeAL2IMPHDL will be searched to replace the source value.

Dates in Records

• Often systems use different date formats. One way to convert them would be tokenizing the date string and rebuilding the date in the destination format using XSL functions. Another possibility is calling a XBUS_Stylet.
  Example:

     <OrderDate>
        <xsl:if test="normalize-space(OrderDate)!=''">
           <xsl:element name="XBUS_Stylet">
              <xsl:attribute name="Name">FormatDate</xsl:attribute>
              <xsl:attribute name="SourceFormat">ddMMyyyy</xsl:attribute>
              <xsl:attribute name="DestinationFormat">yyMMdd</xsl:attribute>
              <xsl:attribute name="Key">
                 <xsl:value-of select="OrderDate" />
              </xsl:attribute>
           </xsl:element>
        </xsl:if>
     </OrderDate>
  

• Some times interfaces need an issue date which is not delivered by the source system. In such a case the actual date can be inserted into the interface content using the same XBUS_Stylet.
  Example:

     <CreditNotesDate>
        <xsl:element name="XBUS_Stylet">
           <xsl:attribute name="Name">FormatDate</xsl:attribute>
           <xsl:attribute name="DestinationFormat">yyMMdd</xsl:attribute>
        </xsl:element>
     </CreditNotesDate>
  

  Without specified source format and source date string the xBus will insert the actual date.