	Product:	MicroStation
	Version:	CONNECT, 2023
	Environment:	N/A
	Area:	Printing
	Subarea:	Design Script

The following keyword descriptions include a brief description of the keyword function, the types of elements the keyword affects (if applicable), the valid data type(s) (if applicable), and an example of how to use the keyword in a Design Script.

Note: The Characters keywords in the "Assignment Keywords" section can be used in comparison statements. See the "Assignment Keywords" section for more information on the Characters keywords.

angle

The angle keyword specifies the angle for element types cell, text node, ellipse, arc, and text. For other element types, the angle value is 0.0.

Data Type: real number in the range of 0.0 to 360.0

Example:

!
! Change the color of text
! elements rotated 90 degrees.
!
if ((type == text) and (angle == 90.0)) then
	 color = 2
endif

area_fill

The area_fill keyword checks to see if the current element is filled.

Data Type: constant (true or false)

Example:

!
! Change the fill color of all filled elements.
! Do not alter elements that are not filled.
!
if (area_fill == true) then
	 fill_color = 10
endif

cellname

The cellname keyword specifies the name of the cell if the current element is a cell header or a component of a cell. For components nested within one or more cells, the cellname keyword specifies the name of the outermost cell unless the component is a nested cell header. In this case, the cellname keyword is the name of the nested cell. If the current element is not a cell header or is not a component of a cell, the value for cellname is "NO_CELL." Wildcards can be used in string comparisons of equality or inequality.

Note: To find the name of the innermost cell name, use the nested_cellname keyword.

Data Type: string

Example:

!
! Change the color of all components of the cell
! named "border."
!
if (cellname == "border") then
	 color = (200,200,200)
endif

characters

The characters keyword specifies the string contained in the element if the current element is a text element. Wildcards can be used in string comparisons of equality or inequality.

Data Type: string

Example 1:

!
!Highlight any text strings that contain the string
!'School' or 'Hospital'.
!
if ((type == text) and (characters =='*School*')) then
	color = (0,0,255)
else if ((type == text) and (characters =='*Hospital*')) then
	color = (255,0,0)
endif

Example 2:

!
!Removes the text "preliminary" if it appears in
!"border" file.
!
if ((lname=="border") and (characters=="preliminary")) then
	 ignore_element=true
endif

class

The class keyword specifies the class type of the current element. For example, the class of the current element might be used in a design script to determine if the current element is part of a dimension or pattern.

Data Type: integer in the range from 0 to 6, or one of the following constants:

0 primary

1 pattern_component

2 construction

3 dimension

4 primary_rule

5 linear_pattern

6 construction_rule

Example:

!
!Do not plot pattern and dimension class elements.
if ((class == pattern_component) or (class == dimension)) then
	 ignore_element = true
endif

cls_end_width

The cls_end_width keyword tests the ending width, in master design file units, of the custom line style associated with the current element. If the current element does not have an associated custom line style, the cls_end_width is 0.0.

Data Type: real number

Example:

!
! Change the color of all elements with
! a custom line style whose ending
! width is greater than 2 master design units.
!
if (cls_end_width > 2.0) then
	 color = 5
endif

cls_name

The cls_name keyword tests the name of the custom line style associated with the current element. For elements without an associated custom line style, the cls_name is "NONE."

Data Type: string

Example:

!
! Change the color of all elements using the style.
! Assign the "origin" custom line style to all
! other elements.
!
if (cls_name == '{ Diamond }') then
	 color = 2
else
	 cls_name = "origin"
endif

cls_origin_width

The cls_origin_width keyword tests the starting width, in master design file units, of the custom line style associated with the current element. If the current element does not have an associated custom line style, the cls_origin_width is 0.0.

Data Type: real number

Example:

!
! Change the color of all elements with a
! custom line style whose starting
! width is greater than 2 master design units.
!
if (cls_origin_width > 2.0) then
	 color = 5
endif

cls_scale

The cls_scale keyword tests the scale factor applied to the custom line style associated with the current element. If the current element does not have an associated custom line style, the cls_scale is 1.0.

Data Type: real number

Example:

!
! Change the color of all elements with a
! custom line style whose scale is 2.
!
if (cls_scale == 2.0) then
	 color = 5
endif

cls_shift_distance

The cls_shift_distance keyword tests the shift distance, in master design file units, applied to the custom line style associated with the current element. If the current element does not have an associated custom line style, the cls_shift_distance is 0.0.

Data Type: real number

Example:

!
! Change the color of all elements with a
! custom line style whose shift
! distance is 0.5 master design units.
!
if (cls_shift_distance == 0.5) then
	 color = 5
endif

cls_shift_fraction

The cls_shift_fraction keyword tests the shift fraction applied to the custom line style associated with the current element. If the current element does not have an associated custom line style, the cls_shift_fraction is 0.0.

