Visual Values for Numeric Fields

Overview

When referencing variables in a data entry application's logic, the value of numeric dictionary items depends on the state of the field on path. If a field has been entered (and has the field color green), its value is returned. However, if:

A numeric dictionary item is on a form.
The data for that form is being entered.
The field is not on path (green) because it has been skipped, or not yet entered.

Under these conditions, referencing this numeric item in logic will return the special value notappl (not applicable). To get the value displayed in the field, even if that field is skipped, you want the "visual value" for the field, which can be accessed using the visualvalue function.

Behavior in Conditional Statements

Because of how CSPro handles special values, the default behavior of not returning visual values can be useful. For example, if a question, MARITAL_STATUS, is asked of people aged 12+, a field might have logic such as this:

PROC AGE_AT_FIRST_MARRIAGE

preproc

// only ask if the person is married, separated, or divorced
ask if MARITAL_STATUS in 2, 4, 5;

In an enumerator enters an age of 15, indicates that the person is married (2), and then goes back to modify the age to 10, the MARITAL_STATUS field is skipped. However, the value for that field was 2 from the previous entry. When executing the logic for AGE_AT_FIRST_MARRIAGE, because MARITAL_STATUS was skipped, the value used in logic is notappl instead of 2 and the ask if control statement works as expected.

If the logic were instead written as:

ask if visualvalue(MARITAL_STATUS) in 2, 4, 5;

The question would be asked because the visual value, the value shown on the screen during data entry, indicates that MARITAL_STATUS is 2 because of the prior entry. If CSPro already returned visual values, logic such as this would have to be rewritten to keep track of the field's entry status. For example:

ask if highlighted(MARITAL_STATUS) and
visualvalue(MARITAL_STATUS) in 2, 4, 5;

Accessing a Field's Value Prior to Entry

There are some circumstances, particularly when modifying cases, when you may want to access a field's value prior to it being entered (or reentered). In these cases, you use the visualvalue function to access the field's value from a previous entry. For example:

PROC INTERVIEW_START_DATE

preproc

// do not overwrite the start date if modifying the case
if visualvalue(INTERVIEW_START_DATE) = notappl then
INTERVIEW_START_DATE = sysdate("YYYYMMDD");
endif;

Always Visual Value

In some applications, particularly operational control ("menu") programs, the CSPro behavior of looking at the status of the field before evaluating the value may not be desirable. In such cases, you can use the Always Visual Value field property to indicate that CSPro should always return the field's visual value. This can also be set in logic. For example:

PROC VALUE

preproc

VALUE = 123;

// displays |NOTAPPL| |123| because VALUE has not been entered at this point
errmsg("|%d| |%d|", VALUE, visualvalue(VALUE));

setproperty(VALUE, "AlwaysVisualValue", "Yes");

// displays |123| |123|
errmsg("|%d| |%d|", VALUE, visualvalue(VALUE));

postproc

// assuming VALUE was not changed, this always displays |123| |123| regardless of
// the AlwaysVisualValue flag because VALUE has been entered at this point
errmsg("|%d| |%d|", VALUE, visualvalue(VALUE));

Visual Values When Writing Cases

When a case is written to a data source in system-controlled mode, the visual values for skipped fields are cleared. When partially saving a case, the visual values are maintained unless using a special argument to savepartial.