core

#### String Functions

The following functions are used with text strings.

CHR

Character Conversion: CHR(<Integer>)

This function returns a string, which consists of the character corresponding to the ASCII decimal value.

ELAPSEDEXECUTIONTIME

Formatted Elapsed Execution Time: ELAPSEDEXECUTIONTIME()

This function returns the time that has elapsed since the measurement routine or mini routine started to execute. The elapsed execution time is the time spent during the DCC portion of the execution; it does not track time for pauses due to attention required by the user. (These include things like execution pauses during comment execution or PC-DMIS messages. Also, errors messages may stop the execution altogether.) The time is returned in "hh:mm:ss" format.

You can record the elapsed execution time at any point in the measurement routine or mini routine by assigning the function to a variable, such as:

ASSIGN/V1=ELAPSEDEXECUTIONTIME()

ELEMENT

Delimited substring location: ELEMENT(<Integer>, <String1>, <String2>)

This function returns the nth substring (element) from string2 using string1 as the delimiting text that divides the elements in string2.

Suppose string2 is "6, 12, 8, 4, 5" and string1 is a comma character ",". The five elements that can be individually retrieved with the element command are "6", "12", "8", "4", and "5".

EQUAL

Case-insensitive string comparison: EQUAL(<String1>, <String2>)

This function compares two strings (ignoring the case) to determine if they are identical. It returns an integer set to 1 if the strings are the same, and 0 if they are not.

FORMAT

Format: FORMAT(<String>,<Integer,double, or point>)

This function takes two expressions and returns a formatted string similar to using the sprintf function inside C++.

- Expression 1 should be a string type that contains one or three format specifiers. If it is a different type, the expression evaluator attempts to coerce it to a string. The string should contain one format specifier if Expression 2 is an integer or double types and three format specifiers (see paragraphs below) if Expression 2 is a point type.

- Expression 2 is expected to be of type integer, double, or point. If a different type is used, the value of the expression is 0.

Format Specifier for FORMAT Function:

The format specifier should have the same syntax as a format specifier used in the sprintf function used in the C++ programming language.

A format specifier consists of optional and required fields and has the following syntax:

%[flags] [width] [.precision] type

Each field of the format specifier is either a single character or a number that signifies a particular format option. The simplest format specifier uses only the percent sign and a type character (for example, %d). If a percent sign is followed by a character that has no meaning as a format field, the character is copied to STDOUT. For example, to print a percent-sign character, use %%.

The optional flag, width, and precision fields, which appear before the type character, control other aspects of the formatting. These are described below:

flags
These optional characters control output justification and the printing of signs, blanks, decimal points, and octal or hexadecimal prefixes. More than one flag can appear in a format specifier.

Here are the possible flags:

–
Meaning: Left align the result within the given field width.
Default: Right align.

+
Meaning: Prefix the output value with a sign (+ or –) if the output value is of a signed type.
Default: Sign appears only for negative signed values (–).

0
Meaning: If the width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and – appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) the 0 is ignored.
Default: No padding.

blank (' ')
Meaning: Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear.
Default: No blank appears.

#
Meaning 1: When used with the o, x, or X type, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.
Default 1: No prefix appears.
Meaning 2: When used with the e, E, or f type, the # flag forces the output value to contain a decimal point in all cases.
Default 2: Decimal point appears only if digits follow it.
Meaning 3: When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros.
Default 3: Decimal point appears only if digits follow it. Trailing zeros are truncated. This is ignored when used with d, i, or u.

width
This second optional field, or argument, controls the minimum number of characters printed. It is a non-negative decimal integer.

- If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values — depending on whether the – flag (for left alignment) is specified — until the minimum width is reached.

- If the width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned 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 if the width is not given, all characters of the value are printed (subject to the precision specification listed below).

precision
This third optional field, or argument, specifies the number of characters to be printed, the number of decimal places, or the number of significant digits. Unlike the width specification, the precision specification can cause either truncation of the output value or rounding of a floating-point value. It is a non-negative decimal integer preceded by a period (.).

type
This required character determines whether the associated argument is an integer, a double, or a point. The list of available types includes:

d - signed decimal integer

i - signed decimal integer

o - unsigned octal integer

u - unsigned decimal integer

x - unsigned hexadecimal integer, using "abcdef"

X - unsigned hexadecimal integer, using "ABCDEF"

e - double in exponential form [-]d.dddd e [sign]ddd

E - same as e, except uses E to introduce the exponent

