CSPro 7.4 has a new function ischecked. This function returns whether a code is part of a check box field's selections. Prior to CSPro 7.4 we would use the pos function. So why use the ischecked function rather than the pos function?

Issue with Pos

Let's look at how the LANGUAGE_SPOKEN variable would be set up. Since a person could speak multiple languages we will use a check box and the language question might look like:

Here English, French, Russian, and Spanish are checked. In previous versions of CSPro we would use the pos function to see if a specific language was checked. For example, if we wanted to know if French was checked we would use:

The error message "French is checked" would be issued. Continuing with our example we could ask if Russian is checked:

In this case pos would return a 1 (true) since Russian is checked and the error message "Russian is checked" would be issued.

If we asked if Hindi is checked:

The pos function would return a 0 (false) and the message "Hindi is not checked" would be issued.

Now let's test if Bengali is checked:

The pos would return a 6 (true) and the message "Bengali is checked" would be issued.

But Bengali is not checked. What happened? The pos("32", LANGUAGE_SPOKEN) searched the string "11212324" found "32" in positions 6-7 returning a 6.

Explanation

The check box codes are placed at uniformly spaced offsets based on the size of the code. For example, if the check box field has a length of 20 and each code has a length of 2, then each selected code is placed in the respective 2-digit offset. That is, positions 1-2 for the 1st code, position 3-4 for the next code, and so on.

The data are stored in the file as shown here:

The pos function does not look by offset, but instead looks for a substring match. Unfortunately, the substring "32" does exist in the data and a false match is found. In previous versions of CSPro we would need to loop through the string being searched by 2 for the language code:

Moving Forward with IsChecked

CSPro 7.4 greatly simplifies this check with the ischecked function. The ischecked function checks for the codes at the appropriate offsets, in this case the function checks positions 1-2, 3-4, 5-6, 7-8, ..., 19-29 for the code "32". To check for Bengali we simply use:

The ischecked function returns a 0 (false) since "32" is not found within one of the uniformly spaced offsets. To do this CSPro requires the codes to be a uniform length. Notice all codes in this example were length 2.

The selcase ("select case") function is used to display a list of cases in an external dictionary, letting an interviewer select a case to load. One function not mentioned in that page's help documentation is the ability for the user to select multiple cases. By using the multiple keyword, the interviewer can select more than one case and then iterate over each of those cases using a for loop.

An undocumented feature allows for all qualified cases to be automatically marked. Using the automark keyword, the selcase dialog is not shown to the interviewer. These two sets of code are the same:

Because selcase allows you to pass a key to match ("" in the example above, which means all case keys), you can use this as a trick to efficiently create value sets if you know what part of the key is. For example, if you have a data file with 50,000 cases, forcase will always loop through all 50,000 cases, whereas providing a key match may limit your loop to substantially fewer cases.

To show a possible use for this trick, we will look at two ways of creating hierarchical value sets for geocodes. Supposing we have three levels of geography—Region, District, and EA—one way to structure a geocode lookup file is as follows:

That is, when defining regions, the district and EA codes are left blank, and when defining districts, the EA code is left blank.

Using a forcase loop to populate the districts based on a selected region, we would loop over the entire data file, filtering on cases where the geocode region matches the selected region, where the geocode district is defined, but where the geocode EA is blank:

Prior to this, to generate the region value set, we would look for cases where the geocode district is blank, and then following this, to generate the EA value set, we would look for cases where the region and district match the selected codes and where the EA is defined. To generate the hierarchical value sets for the three levels of geography would require fairly different loops.

With the selcase automark trick, we can create a single function that can be used to generate the value set for each level of geography:

We call this function from each procedure, specifying the currently selected geocode and the geocode length at each level. In this example, we assume that the region is length 1 and that the other two geocodes are length 2:

Now we have a generalizable function that we can use in our censuses or surveys, a function that will work with any number of levels of geography.

CSPro 7.3 introduces new ways to work with dynamic value sets. Dynamic value sets define the acceptable options for a field and they vary based on responses previously given. Typical value sets, defined in the data dictionary, define a fixed set of responses for a field, but with a dynamic value set, you can customize these responses based on specific conditions.

Prior to CSPro 7.3, you could create dynamic value sets using arrays, but working with these was cumbersome and not intuitive. Now there is a ValueSet object that allow for simpler, and more sophisticated, value set creation. Four scenarios are presented below that show how to use the new ValueSet object.

