Comparison Keywords
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.
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.
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.
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.
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:
Data Type: one of the following constants:
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. |
Data Types:
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
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