f - double with the form [-]dddd.dddd

g - formats to either the e or f format depending on which is more compact

G - same as g, except uses E to introduce the exponent

FORMAT Example

This example shows several statements using the FORMAT function inside a measurement routine:

ASSIGN/V1=PROBEDATA("OFFSET") | V1 becomes type point representing the offsets of the current probe. Using the values from the measurement routine used for this example, V1 becomes: <-1.8898, 1.8898, 5.704>
ASSIGN/V3=FORMAT("%.5f,%.5f,%.5f",V1) | V3 becomes type string. The string is formatted using the point object of variable V1. V3 now has: -1.88976, 1.88976, 5.70403
ASSIGN/V4=1.123456789 | V4 becomes type double.
ASSIGN/V5=FORMAT("%.5f ",V4)+FORMAT("%.6f ",V4)+FORMAT("%.7f ",V4)+FORMAT("%.8f",V4) | V5 becomes type string with this value: 1.12346 1.123457 1.1234568 1.12345679
ASSIGN/V6A="The value of V4 is: "+FORMAT("%.8f",V4) | V6A becomes type string with value of: The value of V4 is: 1.12345679
ASSIGN/V6B=FORMAT("The value of V4 is: %.8f",V4) | The expression result remains the same for same as V6A above.
ASSIGN/V7=4444 | V7 becomes type double since all numbers are assumed double unless coerced to an integer.
ASSIGN/V8=FORMAT("%o",INT(V7)) | V8 becomes type string with this value: 10534
ASSIGN/V9=FORMAT("%u",INT(-1)) | V9 becomes type string with this value: 4294967295
ASSIGN/V10=FORMAT("%x",INT(2143)) | V10 becomes type string with this value: 85f
ASSIGN/V11=FORMAT("%X",INT(9567)) | V11 becomes type string with this value: 255F
ASSIGN/V12=FORMAT("%e",0.0005432) | V12 becomes type string with this value: 5.432000e-004
ASSIGN/V13=FORMAT("%E",145.3421) | V13 becomes type string with this value: 1.453421E+002
ASSIGN/V14=FORMAT(",%6d,",INT(1)) | V14 becomes type string with this value: , 1,
ASSIGN/V15=FORMAT(",%-6d,",INT(1)) | V15 becomes type string with this value: ,1 ,

GETSETTING

This function allows you to return various settings of PC-DMIS based on the string parameter inserted.

GETSETTING(<String>)

You can use these string parameters:

1. - "DCC Mode" – Returns a 1 if PC-DMIS is in DCC mode, 0 otherwise.

   - "Manual Mode" – Returns a 1 if PC-DMIS is in Manual mode, 0 otherwise.

   - "Current Alignment" – Returns a string of the current alignment.

   - "Current Workplane" – Returns a string of the current workplane.

   - "Workplane Value" – Returns a numerical value of the current workplane.

   - "PreHit" – Returns the current prehit value as a double precision number.

   - "Retract" – Returns the current retract value as a double precision number.

   - "Check" – Returns the current check value as a double precision number.

   - "Touch Speed" – Returns the current Touch Speed value as a double precision number.

   - "Move Speed" – Returns the current Move Speed value as a double precision number.

   - "Fly Mode" – Returns a 1 if PC-DMIS uses the Fly Mode, 0 otherwise.

   - "Ph9 present" – Returns a 1 if the Ph9/Ph10 is present, 0 otherwise.

   - "Manual CMM" – Returns 1 if the CMM is a manual CMM, 0 otherwise.

   - "LangStr(<Number or ID>)" – Returns a string from PC-DMIS's resources in the current language from a resource ID number or from one of these IDs:
     "Yes", "No", "Oper", "Rept", "Input", "Doc", "YesNo", "Readout", "Internal", "External", "Rect ", "Polr ", "Out", "In", "Least_Sqr", "Min_Sep", "Max_Insc", "Min_CircSc", "Fixed_Rad", "Workplane", "Xaxis", "YAxis", "ZAxis", "Xplus", "Xminus", "YPlus", "YMinus", "ZPlus", "ZMinus", "Point", "Plane", "Line", "Circle", "Sphere", "Cylinder", "Round_Slot", "Square_slot", "Cone", or "None".
     If the value you use is a positive number, PC-DMIS pulls the string from its resource.dll file. If you use a negative number, PC-DMIS pulls the string from its strings.dll file (the strings table).

   - "Extended Sheet Metal" – Returns a 1 if the Show Extended Sheet Metal Options check box is selected inside the Setup Options dialog box, 0 otherwise.

   - "LastHitMove(X)" – Returns the X value of the most recent HIT /BASIC or MOVE/POINT command. PC-DMIS must be in DCC mode for this to work.

   - "LastHitMove(Y)" – Returns the Y value of the most recent HIT/BASIC or MOVE/POINT command. PC-DMIS must be in DCC mode for this parameter to work.

   - "LastHitMove(Z)" – Returns the Z value of the most recent HIT/BASIC or MOVE/POINT command. PC-DMIS must be in DCC mode for this parameter to work.

