Appendix I: Transfer Scripts
Previous Topic  Next Topic 

Using a transfer script the PocketSurvey Mapper tool can produce data for immediate input into Comino's Saffron, DPFA's Simdel, IBS's Open Housing or ANY housing management or backend database system that your organisation may have in place.

To take advantage of the revolutionary PockeySurvey Mapper tool, available only in PocketSurvey, you must supply a special transfer script to work alongside your survey design. The script must be named 'PocketSurvey Mapper.script' and must be placed in the survey folder that contains you collected data.

Normally Handheld Systems write these scripts for their clients, but for the more adventurous, the format is described below.

Note

A full example of a transfer script can be viewed by clicking here.

Format of a Transfer Script

A PocketSurvey Mapper transfer script comprises of one or more build rules. A build rule comprises of three main parts.

    1. Destination & Source Files. Statements to define the destination and source data files.
    2. Data Fields to be Created. These statements define the data fields to be created and the order that they appear in the output file.
    3. Question Rules. These statements define which question answers will be used to provide data.

Destination & Source Files

BUILD <destfile> FROM <source>

<destfile> is the name of the file to be produced by the build rule. It may comprise of an absolute or relative path, file name, and extension. The name must be enclosed by quotes. Relative paths start from the main PocketSurvey folder.

<source> may be either parent or child. Although these are keywords they must be lower case. They refer to which of the two files produced by PocketSurvey is to be used as input to the rule. These are logical names - PocketSurvey Mapper will determine the actual filenames at run time.

Data Fields to be Created

FIELDS <fieldlist>

<fieldlist> describes the field names in the order in which they will appear in the <destfile> as shown below.

FIELDS
"Asset Reference",
"Location",
"Quantity",
"Characteristic Value".

If a field name contains spaces then it must be enclosed by quotes. Commas separate each fieldname and the list is terminated by a full stop.

Question Rules

If the source is child then each question rule may refer to individual sections and questions in the survey design, as shown below.

FOR QUESTIONS 1 USE . . .

This will apply the rule only to records created by that particular question. If you wish to apply the same rule to more than one section or question then separate the section/question numbers with commas, as shown below.

FOR QUESTIONS 2.1, 2.2, 3.1, 3.2, 3.3, 3.4 USE . . .

If you wish to apply the rule to all the questions (and any nested sections) within a section then simply state the section number, as shown below.

FOR QUESTIONS 2, 3 USE . . .

Note

Section numbers can be viewed by switching the Settings | Section Numbers option on in PocketSurvey.

To apply the rule to all questions use:

DEFAULT USE . . .

DEFAULT must always be used for a parent source. For a child, it may come after any specific question rules; if it is placed before other question rules then it will prevent any following rules from being reached.

Additional conditions may be applied to question rules by inserting WHERE <conditions> immediately before USE, as shown below.

FOR QUESTIONS 2 WHERE Condition_Code = "GOOD" USE . . .

If you wish to combine several conditions together then separate then with AND, as shown below.

FOR QUESTIONS 2 WHERE Category = "F" AND ISNT Condition_Code = "GOOD" USE . .

This means that both conditions must be met before the rule is applied. Note that the second rule is preceded by the keyword ISNT, this negates the following condition - thus, in this example, any Condition_Code that is not "GOOD" will be true.

All rules must be followed by a <fieldlist> as explained below.

Question Rule Field Lists

The question rule field list is a list of source field names in the order in which they will be output. Note that this is not necessarily the order in which they appear in the source. In fact, this should always be the case otherwise there would be no need to re-map the file in the first place.

There is no need to describe the original source fields and their order as PocketSurvey Mapper determines this at run time from the survey design.

The rule field list may contain fewer fields than the output file (unmapped fields will default to nulls) but never more, as shown below.

FIELDS
UPRN,
Quantity,
"Unit Of Measure".
FOR QUESTIONS 2 USE
UPRN,
Answer,
Attr_Unit_Of_Measure.

The + symbol may be used to concatenate fields to produce a single output field, as shown below.

FOR QUESTIONS 1 USE
UPRN,
"Characteristic Text (menu)" + "Characteristic Text (free)".

If a source field name cannot be matched with any of those produced by the survey design then it will be treated as a literal. Therefore badly spelt names will still produce something. Check your output carefully as PocketSurvey Mapper cannot check for errors of this kind.

Header records

If you want column header records to appear in the output files then the field names as 1st record option must be turned on -- see Questionnaire | Options for more details.

Transfer only option

You can use PocketSurvey Mapper to transfer files without any re-organisaton. To do this, simply use the first part of the basic form on its own, as shown below.

BUILD "C:\DATA\SURVEYS\element.txt" FROM child

This will place a verbatim copy of the child file into the C:\DATA\SURVEYS folder under the name "element.txt". Any existing file with the same name will be overwritten.

Using a transfer script from the command line

PocketSurvey Mapper can be used directly form the command line. The general format is "PocketSurvey Mapper" <Pathname>, where <Pathname> is a relative or absolute path to the folder containing your mapper script. By default the mapper appends to any existing output files but the optional -o switch can be used to cause the mapper to overwrite any existing files, e.g.

"PocketSurvey Mapper.EXE" -o SURVEYS\MYSURVEY

If your pathname contains any blank spaces then you will need to enclose it with double quotes.

HandHeld Systems Ltd ©