Language keywords

This page lists the keywords which can be uses in a DSC script.

BREAK: exit a loop

Used to exit loops FOR, FOREACH

IF(NOANSWER(tab[0])) THEN n=xRANDOM("tab")
FOR i=1 TO 100 DO {
        IF(tab[i]==30) THEN {
                n=i
                BREAK
        }
}

CANVAS: declare a canvas

In the VARIABLES section:

 c1 : CANVAS

CHECK: program to be executed whenever a page is submitted

Used to verify a condition before respondent can move to the next page.

For example, to ensure that one number is lower than another.

NEWPAGE()
 ASK(qa_inf)
 ASK(qa_sup)
CHECK : {
          IF(qa_inf>=qa_sup) THEN WARNING(qa_inf," NB: qa_inf must be lower than qa_sup.")
}
ENDPAGE()

DECIMAL: For ''real'' (decimal) numbers where the answer may contain a decimal point

In the examples below precision is the total number of digits and scale is the number of digits to the right of the decimal point. For example, the number 123.45 has a precision of 5 and a scale of 2.

d1 "Enter a decimal number" : DECIMAL   // Any numeric value, without restriction
d2 "Enter a decimal number" : DECIMAL (2)   // Precision=2, no scale
d3 "Enter a decimal number" : DECIMAL (4,2)   // Precision=4, scale=2
d4 "Enter a decimal number" : DECIMAL [0,100] (,4)   // Minimum 0, maximum 100, 4 decimal places
d5 "Enter a decimal number" : DECIMAL [0,10]   // Minumum 0, maximum 10 (excluding 10 itself) - i.e. 0 <= x < 10
d6 "Enter a decimal number" : DECIMAL[0,..] (,1)   // Non-negative decimal, to 1 DP
d7 "Enter a decimal number" : DECIMAL [0.0001,0.9999] (4,4)   // "Between 0.0001 and 0.9999, scale=4 and precision=4 (leading zero is not counted in precision)
d8 "Enter a decimal number" : DECIMAL (5,0)   // Precison=5, Scale=0 - same as INTEGER (5)

DEFINITIONS: Marks the start of response list definitions

The DEFINITIONS section is used to define response lists or question types to be used more than once in the questionnaire

DEFINITIONS
YesNo = {
  1 (1) "Yes",
  2 (2) "No"
}

Q1 "Are you going to the cinema?" : YesNo
Q2 "Do you have an apartment?" : YesNo

DO: precedes the action section of a loop

FOR i=1 TO 10 DO {
 ....
}

ELSE: Precedes actions to be executed if the associated IF condition is not true

ELSE is always associated with an IF. ELSE IF may also be used.

IF (Q1 IN {1}) THEN {
 ....
}
ELSE {
 ...
}

IF(Q2 IN {1}) THEN {
 ....
}
ELSE IF(Q2 IN {2}) THEN {
 ....
}
ELSE {
 ...
}

FLOAT: For ''real'' (decimal) numbers

FLOAT is a type of variable used for ''real'' numbers, i.e numbers that can have decimal places. See DECIMAL for what is now the recommended way to specify the properties of decimal numbers.

QUESTIONS
 Price "Price:" : FLOAT
 Price2 "Price to one decimal place" : FLOAT @[ndecs=1]
 ```

VARIABLES f : FLOAT

<a name="for"></a>
### FOR: To define loops

Used for loops. For example to repeat a set of instructions. For example to loop based on a sequence of numbers from 1 to 5000. 

k=0 FOR i=1 TO 20 DO { k = k + Q1[i] }

FOR i=0 TO 8 STEP 2 DO { .... }

<a name="foreach"></a>
### FOREACH: loop through a list of items

Loop through a list of brands (brand is a variable declared with type lst_brands)

DEFINITIONS lst_brands= { 1 "Brand 1" 2 "Brand 2" ... }

QUESTIONS Brand : lst_brands ROUTE FOREACH brand IN lst_brands DO { ... }

Another syntax: 

FOREACH i IN (1,2,3,99) DO { ... }

For more examples using FOREACH with lists [click here](20103#lists)

### FUNCTION: Declare project/client specific functions

On occasion project or client specific features are needed. The CAWI language can be extended by writing a function in the perl language to provide this extra functionality. Such functions have to be declared with the FUNCTION keyword.

VARIABLES: FUNCTION xTEST RETURNS INTEGER FUNCTION getTown RETURNS INTEGER FUNCTION xRANDOM RETURNS INTEGER

<a name="getcattr"></a>

### GOTO: redirection to a page in the questionnaire

To go (or return) directly to a page in the questionnaire. Clicking the message text in the example below will take respondent to the first page of the questionnaire.

MESSAGE("@GOTO:1$Return to the first question@$")

The page to go to could be set in an integer variable as in the example below.

goto : INTEGER

q7 "Indicate if you agree with each statement about the advert@CLASS:note$You can click here @GOTO:@ANS:goto$$here@$ to see the advert again@$"

<a name="if"></a>
### IF: If Condition

Define a condition under which the subsequent actions should be executed 

IF(age==40) THEN { .......... }

### <a name="integer"></a>INTEGER: for Integers (Whole Numbers)

Questions or variables where the input value is a whole number.

QUESTIONS i1 "How many?" : INTEGER // Standard integer question i2 "How many up to 999" : INTEGER (3) // Integer limited to 3 digits i3 "Select a number from 0 to 10" : INTEGER [0,10] // Integer between 0 and 10 i4 "How far?" : INTEGER [0,..] // Integer between 0 and infinity

VARIABLES n: INTEGER

<!--
### ISVALIDDATE: To be documented

Built in FUNCTION.

Parameters: Returns:

Example

X=ISVALIDDATE(XX)

-->

### OPENTEXT: text box with no limit on the number of characters that can be entered

Q1 "Please describe what you saw:" : OPENTEXT

### QUESTIONS: Marks the start of the question declarations

QUESTIONS Q1 "Age" : 0..99 Q2 "Sex" : lst_sex

<a name="replace"></a>

### REQUIRED: Question must be answered

REQUIRED used to make it obligatory for a question is answered.

Q1 "Age" : 0..99 REQUIRED

### RETURNS: type of result returned by a function

Defines the type of result returned by a function.

FUNCTION xTEST RETURNS INTEGER FUNCTION XRANDOM RETURNS INTEGER FUNCTION XSETDIMLABEL2 RETURNS STRING

### ROUTE: Marks the start of the routing section of the questionnaire

ROUTE urlcp="bye" NEWPAGE() ASK(Q1) ENDPAGE()

### STEP: step through a loop

STEP can be used to control steps through a loop (+2,+10 ....)

FOR i=0 TO 8 STEP 2 DO { .... }

### STRING: string variable

To declare a text string variable.

s : STRING

### TEXT: Text entry box with a defined number of characters

Q1 "Marque: " : TEXT[256]

### THEN: Then

Used in combination with IF

IF (age==40) THEN { .......... }

### TO: highest value in a loop

Sets the highest number in a loop.

For example to display a message 10 times: 

FOR i=1 TO 10 { MESSAGE("Message"+i) }

### VARIABLES: Mark the start of the variable declarations section

VARIABLES n : INTEGER s: STRING ```