To determine whether PC-DMIS is in Manual or DCC mode, consider this example of using the GETSETTING function:

ASSIGN/DCCMODEVAR=GETSETTING("DCC Mode") - This gives the variable DCCMODEVAR the value of 1 if PC-DMIS is in DCC Mode, otherwise 0.

ASSIGN/MANMODEVAR=GETSETTING("Manual Mode") - This gives the variable MANMODEVAR the value of 1 if PC-DMIS is in Manual Mode, otherwise 0.

To determine the current workplane, consider this example:

ASSIGN/WORKPLANE_ID=GETSETTING("Current Workplane") - This gives the variable WORKPLANE_ID the string value of the current workplane (ZPLUS, ZMINUS etc.).

ASSIGN/WORKPLANE_VALUE=GETSETTING("Workplane Value") - This gives the variable WORKPLANE_VALUE a numerical value representing the workplane. The workplanes have these values associated with them: ZPLUS = 0, ZMINUS = 3, XPLUS = 1, XMINUS = 4, YPLUS = 2, or YMINUS = 5.

GETTEXT

This function returns the current text from the specified data field: GETTEXT(<String or Integer>,<Integer>,<Pointer>)

This function has three fields.

First Field—Data Field Number or Description

The first field can be either a string description of the data field, indicated by item (A) in the image below or the data field number, indicated in item (C) in the image below.

Item (B) in the image below is not used in this function, but is sometimes used in automation or in report expressions.

To obtain these values:

1. Place PC-DMIS in Command Mode. Right-click anywhere in the Edit window. A shortcut menu appears.

2. From the shortcut menu, select Change Pop-up Display and then Data Type Information.

3. Position the mouse over a data field in the Edit window. The type description, type number, and type index for that data item display.

The type description may be different for different languages. If your measurement routine is executed on a version of PC-DMIS running in a different language, use the type number instead.

Sample Data Type Information Showing (A) Type Description, (B) Type String Identifier, (C) Type Number, and (D) Type Index

Second Field—Type Index

The second field is the type index, indicated as (D) in the above image. This field is usually zero unless you have more instances of the same type of field in the same command, such as multiple DIRECTORY fields shown in the above image. The correct value for this field can be obtained in the same manner as described for the first field.

Third Field—Command Pointer

The third field is a command pointer. It points to the command containing the field from which the text is being obtained. This field can be specified either by using command pointer notation (i.e., {F15}) or by using the GETCOMMAND expression as shown in this example.

ASSIGN/V1=GETTEXT("Best Fit Math Type",0,{F15}) - This command assigns V1 the current value of the best fit math type toggle of feature F15.

ASSIGN/V2=GETCOMMAND("Comment","TOP",1) - V2 is assigned a pointer to the first comment from the top of the measurement routine.

ASSIGN/V3=GETTEXT("Comment Type",1,V2) - V3 is assigned the value of the Comment Type toggle field. If the first comment in the measurement routine is a comment to be displayed to the operator, the value of V3 will be the string "OPER".

See the "Pointer Functions" for information on the GETCOMMAND expression used for setting a pointer to a command.

GETPROGRAMINFO

This function returns the measurement routine's information based on the parameters passed in: GETPROGRAMINFO(<String>, <Optional String>)

This function has at most two strings as parameters. For most items, you only need the first parameter. The string fields are not case sensitive.

First Field—String

The first field is a string input detailing what information to return.

DATE - Returns the current date

TIME - Returns the current time

PARTNAME - Returns the part name as defined in the measurement routine header

PARTPATH - Returns the full pathway to the measurement routine file

REVISION - Returns the revision number as defined in the heading

DRAWING - Like REVISION, this also returns the revision number as defined in the heading

SERIALNUM - Returns the serial number as defined in the header

STATSCOUNT - Returns the current stats count

