Export-DGN Configuration File

Equipment

Equipment : Import/Export DGN : Export-DGN Configuration File

In order to produce an attribute file from Export-DGN, create an Export-DGN configuration file, and inform Export-DGN of its location in either of two ways:

•

Setting the environment variable EXPLANT_CONFIGURATION to the path of that file before starting MODEL, for example

set EXPLANT_CONFIGURATION = %AVEVA_DESIGN_EXE%\config.sample

If the same configuration file is always used, this is particularly useful.

•

Use the export option 'configuration' ‘<filename>’ command in MODEL to set the path of the configuration file. For example

export option 'configuration' ' C:\configs\config.txt'

If different configuration files for different exports are used, this is particularly useful.

The Export-DGN log-file contains the path of the configuration file used for the run.

Example Configuration File for HTML

Here is a complete example configuration file, the file instructs Export-DGN to create a file of commands to display some attributes of valves in the database.

The example output format used is HTML (Hyper Text Mark-up Language). The example shows how the Export-DGN commands can be used to create tables that can be viewed using a browser, such as Internet Explorer.

The configuration commands used are explained later in this section.

Some of the commands do not fit on a single line of this document and have been split. When the user sees a  character, this means that the next line of the example is really part of the same original line.

When Export-DGN is run using this configuration file it writes, in addition to the usual .dgn file, a .htm file similar to this:

<HTML><HEAD>
<TITLE>Sample Export-DGN HTML output </TITLE>
</HEAD><BODY><H1>AVEVA Attributes</H1>
<TABLE BORDER><CAPTION>Cell 1 0</CAPTION>
<TR><TD>Valve</TD><TD>/V102</TD></TR>
<TR><TD>Branch</TD><TD>/100-B-1-B1</TD></TR>
<TR><TD>Specification</TD><TD>/A3B/VCW100</TD></TR>
<TR><TD>POS</TD><TD>12490 12280 1836.5</TD></TR>
</TABLE>
<TABLE BORDER><CAPTION>Cell 2 0</CAPTION>
<TR><TD>Valve</TD><TD>/V103</TD></TR>
<TR><TD>Branch</TD><TD>/100-B-1-B1</TD></TR>
<TR><TD>Specification</TD><TD>/A3B/VG100</TD></TR>
<TR><TD>POS</TD><TD>12490 12280 2063.4</TD></TR>
</TABLE>
... More tables omitted ...
</BODY></HTML>

And when this file is viewed with a web-browser it appears similar to this:

Structure of the Configuration File

The Export-DGN configuration file is a text file, which may be produced with any text editor (such as notepad).

•

Lines whose first non-blank characters are $* are treated as comments, and are not processed

•

Character strings may be quoted with | characters, and must be quoted if spaces are included in the string

•

Blank lines are permitted (and ignored)

•

Spaces and tabs may be included before commands

•

Words of commands are separated by one or more spaces or tabs (spaces and tabs within |quotes do not separate words)

•

Commands may not be split over more than one line

•

Commands are not case-sensitive

•

Select the Output Files

Switch the Attribute File On or Off


Keywords:	ATTRIBUTE_FILE
Description:	The command switches the Attribute file on or off, and sets its file-extension. The default is not to create an attribute file.

Examples:


ATTRIBUTE_FILE NO	Do not create an attribute file
ATTRIBUTE_FILE html	Create an attribute file with extension .html
ATTRIBUTE_FILE EXTENSION \|no\|	Create an attribute file with extension .no

Control the Encoding of the Attribute File


Keywords:	ENCODING
Description:	The command sets the character encoding for the Attribute File. The default is Latin-1.

Examples:


ENCODING ASCII	Write only 7-bit ASCII characters to the attribute file.
ENCODING LATIN1	Write "Western European" characters in ISO/IEC 8859-1 encoding (this is the default).
ENCODING UTF8	Write characters in the UTF-8 encoding, adding a byte-order-mark at the start of the file.
ENCODING UTF8		ENCODING UTF8 NOBOM	Write characters in UTF-8, but do not write a byte-order mark at the start of the file.

Switch the DGN File On or Off


