What are the X_ISSAME and X_HASCHANGED functions?

When building a report the special functions listed below can be used to highlight fields in the report that have or have not changed their values from one report line to the next.  This is done by putting a properly specified version of one of the functions in the Color Condition property of the field being printed.  This means selecting the field under the ‘Columns’ tab, highlighting it, clicking on the ‘Properties’ button and filling out one of the Background Color Conditions, see Remarks below.  The two functions are complementary in that when one is TRUE the other is FALSE.

Functions
x_HasChanged(cExpression1[, cGroupExpression[, cExpression2[, nRecordOffset[, cWorkArea]]]])
x_issame(cExpression1[, cGroupExpression[, cExpression2[, nRecordOffset[, cWorkArea]]]])

Parameters

cExpression 1                     Type:String         Default Value: None. A value must be specified.               
Expression evaluated at the current line of report data.  This is the raw report field name within quote marks.  For example, “ASSET_NO”.  “ASSET_NO” is the field name of the Asset # field.  It can also be a more complex expression.  For example, a common catalog expression would be “CAT_CODE+CAT_NUM”.  When used in one of the Background Color Condition properties an asterisk between quotes, i.e., “*”, will automatically use the current column expression.  For example, all of the following are equivalent if the column expression is “SERIAL_NO”.  All expressions must be enclosed in quote marks.

X_HASCHANGED (“SERIAL_NO”)
X_HASCHANGED (“*”)

cGroupExpression           Type:String         Default Value: “[]”         
Expression string evaluated to determine whether the evaluated values of cExpression1 andcExpression2 are in the same group.  When comparing the two values from cExpression1 andcExpression2 they are considered equal only if they also are in the same group of records. For example, the Log Asset table keeps track of activity in the Asset table.  It may have entries for many assets, and within each asset many entries for each edit. If you are interested in highlighting catalog changes within each asset you could use the following expression:

X_HASCHANGED(“CAT_CODE+CAT_NUM”,”ASSET_NO”)

Make sure that the data is sorted first by asset #, then catalog to make this work properly.  The default behavior is to not use Group Expressions.  All expressions must be enclosed in quote marks.

cExpression2                      Type:String         Default Value: Same as cExpression1     
Expression evaluated at the line above or below the current line.  How far above or below is determined by the nRecordOffset parameter.  The value obtained from this expression is compared to the value obtained from the original data line (cExpression1).  If not specified, cExpression1 is used so that similar columns or expression are compared in the two different data lines.  The values are compared and a TRUE value is returned if they have the same value, FALSE if they are not the same.  All expressions must be enclosed in quote marks.

nRecordOffset                  Type: Numeric                   Default Value:-1
Number of lines above or below the current line being printed.  Internally, this function first obtains thecExpression1 value at the current line of the report, then moves up or down nRecordOfset lines of data in the report, then obtains the cExpression2 value for comparison.

For example, here is a short sample table used in a report.

Asset_No            Cat_code             Cat_num
=========       =======            =======
ASAMPLE            EP                           1000
ASAMPLE            EP                           2000
ASAMPLE            EP                           2000       (Current Line)
ASAMPLE            EP                           3000

The nRecordOffset value tells the function from which line to get the cEXpression2 comparison value.  Negative values get comparison data from ‘before’ the current line, positive values from ‘after’ the current line. Given the following nRecordOffset values here is the return result.

nRecordOffset                  Returned Value                cExpression1 vs cExpression2
=============          ============             =======================
-2                                            TRUE                                  (EP2000 <> EP1000)
-1                                            FALSE                                 (EP2000 = EP2000)
0                                              FALSE                                (EP2000 = EP2000)
+1                                           TRUE                                   (EP2000 <> EP3000)

Put another way, this is the result of the following expression using the above sample:

X_HASCHANGED (“CAT_CODE+CAT_NUM”, “ASSET_NO”, -2)     = TRUE
X_HASCHANGED (“CAT_CODE+CAT_NUM” , “ASSET_NO”,-1)     = FALSE
X_HASCHANGED (“CAT_CODE+CAT_NUM” , “ASSET_NO”,0)      = FALSE
X_HASCHANGED (“CAT_CODE+CAT_NUM” , “ASSET_NO”,+1)    = TRUE

cWorkArea                       Type: String          Default Value: Current Table or cursor
The BarScan work area table or cursor  from which to obtain the comparison values.  If unspecified this defaults to the current table. Some common work area names are: Asset Table=”AS”, Catalog table= “CA”, Location table = “LO”.  The table specified must actually be in use to obtain a valid value.  All expressions must be enclosed in quote marks.

Return Value

Logical. Returns either TRUE or FALSE (.T. or .F.)

Remarks

Here is a sample field property dialog using the X_HASCHANGED function to highlight changed serial numbers.