Attribute conversion file is a text file with at least two columns separated by spaces or tabs. Actual conversion is made between first two columns. Code table function has radio buttons for direction selection. In format converter Field settings direction depends on operation: reading and writing use different directions. Reading makes conversion from right column to left and writing from left column to right. Same conversion file can be used in both cases and code used by the program is always in the left column.
Comment can be given in its own line or at the end of definition line separated by semicolon or exclamation mark. After the comment character there must be either space, tabulator or other comment character. For example, "! comment" or "!!! ALERT !!!" are comments, but "!T3=1,2,3" is not.
Conversion file is read from the beginning until searched column matches to object's attribute. Then reading stops and value from the other column is assigned to the object. If the conversion file has third column, its attribute is always assigned to the object regardless of conversion direction.
Code table function has setting for default attribute converted. In format converter Field settings default attribute is always T3. For compatiblity with old conversion tables, third column default attribute is always T1. For a same reason its value is assigned be default only for missing attributes. See conditional assignment below.
In its basic form, T3 conversion file looks like following:
3002 147 1 3007 146 9 ! comment 3010 140 ; comment 4001 "12 34" 4002 '123 5'
If the object code matches, depending on direction, either first or second column value, value in the other column is assigned as object code. If the line has third column, its value is assigned as surface code to a field T1. Values containing spaces can be given between single or double quotes. Value given in single quotes can contain double quotes and vice versa.
Conversion file functionality can be expanded to handle combination of multiple attributes. Technically, column searched is search rule and column assigned is assignment rule. Both syntaxes are mostly compatible, which means that they can be used in both directions. Conversion file meant for just one direction can use all search and assignment rules without limitations.
Previous example can also be defined like this:
T3=3002 T3=147 T1!=1 T3=3007 T3=146 T1!=9 ! comment T3=3010 T3=140 ; comment T3=4001 T3="12 34" T3=4002 T3='123 5'
Default attribute ids do not matter any more, because each column defines separately searched or assigned attribute ids. In both cases multiple attribute definitions can now be given separated by semicolons:
T3=3002 GROUP=1;CLASS=3 T1!=1 T3=3007 GROUP=1;CLASS=4 T1!=9 T3=4001 GROUP=2;CLASS=5 T3=4002 GROUP=2;CLASS=6
When converting from left to right, matching code T3 is changed to GROUP and CLASS attributes. In other direction, same attribute combination is changed to T3 code, when all attributes separated by semicolon match. This kind of conversion to different attributes does not remove original attributes from the object.
Alternative attribute values can be given as a comma separated list according normal search rules:
T3=3002 GROUP=1;CLASS=3,5 T1!=1 T3=3007 GROUP=1;CLASS=4,6 T1!=9 T3=4001 GROUP=2;CLASS=8,7,5 T3=4002 GROUP=2;CLASS=6,9
When converting from right to left, attribute value must match so some comma separated value. In other direction, assignment uses first value in the list.
In search rule question mark (?) matches to any single character and asterisk (*) to any character string, but not to an empty attribute value. Comma and asterisk together (,* or *,) match also to empty values. Assignment changes always all question marks to zeroes (e.g. 2?? -> 200). Just asterisk alone does nothing in assignment and asterisks in assigned value are removed (e.g. *ROAD -> ROAD). Comma and asterisk together in assignment follow normal list rule and use first value (*, -> do nothing or ,* -> empty value). Range interval in assignment uses the start value (e.g. 100-200 -> 100).
These can be used for default values like following:
T3=3002 GROUP=1;CLASS=3,5 T1!=1 T3=3007,3??? GROUP=1;CLASS=4,6 T1!=9 T3=4001-4005 GROUP=2;CLASS=8,7,5 T3=4008,,* GROUP=2;CLASS=6,9
Question marks in the second line match all four character codes starting with three. In other direction, first value 3007 is used for assignment. Likewise, third row range matches all codes between 4001-4005 and starting value 4001 is use for assignment in other direction. Last line empty value and asterisk combination (,*) matches all remaining values and first list value 4008 is used for assignment in other direction.
Other attribute value can be used in assignment and attribute can be removed with empty value:
T3=$CODE,*;CODE=,* CODE=$T3,*;T3=,* T3=999, CODE=999,
Previous example from left to right changes attribute T3 to attribute CODE, removes original attribute and assigns default value to missing attributes. First line search rule matches to all attributes with some balue. T3 is either value os CODE attribute ($CODE) or any value (*). Likewise CODE is always either empty or some value (,*). In assignment CODE attribute gets value of attribute T3 and T3 then gets empty value from the list first item. Empty T3 value matches to second line rule and gets the default value 999. Same logic works for other direction.
Macros can also used according normal search and assignment rules. Search rule can be any macro. In assignment calculation macros (e.g. #DZ, #TYPE) do nothing. However, values can be assigned to draw data macros (e.g. #SIZE, #COLOR). Type macros (e.g. #TYPE=POINT, #TYPE=LINE) can be used for limiting conversion to certaing object types.
#COLOR=$RGB,*;RGB=,* RGB=#COLOR,*;#COLOR=,*
Previous from left to right moves color from drawing data to RGB attribute and from right to left vice versa.
Third column assignment can use conditional assignment. Syntax != assigns value only for objects with missing attribute and syntax ?= assigns value only for objects with already existing attribute. For compatibility with old code conversion files default is exclamation mark syntax meaning that value is assigned only for missing attributes.
*, *, T1!=1;T2?=2
Above example assigns for all objects default value 1 to missing attributes T1 and overwrites value 2 to existing attributes T2.
Normally single conversion definition contains one line. To make long definitions clearer they can be divided to multiple lines. This is done by adding escape character (^) to the end of the line. It automatically joins next line to the definition.
*, T1=$ID;^
REPORT="\\SERVER\path\to\reports\2018\";^
REPORT=&$ID;^
REPORT=&".PDF"
Because conversion file reading stops to first matching line, individual file can normally handle only single attribute combination conversion. However, it is possible to divide file to several different sections using title lines in square brackets. Each section is then executed just like separate conversion file. When executing conversion from left to right, sections are executed in order starting from top. Opposite order is used when conversion is executed from right to left.
[Code] T3=$CODE,*;CODE=,* CODE=$T3,*;T3=,* T3=999, CODE=999, [Color] #COLOR=$RGB,*;RGB=,* RGB=#COLOR,*;#COLOR=,*
Section name can also be given in curly bracket instead of square brackets. This executes always every line in the section and can be used, for example, value normalization
{scandic}
MATERIAL=teras,teräs MATERIAL=teras,teräs
_RIM=ritila,ritilä _RIM=ritila,ritilä
Section can be commented out by prepending its name with exclamation mark or semicolon (e.g. [!code] tai {!scandic}).
[!Code] T3=$CODE,*;CODE=,* CODE=$T3,*;T3=,* T3=999, CODE=999, !]
Commented section can be closed with inverted end sequence (e.g. !] or !}) for syntax highlighting. However this is not mandatory for conversion functionality.
Each conversion file section can have some settings. These are partly same as in Code table function, but have effect only inside section. Setting line starts with characters !@ and the setting name must be followed by a colon character. Rest of the line is settings value (e.g. !@LeftRule:#TYPE=POINT). Setting can be given anywhere within section and have effect until it is set again or the section ends.
Following settings are available:
| Setting | Description |
|---|---|
| LeftId | Default attribute for left column |
| RightId | Default attribute for right column |
| ConvertId | Default attribute for both columns |
| ThirdId | Default attribute for third column |
| LeftRule | Additional rule for left column |
| RightRule | Additional rule for right column |
| ConvertRule | Additional rule for both columns |
| ThirdRule | Additional rule for third column |
| LinePoint | Handle also line points |
| TextPoint | Handle also text points |
| FileData | Handle also file attributes |
Column default attributes are used if no attribute name is given in the conversion line (e.g. 123 456 -> T3=123 T3=456). Column additional rules are added to all conversion lines in the section (e.g. 123 456 -> 123;#TYPE=POINT 456;#TYPE=POINT). Other settings are used to handle also line points, text points or file attributes. Value 1 turns setting on and value 0 off (e.g. !@ FileData:1).