The latest iteration of CSPro, version 8.0, has been released! Dive into the newest features and enhancements packed into CSPro 8.0.

What’s new with CSPro 8.0

  • Many specification files are now saved in JSON format, which facilitates working with them in other programming languages or when using other tools.
  • In addition to being able to declare numeric and alphanumeric data types in the dictionary, you can now specify four new data types: Audio, Document, Geometry, and Image.
  • A new framework, the Action Invoker, provides a standard way of running actions from CSPro logic, embedded JavaScript, JavaScript executed on web pages, and in JSON format.
  • A new view, questionnaire view, displays the contents of a case and its components (dictionary, forms, question text) in a read-only mode that facilitates reviewing or printing.
  • The introduction of a new version of logic that enhances the ability to work with string literals and newline characters, and positions the syntax of CSPro logic closer to other languages.
  • A new tool, CSCode, is a text editor with support for tabbed editing of documents. The tool also facilitates running JavaScript, editing and validating JSON, designing and testing HTML dialogs, validating specification files, and more.

To get started with CSPro 8.0, be sure to update CSPro, CEntry Android, and CSWeb to the latest version.


#Release   


When installing CSEntry 7.5+ you may notice the CSEntry folder has moved. The location of the CSEntry folder will depend on whether your installation is a new install or an upgrade of an existing installation. This was necessary to support more stringent security requirements on the Android OS.

New Installations of CSEntry 7.5+

With a new installation of CSEntry 7.5+ (i.e., CSEntry is not installed on the device) the CSEntry folder will be found at /Android/data/gov.census.cspro.csentry/files/csentry.

Upgrading Installations to CSEntry 7.5 – 7.6.1

Upgrading an earlier version of CSEntry to CSEntry 7.5 - 7.6.1 the location of the CSEntry folder will continue to be found at /csentry. For example, an upgrade from CSEntry 7.4 to CSEntry 7.5 will continue to use the CSEntry folder at /csentry. Upgrading to CSEntry 7.6 will again not change the location of the CSEntry folder.

Android 11+

On Android 11+, when upgrading a version of CSEntry which runs applications from /csentry to CSEntry 7.6.2+ it is necessary to complete a new installation. This can be done by uninstalling the current installation of CSEntry and then installing the new version. Note that this is necessary for all versions less than 7.5. For CSEntry 7.5 – 7.6.1 this will be necessary if it is running CSPro applications from the folder at /csentry due to an upgrade installation.

Also, with Android 11+, the only application automatically granted access to manage the contents of /Android/data is the AOSP Files application. You can access the AOSP Files application by going to Settings > Storage > tap on Files. You will be prompted to select the default application. Choose the AOSP Files application.

Caution: Do Not Delete Your Data

A consequence of this change is that uninstalling CSEntry will now remove the CSEntry folder, if it is located at /Android/data/gov.census.cspro.csentry/files/csentry. This will delete your applications and more importantly delete your data!


#Android    #CSEntry   


CSPro 7.4 has introduced a new and improved recode statement that will allow you to get more done in a single recode. To see the differences between the old and new recode you will compare implementations of a typical education edit. Note that the old recode has been deprecated.

Specification

The goal of the two recode implementations will be to verify that students currently attending school are within the allowable age range for their grade. The specfication below defines the valid combination of grades and ages.

alt text

Old Recode Implementation

Using the old recode syntax notice that you will need two recode statements. One for the minimum age and another for the maximum age.

PROC P10_GRADE_NOW_ATTENDING

preproc

    ask if
P09_ATTEND = 1 and P04_AGE >= 3; // Currently attending school

postproc

    numeric
minAgeForGrade, maxAgeForGrade;

   
recode P10_GRADE_NOW_ATTENDING => minAgeForGrade;
                                 
0 => 3;  // Preschool and kindergarten
                                 
1 => 5;
                                 
2 => 6;
                                 
3 => 7;
                                 
4 => 8;
                                 
5 => 9;
                                 
6 => 10;
                                 
7 => 11;
                                 
8 => 12;
                                 
9 => 13;
                               
10 => 14;
                               
11 => 15;
                               
12 => 16;
                               
13 => 16; // University but not graduate school
                               
14 => 18; // Graduate school
                               
15 => 15; // Trade or technical school
   