Easily Create a Dynamic Value Set in a Loop

A typical task is to create a value set based on some attributes entered previously. For example, you might want to present a list of people in a household who are aged 15+ as eligible heads of household. Using the ValueSet object with a for loop with a where condition makes this task trivial:

Combining Value Sets

Suppose you have a question that asks about the way that someone deceased. In the dictionary there is one set of responses that applies to all people and an additional set of responses that applies to females aged 12+. Now you can easily create a dynamic value set, conditionally adding the female aged 12+ responses:

Removing a Value Based on a Previous Selection

Sometimes a questionnaire has a series of questions that asks about preferences, such as, "What is your favorite color?," and then, "What is your second favorite color?" The list of options for the second question can exclude the selected answer to the first question. The ValueSet object makes this task very easy:

Iterate Through Value Set Codes and Labels

Finally, there are two lists that are part of a value set, accessed using the codes and labels attributes. Just as ValueSet is a new object in CSPro 7.3, lists, though around in some form for years, are now fully useable objects. This simplifies iterating through the codes and labels of a value set. For example, if the first two digits of the county code are equal to the state code, a dynamic value set for counties could be created as follows:

There are many ways of formatting the text data you collect in a CSPro application. For example, in the United States it is common to write a telephone number as xxx-xxx-xxxx or (xxx) xxx-xxxx. If only a text field is used, the interviewer could enter either format. However, not knowing the format creates extra work post-data collection, so as the application developer you will want to accept a single format.

This is done using the regexmatch function which was introduced in CSPro 7.2. The function takes two strings, the target and a regular expression and returns whether there is a match or not. In this example, the target string is the telephone number and the regular expression string describes the valid variations of the telephone number.

Regular expressions have their own syntax separate from CSPro logic. To help write your regular expression you can use any regular expression editor that supports the ECMAScript (JavaScript) engine (or flavor).

Writing a Regular Expression

Let us write a regular expression that describes a telephone number in the following format: xxx-xxx-xxxx. We will use the online regular expression editor regex101, make sure to select ECMAScript as the flavor. Start by typing the phone number 123-456-7890 into the test string field. As you write the regular expression, you will notice that the test string is highlighted as it is described by the regular expression.

Step 1

Begin your regular expression by asserting its position at the start of a newline. This will keep your phone number from matching something like otherData123-456-7890.

Step 2

The first character is any number from 0 to 9.

Step 3

The following two characters are also any numbers from 0 to 9. Signal that the pattern will repeat three times.

Step 4

The next character is a hyphen, and will match nothing else, so enter the literal hyphen character.

Step 5

Notice the pattern of the next four characters is the same as the past four. Wrap everything, but the caret in parentheses to create a capture group and signal that the pattern will repeat two times.

Step 6

The last four characters are any numbers from 0 to 9. Signal that the pattern will repeat four times.

Step 7

Finally, end your regular expression by asserting its position at the end of a newline. This will keep your phone number from matching something like 123-456-7890otherData.

Validating a Text Field

With your regular expression in hand, you are ready to validate the telephone number in CSPro. Call regexmatch passing in the telephone number and the regular expression. If 0 is returned then display an error message and re-enter. This allows the interviewer to correct the telephone number. Otherwise, if 1 is returned, do nothing and let the interview continue.

To see a working example, download the regexmatch application.

Before sending interviewers into the field, consider what would happen if CSEntry automatically updated during your survey. If you developed a CSPro application for a previous version or the current version of CSEntry, you may not want the next update. Fortunately, it is simple to disable automatic updates for CSEntry or all apps on Android.

Disable automatic updates for CSEntry

1. Open the Google Play Store .
2. Tap Menu > My apps & games.
3. Select CSEntry.
4. Tap More .
5. Uncheck the box next to "Auto-update."

Disable automatic updates for all apps

1. Open the Google Play Store .
2. Tap Menu > Settings.
3. Tap Auto-update apps.
4. Select Do not auto-update apps.

Update apps manually

1. Open the Google Play Store .
2. Tap Menu > My apps & games.
3. Apps with an update available are labeled "Update."
4. Tap Update All to update all apps. For individual apps, find the specific app you want to update and tap Update.

Tip: In some cases, you may need to restart your device to update an app.