Data Type: real number

Example:

!
! Change the color of all elements with a
! custom line style whose shift
! fraction is 0.25.
!
if (cls_shift_fraction == 0.25) then
	 color = 5
endif

color

The color keyword indicates the color index of the current element.

Data Type: integer in the range from 0 to 255

Example:

!
! Area fill shapes with a color index of 1.
!
if ((color == 1) and (type == shape)) then
	 area_fill = true
endif

envr_value

The envr_value keyword is used to compare the value of a print definition environment variable which is chosen by setting the envr_variable assignment keyword. If the variable has not been set or is not a valid variable, envr_value is set to a zero-length string.

Data Type: string

Example:

!
!Get the value of the print definition environment variable
!ARCHITECT. Find text element with characters
!equal to "$Architect$" and change the text value
!to "Designed by <name>" if ARCHITECT is equal to 
!"Owner1" or "Owner2." Otherwise, change the text
!value to a blank string.
!
envr_variable = "ARCHITECT"
if((type ==text) and (characters == "$ARCHITECT$")) then
 if (envr_value .IN. "Owner1", "Owner2") then
		 characters = "Designed by " + envr_value
	else
		 characters = "" 
	endif
endif

envr_value_num

The envr_value_num keyword is used to compare the value of a print definition environment variable which is chosen by setting the envr_variable assignment keyword. If envr_variable has not been set or is not a valid variable, envr_value_num returns the real number zero.

Data Type: real

Example:

!
!Get the value of the print definition environment variable
!MYCOLOR. If the value of MYCOLOR is greater than
!5, set the weight to 2.
!
envr_variable = "MYCOLOR" 
if(envr_value_num gt 5) then
		 weight = 2
endif

file

The file keyword specifies the file attachment number for the file being processed. Typically, the master file is attachment number 0. Generating a metafile from the command line prints the filename and its attachment number for each reference file.

Data Type: integer

Example:

! If the current element is in the master file
! (index of 0), change its color to 2.
!
if (file == 0) then
	 color = 2
endif

fill_color

The fill_color keyword indicates the fill_color index of the current element. In the case where the element is not filled, fill_color returns a value of -1.

Data Type: integer in the range from -1 to 255

(where -1 indicates no fill_color for the element)

Example:

!
! Shapes with a fill color index of 1
! will be plotted red.
!
if ((fill_color == 1) and (type == shape)) then
	 fill_color = 'red'
endif

Example:

!
! Do not plot shapes that are
! not filled.
!
if ((fill_color == –1) and (type == shape)) then
	 ignore_element = true
endif

first_time

The first_time comparison keyword lets you execute a segment of a design script one time. This keyword (flag) is TRUE the first time the design script is called, and then the value is set to FALSE. The value cannot be reset. A good use for this keyword is when you specify a bookmark template. See the example at the end of this section.

Note: When the system processes a design script, each element in the design file is processed in a top-down order until each element is processed. If the first element in the design file executes the first_time code snippet, the remaining elements will be processed but they will skip the first_time code snippet.

font

For text and text nodes, the font keyword contains the font number for the current element. For elements other than text and text nodes, the font number is zero.

Data Type: integer in the range from 0 to 255

Example:

!
! Do not plot text elements that use font 10.
if ((type == text) and (font == 10)) then
	 ignore_element = true
endif

font_name

For text and text nodes, the font_name contains the font name for the current element. For elements other than text and text nodes, the font name is "NO_FONT_NAME."

Data Type: String

Example:

!
! Change the color of all text elements
! using the "architectural" font.
if ((type == text) and (font_name == 'architectural')) then
	 color = 'gray'
endif

header_level

The header_level comparison keyword returns the top-level parent level for elements that are components of a complex element. For example, suppose you have two instances of a single shared cell in a design file: one placed on level 2, the other on level 3. The shared cell definition contains a single shape element on level 1. The only way to distinguish between the two pieces of geometry is the parent level. You can use the header_level keyword in a design script to apply a named color "red" to the shared cell on level 2.

Data Type: integer

Example:

!
! Change the color of a shared cell on level 2.
!
if ((header_type == shared_cell) and (header_level == 2)) then
	color = 'red'
endif

header_level_name

The header_level_name comparison keyword returns the top-level parent level for elements that are components of a complex element. For example, suppose you have two instances of a single shared cell in a design file: one placed on Level A, the other on Level B. The shared cell definition contains a single shape element on Level C. The only way to distinguish between the two pieces of geometry is the parent level. You can use the header_level_name keyword in a design script to apply a named color "red" to the shared cell on Level A.

Data Type: string

Example:

!
! Change the color of a shared cell on Level A.
!
if ((header_type == shared_cell) and (header_level_name == 'Level A')) then
	 color = 'red'
endif

header_type

