Show TOC

Converting Text Format in the Sender File/FTP Adapter to XMLLocate this document in the navigation structure

Use

You can convert a text file with complex structures to an XML source format. The file can contain different row formats in logical structures.

Handling Structure Deviations

The conversion routine assumes that all structures are constant. The number of fields corresponds to the entry in parameter NameA.fieldNames or the number and length of fields in parameter NameA.fieldFixedLengths .

The structures are not validated. However, you can use the parameters described below to influence the way the conversion routine functions when structure deviations occur.

If you want to allow the structure found at runtime to differ from the configured structure, configure the NameA.missingLastFields and NameA.additionalLastFields parameters. If you do not use these parameters, the result of the conversion depends on whether you have configured the NameA.fieldFixedLengths parameter:

  • Parameter NameA.fieldFixedLengths is not configured

    The number of fields in the inbound structure is defined by the value specified in NameA.fieldSeparator :

    • If the inbound structure contains more fields than specified in NameA.fieldNames , conversion is terminated with an error message.
    • If the inbound structure contains less fields than in NameA.fieldNames , the conversion is executed.

      The fields are also missing in the XML structure.

  • Parameter NameA.fieldFixedLengths is configured
    • If the inbound structure contains more fields than in NameA.fieldNames or NameA.fieldFixedLengths the conversion is executed.

      Additional fields in the structure are ignored.

    • If the inbound structure contains less fields than specified in NameA.fieldNames , conversion is terminated with an error message.

      If the last field only is shorter than defined or is missing completely, the conversion is executed. The contents of the last field are then applied to the XML element as found. Consequently, the value can be incomplete or empty.

You can change this behavior by using the parameters NameA.missingLastFields and NameA.additionalLastFields . If you use this parameter, you can perform a defined check on the inbound structures, and well-defined source structures are created.

Note

You can implement some of the functions of this parameter by using the NameA.lastFieldsOptional parameter.

NameA.lastFieldsOptional is however obsolete and must not be used.

If you use the parameter together with the NameA.missingLastFields and NameA.additionalLastFields parameters an error message is displayed at runtime.

Prerequisites
  • In the sender file/FTP adapter, you have selected File Content Conversion as the Message Protocol.
  • The system expects a file with one or more logical structures (recordsets).

    An unlimited number of recordsets (either one, multiple, or all recordsets in the file) can be sent to the Integration Server/PCK as separate messages.

  • A recordset can contain multiple types of substructures identified by logical names.
  • There can be a fixed or variable number of substructures in a recordset.
  • The format of a substructure must be fixed and corresponds to the description of the row format in the table below.
  • A substructure must always be shown in exactly one line of the text document.
Procedure

Define Document Parameters

  1. Specify the name of the XML document.

    The Document Name is inserted in the message as the main XML tag. This is mandatory for the mapping.

  2. The Document Namespace is added to the name of the document. This is mandatory for the mapping.
  3. Under Document Offset, specify the number of lines that are to be ignored at the beginning of the document.

    This enables you to skip comment lines or column names during processing. If you do not make an entry, the default value is zero lines.

Define Recordset Parameters

  1. Enter the name of the recordset.

    It is included in the XML schema.

  2. Enter the Recordset Namespace.

    It is appended to the name of the structure.

  3. Under Recordset Structure, enter the sequence and the number of substructures as follows:<NameA,nA,NameB,nB,...> , where nA=1,2,3,... or* (for a variable, unlimited number, including 0).
  4. You define the start and end of recordsets containing a variable number and arrangement of structures as follows:
    • Ascending :

      The sequence of the recordset structures is assumed to be unique. A new recordset is started as soon as an earlier structure occurs.

    • Variable :

      The sequence of the recordset structures is assumed not to be fixed. A new recordset is not started until another structure occurs that is defined with a fixed number. If all structures are defined as variable, the system interprets the entire document as a single recordset.

  5. Under Recordsets per Message, specify the number of recordsets to be grouped together in a message.

    This entry is optional. The default value is* . In the default setting, all recordsets are included in a message.

    If the number of recordsets in a document is greater than the number specified, the adapter creates multiple messages from a document. The last message might then contain fewer recordsets than specified.

    Note

    To ensure that each of these messages (that is, each part of a document from which a message is created) is sent to the Integration Server/PCK exactly once, select Exactly Once as the Quality of Service. This is also true if the application is interrupted while creating the messages and restarted again later.

  6. If you have entered a variable number of substructures under Recordset Structure, that is, you have entered the value* for at least one structure, specify a Key Field Name.

    The parser identifies the substructures by their content. This happens using the key field with different constants for the substructures. In this case, you must specify a key field, and the field name must occur in all substructures.

  7. Specify the Key Field Type to be used to compare the predefined values.

    This entry is used if the key field name is defined.