SEQNUM - Like STATSCOUNT, this string also returns the current stats count number

SHRINK - Returns the global scale factor

NUMMEAS - Returns the number of dimensions executed

NUMOOT - Returns the number of out of tolerance dimensions executed

ELAPSEDTIME - Returns the time that has passed since the beginning of the execution

FILENAME - Returns the measurement routine's file name (.prg)

CADMODELNAME - Returns the full path to the file name of the CAD model that you imported into the measurement routine.

CADMODELFILENAME - Returns the name of only the CAD model (not the path) that you imported into the measurement routine.

REPORTNAME - Returns the current output file name.

TEMP - Returns the temperature for the optional second input string. See "Second Field—Optional String" below.

PRGVERSION - Returns a string value of the PC-DMIS version number of the measurement routine file. You can save a measurement routine file to be compatible with a specific version. For more information, see "Save As" in the "Using Basic File Options" chapter.

PRGSCHEMA - Returns an integer of the PC-DMIS schema number of the measurement routine file. This is an internal value used by PC-DMIS used to indicate the commands and options that are serialized.

PCDMISVERSION - Returns a string value of the actual installed version of the PC-DMIS software.

Second Field—Optional String

The second field is an optional string input. It's only needed if TEMP is used in the in the first input field. The possible strings below come from the Temperature Compensation command. For more information, see "Compensating For Temperature" in the "Setting Your Preferences" chapter.

TEMPP - Returns the temperature for the part sensor

TEMPX - Returns the temperature for the X axis sensor

TEMPY - Returns the temperature for the Y axis sensor

TEMPZ - Returns the temperature for the Z axis sensor

REF_TEMP - Returns the reference temperature

HIGH_THRESHOLD - Returns the high threshold temperature

LOW_THRESHOLD - Returns the low threshold temperature

Example

$$ NO, This code sample displays the number of total dimensions and the number of out-of-tolerance dimensions.

ASSIGN/V1=GETPROGRAMINFO("NUMMEAS")

ASSIGN/V2=GETPROGRAMINFO("NUMOOT")

COMMENT/REPT

"Total Dimensions: "+V1

"Total Out of Tolerance: "+V2

$$ NO,This code sample returns the temperature on the Z sensor axis.

ASSIGN/V3=GETPROGRAMINFO("TEMP", "TEMPZ")

COMMENT/REPT

"Temperature on the Z axis: "+V3

GETTRACEVALUE

Read Trace Value: GETTRACEVALUE(<string>)

This function takes a single string parameter. It returns a value from a TRACEFIELD command in the measurement routine.

<string> represents a case-sensitive string of the trace name whose value you want to return.

If you have multiple trace fields with the same trace name, this function returns the value for most recent trace field above this function. If a trace field doesn't contain a value, this function returns a value of 0.

ASSIGN/V2=GETTRACEVALUE("Operator")

where "Operator" is the trace field name in the measurement routine.

INDEX

Substring Location: INDEX(<String>, <String>)

This function returns the location of the second string within the first string. The first letter of string is 1. A return value of zero indicates that the sub string is not found in the string.

For an example of this function, see the "Sample Code for Read Line" topic in the "Using File Input / Output" chapter.

LASTEXECUTIONTIME

Formatted Last Execution Time: LASTEXECUTIONTIME()

This function returns the last execution time that PC-DMIS recorded and stored in the <name of measurement routine>.MiniRoutines.xml file. The last execution time appears in the Execution dialog box. The time is returned in "hh:mm:ss" format.

LEFT

Left number of characters of a string: LEFT(<String>, <n>)

This function returns a string consisting of a number of left-most characters specified by the second expression (n) from the string specified in the first expression (String).

The first expression (String) is coerced to type string. The second expression (n) is coerced to type integer.

For an example of this function, see the "Sample Code for Read Line" topic in the "Using File Input / Output" chapter.

LEN

Length of string: LEN(<String>)

This function returns the number of characters of the string.

LOWERCASE

Create lowercase string: LOWERCASE(<String>)

This function returns a string that is the lowercase equivalent of the expression string.

MID

Middle n characters of a string: MID(<String>, <Integer>, <Optional Integer>)

This function returns a substring consisting of the characters of the string specified in the first parameter starting at the position specified by the second parameter for a length of n characters as specified by the third parameter. If the third parameter is not supplied, the rest of the string is returned.

For an example of this function, see the "Sample Code for Read Line" topic in the "Using File Input / Output" chapter.