endrecode;

   
recode P10_GRADE_NOW_ATTENDING => maxAgeForGrade;
                                 
0 => 6;  // Preschool and kindergarten
                                 
1 => 8;
                                 
2 => 9;
                                 
3 => 10;
                                 
4 => 11;
                                 
5 => 12;
                                 
6 => 13;
                                 
7 => 14;
                                 
8 => 15;
                                 
9 => 18;
                               
10 => 20;
                               
11 => 21;
                               
12 => 22;
                               
13 => 95; // University but not graduate school
                               
14 => 95; // Graduate school
                               
15 => 95; // Trade or technical school
   
endrecode;

   
if P04_AGE in minAgeForGrade:maxAgeForGrade then
        errmsg
("P10_GRADE_NOW_ATTENDING(=%d) is valid for age(=%d)", $, P04_AGE);
   
else
        errmsg
("P10_GRADE_NOW_ATTENDING(=%d) NOT valid for age(=%d)", $, P04_AGE);
       
reenter;
   
endif;

Syntax Change Between Old and New Recode

To make use of the new recode statement you will have to write your recodes with a slighly modified syntax. The table below documents these changes.

Operator Old Recode Syntax New Recode Syntax
Assignment => ->
And : ::
Range - :

New Recode Implementation

With this new recode statement you can determine the minimum and maximum ages within a single recode. Making your logic easier to understand and maintain.

PROC P10_GRADE_NOW_ATTENDING

preproc

    ask if
P09_ATTEND = 1 and P04_AGE >= 3; // Currently attending school

postproc

    numeric
minAgeForGrade, maxAgeForGrade;

   
recode P10_GRADE_NOW_ATTENDING -> minAgeForGrade :: maxAgeForGrade;
                                 
0 ->              3 :: 6;  // Preschool and kindergarten
                                 
1 ->              5 :: 8;
                                 
2 ->              6 :: 9;
                                 
3 ->              7 :: 10;
                                 
4 ->              8 :: 11;
                                 
5 ->              9 :: 12;
                                 
6 ->             10 :: 13;
                                 
7 ->             11 :: 14;
                                 
8 ->             12 :: 15;
                                 
9 ->             13 :: 18;
                               
10 ->             14 :: 20;
                               
11 ->             15 :: 21;
                               
12 ->             16 :: 22;
                               
13 ->             16 :: 95; // University but not graduate school
                               
14 ->             18 :: 95; // Graduate school
                               
15 ->             15 :: 95; // Trade or technical school
   
endrecode;

   
if P04_AGE in minAgeForGrade:maxAgeForGrade then
        errmsg
("P10_GRADE_NOW_ATTENDING(=%d) is valid for age(=%d)", $, P04_AGE);
   
else
        errmsg
("P10_GRADE_NOW_ATTENDING(=%d) NOT valid for age(=%d)", $, P04_AGE);
       
reenter;
   
endif;

Flag Implementation

Another approach is to create a test flag. In the logic below, grade_is_valid is used to show whether or not the combination of grades and ages are valid. This can further increase the readability of your logic.

PROC P10_GRADE_NOW_ATTENDING

preproc

    ask if
P09_ATTEND = 1 and P04_AGE >= 3; // Currently attending school

postproc

    numeric
grade_is_valid = false;

   
recode P10_GRADE_NOW_ATTENDING :: P04_AGE -> grade_is_valid;
                                 
0 ::  3:6    -> true; // Preschool and kindergarten
                                 
1 ::  5:8    -> true;
                                 
2 ::  6:9    -> true;
                                 
3 ::  7:10   -> true;
                                 
4 ::  8 11   -> true;
                                 
5 ::  9:12   -> true;
                                 
6 :: 10:13   -> true;
                                 
7 :: 11:14   -> true;
                                 
8 :: 12:15   -> true;
                                 
9 :: 13:18   -> true;
                               
10 :: 14:20   -> true;
                               
11 :: 15:21   -> true;
                               
12 :: 16:22   -> true;
                               
13 :: 16:95   -> true; // University but not graduate school
                               
14 :: 18:95   -> true; // Graduate school
                               
15 :: 15:95   -> true; // Trade or technical school
   
endrecode;

   
if grade_is_valid then
        errmsg