Define Parameters and Values for Recordset Structures

  1. Set the parameters for all the specified recordset structures NameA, NameB, ... in the table.
    • ignoreRecordsetName

      A <Recordset> element is inserted in the XML structure for each recordset structure. This level is not always required, particularly if the recordset only contains one structure definition.

      If you set the parameter to true , the <Recordset> element is not inserted.

    • NameA.fieldFixedLengths

      If you make an entry here, the system expects a character string that contains the lengths of the structure columns as arguments separated by commas.

      If you also specify a separator for the columns, you must not add its length to the length of the columns.

      This entry is mandatory if you have not made an entry for NameA.fieldSeparator .

    • NameA.keepIncompleteFields

      This parameter is only evaluated if you enter a value for NameA.fieldFixedLengths .

      • If you enter NO and the last field found in the structure is shorter than specified in NameA.fieldFixedLengths , processing is terminated with a corresponding error message.

        This is the default.

      • If you enter YES , the last field found in the inbound structure is transferred to the outbound structure, even if it is shorter than specified in NameA.fieldFixedLengths .

        You use this parameter to control the behavior of the conversion routine for the last field in a structure.

        Use the NameA.missingLastFields parameter to define the behavior at runtime when the structure contains less fields in total that specified in NameA.fieldFixedLengths .

    • NameA.fieldFixedLengthType

      Specifies the form in which the entries under NameA.fieldFixedLengths are counted:

      • char (default value)

        The number of characters is counted.

      • byte

        The byte length of the characters is counted.

    • NameA.fieldSeparator
      • If you make an entry here, the system expects that the structure contains the specified character string (one or more characters) as a separator between the individual columns.
      • If you have not made an entry for fieldFixedLengths , this is the only specification to identify the individual columns in a row.
      • If you made an entry for fieldFixedLengths , the extra length of the separator is taken into account, but no further consistency checks are performed.
    • NameA.lastFieldsOptional (obsolete)

      You use this parameter to specify whether the last fields can be omitted (YES) or not (NO) in a structure with fixed field length, like defined in parameter fieldFixedLengths . If you do not make an entry, the default value is NO.

      This parameter does not apply to comma-separated structures and missing fields are ignored.

    • NameA.enclosureSign

      Specify a string that acts as a text delimiter. Text enclosed by such delimiters is transferred to the target structure unchanged, although the default setting is to remove all text delimiters. Separators within such texts are ignored.

      This parameter is optional. The default setting is an empty value (no text delimiter).

    • NameA.enclosureSignEnd

      If the text delimiters for the beginning and end of the text are different, specify the text delimiter for the end of the text here.

      If you do not make an entry here, the entry from NameA.enclosureSign is used.

    • NameA.enclosureSignEscape

      Specify a string that replaces the text delimiter if it occurs within a text that it delimits.

      When the text is transferred the string is replaced by the value specified in NameA.enclosureSign .

    • NameA.enclosureSignEndEscape

      Specify a string that replaces the text delimiter for the end of the text if it occurs within a text that it delimits.

      When the text is transferred the string is replaced by the value specified in NameA.enclosureSignEnd .

    • NameA.enclosureConversion
      • Specify YES if the text delimiter is to be removed or if the escape character is to be replaced when the files are transferred. This is the default value.
      • Enter NO if the character is to be transferred unchanged.

      If you specify xml.enclosureSign=" and xml.enclosureSignEsc="" , text enclosed in quotation marks is transferred unchanged and the quotation marks are removed.

      If the escape character for a quotation mark ("" ) occurs in the text itself, it is replaced by the quotation mark during the transfer.

    • NameA.endSeparator

      If you want to define an additional string as a separator after the last column in a row, specify it here.

      The system skips this separator when it processes the last column (otherwise the system would treat it as part of the last column).

    • NameA.beginSeparator

      If you want to define an additional character string as a separator before the first column in a row, make a specification here.

      The system skips this separator when it processes this column (otherwise the system would treat it as part of the first column).

      • Special Characters in Strings for Separators

        In all strings for separators ( NameA.fieldSeparator , NameA.beginSeparator , NameA.endSeparator ), you can specify non-printable ASCII characters. These characters can each be inserted individually in the strings in the form ´0xHH´ (including the quotation marks), where HH represents the character encoded as a hexadecimal value.

      • Inserting Strings for Separators in the XML Document:

        The separators specified with NameA.beginSeparator and NameA.endSeparator can also be inserted as fields in the structure of the generated XML document. To do this, specify field names with the following entries:

        NameA.addBeginSeparatorAsField=<fieldname>

        and/or

        NameA.addEndSeparatorAsField=<fieldname>

        The strings, together with the specified field name, are then inserted either at the start or the end of the structure, as they were specified in NameA.beginSeparator and NameA.endSeparator , that is, including the definition of special characters. Special characters cannot be converted since characters of this type are not permitted in XML documents.

    • NameA.fieldNames

      Enter the names of the structure columns. The input format depends on the following:

      • If you have specified a value for NameA.fieldFixedLengths , then a string is expected containing the names of the file columns as arguments separated by commas. This also applies if you have also specified a value for NameA.columnSeparator .
      • If you have only specified a value for NameA.fieldSeparator , the system expects a string containing the names of the file columns in the same format as the file rows. This means that the same separator and any additional string you specify for NameA.endSeparator and/or NameA.beginSeparator are expected.
    • NameA.keyFieldValue

      Specify the value of the key field for the structure.

      This entry is mandatory if the key field name is set. Otherwise, the entry is ignored.

    • NameA.fieldContentFormatting
      • Enter trim to remove all the leading and subsequent blanks for a value found. This is the default.
      • Enter nothing to ensure that the value remains unchanged.
    • NameA.keyFieldInStructure
      • If the key field of the substructure is to be added to the XML document, enter add . This is the default.
      • If the key field is to be ignored, enter ignore .
  2. Use the following parameters if you want to influence the behavior of the conversion routine for inbound structures that deviate from the configuration.
    • NameA.missingLastFields

      If the inbound structure has less fields than specified in the configuration then the XML outbound structure is created as follows:

      • ignore

        Outbound structure only contains the fields in the inbound structure

      • add

        Outbound structure contains all fields from the configuration; the fields missing in the inbound structure are empty.

      • error

        Conversion is terminated due to the incomplete inbound structure. An error message is displayed.

    • NameA.additionalLastFields

      If the inbound structure has more fields than specified in the configuration then the XML outbound structure is created as follows:

      • ignore

        Outbound structure only contains the fields in the inbound structure

      • error

        Conversion is terminated due to the incomplete inbound structure. An error message is displayed.

        The default value is ignore . If you have defined the NameA.fieldFixedLengths parameter, the default value is error .

    If you have defined the NameA.fieldFixedLengths parameter and do not set either of the parameters described above, apart from the default values, the conversion routine works the same as described under Handling Structure Deviations.

    Only once you set one of the two parameters will the other parameter be evaluated with its default value.

    Note

    To ensure a well-defined runtime behavior for variable inbound structures, we recommend that you always set both parameters.

Result

The document has the following structure:

<documentName>...

<recordset>

<NameA>

<field-nameA1>field-value</field-nameA1>

<field-nameA2>field-value</field-nameA2>

<field-nameA3>field-value</field-nameA3>

</NameA>

<NameB>

<field-nameB1>column-value</field-nameB1>

<field-nameB2>column-value</field-nameB2>

<field-nameB3>column-value</field-nameB3>

</NameB>

</recordset>

...

<recordset>

...

</recordset>

</documentName>...