Table of contents

COMPLETE TECHNICAL DOCUMENTATION ON A SINGLE PAGE QUICK START INTRODUCTION
DESIGN Question name line Question text Question note Answer categories Simple skips Display condition Open end part Response recall Computed questions Commenting a script	STRUCTURE Pages Tables Permutations of questions Hierarchical projects Interruption	APPEARANCE Page structure and templates Text formatting Colours and layout In-questionnaire formatting Examples of final products	MANAGEMENT Permission management Integrated module Initiation of a project File management Quota management E-mail notification Questionnaire completion Modifications to a project Case management Real-time results Extraction of data Data base destruction Performing back-ups
APPENDIX A Pound Instructions ** APPENDIX B Installation instructions APPENDIX C URL options APPENDIX D Recent changes and additions APPENDIX E Formatted tabular output syntax APPENDIX F Security features APPENDIX G Context data		APPENDIX H TEST pound instruction APPENDIX I System messages APPENDIX J System variables APPENDIX K Weight variables (deprecated) APPENDIX L Basic HTML codes APPENDIX M Project initiation checklist APPENDIX N File types Summary card of CallWeb syntax
* Updated in April 2025 ** Updated in May 2025

Quick start

This page provides brief instructions on how to set up your first CallWeb project. It is assumed that you have access to a Web server equipped with CallWeb and to an FTP program to transfer files to the server.

1. Using your Web browser, call the CallWeb integrated module; the address was provided to you by your administrator.
2. From there, use the cwedit module to create a one-question questionnaire.
3. Save this questionnaire script under the file name "test" — the questionnaire file will be named test.scw (the .scw extension indicates a CallWeb script).
4. Still from cwedit, click on the Compilation icon. This will open a new window which will report the status of the compilation, and any compilation errors.
5. Close the cwedit window.
6. Click on your browser Reload button to refresh the integrated module page with the information on the project your have just compiled.
7. Select the "test" project from the drop-down list next to "Start a new questionnaire; ../callweb.cgi" and click on the icon on that line.
8. Your question appears on this new, one-question project!

General introduction

CallWeb is a computer system which facilitates the creation of intelligent forms and questionnaires and the management of the collection of data using these forms and questionnaires.

This document reviews the operations of CallWeb in the following sequence:

• first, basic questionnaire design syntax is explained
• then, ways to define a structure for the questionnaire are reviewed
• third, tools available to control the questionnaire appearance are presented
• finally, a project life-cycle is explained

Much of the CallWeb action is centered around scripts which are text files comprising the definitions of each question in the questionnaire — and then some. There are two ways to create and modify scripts:

• using a text editor like Notepad or TextPad, the questionnaire designer has direct control over every aspect of the questionnaire and can perform changes extremely fast;
• using the cwedit CallWeb module, the designer can also control every parameter of a questionnaire in a more user-friendly (but definitely slower) environment. cwedit has three limitations: it does not support the SUFFIX CORNER parameter, the response category ALIAS parameter and the concurrent use of same-named container questions.

The choice of the questionnaire creation and modification is yours; however, this documentation is focussed on the text editor approach (rather than the cwedit module) because it is faster and because it requires more handholding in the beginning.

Questionnaire design

Introduction

A CallWeb questionnaire is contained in a strict ANSI file (only ANSI characters, no word processing commands) where each question is presented in the sequence in which it will be used in the questionnaire. The questionnaire file uses the following naming convention: the extension must be .scw (stands for "script for CallWeb") and the file name (without extension) becomes the project name as far as CallWeb goes. Caution: the case of the letters counts in the name of the file and in the project name.

The structure of a question definition is as follows:

QUESTION_NAME_GOES_HERE
% Question text follows this % sign
   QUESTION TEXT
% Note text follows this % sign
   NOTE TEXT
% Answer categories follow this % sign
   ANSWER CATEGORIES
% Simple skips follow this % sign
   SIMPLE SKIPS
% Display condition follows this % sign
   DISPLAY CONDITION
% Open end part definition follows this % sign
   OPEN END PART
! End of question definition

So a real-life example of a question definition would be as follows.

##
## Question Q1
##
Q1
% Question text
   Are you generally considered a male or a female?
% Note
% Answer categories
   Male
   Female
   *9*I don't really know
% Simple skips
   9 = BYEBYE
% display condition
   Q0.EQ.1
% Open end part
   9 = C80 2 40
! End of question definition

Each segment of the questionnaire definition will now be reviewed.

Questionnaire design

Question name line

The question name line uses the following syntax (all information must be supplied on a single line):

QUESTION_NAME MIN=n MAX=n NCOLS=n SUBSET=question CODESIN=question CATEGORIES=question CORNER=(text) ONE OR MORE KEYWORDS MUST=(condition)

The question name:

• may contain up to 64 characters;
• must start with a letter other than A;
• may contain letters, numbers and the underscore character.

The MIN= parameter is the minimum number of responses expected. Set at zero, it allows nonresponse to a question. The default is 1.

The MAX= parameter is the maximum number of responses expected. Set at a value greater than 1, it forces the use of check boxes rather than radio buttons. The default is 1.

Setting both MIN and MAX at zero creates a question without answer categories. CallWeb displays the question text and note, if applicable.

The NCOLS= parameter determines over how many columns the response categories will span. The overall system default is a single column list. This system default can be overridden by a questionnaire-wide default using the # N COLONNES PAR DEFAUT instruction. Finally, the question-level NCOLS parameter can override all of the defaults on a question by question basis.

The SUBSET=question parameter names the open-end part to use to reduce the list of answer categories using a substring in the code labels (see a full description).

The CODESIN=question parameter names the open-end part to use to reduce the list of answer categories using any criteria from a related data base (see a full description).

The CATEGORIES=question parameter names the open-end part to use as input to create the list of answer categories (see a full description).

The MUST=(condition) parameter specifies a logical condition under which an answer MUST be supplied to the question.

The CORNER=(text) parameter changes the text displayed in the left corner of a table header, for this question only. It can contain one segment for each questionnaire language, specified using square brackets and two-letter language codes (e.g., [EN]).

• See the section on Display conditions for the syntax of logical conditions.
• The logical condition must be within parentheses (for xBase-style conditions) or braces (for Perl-style conditions).
• This is in addition to the MIN and MAX parameters such that a question can have a minimum of zero answers (be allowed to not be answered except under circumstances defined in the MUST condition).
• The MUST condition is applied only if the question is displayed according to its display condition.
• The MUST condition should be specified last on the Question Name line.
• Example of use: one can build a two-variable-side-by-side matrix of, say, importance ratings, where the last entry is an "other" with an open-end box and a rating scale. These two questions have a minimum of zero answers since some people may have no "other" answer but if a scale rating is supplied, a description must be offered in the open-end box. In this case, MUST=(Q2.GT.1) applied to Q1 would insist upon the supply of an answer to Q1 if Q2 was answered to.

The KEYWORDS can be any of the following values (logically, some can be used concurrently, others not):

Questionnaire design

Question text

The question text may flow over several lines. CallWeb concatenates all lines prior to processing the text. Remember that the final appearance for the survey participant, including line wrapping, is controlled by the browser.

Example of a question text segment:

% Question text
   [EN]Are you generally considered a male or a female?
   [FR]Êtes-vous généralement vu(e) comme un homme ou une femme?

The question text may contain HTML codes. Such codes are interpreted directly by the browser.

Recall of previous answers can be done in the question text. See the Response recall section for the syntax of the recalls.

If more than one language is defined in the questionnaire, language segments of the question must be preceded by the international ISO language code within brackets (e.g., [EN]). A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.

The text of the question can be borrowed from another question by putting the equal sign (=) left of the name of the question from which to copy. However, the copy by equal sign is deactivated if the question text starts with a tilde (~) to allow for UTF-8 encoded email titles — the tilde is silently deleted.

Questionnaire design

Question note

Notes are displayed after the question text, using a different look; they also specify the text of the line in matrix presentations (see Tables section).

Example of a note segment:

% Question note
   [EN]Please be as specific as possible.
   [FR]Veuillez être aussi précis que possible.

The note text may contain HTML codes. Such codes are interpreted directly by the browser.

Recall of previous answers can be done in the note text. See the Response recall section for the syntax of the recall.

If more than one language is defined in the questionnaire, language segments of the note must be preceded by the international ISO language code within brackets (e.g., [EN]). A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.

The text of the note can be borrowed from another question by putting the equal sign "=" left of the name of the question from which to copy.

Question cloning

When a series of questions that are exactly the same except for the Note field (and possibly the display condition) must be created (e.g., to create a battery of questions presented in a table format), it is possible to use a succinct cloning syntax. This is more easily explained with an example:

Q1
% question
   Have you ever:
% note
   [SUFFIX:_A]ridden a bicycle
   [SUFFIX:_B]driven a car
   [SUFFIX:_C]piloted a plane
% categories
   Yes
   No
% skips
% condition
% open part
!

This code creates three questions (Q1_A, Q1_B and Q1_C) which share all characteristics except for the content of the Note. These questions may or may not be then placed into pages and/or tables. If different languages are used, each suffixed entry must contain the proper language segments.

The container question (Q1 in the example above) does not exist as far as CallWeb is concerned; only the suffixed questions do. Therefore, while it is possible to copy from and to the suffixed questions (Q1_A and following in the example), it is not possible to copy from and to the container question (Q1 above). This means that, following the same example, this code is legitimate:

Q1
...
   [SUFFIX:_A]=Q0_A
   [SUFFIX:_B]driven a car
   [SUFFIX:_C]piloted a plane
...
Q2A
...
% note
   =Q1_A
...

and this code as well:

Q1
...
   [SUFFIX:_A]ridden a bicycle
   [SUFFIX:_B]driven a car
   [SUFFIX:_C]piloted a plane
...
Q2
...
% note
   [SUFFIX:_A]=Q1_A
   [SUFFIX:_B]=Q1_B
   [SUFFIX:_C]=Q1_C
...

but that this one is not:

Q1
...
   [SUFFIX:_A]ridden a bicycle
   [SUFFIX:_B]driven a car
   [SUFFIX:_C]piloted a plane
...
Q2
% question
   =Q1
   ## Hint: that's because Q1 is a container question, hence it does not exist
...
% note
   =Q1
...

We highly discourage building a script containing a regular question (e.g., Q1) AND a container question (e.g., Q1 + various suffixes), or two container questions, with the same name. The compiler is able to deal with such situations but the cwedit module cannot.

Display conditions can also be applied to particular suffixes. Such a display condition is inserted between brackets immediately after the SUFFIX bracket set and immediately before the text of the note. SUFFIX display conditions supersede any display condition that could be attached to the container question. Thus, in the following example:

Q2
% question
   Have you ever:
% note
   [SUFFIX:_A][Q1.EQ.1]ridden a bicycle
   [SUFFIX:_B]driven a car
   [SUFFIX:_C]piloted a plane
% categories
   Yes
   No
% skips
% condition
   Q1.EQ.2-4
% open part
!

the display condition on the first statement is [Q1.EQ.1] while the other statements have a display condition of [Q1.EQ.2-4].

The same logic applies to CORNER=(text) parameters which can be added on the SUFFIX line as follows:

Q2
% question
   Have you ever:
% note
   [SUFFIX:_A][CORNER=([EN]Put this text in the corner of the table)]ridden a bicycle
   [SUFFIX:_B]driven a car
   [SUFFIX:_C]piloted a plane
% categories
   Yes
   No
% skips
% condition
   Q1.EQ.2-4
% open part
!

The CORNER=(text) parameter changes the text displayed in the left corner of a table header, for this question only. It can contain one segment for each questionnaire language, specified using square brackets and two-letter language codes.

SUFFIX questions are not limited to building tables but they are a very quick way to create a series of questions that share a response set and that can be displayed in table format. It is sometimes useful to insert a title row in such a table, as shown in the image to the right where the PRODUCT and FINANCIAL lines act as titles (no data is collected about them). One simple way to create such titles is to add the letter "T" to the keyword "SUFFIX" (making it "SUFFIXT"). A SUFFIX-title question is imposed a minimum of zero answers (so that it can be left unanswered) and all of its response codes are given a behaviour code of "N" (in addition to any other behaviour code the answer categories may have) so that no response object (a radio button or a check box) is shown in the cells of the title line.

Questionnaire design

Answer categories

Each answer category must be laid out on a single line. Remember that the final appearance for the survey participant, including line wrapping, is controlled by the browser. The syntax of the answer category line may be either of the following three:

Simply a label
*number*Label
*number*behaviour_code*Label

A simple label is automatically assigned a numeric code one unit larger than the previous code, starting from 1. If a number is provided between asterisks, that number becomes the category code. Answer categories need not be ordered according to this number and numbers need not form a sequence.

Answer categories are always given numeric codes. By default, CallWeb reserves four digits to store all answers to regular questions (exclusive of open end parts, see Open end part section) but more can be used. If more are used, the "# Extraction width" pound instruction will be requested by the compiler.

One or more behaviour codes may be added between asterisks following the number code (a number code is required in order to use a behaviour code). Behaviour codes are selected from the following list:

Language segments in answer categories are treated in the same manner as within the question text. A lonely equal sign (=) in a text field can be used to copy text from the default language to any non-default language.

Example of an answer category:

*9*X*[EN]Don't know[FR]Ne sait pas

An unlimited number of categories may be defined for each question. Questionnaire compilation is obviously longer as the number of categories increases.

Copying of answer categories

It is possible to borrow integrally the answer categories from another question by inserting a single line in the answer category section. This line contains the symbol "=" and the name of the question from which to borrow such as in the following:

=Q1

Borrowing questions and questions borrowed from need not be in any particular order in the questionnaire.

Response aliases

Response aliases are elements of text which are different from the main label of an answer and which can be recalled instead of the main label. The syntax of aliases is as follows:

label[ALIAS PW:text][ALIAS NAME:text]

Language codes and behaviour codes can be used along with aliases as in the following example:

*5*D*[EN]label[ALIAS FIRST:text][ALIAS SECOND:text][FR]étiquette[ALIAS FIRST:texte][ALIAS SECOND:texte]

In a given set of answer codes, some codes may bear aliases while others don't. A give code can possess an indefinite number of aliases. Aliases must be placed at the end of the response. Aliases are used in recalls using the syntax &QUESTION#alias_label (e.g., &Q1#PW).

"Title" attribute

Special tags can be added to each response category to improve accessibility for the visually impaired. These special tags are placed in the "title" attribute of HTML form objects to better identify them. These labels are defined in a pair of tags <title></title> in the definition of a response category like this:

*5*D*[EN]label<title>The title goes here</title>[ALIAS FIRST:text][FR]étiquette<title>Le titre va ici</title>[ALIAS FIRST:texte]

The "title" attribute can be defined for all categories, some or none, in one language or several, as needed. The default is the response label itself.

Special cases: permutations and inversions

CallWeb features special tools to implement answer category permutation and inversion.

If the keyword "ROTATION" is present on the question name instruction, the answer categories are displayed in random order, suject to the categories with a B behaviour code.

If the keyword "INVERSION" is present on the question name instruction, the answer categories are displayed in the original order or the reversed order, randomly, suject to the categories with a B behaviour code.

Example:

Q1 ROTATION
% Question text
[EN]Are you generally considered a male or a female?
[FR]Êtes-vous généralement vu(e) comme un homme ou une femme?

Special case: display conditions on response categories

By default, all response categories are displayed. However, their display can be made conditional to previous answers by inserting an additional line containing a display condition within square brackets. Such a condition line affects the category that is defined on the line following immediately.

Example:

A label
[Q1.EQ.1]
*2*Label
*3*Label

In this example, the second category is displayed and available only if the value of Q1 is 1. Answer category display conditions are enforced even when questions are presented as tables.

Questionnaire design

Simple skips

The definition of a simple skip is... simple: list the answer category code(s) left of an equal sign (=), separated by commas, and the question to skip to to the right of the equal sign. There can be any number of such definitions in a question; each must be on its own line.

Example of a simple skip:

% Simple skips
8,9 = BYEBYE

Note that, by default, when questions are skipped, all of the data that they contained are erased. This behaviour can be changed for the whole questionnaire by setting the # Cleaning skips parameter to "no" or for a specific skip by prefixing the destination question with a "~" sign as in

% Simple skips
8,9 = ~BYEBYE

Hyperlink skips with JUMP

It is possible to create a hyperlink to a particular question in the current questionnaire. The syntax is as follows:

... {JUMP:QUESTION}text{/JUMP} ...

This syntax creates a link on "text" (which can part of any of the question elements) that jumps immediately to question "QUESTION" without processing any input from the current page. This type of hyperlink skip does not clean intervening questions.

It is also possible to JUMP to another project using the following syntax: {JUMP:QUESTION,project}.

Finally, it is also possible to JUMP to a specific case of another project using the following syntax: {JUMP:QUESTION,project,telkey}.

These various flavours of {JUMP:} can all produce encrypted links if they are called as {JUMPC:}. (See the cover function.)

Questionnaire design

Display condition

A display condition is a logical expression which determines whether a question is displayed. It is a way to implement skip logic which is much more robust than simple skips or calculated skips because it is directly associated with the destination question.

The logical expression must use the xBase logical expression format (for experts: the expression can also follow Perl syntax and use any variable in the Perl environment if the condition is presented between "{" and "}" signs). It may use any of the variables defined in the questionnaire, including prepopulated data. Basics of the xBase logical expression format are as follows:

• comparison operators are: .EQ., .NE., .GT., .GE., .LT., .LE.
• logical operators are: .AND., .OR., .NOT.
• simple mathematical operations such as: +, -, /, *, **
• parentheses are permissible and affect the order of interpretation.
• questionnaire languages can be identified using the following syntax: LANGUAGE(la) or LANGUE(la) where "la" is a single two-letter ISO language code or a series of them separated by commas and/or spaces.
• empty variables can be identified using the following syntax: ISEMPTY(Q1) or ESTVIDE(Q1) (Q1 is replaced with the appropriate field name, which could be an open-end part name).
• non-empty variables can be identified using the following syntax: NOTEMPTY(Q1) or NONVIDE(Q1) (Q1 is replaced with the appropriate field name, which could be an open-end part name).
• QUESTION(Q1) is true if Q1 is the current question when the test is performed. QUESTION(Q1...) is true if the name of the current question when the test is performed starts with Q1.
• NRESPONSES(Q1) returns the number of responses given to Q1.
• MOBILE() returns 1 or true if the questionnaire is displayed on a mobile device (0 otherwise).
• ACCESS() returns 1 or true if the questionnaire is displayed in accessiblity mode (0 otherwise).
• when using .EQ. and .NE. (on regular single-answer and regular multiple-answer questions as well as integer open parts), the right side of the comparison may take three forms:
• Q1.EQ.1 and Q1.NE.1 compare the answer to Q1 to a single integer
• Q1.EQ.1,3,5 and Q1.NE.1,3,5 compare the answer to Q1 to a each integer and returns true if one of them matches (for .EQ.) or none of them matches (for .NE.)
• Q1.EQ.1-5 and Q1.NE.1-5 compare the answer to Q1 to a each integer between the two bounds and returns true if one of them matches (for .EQ.) or none of them matches (for .NE.)
• Q1.EQ.1-5,7 and Q1.NE.1-5,7 compare the answer to Q1 to a each integer between the two bounds as well as other individual values (any number of ranges or individual values can be supplied between commas) and returns true if one of them matches (for .EQ.) or none of them matches (for .NE.)