("P10_GRADE_NOW_ATTENDING(=%d) is valid for age(=%d)", $, P04_AGE);
   
else
        errmsg
("P10_GRADE_NOW_ATTENDING(=%d) NOT valid for age(=%d)", $, P04_AGE);
       
reenter;
   
endif;

#Logic   


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:

alt text

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:

if pos("21", LANGUAGE_SPOKEN) then
    errmsg
("French is checked");
else
    errmsg
("French is not checked");
endif;

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

if pos("23", LANGUAGE_SPOKEN) then
    errmsg
("Russian is checked");
else
    errmsg
("Russian is not checked");
endif;

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:

if pos("33", LANGUAGE_SPOKEN) then
    errmsg
("Hindi is checked");
else
    errmsg
("Hindi is not checked");
endif;

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:

if pos("32", LANGUAGE_SPOKEN) then
    errmsg
("Bengali is checked");
else
    errmsg
("Bengali is not checked");
endif;

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.

alt text

The data are stored in the file as shown here:

alt text

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:

numeric languageFound = 0;

do varying numeric idx = 1 while idx <= length(LANGUAGE_SPOKEN) by 2
   
if LANGUAGE_SPOKEN[idx:2] = "32" then
       
languageFound = 1;
       
break;
   
endif;
enddo;

if languageFound then
    errmsg
("Bengali is checked");
else
    errmsg
("Bengali is not checked");
endif;

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:

if ischecked("32", LANGUAGE_SPOKEN) then
    errmsg
("Bengali is checked");
else
    errmsg
("Bengali is not checked");
endif;

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.


#Logic   


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:

// create a dynamic value set showing the EAs in Region 1 / District 1
valueset ea_vs;

// code demo 1 --- using a forcase loop
forcase EA_DICT where REGION = 1 and DISTRICT = 1 do
   
ea_vs.add(EA_NAME, EA);
endfor;

// code demo 2 --- automatically marking cases and then using a for loop
selcase(EA_DICT, "") where REGION = 1 and DISTRICT = 1 multiple(automark);

for EA_DICT do
   
ea_vs.add(EA_NAME, EA);
endfor;

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:

Region District EA Geocode Name
1     Region 1
1 2   District 2 in Region 1
1 2 5 EA 5 in Region 1 / District 2

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:

PROC DISTRICT

preproc

    valueset
geography_vs;

   
forcase GEOCODES_DICT where GEOCODE_REGION = REGION and
                               
GEOCODE_DISTRICT <> notappl and
                               
GEOCODE_EA = notappl do

       
geography_vs.add(GEOCODE_NAME, GEOCODE_DISTRICT);

   
endfor;

   
setvalueset(DISTRICT, geography_vs);

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:

PROC GLOBAL

valueset
geography_vs;

function CreateGeographyVS(string already_selected_key, numeric geocode_length)

    // clear the dynamic value set
   
geography_vs.clear();

    // automatically select all cases that match the key passed in as a parameter
   
selcase(GEOCODES_DICT, already_selected_key) multiple(automark);

    // this geocode starts at the position after the already selected key
   
numeric new_key_offset = length(already_selected_key) + 1;

    // loop over the cases that match the already selected key
   
for GEOCODES_DICT do

        // extract the remaining geocodes
       
string new_key_portion = strip(key(GEOCODES_DICT)[new_key_offset]);

        // when the remaining geocodes match the geocode length we are expecting,
        // this is a match so add it to the value set
       
if length(new_key_portion) = geocode_length  then
           
geography_vs.add(GEOCODE_NAME, tonumber(new_key_portion));
       
endif;

   
endfor;

    // make sure that there was at least one geocode for this hierarchical level
   
if geography_vs.length() = 0 then
        errmsg
("Geocode lookup error ... the geocode database is not complete.");
       
stop(1);
   
endif;

end;

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:

PROC REGION

preproc

   
CreateGeographyVS("", 1);
   
setvalueset(REGION, geography_vs);

PROC DISTRICT

preproc

   
CreateGeographyVS(maketext("%v", REGION), 2);
   
setvalueset(DISTRICT, geography_vs);

PROC EA

preproc

   
CreateGeographyVS(maketext("%v%v", REGION, DISTRICT), 2);
   
setvalueset(EA, geography_vs);

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.


#Logic