Keywords:	DGN_FILE
Description:	The command switches the DGN file on or off. The default is to create a DGN file.

Examples:


DGN_FILE NO	Do not create a DGN file
DGN_FILE YES	Create a DGN file

Define the Output Format

Export-DGN has a very flexible output format that enables attribute data to be exported in the way that is most useful to the user. The section describes the configuration commands available to control the output format.

Link to the DGN File

Four numbers link the cells in the dgn file to the attributes in the attribute file. These are stored as an Attribute Linkage. The first two of these are constant for all cells in the file and may be set by the ATTRIBUTE_LINKAGE command. For example, a web-browser is not read and the dgn file itself has no particular requirements:

ATTRIBUTE_LINKAGE 32768 0

Export-DGN generates the other two numbers, which change for each cell in the file.

Define the Head and Foot of the Attribute File

To define constant information to be placed at the start or end of the attribute file, use the FILE_HEADER and FILE_FOOTER commands. Each may be used more than once.

For example the HTML file needs three lines at the start:

<HTML><HEAD>
<TITLE>Sample Export-DGN HTML Output </TITLE>
</HEAD><BODY><H1>AVEVA Attributes<H1>

and one line at the end:

</BODY></HTML>

and so the configuration file has three FILE_HEADER commands and one FILE_FOOTER command:

FILE_HEADER |<HTML><HEAD>|
FILE_HEADER |<TITLE>Sample Export-DGN HTML Output
</TITLE>|
FILE_HEADER |</HEAD><BODY><H1>AVEVA E3D™ Attributes<H1>|
FILE_FOOTER |</BODY></HTML>|

Define the Head and Tail of an Element

The HTML file needs to start the table and define a caption at the start of each element, for example:

<TABLE BORDER><CAPTION>Cell 1 0</CAPTION>

and needs to close the table afterwards:

</TABLE>

Some of the information in the element header changes from element to element, and so the command uses two variables in the quoted strings:

ELEMENT_HEADER |<TABLE BORDER><CAPTION>²
Cell %ID1% %ID2%</CAPTION>|
ELEMENT_FOOTER |</TABLE>|

These variables (%ID1% and %ID2%) are replaced whenever an element is processed by the current identification numbers (the third and fourth numbers in the dgn attribute linkage). Refer to Variables Available for a list of all available variables.

Define the Format of an Attribute

Each attribute is output using a single text format, with the variable %TAG% set to the tag defined for the attribute, and %VALUE% set to the value of the attribute.

The HTML needed for one line of a table is:

<TR><TD>Valve</TD><TD>/V102</TD></TR>

and so the command needed is:

ATTRIBUTE_FORMAT
|<TR><TD>%TAG%</TD><TD>%VALUE%</TD></TR>|

As another example, to create a file with attribute lines looking like:

Valve = "/V102"

use the command:

ATTRIBUTE_FORMAT |%TAG% = "%VALUE%"|

Variables Available

Variables available for selection to in the formats are as follows, these are replaced by the appropriate values when the format is used:

•

%LINKAGE1% is replaced by the first value from the ATTRIBUTE_LINKAGE command, (the first of the four linkage numbers in the dgn file) in the range from 0 to 65535

•

%LINKAGE2% is replaced by the second value from the ATTRIBUTE_LINKAGE command, (the second of the four linkage numbers in the dgn file) in the range from 0 to 65535

•

%ID1% is replaced by the first ExPLANT-I generated identification number, (the third of the four linkage numbers in the dgn file) in the range from 0 to 65535

•

%ID2% is replaced by the second ExPLANT-I generated identification number, (the last of the four linkage numbers in the dgn file) in the range from 0 to 65535

•

%#LINKAGE1%, %#LINKAGE1%, %#ID1% and %#ID2% are replaced by the same values, but in the range -32768 to32767

•

%TAG% is replaced with the attribute tag

•

%VALUE% is replaced with the attribute value

•

%% is replaced by a single % character

•

If a format ends in a single % then Export-DGN does not move to the next line of the Attribute File before the next item.

Set the Output Units


Keywords:	OUTPUT_UNITS
Description:	The command controls how Export-DGN writes units to the attribute file. It does not affect unit handling within the DGN file. The default is use AVEVA E3D™ internal units (typically millimetres).