CallWeb takes care of applying the xBase logic on multiple-answer questions.

Remember that all answer categories are numeric. This simplifies the construction of logical expressions.

Example of a display condition segment:

% Display condition
(Q1.GT.2.AND.Q2.EQ.1)

When CallWeb encounters a display condition which evaluates to "false", it erases any data that the associated question may contain in its numeric and open-end portions — however, it does not erase the destination of a CALCUL variable. This is a logical behaviour since that question should not have been displayed to start with — although it may have been legitimately displayed before the user backtracked and changed previous answers. To create a non-displayed variable where data must be stored (such as prepopulated fields), consider using the open-end portion of a BLANK question or the NEVERUPDATE or STOCK question types, or the display condition must be prefixed with a tilde (~) to indicate a non-cleaning display condition (much like the tilde prefix makes a simple skip non-cleaning)..

It is possible to borrow the display condition from another question by inserting a single line in the display condition section. This line contains the symbol "=" and the name of the question from which to borrow such as in the following:

=Q1

Borrowing questions and questions borrowed from need not be in any particular order in the questionnaire.

Questionnaire design

Open-end part

An alphanumeric, numeric and other types of open-end component may be attached to any answer category. It is stored in a separate "question" which bears the same name as the originating variable to which the letter "A" is preappended. The definition of open-end parts follows this syntax: list the associated answer category code(s), separated by commas, left of an equal sign and add the open-end instructions right of the equal sign.

Example of an open-end segment:

% Open-end part definition
9 = C80

The syntax of the open-end instruction line is as follows (according to the type of data expected).

Controlling the size of the data entry box

Most open-end parts default to displaying a 4-line, 40-column box. The size of the box can be determined on a case-by-case basis using the following syntax:

open-end_parameter n_rows n_columns

as in

C30 1 20

which opens a 1-row, 20-column box to contain an alpha-numeric answer of a maximum of 30 characters.

Note: Unless "# Enforce response length" is set to YES, multi-line boxes do not implement the limit as to the acceptable number of characters; in this case, the limit is used only upon extracting a fixed-column file. Single-line boxes do constrain the input to the number of characters specified along with the open-end type. If "# Enforce response length" is set to YES and that the W modifier accompanies the C open-end (e.g., CW100 2 30), the value (here 100) is expressed in words rather than characters.

Numeric open-end parts always open a single-line data entry box; the width of this box is a function of the number of characters allowed by the open-end part definition.

Formatting numeric values

By default, numeric values supplied in open-end parts are not formatted; in fact, extraneous characters like dollar signs and percent signs are stripped from the value stored in the data base and French decimal commas are changed to English decimal points.

Using the following syntax, it is possible to display a formatted version of an open-end part in data entry boxes and in response recalls:

1 = N5 FORMAT=formatxx

where

• "FORMAT=" is a keyword that must be supplied as such;
• "format" is one of the following values:
• NUM: for a simple numeric value using xx decimals
• DOLLAR or DOLLARS: for a currency value expressed in dollars
• POUND or POUNDS: for a currency value expressed in Sterling pounds
• EURO or EUROS: for a currency value expressed in euro
• PERCENT or POURCENT or %: for a percentage value
• TELEPHONE: for a telephone number stored as a 10-digit number
• ZERO: returns z zero-padded version of an integer value
• "xx" is the number of decimals to display (except for TELEPHONE where no xx is expected and ZERO where xx is the total number of positions in the final zero-padded integer value).

Therefore, 1 = N6.2 0 100 FORMAT=DOLLAR2 would display the open-end part as a dollar value with 2 decimals.

Note that the field width (6 in the example above) determines the width of the data entry box for a numeric value; this width must be sufficient to allow for the display of the formatted value.

Also note that the "format" keyword can be replaced by a substituted value in Perl (between braces) format; this allows for conditional formatting (e.g., displaying currency amounts as a function of a previous question).

Questionnaire design

Response recall

CallWeb allows for the recall of three types of information in the question text, question note and answer categories:

Recalls can be performed on data stored in any type of question, be that a regular "asked" question or a BLANK question, a CALCUL question, etc.

Example of recall of the answer category selection in question Q1:

% Question text
[EN]Earlier, you mentioned that you are generally considered a &Q1? Was it always the case?
[FR]Vous avez mentionné plus tôt que vous êtes généralement vu(e) comme un(e) &Q1? Est-ce que cela a toujours été le cas?

Recall pound instruction

Special recall values can be created using the "# Recall" or "# Rappel" instruction. The syntax of the instruction is as follows:

# Recall some_label = [EN]recalled_text[FR]texte_rappelé

These values are recalled using the following syntax: &#some_label. For example, all "New" icons used in this documentation appear using

&#NEW which is defined in the following pound instruction: # Recall NEW = <img src="cwdoc/new.gif" style="vertical-align:middle">.

To avoid clashes with HTML symbols, some_label must be in capital letters when recalled and it must start with a letter. It can contain letters, numbers and the underscore character.

# RECALL (or # RAPPEL) can use display conditions so that different substitutions are done under different circumstances. Display conditions come right before the recalled value itself as in:

# Recall WORD = [AQ1.LE.1][EN]word[FR]mot[AQ1.GT.1][EN]words[FR]mots

In this example, &#WORD recalls "word" (singular) if AQ1 is less than or equal to 1 and "words" (plural) if AQ1 is greater than 1.

The display condition is expressed in xBase syntax unless it is within braces and it is expressed in Perl syntax. If the display condition contains a closed bracket symbol (as in a Perl regular expression including classes of characters), use double open and closed bracket symbols to delimit it (as in [[{condition}]]). The recalled text of the first matching display condition is used. The condition [ELSE] is always true; it is useful to conclude a series of conditions.