ORD

Ordinal Conversion: ORD(<String>)

This function returns the integer ASCII value of first letter of the string (0-255).

PCDMISAPPLICATIONPATH

Full pathway display: PCDMISAPPLICATIONPPATH()

This function returns the string value containing the full path to the application directory where PC-DMIS is installed. This directory contains the main executable and other necessary program files to run PC-DMIS.

PCDMISUSERHIDDENDATAPATH

Full pathway display: PCDMISUSERHIDDENDATAPATH()

This function returns the string value containing the full path of the hidden user data directory used by PC-DMIS. See "Understanding File Locations" for the files contained in this directory.

PCDMISUSERVISIBLEDATAPATH

Full pathway display: PCDMISUSERHIDDENDATAPATH()

This function returns the string value containing the full path of the visible user data directory used by PC-DMIS. See "Understanding File Locations" for the files contained in this directory.

PCDMISSYSTEMHIDDENDATAPATH

Full pathway display: PCDMISSYSTEMHIDDENDATAPATH()

This function returns the string value containing the full path of the hidden system data directory used by PC-DMIS. See "Understanding File Locations" for the files contained in this directory.

PCDMISSYSTEMVISIBLEDATAPATH

Full pathway display: PCDMISSYSTEMVISIBLEDATAPATH()

This function returns the string value containing the full path of the visible system data directory used by PC-DMIS. See "Understanding File Locations" for the files contained in this directory.

PCDMISSYSTEMREPORTINGPATH

Full pathway display: PCDMISSYSTEMREPORTINGPATH()

This function returns the string value containing the full path to the Reporting directory used by PC-DMIS. This directory contains the report and label templates used by the Report window.

RIGHT

Right n characters of string: RIGHT(<String>, <Integer>)

This function returns a string consisting of the n rightmost characters specified by integer from the string.

SYSTEMDATE

System Date: SYSTEMDATE(<Date Format String>)

This function returns the date-formatted string with the current date details filled in. For example, the command SYSTEMDATE("MM’/’dd’/’yy") returns the string "02/12/14" if the current date is February 12, 2014.

Use the following string elements to create the date string. Elements must be in the same case as shown below (MM instead of mm). Non-date characters (such as spaces) that appear between date format string elements appear in the output string in the same location as the input string. Characters in the input string delimited by single quotes appear in the same location in the output string without the single quotes.

d - Day of the month as digits. No leading zero for single-digit dates.

dd - Day of the month as digits. Leading zero used for single-digit dates.

ddd - Three-letter abbreviation for the day of the week.

dddd - Full name for the current day of the week.

M - Month as digits with no leading zeros for single-digit months.

MM - Month as digits with leading zero for single-digit months.

MMM - Month as three-letter abbreviation.

MMMM - Full name of month.

y - Year as digits with no leading zeros for single-digit years.

yy - Year as digits with leading zero for single-digit years.

yyyy - Year represented by four digits.

SYSTEMTIME

Formatted System Time: SYSTEMTIME(<Time Format String>)

This function returns the time-formatted string with the current time details filled in. For example, the command SYSTEMTIME("hh:mm:ss tt") returns the time in a formatted string, like this "11:29:40 PM".

Use the following string elements to create the time string. Elements must be in the same case as shown below (tt instead of TT). Non-time characters (such as spaces) appearing between time format string elements will appear in the output string in the same location as the input string. Characters in the input string delimited by single quotes will appear in the same location in the output string without the single quotes.

h - Hours with no leading zero for single-digit hours; 12-hour clock

hh - Hours with leading zero for single-digit hours; 12-hour clock

H - Hours with no leading zero for single-digit hours; 24-hour clock

HH - Hours with leading zero for single-digit hours; 24-hour clock

m - Minutes with no leading zero for single-digit minutes

mm - Minutes with leading zero for single-digit minutes

s - Seconds with no leading zero for single-digit seconds

ss - Seconds with leading zero for single-digit seconds

t - One character time marker string, such as A or P

tt - Multi-character time marker string, such as AM or PM

SYSTIME

System Time: SYSTIME()

This function returns a string with the current system time. This function differs from the SYSTEMTIME function described above. It automatically returns the day, date, and time, followed by the year.

Example: "Wed February 12 13:50:21 2014"

The returned string, showing the current system time, is adjusted to local time zone settings.

UPPERCASE

Creates uppercase string: UPPERCASE(<String>)

This function returns a string that is the uppercase equivalent of string.