Examples:


OUTPUT_UNITS RAW	Use AVEVA E3D™ internal units, this should not be combined with any other OUTPUT_UNITS command
OUTPUT_UNITS MM DECIMAL 3	When writing a value in millimetres, use three decimal places.
OUTPUT_UNITS INCH DECIMAL 2	When writing a value in inches, use two decimal places.
OUTPUT_UNITS FINCH FRACTION 32	When writing a value in feet and inches, use fractions as small as 1/32 of an inch.
OUTPUT_UNITS BORE NOMINAL MM DECIMAL 3	When writing a value which is in bore units, output the nominal bore in millimetres to three decimal places.
OUTPUT_UNITS BORE ACTUAL INCH	When writing a value which is in bore units, output the actual bore in inches to the ordinary inch precision.
OUTPUT_UNITS DISTANCE FINCH FRACTION 64	When writing a value in distance units, output in feet and inches to 1/64 of an inch.

Here are some examples of sets of OUTPUT_UNIT commands:

If bore and distance values are to be reported in millimetres, using the nominal bore to one decimal place, all other dimensions to three decimal places the user should include:

OUTPUT_UNITS MM DECIMAL 3
OUTPUT_UNITS DISTANCE MM
OUTPUT_UNITS BORE NOMINAL MM DECIMAL 1

If distances are to be in feet, inches and eighths of an inch, actual bores in inches to three decimal places, and any other inch dimensions to one decimal place the user should include:

OUTPUT_UNITS DISTANCE FINCH FRACTION 8
OUTPUT_UNITS BORE ACTUAL INCH DECIMAL 3
OUTPUT_UNITS INCH DECIMAL 1

Select Attributes for Output

Choose Elements

Each element type in the attribute file can be reported on but a block of commands must be included in the configuration file. The block starts with the type of the element, and ends with the corresponding END_ command. Between these two, include the attributes that they require.

For example:

BRANCH
    ALL_ATTRIBUTES
    ALL_UDAS
END_BRANCH

VALVE
    NAME
    SPREF
    :MANUFACTURER
END_VALVE

Each element found when Export-DGN is scanning the DESIGN database according to the export commands is checked so see if it is one of those listed in the configuration file. If it matches, a MicroStation Cell is added to the dgn file. Since the MODEL is hierarchical, with, for example ZONEs containing PIPEs containing BRANCHes containing VALVEs, this, by default, creates Cells within Cells in the dgn file, this can lead to two problems:

•

There is a limit on the amount of data that can be put in a MicroStation Cell. A ZONE almost certainly exceeds this limit

•

Some applications that read dgn files may not interpret nested cells correctly.

To deal with these situations it is possible to tell Export-DGN to handle some elements differently, and either to use an empty cell, or a cell containing geometry, but not nested cells. If the user uses the EMPTY qualifier on an element line, for example

ZONE EMPTY
NAME
END_ZONE

Export-DGN creates an almost empty cell in the dgn file, and link the attributes to that. As the cell is almost empty it does not exceed the size limit. The cell does not completely empty as many dgn file readers reject completely empty cells. (If necessary, a line of zero length is put in the cell). It is often better to use the facilities to report on the attributes of another element (described in Attributes of Other Elements) to report attributes of these very high-level attributes.

If the NONEST qualifier on an element line is used then Export-DGN writes a cell to the dgn file which may contain geometry, but does not contain the cells of other elements from the configuration file (it may contain cells produced for geometry defined in AVEVA E3D™ as facets). It is recommend that the user only uses this option if the system reading the dgn file cannot cope with the default NEST option.

An example of a possible use of NONEST is when the user wants to have cells for valves, but to gather all the geometry within a branch except for the valves into a branch-cell. The user can express this as:

BRANCH NONEST
    ALL_ATTRIBUTES
END_BRANCH

VALVE
    ALL_ATTRIBUTES
    NAME OF BRANCH
END_VALVE

If a particular cell would exceed the maximum possible size, Export-DGN excludes some of its contents from the cell. All the geometry is included in the file, but it is not included in the cell structure. If this happens, a warning message is output to the log-file.

