Functions for Report Expressions

Items preceded with an asterisk symbol (*) are unique to the reporting expression language.

ACOS(<expression>)
This function returns the arc-cosine for the input value. Input and result are in radians.

ANGLEBETWEEN(<expression1>, <expression2>)
This function returns the angle between the two inputs expression1 and expression2, which should be of type vector. Result is in degrees.

ARRAY(<expression1>,<expression2>, & <expressionN>)
This function creates an array out of the input values.

ASIN(<expression>)
This function returns the arc-sine for the input value. Input and result are in radians.

ATAN(<expression>)
This function returns the arc-tangent for the input value. Input and result are in radians.

COMMANDDATA(<expression1>,<expression2>)
This expression calculates or displays information from the feature referenced by the command object from the Report Data event. This takes a single required parameter for expression1. This parameter tells PC-DMIS what feature information to display. A second optional parameter, expression2, is provided for future support but currently isn't used.

You can also pass expressions, like the ISOUTTOL() function, through expression1:

In this example, taken from the TEXTANDCAD_OOT.RTP report template, the expression checks to see if the out-of-tolerance value is greater than zero:

IF "COMMANDDATA("=ISOUTTOL()","")>0" Then Use Template "Reference_ID.lbl"

If so, it uses the Reference_ID.lbl label template. For more information on ISOUTTOL, see the ISOUTTOL expression description below.

CHR(<expression>)
This function returns the ASCII character value for the corresponding input value, which should be of type integer.

*COLOR(<expression1>, <expression2>)
This function makes the text value of expression1 use one of the four colors as currently defined in the color tree. 1 = Marked Color, 2 = Unmarked Color, 3 = Step Mode, and Color 4 = Error Color. See "Changing a String's Text Color".

*GetTolColor(expression1, expression2, expression3)
This function takes three expressions: deviation, plus tolerance, and minus tolerance. It returns the current tolerance color as type COLORREF based on the deviation.

expression1 is the deviation as a double value, expression2 is the plus tolerance as a double value, and expression3 is the minus deviation as a double value.

You can use this returned color with the color properties of objects in reporting, such as ForeColor and BackColor, to dynamically change the color of the object to reflect the current tolerance value.

CONCAT(<expression1>, <expression2>, & <expressionN>)
This function concatenates all of the strings specified in expressions 1 through N together into one string.

COS(<expression>)
This function returns the cosine for the input value. Input and result are in radians.

*COUNT(expression1)
This function returns the number of instances of the data type specified in expression1 for the current command.

CROSS(<expression1>, <expression2>)
This function returns the cross product of expession1 and expression2, both of which should be of type vector.

*DATAFIELD(<expression1>, <expression2>, <expression3>)
You use this function only within the Custom Report Editor. This function returns information from a specific data field within a feature, dimension, or command. This function takes three parameters: expression1 is a string representing the unique id or id of the command, expression2 is a string representing the data type, and expression3 is the typeindex. Normally, the typeindex is 0, but in cases where a dtype occurs more than once, it will be 1 or greater.

PC-DMIS automatically creates and uses this expression when you drag and drop items from the Edit window into your custom report.

DELTA(<expression1>, <expression2>, <expression3>)
This function generates a new point moved along the vector specified in expression2 by the distance specified in expression3 from the point specified in expression1.

DISTANCEFROMEDGE()
This function retrieves the distance of the measured centroid of the command's underlying feature from the closest edge on the CAD.

You can use this function in the Rule Tree Editor to specify different label templates based on the distances returned.

DOT(<expression1>, <expression2>)
This function returns the dot product of expression1 and expression2. The input values should be of type point.

DOUBLE(<expression>)
This function converts the input value from its current type to a double. In the case of a point, the function returns the distance of the point from the origin.

EQUAL(<expression1>, <expression2>)
This function tests whether two arrays are identical and returns 1 if they are identical; otherwise, it returns 0.

*FILENAME()
This function returns the full path and file name of the measurement routine.

*GETCOUNT(expression1)
This function returns a long value of the number of instances that exist for the ENUM_FIELD_TYPES data type, specified in expression1. For example, a location dimension that reports in X,Y,Z, and D would return 4 for the Axis data type.

GETFEATURESSETID(<expression1>)
During execution, if the current command is a dimension, this function checks to see if the reference feature for this dimension is in a feature set. If it finds the reference feature in a set, it returns that set's ID as a string value with a ".lbl" extension appended to the end it. If it does not find a feature set command with the reference feature, it returns the default string value supplied in <expression1>. This default value should be a label file name that includes the .lbl extension.

For example, suppose you have the following Location dimension that references a circle named CIR1:

DIM LOC1= LOCATION OF CIRCLE CIR1 UNITS=IN ,$

GRAPH=OFF TEXT=OFF MULT=10.00 OUTPUT=BOTH

...

END OF DIMENSION LOC1

You can use the GetFeatureSetID function inside a rule to automatically determine the label that PC-DMIS displays for this dimension depending on whether or not CIR1 exists inside of a feature set.

For example, this rule automatically uses the LEGACY_DIMENSION.LBL label if it cannot find a FEAT/SET command that contains CIR1:

USE TEMPLATE "=GetFeatureSetID("LEGACY_DIMENSION.LBL")"

If there is a FEAT/SET command, you can then change the ID for that command to match the desired label name you want to use (or change a label file name to match the ID). PC-DMIS then uses that label instead.

In this code here, notice that the FEAT/SET references CIR1. It also has its usual label identification changed to "REFERENCE_ID" and the GetFeatureSetID function returns "REFERENCE_ID.LBL":

REFERENCE_ID=FEAT/SET,CARTESIAN

THEO/<0,0,0>,<0,0,1>

ACTL/<0,0,0>,<0,0,1>

CONSTR/SET,BASIC,CIR1,,

GETTEMP(<expression1>)
This function returns the specified temperature or threshold value. One of these string values used for expression1 determines what this function returns:

IF(<expression1>, <expression2>, <expression3>)
If expression1 evaluates to a non-zero value, the function returns the value of expression2; otherwise, the function returns the value of expression3.

ISMARKEDFORARM(<expression>)
Use this function in Multiple Arm mode contexts. This function returns 1 if the command is marked for the arm specified in <expression>; otherwise, it returns 0. This function lets you control what is displayed in the report based on the command's executing arm.

=IsMarkedForArm(1)

would return 1 if the current command is marked for arm 1, otherwise it returns 0.

=IsMarkedForArm(2)

would return 1 if the current command is marked for arm 2, otherwise it returns 0.

=IsMarkedForArm(1) AND IsMarkedForArm(2)

would return 1 if the current command is marked for both arms, otherwise it returns 0.

*ISOUTTOL()
This function checks if a command is out of tolerance. This is only used with the COMMANDATA expression as discussed above.

LEN(<expression>)
For a string, this function returns the number of characters in the string. For an array, it returns the number of elements in the array.

*LOADSTR(<expression>)
This function loads the string using the numerical value from the resource files. A negative numerical value causes the string to be loaded from the string's resources. See "Loading Strings from PC-DMIS" for more information.

*NUMMEAS()
This function displays a number value that represents the number of dimensions reported.

*NUMOUTTOL()
This function displays the number of reported out-of-tolerance dimensions.

*PARTNAME()
This function displays the part name (the same as what is shown in the file header).

PAGEDIMCOUNT("ObjectID",Range)
This function takes two parameters. If the first parameter is empty (nothing inside the quote marks), then this function returns the number of dimensions in the current page with a max deviation less than Range*Tol. The second parameter, Range, is a floating number. If the first parameter references a CadReportObject ID or a TextReportObject ID, then this returns the number of in-tolerance dimensions associated with the specified CadReportObject or TextReportObject.

For example, suppose you want to return the number of out of tolerance dimensions with CadReportObject1. You could use the following code to do this:

=TotalPageDimCount("CadReportObject1") - PageDimCount("CadReportObject1",1.0)

You can also calculate the number of dimensions that contain a specific number of axes. To do this, append ":N" to the ID, where N is a number that represents the number of axes.

For example, typing =PageDimCount("CadReportObject1:4",1.0) returns the number of dimensions associated with CadReportObject1 that contains at least four axes and that had the fourth axis within the specified tolerance of 1.0. If you do not specify the number of axes, it returns the number of dimensions associated with CadReportObject1 if all axes were within the specified tolerance of 1.0.

For Custom Reports, you can only use this function with a CADReportObject, because a TextReportObject cannot go on a Custom Report.

*REGSETTING(<expression1>, <expression2>)
This function displays a value of a specific entry. This function takes two parameters: expression1 determines the section, and expression2 determines the entry.

REPORTDIMCOUNT(<"expression1">, <expression2>)
This function acts like the PageDimCount() function except that instead of displaying the number of out of tolerance dimensions for the current page, it displays the total number of out of tolerance dimensions for the entire report. In addition, for <expression1>, you need to use CadReportObject1 or TextReportObject1 as the ID, or leave it empty (with just the quotes).

For Custom Reports, you can only use this function with a CADReportObject, because a TextReportObject cannot go on a Custom Report.

REPORT_LABEL_AXIS(<expression1>,<expression2>, etc.)
This function returns a string delimited by \n that describes each axis that the tolerance command outputs.