If the recall is followed by a tilde (e.g. &#WORD~), this character serves as a delimiter and is NOT transmitted to the questionnaire page thereby allowing the absence of spacing between the ercall and the text that follows it..

Advanced features

Recalled values are inserted within HTML <SPAN> markers to give them the SUBSTITUT style. This can interfere with the proper display of some recalled values — particularly if the recalled values are placed within hyperlink marks. To avoid the addition of the SUBSTITUT style, insert a tilde character (~) between the recall symbols and the variable name as in the following:

% Question text
[EN]Earlier, you mentioned that you are generally considered a &~Q1? Was it always the case?
[FR]Vous avez mentionné plus tôt que vous êtes généralement vu(e) comme un(e) &~Q1? Est-ce que cela a toujours été le cas?

It is possible to recall any variable available in the Perl environment as part of the CallWeb script (see the context data, in particular). The recall syntax is then {$variable}. For example, the following page header would cite the current case access code:

# HEADER EN = Your case access code is {$_telkey}

Recalled values may contain recalls. For example, the following instruction is valid and will recall the _telkey value using &#TELKEY:

# Recall TELKEY = {$_telkey}

There is yet another type of recall (although it is more than a simple recall). Any Perl expression (not only variable names) can be displayed where substitutions are allowed using the following syntax:

<EXECUTE>Perl expression</EXECUTE>

Using this syntax, one can display the result of complex calculations without having to store them in a CallWeb question field.

Also, it is possible to calculate the result of a recall into a question or as part of an EXECUTE tag. See the "substitue" function on the computed questions page.

Finally, here is a specialized type of substitution: <crypt>text</crypt>. The text between these tags is encrypted using the cover function. There is a special application of this type of substitution. Options inserted in CallWeb questionnaire URLs can be obfuscated using syntax like the following:

http://somedomain.com/cwx.cgi?_crypt=<crypt>_proj=THISPROJECT&_telkey=SOMETELKEY</crypt>

which produces

http://somedomain.com/cwx.cgi?_crypt=0648090e3706020808253b346d0370622a45362a172e1a13380e0e123916016c1f322319

Used in an e-mail invitation, for example, CallWeb encodes the value between <crypt></crypt> tags and associates it to the _crypt URL option. This option is decompressed by CallWeb to recover the initial options and values that the encrypted text contains. It is possible to encrypt only a portion of the URL options if there are advantages to doing so.

Questionnaire design

Computed questions

BLANK questions

If the keyword "BLANK" is present on the question name instruction, then

• the question does not display on screen;
• the value of the first answer category is assigned to the question; and,
• eventually, the flow follows the simple skip associated with the first answer category.

A BLANK question can be associated with a display condition to attribute a value to the question conditional on previous answers or to perform complex skips.

Complex skips

A simple skip associated with the first answer category of BLANK questions is honoured. Therefore, BLANK questions can be used to implement complex skips via the display condition, i.e., the complex skip logic is placed in the display condition and the destination of the skip is associated with the first category of the question.

Complex skips can also be implemented via CALCUL questions (see the next paragraph). In this case, a calculation is made, returning a value into the same question (for example; this is not a necessity, as long as there is a value in the CALCUL question to use for skips), and response categories are associated with simple skips. For example, using the contexte system variable, the following code checks whether the current time is before or after noon and redirects the questionnaire flow accordingly:

REDIRECT CALCUL
% Text
REDIRECT = ( $contexte{heure} < 120000 ) ? 1 : 2
% Categories
*1*AM
*2*PM
% Simple skips
1 = ~Q_AM
2 = ~Q_PM
% Display condition
% Open parts
! ===================================================<

CALCUL questions

If the keyword "CALCUL" is present on the question name instruction, CallWeb expects the question text to use the following syntax:

output_variable = perl_expression

This returns the result of the evaluation of "perl_expression" in "output_variable". The "perl_expression" must follow Perl syntax and question names must be prefixed with "$". Please refer to the questionnaire driving Circum Network Inc.'s EchantiCalc script for several examples of use of this feature.

Some special functions can be used in a CALCUL question to perform survey-specific actions. Among them are:

COMPUTE BUTTON feature

It is sometimes useful to perform a mathematical operation right on a page, such as summing a series of numerical answers and displaying the total. This can be accomplished by adding a button on the page; that button performs the operations programmed in a CALCUL question and then redisplays the same page where a recall of values can be performed.

Syntax of the COMPUTE BUTTON:

<COMPUTE BUTTON>CALCUL_QUESTION, text</COMPUTE BUTTON>
or
<BOUTON CALCULE>CALCUL_QUESTION, text</BOUTON CALCULE>

CALCUL_QUESTION is the name of the CALCUL question triggered by the button. The text which follows the CALCUL_QUESTION and a comma is displayed as part of the button. If this text happens to be the name of a (image) file, that image is used to display the button. In this case, a third portion, still delimited by a comma, can contain the ALT text of the image. A fourth portion, still delimited by a comma, can contain the keyword NOTEST to ensure that the button calculation is activated even if the data on the page do not conform to the normal validation tests.

For example, the following code:

Q3 MIN=0 MAX=1
% question
[EN]How many people from each of the following age groups live in your household, including you who have already indicated being over 17?
[FR]Combien de personnes de chacun des groupes d'âges suivants votre ménage compte-t-il en vous incluant et compte tenu que vous avez déjà indiqué être âgé de plus de 17 ans?
% note
[SUFFIX:A][EN]Less than 10 years old[FR]Moins de 10 ans
[SUFFIX:B][EN]From 11 to 17 years old[FR]De 11 à 17 ans
[SUFFIX:C][EN]18 and more[FR]18 ans ou plus
% categories
*1*=*[EN]Number of people[FR]Nombre de personnes
% skips
% condition
% open-end
1 = N2.0 0 10
! ==================================================
Q3D MIN=0 MAX=1
% question
=Q3A
% note
[EN]<COMPUTE BUTTON>CALCQ3,Sum up</COMPUTE BUTTON>[FR]<BOUTON CALCULE>CALCQ3,cw/additionner.gif</BOUTON CALCULE>
% categories
*1*NM*[EN]&&ACALCQ3[FR]&&ACALCQ3
% skips
% condition
% open-end
! ==================================================
CALCQ3 CALCUL
% question
ACALCQ3 = $AQ3A + $AQ3B + $AQ3C
% note
% categories

% skips
% condition
% open-end
1 = N3.0 0 999
! ==================================================

displays this table:

Note: other Web survey packages perform such operations using JavaScript; in keeping with the CallWeb philosophy, no JavaScript is used in programming this feature. Also, the operations triggered by the COMPUTE BUTTON are totally up to the questionnaire designer (e.g., totalling, sum of products, extraction of data, string manipulation) since they are encapsulated in a CALCUL question which may perform any operation and modify any number of fields.

The display condition of the CALCUL question triggered by the button is enforced.

RANDOM questions

RANDT is now deprecated. Please use the random_integer function described above.

If the keyword "RANDOM" is present on the question name instruction, CallWeb expects the rest of the question to use one of the following syntaxes:

RANDT(number,output_variable)
RANDT(input_variable,output_variable)

The RANDT function returns, in "output_variable", a random integer between 1 and either NUMBER or the value of the variable named "input_variable".

Questionnaire design

Commenting a script

It is often useful to add comments in CallWeb scripts to provide explanations of what the designer is trying to accomplish. The feat may not be so obvious to another questionnaire designer who may be called upon to modify one's script.

There are two classes of comments in a CallWeb script:

• comments that are deleted during compilation; these are all the script lines that start with at least two pound signs (that can be preceded by one or more blank spaces or tabs);
• comments that are saved during compilation and that are printed on questionnaire printouts produced by the cwquestionnaire module; these comments are located at the end of a script line, passed a space and two pound signs, They are associated with the segment of the question where they are located and they are printed accordingly by cwquestionnaire.cgi.

Here are the legitimate locations of printing comments:

Q3A ## Question name comment
% question ## Question segment comment

[EN]How many people from each of the following age groups live in your household, including you who have already indicated being over 17?
[FR]Combien de personnes de chacun des groupes d'âges suivants votre ménage compte-t-il en vous incluant et compte tenu que vous avez déjà indiqué être âgé de plus de 17 ans?
% note ## Note segment comment

[EN]Less than 10 years old[FR]Moins de 10 ans
% categories ## Category segment comment

*1*=*[EN]Number of people[FR]Nombre de personnes ## Specific category comment
% skips

1 = Q99 ## Specific skip comment
% condition

Q1.EQ.1 ## Display condition segment comment
% open-end

1 = N2.0 0 10 ## Specific open-part comment
! ==================================================

Note that printing comments are not compabible with cwedit.cgi and with the copy syntax which uses the equal sign (=).

Questionnaire structure

Introduction

The basic CallWeb questionnaire contains a series of instructions defining questions and variables. Another set of commands is available to affect questionnaire structure. All of these instructions are located within the questionnaire file and identified with a pound sign ("#") as the first character of the line. Each of these instructions must fit on a single line in the questionnaire file.

Questionnaire structure

Pages

By default, CallWeb displays one question per browser screen. The # GROUP instruction changes this default behaviour. It uses the following syntax:

# Group NAME = VAR1 - VAR2

where

• NAME is the name of the page; any unique alphanumeric string is acceptable;
• VAR1 is the first variable to include on the browser page;
• VAR2 is the last variable to include on the browser page; obviously VAR2 must come after VAR1 in the questionnaire order.

Limitations: note that skips cannot take place within a page and that simple skips are honoured only on the last question displayed on the page. Also, BLANK questions and CALCUL questions do not perform their feat within pages; these types of questions should be located between defined pages if necessary — in fact, their inclusion in a page is flagged as an error by the compiler.

Questionnaire structure

Tables

By default, CallWeb displays each question sequentially. The # TABLE instruction changes this default behaviour. When a series of variables belong to a matrix:

• the question text of the first variable is displayed;
• the note field of each question labels each row, and;
• the answer categories of the first question determine the columns labels and their order.

The syntax of the "# TABLE" instruction is:

# TABLE NAME = VAR1 - VAR2 HEADER=n PIXELS=n COLVARS=n POSITION=x FORCE_CODES TRANSPOSE SPECIAL=(n,...) CORNER=(...) VALIDATION

where

• NAME is the name of the matrix; any unique alphanumeric string is acceptable;
• VAR1 is the first variable to include in the table;
• VAR2 is the last variable to include in the table; obviously VAR2 must come after VAR1 in the questionnaire order; (the next arguments are all optional and their study should be reserved to more advanced users)
• HEADER=n is the frequency at which the column headings are repeated within the table, expressed in number of questions (-1 means no repetition); it can also be called using ENTETE=n
• PIXELS=n is the number of pixels the browser should attempt to give to each response column (-1 lets the browser figure out the layout);
• COLVARS=n is the number of variables to stack in the columns;
  • the default is -1 which means that the columns of a table are defined by the first variable in the table set (it can also be called using the VARSCOL=n name)
  • a value of 1 has a similar meaning except it directs the system to place the text of the first question within the matrix, above and across the answer categories
  • a value greater than 1 means that the matrix displays that number of variables across the columns of the matrix — obviously, the number of variables in the matrix must be a multiple of the number of columns used across the columns; the system displays the first COLVARS columns across the first row of the matrix, then the second set of COLVARS columns across the second row, and so on; in the questionnaire .scw file, the variables must be ordered according to the sequence of use in the matrix, i.e., from left to right and from top to bottom (i.e., if the matrix comprises 8 questions (Q1-Q8) and is defined as using two variables across the columns, Q1 and Q2 are displayed in that order on the first row, then Q3 and Q4 on the second row, etc.)
• POSITION=x determines the position of the table on the page: "LEFT" or "GAUCHE" puts the table on the left margin; "RIGHT" or "DROITE" does the same on the right margin; "CENTER" or "CENTRE" centres the table horizontally on the page. The default value is LEFT.
• FORCE_CODES is a keyword which forces the variables in the matrix to use their own response codes (whereas, without it, every variable in the matrix uses the codes of the first-row variable for their column order); this cannot be used along with permutated response codes; for example, this can be used to display a drop-down list of provinces and territories in a table that otherwise contains single boxes of text;
• TRANSPOSE reverses the presentation of rows and columns. By default, CallWeb displays the response categories as columns and the questions as rows such that one (or more) selection is expected on each row; with TRANSPOSE, the questions are arrayed as columns and the response codes make up the rows such that one (or more) response is expected for each column. For example, parent educational achievement could be requested with each of the mother and the father occupying one column of the matrix;
• SPECIAL is an instruction which identifies the response codes that are to be coloured differently from the normal table colour; the normal colour is driven by the # M_COULEURCELLULES instruction while the SPECIAL codes are painted with the # M_COULEURSPECIALE instruction; the column header cell, which is normally coloured by the # M_COULEURTITRESCOLONNES instruction, also bears the special colour for the selected codes. All vertical variables of the table share these special codes such that, if code 9 is to be special-coloured, all codes 9, in all vertical variables, are coloured as such; also refer to the "S" answer category behaviour code;
• CORNER is text within parentheses that appears in the upper left hand side corner of the matrix; language codes in the form of [xx] may be embedded within this text; if the text includes parentheses, insert them as &# codes where an open parenthesis is the code &#40; and a closed parenthesis is the code &#41;
• VALIDATION is a special validation instruction for the matrix as a whole; validation instructions include:
• EXCLUSIF(min,max,A)
  this validation instruction demands that the respondent provides only one answer per column of the table; the system accepts a minimum of MIN answers between the values of 1 and MAX; if the "A" argument is provided, the test is performed on the open end parts of the questions in the matrix; otherwise it is performed on the normal questions.
• ORDRE(min,max,A)
  this validation instruction places demands on the respondent similar to EXCLUSIF except the answers are interpreted as an order of preference; therefore, the set of answers must include, at a minimum, all values between 1 and the MIN argument out of a maximum of MAX answers.

Important note: by definition, tables are displayed within pages; therefore, the questions making up the matrix must also be part of a (and the same) page defined with a # GROUP instruction.

The following statements show an example which incorporates all of the circumstances described in this section:

# Group Alpha = Q1-Q10
# Table Beta = Q2-Q8
# Permutation Gamma = Q3-Q7

Questionnaire structure

Permutation of questions

By default, CallWeb displays the questions in the order in which they are defined in the questionnaire. This default order can be affected by simple skips and complex skips. It can also be randomised via the permutation of questions.

CallWeb uses the # PERMUTATION instruction to define sets of consecutive questions which are to be displayed in random order. The syntax follows:

# Permutation NAME = VAR1 - VAR2 STEP=step LIMIT=limit LIKE=permutation

where

• NAME is the name of the permutation; any unique alphanumeric string is acceptable;
• VAR1 is the first variable to include on the permutation set;
• VAR2 is the last variable to include on the permutation set; obviously VAR2 must come after VAR1 in the questionnaire order;
• STEP is the number of variables in each block to be permutated (default = 1; can also be named PAS).
• LIMIT is the number of blocks of variables (blocks are defined by the STEP parameter) to display (default = all; can also be named LIMITE).
• LIKE (COMME in French) is the name of another permutation that will drive the order of the current permutation (default, none).

In the following example,

# Permutation 1 = Q5-Q10 STEP=2

Q6 always comes right after Q5, as will Q8 after Q7 and Q10 after Q9. However, the three pairs are offered in random order to respondents as in:

Q7-Q8, Q5-Q6, Q9-Q10
or
Q9-Q10, Q7-Q8, Q5-Q6

In the following example,

# Permutation 1 = Q5-Q10 STEP=1 LIMIT=2

Only two randomly selected questions in the series from Q5 to Q10 are displayed, in random order.

In the following example,

# Permutation 1 = Q5-Q14 STEP=2 LIMIT=2

Only two randomly selected blocks of two questions in the series from Q5 to Q14 are displayed. They could be Q7-Q8 and Q11-Q12, for example.

Display conditions affect which variables are displayed throughout the questionnaire, including in permutations.

Parallel permutations

Sometimes, the order of a second set of questions must be the same as the random order of a first set of permutated questions. This is achieved by adding the LIKE= parameter to the second permutation definition followed by the name of the first permutation. For example:

# Permutation P1 = Q5-Q14 STEP=2 LIMIT=2
# Permutation P2 = Q15-Q24 LIKE=P1

Permutation P2 will always be presented in the same order as permutation P1. Note that the LIKE parameters do not supercede the STEP and LIMIT parameters. The number of items in the two permutations must be the same. Different display conditions may apply and modulate the number of items displayed in a given questionnaire but the order of those displayed will be the same.

Permutation within permutation: embedding permutations at any depth

All of the features described above can be implemented in permutations that are performed within permutated blocks. For example, in the following definitions:

# Permutation E001 = Q1-Q15 STEP=5
# Permutation I002 = Q1-Q5
# Permutation I003 = Q11-Q12

• one exterior permutation E001 entails three blocks of 5 questions which will appear in random order (e.g., sometimes Q1-Q5, then Q11-Q15, then Q6-Q10)
• one interior permutation I002 presents Q1 to Q5 in random order;
• another interior permutation I003 makes Q11 and Q12 appear in random order (e.g., an interior permutation does not need to use an entire block of the exterior permutation).

The questions of a permutation cannot overlap between blocks of the exterior permutation. Also, a permutation cannot include questions that are part of an exterior permutation and other questions that are not.

Note: permutation imbedding works only if the names of the permutations are chosen such that, in each case, the exterior permutation comes before the interior permutation, in alphabetical order of permutation names.

Such imbedding of permutations can be done at any depth level (e.g., permutations within permutations within permutations within ...).

Questionnaire structure

Hierarchical projects

Typically, all data for a project are maintained within a single CallWeb data base. There are times, however, when a more complex structure is more appropriate. Let's take the example of a study on family employment. Part of the questionnaire may deal with the household; another part may request information from each household member. Of course, it is possible to set up a large enough number of blocks of questions to accommodate the largest possible household, but this may not be the most efficient way to collect the information. That's where hierarchical projects come into play.

In hierarchical projects, a master CallWeb project acts as the parent data base (in our example, it would deal with the household). One or more "children" CallWeb projects link into the master project to allow as many children "relations" as is required. In our example, each household member would be a child of the master household project. Each such child relation requires a separate CallWeb project; there can be any number of such relationships within a project and children projects may have children projects of their own. For example, one household could have several household members and each household member could have several jobs.

Syntax

Hierarchical projects are defined using RELATION-type questions.

• In a RELATION question, the minimum and maximum number of answers refer to the number of child records. Setting the minimum and maximum to 1 and 3 will ensure that the respondent enters at least 1 child and no more than 3. The default values are 0 and 9999 respectively.
• The number of child records is stored in the RELATION question upon moving to the next page.
• A RELATION question has no text of its own; therefore, it would normally be inserted in a multi-variable screen which would provide context and explanations. Note that a RELATION question cannot co-exist on the same page with other questions collecting answers; the reason for this is that the add and modify relation buttons open a new questionnaire without first saving the information in the current page of the parent questionnaire.
• The question text segment of the question is used to pass along the RELATIONship parameters using the following syntax (where commas and slashes count!):

Useful pointers

• Use an open-end part (e.g., APARENTCODE) to store the many characters of parent_telkey_varname_in_child_project.
• Variables copied from the parent to the child (parent_telkey_varname_in_child_project and copy_into_children) should probably bear a STOCK type so that they are not displayed.
• In the child project, variables copied from the parent must be listed in a # Attributable questions instruction so that the child project accepts the values.
• There are default text values for the buttons to add, modify or delete a child as well as to refresh the page displayed. These text values can be customized for a project using a series of pound instructions prefixed with # Text relation.
• For technical reasons, the "refresh" button of RELATION questions is NOT compatible with the DEMO mode. The same can be accomplished in DEMO mode by backtracking to the question prior to the RELATION question and going forward again.
• Recalling a RELATION question as &@QUESTION inserts the number of children in the recall location. Recalling as &QUESTION inserts a complete table of the children.
• The child project must include a "# URL" instruction pointing back to the parent questionnaire. The URL link should use a syntax like this one:
  # URL = callweb.cgi?_proj=PARENT_NAME&_lang=EN&_telkey={$APARENT_TELKEY}&_debute=RELATION_QUESTION
  where PARENT_NAME is the name of the parent project, APARENT_TELKEY is the name of the child variable containing the parent telkey (parent_telkey_varname_in_child_project, above) and RELATION_QUESTION is the name of the RELATION question in the parent project.

Respondent user interface

When reaching the RELATION question, the respondent is shown an "Add" button and a "Refresh" button. Upon clicking the Add button, the system continues with a new child questionnaire; once that child questionnaire is completed, the system redisplays the parent questionnaire with a table describing the existing child or children. In this table, a link allows the respondent to correct one of the children or to delete it. The table also displays information from each child using the question text and the text of the answer categories from the child project. Alternative text for questions text and answer categories can be defined in the appropriate segments of the child questionnaire by putting this alternative text between <parent></parent> tags. For example,

*1*This is the text for category 1 <parent>Category 1</parent>

would display "This is the text for category 1" within the child questionnaire but "Category 1" in the summary table in the parent questionnaire.

Extracting data from child records

Child data are stored in a separate CallWeb project. Nonetheless, it is possible to extract information from the child data during the completion of the questionnaire and use it in the parent project.

The &apropos_relations function can be used in CALCUL questions to perform extractions. The general syntax of this function is as follows:

DESTINATION = &apropos_relations("RELATION_QUESTION","DATA_TYPE","OPTIONAL_PARAMETER")

The following table details the existing data types that can be produced and their associated parameters.

Questionnaire structure

Interruption

A button to offer respondents the ability to interrupt the questionnaire may be added on every page of the questionnaire by activating the # Bouton stop instruction. By default, # BOUTON STOP is deactivated as in:

# Bouton stop = non

To display the Interruption button, set the instruction to "oui" and add the question where the respondent will be directed upon interruption after a comma, as in:

# Bouton stop = oui, Q99

This instruction will force the display of an Interruption button on each page of the questionnaire. If the respondent clicks that button, they will be directed to question Q99 but, upon coming back into the questionnaire later, they will resume from the page attained before requesting the interruption.

The STOP button can also be displayed conditionally based on a display condition placed in lieu of the Yes first argument, in square brackets. For example:

# Bouton stop = [QTYPE.EQ.1], Q99

will display the STOP button only if QTYPE equals 1.

What happens on the page where the interruption is directed is up to the CallWeb script designer. It could be a page without buttons (BACKWALL, CULDESAC and NOSTOP) displaying some message or the URL needed to return into the questionnaire. It could be calculated questions that send an e-mail to the respondent with instructions. It could be anything CallWeb can do with its set of features and questions.

The text of the Interruption button is controlled by the # TEXTE STOP instruction. Each language of the questionnaire may have its own such instruction as in:

# Texte stop = [EN]Stop[FR]Arrêt

The interruption button can also be an image. See the # IMAGE STOP instruction.

Although a STOP block of questions is often used to allow stopping of a questionnaire at one point and resuming from where the interruption block was invoked, it can also be used to branch to a special set of questions from anywhere in the questionnaire and then to go back to the normal flow of questions afterwards. To perform this feat, add a # Stop button instruction, branch to an isolated part of the questionnaire and end this block of questions with a question qith a DESTOP type. The DESTOP question branches back to the question from which the STOP button was invoked.

Questionnaire appearance

Introduction

The appearance of the questionnaire is controlled by three sources of information: a cascading style sheet, various pound sign instructions and some in-questionnaire parameters.

Questionnaire appearance

Page structure and templates

In its simplest form, the CallWeb page (see the example on this page) is a vertical construction that includes the following pieces:

• a header, controlled by the # Header instruction
• an optional horizontal series of buttons, controlled by the # Button order top instruction
• the body of the page, that contains the questions
• an horizontal series of buttons, controlled by the # Button order bottom instruction
• a footer, controlled by the # Footer instruction

This linear structure and the related pound instructions allow for the creation of a wide variety of questionnaire looks and for the creation of custom pages. While remaining simple, this structure is constraining: it can only be vertically oriented and the integration of visual elements from other sites like corporate Web sites is arduous and limited. The # Template instruction shatters these constraints imposed by the vertical construction of the questionnaire.

Template-controlled page structure

The # Template instruction offers a second page composition method. It identifies an HTML file from which the questionnaire page is built. For example, the HTML file could be a copy of a typical Web page from an organisation or templates of the Government of Canada Common Look and Feel Standards for the Internet standard. In that HTML page, the CallWeb designer places markers that CallWeb substitutes for portions of questionnaire pages. The existing markers are as follows:

These markers can be placed anywhere in the HTML template page. This could allow, for example, to have a Previous page button on the left side of the page and a Next page button on the right side. None of the markers is mandatory and all can be repeated (e.g., there can be several &*BUTTONSH:...)

Technical note: the template page must be built taking into account that the questionnaire is produced from the root directory of the CallWeb instance. Therefore, links to objects (e.g., images, styles, hyperlinks) must be relative to the root directory (which is most flexible) or must be absolute (which is simplest).

Questionnaire appearance

Text formatting

CallWeb expects to find a cascading style sheet (CSS) called "style.css" in the directory of the questionnaire file; otherwise, it looks for it in the resources directory (usually gr/) and finally in the current directory (the CallWeb root installation directory in the case of the callweb module or the source utility directory for utilities). The # Stylesheet instruction can also be used to name a stylesheet file for a particular project.

To obtain the official CallWeb look, place this stylesheet in the gr/ directory and the folloing instructions in the etc/usager.conf file:

_M_COULEURTITRESCOLONNES = #4578A6
_M_COULEURCELLULES2 = #D5EBFF
_M_COULEURCELLULES = #E8F4FF
_M_COULEURBORDURES = #A8B4BF

The explanation of the syntax of CSS is beyond this manual; several good references exist, as well as several Web sites. (http://www.w3.org/TR/REC-CSS1 is a key reference.) The CSS must define some specific styles and it may contain additional ones.

CallWeb styles (note that capitalization of the style name counts in certain browsers and that CallWeb uses all-uppercase style names):

• .QUESTION
  used to format the question text;
• .REPONSE
  used to format the text of answer categories in normal format;
• .AUTOSUBMIT
  used to format the text of answer categories subjected to # Auto submit; the following style is particularly useful:
  .AUTOSUBMIT { padding-right: 20px; background: transparent url(../gr/autosubmit.gif) no-repeat center right; }
• .NOTE
  used to format the text of notes;
• .COLONNE
  used to format the text of answer categories in matrix format;
• .LIGNE
  used to format the text of item in matrix format;
• .SUBSTITUT
  used to format the text which is recalled from previous data, in question text, note and answer categories;
• .THERMOMETRE
  used to format the text of the thermometer text;
• .MATRICE, .MATRICE2, .MATRICE3
  attributed to all question tables (displaying questions as rows and answer categories as columns); useful to locate the tables horizontally;
• .CATEGORYTABLE
  attributed to HTML tables which structure the answer categories;
• .BOUTONS
  attributed to the button table; useful to locate the buttons horizontally;
• .ERREUR
  used to format error messages;
• .H5
  used to format a few headings;
• .EQUIVALENTH5
  used to format utility headers;
• .EQUIVALENTH6
  used to display question names under some circumstances;
• .NEPASLIRE
  used to format response categories using the P behaviour code;
• .LIRE
  used to format response categories using the L behaviour code;
• .SPECIAL
  used to format response categories using the S behaviour code.
• .BUTTON
  used to format buttons such as the Next Page or Previous Page buttons.
• .DROPDOWN
  used to format dropdown lists.
• .NUMBOX
  used to format numeric open-end boxes.
• .TEXTBOX
  used to format single-line and multi-line text boxes (open-end parts).
• .CATI_APP_BUTTON_O
  used to format CATI appointment buttons with a mandatory comment.
• .CATI_APP_BUTTON_F
  used to format CATI appointment buttons with an optional comment.
• .CATI_APP_BUTTON_A
  used to format CATI appointment buttons without comment.
• .CATI_OTH_BUTTON_O
  used to format CATI result buttons other than appointments with a mandatory comment.
• .CATI_OTH_BUTTON_F
  used to format CATI result buttons other than appointments with an optional comment.
• .CATI_OTH_BUTTON_A
  used to format CATI result buttons other than appointments without comment.
• .CATI_QUE_BUTTON
  used to format the CATI button that opens the questionnaire.
• .CATI_TEL_BUTTON
  used to format the CATI buttons that change the telephone number.
• .CATI_ACT_BUTTON
  used to format the CATI buttons associated with actions (new number, search, finish).
• .PERMBUTTON
  used to format submit buttons in administrative forms.
• .SELECTION
  used to format the selection statements in cwfreq.
• .QLIGNE
  used to format the text of the question defining the lines of a table in cwfreq.
• .QCOLONNE
  used to format the text of the question defining the columns of a table in cwfreq.

Styles which should be defined:

• BODY
  sets the background, the default font and the page margins for the entire questionnaire. (With regard to text formatting, we prefer to set all of the basic HTML tags so that all browsers behave correctly. The main ones, for CallWeb use, are P, TABLE, TR and TD.)

Other styles:

• Any other style may be defined and used in question text, note and answer category text via the SPAN HTML syntax: <SPAN CLASS=style>texte</SPAN>

Questionnaire appearance

Colours and layout

A number of pound instructions control the formatting of several aspects of the questionnaire appearance. Another page of this documentation identifies which aspects of the page are controlled by CSS styles.

All tabular outputs (tables and MEMO questions within questionnaires but also parameter tables in utilities, record dumps in cwNav, two-way crosstabs in cwFreq, etc.) are produced by the same protocol. This protocol uses the pound instructions stored within the questionnaire to format tabular outputs. If the questionnaire script does not contain specific instructions for a particular aspect of the tabular output, CallWeb uses the specific installation defaults stored in the instance configuration directory. If instructions are not found there, defaults apply.

Advanced colours and layout

It is possible to control the formatting of question tables in a finer way by using a CSS style sheet. To access this advanced mode, first activate it with the following pound instruction:

# Styles for tables = yes

With this mode activated, the format of table cells is controlled by a collection of style sheets rather than by the pound instructions listed above. The following image documents which style controls which cell. The lines of style definition under the image indicate the statements used in the style.css file (note that all style names are in uppercase letters).

 .ORDINARY_CELL_A, .ORDINARY_CELL_A0, .ORDINARY_CELL_A1 { background: #E4EDF9; }
 .ORDINARY_CELL_A2 { background: #F9FAFF; }
 .ORDINARY_CELL_B, .ORDINARY_CELL_B0, .ORDINARY_CELL_B1 { background: #FFFFFF; }
 .ORDINARY_CELL_B2 { background: #CCCCCC; }
 .SPECIAL_COLUMN0 { background: #FFFFFF; }
 .SPECIAL_COLUMN1 { background: #FFFF66; }
 .SPECIAL_COLUMN2 { background: #CCFF00; }
 .SPECIAL_LINE_A0 { background: #FFFFFF; }
 .SPECIAL_LINE_B0 { background: #CCCCCC; }
 .SPECIAL_CELL1 { background: #FFFFCC; }
 .SPECIAL_CELL2 { background: #CCFF99; }
 

Here is how this works:

• first, note that the table is broken down into three vertical sections (because there are two questions side by side; it would be two if there was only one question and four if there were three questions, etc,):
• the first vertical section is the column of row labels; note that all styles in that column end with a "0";
• the second vertical section corresponds to the first question; all of its styles end with "1";
• the third vertical section is where the second question is located; all of its styles end with "2";
• if there were more vertical questions, the numbering of the styles would ensue.
• second, note that, in the body of the table, the colours of lines alternate for odd-numbered and even-numbered lines; styles corresponding to odd-numbered lines have an "A" as the second last character while the syles for even-numbered lines have a "B" in the same position;
• there are 4 style name prefixes:
• SPECIAL_COLUMN (which becomes SPECIAL_COLUMN0, SPECIAL_COLUMN1 and SPECIAL_COLUMN2 for the various vertical sections) controls the column headers;
• SPECIAL_LINE_ (which becomes SPECIAL_LINE_A0 for the odd-numbered lines in section 0, etc.) controls the line headers;
• SPECIAL_CELL (which becomes SPECIAL_CELL0 and SPECIAL_CELL1 for the various vertical sections) controls the cells belonging to columns defined as "special" using a answer category behaviour code or the table definition pound instruction;
• ORDINARY_CELL_ (which becomes ORDINARY_CELL_A1, ORDINARY_CELL_B1, ORDINARY_CELL_A2 and ORDINARY_CELL_B2 for the odd- and even- numbered lines in sections 1 and 2, etc.) controls the cells in the body of the table.
• if this advanced mode is used in a project, it also affects the presentation of tables in utility programs. Therefore, it is a good idea to define the following styles (which are not used in question tables but are in other contexts): ORDINARY_CELL_A, .ORDINARY_CELL_A0, .ORDINARY_CELL_B, .ORDINARY_CELL_B0.

Questionnaire appearance

Particular cases: in-questionnaire formatting

Open-end box size

It was earlier stated that the syntax to define an alphanumeric open-end part was

Cwidth

In fact, two other arguments may be used, as follows:

Cwidth LINES COLUMNS

• LINES is the number of lines of the textbox;
• COLUMNS is the number of columns of the textbox.

HTML coding

In the question text, the question note and in the text of answer categories, as well as other questionnaire pound instructions such as # ENTETE and # PIED, it is possible to include standard HTML code. This way, HTML tables can be drawn to line up parts of text, hyperlinks can be inserted, images can be displayed, etc.

Questionnaire appearance

Final products

Here are examples of appearences that CallWeb pages may take. Of course, this is by no means an exhaustive set.

Field management

Introduction

The management of a CallWeb field project encompasses a series of operations which are depicted in the next exhibit, along with the tool which is reserved for each step. It is assumed that text editing (we really like TextPad) and FTP transfers are mastered by the project manager (even though the cwdocs module can now be used to transfert files).

The rest of this section describes the five stages of a field project: the initiation of the project, modifications during data collection, case management of data, real-time table production and data extraction.

Field management

Permission management

All administrative accesses to CallWeb are controlled by a set of permissions that are based on modules and projects. Access to questionnaires by respondents and access to CATI interviewer modules are NOT subject to this permission scheme.

If no permissions are defined (such as upon initial use of the system), the site manager must access the cwperm.cgi module in the utility directory and define a super-user (see definition below). This super-user can then define additional users according to site needs.

Key concepts

There are two kinds of users: super-users and regular users. Super-users have access to anything and are the only ones who can use cwperm.cgi to create users and set permissions. Regular users can only perform the tasks that they are allowed according to the permissions set for them by the super-user.

There are six types of permissions, as follows:

• All modules, all projects: a regular user can be given access to all modules and all projects. This is equivalent to the super-user permissions with the exception that that regular user cannot access cwperm.cgi to create users and set permissions;
• All modules, one project (or more): a user can be given access to all modules for a specific project (or more than one);
• All projects, one module (or more): a user can be given access to all projects from a particular module (or more than one);
• One (or more) projects, one (or more) module: a user can be given piecemeal access to combinations of particular projects and particular modules; this is the finest level of permission control. It can be used, for example, to grant a client access to frequency tables in their project;
• Generic # Accessible by module permissions: a user can be given access to a selection of modules for projects where they are named in the # Accessible by pound instruction; these permissions have no effect outside such projects.
• Permissions that are dynamically borrowed from other users: a user can be associated to other users from which it borrows their permissions in real time. These users can themselves borrow permissions from other users (in a cascade).

Users are temporarily locked out of the system if they accumulate three incorrect accesses within a two minute period.

Permission management functions

Once a super-user accesses cwperm.cgi (either directly or via the integrated module), they get a menu similar to the one depicted here. The following functions are available to them:

• Display the list of users
  This simply lists all user names, for reference.
• Create a user
  A new user is given a name and a type (super-user or regular user). The user type cannot be changed later on.
• Change a user's password
  Any user can be given a new password, which needs to be confirmed.
• Add/modify a user's permissions
  After selecting a user whose permissions are to be modified, a (rather daunting) interface is displayed that allows the super-user to identify which permissions that user shall possess. Each available module is displayed in columns, in addition to a column for all modules. Each project is presented in rows, in addition to a row for all projects and a row for projects identifying the user in # Accessible by. Permissions can be redundant (e.g., a permission for all projects on cwfreq.cgi and a permission on one particular project on the same module). The most liberal interpretation of permissions is made later on.
  A box labelled "Permission level" accepts positive integers; it is not yet in use.
• Copy permissions from one user to one or more
  Permissions can be copied from one user to one or more other users. A useful strategy using this feature would be to create a fake user that bears the permissions for a group of users and then to copy permissions from this fake user to all users in the group. Permission copying can be dynamic (and change in real time with changes to the permissions of the source users), additive (the permissions of the source user are added to the existing permissions of the destination user without touching existing permissions of the destination user) or can entirely replace the existing permissions of the destination user.
• Delete a user
  Users can be deleted entirely form the permission system, one at a time.
• Log out
  This option interrupts the activity of the super-user in cwperm.cgi.

User management strategies

More to come.

Field management

Integrated module

A module called cw, located in the utilities directory, provides a front-end for every CallWeb module available in the said directory (as well as the callweb.cgi module located one level up in the directory structure.

It is highly advisable to use this module to access all of the other CallWeb programs as the required and optional parameters are displayed on screen (no typing, no risk of forgetting arguments).

Utilities located in the main utilities directory (defined in the installation file) have access to all CallWeb projects. To create an instance of a utility program that has access to a limited number of projects, follow the procedure explained in the CallWeb cookbook.

Field management

Initiation of a project

Required pound statements

In addition to the definition of questions, a CallWeb questionnaire script must include the following three pound statements:

• # Available languages = LA,LA,LA,...
  This statement lists the languages that are defined in the questionnaire, using 2-letter ISO codes (EN for English, FR for French, ES for Spanish); CallWeb reports every instance of missing text segments based on this list.
• # Default language = LA
  This statement identifies the language which is displayed by default if no language is stated upon calling a CallWeb tool; it uses a 2-letter ISO code.
• # Survey type = (one of the following codes)
  This statement determines the type of data collection.
• Open = fully open, no provision of an access code (was 1)
• Closed = controlled access; the data base must be prepopulated (was 2)
• Open Combination = fully open; a user id and a password are selected by the participant (was 3)
• Open Offered = fully open, provision of an access code for resuming (was 5)
• Password = controlled access; the data base must be prepopulated; the _password field contains the changeable password (was 7). A cookbook recipe describes this system in detail.

Physical installation of the questionnaire script file

The physical installation of a CallWeb project requires that the questionnaire script file:

• bears a .scw extension (lower case); CallWeb considers all .scw files as questionnaires;
• be located on a Web server in a directory whose name starts with "cw" and be located one level under the directory where the callweb program is located (the directory must be owned by the user under which the Apache server runs or offer read-write-execute permissions to the world — check with your system administrator);
• be accompanied by a file named "style.css", in the same directory as the questionnaire script file; this cascading style sheet file controls certain aspects of the formatting of the questionnaire; all projects in a directory share the style.css file; projects located in different directories prefixed with "cw" can use different style.css files.

Each CallWeb project creates the following files:

• project.qcw
  a compiled version of the questionnaire for fast access.
• especially named MySQL database
  the data base of answers provided; it may contain a series of empty records if it was prepopulated with data by the project manager prior to initiating the field work.

Questionnaire compilation

Once a questionnaire is sufficiently complete (still subject to tests and modifications) and uploaded to the Web server, the cw script is used to activate various functions.

Compilation requires the script name. Six options are available:

• Structural change
  This box must be selected if the project data structure changes with the new script; data structure changes are:
• the addition/deletion of a question
• the addition/deletion of an open-end part
• the transformation of a single-answer question into a multiple-answer question or vice versa
• moving questions in the questionnaire
• Details
  This checkbox activates the display of detailed compilation messages.
• Test
  The "test" checkbox may be selected to request a test compilation without changes to the existing compiled questionnaire or to the existing response data base.
• Beautify scw
  With this box checked, the system produces a new version of the .scw file with "percent" lines labelled and indentation inserted to facilitate reading.
• History
  Displays the compilation history for the project.
• Copy
  Initiates the copy of the .qcw file to another server.

The compilation produces a wealth of information which should be studied carefully. Compilation errors are highlighted using the .ERREUR style found in the style.css file and located at the top of the compilation report.

If compilation errors are found, no change is made to the compiled questionnaire or to the response data base.

Compilation may also produce "warnings". Warning messages are elements of information of particular interest that are not errors per se but that could potentially be considered problematic. They include:

• leaving a project without access control;
• two instances of the same pound instruction;
• the presence of a &# recall instruction without a corresponding # RECALL pound instruction;
• returning the result of a CALCUL in a non-existent question.

Questionnaire comparison

cwCompare can be used to help identify the structural differences between two versions of the same questionnaire. Both versions must be compiled and reside on the same server. cwCompare does not compare the text of the questionnaire — only the structural components (skips, question types, etc.).

Data prepopulation

Once the questionnaire has compiled without error, data may be forced into the data base. This is called prepopulating the data base. This must be used to create access codes in fully controlled data collections. Prepopulation can also be used to insert information about people who will complete the questionnaire, in a controlled-access context; these data can then be used in the course of the data collection.

Prepopulation can be done on an empty CallWeb data base or cases may be added to an existing data base.

Prepopulation data are supplied in a file with the following characteristics:

• the file name must bear an extension starting with a "t", such as "prepop.tab";
• ANSI file;
• one record per case;
• fields are tab-delimited;
• the first line of the file lists the variables in the prepopulation file according to the question name in the questionnaire script; names are tab-delimited; fields using names that are not used in the questionnaire script are ignored;
• the case identification code (called _telkey in CallWeb) must be present in the prepopulation file; it may contain letters, numbers and the underscore character — any other character is stripped out from the imported value as well as from the value supplied to start the questionnaire (such that, say, a telephone number with parentheses and dashes could be supplied as an identification code and it would survive the deletion of inadmissible characters);
• it is possible to add comments to the prepop file by starting them with a comment string (##).

This file must be uploaded to the Web server and located in the same directory as the questionnaire script file for the project.

To assure the preservation of prepopulated data in all circumstances (include case reinitialization), use the NEVERUPDATE keyword on the question name line of the questions in which data are imported.

In the cw integrated interface, cwprepop can be called by selecting the project name and the name of the tab-delimited data file from drop-down lists.

The cwprepop module can also be used to add data into existing cases (or replace existing data) if the "replace variables" button is selected instead of the "add cases" button in the cw interface. In this context, a value of "--" does not replace the pre-existing value.

Generation of random test data

Once the questionnaire has compiled without error, test data can be randomly generated to verify that the logical conditions of the script work as expected. The script cwgen performs this function. It can be used in two manners:

• if the project data base is empty (no data was pre-populated or created via questionnaires), cwgen (called from the integrated module cw) accepts, as argument, the number of questionnaires to create;
• if the project data base is not empty, cwgen requests confirmation of the operation using the destruction keyword and proceeds to re-generate all questionnaires in the data base while respecting pre-populated data.

Each question in the questionnaire is scanned for each case and a random answer is selected for close-ended questions and for open-end parts. Skips, calculations, no-answer questions, etc. are honoured; matrix texts and Test pound instructions are not — and a list of these oversights is produced upon completing the random generation of data.

CallWeb aborts the random generation process if it reaches what appears to be an infinite loop.

Field management

File management

The CallWeb cwdocs module allows you to manage your project files on the server without the need for a separate FTP or SFTP program. Like all other CallWeb modules, cwdocs is entirely Web-based and requires no local installation.

With this module, users can create, delete, copy, rename and move directories. They can also upload, download, delete, copy, rename and move files. (To come: deleting to a trashcan.)

This module was written with security in mind. Users are jailed within the CallWeb instance; if cwdocs is called from a directory other than the master utility directory, users are jailed in that directory. They see only files that are reasonably managed in a Web application. They cannot change file or directory permissions.

cwdocs can only modify or delete directories and files that are accessible to the user under which the Web server runs. Therefore, it is possible that users of cwdocs will not be able, for example, to delete files or directories that were created by other Linux users. That's the cost of security.

When a user creates a directory off the root of the CallWeb instance, access to that directory is added to that user's permissions. However, that access permission is not deleted if the directory is erased. It would be deleted if a super-user re-saved the user's permissions in the permission module.

Access to cwdocs will be from a new icon placed in the upper right-hand side corner of the integrated module interface.

Field management

Quota management

CallWeb supports completion quotas based on single-character stratification (e.g., gender) and multiple-character stratification (e.g., gender within age groups) as well as compound stratification (e.g., a set of quotas on gender and a set on age groups). Membership to a stratum can be based on pre-populated data as well as on data collected in the questionnaire itself and on a combination of such. Quota targets can be modified at any time during the data collection period. Once a quota is filled, respondents from that stratum are redirected within the questionnaire, for total control over the handling of the situation.

Strata and quotas are defined in a special type of question: the QUOTA type. A question is a QUOTA question if the keyword "QUOTA" is present on the question name instruction. The syntax of the question text is as follows (in this syntax, quotas, commas and equal signs are significant):

Q1 QUOTA
% Question text
complete = name of the variable indicating a complete case,
skip = name of the variable where to skip when a quota is filled,
value = quota, value = quota, ...

The ingredients of the definition of quotas are as follows:

• complete = name of the variable indicating a complete case,
  The question named as "complete" is used to determine whether a case has been completed for the purposes of quota calculation; any value greater than zero in the Complete question indicates a complete questionnaire. As long as the value of the Complete question is unassigned or equal or less than zero, the case is not used in totalling the number of questionnaires completed within the quota. This variable may be a question located late in the questionnaire or a value calculated specifically for this purpose. If it uses the open-end part of a numeric question, remember to refer to the "A" variable name.
• skip = name of the variable where to skip when a quota is filled,
  Once a quota is complete, the flow of the interview is altered: the questionnaire continues with the question listed as the "skip" question. The "skip" question can be located anywhere in the questionnaire. Typically, it would be a CULDESAC question ending the questionnaire, but it could also be a BLANK or CALCUL question which could act as a flag to control the questionnaire flow, or any other valid CallWeb questionnaire structure.
• stratum value = quota target, ...
  The "stratum value" part is the number of the stratum (and the value of the QUOTA variable); the "quota target" is the number of questionnaires expected in that stratum. Moreover, in the CATI version of CallWeb, a fixed variable called PRESTRATE may possess a numeric value corresponding to the maximum number of dossiers available to interviews at once. This second value is supplied in the same fashion as the quota target (i.e., stratum number = maximum number).

Stratum membership is determined by the value stored in the QUOTA variable. For example, if the QUOTA variable contains a 4 for a particular case, that case belong to quota number 4. Response categories may be defined (and labelled) for QUOTA questions but this is not mandatory. If they are defined, the labels are used by the report modules.

A particular quota is deemed complete when the number of cases with a value greater than zero in the "complete" variable is equal to or greater than the target stated in the QUOTA question for that stratum.

QUOTA questions are subject to display conditions: the quota criteria are activated only if the display condition is true.

Several QUOTA questions may be used in a questionnaire; they are used if and when the flow of the questionnaire reaches them. Therefore, a first set of quotas could be imposed on a first characteristic, early in the questionnaire or based on prepopulated data, and a second set of quotas could take effect later, maybe based on data collected as part of the interview or calculated data.

The following constraints apply to QUOTA questions:

• if the QUOTA variable is unassigned or has a value that is not listed in the list of quotas, quotas are not enforced and the questionnaire continues;
• a QUOTA question should always be located before the complete case variable within the questionnaire; if it isn't, partial questionnaires could erroneously be considered complete (unless the QUOTA question comes late in the questionnaire, in which case its usefulness is doubtful);
• since QUOTA questions involve a skip, they cannot be placed within a multi-question page; they must be inserted between defined pages;
• membership to a stratum and the number of completed questionnaires in a quota are verified only upon reaching and activating the QUOTA question;
• the QUOTA question is never displayed on screen; it is an administrative question; its value must be determined by pre-populated data or via a calculation;
• there can be an unlimited number of strata in a questionnaire.

Field management

E-mail notification

The cwemail module sends initial notification and reminders via e-mail. It uses a question as a template which may include recalls of values stored in the survey data base (probably via pre-population). It features tools to select subsets of cases according to any data in the data base as well as subsets defined by ranges of position numbers in the data set. Therefore, it is possible, for example, to send an initial invitation to all participants which includes their custom access code and which is delivered in their preferred language, and to follow-up with those who have initiated but not completed the questionnaire a week later with a motivational message which could be different from another follow-up to those who have not accessed the questionnaire at all.

E-mail notification is based on a special questionnaire variable which contains the title and text of the message to be broadcast. The following rules apply:

• the type code EMAIL must be listed on the line of the script containing the question name;
• EMAIL-type questions do not use the language codes; if language-specific messages have to be sent, create as many EMAIL questions as there are languages and select cases to broadcast to according to a language indicator;
• the body of the question text contains the subject line of the message;
• the note part of the question text contains the body of the message to be broadcast;
• paragraphs must be noted by <P> codes while simple line breaks are signified using <BR>;
• cwEmail reformats the message to create lines of 65 characters or less while respecting paragraphs and line breaks;
• an HTML version of the message may be inserted between <HTML> and </HTML> tags; the HTML coding must be adequate and complete — CallWeb does not validate it. It is recommended that a plain text version of the message accompanies the HTML version if the latter is used so as to accommodate all e-mail clients.
• the text of the title and/or of the (plain or HTML) message may contain recalls (piping) of any data in the data base using CallWeb recall syntax; additionnally, system variables such as the _telkey (the key to individual access to pre-existing questionnaires) can be recalled using the following syntax: {$varname}, e.g., {$_telkey}.
• the text of the message may contain an instruction to attach a file to the message; to do so:
• add the following anywhere in the body of the message
  [attach = directory/filename] or [annexer = directory/filename]
• the filename must be prefixed with the name of the directory where the file is located: if file "abc.pdf" is in directory "cwproject", the proper syntax is
  [attach = cwproject/abc.pdf]
• it is also possible to attach several files by separating their names with commas as in
  [attach = directory/filename1, directory/filename2]
• when a file is attached to a message, the message must contain an HTML portion in addition to the usual text portion; if one is not supplied, CallWeb creates it from the plain text version.
• the text of the message may contain an instruction to track the date and time of the opening of the message by the recipient; to do so add a [track = SOME_OPEN_PART] to the message. The date and time of opening will be stored in that open part in the appropriate _telkey.

The following are required for the e-mail notification operation:

• one open-end question containing the e-mail address of each participant;
• one open-end question available to store the datestamp of the mailout; the following codes are also used in that field
• -1 + datetime of the attempt: the message could not be sent within the allotted amount of time;
• -2 + datetime of the attempt: the domain name of the e-mail address is not reachable;
• -8 + datetime of the attempt: the e-mail address field is empty;
• -99: the system is attempting to send to that case or the procedure crashed while sending to this case.
• an e-mail address used as the sender of the invitation;
• the write access password to the CallWeb questionnaire since time date and time of e-mail delivery is stored in the data base;
• a question which acts as the e-mail text template.

One option, offered interactively, allows for the simulation of the mailing: messages are displayed on screen but neither sent out not timestamped in the data file.

Managing bounced e-mail messages

Using the # Send bounces to instruction, bounced messages can be sent to any arbitrary destination, or to the cwbounces.pl script which logs bounced messages and attempts to signal them in the CallWeb data set. To activate this latter function, follow these instructions:

• the format of the destination of bounced messages must be "bounces.*@domain.xxx"; CallWeb reformats this address to suit its needs;
• the # Check bounces against instruction is a comma-delimited list of question names which indicates which question field contain the e-mail addresses to check against the bounced addresses;
• the # Save bounces into must also be set to a comma-delimited list of question names which will receive the date and time of the bounce notifications (textual open-end parts); there must be as many question names in this list as there are in the # Check bounces against list;
• note that this system works only for project names using only lower-case characters because of limitations to e-mail address syntax. Note also that none of the directory names in the full path reaching the project directory can contain a dash.
• the cwbounces.pl module must be appropriately installed.

Automatic e-mail delivery

Using parameters set in # Auto email instructions, CallWeb can be asked to scan project data on a regular basis (say, every hour) to identify records which meet a certain condition, and to send them an e-mail message. The e-mail message itself follows the rules outlined above regarding formatting and recalling of record values. The generix syntax of this instruction is as follows (note: the equal signs and the commas are delimiters; use them as described in this example):

# Auto email xxx = (xxx can be any string uniquely identifying this instance of AUTOEMAIL)
#>     active = (yes or no, whether the instruction is currently active; the default is yes),
#>     selection = [ (MySQL expression identifying which cases to email to in the data base; must be within square brackets) ],
#>     email = (name of the EMAIL-type question in the questionnaire which is used to format the mesage),
#>     from = (e-mail address shown as sending the message),
#>     sender = (e-mail address effectively sending the message),
#>     to = (name of the CallWeb open-end part containing the e-mail address to send to),
#>     cc = (name of a CallWeb open-end part containing an e-mail address to send a carbon-copy to [optional]),
#>     reportto = (e-mail address to send reports to; supersedes the administrator_email installation instruction),
#>     bounces = (e-mail address to send bounces to; the type of address discussed above can be used as well to automatically intercept the bounces),
#>     store = (name of the CallWeb open-end part where the timestamp of the e-mail sent will be stored),
#>     max = (maximum number of messages to send in one iteration; this can be used to avoid mail server overload, in or out),
#>     delay = (seconds of delay before sending a second message to the same domain; the default is 120 seconds),
#>     unsubscribe = (URL to access the questionnaire unsubscribe feature; see the recipe)

Here is a real life example:

# Auto email 001 =
#>     active = yes,
#>     selection = [ ADATE > 20050101 AND NOT AINVITATION > 0 ],
#>     email = INVITATION,
#>     from = info@callweb.ca,
#>     to = AEMAILADDRESS,
#>     cc = ACCADDRESS,
#>     bounces = bounces.*@callweb.ca,
#>     store = AINVITATION,
#>     max = 1000,
#>     delay = 120,
#>     unsubscribe = http://circum.com/callweb/callweb.cgi?en:{$contexte{projet}}:{$_telkey}:UNSUB

One CallWeb project can contain any number of such automatic e-mail instructions (make sure they have different identifying strings) so that various circumstances (defined by the selection condition) can trigger different e-mail messages.

Limited substitution capabilities exist within the "selection" clause — essentially via the contexte list of data fields. For example, to trigger a message on January 1, 2009, the following condition could be used:

#>     selection = [ {$contexte{date}} > 20090101 ],

Field management

Questionnaire completion

Once the questionnaire is compiled — and data are prepopulated, if necessary — potential participants may be invited to complete the questionnaire. There is a variety of technical ways to open access to a questionnaire. Some are reviewed.

The most transparent way to access a CallWeb questionnaire is with the following Web instruction which applies to a fully open questionnaire or one where participants are provided with access codes on the fly:

http://here.com/callweb.cgi?_proj=project&_lang=LA

where

• "project" is the name of the questionnaire script;
• "LA" is the language in which to access CallWeb; if not provided, the questionnaire default language is used.

If an access code (see the # Survey type pound instruction) must be supplied to open a questionnaire, the same instruction may be used (and the system will prompt for the access code) or the instruction may be completed as follows:

http://here.com/callweb.cgi?_proj=project&_telkey=code

where

• "project" is the name of the questionnaire script;
• "code" is the access code;
• the _lang=LA parameter can be added to the call; it determines the language of the questionnaire; if it is not provided, the questionnaire default language is used.

If the questionnaire must be initiated at a location other than the first question (for a blank questionnaire) or the last question displayed (for a return questionnaire), the URL may contain a specific entry point as follows:

http://here.com/callweb.cgi?_proj=project&_telkey=code&_debute=QUESTION

where

• "project" is the name of the questionnaire script;
• "code" is the access code;
• "QUESTION" is the name of the question which will act as entry point into the script. The _AUDEBUT_ code can be used to force the questionnaire to begin at the first question, notwithstanding where the questionnaire was last left.

An appendix to this documentation lists all available URL options available when calling a questionnaire.

The instruction to access CallWeb may be hidden on a static page using a form or a hyperlink or using Web redirection tools like go.97.ca or custom built Web scripts.

Extremely short URL syntax

CallWeb also supports an extremely short URL syntax which ensures that links are not cut off in invitation e-mail messages. The syntax is as follows:

callweb.cgi?language:project:telkey:initial_question

as in

callweb.cgi?EN:demo:11111:Q21

or

callweb.cgi?EN:demo

if no access code is required or supplied within the link and the questionnaire starts at the beginning or at the last question displayed.

In fact, even the language parameter is optional; if it is not supplied, the default language defined in the questionnaire script is used. Note that CallWeb uses as the language parameter the first value that is made of two (and only two) letters (such that, if the project name, the _telkey or the _debute question are two-letter codes, the language parameter must be specified and must come before the other two-letter code). The other parameters must be in the order defined above.

Given the proper set up of the Web server, it is also possible to dispense with the explicit call to the callweb module (in Apache terms, by making callweb.cgi one of the DirectoryIndex entries). the link could then be shortened to something like:

http://ici.com?demo

Field management

Modifications during the course of a project

Any modification may be made to the questionnaire during the course of a project and without interrupting the collection of data. Of course, adding a question won't suddenly make data appear in completed questionnaires, but the system can regenerate itself to take modifications into consideration from there on and keep as much of the previously collected data as possible.

A simple compilation is sufficient to affect changes to a questionnaire:

• if the change does not add questions, delete questions, rename questions or move questions;
• if the change does not modify whether or not questions have open-end parts;
• if the change does not change a multiple-response question into a single-response question or vice versa.

The compilation procedure reports whether a structural data change is required. If so, it will be performed only if the "structural change" checkbox of the integrated module has been selected; otherwise, the compilation will terminate with an error and no change will be made either to the compiled questionnaire or to the data base.

Field management

Case management

Sometimes, data must be accessed on a case-by-case basis to look up responses, to correct them or to code open-ends. CallWeb offers cwNav to do just that. A call to cwNav (which stands for Navigate) is done via the integrated interface by providing the project name in the "Display data" section of the cw module.

The cwNav tool displays a menu to select cases and to select a subset of questions to display. Provided the right access codes are provided, the interface offers two ways to delete cases, three to view a case individually and three to open a case for editing.

Mass editing

Of particular significance is the mass editing mode that is activated by making the proper selection in the options menu. In mass editing mode, all displayed fields of all displayed cases are editable directly in a grid-like format. This could be particularly useful to display open-ended responses and a series of open-ended coding variables to perform a content analysis of the textual responses.

In mass edit mode, if _res (the most recent call result) is selected for editing, a new line appears in the menu. It offers the possibility of changing all existing _res values among selected cases to a new value. A dropdown list of possible _res codes is offered. If one of these codes is selected, all cases with _res values within the scope of the case selection are changed to that chosen value.

If a multiple-response question is edited in boxed mass edit mode, different values can be separated by commas or spaces. CallWeb edits the data upon Action! to delimit the values using "μ" characters. This is useful to code open-ended questions.

Reapplying CALCUL questions

cwNav also allows to reapply CALCUL questions (that is, to compute or recompute a calculation) on existing cases. After possibly identifying the cases to use in the operation using the case-selection portion of the menu, select a CALCUL question from the appropriate drop down list in the cwNAV interface (this feature is only available if the write-access password has already been supplied, if one is defined) and click Action!. Then key in the "UPDATE" keyword (upper case) and click Action! again.

Technical note: when reapplying CALCUL questions using cwnav.cgi, system variables (with names starting with an underscore) from the case data (such as _prepops and _h1) must be capitalized in the CALCULations (which is not the case in the CALCULations which take place during the performance of the questionnaire). One way around this issue for CALCUL questions which are intended to be used in cwnav.cgi as well as in the regular CallWeb context is to double up the name of the field and to put an "or" bar between the two as in $_prepops|$_PREPOPS. In Perl parlance, this means "use $_prepops if it exists, otherwise use $_PREPOPS".

Assigning values based on calculated expressions

This module also includes the ability to assign values to a variable based on a MySQL expression. Any field in the data base can be reassigned. Any type of assignment may be performed as long as the syntax of the expression is legitimate from MySQL's point of view and as long as the result of the expression conforms to the selected field data type. The following rules apply:

• only cases identified by the selection criteria (at the top of the utility menu) are affected by the assignment;
• the two parameters which specify a range of data base records to deal with ("Start from record no." and "Number of records to use") are NOT used in performing this operation;
• once a target variable is selected (on the "Update using MySQL" line in the interface) and a MySQL expression is entered, and after activation with the Action button, the system displays the ensuing assignment expression and requests confirmation via a keyword; the keyword is "UPDATE" (upper case).
• remember that the normal fields in the data base (non open-end parts) are stored as 16-byte character fields; MySQL allows mathematical operations on such fields (which are converted from character to numeric on the fly). Open-end parts (fields prefixed with A) are 64,000-byte character fields.

For example, it is possible to assign to AQ2 a value that is twice that of AQ1 with the following expression: AQ1*2. Also as an example, this operation could be performed only on cases where AQ2 is larger than 10 by making the proper selection in the options menu.

Use of this feature should be left to exceptional circumstances as the control of the assignment rests entirely with the user; none of the normal CallWeb data validation procedures are applied.

Field management

Real-time results

The cwFreq tool builds univariate frequency distributions, histograms, two-way tables and descriptive statistics in real time. It performs its duties equally well on numeric and on alphanumeric data. A call to cwFreq (which stands for Frequencies) is done via the integrated interface by providing the project name in the "Build tables" section of the cw module.

The cwFreq tool displays a menu to select cases and to select a subset of questions to display. Provided the right access codes are provided, the interface offers access to cases for editing.

Field management

Extraction of data

Data may be extracted at any time from the CallWeb data base and formatted for use with popular data analysis software. CallWeb can create:

• four data files:
• a comma-delimited file suitable for use in Excel (.csv extension);
• a fixed-column file suitable for use in statistical data analysis software like SPSS, SAS, StatXP and R (.dat extension);
• a tab-delimited file suitable for re-population of a CallWeb data base (.tcw extension);
• a comma-delimited file of the open-end parts along with the associated question name and _telkey (.opn extension).
• five program statement files:
• an SPSS code file for reading the fixed-column data file, including the assignment of variable and value labels (.sps extension);
• an R code file for reading the fixed-column data file, including the assignment of variable labels and variable formats (.r extension);
• a SAS code file for reading the fixed-column data file, including the assignment of variable labels and variable formats (.sas extension);
• an ASCQUE instruction file for the creation of a VoxCo Interviewer questionnaire which can then be converted to a StatXP format for reading the fixed-column data file, including the assignment of long labels and category labels (.asc extension);
• a Classic 1.1 Triple-S instruction file (.sss extension).
• an XML Triple-S 2.0 instruction file (.ssx extension).
• a Stata code file for reading the fixed-column data file, including the assignment of variable labels and variable formats (.stt extension);
• and a copy of the CallWeb question (.scw file).

The cwExtr (which stands for Extraction) tool is called from the integrated interface. cwExtr compresses the files it extracts into a zip archive. It either sends this zip file by e-mail to the address identified in # Send extractions to or it leaves the extraction on the server. The destination is selected in the cwExtr parameter interface.

In database-to-database mode (requested from the integrated interface, cwExtr can copy data from one CallWeb data base directly into another CallWeb data base. The source and destination data bases can reside in separate servers but they can also be in different instances of CallWeb on a single server or in the same CallWeb instance. In this mode, new data records can be added to the destination data base and existing data records can be updated with the data in the source data base. It is possible to select only a subset of fields to be transferred but system fields (the name of which starts with an underscore) are always transferred. All fields selected for transfer from the source data base must exist in the destination data base but the data base structure may differ between the two CallWeb projects otherwise.

Field management

Data base destruction

Once a project is completed and the data have been secured by an extraction, the cwdestruction module is used to get rid of the data base itself. The program requests that the keyword "DESTRUCTION" be typed in to confirm the intentions of the user. The write-access password must also be supplied if it is defined in the cwNav write password pound instruction.

This module is the only one (other than cwcompile, of course) which works even if the questionnaire file is not available. This allows for the destruction of data bases even if the questionnaire file was deleted (or otherwise rendered inaccessible) before the data base.

There is no further confirmation of the destruction command, so be extremely prudent in using this module.

Field management

Performing back-ups

CallWeb data reside in MySQL data bases which are not readily available to back-up software. The cwArchive modules perform timed back-ups of data files and place the zipped archives in the project directory.

The cwArchive back-up planning tool is available from the cw integrated module. It lists each CallWeb project based on the existence of MySQL data tables. For each project, hourly and daily back-ups can be planned. The number of hourly and daily back-up files to conserve on disk must also be set. It is also possible to provide an e-mail address where the back-ups will be sent.

By combining these tools, it is therefore possible, for example, to back-up the data file at 11AM, 2PM and 6PM while keeping 6 of these back-up files on disk (thereby providing two days of fail-safe back-ups) and to send a back-up set every night to an off-site e-mail address.

The first line of the back-up planning table defines the default behaviour that is applied to all project that don't possess their own planning strategy — this way, once the default strategy is defined, it is not necessary to worry about defining a back-up strategy for each new project.

cwArchive implements the following efficiency procedures:

• if the data have not changed between two back-up procedures of the same kind (either hourly or daily), the most recent back-up file is not kept — so that automatic mirroring utilities do not uselessly make copies of the same data over and over. This means that new back-up sets are not created as long as the data remain the same.
• following the logic of the previous point, only new back-up sets are sent by e-mail.
• if a daily back-up is planned at the same time as an hourly back-up, only the daily back-up is performed.

The cwArchive.pl module must be referenced in the /etc/cron.hourly directory to that it is started up every hour. The text on the installation of CallWeb offers more information in this regard.

Appendix A

Pound instructions

Pound instructions define various elements of the behaviour of CallWeb. They start with a pound sign (#) which may be preceded by spaces or tabs for the sake of clarity. A given pound instruction may be split over several lines by starting the second and following lines with a pound followed by a greater-than sign (#>); this combination may be preceded or followed by spaces or tabs.

Instruction		Syntax	Explanation	Default value
MANDATORY
# Available languages # Langues disponibles (*)	=	EN,FR	List of languages which will be available in the questionnaire. Languages are defined using two-letter ISO 639-1 language codes.	none
# Default language # Langue par defaut (*)	=	EN	Default language used when none or a non existent one is specified. It must be one of the languages identified in # Available languages.	none
# Survey type # Type enquete (*)	=	code	Open | Ouvert = fully open, no provision of an access code (was 1) Closed | Ferme = controlled access; the data base must be prepopulated (was 2) Open Combination | Ouvert Combinaison = fully open; a user id and a password are selected by the participant (was 3) Open Offered | Ouvert Offert = fully open, provision of an access code for resuming (was 5) Password | Mot de passe = controlled access like Closed plus an encrypted password (was 7). A cookbook recipe describes this system in detail.	none
STRUCTURE
# Group ID # Ecran ID (*)	=	Qm-Qn	Questions between Qm and Qn, including Qm and Qn, will be displayed on a single page.	none
# Table ID # Matrice ID (*)	=	Q1-Q2 HEADER=n PIXELS=n COLVARS=n POSITION=x FORCE_CODES TRANSPOSE SPECIAL=(n,...) CORNER=(...) VALIDATION	Questions between Qm and Qn, including Qm and Qn, are displayed in table format. The table header is repeated every HEADER row; the columns are PIXELS wide; there are COLVARS vertical questions. The POSITION can be LEFT|GAUCHE (default), CENTRE or RIGHT|DROITE. Details.	none
# Permutation ID	=	Qm-Qn STEP=n LIMIT=n LIKE=permutation	Questions between Qm and Qn, including Qm and Qn, are presented in random order and only LIMIT blocks are displayed. LIKE is the name of another permutation that drives the order of the current permutation. Details.	none
# New question order # Nouvel ordre de questions (*)	=	comma-delimited lists of question names; lists are slash-delimited	reorders questions defined in the questionnaire; there can be any number of reorder lists; they are separated by slashes. Each list is made of an arbitrary number of question names separated by commas, presented in the new order in which they will be processed in the questionnaire. This instruction facilitates the generalised use of the SUFFIX syntax. Example: # New question order = Q3, Q2, Q1 / Q14, Q16, Q15. As with all pound instructions, only one such instruction (the last one in the .scw file) is active in the questionnaire.	none
# Deactivate pages # Desactiver les pages (*)	=	yes|no oui|non	Whether or not CallWeb uses the GROUP (ECRAN) and TABLE (MATRICE) instructions in the questionnaire. May serve to linearize a questionnaire for CATI purposes.	no
(DEPRECATED) # Note segment # Segment note (*)	=	yes|no oui|non	Whether or not the NOTE text is presented in its own separate field in the .scw file (as opposed to the old syntax with the [NOTE] indicator in the question text)	yes
(DEPRECATED) # Rotations on RO # Rotations sur RO (*)	=	yes|no oui|non	Whether or not a pair of RO variables will behave as bounds of a permutation of questions. It should be set to "no" but it exists for backwards compatibility considerations.	no
# INDEX	=	List of questions	Comma-delimited list of questions needing to be indexed in the database. Open-ended question (using text fields) must be specified along with the number of characters to index within parentheses (e.g. AQ1(20)).	none
# Create View ID	=	SQL statement	SELECT SQL statement pulling some subset of data from the CallWeb database for use in another application. ID must be unique in the questionnaire file.	none
ACCESS (general)
# cwNav read password # Mot de passe cwNav lecture (*)	=	password	Password to read data in utility programs.	none
# cwNav write password # Mot de passe cwNav ecriture (*)	=	password	Password to modify and delete data in utility programs.	none
# cwextr zip password (*)	=	password	Password used to encrypt extracted data in a zip file (spaces compressed upon use).	none
# cwcompile zip password (*)	=	password	Password used to encrypt information stored by cwcompile in a zip file (spaces compressed upon use).	none
# cwarchive zip password (*)	=	password	Password used to encrypt back-up data stored by cwarchive.pl in a zip file (spaces compressed upon use).	none
# cwemail password # Mot de passe cwemail (*)	=	password	Password to send e-mail message through cwemail.	none
# Return permitted # Retour permis (*)	=	yes|no oui|non	Whether the permission is granted to return into a completed interview.	no
# Password change in type 7 # Changement de mot de passe en type 7 (*)	=	yes|no oui|non	Whether the user is offered the possibility to change their password in Survey type Password.	yes
# Seconds locked # Secondes de verrou (*)	=	# of seconds	Number of seconds during which a questionnaire is reserved to the active user.	0
# Language switch # Changement de langue (*)	=	yes|no oui|non	Whether the user can switch languages once the questionnaire is started.	yes
# Telkey pattern	=	pattern	Pattern followed for the creation of case identifiers (_telkey): combination of [C]onsonant, [V]owel, [L]etter, [N]umeric, [S]pecial and [?] for any of these. Any other character is inserted as it is. Each character of the pattern is replaced by one character in the access code. Substitutions are honoured.	CVCVCVN
# use_telkey_table	=	yes|no oui|non	adjusts the use_telkey_table installation instruction on a project by project basis (necessary for the correct operation of BASEpretest). "Yes" in this instruction will work only if the installation instruction is already set to yes.	yes
# Visible from # Visible depuis (*)	=	directory list	Comma-delimited list of utility directories which can access this project. The master util directory (defined by the "repertoire_utilitaire_maitre" key in the main configuration file) has default access to all projects.	none
# Accessible by # Accessible par (*)	=	list of users	Comma-delimited list of users who have access to the project based on their "Accessible by" accesses as defined in cwperm.cgi.	none
# Noreturn condition # Condition de non retour (*)	=	logical condition	xBase or Perl (in braces) logical condition indicating when a case cannot be re-entered — if the "# Return permitted" instruction has been set to "no". If a respondent has gone past the last question and that "# Return permitted" was set to "no", the questionnaire cannot be re-entered; the same is true of the "# Noreturn condition" is true; this allows to control return access without making respondents leave the questionnaire (presumably to a static Thank you page).	none
# Control by cookie # Controle par cookie (*)	=	yes|no	(in callweb.cgi only; does not work in cwx.cgi) activates a cookie-based control system which prevents the creation of a second questionnaire by a given computer in a fully open project; it has no effect on other types of questionnaires.	no
# Deny access if # Nier acces si (*)	=	logical condition	xBase or Perl (in braces) logical condition indicating when cases cannot be accessed. The condition can use any value in the questionnaire and any contexte data such as the date and time.	none
# Freeze data if # Figer les donnees si (*)	=	logical condition	xBase or Perl (in braces) logical condition indicating when cases cannot be modified any further. The condition can use any value in the questionnaire and any contexte data.	none
# Allow new in open combination	=	yes|no	In Open combination mode, accepts or refuses the creation of new cases based on newly supplied _telkeys.	yes
# Auto submit	=	logical condition	xBase or Perl (in braces) logical condition indicating whether CallWeb automatically submits a questionnaire page upon the selection of an answer. This is activated only on pages that contain a single question that allows for a single selection (radio button type); it is not activated on answer categories that contain an open-ended part.	none
# Master compilation server # Serveur maitre de compilation (*)	=	server name	Name of the server which has permission to compile the script. The server name is defined in the configuration file.	none
# Master codes	=	comma-delimited list of codes	Each of these passwords provide access to the project via the callweb.cgi (or cwx.cgi) module. Access is not granted without providing one of these codes.	none
# 2FA	=	[EMAILQUESTION]name of an EMAIL question [EMAILADDRESS]name of the open-end part of the question containing the email address of the respondent [CODEPATTERN]code pattern [STORECODE]name of an open-ended STOCK question to store the random code [FROM]"from" email address [COLLECTCODE]name of the question used to collect the random code from the respondent	If this instruction exists, before displaying any page, CallWeb checks that a 2FA cookie exists. If it does not, an email using the EMAILQUESTION text (that must contain a recall of the open-end part of the STORECODE question) is sent to the address in EMAILADDRESS. The CODEPATTERN follows the "# Telkey pattern" convention. The STORECODE and COLLECTCODE questions must include a C open-end part. The respondent is displayed question COLLECTCODE where they must enter the code received by email. Upon correct entry of the code, they are sent to the page they would have seen if there was no 2FA. A cookbook recipe describes this system in detail.	none
ACCESS (screen readers)
# Question Framing # Encadrement des questions (*)	=	legend | p	Specifies whether question text is framed within <p></p> tags or <legend></legend> tags	legend
# Table of contents of errors # Table des matieres des erreurs (*)	=	both|access|regular|none	Displays a table of contents of errors at the top of the questionnaire page depending on the display mode.	none
# Focus on error	=	first|general	If an error is found on a page, determines if the focus is on the first error or on the general error message.	general
ACCESS (CATI and robot)
# Supervisor password # Mot de passe des superviseurs (*)	=	password	Password used by supervisors to access call queue management functions.	none
# Master CATI server # Serveur maitre pour le CATI (*)	=	server name	Name of the server which has permission to manage the CATI component of a project. The server name is defined in the configuration file. This instruction requires that the control_by_other_server_possible installation option be set to yes.	none
# Maximum interviewers	=	number	Maximum number of interviewers allowed in the project at once.	999999
# Linear CATI mode	=	yes|no	In CATI mode, by default, questionnaires are displayed in a second browser window while the interviewer's call management screen remains open. With "# Linear CATI mode" set to "yes" or "oui", the questionnaire opens in the same window as the call management screen and a button is displayed at the top of the questionnaire to return to the call management screen.	no
# Cati	=	yes|no|ivr oui|non|ivr	Determines whether or not a CallWeb project is to be managed as a CATI project or as an IVR project. CATI projects have specific requirements which are enforced when this option is on. A default value may be defined in the CallWeb instance configuration file using the keyword "cati" (lower case).	no
ACTION (general)
# Include	=	file name	Inserts the content of the file at that location in the script, before compilation. If the file name has no path, the file must be located in the same directory as the .scw file; a path relative to the root of the CallWeb instance may be provided, e.g., cw/file.inc. Files that are included may contain Include statements of their own. With Include, one can share portions of questionnaires between scripts.	none
# Test ID	=	[TRIGGER]... [CONDITION]... [MESSAGE]... [TYPE]...	Applies error CONDITION test when receiving a value for the TRIGGER question and, if true, returns error MESSAGE where the TYPE specifies. Details.	none
# Recall ID # Rappel ID	=	recalled text or [condition]recalled text	Creates a value which may be recalled using the &#ID syntax. See the recall page for details. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Default JavaScript to # JavaScript par defaut*	=	yes|no oui|non	Determines whether or not JavaScript should be considered active if no information was yet received from the client session.	yes
# Load JavaScript Library	=	yes|no oui|non	Determines whether or not JavaScript libraries (Mootools and Highcharts) are loaded for questionnaire pages.	yes
(DEPRECATED) # Email # Courriel (*)	=	e-mail address	E-mail address where every completed questionnaire is e-mailed as back-up. Separate multiple addresses with commas.	none
# Default cwemail email # cwemail email par defaut (*)	=	e-mail address	default e-mail address used as sender in cwemail; can be changed within the cwemail interface.	none
# Default cwemail sender # cwemail envoyeur par defaut (*)	=	e-mail address	default e-mail address used as actual technical sender in cwemail (as opposed to the e-mail address that appears in the From field of the message); can be changed within the cwemail interface. This information is used by the receiving server to assess the risks of the message being spam. It should be an address that is deliverable to the sending server.	none
# cwemail report to (*)	=	e-mail address	e-mail address to which the turbo-mode report is sent.	system administrator
# convert email subject (*)	=	yes|no oui|non	Determines whether or now the email subject will be converted to UTF-8. Test before using.	Yes
# List Unsubscribe (*)	=	URL to unsubscribe	default URL to access the questionnaire unsubscribe feature. See the relevant cookbook recipe.	none
# Send extractions to # Envoyer extractions a (*)	=	e-mail address	E-mail address where cwextr data extractions can be e-mailed. Separate multiple addresses with commas.	none
# cwextr copy directory # repertoire sauvegarde cwextr (*)	=	(local directory)	Name of a local directory offered by default as a location where to put extractions in cwextr.	none
# Extraction width # Largeur extraction (*)	=	ncolumns	Default extraction width for closed questions.	4
# Minimal extraction width # Extraction de largeur minimale (*)	=	yes|no	If set to yes, data extractions default to the minimal number of columns required to represent the data.	no
# Refuse duplicates in cwprepop # Rejeter les doublons dans cwprepop (*)	=	list of questions	Comma-delimited list of questions or system variables (like _telephone) that cwprepop will test for duplicate values. Cases with duplicate are not prepopulated and their status is reported.	none
# Send bounces to	=	e-mail address	single E-mail address where bounces from e-mail sent by CallWeb will be directed. If the address is formatted as bounces.*@domain.xxx, CallWeb reformats the address to work with cwBounces.pl which intercepts bounced messages.	none
# Check bounces against	=	AQn	Name of the open-end part containing the e-mail address to which invitations/messages were sent (or comma-delimited list of open-end parts the same length as that of # Save bounces into). This value is used by cwbounces.pl to identify to which data base record a bounce message is associated. It must be set to use cwbounces.pl and the bounces.*@domain.xxx form of # Send bounces to.	none
# Save bounces into	=	AQn	Name of the open-end part containing the date and time of the bounce messages received for this data base entry (or comma-delimited list of open-end parts the same length as that of # Check bounces against). It must be set to use cwbounces.pl and the bounces.*@domain.xxx form of # Send bounces to.	none
# Complete case # Dossier complet (*)	=	SQL logical expression	Logical expression describing completed questionnaires. It must be a valid SQL-syntax expression; no validation is performed on its syntax.	none
# Cleaning skips # Sauts nettoyants (*)	=	yes|no oui|non	Whether or not data cleaning will be performed between the bounds of forward skips.	yes
# Save backwards # Sauve a reculons (*)	=	yes|no oui|non	Whether or not to save responses provided on a page before clicking on the CallWeb back button (not the browser back button). For logical reasons, no data validation is performed.	yes
# Url	=	url	URL where the browser will be sent at the completion of the questionnaire. The value can include recalled values. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. Therefore, different language versions can exit to different URLs as in # URL = [EN]http://yahoo.com[FR]http://yahoo.fr Substitutions are honoured..	none
# Attributable questions # Questions attribuables (*)	=	list of questions	Declares the list of questions (in the form: Q1-Q5, Q7, Q8-Q10,...) which may have their values attributed at the time of the original call of a case. For example, assuming that Q1 is among these questions and that abc is an Open project, calling "callweb.cgi?_proj=abc&Q1=2" would open a new record in the data base and attribute value 2 to question Q1 — this works with all _typeint types of projects. The rules are: only questions listed in this instruction can be attributed; only cases that have never been accessed can be attributed; only questions that are empty can be attributed (e.g., a prepopulated value cannot be changed via this procedure). Not all attributable questions need be attributed. Note that question names are always capitalized and that URLs and forms are case-sensitive. Remember, that in the flow of the questionnaire, all questions, including those listed in this instruction, are subject to be blanked out by BLANK question types, display conditions and skips; appropriate non-cleaning skips may be required to preserve the values attributed via this protocol.	none
# Pretest	=	text or HTML code	creates hyperlinks to BASEpretest and displays them besides every question that does not possess a NOPRETEST question type. If present and if BASEpretest exists, these links are created and pop a new window with a feedback form. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. See the related recipe.	none
# Pretest project # Projet pretest (*)	=	text	name of the CallWeb project used for the # Pretest feature.	BASEpretest
# Auto email	=	complex syntax (see the page on e-mail notification)	provides the parameters required for automatically sending e-mails under pre-set conditions.	none
# Stop			No parameters. Interrupts the compilation of the questionnaire file and disregards the following instructions.	n/a
# Execute if # Executer si	=	CALCUL question name or names separated by slashes or [condition]CALCUL question name or list of names separated by slashes	Identifies a CALCUL question (or a slash-delimited list of CALCUL question names) that is (possibly, conditionally) executed before displaying the next page. This instruction is evaluated after every page when the processing of the answers sent is found errorless and before calculating the display of the next page. See the recall page for details on the conditional syntax.	none
# Always open at # Toujours ouvrir a	=	question name	Identifies the question that the questionnaire opens on at every start (which ever question the questionnaire was closed on). The keyword _AUDEBUT_ can be used.	none
# Only for server ID # Seulement pour le serveur ID (*)	=	another pound instruction	"Only for server" is followed by the name of a server (defined in the CallWeb instance configuration file) as in # Only for server ABC = # cati = yes. This instruction is followed by another pound instruction which is activated only for the named server. Note that normal validations performed on the sub-instruction (in the previous example, "cati = yes") are not performed during compilation; it is good practice to test the sub-instruction as a normal instruction before tucking it into a "# Only for server" instructions.	none
# Copy questionnaire into # Copier le questionnaire vers (*)	=	user@location/directory	Sends a copy of the compiled questionnaire to a secondary CallWeb server in the context of a multi-server configuration. The instruction includes the shell user, the domain name or the IP address of the target server and the destination project directory, such as # Copy questionnaire into = someuser@callweb.ca/var/www/html/somerep/cwproject This copies the .qcw file as well as an empty .scw file. Public keys must have been exchanged between the servers for this instruction to work. More than one copy can be defined by specifying a comma-delimited location/directory list. It is also possible to copy other files located in the project directory by stating their name or pattern as part of the comma-delimited list, such as # Copy questionnaire into = someuser@callweb.ca/var/www/html/somerep/cwproject, *.pdf, *.docx which would copy all pdf and docx files from the compilation server to the distant server.	none
# MySQL engine	=	engine name	Specifies which of the MySQL storage engines to use for the project data base.	none
# BASEclicks	=	yes|no oui|non	Specifies whether the time spent on each page of the questionnaire should be stored in the BASEclicks data base.	no
# General Upload Parms	=	dir = x, file = yes|no, min = m, max = n, password = (value), extensions = ext1/ext2/...	Specifies the parameters used by File Upload open-end questions: dir is the directory where the files are stored within the project directory; file is a yes|no indicating whether the files are stored in the "dir" directory in addition of the MySQL database; min is the minimum number of bytes required for an uploaded file (default = zero); max is the maximum number of bytes allowed for an uploaded file (no default); password is an optional parameter requesting to zip the uploaded file and to password-protect it using this value which can be simple text or a substitution; extensions is a slash-delimited list of file extensions allowed (an asterisk indicates that all extensions are accepted).	none
ACTION (CATI and robot)
# Use do not call list	=	yes|no oui|non	Whether or not to use the information in project BASEdonotcall when pre-populating a project; also controls the display of the do-not-call checkbox on the interviewer interface.	yes
# Do not call email	=	e-mail address	E-mail address where a notification is sent every time an interviewer adds a telephone number to the do-not-call list. Separate multiple addresses with commas.	none
# CATI selection 3	=	question, yes|no question, oui|non	States that a certain question in the questionnaire is to act as a third case selection criterion for interviewers in CATI mode. The second parameter, following a comma, indicates whether interviewers are allowed to change the value of this datum from their call management window.	question name, none; action switch, YES
# Productivity index	=	MySQL expression	MySQL expression returning an index of interviewer productivity. Used in cwprod.cgi. See also the productivity_index installation option.	ROUND((completes_first + 2*completes_norefusal + 5*completes_withrefusal - 3*refusals_first ) / duration,1)
# Close full quota # Fermeture automatique des quotas atteints	=	yes|no oui|non	In CATI mode, controls whether the automatic quota closure system is activated.	yes
# Basic call management	=	yes|no oui|non	In CATI mode, controls whether the call queue management system uses simple dropdown lists to specify delays or more flexible value boxes.	no
# Other n in cwsuper # Autre n dans cwsuper **	=	MySQL expression	MySQL expression returning a count from the data base in cwsuper.	none
APPEARANCE CONTROL (page)
# Template # Gabarit	=	file_name	Name of the HTML file to be used as questionnaire template. The path may be specified, otherwise the file must be located in the project directory. In left undefined, the page is built using the traditional vertical construction. Another documentation page provides details. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. Substitutions are honoured.	none
# Stylesheet	=	file_name	Name of a file containing CSS styles specific to the current project. The path may be specified, otherwise the file must be located in the project directory. If not defined, substitution rules apply. Substitutions are honoured.	none
# Page_position	=	left|center|right	Position of the CallWeb question area within the browser window.	left
# Page_width # Page_largeur (*)	=	pixels|%	Width of the CallWeb question area within the browser window. It can be specified in pixels (a raw number) or in terms of percentage of the window (number with a percent sign).	100%
# Page_wire_pixels # Page_fil_pixels (*)	=	pixels	Width, in pixels, of the wire separating the CallWeb question area from the rest of the browser window.	0
# Page_wire_colour # Page_fil_couleur (*)	=	#FFFFFF	Colour of the wire separating the CallWeb question area from the rest of the browser window.	#FFFFFF
# Page_interior_colour # Page_interieur_couleur (*)	=	#FFFFFF	Colour of the CallWeb question area. The colour of the outside area is determined by the "body" style in the cascading style sheet file.	#FFFFFF
# Background image # Image de fond (*)	=	url.gif|url.jpg	Image to display underneath the questionnaire area.	none
# Page_interior_margin_pixels # Page_interieur_marge_pixels (*)	=	2	Width of the space separating the CallWeb question area from the wire and the rest of the browser window.	2
# Default N columns # N colonnes par defaut (*)	=	number	Default number of columns over which the response categories are laid out. This general value can be overridden on a question by question basis using the ncols argument on the question name line.	1
# Radio button position # Position du bouton radio (*)	=	top | middle | bottom	Vertical position of the radio button or checkbox relative to the answer category text in a normal one-question display.	top
# Header # Entete (*)	=	text	Text displayed at the top of each page. HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Footer # Pied (*)	=	text	Text displayed at the bottom of each page. HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Between questions # Entre questions (*)	=	yes|no oui|non	Whether or not a horizontal line separates each question.	no
# HTML Title # Titre HTML (*)	=	text	Title displayed in the browser bar during the execution of the questionnaire. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example. Substitutions are honoured.	none
# Title # Titre (*)	=	text	Project title displayed at the top of the questionnaire listing in cwQuestionnaire. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Display question names # Affiche noms questions (*)	=	yes|no oui|non	Whether or not question names are displayed on screen (debugging tool).	no
# Activate the mobile mode # Activer le mode mobile (*)	=	yes|no oui|non	Whether or not mobile devices are shown simplified pages.	no
# Thousand separator # Separateur de milliers (*)	=	character(s)	Specifies the character or characters to use to separate groups of thousands in numeroc values. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	_
APPEARANCE CONTROL (tables)
# M_CellColour # M_CouleurCellules (*)	=	#FFFFFF	Colour of the interior of odd-numbered-row cells in tables.	#FFFFFF
# M_CellColour2 # M_CouleurCellules2 (*)	=	#FFFFFF	Colour of the interior of even-numbered-row cells in tables.	#FFFFFF
# M_SpecialColour # M_CouleurSpeciale (*)	=	#ACACAC	Colour of the SPECIAL codes for the table.	#CCCCCC
# M_InteriorSpacing # M_EspacementInterieur (*)	=	number	Width of the interior margins in matrix cells	3
# M_Borders # M_Bordures (*)	=	number	Width of the border in tables	1
# M_BorderColour # M_CouleurBordures (*)	=	#CCCCCC	Colour of the matrix borders.	#FFFFFF
# M_ColumnTitleAlignment # M_AlignementTitresColonnes (*)	=	T|B|M	Location of column titles within their cells: T = top, B = bottom, M = Middle	B
# M_ColumnTitleColour # M_CouleurTitresColonnes (*)	=	#FFFFFF	Colour of the column title cells in tables.	#666699
# M_LineTitleColour # M_CouleurTitresLignes (*)	=	#FFFFFF	Colour of the odd-numbered row title cells in tables.	#CCCCCC
# M_LineTitleColour2 # M_CouleurTitresLignes2 (*)	=	#FFFFFF	Colour of the even-numbered row title cells in tables.	#FFFFFF
# M_ Cell highlighting # M_ mise en evidence (*)	=	#EEEEEE	Colour of the cell highlighting.	Same as column headings
# Cell highlighting # Mise en evidence des cellules (*)	=	yes|no oui|non	Activates or deactivates cell highlighting in response categories and in tables.	yes
# Styles for tables # Styles pour matrices (*)	=	yes|no oui|non	Whether or not to activate the use of CSS styles to format the question tables.	no
# M text position # Position texte M (*)	=	left | right gauche | droite	Position, relative to the radio button or the checkbox, of the text produced in a table cell by the M answer behaviour code..	right
APPEARANCE CONTROL (buttons and thermometer)
# Display language button # Affiche bouton langue (*)	=	0 or NO or NON 1 or TOP or HAUT 2 or BOTTOM or BAS	Location of the buttons used to swap from one language to the next: no button, to the top after the title or at the bottom along the navigation buttons.	BOTTOM
# Display back button # Affiche retour arriere (*)	=	yes|no oui|non	Whether or not the "back" button or image is displayed.	no
# Page Error Image # Image erreur page (*)	=	file name	Identifies a graphic file to use to highlight errors in a submitted questionnaire page. If the file name has no path, the file must be located in the same directory as the .scw file; a path relative to the root of the CallWeb instance may be provided, e.g., cw/file.gif. Substitutions are performed at compilation time.	gr/erreur_page.gif
# Field Error Image # Image erreur champ (*)	=	file name	Identifies a graphic file to use to highlight errors at the question level. If the file name has no path, the file must be located in the same directory as the .scw file; a path relative to the root of the CallWeb instance may be provided, e.g., cw/file.gif. Substitutions are performed at compilation time.	gr/erreur_champ.gif
# Forward text # Texte avance (*)	=	text	Text displayed on the "Next" submit button or under the "Next" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Next question
# Submit text # Texte submit (*)	=	text	Text displayed on the "Next" submit button or under the "Next" submit image for SUBMIT-type questions. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Submit
# Backwards text # Texte recule (*)	=	text	Text displayed on the "Previous" submit button or under the "Previous" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Previous question
# Unlock text # Texte unlock (*)	=	text	Text displayed on the "Unlock" submit button or under the "Unlock" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Save and exit
# Stop text # Texte stop (*)	=	text	Text displayed on the "Stop" submit button or under the "Stop" submit image. HTML codes are interpreted only under the submit image. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Stop
# Button order bottom # Ordre des boutons bas (*)	=	code letters	Determines the order of presentation (left to right) of the buttons and progress bar/thermometer at the bottom of each question screen. The letters indicate the nature of the buttons and their order: [B]ack button, [N]ext button, [U]nlock button, [L]anguage buttons, [T]hermometer, [S]top button. This is also the default order. Any letter not supplied in the instruction is added by the compiler, in this same order, after declared buttons. Whether some of these buttons appear is controlled by other pound instructions.	BNULTS
# Button order top # Ordre des boutons haut (*)	=	code letters	Determines the order of presentation (left to right) of the buttons and progress bar/thermometer at the top of each question screen. The letters indicate the nature of the buttons and their order: [B]ack button, [N]ext button, [U]nlock button, [L]anguage buttons, [T]hermometer, [S]top button. This is also the default order. Unnamed buttons are not displayed.	none
(DEPRECATED) # Button order # Ordre des boutons (*)	=	code letters	Determines the order of presentation (left to right) of the buttons and progress bar/thermometer at the bottom of each question screen. The letters indicate the nature of the buttons and their order: [B]ack button, [N]ext button, [U]nlock button, [L]anguage buttons, [T]hermometer, [S]top button. This is also the default order. Any letter not supplied in the instruction is added by the compiler, in this same order, after declared buttons.	BNULTS
# Button position # Position des boutons (*)	=	LEFT | CENTER | RIGHT	Position of the directional buttons.	LEFT
# Top button position # Position des boutons haut (*)	=	LEFT | CENTER | RIGHT	Position of the top directional buttons (overwrites # Button position).	LEFT
# Bottom button position # Position des boutons bas (*)	=	LEFT | CENTER | RIGHT	Position of the bottom directional buttons (overwrites # Button position).	LEFT
(DEPRECATED) # Thermometer # Thermometre (*)	=	0|1|2|51|52 , QUESTION1 , QUESTION2	Location of the progress bar: 0, no progress bar; 1, to the right of the page title, expressed as a percentage; 2, to the right of the "Next" button, expressed as a percentage; 51, to the right of the page title, expressed as a number of questions, 52, to the right of the "Next" button, expressed as a number of questions. QUESTION1 and QUESTION2 are optional; they are separated by commas. They are the names of a first and last questions used in calculating the completion rate; if only QUESTION1 is specified, QUESTION2 is assumed to be the last question of the questionnaire; if neither are specified, QUESTION1 is the first question of the questionnaire.	0
# Display thermometer # Affiche thermometre (*)	=	NONE | TOP | BOTTOM | AUCUN | HAUT | BAS, NUMBER | NOMBRE | PERCENT | POURCENTAGE | MUTE | MUET, QUESTION1, QUESTION2	Position de la barre de progression. NONE or AUCUN, no progress bar; TOP or HAUT, after the page header; BOTTOM or BAS, to the right of the "Next" button. After a comma, PERCENT or POURCENTAGE to express the progress as a percentage; NUMBER or NOMBRE to express it as a number of questions left; MUTE or MUET to put no text right of the progress bar. QUESTION1 and QUESTION2 are optional; they are separated by commas. They are the names of a first and last questions used in calculating the completion rate; if only QUESTION1 is specified, QUESTION2 is assumed to be the last question of the questionnaire; if neither are specified, QUESTION1 is the first question of the questionnaire. QUESTION1 and QUESTION2 may also be substitutions which compute to a question name when the questionnaire is displayed.	NONE
# Stop button # Bouton stop (*)	=	no|yes|[condition], question|substitution non|oui|[condition], question|substitution	Whether or not the Interruption button is displayed. If set to "yes" or to a true display condition between square brackets, a second parameter is passed after a comma: the name of the question where the respondent is directed after clicking on the Interruption button, or a substitution that will compute to a name when the questionnaire is displayed.	no
# Thermometer text # Texte thermometre (*)	=	text	Text displayed above the progress thermometer. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Progression in the questionnaire
# Thermometer colour # Couleur thermometre (*)	=	#FFFFFF	Colour of the thermometer.	# M_ColumnTitleColour
# Thermometer width # Largeur thermometre (*)	=	pixels	Number of pixels used by the width of the thermometer.	200
# Thermometer height # Hauteur thermometre (*)	=	pixels	Number of pixels used by the height of the thermometer.	10
# Thermometer border width # Largeur bordure thermometre (*)	=	pixels	Number of pixels of the thermometer border.	1
# Thermometer border colour # Couleur bordure thermometre (*)	=	#FFFFFF	Colour of the thermometer border.	#CCCCCC
# Thermometer gap width # Largeur espace thermometre (*)	=	pixels	Number of pixels of the gap between the thermometer border and the thermometer itself.	1
# Thermometer gap colour # Couleur espace thermometre (*)	=	#FFFFFF	Colour of the gap between the thermometer border and the thermometer itself.	#FFFFFF
# Second line of buttons # Seconde ligne de boutons (*)	=	yes|no	Controls the display of the text line which follows the buttons and thermometer at the bottom of the page. Can be used to attach "alt" and "title" text to graphical Next, Back and language buttons while avoiding the text equivalent below the buttons.	Yes
# Image left # Image gauche (*)	=	image_file_name	Name of the image file to be used as a "Previous" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Image right # Image droite (*)	=	image_file_name	Name of the image file to be used as a "Next" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Submit image # Image submit (*)	=	image_file_name	Name of the image file to be used as a "Next" button if the question has a SUBMIT question type. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Language image # Image langue (*)	=	image_file_name	Name of the image file to be used as a language button. The path must be specified. In left undefined, a standard HTML button is displayed. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Image stop	=	image_file_name	Name of the image file to be used as a "Stop" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Image unlock	=	image_file_name	Name of the image file to be used as an "Unlock" button. The path must be specified. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Radio button suffix (retired) Suffixe des boutons radios (retiré) *	=	text	Suffix added to the names of the image files used to replace radio buttons and check boxes. Substitutions are honoured.. The image files may reside in the project directory or in the resource directory (gr/). The following image types are sought (in this order): png, gif, jpg. Ideally, images should be between 12 and 15 pixel square. Eight images must be defined in a set: cboxCheckedDisabled, cboxDisabled, cboxChecked, cbox, radioCheckedDisabled, radioDisabled, radioChecked, radio (e.g., cboxCheckedDisabledGREEN.png). The following sets are predefined: BLUE, GREEN, PURPLE, RED, YELLOW	none
# Radio button directory # Repertoire des boutons radios *	=	text	Directory where the radio button and check box images are found (see # Radio button suffix). It must be a subdirectory of the instance root directory. Substitutions are honoured..	gr/
APPEARANCE CONTROL (messages)
# Mandatory question # Question obligatoire (*)	=	HTML text	Inserts the HTML text after the question or note text of a mandatory question (which has a minimum number of answers of at least 1). The text can use HTML coding such as <SPAN CLASS=ERREUR>*</SPAN>. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
(DEPRECATED) # General error message # Message erreur general (*)	=	text	Text displayed at the top of the page if an error was identified in the responses provided. HTML codes are interpreted but the whole text is formatted using the .ERREUR style. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Incomplete or erroneous data were identified on this page. Please see below.
# Demo message # Message demo (*)	=	text	Text displayed at the top of the page if the system functions in demo mode (no data saving). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	DEMONSTRATION MODE. Responses will not be recorded.
# Frozen data message # Message donnees figees (*)	=	text	Text displayed at the top of the page once # Freeze data if is true (no modifying saving). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	The data in this case are frozen. No change will be recorded.
# System message [message number] # Message du systeme [message number] (*)	=		Redefines (and customizes) system messages. "[message number]" must be substituted for the actual number of the system message to affect. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Enforce response length # Contraindre la longueur des reponses (*)	=	yes|no	Limits a multi-line alpha-numeric response to the number of characters specified in the .scw file (if JavaScript is activated in the respondent's browser). Also determines whether CallWeb produces an error message if a multi-line alpha-numeric response is longer than the open-part length defined in the questionnaire.	no
APPEARANCE CONTROL (access code page)
# Access page header	=	yes|no oui|non	Whether or not to display the page header (# Entete LA) on the access code request page.	yes
# Access page footer	=	yes|no oui|non	Whether or not to display the page footer (# Pied LA) on the access code request page.	yes
# Access request telkey	=	text	Text displayed before the input box on the access code request page (when no access code is offered). HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>Your access code, please</P>
# Access give telkey	=	text	Text displayed before the input box on the access code request page (when a new access code has been offered). HTML codes are interpreted. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>Your access code is <B>{$_telkey}</B>.<BR>Keep it to be able to access your answers in the future.</P>
# Access send telkey button	=	text	Text of the Send button on an access code request page. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Send
# Access send telkey image	=	image_file_name	Name of the image file to be used as the Send button on an access code request page. The path must be specified. In left undefined, a standard HTML button is displayed. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	none
# Access no telkey button	=	text	Text of the "I have no access code" button on the access code request page (# Survey type = Open Offered). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	If you don't have an access code, click here
# Access bad telkey	=	text	Text displayed when an incorrect access code is supplied (# Survey type = Closed or Open Offered). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>The access code supplied (<EXECUTE>$formdata{_telkey}</EXECUTE>) is not valid.</P>
# Access bad telkey 7	=	text	Text displayed when an incorrect access combination is supplied (# Survey type = Password). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>This combination of access code (<EXECUTE>$formdata{_telkey}</EXECUTE>) and password is not valid.</P>
# Access request access code in type 3	=	text	Text displayed in # Survey type = Open Combination to request an access code (the syntax rules for the code could be inserted in this statement). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>Your <B>access code</B>, please.<BR>If you don't have an access code yet, please create one.</P>
# Access request password in type 3	=	text	Text displayed in # Survey type = Ouvert Combinaison to request a password (the syntax rules for the password could be inserted in this statement). Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>Your <B>password</B>, please.<BR>If you don't have a password yet, please create one.</P>
# Access bad combination in type 3	=	text	Text displayed upon finding a bad password for an existing access code in # Survey type = Ouvert Combinaison. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER CLASS=ERREUR>This access code already exists or the access code/password combination is invalid.</P>
# Access bad telkey pattern in type 3	=	text	Text displayed upon finding an access code which does not conform to # ACCESSTELKEYPATTERN. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER CLASS=ERREUR>The access code does not follow the expected pattern.</P>
# Access bad password pattern in type 3	=	text	Text displayed upon finding a password which does not conform to # ACCESSPASSWORDPATTERN. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER CLASS=ERREUR>The password does not follow the expected pattern.</P>
# Access request password in type 7 (*)	=	text	Text displayed in # Survey type = Password to request a password. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER>Your <B>password</B>, please.</P>
# Access request new password in type 7 (*)	=	text	Text displayed in # Survey type = Password to offer the entry of a new password. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<p align="center">If you want to change your <b>password</b>, enter the existing password above, then type a new password below twice.</p>
# Access bad telkey pattern in type 7 (*)	=	text	Text displayed upon finding a password which does not conform to # ACCESSTELKEYPATTERN. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	<P ALIGN=CENTER CLASS=ERREUR>The password does not follow the expected pattern.</P>
# Access telkey pattern	=	regular expression	Regular expression used to described the pattern of acceptable access codes in # Type enquete = 3. Do not include the starting and ending slashes but escape the expression according to rules. The regular expression is assumed to start with ^ and end with $ — that is, the entire user ID supplied must conform to the pattern.	.+
# Access password pattern	=	regular expression	Regular expression used to described the pattern of acceptable passwords in # Type enquete = 3. Do not include the starting and ending slashes but escape the expression according to rules. The regular expression is assumed to start with ^ and end with $ — that is, the entire password supplied must conform to the pattern.	.+
APPEARANCE CONTROL (relation)
# Text relation add	=	text	In the context of a RELATION question, text displayed on the button to add a child. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Add
# Text relation refresh	=	text	In the context of a RELATION question, text displayed on the button to refresh the page. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Refresh
# Text relation delete	=	text	In the context of a RELATION question, text displayed on the button to delete a child. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Erase (immediate effect)
# Text relation modify	=	text	In the context of a RELATION question, text displayed on the button to modify a child. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.	Modify
APPEARANCE CONTROL (CATI and robot)
# Read # Lire	=	text	Text inserted before an answer category label with behaviour code L. Can contain HTML code. Substitutions are honoured.	<IMG SRC="gr/lire.gif">&nbsp;
# Do not read # Ne pas lire (*)	=	text	Text inserted before an answer category label with behaviour code P. Can contain HTML code. Substitutions are honoured.	<IMG SRC="gr/nepaslire.gif">&nbsp;
# Display min max # Affiche min max (*)	=	yes|no oui|non	Whether or not the minimum and maximum number of answers are displayed in the note field.	no
# Robot caller id	=	telephone number	Telephone number displayed by the IVR robot.	none
# Robot caller id text	=	text	text displayed by the IVR robot.	none
# Caller id	=	telephone number	Telephone number displayed by the Asterisk server placing calls on behalf of interviewers.	none
# Caller id text	=	text	text displayed by the Asterisk server placing calls on behalf of interviewers.	none
OTHER
# No deep mobile check (*)	=	yes|no	Skips the deep check for mobile devices using the BrowserDetect module.	no
##		text	Comment; not subject to compilation.	none
#>		text	Continuation line. The text on this line is added to that of the previous line	none

* This value is used internally by CallWeb.

Appendix B

Installation instructions

Server software requirements

CallWeb needs the following to be installed on the server:

• Perl 5 (including the following modules: CGI, CGI::Carp, DB_File, DBI, Fcntl, File::Compare, File::Copy, File::Path, FileHandle, IO::Socket, locale, LWP::Simple, Net::FTP, Net::Telnet, POSIX, Time::HiRes, Time::Local, SOAP::Lite 1.08, Encode)
• MySQL 4 or better
• Berkeley DB
• a Web server (tested with Apache 2 with mod_unique_id enabled)
• Sendmail
• (for dialer and robot operations) Asterisk, version 1.2 or better (and the Asterisk::AGI Perl module)

Questionnaire designer client station

The following software has proven very valuable in editing CallWeb .scw files:

• TextPad is an extraordinary pure-text editor which offers a whealth of functions. In particular, it supports syntax highlighting which makes CallWeb .scw files much more readable. A TextPad syntax highlighting file is available for CallWeb. Alternatively, some like Notepad++ for which CallWeb has a basic syntax highlighting file as well.
• KeyText is a fabulous keyboard and hot key mapper. For example, one can paste an entire CallWeb question definition by simply pressing a predetermined combination of keys.
• the free RGBtoHEX provides an easy way to select colours and identify the corresponding hex code.
• the free Pixie is a colour picker: point to a colour on screen and Pixie tells you the hex, RGB, HTML, CMYK and HSV values of that colour (the hex value can be copied to the paste buffer using a keycoard key combination). ColorZilla, a free Firefox extension implements a similar function, but it is available only within Firefox.
• there are hundreds of useful Web applications. For example, http://gradcolor.com/ creates a gradient which is very useful to find different intensities of a given coulour (do this by requesting a gradient from that colour to white).

File locations

System configuration file

The system configuration file and the project configuration files may contain several parameters controlling the in-depth behaviour of CallWeb and its default appearance. Some parameters must be supplied in one file or the other. Mandatory parameters are (parameters are case-sensitive):

The following are mandatory in CATI mode:

The following are mandatory to connect an Asterisk server to CallWeb:

The following are mandatory in robot mode:

The following are mandatory in connecting CallWeb to a predictive dialer:

In a project-specific configuration file, if the MySQL host is redefined, the following entry is mandatory:

Any pound instruction can be inserted in the system configuration file. All such pound instructions found in the system configuration file are inserted at the beginning of all questionnaires upon compilation. This means two things:

• that system-wide defaults can be defined for any of the pound instructions, such as defining a default read access password for all projects with "# cwNav read password = some_password";
• that such system default values can be overwritten inside any questionnaire by adding the same instruction (with other parameters) in the .scw file.

In addition, optional configuration parameters include (parameters are case-sensitive):

administrator_email	=	(e-mail address of the CallWeb system administrator)
notify_after	=	(number of days of data base inactivity that triggers an e-mail reminder; the default is 14)
notify_every	=	(number of days between notifications of inactive projects as defined by notify_after; the default is 1)
maximum_undo_versions	=	(number of update versions to keep available for undo; the default is 5)
serveurftp	=	(name/address of the FTP server offering system updates and upgrades)
proxyftp	=	(name/address of the proxy server through which FTP has to connect; add ":port" if the proxy does not use the default FTP port)
usagerftp	=	(user name on serveurftp)
motdepasseftp	=	(password for usagerftp)
engine	=	(MyISAM or InnoDB)
use_telkey_table	=	(yes or no; determines whether a table of reserved _telkeys is used for open projects (preferable); requires mod_unique_id in Apache; default "no")
nom_de_ce_serveur	=	(name of the server; used in # Only for server and # Master compilation server instructions)
repertoire_utilitaire_maitre	=	(name of the master utility directory)
repertoire_cati_maitre	=	(name of the master directory for CATI scripts)
nom_installation	=	(name of the installation reflected in the utility banner)
langue	=	(2-letter code for the default language)
update_daemon	=	(0 or 1 according to whether the daemon files must be updated with cwupdate. Place in only one CallWeb instance on a given server.)
cwextr_types	=	(default extraction file types presented as a comma-delimited list among the following: csv, dat, tcw, opn, sps, sas, rcode, asc, sss, scw)
cwextr_email	=	(e-mail address to select as the default extraction destination)
csv_delimiter	=	(single character used as a delimiter in extracted csv files)
champs_par_csv	=	(default number of fields in an extracted csv file)
test_email_address_hostname	=	(domain name used by the test_email_address function to build the FROM parameter (should be a subdomain like mail.callweb.ca). Uses $ENV{HTTP_HOST} or $ENV{HOSTNAME} otherwise.)
url_principal	=	(URL used by cwautoemail.pl to call cwemail.cgi; must be a fully qualified URL ending with a slash such as http://domain.com/utilities/)
max_var_label_length	=	(default maximum length of variable labels extracted to other software code; default = 60)
max_value_label_length	=	(default maximum length of category labels extracted to other software code; default = 40)
max_spss_alpha_field	=	(maximum number of characters read off alphanumaric fields in SPSS; default = 254)
default_cwtelkeys_pattern	=	_telkey pattern proposed by default by cwtelkeys
_M_COULEURCELLULES	=	(# colour code; base cell colour for tables)
_M_COULEURCELLULES2	=	(# colour code; second cell colour for tables)
_M_COULEURTITRESCOLONNES	=	(# colour code; column header cell colour for tables)
_M_COULEURTITRESLIGNES	=	(# colour code; base line header cell colour for tables)
_M_COULEURTITRESLIGNES2	=	(# colour code; second line header cell colour for tables)
_M_COULEURBORDURES	=	(# colour code; border colour for tables)
_M_BORDURES	=	(number of pixels for table borders)
_M_ESPACEMENTINTERIEUR	=	(number of pixels for internal spacing of table cells)
_M_ALIGNEMENTTITRESCOLONNES	=	(T|B; vertical alignment of column header cells)
cati	=	(oui|non|ivr, whether the installation is CATI- or IVR-type by default)
couleur_commentaire_o	=	(# colour code; colour of the CATI result codes where interviewer comments are mandatory)
couleur_commentaire_f	=	(# colour code; colour of the CATI result codes where interviewer comments are optional)
couleur_commentaire_a	=	(# colour code; colour of the CATI result codes where interviewer comments are disallowed)
between_cati_buttons	=	(number of pixels to insert between CATI buttons presented to interviewers)
lignes_commentaires	=	(number of lines of the comment entry box for interviewers)
colonnes_commentaires	=	(number of columns of the comment entry box for interviewers)
size_of_stratum_selection_box_in_cwsuperpro	=	(number of lines for the multiple select drop-down list of strata in cwsuperpro; default 5)
default_for_cati_comment_carry_over	=	(yes|no whether the interviewer comment is carried over from call to call by default
delai_min_entre_appels	=	minimum number of seconds between two call results by a particular interviewer for a given case
allow_password_change_by_interviewers	=	yes | no (if yes, interviewers are given a chance to change their password upon login)
allow_sip_change_by_interviewers	=	yes | no (if yes, interviewers are given a chance to change their SIP extension upon login)
constrain_to_groups	=	yes | no (if yes, the free case selection option is not displayed to interviewers if groups exists in CATI mode)
allow_viewing_time	=	yes | no (if no, interviewers are not offered the option to view thier cumulated time in CATI mode)
interviewer_clock	=	12|24 (displays the apppointment clock as a 12- or 24-hour clock; 24 is the default)
allow_cross_project_search	=	yes | no (if no, interviewers are not offered the list of projects from which to search for a case in CATI mode)
interviewer_timer	=	yes | no (whether or not interviewers are shown a timer on the call management screen; the default is yes)
mpBASEtemps	=	password used in BASEtemps (mpBASEtemps is used in cwsuper to give supervisors access to interviewer time slips.)
productivity_index	=	MySQL expression returning an index of interviewer productivity. Used in cwprod.cgi. The default is ROUND((completes_first + 2*completes_norefusal + 5*completes_withrefusal - 3*refusals_first ) / duration,1).
repertoire_wav	=	absolute path to the server directory containing the project directories where .wav files of the interviews are stored
repertoire_html_wav	=	directory alias defined in the Apache configuration to permit building URLs to the .wav files even if they are outside the Web server directory structure
seconds_before_dialling	=	seconds (in CATI mode with an Asterisk dialler, length of the pause between the display of the call management screen and the automated dialling of the telephone number)
storeinBASEappels	=	yes | no (in CATI mode, if no, call results are not stored in real time in BASEappels and interviewers do not get a dynamic count of their results)
week_start	=	between 0 and 6: determines when the week starts in the calculation of the _week system variable; 0 for Sunday, 1 for Monday, etc.
comparative_results	=	yes|no (in CATI mode, controls the display of a summary of interviewer productivity to each interviewer)
command_prefix_for_record_wav	=	(some text) (prefix command used by the Apache user to start and stop recordings in face-to-face settings)
url_to_cwagent	=	(url) (full URL to the cwagent.cgi script to bridge agents from int2select.cgi to cwagent.cgi; should be in the usagerXXX.conf file of the CallWeb instance agents use to log in) (e.g., http://192.168.0.1/prod/interviewers/cwagent.cgi)
url_from_cwagent	=	(url) (full URL to the int2select.cgi script to bridge agents from cwagent.cgi back into int2select.cgi; should be in the usagerXXX.conf file of the CallWeb instance where cwagent.cgi runs, i.e. in the robot instance) (e.g., http://192.168.0.2/prod2/interviewers/int2select.cgi)
agent_languages	=	comma-delimited list of ISO language codes offered to the agents logging into cwagent.cgi
parms_to_copy_dump_file (OBSOLETE)	=	apache@server (where "server" is a distant MySQL server where the backup dump files will be written. This parameter serves to copy the dump file over to the administrative server and to delete it from the MySQL server. For this to work, ssh keys must have been exchanged for the Apache user [for compilation backups] and the root user [for automated backups])
control_by_other_server_possible	=	yes | no, set this to yes if it is possible that there will be CATI projects that are controlled by another server based on the # Master compilation server pound instruction
default_cwpermissions_directory_permissions	=	permission level assigned to project directories by cwpermission; it must be in octal representation; the default is 0777.
default_cwpermissions_file_permissions	=	permission level assigned to project files by cwpermission; it must be in octal representation; the default is 0666.
cwpermissions_deletes_from_cwdir	=	(case insensitive regular expression, minutes); the two options are separated by a comma; cwpermissions.pl deletes files that correspond to the regular expression pattern when they are older than the number of minutes stated in the second option; the regular expression is not tested — it is entirely the responsibility of the CallWeb manager.
exclude_from_cwcompile_backup	=	(case insensitive regular expression); defines a regular expression identifying files to NOT save in cwcompile zip backups.
hide_user_from_cwdocs_link	=	yes; if defined, this option hides the user code from the cwdocs link in cw.cgi.
check_login	=	yes | no, set to no, it deactivates the authentification system.
dialer_timeout_milliseconds	=	number of milliseconds after which the dialer considers a call ring-no-answer.
musiconhold	=	0|1, whether or not to use music-on-hold when transfering a batch-dialed extra call to an agent.
external_transfer_string	=	string used by Asterisk to compose SIP channel information for external audio monitoring; this is lifted from the relevant Asterisk context.
systemlog	=	level of logging to be performed in the instance. Valid values are: 0: Emergency (emerg); 1: Alerts (alert); 2: Critical (crit); 3: Errors (err); 4: Warnings (warn); 5: Notification (notice); 6: Information (info); 7: Debug (debug).
max_log_size	=	maximum size of the log file before rotation, expressed in megs.
service_command_path	=	path of the service command used in cwupdate.pl. Normally, this option is not necessary.
login_pw_valid_days	=	number of days after which a user must change their password to access CallWeb utility modules (none by default).
login_pw_allow_same	=	(yes|no) whether or not users are allowed to supply the same password when requested to change it.
login_pw_rules	=	tab-delimited list of regular expressions that must be adhered to in creating a new password.
login_pw_rules_message	=	text displayed to explain the password composition rules. Different linguistic versions may be defined by inserting [xx] codes using ISO language codes; see # URL for an example.
out_of_service	=	(yes|no) blocks all access to the instance questionnaire and displays a general out-of-service message.
no_lastlogin_storage	=	(yes) avoids storing the time of last utility program login in the permission file.
user_cookie_expiry_minutes	=	(number of minutes after which a user cookie expires; the default is 120)
use_user_cookie	=	yes | no, determines if user cookies are used instead of the _user parameter
cwarchive_extensions	=	(extensions), provides a comma-space delimited list of file extensions to add to the automated archives
cookie_same_site_security	=	(none|lax|strict), default = lax, SameSite security level of the administrative user cookie
charset	=	(character set), default = ISO-8859-15, character set declared upon the creation of the HTML pages; change this only if use of a UTF-8 font is necessary

Automated tasks

A number of tasks are performed automatically by various programs once they are scheduled in the cron feature of a Linux server. They are as follows.

One last script cwbounces.pl is a special case. Its purpose is to intercept bounced messages and to update the CallWeb data base with an indication of this bounce. It is not located in the cron system but rather, it is called by Sendmail upon receiving bounced messages for the "bounces" address. A single instance of this program services an entire server and all instances of CallWeb installed on it. Here are detailed installation instructions:

• put the cwbounces.pl script in the main utilities directory;
• make cwbounces.pl executable (0755);
• create a symbolic link cwbounces.pl in /etc/smrsh, pointing to the cwbounces.pl script in the utilities directory;
• create a virtual user called "bounces.+*@domain.xxx" (adjust the domain name but leave the left side of this expression intact) and send its mail to the "bounces" alias;
• create a mail alias "bounces" piped to the cwbounces.pl script (|cwbounces.pl).

Note that, for cwbounces.pl to work with a given instance of CallWeb on a server, the following directories and files must be readable by the user or the group "mail" (under which Sendmail runs):

• the cwroutines.pl file ;
• the etc directory;
• the file usager???.conf file within the etc directory (the exact name of this file varies with each instance of CallWeb).

Daemon mode installation

The CallWeb daemon mode is three times as fast as the base mode. In daemon mode, CallWeb runs constantly in the server background, waiting for questionnaire page request files to be placed by cwx.cgi (which replaces callweb.cgi in daemon mode) in the spool directory. The CallWeb daemon processes these request files and places the HTML code of the next questionnaire page in the spool directory for cwx.cgi to display to the respondent.

To use the CallWeb daemon mode, follow the installation instructions and then call the questionnaires with the cwx.cgi module instead of the callweb.cgi module.

CallWeb daemon mode installation instructions:

• the daemon mode requires that Apache loads the mod_unique_id module. Make sure that the following line is part of the Apache configuration:
  LoadModule unique_id_module modules/mod_unique_id.so
• create the directory /var/spool/callweb and allow the Web server user to read from it and to write to it, for example:
  mkdir /var/spool/callweb
  chmod 0777 /var/spool/callweb
• place cwx.cgi in the CallWeb installation master directory and allow the Web server user to execute it, for example:
  chmod 0755 cwx.cgi
• create the /opt/callweb directory and place callwebd.pl as well as cwroutines.pl in it, for example:
  mkdir /opt/callweb
  cp callwebd.pl /opt/callweb
  cp cwroutines.pl /opt/callweb
  chmod 0700 /opt/callweb/callwebd.pl
• create the /var/log/callweb directory and make it writable by the Apache user, for example:
  mkdir /var/log/callweb
  chown apache:apache /var/log/callweb
  chmod 0755 /var/log/callweb
• place callwebd in /etc/rc.d/init.d and give it execution permission by root, for example:chmod 0700 /etc/rc.d/init.d/callwebd
• request that the CallWeb daemon be started automatically upon server boot: chkconfig --add callwebd (see update-rc.d for Ubuntu)
• to allow for daemon system updates, add the following line to the usagerXXX.conf file of one instance on the server (probably the most active production instance): update_daemon = 1. That CallWeb instance will control updates to the daemon system.
• if the system is connected to a Munin server:
• activate loglevels 1 (for problems) and 4 (for page creation) in /etc/callweb.conf (see below);
• place the callwebd_pages script in the /etc/munin/plugins directory
• make callwebd_pages executable
• restart Munin with service munin-node restart

The CallWeb daemon is started, stopped and restarted with the command service callwebd start|stop|restart. The daemon status can also be probed with service callwebd status. When the "restart" or the "stop" command is issued, the CallWeb daemon waits until the request queue is empty before proceeding with stopping the daemon.

The CallWeb daemon configuration file is /etc/callweb.conf. The CallWeb daemon must be restarted for changes to the configuration file to take effect. Its content is as follows.

Multi-server configuration (CallWeb cluster)

Using the configuration files, it is possible to develop various server implementations of CallWeb. First, CallWeb can run on the same computer as the data base server if the "hote" parameter of the main CallWeb configuration file points locally:

hote = localhost

Another CallWeb server could use the same MySQL server by specifying a distant address for the "hote" in its main configuration file:

hote = 99.99.99.99

If the two CallWeb servers use the same "client" parameters in their main configuration file, both servers will "see" projects from both origins; that would be the typical setup of a multi-site CATI system. If they use different "client" parameters, each CallWeb server will only see its own projects.

Each project used in a multi-server configuration (also called "CallWeb cluster") should possess a # Master compilation server pound instruction to protect the integrity of the questionnaire files. Parallelism of the questionnaire files across servers is ensured by the # Copy questionnaire into instruction which dispatches a copy of the questionnaire (and an empty .scw file) to distant servers (there should be one such instruction for each of the distant servers in the CallWeb cluster which will use the questionnaire). This dispatching of questionnaires requires that a direct SSH connection (with exchange of public keys) exists between the servers; see below for the procedure.

In a multi-server configuration, re-compilation of the .scw script involving changes in data structure should be performed on the computer running the MySQL server. Otherwise, while the compilation will be performed and the data base adjusted if required, no backup of the data will be kept before modifying the data structure.

Note that, for bi-mode projects, the CATI CallWeb server must be the Master for compilation so that the .ccw file is correctly processed.

Exchange of public keys between servers

This procedure must be carried out only once per server connection. In brief, here is the procedure for the exchange of public keys between Linux servers:

• in this procedure, "computer2" (the server, or the CallWeb computer which will receive the compiled CallWeb questionnaires) is the machine granting access to "computer1" (the client, or the computer which will send the compiled CallWeb questionnaires);
• on computer1,
• in a root shell, issue the following commands:
• passwd apache [when prompted, enter a password for user apache]
• usermod -s /bin/bash apache
• chown apache:apache /var/www
• enter a shell with the apache user ("su apache");
• as the apache user, issue the following commands in a computer1 terminal window:
• cd /var/www/
• [if the .ssh directory does not exist] mkdir .ssh
• cd .ssh
• ssh-keygen -t rsa [accept the default options and do not specify a passphrase; this generates two files: id_rsa and id_rsa.pub]
• in a root shell, issue the following commands:
• chown root:root /var/www
• copy id_rsa.pub from computer1 to computer2, in directory /var/www/.ssh (for example, via SFTP);
• on computer2, in a root shell, issue the following commands:
• usermod -s /bin/bash apache
• cd /var/www/.ssh
• cat id_rsa.pub >> authorized_keys
• in a shell as the apache user on computer1, initiate an SSH connection and type "yes" when prompted; this needs be done once to accept the exchange of keys.

Appendix C

URL options

It is highly advisable to use the cw integrated module to access the various components of CallWeb (for simplicity and safety). Nonetheless, there may be circumstances where direct coding of URLs is necessary. The following tables provide the URL options which can facilitate the creation of specialized menus.

URL options for the callweb module

URL options are used when building the URL to call CallWeb. Such URL could look something like: <http://blabla.ca/callweb.cgi?_proj=test&_demo=1&_lq=1&_print=1&_debute=Q1>. CallWeb also offers a short syntax to call questionnaires.

Appendix D

Recent changes and additions