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:
The number of fields in the inbound structure is defined by the value specified in NameA.fieldSeparator :
The fields are also missing in the XML structure.
Additional fields in the structure are ignored.
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.
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.
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.
Define Document Parameters
The Document Name is inserted in the message as the main XML tag. This is mandatory for the mapping.
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
It is included in the XML schema.
It is appended to the name of the structure.
The sequence of the recordset structures is assumed to be unique. A new recordset is started as soon as an earlier structure occurs.
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.
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.
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.
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.
This entry is used if the key field name is defined.
Define Parameters and Values for Recordset Structures
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.
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 .
This parameter is only evaluated if you enter a value for NameA.fieldFixedLengths .
This is the default.
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 .
Specifies the form in which the entries under NameA.fieldFixedLengths are counted:
The number of characters is counted.
The byte length of the characters is counted.
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.
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).
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.
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 .
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 .
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.
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).
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).
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.
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.
Enter the names of the structure columns. The input format depends on the following:
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.
If the inbound structure has less fields than specified in the configuration then the XML outbound structure is created as follows:
Outbound structure only contains the fields in the inbound structure
Outbound structure contains all fields from the configuration; the fields missing in the inbound structure are empty.
Conversion is terminated due to the incomplete inbound structure. An error message is displayed.
If the inbound structure has more fields than specified in the configuration then the XML outbound structure is created as follows:
Outbound structure only contains the fields in the inbound structure
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.
To ensure a well-defined runtime behavior for variable inbound structures, we recommend that you always set both parameters.
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>...