The header_type keyword determines the outermost complex header type for elements that are components of a cell or shared cell. If the current element is not part of a cell or shared cell, the value of the header_type keyword is the same as the element's type.

Data Type: integers that correspond to valid header element types or one of the following constants: cell or shared cell

Example 1:

!
! If the current element is a component of a cell,
! change its weight to 2.
!
if (header_type == cell) then
	 weight = 2
endif

ip_scale_num

The ip_scale_num keyword gets the print definition scale as a number. The number is always returned in the form of master units/print units, regardless of how MS_PLT_SCALE_METHOD is set. For example, if the scale ratio displayed in the print dialog is master units : print units, and your scale is set to 2:1, the single-value numeric scale factor would be 2.0/1.0, or 2.0.

Data Type: real number

Example:

!
! Plot line thickness based on the print definition scale.
!
if (ip_scale_num ==2) then
!large drawing use thick lines
	thickness = (weight +1) * .02
else
!small drawing use thinner lines
	 thickness = (weight +1) * .01
endif

ip_xsize_num

The ip_xsize_num keyword gets the print definition xsize as a number.

Data Type: real number

Example:

!
! Plot line thickness based on the print definition xsize.
!
if (ip_xsize_num > 17) then
	 !large drawing use thick lines
	 thickness = (weight +1) * .02
else
	 !small drawing use thinner lines
	 thickness = (weight +1) * .01
endif

ip_ysize_num

The ip_ysize_num keyword gets the print definition ysize as a number.

Data Type: real number

Example:

!
! Plot line thickness based on the print definition ysize.
!
if (ip_ysize_num > 17) then
	 !large drawing use thick lines
	 thickness = (weight +1) * .02
else
	 !small drawing use thinner lines 
	 thickness = (weight +1) * .01
endif

level

The level keyword contains the level number of the current element.

Data Type: integer greater than or equal to zero

Example:

!
! Set the color of the element based on its level.
!
if (level == 1) then
	color = 1
else if (level == 2) then
	 color = 2
endif

level_name

The level_name keyword contains the level name of the current element. Wildcards can be used in string comparisons of equality or inequality.

Data Type: string

Example:

!
! Set the color of the element based on its level.
!
if (level_name == "floor1") then
	 color = 1
else if (level_name == "floor2") then
	 color = 2
endif

lname

If the current element is in a reference file, the lname keyword contains the logical name of the reference file. If the current element is in the master file, the lname keyword evaluates to an empty string (""). Wildcards can be used in string comparisons of equality or inequality.

Data Type: string

Example:

!
! Change the weight of all elements in the
! reference file with the logical name of
! "border" to be a weight of 2. Elements in
! the master file and other reference
! files will not be changed.
!
if (lname == 'border') then
	 weight = 2
endif

model_format

The model_format keyword allows you operate on elements inside one of the following model formats: DGN7, DGN8, DWG, or DWF.

Data Type: constants (DGN7, DGN8, DWG, or DXF)

Example:

!
! Apply a different screening percentage for
! each model format.
!
if (model_format == DGN7) then
	 screening = 20
else if (model_format == DGN8) then
	 screening = 30
else if (model_format == DWG) then
	 screening = 40
else if (model_format == DXF) then
	 screening = 50
endif

nested_cellname

If the current element is a cell header or a component of a cell, the nested_cellname keyword specifies the name of the cell. For components nested within one or more cells, the nested_cellname keyword specifies the name of the innermost cell. If the current element is not a cell header or is not a component of a cell, the value for the nested_cellname keyword is "NO_CELL." Wildcards can be used in string comparisons of equality or inequality.

Note: To find the name of the outermost cell name, use the cellname keyword.

Data Type: string

Example:

!
! Change the weight of all components of the nested
! cell named "FRAME."
!
if (nested_cellname == 'FRAME') then
	 weight = 3
endif

properties

The properties keyword provides two methods for determining if bits in the properties word of the element are set. For example, the following two relational expressions are equivalent:

if(hole == true) then	if(properties == hole) then
.	.
.	.
.	.
endif	endif

Data Type: one of the following constants:

attributes

hole

locked

modified

new_element

nonplanar

nonsnappable

screen_relative

Example:

!
! Do not plot any element with the screen_relative
! bit set in the properties word.
!
if (properties == screen_relative) then
	 ignore_element=true
endif

size

For text elements, the size keyword is the height of the text string. For all other elements, the size is the largest of the X, Y, or Z range of the element.

Data Type: working units

Example:

!
! Change the color of text elements whose height is 
! greater than 4 subunits.
!
if ((type == text) and (size > 0:4:0)) then
	 color = 3
endif

style

The style keyword contains the value of the current element's line style. If the style has been set earlier in the design script by the style keyword, then style will evaluate to the new style instead of the original style of the element. Also, if a named style or transitions have been used to set the style of an element, the style comparison keyword will not reflect this. It will evaluate to the current style index.

