Defining a Flat File

Defining the Flat File

The flat file structure is defined in a class diagram. A root class defines the file and its settings (like e.g. the record separator). This class must have stereotype <<FlatFile>>.

As this is the root of a flat file declaration no attributes are allowed. You should give this class a meaningful name, because the output object flow of the <<FlatFileAdapter>> action in the activity diagram uses this class as a type.

You can change the flat file settings on the specification dialog of the root class.

Figure: Change Flat File Settings

Value <NewLine> of tag Record Separator is a literal placeholder for special character \n. A complete list of all placeholders is listed below.

The other optional tagged values are listed below.

Flat File Settings

Find below a list of all tagged values corresponding to stereotype <<FlatFile>>.

Tagged ValueDescriptionAllowed ValuesExampleescapeCharacterDefines the character used for escaping when a reserved character is used within a field value.any character/fillCharacterDefines a dummy character to fill non-existent values (results in NULL). Used for fixed attribute layout only.any character0quoteCharacterThe quoteCharacter will be ignored by reading field value.any character/recordSeparator Separator of the different records, normally line feed and carriage return. For serialized files, any other character can be defined.any character or one of<newline><esc><newline>parses correctly on Unix and Windows platforms<space><tab> <tabulator><unixnewline>composes newline<windowsnewline>composes newline and carriage return reservedCharacters Defines a list of characters to be escaped automatically when the file is composed.any character{"/", "%", "&", "(", ")"}

Defining a Flat File Record

The record structure and the relation between records is defined by one or more child classes and the association to their parent class (e.g. the root class or a parent record class). All records have stereotype <<FlatFileRecord>>.

Figure: Flat File Record Structure

Flat File Record Groups

Additionally, (virtual) groups can be defined by stereotype <<FlatFileGroup>>. These classes have no physical representation in the flat file itself.

Flat File Record Settings

Find below a list of all tagged values corresponding to the stereotype <<FlatFileRecord>>.

There were errors rendering macro: An unknown error occurred.

For detailed information on associations see Defining a Flat File | id (25.1)DefiningaFlatFile FlatFileGroupSettings or Defining a Flat File | id (25.1)DefiningaFlatFile AssociationsEndingsof<<FlatFileRecord>>and<<FlatFileGroup>> .

Flat File Group Settings

You can group multiple records in one virtual structure by using the stereotype <<FlatFileGroup>>. This virtual group does not have a representation in the flat file and therefore cannot hold any attributes. Apart from this, this element has the same behavior like a flat file record. For parsing and composing, the pattern and conditions are checked but no mapping takes place. The record details are given to the associated class where the mapping is done.

Find below a list of all tagged values corresponding to the stereotype  <<FlatFileGroup>> .

Tagged ValueDescriptionAllowed ValuesExamplepatternError rendering macro 'multiexcerpt-include' : Page loading failedany character^Pattern.*a valid regular expression

Associations Endings of <<FlatFileRecord>> and <<FlatFileGroup>>

All associations ending on a class with stereotype <<FlatFileRecord>> or <<FlatFileGroup>> can have additional attributes, if the association end has stereotype <<FlatFileSubRecord>> applied.

Find below a list of all tagged values corresponding to stereotype    <<FlatFileSubRecord>> .

Tagged ValueDescriptionAllowed ValuesExampleconditionA condition that must evaluate true if the record exists. The condition can refer to a self object which represents the current state of the parent.any valid conditional expressionself.UNS.exists()evaluationOrderDefines the order in which the associations starting on same parent class must be processed, see (25.1) Flat File Adapter Parsing Process.any integeroffsetDefine the position of this record in the flat file, starting with 0 for the first record and always relative to the parent element.any integer

Defining Flat File Record Attributes

All Attributes on a <<Flat File Record>> class need to have stereotype <<FlatFileAttribute>>. Depending on the layout type of the flat file (fixed or separated), you can specify different tagged values (see Defining a Flat File | id (25.1)DefiningaFlatFile AttributeSettingsforattributeLayout=fixed and Defining a Flat File | id (25.1)DefiningaFlatFile AttributeSettingsforattributeLayout=separated). Additionally, you can define record fields as to be of complex type (see Defining a Flat File | id (25.1)DefiningaFlatFile ComplexFlatFileRecordAttributes).

Attribute Settings for attributeLayout = fixed

For flat files having a fixed layout, you need to specify external length and order of the attribute, and optionally, you can specify a padding.

Tagged ValueDescriptionAllowed ValuesExampledecimalsReplaced by format.externalLengthNumber of characters of the field (only for fixed length records relevant).any integerformatError rendering macro 'multiexcerpt' : Page loading failedany valid number or dateTime patternS9G999G990D00 %Y.%m.%d-%H:%M:%nativeTyp deprecatedReplaced by format.orderThe evaluation order of the attributes. If offset is not used, order reflects the field number within the record.any integeroffsetThe character position of this field within the record.any integerpaddingDefines the padding rule for the field. When parsing, the characters on the left or right side are ignored up to the first different character. When composing, the field is filled on the left or right side with the specified character.left("<any character>")left("0")right("<any character>")right(" ")suppressEscapingError rendering macro 'multiexcerpt' : Page loading failedtrueattribute values of this attribute will not be un-escaped (parser) or escaped (composer)falseescaping/un-escaping is not suppressedparseMacroError rendering macro 'multiexcerpt-include' : Page loading failed   any valid macro expression (see Macro Expressions)GetCounter(0)composeMacro

Attribute Settings for attributeLayout = separated

For attributes in separated flat files, you can supply an offset to specify the position of the field (attribute) in respect of the other record fields.

Tagged ValueDescriptionAllowed ValuesExampleformatError rendering macro 'multiexcerpt-include' : Page loading failedorderThe evaluation order of the attributes. If offset is not used, order reflects the field number within the record.any integeroffsetThe relative position of the field in respect of the other fields in the record, e.g. field number 3 has offset = 2.any integersuppressEscapingError rendering macro 'multiexcerpt-include' : Page loading failedparseMacroError rendering macro 'multiexcerpt-include' : Page loading failedany valid macro expression (see Macro Expressions)GetCounter(0)composeMacro

Complex Flat File Record Attributes

Flat file record attributes can by of complex type. The complex type must have stereotype <<FlatFileComplexAttribute>> applied, then.

Figure: Flat File Complex Attribute

You can use this class to divide a record field into sub-fields. You can think of this like a <<FlatFileRecord>> placed within a single field. Most of the tagged values that are valid for a flat file record are valid for a complex attribute, too. Though, the scope of these settings is not the record, but the field.

There were errors rendering macro: An unknown error occurred.

Macro Expressions

Available macros are counters:

• eight automatic counters with ID AUTO0 .. AUTO7 (for parsing and composing)

• two automatic line counters with ID LINE0 and LINE1 (for parsing only)

• unlimited custom counters with ID CUSTOM0 .. CUSTOMx (for parsing and composing).

Automatic counters automatically increase with each processed record, whereas custom counters have to be increased manually using the IncreaseCounter() macro. When parsing/composing the first record, all counters have the initial value of 0.

For GetCounter() and VerifyCounter() only attributes of type Integer are supported.