Creating PREPARE Specifications

PREPARE specifications include all the text, formatting commands and logic conditions that are necessary to run an interview with Survent. The question text is typed as it will appear on the screen during an interview. All other commands must follow specific syntax.

This section explains the syntax for writing PREPARE specifications. You can use this syntax to create an ASCII file and then call the file into PREPARE for processing or specify the commands line by line in the PREPARE program.

The basic syntax for questionnaire specifications is:

>PURGE_SAME
~PREPARE COMPILE

[Study header]

{question 1}
{question 2} 
..
>Meta commands (optional) 
..
{!Compiler commands} (optional) 
..
{question n}

~END
  • >PURGE_SAME tells the program to replace rather than rename same-named files that are created in this run.
  • ~PREPARE COMPILE tells the program to compile the specifications.
  • The Study Header describes the study name, case length and other parameters that control the overall interview process and how data is collected.
  • Question specifications display text to the interviewer and describe input data characteristics or serve as controls for the questionnaire flow or data collection.
  • Meta commands control the programming environment.
  • Compiler commands control general features of groups of questions or the questionnaire as a whole.
  • ~END ends specifications and causes them to be compiled. Any commands after the ~END will be ignored.

In addition to the basic syntax, special characters such as the ampersand, used for continuation of multiple-line commands, and the apostrophes used for comments, are used. Their use will be discussed later.

Composing and Compiling Questions in PREPARE

PREPARE is a subset of the Survox Mentor program. To use PREPARE, you must specify that you are in the questionnaire preparation mode. The command to do that is ~PREPARE. This must be invoked before any other questionnaire creating commands.

Commands preceded by a tilde (~) are Survox commands specifying which programming block you are working in.

To use an editor to create PREPARE specifications:

~PREPARE COMPILE should be the first line in the file (after the optional, but very useful, >PURGESAME). It directs the program to compile the questionnaire after the specifications have been entered and the program sees a ~END statement.

You can control the backup specification files that are created when you compile the specifications. By default, or by specifying ~PREPARE COMPILE SURVENT_SPECS, a backup QSP file is created with commands in standard Survent syntax. ~PREPARE COMPILE -SPEC_FILES compiles the questionnaire but does not create any files other than a QFF and QUO. This reduces the compile time somewhat.

Other keywords supported are QUANTUM, SAS, SPSS and SSS_XML to create files for other systems. (See CONVERSION TO OTHER LANGUAGES for sample output using some of these keywords.)

NOTE: Keywords that write to the same spec files cannot be used together. The QUO, QSP, CHK, HRD, DB and SUM files can be suppressed by options on the header.

The study header is next, followed by question specifications.

~END causes the specifications to be compiled and exits you to the operating system prompt.

A PREPARE compile consists of up to three steps:

  • Syntax checking
  • Label resolution
  • Variable conversion

Syntax checking is done on each question and command as the file is read. Error and warning messages are displayed at the screen and printed in the list file. You will see an indication of each question as it is read; labeled questions will display the question label, and questions without a label will print their assigned label. Error messages are printed like “ERROR #### text…”, and warnings “WARN #### text…”.

Label resolution guarantees that all references to other questions are to actual questions of the proper type for the reference.

Variable conversion makes DB variables for later use by the Survox utilities or Mentor program (if a DB file is being created). The auxiliary files (DEF, TAB, etc.) are also made during this phase.

Controlling the Auxilliary Spec Files Created

You can compile Survent specifications with the -SPEC_FILES option (makes only the QFF and QUO files) and produce only those auxiliary files you need once you are satisfied with the questionnaire.

EXAMPLE:

~PREPARE COMPILE -SPEC_FILES

Any auxiliary file can be generated from a compiled QFF (questionnaire) file without re-compiling.

The syntax for generating auxiliary spec files from a compiled Survent questionnaire is:

~QFF_FILE <studyname>
~PREPARE MAKE_SPEC_FILES keyword

where the keywords include all those available under ~PREPARE COMPILE  and these additional keywords:

Keyword File Created
CHK CHK
HRD HRD – If !HARDCOPY is specified
QSP QSP
SUM SUM

EXAMPLE:

~QFF BANK (Loads the compiled QFF file.)
~PREPARE MAKE_SPEC_FILES  (Generates a CHK file.)

NOTE: If there is a password  in the study header, you must know it to generate files.  This is used for security purposes.

Next Topic