*REPORTVALUE(<expression1>)
This function displays the value of another object's property. It takes one parameter, shown as expression1. This should be a string value of the object's unique ID followed by a period and then the property's name. For example: =REPORTVALUE("text1.text")

*REVNUM()
This function displays the revision number (the same as what is shown in the file header).

*RGB(<expression1>, <expression2>, <expression3>, <expression4>)
This function colors the string specified in expression1 to the color specified via the RGB values of expression2, expression3, and expression4. See "Changing a String's Text Color".

*SERNUM()
This function displays the serial number (the same as what is shown in the file header).

*STATCOUNT()
This function returns the statistics count (the same as in the file header).

*TOGGLESTR(<expression1>, <expression2>)
This function pulls the toggle string from the resources base on the resource id value in expression1. The function uses a negative number for cases where the string should come from the strings resources. This function uses the value of expression2 to specify the substring to return. The result is the substring.

*TOGGLESTRING(DATA_TYPE)
If the specified data type for the given command is of type toggle string, this function returns the full toggle string.

*TOGGLEVALUE(DATA_TYPE)
If the specified data type for the given command is of type toggle string, this function returns the index number (or toggle value) of the toggle string.

*TOL(<expression1>, <expression2>, <expression3>, <expression4>)
expression1 is the string to color, expression2 is the test value, expression3 is the maximum in-tolerance value, and expression4 is the minimum in-tolerance value. If the test value is in tolerance (between the values for expression3 and expression4), then the software colors the text black. Otherwise, the software colors the text with the error color (usually red). You can define the error color in the Color Editor dialog box (Edit | Preferences | Edit Window Colors).

This code displays the text "Out of Tolerance" in the error color (by default, this is red):

*TOLF(<expression1>, <expression2>, <expression3>, <expression4>, <expression5>)
This function provides additional formatting capabilities beyond the TOL expression. The first four parameters are the same as listed in the TOL function above. The fifth expression determines the font, size, format, and color for an out-of-tolerance condition. It expects this syntax:

c is an RGB(r,g,b) color formatting where r = red, g = green, and b = blue. Each value can be in the range of 0 to 255.

Each of these items is optional and must be separated with a colon (:) character. For example, to set only the font size, you could have ":14", but to set only the color, you would need ":::RGB(0,0,0)".

This example formats any measured dimension that is out of tolerance with an Arial font, size 12, with a boldface formatting and a red color.

TOLEXT(<expression1>, <expression2>, <expression3>, <expression4>, <expression5>)
This function is similar to the TOL function except you can use ExtendedDTypes.

Where "SEG=1" is the extended portion that PC-DMIS adds to the REPORT_LABEL_NOMINAL expression.

TOTALPAGEDIMCOUNT("ObjectID")
This function contains one parameter. If the function is empty (nothing between the quotation marks), it returns the total number of dimensions in the current page. If you type the ID of a CadReportObject or TextReportObject in the parameter, PC-DMIS returns the total number of dimensions associated with that object.

For example, if you used this expression =TotalPageDimCount("CadReportObject3"), PC-DMIS returns the total number of dimensions associated with CadReportObject3.

You can also calculate the number of dimensions that contain a specific number of axes. To do this, append ":N" to the ID, where N is a number that represents the number of axes.

For example, typing =TotalPageDimCount("CadReportObject1:4") would return the total number of dimensions associated with CadReportObject1 that contained at least four axes.

For Custom Reports, you can only use this function with a CADReportObject, because a TextReportObject cannot go on a Custom Report.

TOTALREPORTDIMCOUNT("ObjectID")
This function is similar to the TotalPageDimCount() function with these important differences: Instead of returning the number of dimensions for the current page, it returns the total number of dimensions for the entire report. This works if there's a CadReportObject or TextReportObject. If you have an object ID as your parameter, it needs to be named CadReportObject1 or TextReportObject1.

For Custom Reports, you can only use this function with a CADReportObject, because a TextReportObject cannot go on a Custom Report.

TRACEFIELD(<expression>)
This function displays the given tracefield's name and value in the report. The value of the expression is a number value that represents the order of the listed tracefields from top to bottom in your measurement routine. So to display the first listed tracefield, the code would read: =TRACEFIELD(1)

USERSTRING(<expression1>,<expression2>)
This function pulls a custom string from a comma separated value (CSV) text file and displays that string in the label. See "Loading Strings from a Text File" for an example of this function.

*VARIABLE(<expression1>,<expression2>)
This function displays the defined variable's value. This function takes one or two parameters. expression1 is the string value that represents the variable's ID. expression2 is an optional ID of another command ID or UID. See "Displaying a Variable's Value" for more information.