CADLMAN.TXT contains a description of programming features found in CADL, the CADKEY Advanced Design Language. A bound version of this document with examples accompanying each command is available from Cadkey. If you are new to CADL programming you may also be interested in the CADL/CDE Training Kit "Exploring CADKEY's Open Architecture." This training kit offers an introduction for beginners covering a complete description of CADL and CDEs (Cadkey Dynamic Extentions - Program Extensions written in C). The kit contains numerous examples in the text and on a sample files disk. Both the CADL Reference Manual and The CADL/CDE Training Kit can be ordered directly from Cadkey using the FAX-back forms included with your package. Table Of Contents - CADL Reference Manual Introduction To CADL CADL Guide Format Section One: Basics Using CADL CADL Expressions Program Control Statements Section Two: Commands Introduction Entity Primitives Entity Control Display Control Viewport Control View Manipulation User Interaction Data File Input and Output Part and Pattern File Access Setting System Values Strings and Arrays Vector Math Functions Copious Entities Collectives Groups Dialog Box Manager Accessing CDE Modules Section Three: Reference Section Four: CADL Compiler Introduction to CCOMP CCOMP Files Using CCOMP Command Line Options Compiler Directives Compiler Specific Commands Appendices Appendix I: CADL Error Messages Appendix II: System Arrays Appendix III: Entity Information Appendix IV: Dialog Box Errors Appendix V: Dialog Box Entity Attributes Appendix VI: Sample Files ______________________________________________________________________________ Introduction The CADKEY Advanced Design Language (CADL) is a powerful programming language that operates within the structure of the CADKEY program. The flexibility of this language allows you to design and store your own functions and entities within CADKEY, as well as access the CADKEY database. The purpose of this section is to help you understand the basic capabilities of the CADL language. This CADL Guide is divided into the following sections: This section, Introduction to CADL, describes the various formats used throughout this guide. Section One: Basics describes those elements which comprise a CADL program file along with any existing restrictions on their use. This includes register variables, CADL data types, variable declarations, format specifiers, math functions and program control statements.. Section Two: Commands groups all of the commands into their related categories and gives a brief description of each of them. Section Three: Reference is an alphabetic listing of every CADL command, excluding compiler specific commands. Section Four: CADL Compiler explains the use of the CCOMP utility and lists the commands and directives that are specific to compiled programs. The Appendices list CADL error messages, information held in the system arrays, dialog box errors, dialog box entity attributes, and includes four samples programs. ______________________________________________________________________________ CADL GUIDE FORMAT The format used by the CADL guide follows these basic rules: * Commands beginning with sys_ or dg_ are case-sensitive and must be in lower case letters, as they will appear throughout the manual. The rest of the commands are not case-sensitive, but for clarity, will be printed in upper case. For example: sys_get_name ARC * Those parameters considered "optional" are enclosed in square brackets for easy reference. LABEL x1, y1, x2, y2, x3, y3, arrowtype, x, [pen] * Any section of text that is in the following typeface may be taken directly from book and executed. Bold text in this typeface represents on-screen text results. For example, PAUSE "This can typed in directly" will output the following line to the CADKEY prompt line: This can be typed in directly * An ellipses (...) found within square brackets indicates that additional parameters may be specified. GENDIM form, numlines, numarcs, numarrows, arrayname, arrowtype, x, [...] * Described in parenthesis next to each command parameter is a descriptor which indicates the type of parameter. For example: numlines (integer) describes numlines as the name of an integer value. (See CADL Expressions for an explanation of the different types of parameters allowed in CADL.) Those descriptors are explained: (string) identifies a group of characters enclosed by double quotation marks. In an example group of characters such as "This is an example string", all printable characters, spaces and tabs are permitted. A backslash character (\) allows you to include some special characters in the string: \\ backslash \r carriage return \" double quote \n new line \b backspace \f form feed \t tab \a..z results in that character (word) identifies a group of characters delimited by white space or commas. (double) identifies a double precision floating point value. An expression may also be specified, in which case the floating point result is used. (integer) identifies an integer value. An expression may also be specified, in which case the integer result is used. (val) identifies either a floating point or an integer value. An expression may also be specified, in which case the result is used. (fvar) identifies the name of a double precision floating point variable. (ivar) identifies the name of an integer variable. (cvar) identifies the name of a character variable. (var) identifies the name of either a floating point or an integer variable. (farray) identifies name of an array of double precision floating point numbers. It is similar to 'word'. (iarray) identifies name of an array of integers. It is similar to 'word'. _____________________________________________________________________________ Section One: Basics Table Of Contents USING CADL CADL EXPRESSIONS Register Variables CADL Data Types Variable Declarations Data Typing Declaring ARRAYs Declaring SLISTs The CLEAR command Format Specifiers Input Format Specifiers Output Format Specifiers Math Functions PROGRAM CONTROL STATEMENTS The REM statement The IF statement Branching and Looping with Labels Program Branching Exiting a CADL program Suspending CADL Execution Calling External Programs or System Processes Declaring the Security Code String Compiler-Specific Control Statements USING CADL A CADL program file may be generated using a text editor or word processing program under the rules defined in this guide. Names for these files follow the same specifications as the system's naming convention, along with the addition of an extension. Specific extensions are discussed in their respective sections of this guide. To execute a CADL file in CADKEY or CUTTING EDGE, use the FILES, CADL, EXECUTE option. Enter the name of the CADL file and press . If an error is detected, CADL file processing halts and an error message is displayed. For a complete listing of these error messages and their descriptions, refer to Appendix I. A typical CADL file consists of variable length records delimited by new lines. Each of these statements directs the flow of the program. A typical statement represents either a primitive, command or expression, along with any required parameters. Please refer to the Reference section of this guide for detailed information on primitives, program control statements and commands. CADL EXPRESSIONS The purpose of an expression is to evaluate a mathematical statement and optionally store the results in a variable. Refer to Register Variables, found in this section, for an explanation of the different types of variables offered by the system. For example: POINT (2.0+a), 3.0, (a*b) describes a POINT primitive with an x value assigned the results of 2 plus the numeric value of a, a y value of 3, and a z value assigned the results of a times b. Note that in a CADL program, an expression terminates at the end of a line unless a backslash(\) is found. When this is the case, the command is continued on the following line. For example: n = sqrt(a*b)+\ sin(angle)*2*\ (x+y+z) This equation is evaluated as n = sqrt(a*b)+sin(angle)*2*(x+y+z). The backslash (\) must be the last character in the line, immediately preceding the . The following rules apply to CADL expressions. There are three types of constants, as listed below. Integer Constants XE "Integer Constants" A decimal integer is a sequence of digits 0 - 9. If the first digit is a 0, the integer is taken as an octal (base 8) value. In this case only digits 0 - 7 are valid. If the sequence is preceded by the prefix 0x or 0X, the integer is taken as a hexadecimal (base 16) value. In addition to 0 - 9, hexadecimal digits also include the characters a-f (upper or lower case) corresponding to the values 10 - 15 respectively. Float Constants XE "Float Constants" A float constant consists of a signed integer part, a decimal point, a fractional part, an E (or e), and a signed integer exponent. Either the integer part or the fractional part may be omitted, but not both. Either the decimal point or the E (or e) with exponent may be omitted, but not both. String Constants XE "String Constants" A string constant is a sequence of characters enclosed in quotes, such as "this is a string". All strings are treated as an array of characters and are automatically terminated by the null character (ASCII value 0). Thus, the string "hello" actually contains six characters. A special character sequence is provided to denote control characters and characters outside of the ASCII range. The sequence is signaled by a backslash(\) character. When detected, the next character is interpreted as shown below. For characters not listed, the character itself is used. This provides a way of entering characters which normally have a special meaning (e.g., use \\ for the \ character, \" for ", etc.) \b backspace \f formfeed \n newline \r carriage return \t tab In addition to the above characters, an octal value may be entered by following the \ character with a three digit octal number (e.g., \263). Also, a hexadecimal value may be entered by following the \ character with the character x and two hexadecimal digits (e.g., \x85). For an octal value the permissible range is \000 - \377; for a hexadecimal the range is \x00 - \xff. Most of the operators recognized by the expression evaluator are equivalent to their counterparts in the 'C' programming language (those which are different are marked with a *). The list is as follows: Math Operators XE "Math Operators" a + b addition a - b subtraction a * b multiplication a / b division a ^ n nth power of a* (a) precedence a[n] array index -a negative a +a positive a a' feet* a" inches* a % b a (integer) modulus b xxx = b numeric variable assignment $msg="hello" string variable assignment $$msg[x] = "world" slist element assignment a=1.5 double floating point assignment b=1 integer (stored as double) assignment Logical Operators XE "Logical Operators" a == b equal comparison a != b not equal comparison a > b greater than comparison a < b less than comparison a >= b greater than or equal to comparison a <= b less than or equal to comparison a && b AND operation a || b OR operation (a) ? x : y conditional Bitwise Operators XE "Bitwise Operators" a | b a ORed with b a & b a ANDed with b a # b a XORed with b* a >> b a shifted right by count of b a << b a shifted left by count of b ~a complement Algebraic operations are prioritized, as with BASIC, FORTRAN, C and most programming languages. The precedence of operators XE "precedence of operators" , listed below, is grouped by operator type. The group header indicates whether the operators are processed from left to right or vice versa. The list is arranged from higher to lower precedence with operators on the same line having equal precedence. Note that ' (feet) and " (inches) are actually special unary operators. Primary-expression operators (left->right) () [] functions (cos, sqrt, sizeof, etc.) Unary operators (right->left) + - ~ ' " Binary operators (left->right) ^ * / % + - >> << < > <= >= == != & # | && || ?: Assignment operator (right -> left) = Operation Examples Example 1: Statement: x = 4 / 10 * PI + cos(45) Result: variable x is assigned the value 1.963744 Example 2: Statement: x = (y = 23 / 5) + (z = @depth) (where @depth = 0) Results: variable x is assigned the value 4.6 variable y is assigned the value 4.6 variable z is assigned the value of system variable @depth which, in this case, equals zero. Example 3: Statement : $msg = "Hello" Results: The string variable $msg is created with an array size of 6 and contains the characters "Hello" followed by a null terminating character. This is equivalent to the statement: array $msg[6] = {72, 101, 108, 108, 111, 0} Register Variables Variables may substitute a constant numeric value anywhere in a CADL program file (e.g., primitives, commands or expressions), including when specifying an array size. There are two types of variables offered, a variable set by the user, and a system variable maintained and updated by the system. Rules for Register Variables XE "Register Variables" 1) The system register database recognizes and stores floating point (double precision) numeric values only, even if an integer constant was initially assigned. 2) Variables may be assigned a name consisting of any number of characters, however only the first eight are used (any extra characters are ignored). The first character of a variable name must begin with an alpha character. The remaining characters may be any combination of alphanumeric and underscore (_) characters. Upper and lower case differences are observed. 3) Arrays may be used if they have been previously initialized with the ARRAY statement. 4) The maximum number of variables which may be assigned at one time is definable using the configuration program. An arrayname counts as one variable name. 5) A number of reserved variables are maintained and updated by the system. They are accessible through CADL as read-only. These variables must always begin with the @ character. System variables XE "System Variables" are case insensitive. The current list is as follows: @cdldev - CADL input device number @cdlname[] - name of most recently accessed CADL filename @cdlpath[] - directory path of CADL files @cid - ID of currently accessed copious entity @color - current color @const - current system status of 2D/3D construction switch @csize - size of currently accessed copious entity @ctcode - type code of currently accessed copious entity @curvp - current viewport @cview - current construction view number @cwd[] - current working directory path @cviewmat[9] - current construction view matrix @depth - current depth setting @dflt - last value entered on the prompt line @dimfill - current dimension text fill mode @dimfont - current dimension text font number @dimht - current system text height for dimensions @diminfo1[] - array used by some CADL functions to return integer data for the dimension entity @diminfo2[] - array used by some CADL functions to return floating point data for the dimension entity @dimscale - current system dimension scale @dimslnt - current dimension text slant angle @entatt[] - array used by some CADL functions to return attributes for the entity @error - CADL/calculator error number @fltdat[] - array used by some CADL functions to return floating point data @intdat[] - array used by some CADL functions to return integer data @key - character code for last key hit @lastid - ID number of last entity added to database @lastvw - number of the last view added to the database @ldrln[][] - array used by some CADL functions to return data for the leader line @level - current system level @levels[] - displayed levels array mask @ltype - current line type @lwidth - current line width @mscdat[] - array used by some CADL functions to return miscellaneous data @noteang - current system note text angle @notefill - current note text fill mode @notefont - current note text font number @noteht - current system text height for notes @noteline - current note text line spacing factor @noteslnt - current note text slant angle @noteuln - current note text underline mode @notpath[] - directory path of note files @nread - number of data items read with last CADL READ command @numflt - number of items currently in @fltdat array @numint - number of items currently in @intdat array @numpal - number of palette colors supported by graphics controller @numstr - number of items currently in @strdat array @numvp - current number of graphic viewports @palb[256] - current system color palette BLUE values, where: @palb[n] = BLUE value (between 0 and 255) for color palette index n @palg[256] - current system color palette GREEN values, where: @palg[n] = GREEN value (between 0 and 255) for color palette index n @palr[256] - current system color palette RED values, where: @palr[n] = RED value (between 0 and 255) for color palette index n @pen - current pen value @pltname[] - name of most recently accessed plot filename @pltpath[] - directory path of plot files @prtname[] - name of most recently accessed part filename @prtpath[] - directory path of part files @ptnname[] - name of most recently accessed pattern filename @ptnpath[] - directory path of pattern files @refarc[][] - array used by some CADL functions to return data for the reference arc @refln[][] - array used by some CADL functions to return data for the reference line @refpnt[][] - array used by some CADL functions to return data for the reference point @scale - current system viewing scale @selpval - parameter value of marker position on selected entity @selsnum - segment number of marker position on selected entity @sfpath[] - directory path of scratch files @strdat[] array used by some CADL functions to return string data @suppath[] - directory path of support files @txtasp - current system text aspect ratio for note and dimension text @txtatt[] - array used by some CADL functions to return attributes for the dimension text @txtinfo[] - array used by some CADL functions to return integer data for the dimension text @units - current system units mode, English or Metric @versel - current verify selection mode @view - current system view number @viewmat[9] - current view matrix @vwwld - current system status of view/world switch @xcursor - current X cursor location @xcview - last X coordinate value returned by the Position Menu (construction view coordinates) @xmax - X max coordinate of current viewport window @xmin - X min coordinate of current viewport window @xview - last X coordinate value returned by the Position Menu (view coordinates) @xworld - last X coordinate value returned by the Position Menu (world coordinates) @ycursor - current Y cursor location @ycview - last Y coordinate value returned by the Position Menu (construction view coordinates) @ymax - Y max coordinate of current viewport window @ymin - Y min coordinate of current viewport window @yview - last Y coordinate value returned by the Position Menu (view coordinates) @yworld - last Y coordinate value returned by the Position Menu (world coordinates) @zcview - last Z coordinate value returned by the Position Menu (construction view coordinates) @zview - last Z coordinate value returned by the Position Menu (view coordinates) @zworld - last Z coordinate value returned by the Position Menu (world coordinates) @1-@10 - numeric values currently displayed on the prompt line, in order of their appearance CADL Data Types There are various types of data that need to be represented in a program. In the previous versions, CADL supported a single data type, the floating point, in the range of -10^308 to 10^308 and a precision of as many as 15 digits. Two other data types, integer and character, are obtained by using the floating point. Whenever a value is used in integer operations, the value is truncated or rounded to the nearest integer value. Similarly, if a character is divided by 256, the remainder is used as the ASCII value of the character. Now, in addition to the above mechanism, CADL supports more data types. However, if a variable is not defined, it will now be considered a double. The abstract data types supported by CADL are as follows: char XE "data types:char" a single character Example: char letter, digit letter = 'A' digit = '9' double XE "data types:double" double precision floating point data Example: double x, y x = 1.00 y = 2.12345678998765432 float XE "data types:float" floating point data Example: float x, y x = 2.0 y = 10.5 int XE "data types:int" integer Example: int x, y x = 1 y = 10 long XE "data types:long" long integer Example: long x, y x = 39123 y = 5549 short XE "data types:short" short integer Example: short x, y x = 1 y = 5 slist XE "data types:slist" array of strings of characters Example: slist $$xyz[0] $$xyz[0] = "menu1" string XE "data types:string" array of characters Example: string $title $title = "menu1" uchar XE "data types:uchar" unsigned character Example: uchar c c = 'a' uint XE "data types:uint" unsigned integer Example: uint x x = 25 ulong XE "data types:ulong" unsigned long integer Example: ulong x x = 62234 ushort XE "data types:ushort" unsigned short integer Example: ushort x x = 8 Variable Declarations XE "Variable Declarations" Data Typing When you use a variable for the first time and have done no data typing XE "Data Typing Variables" to it, it is assumed to be a double precision variable. However, if you wish to create a variable of any other type (i.e., int, char, etc.) you must data type it in the following manner: data-type var1 [, var2, ... ] For example: int x, y, z This statement declares x, y, and z as integer variables. They will remain typed as integers until you use the CLEAR command on them or quit CADKEY or CUTTING EDGE. You cannot change the data type of a variable once it has been typed unless you use the CLEAR command and then retype it. To data type arrays, you use the same format as above. The only difference is shown in the following example: int pts[0] This line types the array, pts, as an integer array. If an array is not data typed, it will default to an array of doubles. The zero enclosed by brackets after the arrayname on the data type line signifies that arrayname will be later declared as an array. This is not the actual declaration. To use the array, you still must use the ARRAY declaration. This line merely states that when arrayname is declared, it will be an array of the data type you specified. Declaring ARRAY XE " ARRAY" s Arrays allow data to be assigned to a single or multi-dimensional storage array within a CADL program. Data may be assigned to an array anywhere within a CADL file, as long as it is assigned before the array is used. The limit to the number of dimensions in an array is five. Use the following formulas to calculate the maximum size for two to five dimensional arrays: Two-dimensional arrays: ( i, j ) i / 2 + i * j <= maximum Three-dimensional arrays: ( i, j, k ) i * j / 2 + i * j * k <= maximum Four-dimensional arrays: ( i, j, k, l ) i * j * k / 2 + i * j * k * l <= maximum Five-dimensional arrays: ( i, j, k, l, m ) i * j * k * l / 2 + i * j * k * l * m <= maximum To declare an array, you must use one of the following formats: Format 1: ARRAY arrayname[n]={n1, n2, n3...} Format 2: ARRAY arrayname[n] .. arrayname[0] = n1 arrayname[1] = n2 .. To declare an array, you must use ARRAY, followed by the array's name. Following the arrayname on the line is a number enclosed in square brackets, representing the dimensional size. Up to five sets of brackets may be used. One set of brackets represents a single-dimensional array; two sets represent a two-dimensional array; three sets represent a three- dimensional array. The size of the array can also be specified using a variable. Once you've declared the array, you can set the elements of the array on the same line by following the dimension size(s) with an equals sign (=) and then a list of the elements, separated by commas and surrounded by curly braces { } (See Format 1). When using this type of initialization for arrays, the elements in the list must be numeric values; they cannot be variables or expressions. For multi-dimensional arrays, data is stored by switching the last dimension first, and then continuing up to the first dimension. (See Array Declaration Examples.) If you don't wish to set the array initially, but would rather set it later in your program, you may assign values to the array elements by using Format 2. When assigning values to array elements in this fashion, the elements may be assigned with variables along with numeric values. Note that when you are setting the values of an array, the elements are numbered from 0 to (n-1), NOT from 1 to n. You can declare an array even if it has already been declared once. You can change the size of each dimension and even the number of dimensions; however, by doing this, you will lose all the data that you previously stored in the array. Array Declaration Examples To define a one-dimensional array of five values, either of the following formats will create the same array: int data [0] ARRAY data [5] = {0, 1, 2, 3, 4} int data [0] ARRAY data [5] data [0] = 0 data [1] = 1 data [2] = 2 data [3] = 3 data [4] = 4 To define a two-dimensional array of three rows and two columns, both of the following formats will create the same array: int data [0] ARRAY data [3][2] = {0, 1, 2, 3, 4, 5} int data [0] ARRAY data [3][2] data [0][0] = 0 data [0][1] = 1 data [1][0] = 2 data [1][1] = 3 data [2][0] = 4 data [2][1] = 5 To define a three-dimensional array of three rows, two columns, and two planes, you can use either of the following: int data [0] ARRAY data [3][2][2] = {0, 1, 2, 3,\ 4, 5, 6, 7,\ 8, 9, 10, 11} int data [0] ARRAY data [3][2][2] data [0][0][0] = 0 data [0][0][1] = 1 data [0][1][0] = 2 data [0][1][1] = 3 data [1][0][0] = 4 data [1][0][1] = 5 data [1][1][0] = 6 data [1][1][1] = 7 data [2][0][0] = 8 data [2][0][1] = 9 data [2][1][0] = 10 data [2][1][1] = 11 Declaring SLISTs The SLIST data type XE "data types:slist" is very similar to an array except that it is only a single dimensional list of strings. To declare an SLIST, use the following format: SLIST $$listname[numstrings][maxlength] You can specify the number of strings in the list and the maximum size of every string in that list. If either numstrings or maxlength is set to zero(0), that field is assumed to be of variable size. Unlike an ARRAY declaration, you cannot initialize an SLIST. You must set every item in the SLIST separately. For example: SLIST $$parts[0][0] $$parts[0] = "nut" $$parts[1] = "bolt" $$parts[2] = "screw" The CLEAR XE "CLEAR " command When you declare a variable, that variable remains in variable buffer until you quit the program or use the CLEAR command. The CLEAR command will remove a specified variable from the variable buffer space. If CLEAR is used without any parameters, it will remove all variables from the variable buffer space. For example: CLEAR x, y This line will remove the variables x and y from the variable buffer space. It is a good programming practice to CLEAR all variables you have used at the end of your program. This practice ensures that none of your variables will have any effect on another program which may later be executed. For example, if you type cast the variable num as type integer, and then don't CLEAR it at the end of your program, the next program you run may try to type cast num as a char type, and will receive an error. Format Specifiers XE "Format Specifiers" The format-string controls the interpretation of the input fields and is read from left to right. Characters that fall outside format specifications are expected to match the sequence of characters in the input stream; the matched characters are scanned but not stored. If a character in the input stream conflicts with the format-string, the specifier input terminates. The conflicting character is left in the stream as if it had not been read. When the first format specification is found, the value of the first input field is converted according to the format specification and stored in the location specified by the first argument. The second format specification causes the second input field to be converted and stored in the second argument. This process continues through the end of the format-string. An input field is defined as all characters up to the first white-space character (space, tab, or new line), or up to the first character that cannot be converted according to the format specification, or until the field width, if specified, is reached, whichever comes first. If there are too many arguments for the given format specifications, the extra arguments are ignored. An error is generated if there are not enough arguments for the given format specifications. The format-string can contain one or more of the following: - White-space characters (blank (' '), tab ('\t'), or new line ('\n')). A white-space character causes input to read, but not store, all consecutive white-space in the input up to the next non white-space character. One white-space character in format-string matches any number (including 0) and combination of white-space characters. - Non white-space characters, except for the percent-sign character (%). A non white-space character causes input to read, but not store, a matching non white-space character. If the next character in the input stream does not match, input terminates. - Format specifications, introduced by the percent sign (%). A format specification causes input to read and convert characters into values of a specified type. The value is assigned to an argument in the argument list. Input Format Specifiers XE "Input Format Specifiers" XE "Format Specifiers:Input" The input format specifier is as follows: %[*][width]type Each field of the format specification is a single character or a number signifying a particular format option. * an asterisk following the percent sign suppresses assignment of the next input field, which is interpreted as a field of the specified type. The field is scanned but not stored. width is a positive decimal integer controlling the maximum number of characters to be read from the stream. No more than width characters are converted and stored at the corresponding argument. Width characters may be read if a white-space character (space, tab, or new line) or a character that cannot be converted according to the given format occurs before width is reached. type is a character which appears after the last optional format field. This determines whether the input field is interpreted as a character, a string, or a number. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign (%) is followed by a character that has no meaning as a format-control character, that character and the following characters (up to the next percent sign) are treated as an ordinary sequence of characters - that is, a sequence of characters that must match the input. For example, to specify that a percent sign character is to be input, use %%. The type characters and their meanings are described as follows: d represents a decimal integer input with an integer argument. o represents an octal integer input with an integer argument. x represents a hexadecimal integer input with an integer argument. i represents a decimal, hexadecimal or octal integer input with an integer argument. u represents an unsigned decimal integer input with an integer argument. e and f represent floating-point values consisting of an optional sign (+ or -), a series of one or more decimal digits possibly containing a decimal point, and an optional exponent ("e" or "E") followed by an optionally signed integer value with a float argument type. c represents a character. White-space characters that are ordinarily skipped are read when c is specified; to read the next non-white space character, use %1s. A character argument type is used. s represents a character string. To read strings not delimited by space characters, a set of characters in brackets ([]) can be substituted for the s (string) type character. The corresponding input field is read up to the first character that does not appear in the bracketed character set. If the first character in the set is a caret (^), the effect is reversed: the input field is read up to the first character that does appear in the rest of the character set. Output Format Specifiers XE "Format Specifiers:Output" XE "Output Format Specifiers" The pause, prompt, print, or sprint format specifier is a single character or number representing a particular format option. The format followed by a specifier is as follows: %[flags][width][*precision]type Each parameter is described: Type is a character which appears after the last optional format field. This character tells to the program whether a character, string or number is being used. This type character may be used with the percent sign alone at any time (e.g., %f). Those other fields listed in the format above are optional. A full description of each is described in their section headings. Each is briefly described here: Type characters supported are: d represents an integer type with an output format of a signed decimal integer. u represents an integer type with an output format of an unsigned decimal integer. o represents an integer type with an output format of an unsigned octal integer. x represents an integer type with an output format of an unsigned hexadecimal integer, using the characters 0-9 and a-f. f represents a floating point type with a signed value having the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision. e represents a floating point type with a signed value having the form [-]d.dddd e [sign]ddd, where d is a single decimal digit, dddd is one or more decimal digits, ddd is exactly three decimal digits, and sign is + or -. g represents a floating point type with a signed value printed in "f" or "e" format, whichever is more compact for the given value and precision (see below). The "e" format is used only when the exponent of the value is less than -4 or greater than precision. Trailing zeros are truncated and the decimal point appears only if one or more digits follow it. c represents a character with an output format of a single character. s represents a string with an output format of characters printed up to the first null character ('\0') or until precision is reached. Flags justify the output and printing of signs, blanks, decimal points, octal and hexadecimal prefixes. More than one flag can appear in a format specification. Flag characters supported are: - left justifies the result within the field width (default is right justify). + prefixes the output value with a + or - sign if the output value is of a signed type (default is when sign appears only for negative signed values). (' ') (blank) prefixes the output value with a blank if the output value is signed and positive; the "+" flag overrides the blank flag if both appear, and a positive signed value will be output with a sign (default is no blank). # used with the o or x format, the "#" flag prefixes any non-zero output value with 0, or 0x respectively (default is no prefix). Used with e format, the "#" flag forces the output value to contain a decimal point in all cases (default is decimal point appears only if digits follow it). Used with g format, the "#" flag forces the output value to contain a decimal preventing the truncation of trailing zeros. Ignored when used with c, d, u, or s types (default is decimal point appears only if digits follow it). Trailing zeros are truncated. Width describes the minimum number of characters output. The width (non-negative decimal integer) controls the number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added on the left or the right (depending on whether the "-" flag is specified) until the minimum width is reached. If width is prefixed with a 0, zeros are added until the minimum width is reached (not useful for left-justified numbers). The width specification never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or width is not given, all characters of the value are printed (subject to the precision specification). Precision describes the maximum number of characters printed for all or part of the output field, or minimum number of digits printed for integer values. The precision specification is a non-negative decimal integer preceded by a period (.) which specifies the number of characters to be printed, or the number of decimal places. Unlike the width specification, the precision can cause truncation of the output value, or rounding in the case of a floating point value. The interpretation of the precision value and the default when precision is omitted depends on the type: d/u/o Precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. If precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1. e The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded. Default precision is six; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed. g The precision specifies the maximum number of digits printed. c No effect. The character is printed. s The precision specifies the maximum number of characters to be printed. If a percent sign (%) precedes a character that has no relation to the form field, the character is copied out to output. In other words, a percent sign may be printed as a character by typing %%. Characters are printed until a null character is encountered. Math Functions XE "Math Functions" Following is a list of functions which are offered by the system and may be used in an expression to replace a constant numeric value. abs XE "ABS" (x) Returns the absolute value of a number, x. Argument: x can be any constant value, an assigned variable, or an expression. Example: x = -2 y = abs(x) (y will be equal to 2) Error: none acos XE "ACOS" (x) Returns the arc cosine of x, in the range of 0 to 180 degrees. Argument: The value of x must be between -1 and +1. Example: y = acos(0.862) (y will be equal to 30.4581) Error: If the value of x is outside the allowed domain, the error message 'acos: DOMAIN error' is displayed. asin XE "ASIN" (x) Returns the arc sine of x in the range between -90 and +90 degrees. Argument: The value of x must be between -1 and +1. Example: y = asin(0.65) (y will be equal to 40.5416) Error: If the value of x is outside the allowed domain, the error message 'asin : DOMAIN error' is displayed. atan XE "ATAN" (x) Returns the arc tangent of x in the range between -90 and +90 degrees. Argument: x may be any constant value or an assigned variable. Example: y = atan(17) (y will be equal to 86.6335) Error: none atan2 XE "ATAN2" (y, x) Returns the arc tangent of y/x in a range between -180 and +180 degrees. Arguments: Any two values, with the exception that they are not both equal to zero. Example: y = atan2(2, 3) (y will be equal to 33.6901) Error: If the values of x and y are both 0, the error message 'atan2 : DOMAIN error' is displayed. ceil XE "CEIL" (x) Returns the value of x rounded up to the nearest integer (the integer ceiling). Argument: x can be any value. Example: y = 5.84 x = ceil(y) (x will be equal to 6) Error: none copsize XE "COPSIZE " (type) Returns an integer representing the size of a specified copious entity item. A value of zero is returned for any undefined constant. Argument: type can be any one of the following constants (either upper or lowercase letters may be used): char - character uchar - unsigned character int - integer uint - unsigned integer short - short integer ushort - unsigned short long - long integer ulong - unsigned long float - float double - double tcode - copious entity type code Example: s = copsize (long) (s will be equal to 4) Error: none cos XE "COS" (x) Returns the cosine of the angle x in the range between -1 and +1. Argument: Any angle value, x, in degrees. Example: y = cos(67.3) (y will be equal to 0.385906) Error: none cosh XE "COSH" (x) Returns the hyperbolic cosine of the angle x which will be greater than or equal to one(1). Arguments: Any angle value, x, in degrees. Example: y = cosh(67.3) (y will be equal to 1.7729) Error: none dms XE "DMS" (d, m, s) Given degree, minute, and second values, this function will return a single value in degrees, using the following formula: dms = d + (m/60) + (s/3600). Arguments: Any d, m, or s value Example: y = dms (23, 2, 55) (y will be equal to 23.0653) Error: none exp XE "EXP" (x) Returns the natural exponential function, which is the value e raised to the xth power (ex). Argument: x can be any value. Example: y = exp(3) (y will be equal to 20.0855) Error: When the resultant value overflows, the value is set to the largest possible double precision value. floor XE "FLOOR" (x) Returns the value of x rounded down the nearest integer (the integer floor). Arguments: x can be any value. Example: y = 5.84 x = floor(y) (x will be equal to 5) Error: none fmod XE "FMOD " (x, y) Returns the modulus, x mod y. The modulus is the floating point remainder of an integer division. Arguments: x and y can be any values. Example: x = 55.32 y = fmod (x, 3) (y will be equal to 1.32) Error: none hypot XE "HYPOT" (x, y) Returns the length of the hypotenuse of a right triangle, which is calculated using sqrt(x2 + y2) Arguments: The lengths of the two legs of a right triangle, x and y. Example: a = 3.5 b = 6.7 h = hypot(a, b) (h will be equal to 7.5591) Error: none log XE "LOG" (x) Returns the natural logarithm of x. Argument: Any number x which is greater than or equal to zero. Example: y = log(4.9) (y will be equal to 1.58924) Error: If x is less than zero, the error message 'log : DOMAIN error' is displayed. log10 XE "LOG10" (x) Returns the base 10 logarithm of x. Argument: Any number x which is greater than or equal to zero. Example: y = log10(3) (y will be equal to 0.477121) Error: If x is less than zero, the error message 'log10 : DOMAIN error' is displayed. pow XE "POW " (a, b) Returns the value of a raised to the power of b (ab). Arguments: a and b can be any values. Example: x = pow (3, 2.5) (x will be equal to 15.5885) Error: none sin XE "SIN" (x) Returns the sine of the angle x in a range between -1 and +1. Arguments: Any angle value x, in degrees. Example: y = sin(16) (y will be equal to 0.275637) Error: none sinh XE "SINH" (x) Returns the hyperbolic sine of the angle x which will be greater than or equal to zero (0). Arguments: Any angle value x, in degrees. Example: y = sinh(34) (y will be equal to 0.628857) Error: none sizeof XE "SIZEOF" (xxx) Determines the size of an array (number of elements) or whether a variable has been defined. Argument: xxx is the name of a variable or array. Returns: An integer representing the size of the item specified, where: 0 = undefined 1 = defined single variable >1 = defined array of n elements Example: n = sizeof (foobar) Error: none sqrt XE "SQRT" (x) Returns the square root of x. Argument: Any number x which is greater than or equal to zero. Example: y = sqrt(18.67) (y will be equal to 4.32088) Error: If sqrt( ) is passed a negative value for x, then the error message 'sqrt : DOMAIN error' is displayed. tan XE "TAN" (x) Returns the tangent of x. Arguments: Any value x, in degrees. Example: y = tan(42) (y will be equal to 0.900404) Error: none tanh XE "TANH" (x) Returns the hyperbolic tangent of x. Arguments: Any value x, in degrees. Example: y = tanh(42) (y will be equal to 0.624921) Error: none PROGRAM CONTROL STATEMENTS Program control statements XE "program control statements" decide the flow of the program execution by branching, looping or conditionally executing portions of code. The following is a brief discussion of each one of the program control statements. For more detailed information, including formats and restrictions, refer to the Reference section. The REM statement The REM XE "REM " XE "program control statements:REM" statement can be used to insert comments into your code. This keyword, as well as any following text, is ignored by the system when the program is executed. You therefore could also cause certain commands to be ignored just by placing REM in front of them. Example: REM This is just a comment REM PROMPT "This command will not be executed until the REM is removed" The IF statement The IF XE "IF " statement is used to conditionally execu XE "program control statements:IF" te a portion of code. The IF has the format: IF (expr) statement First, the expression (expr) is evaluated. If it is true (nonzero), then the following statement is executed and program flow continues as normal. If the expression was evaluated as false (zero), then the statement following the IF statement is skipped and program flow continues with the next statement. Example: y = 5 IF ( x > 10 ) y = 0 PAUSE "The value of y is %d",y In this example, the expression (x > 10) is first evaluated. If it true (x is greater than 10), then execution continues with the next statement which sets y equal to zero(0). If it is not true (x is less than or equal to 10), then the statement, y=0, is skipped and program flow continues with the following statement, in this case a PAUSE statement (see the Reference section for details on the PAUSE command). Branching and Looping with Labels A label XE " labels" is used to mark a specific location within the program. This location can th XE "program control statements:GOTO" XE "program control statements:ON GOTO" en be referenced by a GOTO XE "GOTO " or ON GOTO XE "ON GOTO" statement. When placing a label, you must precede the label with a colon. For example: :menu1 Normally, CADL processes each statement from the beginning of a program to the end. The GOTO statement allows execution to branch to a location in the program that has been labeled. The format for a GOTO statement is: GOTO label This causes the program to branch to the statement immediately following the specified label. When specifying the label in the GOTO statement, you don't need to include the semicolon. By using both the IF and GOTO statements you create program loops. Example: i = 1 :loop PAUSE "The value of i is %d",i i = i + 1 IF ( i <= 5 ) GOTO loop In this example, the PAUSE command will be executed five times. The ON GOTO statement provides you with an easy way to branch to multiple labels based on a computed value. The format for the ON GOTO statement is as follows: ON value GOTO [label1, label2, ...] If value is computed to be a negative number or zero, execution will GOTO label1. Computed values of 1, 2, 3, etc. causes execution to GOTO the second, third, fourth, etc. labels, respectively. If there is a positive value for which there is no respective label, execution goes to the last label in the list. This statement is really a replacement for a series of IF...GOTO statements. The following two sections of code perform the same function: IF (x <= 0) GOTO lab1 IF (x == 1) GOTO lab2 IF (x == 2) GOTO lab3 IF (x >= 3) GOTO lab4 ON x GOTO lab1, lab2, lab3, lab4 Program Branching The GOTO and ON GOTO statements are for branching within the current CADL program. CHAIN XE "CHAIN " and DOSUB XE "DOSUB " are for branching off the normal program flow into other CADL XE "program control statements:CHAIN" XE "program control statements:DOSUB" files. DOSUB transfers control over to a specified CADL file. When the end of that file is reached or an EXIT statement (see below) is processed, control then returns back to the original file at the statement immediately following the DOSUB statement. CHAIN transfers control to a specified CADL file, but there is no return to the original file as in the DOSUB statement. Exiting a CADL program Normally a CADL program is done when it reaches the end of the file. However, if you want to terminate the program before it reaches the end of the file, there are two statements to do it: ABORT XE "ABORT " and EXIT XE "EXIT" . Although they both will immediately exit the current program, there is a dif XE "program control statements:EXIT" XE "program control statements:ABORT" ference in what they will do afterwards. ABORT will always terminate the current program and return you to the CADKEY or CUTTING EDGE program. EXIT will also terminate the current program, but if that program was executed by a DOSUB statement, EXIT will return control over to the program with the DOSUB statement in it. If the current program was not called by a DOSUB statement, then it will return you to the CADKEY or CUTTING EDGE program. Suspending CADL Execution The WAIT XE "WAIT " command will suspend CADL execution for XE "program control statements:WAIT" a specified number of seconds. Calling External Programs or System Processes To call an external program or access a system process, you must use the EXEC XE "EXEC " command. When executed, this command temporarily suspends the system and executes the command that you specified. When XE "program control statements:EXEC" the program or process is complete, control is returned to the statement immediately following the EXEC statement. Declaring the Security Code String The CODE XE "CODE " command declares the proper security code string to allow file execution to occur. If the CODE string does not match the security code string in SECURE.DAT XE "SECURE.DAT" , then the XE "program control statements:CODE" program will not run. This command is not required unless the default SECURE.DAT file supplied with your CADKEY or CUTTING EDGE installation diskettes has been changed. Compiler-Specific Control Statements The following is a list of program control statements that can only be used in compiled programs (see the Compiler section for details): CONTINUE DO ... WHILE EXITLOOP FOR IF LOCAL SWITCH WHILE _____________________________________________________________________________ Section Two: Commands Table Of Contents Introduction Entity Primitives Entity Control Drawing Entities Deleting Entities Aligning Ordinate Dimensions Entity Selection Entity Attributes Display Control Redrawing Viewports Scaling Clearing a Viewport Selecting Displayed Levels Level Descriptors Viewport Control Normalized Device Coordinate System Viewport Manipulation Viewport Information Inquiries View Manipulation Defining a New View Converting CADL Reference Numbers to CADKEY View Numbers View Descriptors Setting the Display View and the Construction View Retrieving a System View Matrix Coordinate System Transfer User Interaction The Prompt Line Menus Data Input Getting a 3D Coordinate Selecting Attributes Selecting a Plane Selecting Entities Checking the Keyboard Buffer Data File Input and Output Input Commands Output Commands Closing a File Part and Pattern File Access Saving and Loading Part Files Part File Descriptors Saving and Loading Pattern Files Setting System Values Color Graphics Palette Graphics Cursor Location Note Text Attributes Levels Displayed System Parameters Strings and Arrays Copying an Array String Functions Vector Math Functions Copious Entities Copious Types Copious Entities Copious Data Collectives Creating A Collective Adding Entities To A Collective Removing Entities From A Collective Controlling Collective Selection Groups Creating a Group Getting Group Information Dialog Box Manager Basics Dialog Box Coordinate Systems Dialog Box Design Considerations Creating a Dialog Box Child Dialog Boxes Drawing a Dialog Box Erasing A Dialog Box Destroying A Dialog Box Dialog Box Entities Entity Index Entity Position Entity Attributes Buttons Boxes Input Fields Notes Radio Buttons Sliders List Boxes Check Boxes Combo Boxes Tables Icons Titles Deleting Entities Errors In Creation And Modification Freezing A Dialog Box Running the Dialog Box Keyboard Bindings Selecting the Focus Accessing CDE Modules Introduction The purpose of a command is to perform operations much like functions found in the main CADKEY or CUTTING EDGE program. A command consists of a keyword followed by one or more parameters. For example: SET COLOR,3 defines the current color as if you had used the Immediate Mode Command or the COLOR function. Variable assignments may also be used in describing commands as explained under Register Variables. Note that a space is only recognized in a command when it is used to separate the keyword from its parameters. Entity Primitives A data primitive specifies the information for an entity in the database. When executed by the CADL processor, these primitives are converted to entities and vice versa. An example of a data primitive found in a CADL file is: LINE 1.5, 3.0, 0.0, 3.5, 2.0, 0.0, 1, 1, 1, 1, 2, 1 Each value represents an assigned parameter (refer to LINE primitive). Those parameters not specified are defaulted to the values assigned for each specific argument. Variable assignments may also be used in describing primitives as explained in Register Variables. If you wish to use a default parameter for an option, you may use either or both of the following options: If a parameter to be omitted falls between other parameters, omit the specific parameter in the description, but not the commas. If a parameter falls at the end of a primitive description line, use less than the total number of parameters permitted for a given command. For example, in the POINT primitive: POINT 8.5, 3.0, 22., , 7 the color parameter which is supposed to occur between the 22. and 7 parameters, and the group number, subgroup number, and pen number which normally occur after the 7 parameter, are automatically set to default values because they are not specified. Recognition of Entity Primitives MODE XE "MODE " allows the operational mode for CADL file execution to be set, with regard to the recognition of data primitives. Three modes are available: NORMAL - displays primitives on the screen and adds them to the database DRAW - only displays them on the screen (does not add them to the database) SUPPRESS - only adds them to the database (does not display them) The following list specifies all the displayable primitives supported in CADL: ANGDIM (Angular Dimension) ARC CIRCLE CIRDIM (Circular Dimension) CONIC FNOTE, NFNOTE (File Note) GENDIM (Generic Dimension) LABEL, NLABEL LEADER, NLEADER LINDIM (Linear Dimension) LINE, VLINE NOTE, NNOTE ORDDIM (Ordinate Dimension) POINT, VPOINT POLYGON, VPOLYGON POLYLINE SPLINE WITNESS, NWITNESS XHATCH Some primitives now have two versions, one preceded by an 'N' (the new style), and one without (the old style). Both versions will create the same entity but the new versions make use of the system arrays for input of parameters. The old version may not be supported in future versions of CADL. Entity Control Drawing Entities To draw a particular entity, XE "entity control:drawing" use the DRAWENT XE "DRAWENT " command. In order to draw the entity, it must be at least partially within the current viewport bounds, be in the current view and be on a displayed level. To draw all entities at once, use the REDRAW XE "REDRAW " command. Deleting Entities To delete entities, use the DELENT XE "DELENT " co XE "entity control:deleting" mmand. With this command you can delete the last entity found by one of the get entity commands (i.e., GETENT, GETNEXT, etc.), delete a specific entity by its ID number, or else delete all entities currently in the selection list. Aligning Ordinate Dimensions ORDALIGN XE "ORDALIGN " allows you to align the specified ordinate dimension entity. An ordinate dimension is a collective en XE "entity control:ordinate alignment" tity and therefore, the ID of only one of its many ordinates need be passed. The system will automatically align the dimension. Entity Selection To select an entity by its ID number, use GETENTID XE "GETENTID" . To select an entity at a particular X, Y view location, use GETENTXY XE "GETENTXY" . To select all entities within the current window boundaries, use the GETALL XE "GETALL " command. If the selection process is successful, a selection list will be created, containing all the entities selected. To process through the list, you must use the GETNEXT XE "GETNEXT" command. GETNEXT will retrieve the data for each entity selected one at a time from the selection list. If you need to clear the selection list, use CLEARSEL XE "CLEARSEL" . Entity Attributes DEFATTR XE "DEFATTR" , in conjunction with SETATTR XE "SETATTR" , allows for a number of entity attributes to be changed through CADL file execution XE "entity control:attributes" . The purpose of DEFATTR is to define which attributes are to be set, as well as the order in which they are to appear. Once defined, SETATTR is called to actually modify an entity's attributes. The attributes you can set are: color fill color group number level number line type line width pen number subgroup number text rotation angle text aspect ratio text fill mode text font text height text line spacing factor text mirror mode text slant angle text underline mode Display Control Redrawing Viewports When you change the scale of a particular viewport, or change which levels are to be displayed, the effects aren't immediately noticeable. Although the changes were made XE "viewports:redraw entities" internally, the viewport(s) aren't automatically updated. To update them, you need to use the REDRAW XE "REDRAW " command. REDRAW allows you to redraw a specific viewport or all of them at once. Scaling The AUTO XE "AUTO " command will scale the current part to fit totally inside the selected viewport(s). To zoom-out, by dividin XE "scaling:automatic" g t XE "scaling:double" XE "scaling:half" XE "scaling:scale to window" XE "scaling:setting specific scale" he current part scale factor by two, use the HALF XE "HALF " command. XE "viewports:automatic part scaling" XE "viewports:double scale" XE "viewports:half scale" XE "viewports:set part scale" XE "viewports:zoom in on a window" XE "viewports:zoom-in" XE "viewports:zoom-out" To double the current scale value of a viewport, or effectively zoom-in, use DBLSCL XE "DBLSCL" . To zoom-in on a specific area within the viewport, you can use the WINDOW XE "WINDOW " command. You can also set the exact scale factor by using the SCALE XE "SCALE " command. All these scaling commands allow you to scale either the primary viewport, a specified viewport, or all the viewports. Clearing a Viewport The CLS XE "CLS " command will clear a specified view XE "viewports:clear" port, the primary viewport, or all of them. This clears only the graphics that are displayed; it doesn't affect the entity data in any way. Selecting Displayed Levels The LEVELS XE "LEVELS " command allows you to turn a level on or off. When a level is on, it will be display in the viewport(s). When a level is off, any entities that are on that level will not be displayed. You can select a specific level to turn on or off, or you select a range of levels. Level Descriptors To set or retrieve the descriptor of an existing level, use the sys_put_name xe "sys_put_name" and sys_get_name xe "sys_get_name" commands, respectively. Viewport Control Normalized Device Coordinate System The Normalized Device Coordinate System XE "Normalized Device Coordinates" XE "NDC" (NDC) is the system used to place and locate viewports in graphics area. The graphics area in this system is considered to be one unit in both the vertical and horizontal direction. This means that any horizontal or vertical coordinate will be between zero (0.0) and one (1.0). Viewport Manipulation To add a viewport to the graphics area, use the sys_addvp xe "sys_addvp" command. The new viewport to be added cannot overlap any other XE "viewports:adding" existing viewports or else an error will be returned and the viewport will not be created. The total number of viewports cannot exceed the limit set in the configuration program. The delete a viewport, use the sys_delvp xe "sys_delvp" XE "viewports:removing" command. It is possible to delete all of the viewports from the graphics area, which could be useful when you are trying to create a custom configuration of viewports. To set the graphics area to one of eight standard viewport configurations, use sys_autovp XE "sys_autovp" . When selecting which of the configurations you wish to set to, you can a XE "viewports:default configurations" lso pick which viewport will be considered the primary viewport. To resize or move a viewport, use sys_movevp XE "sys_movevp" . This command all XE "viewports:resizing" ows you to XE "viewports:moving" select which viewport is to be changed, and the new positions for each corner of the viewport. Viewport Information Inquiries To determine what th XE "viewports:retrieving information" e NDC size of a text box of rows and columns, use the sys_inqtbsize xe "sys_inqtbsize" command. This can be useful when resizing viewports so that they do not overlap a dialog box. To find out the definition coordinates of a particular viewport, XE "viewports:definition coordinates" based on the graphics area, use the sys_inqvpdef xe "sys_inqvpdef" command. To find out the definition coordinates based on the entire screen, use CALL INQ_VP_NDC. XE "INQ_VP_NDC" XE "CALL:INQ_VP_NDC" The sys_inqvpinfo xe "sys_inqvpinfo" command will provide you with the following information: 1. The current viewport mask 2. The primary viewport number 3. The number of available viewports View Manipulation Defining a New View To define a new view, you must use the VIEW XE "VIEW " primitive (even if you want to use one of the predefined views). You supply the primitive with the nine numbers that make up the view matrix and it returns a CADL reference number for that view. Converting CADL Reference Numbers to CADKEY View Numbers The CALL CDLV2SYSV XE "CDLV2SYSV" XE "CALL:CDLV2SYSV" command will convert a CADL reference number to a System view number. View Descriptors To set or retrieve the descriptor of an existing view , use the sys_put_name xe "sys_put_name" and sys_get_name xe "sys_get_name" commands, respectively. Setting the Display View and the Construction View To set the display view to a specific System view number, use the SET VIEW XE "VIEW, SET" XE "SET:VIEW" command. If you wish to set the construction view, use SET CVIEW XE "CVIEW, SET" XE "SET:CVIEW" . Both SET VIEW and SET CVIEW take the System view number as a parameter, not the CADL reference number. Retrieving a System View Matrix The GETVIEW XE "GETVIEW " command will retrieve a specified system view and store its view matrix elements in the system array, @FLTDAT in elements 0 through 8. Coordinate System Transfer There are four CALL commands that allow you to translate the position of a point as you change views. To transfer a point from world to view coordinates, there are two commands you can use. CALL XFWV XE "CALL:XFWV" XE "XFWV" transforms a world coordinate to a view coordinate using the current view matrix. CALL XFMWV XE "CALL:XFMWV" XE "XFMWV " transforms a world coordinate to a view coordinate using a specified view matrix. To transfer a point from view to world coordinates, there are two commands you can use. CALL XFVW XE "CALL:XFVW" XE "XFVW " transforms a view coordinate to world coordinates using the current view matrix. CALL XFMVW XE "CALL:XFMVW" XE "XFMVW " transforms a view coordinate to world coordinates using the specified view matrix. If you wish to translate a point from one view to another, you must use the world coordinate as an intermediate step. For example, if you wanted to translate a point from view 2 to view 4, you would have to translate from view 2 to world coordinates, then from world to view 4 coordinates. User Interaction The Prompt Line Most of the commands in this section include a parameter that allows you to modify the prompt line. However, you can also output a string to the prompt line at any other time. The two commands, PROMPT XE "PROMPT " and PAUSE XE "PAUSE" , will output a specified string to the prompt line. The only difference between the two is that PAUSE will output the string and then wait for the user to hit before giving control back to the program. PROMPT prints out the string and then immediately returns control to the program. Menus The GETMENU XE "GETMENU " command allows you to specify a string to be displayed on the prompt line, up to nine menu options, which menu item, if any, will be considered the default option, and whether or not to modify the history line when the user makes a selection. CLEARHST XE "CLEARHST " will clear the history line from a certain position to the end of the line. If no position is specified, the entire history line will be cleared. Data Input GETFLT XE "GETFLT" , GETINT XE "GETINT" , and GETSTR XE "GETSTR " allow the user to input a float, an integer, or a string, respectively. Each of these input commands allow you to set the string that will be output on the prompt line, set a default value and specify up to nine menu choices. Control is returned to the program when the user either types in a value, selects a menu choice, or else hits ESCAPE or BACKUP. Getting a 3D Coordinate GETPOS XE "GETPOS " displays a text string on the first half of the prompt line along with the position menu, and then waits until a 3D position is indicated using one of the options provided by the position menu. GETCUR XE "GETCUR " allows you a little more control than GETPOS. With GETCUR, you can specify a cursor style from the following list: arrow crosshairs drag box rubberband box rubberband line You can also display a menu in the menu area. Control returns to your program when the user either selects a menu item or a 3D position. Selecting Attributes GETCOLOR XE "GETCOLOR " displays a text string on the prompt line and a window of color icons. You specify whether the number of selectable colors is 16 or 256. It then waits for the user to select one or more colors. To allow the user to select a line type from a window of line type icons, you need to use GETLTYPE XE "GETLTYPE" . To let the user select a line width, use the GETLWIDTH XE "GETLWIDTH " command. Selecting a Plane GETPLANE XE "GETPLANE " allows the user to choose a method for plane selection using plane selection menu. After the user has selected a method and then selected the plane, control is returned to the program. Selecting Entities GETENT XE "GETENT " displays a text string on the prompt line, activates the graphics cursor, and waits until a single entity is selected. To allow the user to select more than one entity, you can use the GETENTM XE "GETENTM " command. GETENTM invokes the general selection mechanism and waits until one or more entities are selected. If the selection process was successful, you will need to use GETNEXT XE "GETNEXT " to retrieve the data on each entity in the list. If you need to clear this selected list of entities, use the CLEARSEL XE "CLEARSEL " command. Checking the Keyboard Buffer Use GETKEY XE "GETKEY " to check the system keyboard buffer. If there is a character in the buffer, this command will also return its character code, including the ESCAPE, BACKUP and CR () keys. Data File Input and Output Input Commands READ XE "READ " causes data to be read from an ASCII file and set into specified variables. The data file consists of numeric values separated by commas. For each variable specified, a number is extracted from the data file. INPUT XE "INPUT " reads characters, integers, and floating point numbers from the current standard input device in a variety of ways through the use of a format string. INPUT is a more flexible alternative to the READ command. The format string can contain any number of field specifiers which are used to describe how input data should be read and converted to variable values. For each specifier, a variable name is parsed from the statement and set accordingly. READDEV XE "READDEV " reads the CADL digitizing device for a coordinate position, optionally waiting for a function button to be pressed. The number of dimensions returned and the nature of any additional information returned is device dependent. Output Commands WRITE XE "WRITE " provides a means of writing out variable values to a data file. To open a file, you can select from the four following modes: overwrite file if it already exists, append to the end of a file, create only a new file (no overwrite), and append only to an existing file. PRINT XE "PRINT " allows the user to write characters, integers, and floating point numbers to the current standard output device in a variety of ways through the use of a format string. PRINT is a more flexible alternative to WRITE. The format string can contain any number of field specifiers, which are used to describe how values should be converted and written to the output device. Closing a File The CLOSE XE "CLOSE " command will close either the standard input device (DEVIN), the standard output device (DEVOUT), or a data file. Data files are normally closed only at CADL termination or whenever the EXEC command is processed. This command can be used to close a data file any other time. DEVOUT should be closed if DEVIN is to be used to read what was written to DEVOUT. Part and Pattern File Access Saving and Loading Part Files To load and save part files, use sys_prt_load xe "sys_prt_load" and sys_prt_save XE "sys_prt_save" , respectively. When saving a part, you have the option of locking the file and choosing if you will want to overwrite a file if it has the same name as the part you're currently saving. Part File Descriptors To find out what the descriptor for the currently loaded part is, use the sys_prt_desc_inq xe "sys_prt_desc_inq" command. To set the part descriptor of the currently loaded part, use sys_prt_desc_set xe "sys_prt_desc_set" . Saving and Loading Pattern Files The sys_ptn_load xe "sys_ptn_load" and sys_ptn_save xe "sys_ptn_save" commands load and save pattern files, respectively. When loading a pattern, you have access to all the options that you would have if you were loading a pattern directly from CADKEY or CUTTING EDGE. These options include grouping the pattern, placing the pattern on a particular level, and setting the scale, rotation and view of the pattern. When saving a pattern, you must specify the entities to save in the pattern, either by their individual ID numbers, or using the selection list (see GETENTM or GETALL). You can also choose to overwrite an existing pattern file of the same name if it exists. Setting System Values Color Graphics Palette To set one or more colors in the CADKEY color graphics palette, use the PALETTE XE "PALETTE " command. Each color defined is a combination of red, green, and blue intensities. PRANGE XE "PRANGE " allows a range of colors in the System graphics palette to be set such that a linear blend is chosen between the start and end RGB (red, green, and blue) values specified. Graphics Cursor Location SETCUR XE "SETCUR " sets the display of the current graphics cursor position to the specified view coordinate position. Note Text Attributes SETNOTE XE "SETNOTE " performs the same function as using the DETAIL, SET function of the system. It allows you to set various note text parameters which will be assigned to all subsequently created notes. The attributes you can set are: aspect ratio filled font font line spacing factor rotation angle slant angle text height underlining Levels Displayed LEVELS XE "LEVELS " changes the levels displayed by adding or removing either a single level or a range of levels. System Parameters System parameters can be set through CADL file execution through use of the SET XE "SET " command. The parameters that can be set by this command are as follows: Directory Paths CADL directory note files directory part files directory pattern files directory plot files directory System Masks color mask entity mask level mask level mask line type mask line width mask pen mask selection mask Dimension Parameters arrowhead direction arrowhead style dimension text fill mode dimension text font dimension text height dimension text slant angle leader style line type line width note fill mode note font note rotation angle General System Parameters construction depth construction mode construction plane coordinate entry mode cursor snap alignment and increment cursor snap mode cursor tracking database search and draw order decimal precision display of construction view axes display view axes grid alignment and increment grid mode immediate mode command switch line limit mode standard input device standard output device system color system level system pen number system unit mode verify selection mode view number for specific viewport Strings and Arrays Copying an Array CALL MEMCPY XE "CALL:MEMCPY" XE "MEMCPY " will copy one or more elements from a one dimensional array, at a specified source index, to a one dimensional destination array (starting at a specified destination index). String Functions To concatenate two strings, you need to use the CALL function, CALL STRCAT XE "CALL:STRCAT" XE "STRCAT " . This function takes in two strings, s1 and s2, and concatenates s2 onto the end of s1. For example: $s1 = "Hello" $s2 = " world." CALL STRCAT $s1, $s2 After this is executed, $s1 will contain the following string: "Hello world." (including a null terminator) To compare two strings, there are two CALL functions you can use. To make a case-sensitive comparison of two strings, use CALL STRCMP XE "CALL:STRCMP" XE "STRCMP" . To compare two strings without regard to letter case, use CALL STRCMPI XE "CALL:STRCMPI" XE "STRCMPI" . Both functions will tell you if the strings match or else which string is of greater value at the first non matching character. To copy one string to another, you need to use the CALL STRCPY XE "CALL:STRCPY" XE "STRCPY " function. (If you only wish to copy a particular section of a string, use the CALL MEMCPY XE "CALL:MEMCPY" XE "MEMCPY " function). The CALL STRLEN XE "CALL:STRLEN " XE "STRLEN " function will return the length of a string, not including the null terminator. To convert a string to a floating point value, you need to CALL STRFLT XE "CALL:STRFLT" XE "STRFLT" . To convert a string to an integer value, use the CALL STRINT XE "CALL:STRINT" XE "STRINT " function. SPRINT XE "SPRINT " allows you to write characters, integers, and floating point numbers into a string variable through the use of a format string. Vector Math Functions The calculate the cross product of two vectors, use CALL CROSS XE " CALL:CROSS" XE "CROSS" . The dot product of two vectors is calculated using the CALL DOTPROD XE "CALL:DOTPROD" XE "DOTPROD " function. To determine an arc tangent that works in all four quadrants and outputs a value in the range of 0.0 to 2*pi, use CALL ATAN3 XE "CALL:ATAN3" XE "ATAN3" . Copious Entities Copious entities are non-displayable data entities that are accessible only through CADL. These entities are stored in the part file when the part file is saved, so that they are available when the part file is loaded again. There are three groups of commands that manipulate, respectively: 1. The different types or classes of copious entities. 2. The copious entities under each type. 3.The data stored in each copious entity. Copious Types A copious type identifies a group of copious entities by name and type number. Every copious entity created must belong to an existing copious type. The command for defining a copious type is ADDCTYPE XE "ADDCTYPE" XE "copious commands:adding entity types" . There can be a maximum of 256 copious types in a part file at one time. To delete a copious type, use the DELCTYPE XE "DELCTYPE " command. You can only XE "copious commands:delete entity type" delete a copious type when no copious entities exist of that type. If you know the name of the copious type and you need to know its type number, use INQTCODE XE "INQTCODE" . If you know the type number and nee XE "copious commands:retrieve type name" d the name, XE "copious commands:retrieve type code" use INQCTYPE XE "INQCTYPE" . Copious Entities A copious entity can be created in a part file by defining its size and indicating the copious type to which it will belong. To add a copious entity, use ADDCOP XE "ADDCOP" . The size of the copious entity will dep XE "copious commands:adding a copious entity" end on the data that will be stored in the copious entity. The following types of data can be stored in a copious entity: characters integers unsigned shorts long integers double precision floats copious entity type codes entity or copious ID's copious entity sizes Since these data types can have different sizes on different systems, use the COPSIZE XE "COPSIZE" () function to determine the size of a data type. The command to select a copious entity that already exists in the part file is GETCOP XE "GETCOP" . XE "copious commands:selecting a copious entity" DELCOP XE "DELCOP " will del XE "copious commands:delete a copious entity" ete a copious entity that is no longer needed in a part file. Copious Data After a copious entity has been creat XE "copious commands:data output" ed, data can be stored in it. The command to write information to a copious entity is CWRITE XE "CWRITE" . A copious entity must be selected with the GETCOP command before data can be stored in it. To read data from an existing copious entity, use XE "copious commands:data input" the CREAD XE "CREAD " command. As with CWRITE, a copious entity must be selected before its data can be read. Every time a copious entity is selected for reading or writing, a pointer is set to the beginning of its data. The pointer is moved forward with every CREA XE "copious commands:move data pointer" D and CWRITE command according to the data being read or written. However, the pointer can be moved separately using the CMOVE XE "CMOVE " command, either relative to the current pointer position or to an absolute location within the data. Collectives Creating A Collective To XE "collectives:creation" create a collective before any of the entities have been created, use the "SET collect, mode" command. When you set the mode to 1 (on), any entities created afterwards will be put into a collective. When all the entities have been created that you wish to be in the collective, set the mode to 0 (off). This causes all following created entities to be created normally. To create a collective after the entities have already been created, use the command, MAKECOLL XE "MAKECOLL" . There are two ways to specify which entities are to be in the collective. The first way is to specify a list of entity ID's in an array. The second way is to specify a range of entity ID's by supplying MAKECOLL two ID's, the minimum and maximum. Adding Entities To A Collective To add an XE "collectives:adding an entity" entity to a collective or to combine two collectives, use the ADDCOLL XE "ADDCOLL " command. This command takes as parameters two entity ID's. If you wish to add an entity to a collective, one ID must be of an entity already inside the collective, and the other will be the entity you wish to add. If you want to combine two collectives, pick an entity ID from both collectives and the two collectives will be joined. Removing Entities From A Collective To remove a single e XE "collectives:remove an entity" ntity from a collective, use the REMCOLL XE "REMCOLL " command. If you wish to remove all entities from a specific collective XE "collectives:removing all entities" , use BURSTCOLL XE "BURSTCOLL" . All you need to specify is one ID from an entity within the collective. Controlling Collective Selection "SET collsel, mode" controls the manner in which collective entities are put into the selection list when selected using GETENT XE "GETENT" , GETENTM XE "GETENTM" , GETENTXY XE "GETENTXY " and GETALL XE "GETALL" . If mode is set to 0, all the entities in the collective are highlighted and the first entity is put into the selection list. The rest of the entities in the collective cannot be selected through XE "collectives:entity selection" user interaction but only with the NEXTCOLL XE "NEXTCOLL " command. If mode is set to 1, only the selected entity is highlighted and put into the selection list. Groups Creating a Group The GROUP XE "GROUP " primitive sets up a group with a specified number of subgroups. The GROUP primitive also requires that you include a group name, a string up to eight characters in length, and the group reference number. This number is used in other primitive calls to place an entity in a specified group upon creation. Getting Group Information GETGROUP XE "GETGROUP " will return the group name and subgroup flags for a specified group reference number. Dialog Box Manager Basics A dialog box is a collection of entities that are set up by the application and then manipulated by the user. Currently, the dialog box manager supports 11 entity types. They are: buttons, radio buttons, check boxes, list boxes, notes, boxes, input fields, tables, combo boxes, sliders, and icons. This chapter describes the dialog box commands. These commands provide dialog box management for the user interface. For each entity type, there are routines to create an entity, change an entity's attributes, and to gather information from an entity. There are also routines for creating a dialog box, running a dialog box, and destroying a dialog box. Dialog Box Coordinate Systems XE "dialog boxes:coordinate system" Because dialog boxes are implemented as a special case of a text window, the Y-axis runs from top to bottom. Also, all numbers are in "font units." Therefore, an icon defined to reside at 0,0 at the top left of the dialog box. If it is 2 units high by 2 units wide, it is as big as a 2 by 2 stack of letters. This scheme allows all dialog entities to scale correctly regardless of resolution or text fonts available on the target machine. Also, note that the coordinates for anchor points are doubles. Dialog Box Design Considerations XE "dialog boxes:maximum size" Do not define a dialog box bigger than can be shown on an EGA screen. This is approximately 20 lines high by 60 characters wide. Creating a Dialog Box XE "dialog boxes: creating" The dialog box is identified by an ID. This ID is preserved for the life of a dialog box. An application uses this ID as the "dialog box handle." This handle is used for most of the provided routines. The dg_init_dialog xe "dg_init_dialog" command creates a dialog box. and returns a value in the system variable @ERROR. The value in @ERROR is either a dialog box handle, or 0 if it could not satisfy the request. Child Dialog Boxes You can define a dialog box XE "dialog boxes: child dialog boxes" to be a child of another dialog box. A child dialog box displays only if its parent is currently displayed. The child dialog box must be completely inside the parent. The dialog box manager tries to enforce this rule, but it is possible to confuse it in pathological cases. The child dialog box also has a dialog box handle. While working inside a child dialog box, its handle should be used. After initializing a child dialog box, you can use all the dialog box manager calls on it. Just be sure that when you call dg_draw_dialog xe "dg_draw_dialog" for the child, that the parent is still displayed, and remember to call dg_erase_dialog xe "dg_erase_dialog" , so that the parent redraws correctly. When you call dg_run_dialog xe "dg_run_dialog" for the child, only the entities in the child dialog box are active, even if you still see entities in the parent dialog box. Drawing a Dialog Box XE "dialog boxes: drawing" Once you define the dialog box using dg_init_dialog xe "dg_init_dialog" or dg_child_dialog xe "dg_child_dialog" , and also define the entities using the entity routines presented, you will want to paint it on the screen using dg_draw_dialog. XE "dg_draw_dialog" Erasing A Dialog Box XE "dialog boxes: erasing" After you finish user interaction, you can remove the dialog box and restore the viewports behind it. This does not alter the dialog box's internal structures, but merely removes it from the screen. To erase a dialog box use the dg_erase_dialog xe "dg_erase_dialog" command. Make sure to pass the appropriate handle for the system. In order to erase a parent dialog box, all its children should be erased. Destroying A Dialog Box The dg_free_dialog command frees all associated memory, and destroys the dialog box. You can use this after you complete user interaction. XE "dialog boxes: destroying" XE "dg_free_dialog" Dialog Box Entities Entity Index XE "dialog box entities:index" Each entity has a unique index number associated with it. When you create a dialog box, you must specify items to be the maximum number of entities you plan to create. As you are creating entities, you can then specify any index as long as it's in the range between 0 and (items-1). The index can then be used to: o Notify you that an entity has changed. o Tell the dialog box manager which entities' attributes to change. o Request information about an entity. o Modify or delete an entity. Entity Position XE "dialog box entities:position" Each entity has an anchor point, specified in text coordinates. You manipulate attributes with dg_get_flags xe "dg_get_flags" and dg_set_flags XE "dg_set_flags" . These commands return and set the attributes for the specified entity, respectively. You can also specify attributes bits when you create an entity. Buttons XE "dialog box entities: buttons" The dg_add_button xe "dg_add_button" command creates a button. The button has a space before and after the text, which is centered in the button. Specify the value of nc, so that dialog boxes that translate into foreign languages still line up correctly. A button has a flag value DG_RET_ON_SEL(0x0001) specified by default. Buttons take up an extra cell in each direction around them, for the effect. Extracting Button Information There is no information to extract. The dialog box manager tells you that a button has been pressed. Boxes XE "dialog box entities:boxes" A box is an entity that shows group associations. You create a box with the dg_add_box xe "dg_add_box" command. There is no information to extract from a box. Input Fields XE "dialog box entities:input fields" There are three types of input fields: STRINGS, DOUBLES, and INTS. The calculator processes all input for double fields, so the user can type "3 + 4.57 + @depth" into a double field, and the computed value is placed in the field. To input a value use the dg_add_text_double xe "dg_add_text_double" , dg_add_text_int xe "dg_add_text_int " and dg_add_text_string XE "dg_add_text_string" commands. Extracting Input Field Information The dg_get_text_double xe "dg_get_text_double" , dg_get_text_string XE "dg_get_text_string" , and dg_get_text_int XE "dg_get_text_int" commands return the current value of an input field. Modifying Input Fields You can modify the contents of an input field. The dg_set_text_double xe "dg_set_text_double" , dg_set_text_string XE "dg_set_text_string" , and dg_set_text_int xe "dg_set_text_int" commands give a new value to the field. To change the type of the field, delete it and recreate it. Notes A note is a string of text in the dialog box. If you set the flag value to DG_RET_ON_SEL (0x0001) for a note, it acts like a button, but without the highlighting effect. Use this for emulating a hypertext XE "hypertext, emulating" or Rich Text Format (RTF) XE "Rich Text Format (RTF), emulating" application. Radio Buttons XE "dialog box entities:radio buttons" Radio buttons allow the user to choose one option from a multiple option selection. The application specifies the strings for each choice, and which one is currently chosen. The user changes the selection by clicking on either the box or the associated text. If the text value passed to dg_add_radio is omitted, you can add the entries, one at a time, using dg_set_radio_text XE "dg_set_radio_text" . xe "dg_add_radio" Extracting Radio Button Information Use the dg_get_radio xe "dg_get_radio" command to extract information from a radio button. This command returns the currently selected radio button in the set. Modifying Radio Button Information You change the active element with the dg_set_radio xe "dg_set_radio" command. You set or change the text string for a field with dg_set_radio_text xe "dg_set_radio_text" . To change the number of buttons, delete the entity and add it again. Sliders XE "dialog box entities:sliders" XE "dialog box entities:scroll bars" Slider entities, more commonly known as scroll bars, have a draggable slider bar in the middle of the entity, and icons on either end. Pressing either icon moves the slider one segment in that direction. Pressing the area between an icon and the slider box causes the entity to "page" that number of segments. Moving the slider bar, by holding down the mouse button, causes the slider to take up the new position specified. You create a slider entity with the dg_add_slider xe "dg_add_slider" command. Extracting Slider Information You extract information from a slider entity with dg_get_slider XE "dg_get_slider" . This command returns the current segment of the slider. Modifying Slider Information You change the active segments and other settings with dg_set_slider. XE "dg_set_slider" By default, the slider returns picks to you only if you specify a flag value of DG_RET_ON_SEL (0x0001) at creation. When you drag the slider bar, the program does not notify you until you release the slider bar. To be notified as the user drags the slider, specify the flag value as DG_TRACK (0x0800) and DG_RET_ON_SEL (0x0001), which generate a press message every time the slider moves one or more pixels. List Boxes XE "dialog box entities:list boxes" List boxes provide the mechanism for selecting a string from a potentially large set of strings. FILES, PART, LST LD is an example of a list box. If the text passed to dg_add_list xe "dg_add_list" omitted, the strings can be added later using dg_set_list_text XE "dg_set_list_text" . Extracting List Box Information You extract list box information with dg_get_list XE "dg_get_list" . This command returns the index of the string chosen by the user. To retrieve the actual text string of a selection, use the dg_get_list_text xe "dg_get_list_text" command Modifying List Box Information To change the selected item, use dg_set_list XE "dg_set_list" . To set or change a list item, use dg_set_list_text XE "dg_set_list_text" . If list item you select is greater than the number of items in the list, the list expands to the new amount. To delete an item from the list, use dg_del_list_text XE "dg_del_list_text" . Check Boxes A check box provides a simple toggle. To add a check box use the dg_add_check command. Extracting Check Box Information You extract information from a check box with dg_get_check XE "dg_get_check" . This command returns the status of the specified check box. Modifying Check Box Information To change the state of a check box, use dg_set_check XE "dg_set_check" . Combo Boxes XE "dialog box entities:combo boxes" A combo box is a list box with an attached input field. The user selects an item from the list box or enters a string into the input field. If the Must Exist flag is true, the user must select from the list. If the input field is used, the typed string will force itself to match one of the list items. If the text is omitted, use dg_set_combo_list_text xe "dg_set_combo_list_text" to specify the text strings later. To add a combo box use the dg_add_combo xe "dg_add_combo" command. Extracting Combo Box Information You extract information from a combo box with dg_get_combo_string xe "dg_get_combo_string" or dg_get_combo_list_active XE "dg_get_combo_list_active" . The dg_get_combo_string command returns a string value of the specified combo box in the @STRDAT system array while dg_get_combo_list_active returns the list index of the active element of the specified combo box. Modifying Combo Box Information To set or change a list item in a combo box, use dg_set_combo_list_text XE "dg_set_combo_list_text" . If the item's number is greater than the current total number of items, the list expands to the new amount. To delete an item from the combo list, use dg_del_combo_list_text XE "dg_del_combo_list_text" . To change the input string in a combo box, use dg_set_combo_string xe "dg_set_combo_string" and to change the active list element and the input string in a combo box, use dg_set_combo_list_active XE "dg_set_combo_list_active" . Tables XE "dialog box entities:tables" A table is made up of columns. Each column can have its own width, input type, and printf format string. You create the global information for a table first, then specify each column. You can also specify each cell individually. To specify each cell individually, call dg_set_table_doubles XE "dg_set_table_doubles" , dg_set_table_ints xe "dg_set_table_ints" or dg_set_table_strings xe "dg_set_table_strings" for each column to set up columnar data such as printf format string and the colors, and pass a NULL in the vals field. If you use this method to build the table, specify 0 for the 'maxrows' argument to dg_add_table XE "dg_add_table" , and use dg_add_table_row xe "dg_add_table_row" to add each row of the table. To create a table with multiline headers, you use the '&' character as a separator. For example, using slist $$ch[0] = "Initials&Values" slist $$ch[1] = "Time","&Money" will give a you a heading that looks like this: Initial Time Values Money After adding the table, set up its columns. To set up a column of integers use the dg_set_table_ints xe "dg_set_table_ints" command. To set of a column of doubles use dg_set_table_doubles xe "dg_set_table_doubles" and to set of a column of strings use the dg_set_table_strings xe "dg_set_table_strings" command. Modifying Table Rows To add a row to an existing table, use dg_add_table_row XE "dg_add_table_row" . You can add rows only at the end of the table. When you add a row, all string columns are set to the empty string, and integer and double columns are set to zero. To delete a row from an existing table, use dg_del_table_row XE "dg_del_table_row" . To invert a row in an existing table, use dg_invert_table_row XE "dg_invert_table_row" . Use inverting for doing "multiple selection" of rows from within a table. An inverted row swaps each cell's foreground and background colors in that row. Therefore, inverting an inverted row returns it to normal. Locking Columns You can lock a column in two ways. You can either call dg_set_table_ints, doubles, or strings, with dg_locked XE "dg_locked" specified as a flag; or you can call dg_lock_table_col XE "dg_lock_table_col" . To unlock a column, use dg_unlock_table_col. XE "dg_unlock_table_col" A user cannot alter the contents of a locked column. When he picks, he will receive a message back from the dialog box manager that the cell is locked. Locking the entire table, by locking each column, and then using the dg_invert_table_row command after each user pick provides the basic mechanism for multiple selection of items from a table. Setting Cells These commands can be used to set individual cells to new values. To set an integer cell use the dg_set_cell_int xe "dg_set_cell_int" command. To set a double cell use dg_set_cell_double xe "dg_set_cell_double" and to set a string cell use dg_set_cell_string XE "dg_set_cell_string" . Extracting Table Information To inquire about the value of a specific cell, use dg_get_cell_int XE "dg_get_cell_int" , dg_get_cell_double XE "dg_get_cell_double" , and dg_get_cell_string XE "dg_get_cell_string" . To ask which cell was modified last, you will need to have set a flag value of DG_RET_ON_SEL (0x0001) for the table. Then to find out which cell was changed, use the dg_get_table_changed command XE "dg_get_table_changed" . It places into row and col the location of the last changed cell, or places -1 in row and col if nothing changed. Icons XE "dialog box entities:icons" XE "dg_add_icon" Icons are like buttons, but can contain a user-definable picture instead of text. To add an icon, call the dg_add_icon command. Defining Icons Icons must be an integer number of cells high and wide, but within the boundaries the coordinates of the entities that make up the icon are doubles. For example, to define a 3x3 icon, your arguments to the entity commands range from 0.0,0.0 (the upper left corner) to 3.0,3.0 (the bottom right corner). Icons anchor by their upper-left corner, and the y axis positive direction is downward. Following the name field is a list of the entities that make up the icon. Currently, four entities are supported: lines, boxes, bars, and polygons. To define lines: line color x1 y1 x2 y2 Example line green 0.0 0.0 1.0 1.0 This draws a green line from the top left corner to the bottom right corner of the cell. You define boxes and bars exactly like lines, substituting the word bar or box for line. To define polygons you use: pgon color nvert x1 y1 x2 y2 ..... xn yn where nvert is the number of vertices in the polygon and each x and y coordinate is for each of the vertices, in the order they are to be connected. The following example shows the icon definition for a 3x3 character yield sign, with a white background, upside down yellow triangle, with a black border. yield 5 3 3 bar white 0.0 0.0 3.0 3.0 pgon yellow 4 0.5 0.5 2.5 0.5 1.5 2.0 0.5 0.5 line black 0.5 0.5 2.5 0.5 line black 2.5 0.5 1.5 2.0 line black 1.5 2.0 0.5 0.5 Extracting Icon Information There is nothing to extract. The dialog box manager notifies users when the icon is pressed. Titles XE "dialog box entities:titles" XE "dg_add_title" Any entity can have a title. You can add a title to any entity after you create it. The r and c values for this command are relative to the entity not absolute. To add a title use the dg_add_title command. Deleting Entities XE "dialog boxes: deleting entities" XE "dialog box entities:deleting" XE "dg_del_ent" To remove an entity from a dialog box, use dg_del_ent. After you delete an entity, you can reuse its index number for a new entity. Errors In Creation And Modification XE "dialog boxes:errors" XE "dialog box entities:errors" There are many reasons why the dialog box manager returns errors. These include: modifying the wrong index, for example, calling dg_set_cell_string on an entity which isn't a table; indexing out of bounds; or other errors. The dialog box manager uses the system variable @ERROR to pass back error status. The variable sets to zero upon successful completion of any dialog box manager command. @ERROR is cleared after any successful call, so examine it after every dialog box manager call. Freezing A Dialog Box XE "dialog boxes:freezing" XE "dg_freeze_dialog" Occasionally, you can make major changes to the dialog box, for example, resetting values in a file list box when the user changes directories. In these cases, you should stop all dialog box updates until the changes are completed. Call dg_freeze_dialog to freeze a dialog box. To refresh the screen, call dg_draw_dialog xe "dg_draw_dialog" when the updates are finished. This clears the frozen bit from the dialog box. Running the Dialog Box XE "dialog boxes:running" Once you create a dialog box and add all of your entities, you can draw the dialog box and get user input. To draw the dialog box call dg_draw_dialog, then use dg_run_dialog. It xe "dg_run_dialog" returns an integer, which is the index of the button that the user pressed. Also, it could be the index of any other field if you set the flag value to DG_RET_ON_SEL (0x0001) flag for that field and change it. Keyboard Bindings XE "dialog boxes:keyboard bindings" XE "dialog box entities:keyboard bindings" You can assign the command keys F1 through F9 and the keys Alt-A through Alt-Z to entities. Because dg_run_dialog disables immediate mode commands, this should not cause any conflicts. You can bind the keys to button and check box entities in one of two ways. The command, dg_add_binding, xe "dg_add_binding" binds the specified key to the specified button or check box entity. If the user presses the bound key, the entity behaves exactly as if it was pressed by the mouse; it gains the focus. XE "focus" The second way to bind a key to a button or check box is by preceding the selected key in the entity's text with an ampersand '&', e.g., if the button text is "List Files" add a '&' character "List &Files". This will creates a button that is also bound to the Alt-F key. To bind a key to combo boxes, input fields, radio buttons, or list boxes, you must precede the selected key in the title of the entity by an ampersand '&', e.g, "Paper &X Offset" creates a bind between Alt-X and the entity which is titled "Paper X Offset". If you use dg_add_binding, the key that is bound to the entity is not visible. If you use the ampersand method, the selected key is underlined in the text or title field. Do not bind a key to more than one entity. Selecting the Focus XE "dialog boxes:focus" XE "dialog box entities:focus" The dialog box manager always knows which entity has the focus. The entity with the focus has priority for keyboard input and mouse picks. For example, if you have a drop down combo box that overlays other fields when it drops, the manager knows that mouse picks go first to the combo box, and not to the obscured entities, because its attention is focused on that object. The focus shifts with mouse picks, by tab key presses, or directly by programmer control. For example, if you have a check box to select whether or not an operation sends its result to the printer or to a file, the space to enter the file name should be frozen if printer is selected, and open if the file option is picked. When the check box is set to file, the file name box should be unfrozen and the user's next keyboard input should go to that field. The command dg_move_focus xe "dg_move_focus" redirects the dialog box manager's attention to the specified field. You can use this code before a dialog box is run for the first time. For example, when you display a "File/List/Load" box, the File Name field could be defined as having the focus. Accessing CDE Modules A CDE module can be loaded using the CDEOPEN XE "CDEOPEN " command. This command works the same way as the FILES-CDE- LOAD menu sequence. A CDE module can be closed by the CDECLOSE XE "CDECLOSE " command, which is equivalent to the FILES-CDE- CLOSE menu sequence. Functions in CDE modules can be accessed from CADL programs. If a CDE module is already loaded, its functions can be called directly from CADL if the arguments and return types for these functions use data types supported by CADL. For example, functions that use structures cannot be called from CADL. User defined types are acceptable as long as they reduce to the supported types. The following type are supported by CADL for arguments to CDE function calls (the type in parenthesis is the CADL data type corresponding to the CDE type): char (char) char* (string) unsigned char (uchar) char** (slist for argument only, not for return type) int (int) unsigned int (uint) short (short) unsigned short (ushort) long (long) unsigned long (ulong) float (float) double (double) For example, if a CDE module has the following definition for a function: typedef int BOOLEAN; int my_func1 (double x, double y, double z, BOOLEAN flag); it can be called from CADL with the following syntax: my_func1 x, y, z, flag where x, y, and z are floating point values and flag is an integer value. The values must fall within the expected ranges for the function, or a runtime error will occur. ____________________________________________________________________________ Section Three: Reference Table of Contents ABORT ADDCOLL ADDCOP ADDCTYPE ANGDIM ARC ARRAY AUTO BURSTCOLL CALL CDECLOSE CDEOPEN CHAIN CIRCLE CIRDIM CLEAR CLEARHST CLEARSEL CLOSE CLS CMOVE CODE CONIC CREAD CWRITE DBLSCL DEFATTR DELCOP DELCTYPE DELENT dg_add_binding dg_add_box dg_add_button dg_add_check dg_add_combo dg_add_icon dg_add_list dg_add_note dg_add_radio dg_add_slider dg_add_table dg_add_table_row dg_add_text_double dg_add_text_int dg_add_text_string dg_add_title dg_child_dialog dg_del_combo_list_text dg_del_ent dg_del_list_text dg_del_table_row dg_draw_dialog dg_erase_dialog dg_free_dialog dg_freeze_dialog dg_get_box_rc dg_get_cell_double dg_get_cell_int dg_get_cell_string dg_get_check dg_get_colors dg_get_combo_list_active dg_get_combo_string dg_get_flags dg_get_icon_rc dg_get_list dg_get_list_text dg_get_note dg_get_radio dg_get_slider dg_get_table_changed dg_get_table_invert_status dg_get_text_double dg_get_text_int dg_get_text_string dg_init_dialog dg_inq_dialog_wh dg_invert_table_row dg_lock_table_col dg_move_focus dg_radio_align dg_run_dialog dg_set_button_border dg_set_cell_double dg_set_cell_int dg_set_cell_string dg_set_check dg_set_colors dg_set_combo_list_active dg_set_combo_list_text dg_set_combo_string dg_set_flags dg_set_list dg_set_list_text dg_set_note dg_set_radio dg_set_radio_text dg_set_slider dg_set_table_doubles dg_set_table_ints dg_set_table_strings dg_set_text_double dg_set_text_int dg_set_text_string dg_set_title dg_unlock_table_col DOSUB DRAWENT EXEC EXIT FNOTE GENDIM GETALL GETCOLOR GETCOP GETCUR GETENT GETENTID GETENTM GETENTXY GETFLT GETGROUP GETINT GETKEY GETLTYPE GETLWIDH GETMENU GETNEXT GETPLANE GETPOS GETSTR GETVIEW GOTO GROUP HALF IF INPUT INQCTYPE INQTCODE LABEL LEADER LEVELS LINDIM LINE MAKECOLL MODE NEXTCOLL NFNOTE NLABEL NLEADER NNOTE NOTE NWITNESS ON GOTO ORDALIGN ORDDIM PALETTE PAUSE POINT POLYGON POLYLINE PRANGE PRINT PROMPT READ READDEV REDRAW REM REMCOLL SCALE SET SETATTR SETCUR SETNOTE SPLINE SPRINT sys_addvp sys_autovp sys_delvp sys_get_name sys_inqtbsize sys_inqvpdef sys_inqvpinfo sys_movevp sys_prt_desc_inq sys_prt_desc_set sys_prt_load sys_prt_save sys_ptn_load sys_ptn_save sys_put_name VIEW VLINE VPOINT VPOLYGON WAIT WINDOW WITNESS WRITE XHATCH ABORT ABORT XE "program control statements:ABORT " causes an immediate exit from CADL processing, and control is returned to the CADKEY program. Use EXIT to backup one DOSUB level. XE "ABORT" Format: ABORT ADDCOLL XE "collectives:adding an entity" Add an entity to a collective or combine collectives. XE "ADDCOLL" Format: ADDCOLL id1, id2 Input Parameters: id1 (ulong) ID of an entity in the collective being added to. id2 (ulong) ID of the entity to add to the collective. If the entity belongs to another collective, the two collectives will merge. Output Parameters: none System Variables Set: @ERROR(ivar) Error Code: 0 = No error -23 = Entity cannot be made into a collective ADDCOP ADDCOP XE "copious commands:adding a copious entity" XE "ADDCOP " creates a copious entity of a given size. The size of the entity is determined by using the special calculator function copsize(). Initially, all values in the entity (whether characters, doubles, integers, etc.) are zero. Once created, values can be written to or read from the entity using the CWRITE and CREAD commands. There are no restrictions as to the order of the values; however, values should be read in the same order that they were written, otherwise the results are unpredictable. Format: ADDCOP tcode,size Input Parameters: tcode (ival) Entity type code size (ival) Size of entity Output Parameters: none System Variables Set: @ERROR (ivar) Error Code: 0 = No error 1 = Type does not exist 2 = Invalid size @CID (ivar) ID assigned to entity @CTCODE (ivar) Entity type code @CSIZE (ivar) Entity size ADDCTYPE ADDCTYPE XE "copious commands:adding entity types" XE "ADDCTYPE " creates a new copious entity type (classification) identified by a specified name (a character string). Up to 256 types may be defined in any given part file. When a type is created, a "type code" is assigned and returned. The code is needed later for use with CADL commands that access copious entities. The purpose of using codes is one of convenience - it's simply easier to deal with numbers than with strings. Once a code is assigned, it remains so until the copious entity type is deleted. However, the number of copious entity types and the order in which they are added affects the assigned code values. This means that it is very unlikely two parts will have the same code assignments. Consequently, the codes MUST be reestablished at each invocation of CADL. Use INQTCODE to determine the type code of an existing copious entity type. Format: ADDCTYPE name, tcode Input Parameter: name (string) Name of copious entity type to add. Up to 19 characters can be specified. Output Parameter: tcode (ivar) Variable in which to store returned type code. If the type being added already exists, the existing type code is returned. System Variables Set: @ERROR (ivar) Error Code: 0 = No error 1 = Type already exists 2 = Too many types ANGDIM The ANGDIM XE "detail entities:angular dimension" XE "primitives:ANGDIM" XE "ANGDIM" primitive describes an angular dimension entity. All ANGDIM data is represented in local view coordinates. When an ANGDIM primitive is read from a CADL file, an angular dimension entity is created in the database. When an ANGDIM entity is written to a CADL file as an ANGDIM primitive, a VIEW primitive is created first. In addition to a VIEW primitive, some arrays are created. These arrays are used for the ANGDIM definition. When an ANGDIM primitive is read from a CADL file, all the arrays except refln are optional. ANGDIM requires two reference lines. The system calculates the angle between the two reference lines defined in the refln array. If a special value/string is desired in place of the numeric value of the angle then the string should replace the parameter 'str'. Format: ANGDIM x, y, z, str, refln, dimval, [txtinfo], [diminfo1], [diminfo2], [txtatt], [entatt] Input Parameters: x (double) X value of the lower left corner of the dimension text in the view coordinates y (double) Y value of the lower left corner of the dimension text in the view coordinates z (double) Z value of the lower left corner of the dimension text in the view coordinates str (string) A character string. If it is omitted, the dimension value is calculated and displayed. refln(farray) Array of floats that defines the coordinates of the reference lines. Each ANGDIM requires two reference lines. For more detail refer to the System Arrays section. dimval(integer) A flag that defines angle type: 1 = Acute angle (< 180) 0 = Obtuse angle (> 180) txtinfo(iarray) An array of integer values that describes the information for the dimension text. The array is not required if the value of 'str' is NULL. For more detail refer to the System Arrays section. diminfo1(iarray) An array of integer values that is used for the dimension. For more detail refer to the System Arrays section. diminfo2(farray) An array of floats that is used for the dimension. For more detail refer to the System Arrays section. txtatt(farray) An array of floats that describes the attributes of the dimension text. The array is not required if the value of 'str' is NULL. For more detail refer to the System Arrays section. entatt(iarray) An array of integer values that describes the attributes of the entity. For more detail refer to the System Arrays section. Output Parameters: none System Variables Set: none ARC The ARC XE "primitives:ARC " XE "ARC " primitive describes a circular arc defined in a specified plane. All ARC data is represented in local view coordinates. When an ARC primitive is read from a CADL file, an arc entity is created in the database. When an arc entity is written to a CADL file as an ARC primitive, a VIEW primitive is created first (if necessary) which the ARC primitive may reference as its definition plane. Format: ARC xc, yc, zc, rad, ang1, ang2, [vnum], [col], [lev], [ltype], [grpnum], [subgrp], [pen], [lwdt] Input Parameters: xc (double) X value of arc's center in arc's view coordinates yc (double) Y value of arc's center in arc's view coordinates zc (double) Z value of arc's center in arc's view coordinates rad (double) Radius value of the arc in the current system units rad must be >= 0.0005 and <= 10,000 ang1 (double) Starting angle of arc segment ang1 must be >= 0 and <= 360 degrees ang2 (double) Ending angle of arc segment ang2 must be >= 0 and <= 360 degrees vnum (integer) VIEW primitive reference number. The VIEW primitive referenced must precede this primitive or an error message is displayed and the program terminates. 0 = Use current system view in effect col (integer) Color 0-15 = Number in the system color palette lev (integer) Level number 1-256 = System level number 0 = Use current level number ltype (integer) Line type: 1 = Solid 2 = Dashed 3 = Center Line 4 = Phantom Line 0 = Use current system line type grpnum (integer) Group reference number 1-127 = Group number assigned 0 = No group assignment subgrp (integer) Subgroup reference number 1-256 = Subgroup number assigned 0 = No subgroup assignment Note : If you wish to specify a group, you must include both the group and the subgroup number. If either of these arguments is missing or set to zero(0), both of them will be ignored. pen (integer) Pen number 1-8 = Pen number 0 = Use current system pen number in effect lwdt (integer) Line width 1-15 = Odd line width 0 = Use current system line width Output Parameters: none System Variables Set: none ARRAY Array XE "ARRAY" s allow data to be assigned to a single or multi- dimensional storage array within a CADL program. Data may be assigned to an array anywhere within a CADL file, as long as it is assigned before the array is used. The limit to the number of dimensions in an array is five. To declare an array, you must use one of the following formats: Format 1: ARRAY arrayname[n]={n1, n2, n3...} Format 2: ARRAY arrayname[n] .. arrayname[0] = n1 arrayname[1] = n2 .. To declare an array, you must use ARRAY, followed by the array's name. Following the arrayname on the line is a number enclosed in square brackets, representing the dimensional size. Up to five sets of brackets may be used. One set of brackets represents a single-dimensional array; two sets represent a two-dimensional array; three sets represent a three- dimensional array. The size of the array can also be specified using a variable. Once you've declared the array, you can set the elements of the array on the same line by following the dimension size(s) with an equals sign (=) and then a list of the elements, separated by commas and surrounded by curly braces { } (See Format 1). When using this type of initialization for arrays, the elements in the list must be numeric values; they cannot be variables or expressions. For multi-dimensional arrays, data is stored by switching the last dimension first, and then continuing up to the first dimension. (See Array Declaration Examples.) If you don't wish to set the array initially, but would rather set it later in your program, you may assign values to the array elements by using Format 2. When assigning values to array elements in this fashion, the elements may be assigned with variables along with numeric values. Note that when you are setting the values of an array, the elements are numbered from 0 to (n-1), NOT from 1 to n. You can declare an array even if it has already been declared once. You can change the size of each dimension and even the number of dimensions; however, by doing this, you will lose all the data that you previously stored in the array. Examples To define a one-dimensional array of five values, either of the following formats will create the same array: int data [0] ARRAY data [5] = {0, 1, 2, 3, 4} OR int data [0] ARRAY data [5] data [0] = 0 data [1] = 1 data [2] = 2 data [3] = 3 data [4] = 4 To define a two-dimensional array of three rows and two columns, both of the following formats will create the same array: int data [3][2] ARRAY data [3][2] = {0, 1, 2, 3, 4, 5} OR int data [0][0] ARRAY data [3][2] data [0][0] = 0 data [0][1] = 1 data [1][0] = 2 data [1][1] = 3 data [2][0] = 4 data [2][1] = 5 AUTO AUTO XE "viewports:automatic part scaling" XE "scaling:automatic" XE "AUTO " automatically scales the current part to fit in the viewport. This performs the same function as using the system's Immediate Mode command, except that an automatic redraw is not performed. Format: AUTO [vpnum] Input Parameter: vpnum (ival) Viewport number: -1 = All viewports 0 or default = Primary viewport positive number = Designated viewport Output Parameters: none System Variables Set: none BURSTCOLL XE "BURSTCOLL" XE "collectives:removing all entities" Remove all entities from collective. Format: BURSTCOLL id Input Parameter: id (unsigned long) ID of an entity inside the collective System Variables Set: none CALL CALL XE "CALL " provides a mechanism for invoking an internal CADKEY function. A collection of functions is provided that helps reduce the size and complexity of CADL files by performing commonly used operations. Format: CALL func, arg1, ... Input Parameters: func (word) Function name (see following pages) Additional parameters are function-dependent. Output Parameters: Function-dependent System Variables Set: @ERROR (ivar) Error Code: 0 = No error 1 = Error accessing an argument 2 = Called function error CALL Functions Here is a list of functions accessible through the CALL statement. Except for strings, all input and output arguments are floating point values, unless otherwise noted. An actual string (e.g., "This is a string") can be used as an argument if it is passed to the called function, but not returned. For example, the contents of a string variable can now be directly compared to a string: call strcmp, $file, "myfile.dat", retval XE "ATAN3" XE "CALL:ATAN3" CALL atan3, y, x, r Calculate the arc tangent of y/x . This function works correctly in all four quadrants. Input Parameters: y - y value x - x value Output Parameter: r - arc tangent of y/x in the range of 0.0 to 2p. Error: None XE "CDLV2SYSV" XE "CALL:CDLV2SYSV" CALL cdlv2sysv, cv, sv Convert a CADL reference view number to system view number. Input Parameter: cv - CADL reference view number Output Parameter: sv - system view number Error: 1 - unknown CADL reference view number XE "CROSS" XE "CALL:CROSS" CALL cross, rx, ry, rz, x1, y1, z1, x2, y2, z2 Calculate the cross product of two vectors, (x1, y1, z1) and (x2, y2, z2). Input Parameters: x1 - x value of first vector y1 - y value of first vector z1 - z value of first vector x2 - x value of second vector y2 - y value of second vector z2 - z value of second vector Output Parameters: rx - x result ry - y result rz - z result Error: None XE "DOTPROD" XE "CALL:DOTPROD" CALL dotprod, x1, y1, z1, x2, y2, z2, r Calculate the dot product of two vectors, (x1, y1, z1) and (x2, y2, z2). Input Parameters: x1 - x value of first vector y1 - y value of first vector z1 - z value of first vector x2 - x value of second vector y2 - y value of second vector z2 - z value of second vector Output Parameter: r - dot product result Error: None XE "INQ_VP_NDC" XE "CALL:INQ_VP_NDC" CALL inq_vp_ndc, vp, x1, y1, x2, y2 Inquire about the normalized device coordinates (NDC) of a specific viewport based on the entire screen. (Refer to the SYS_INQVPDEF command) Input Parameter: vp - viewport number Output Parameters: x1 - x value of lower left corner of viewport y1 - y value of lower left corner of viewport x2 - x value of upper right corner of viewport y2 - y value of upper right corner of viewport Error: 1 - unknown viewport number XE "MEMCPY" XE "CALL:MEMCPY" CALL memcpy, dst, didx, src, sidx, cnt Copy one or more elements from a one dimensional source array (starting at the source index) to a one dimensional destination array (at the destination index). Input Parameters: didx (ival) - destination array index src (val) - source array sidx (ival) - source array index cnt (ival) - count of elements to copy Output Parameter: dst (val) - destination array Errors: 1 - source or destination not one dimensional array 2 - index or count out of range XE "STRCAT" XE "CALL:STRCAT" CALL strcat, s1, s2 Concatenate string s2 onto the end of string s1. Input Parameters: s1 - first string s2 - second string Output Parameter: s1 - string 2 concatenated onto string 1 Errors: 1 - unable to access/create a string variable 2 - string overflow XE "STRCMP" XE "CALL:STRCMP" CALL strcmp, s1, s2, r Calculate a case sensitive comparison of the two strings, s1 and s2. Input Parameters: s1 - first string s2 - second string Output Parameters: r - integer result of comparison of s1 with s2: Zero means the two strings match. A positive value means s1 is of greater value than s2 at the nonmatching character. A negative value means s2 is greater than s1 at the nonmatching character. Errors: 1 - unable to access a string variable 2 - string overflow XE "STRCMPI" XE "CALL:STRCMPI" CALL strcmpi, s1, s2, r Calculate a case-insensitive comparison of the two strings, s1 and s2. Input Parameters: s1 - first string s2 - second string Output Parameter: r - integer result of comparison of s1 with s2. Zero means strings match. Positive value means s1 is of greater value than s2 at first nonmatching character. Negative value means s2 is greater than s1. Errors: 1 - unable to access a string variable 2 - string overflow XE "STRCPY" XE "CALL:STRCPY" CALL strcpy, s1, s2 Copy string s2 into string s1. Input Parameter: s2 - source string Output Parameter: s1 - destination string (copy of source string) Errors: 1 - unable to access/create a string variable 2 - string overflow XE "STRLEN" XE "CALL:STRLEN" CALL strlen, str, len Determine the length of the string, str. This length does not include the null terminator. Input Parameter: str - string Output Parameter: len - length of string Error: 1 - unable to access a string variable XE "STRFLT" XE "CALL:STRFLT" CALL strflt, str, flt Convert a string to a floating point value. Input Parameter: str - string to convert Output Parameter: flt - converted floating point number Error: None XE "STRINT" XE "CALL:STRINT" CALL strint, str, int Convert a string to an integer value. Input Parameter: str - string to convert Output Parameter: int - converted integer number Error: None XE "XFVW" XE "CALL:XFVW" CALL xfvw, vx, vy, vz, wx, wy, wz Transform the view coordinates (vx, vy, vz) to world coordinates (wx, wy, wz) using the current view matrix Input Parameters: vx - view x value vy - view y value vz - view z value Output Parameters: wx - world x value wy - world y value wz - world z value Error: None XE "XFWV" XE "CALL:XFWV" CALL xfwv, wx, wy, wz, vx, vy, vz Transform the world coordinates (wx, wy, wz) to view coordinates (vx, vy, vz) using the current view matrix Input Parameters: wx - world x value wy - world y value wz - world z value Output Parameters: vx - view x value vy - view y value vz - view z value Error: None XE "XFMVW" XE "CALL:XFMVW" CALL xfmvw, m, vx, vy, vz, wx, wy, wz Transform the view coordinates (vx, vy, vz) to world coordinates (wx, wy, wz) using the specified view matrix Input Parameters: m - transformation matrix vx - view x value vy - view y value vz - view z value Output Parameters: wx - world x value wy - world y value wz - world z value Error: 1 - unable to access view matrix XE "XFMWV" XE "CALL:XFMWV" CALL xfmwv, m, wx, wy, wz, vx, vy, vz Transform the world coordinates (wx, wy, wz) to view coordinates (vx, vy, vz) using the specified view matrix Input Parameters: m - transformation matrix wx - world x value wy - world y value wz - world z value Output Parameters: vx - view x value vy - view y value vz - view z value Error: 1 - unable to access view matrix CDECLOSE CDECLOSE XE "CDECLOSE " allows you to close an already opened CADKEY Dynamic Extension (CDE) module from within the current CADL program. This function is useful when too many CDE modules are opened. The file specification is processed as follows: 1) if the specification does not include a path, the directory of the CDE file is defined in CDEPATH; 2) if a full path is included, the specified directory is used; 3) if the specification includes a relative path, the specified directory is relative to the directory of the initial CDE path; except 4) if the relative path begins with either "." or "..". In this case, the specified directory is relative to the same directory as the CADL program containing the CDECLOSE command. The ".cde" file extension is always forced. When specifying a path, the use of forward slashes (/) or backslashes (\) is dependent upon the operating system under which CADKEY is running. In the event of an error (namely, the specified file does not exist), execution from within the current CADL file is terminated. For more information about CDE refer to the CADKEY Software Development Kit (SDK) Manual. Format: CDECLOSE fname Input Parameter: fname (string) File name of CDE module Example: CDECLOSE "primtv" CDEOPEN CDEOPEN XE "CDEOPEN " allows you to open a CDE module from within the current CADL file. After opening a CDE module, all the functions defined in the definition (.DEF) file can be called as commands in the CADL program. The CDE module remains in memory, until the CADKEY program is terminated or the CDE module is closed. The file specification is processed as follows: 1) if the specification does not include a path, the directory of