Choose Multiple Elements

If the same set of attributes need to be reported for multiple element types the ELEMENTS / END_ELEMENTS commands can be used, as in the example below:

ELEMENTS
ELEMENT GASKET
ELEMENT CROSS
ELEMENT ELBOW
ELEMENT BRANCH
    ALL_ATTRIBUTES
    ALL_UDAS
END_ELEMENTS

The start of the block is defined by the command ELEMENTS. Each element type that is to output the same set of attributes is then listed in the lines after the ELEMENT command. Any number of element types can be listed but they must be listed in consecutive lines. The attributes are then defined in exactly the same was as described in Choose Elements. The block is then terminated by the END_ELEMENTS command.

Choose Attributes

There are two special commands to report on groups of attributes at once:

•

ALL_ATTRIBUTES: if this is included in an element-block all attributes available in the element (apart from user-defined attributes) are listed in the Attribute file

•

ALL_UDAS: if this is included in an element block all user-defined attributes are listed in the Attribute file.

To report on individual attributes include them by name, for example by the Q ATTS command in MODEL. To report on a UDA (user-defined-attribute) include the leading colon, in Q ATTS. It may be useful to always include one or two standard attributes, for example the AVEVA E3D™ TYPE and NAME of the element, so that they can always connect back to the AVEVA E3D™ element from which the attributes were extracted.

Change the Tag in the Attribute File

If the tag given to the attribute in the attribute file is to be changed, use the AS modifier. For example

TYPE AS |Class of Element|
NAME AS  |ID|

Note:

When the new tag includes spaces, quote it in ||. In the second example it is not strictly necessary to use the quotes, as the new tag is a single word, but it is recommended, for consistency, to use them.

Reference Attributes

By default, if the user asks for a reference attribute, Export-DGN reports the name of the element referred to. For example, if the element block were

VALVE
TYPE
NAME
REFNO
SPREF
END_VALVE

the report might be

TYPE: VALVE
NAME: /V102
REFNO: /V102
SPREF: /A3B/VCW100

Sometimes the reference may be reported as the database reference number, rather than its name. In this case the user must add the ASREF modifier to the attribute. For example:

VALVE
TYPE
NAME
REFNO ASREF
SPREF
END_VALVE

might produce the report

TYPE: VALVE
NAME: /V102
REFNO: =40/92005
SPREF: /A3B/VCW100

Combine the AS and the ASREF modifiers, for example:

REFNO ASREF AS |AVEVA E3D™ Reference|

Attributes of Other Elements

Report on attributes of other elements referred to by the element they are working on, for example some attributes of an element owning the current element, or of the specification referred to by the element. The user can do this by using OF modifiers, for example

VALVE
    NAME OF PIPE AS |Pipe-name|
    CATREF OF SPREF
    OWNER OF PTREF OF CATREF OF SPREF ASREF
    :LOCATION OF ZONE
    :VISIBLE OF SPEC OF PSPEC OF BRANCH
END_VALVE

As the user can see from these examples, they can chain OF modifiers, and combine them with the other modifiers.

Using WRT

If the position or orientation attribute of an element needs to be output with respect to some other element in the DESIGN databases, WRT may be used. For example:

DISH
    POS WRT WORLD
    POS WRT =23964/17687
END_DISH

The example would display the dish position first in terms of world coordinates, then with respect to the position of the element represented by the database reference number =23964/17687

The WRT target may be either a database reference number or an element type within the design that owns the current element directly or through the hierarchy, such as WORLD, SITE, ZONE, OWNER. It is not currently possible to specify the WRT target by an element name.

Array Attributes

If the attribute being reported is an array, then normally all items in the array are listed. If the user wants to report a particular item from the array, they can choose a particular index, for example:

PARA [3] OF CATREF OF SPREF

Note:

There must be a space between the attribute name and the [ character.

Miscellaneous Commands

Control Cell Names

By default Export-DGN names all the cells produced for the chosen elements. These names are not particularly meaningful, but some applications and dgn file-checking utilities consider cells without names to be errors. To switch off the cell names add the command

NAME_CELLS NO

to the configuration file.