You can customize CSEntry's behavior by creating a
PFF file. You can then use the PFF file as a command line parameter for CSEntry.exe. For example, if you name your PFF file MySurvey.pff, then you run the data entry application by invoking:
"C:\Program Files (x86)\CSPro 8.0\CSEntry.exe" MySurvey.pff
This assumes that CSPro was installed in the default directory. Your PFF file must have a .pff extension.
You can create a PFF file in one of two ways: either [1] create one with a text editor (such as Notepad or Wordpad), or [2] have it generated automatically for you by launching your data entry application from within the CSPro Designer. The file will have the same name as your application, but with a .pff extension instead of .ent. For example, if your data entry application was named MySurvey.ent, the generated PFF would be named MySurvey.pff.
The following section shows the options available to you in a CSEntry PFF file. A PFF file is not case sensitive, so you can use any combination of upper and lower case text.
[Run Information]
Version=CSPro 8.0
AppType=Entry
Description=My Survey
ShowInApplicationListing=Always
[DataEntryInit]
OperatorID=John
Key=1250
StartMode=Add
AutoAdd=Yes
FullScreen=No
NoFileOpen=No
Lock=Verify,Stats
Interactive=Ask
CaseListingFilter=12
[Files]
Application=.\MySurvey.ent
InputData=.\MyData.csdb
Paradata=.\MyParadataLog.cslog
CommonStore=.\MySettings.db
HtmlDialogs=.\MyDialogsDirectory
BaseMap=.\MyMap.mbtiles
[ExternalFiles]
LOOKUP_DICT=.\LookupFile.dat
[Parameters]
Parameter=your choice
Language=LINGALA
OnExit=.\Menu.pff
[DataEntryIds]
PROVINCE=12
DISTRICT=05
The [Run Information] block is required. While Version and AppType must appear exactly as shown in the example above, there are two optional properties:
- Description=if specified, it will be used instead of the name of the file in the list of applications (mobile only) and in the window title during data entry (all platforms).
- ShowInApplicationListing=determines whether the application associated with this PFF is displayed on the mobile Entry Applications screen. The possible options are: Always (default), Never, and Hidden. Operators must manually elect to show hidden applications, whereas PFFs with the Never option will never be shown. Always (the default) is a good choice for menu applications or other programs that you always want your interviewers to see. Never is a good choice for the applications the menu program launches, as you will likely not want those programs being launched directly without parameters being set first. Hidden is useful for utility programs that you want supervisors or IT staff to have access to, but that you don't want the interviewers to be aware of.
The [DataEntryInit] block is optional. It gives you the opportunity to customize the following runtime characteristics:
- OperatorID=specifies the operator ID for the purposes of logging operator statistics. If this line is not present but your data entry application has been set to ask for this, CSEntry will prompt the operator for one at runtime.
- StartMode=determines the mode in which CSEntry starts. The possible options are: Add, Modify, and Verify. If this line is not present, one of two things will occur: if the data file does not exist, then the program will start in Add mode; if the data file does exist, then CSEntry will wait for the operator to choose their desired mode. The operator's choices may be constrained due to options indicated in the Lock feature.
You can also specify the case upon which to act by adding a semicolon and the case IDs of an existing case (for example: StartMode=Modify;010502). This will open CSEntry in Modify mode and open the case indicated by the ID. If the StartMode conflicts with the Lock parameter settings, then the StartMode parameter will take precedence. - Key= specifies the case ID to automatically open. If a key is provided that exists in the data file, CSEntry will open that case and then close once the case has been entered. If the case does not exist, a new case is created and the IDs automatically filled from the values specified. If only a partial key is provided, then only the values specified are prefilled. (For example, if the IDs are cluster and household number and the key only specifies the cluster, then the cluster will be automatically filled but the interviewer will have to specify the household number.) The StartMode attribute takes precedence over the Key attribute. You generally will use only one, if any, in your design. This attribute is typically used in menu programs, often with the output of the key logic function.
- AutoAdd=indicates whether, while in Add mode, CSEntry should continuously add cases, meaning that after a case is added, CSEntry will begin adding another case. The possible options are: Yes (default) and No.
- FullScreen=determines whether CSEntry will open the application in full screen mode, with no case tree on the left. The possible options are: Yes, No (default), and NoMenus. The parameter NoMenus will open CSEntry in a tablet-friendly mode whereby the case tree and the CSEntry menus and title bar are not shown.
- NoFileOpen=determines whether CSEntry will permit the operator to open another data file while running a data entry application. The possible options are: Yes (default) and No.
- Lock=indicates what CSEntry modes the operator cannot access. The possible options are:
- Add: The operator cannot add new cases.
- Modify: The operator cannot modify existing cases.
- Verify: The operator cannot verify existing cases.
- Delete: The operator cannot delete cases.
- View: The operator cannot use the questionnaire view to view cases from the case listing.
- Stats: The operator cannot view operator statistics.
- CaseListing: On mobile CSEntry, the Case Listing screen will be bypassed.
Multiple modes can be specified by listing each mode, separated by a comma. - Interactive=specifies the default way that CSEntry runs in Interactive Edit mode. The possible options are:
- Ask: The default option, CSEntry will ask the operator how to run Interactive Edit.
- Both: CSEntry will display both out-of-range messages and errors generated from the errmsg function.
- ErrMsg: CSEntry will only display errors generated from the errmsg function.
- Range: CSEntry will only display out-of-range message.
- Off: Interative Edit mode will be disabled.
If the mode is followed by a comma and Lock, then the mode cannot be changed by the operator. Otherwise, unless the option is Off, the operator can change the mode from within CSEntry. - CaseListingFilter=filters the cases in the data file shown to the operator. The filter string can use regular expressions. If you have multiple operators entering data to the same data file, this can be a way to prevent operators from interacting with data entered by other operators. The filter is matched against the IDs of each case.
The [Files] block is required. A description of the files, not all of which have to be specified, is as follows:
- Application=the name of the data entry application that you created.
- InputData=the data file that an operator will be creating, modifying, or verifying with this data entry application.
- Paradata=the name of a file where events logged during the application's run are saved.
- CommonStore=if you use the loadsetting or savesetting functions in your program, this file overrides the default location where these settings are saved.
- HtmlDialogs=the name of a directory that contains custom HTML dialogs that override the default CSPro ones.
- BaseMap=the name of the online map or the filename of an offline map used for CSPro mapping.
If the
[ExternalFiles] block is present, it means that a second (or more) dictionary was linked to the data entry application. In the example above, LOOKUP_DICT is the dictionary name, and LookupFile.dat is the name of the data file that contains the
lookup codes.
The [Parameters] block is optional. This section defines parameters for the data entry run.
- Parameter=allows you to pass in a string to your program. The parameter can be any length, although the string that retrieves the value in your program (via the sysparm function) must be large enough to accommodate it. Once the parameter is retrieved, it can be parsed by your program for further usage.
- Language=specifies the initial language of the program. The parameter must match the name of a language specified in the question text, dictionary, or message file.
- OnExit=specifies a PFF file to run after the data entry program closes. This can be useful, for example, if you want to relaunch a menu program after collecting data.
When starting a new case, if the name of a parameter matches the name of a dictionary item, the value of that item will be set to the value specified in the PFF. This is similar to how the persistent fields are processed (see below), but this works for non-persistent fields.
The
[DataEntryIds] block is for use with any
persistent IDs that you have defined. CSEntry will assign the specified values to the indicated persistent fields when a new data file is created. This feature allows automatic definition of persistent fields, such as geographic IDs. If you provide values and run this on an existing data file, and the PFF file values do not match the values in the data file, then the PFF values will be ignored. The syntax is as follows:
id_item_name=initial_value