Data Type: integer in the range from 0 to 7

Example:

!
! Change the color of any element not on level 1 
! that has a line style of 7.
!
if ((level<>1) and (style == 7)) then
	 color = 2
endif

tag keywords

The tag keywords check the tag data attached to the current element. If tag data is not attached to the current element, the TAG_CHARACTER keyword evaluates to "NO_TAG_CHARACTER," while TAG_INTEGER and TAG_REAL evaluate to NO_TAG_NUM.

The following are brief descriptions, data types, and examples of the tag keywords.

Tag_display	checks to see if a particular type of tag is displayed.
Tag_character	tests the actual tag's value.
Tag_integer	tests the actual tag's value.
Tag_real	tests the actual tag's value.

Note: The tag_character, tag_integer, and tag_real comparison keywords must be used with the tag_set and tag_name assignment keywords.

Data Types:

tag_character	string
tag_display	constant (true or false)
tag_integer	integer
tag_real	real number

Example:

!
! Assuming the design file uses two tag sets,
! "Home address" and "Work address," each
! containing a character tag named "City,"
! change the color of all elements whose tags
! specify a home address of "Huntsville" or a
! work address of "Madison."
!
! Start by looking for "City" tags belonging to
! the "Home address" tag set.
!
tag_set = 'Home address'
tag_name = 'City'
if (tag_char == 'Huntsville') then
	 color = 4
endif
! Now look for tags in the "Work address"
! tag set.  Note that the tag name is still "City".
tag_set = 'Work address'
if (tag_char == 'Madison') then
	 color = 4 
endif

text_node_number

The text_node_number comparison keyword can be used to test against the text node number of a text node complex element.

Data Type: integer

Example 1:

!
! Change the color of text associated with a specific
! text node number.
!
if (text_node_number eq 46) then
	 color = 3
endif

Example 2:

!
! This design script sets a plot sheet attribute
! based on the characters stored in a text node element
! in the design file. This sheet attribute can be used
! as attribute date in a digital archive.
if (text_node_number eq 10) then
	 envr_variable = "Author"
	 envr_value = envr_value + " " + characters
else if (text_node_number eq 11) then
	 envr_variable = "Title"
	 envr_value = envr_value + " " + characters
endif

type

The type keyword determines the element type of the current element.

Data Type: integers that correspond to valid element types, or one of the following constants:

arc (type 16)	line_string (type 4)
assoc_dim(type 33)	mesh (type 105)
bspline_curve (type 27)	multiline(type 36)
bsplne_surface(type 24)	shape (type 6)
cell (type 2)	shared_cell (type 35)
complex_shape (type 14)	solid (type 19)
connected_string (type 12)	surface (type 18)
curve (type 11)	text (type 17)
ellipse (type 15)	text_node (type 7)
line (type 3)

Example:

!
! Change the color of lines, linestrings, and curves
! on level 1
!
if ((type in 3,4,11) and (level == 1)) then
	 color = 1
endif

Note: To test for multiline and associative dimensioning elements, use header_type instead of type.

weight

The weight keyword contains the value of the current element's line weight.

Data Type: integer in the range from 0 to 31

Example:

!
! Set color of element based upon its weight
!
units = inches
if (weight == 0) then
	  color = 1
else if (weight == 1) then
	  color = 2
else if (weight == 2) then
	 color = 3
else if (weight == 3) then
	 color = 4
else if (weight == 4) then
	 color = 5
else if (weight == 5) then
	 color = 6
endif

width

The width keyword is valid only for 2D lines, linestrings, ellipses, arcs, and connected strings. All other elements and 3D elements have a width value of 0. The width value is extracted from the element's Z low range field and specifies the element's line width in working units as opposed to a weight value.

Data Type: working units

Example:

!
! Change the color of lines, linestrings, connected
! strings, arcs, and ellipses based on their width. 
!
units = inches
if (type .in. 3,4,12,15,16) then 
	if (width  == 0:0:050) then 
		 color = 1
	else if (width == 0:0:100) then 
		 color = 2
	else if (width == 0:0:150) then
		 color = (30,50,100)
	else if (width == 0:0:200) then
		 color = (100,0,0)
	else if (width > 0:0:300) then
		 color = (0,0,0)
 endif
endif

Other language sources

Original Author:

Jayson Perry

Design Script Comparison Keywords

angle

area_fill

cellname

characters

class

cls_end_width

cls_name

cls_origin_width

cls_scale

cls_shift_distance

cls_shift_fraction

color

envr_value

envr_value_num

file

fill_color

first_time

font

font_name

header_level

header_level_name

header_type

ip_scale_num

ip_xsize_num

ip_ysize_num

level

level_name

lname

model_format

nested_cellname

properties

size

style

tag keywords

text_node_number

type

weight

width

See Also

Other language sources