SCROLL: List of dsc keywords and functions

List of dsc keywords and functions

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

Note that date functions are not included in this list. Click here for date functions.

AND: The logical AND

AND is used to check if multiple conditions are TRUE

In this example, if Q1=1 and Q2=1 then the actions after the THEN are executed:

IF (Q1 IN {1} AND Q2 IN {1}) THEN { ... }

ANSWER: Question answered or not

In the example below if question Age is answered then the statements after the THEN are executed:

IF (ANSWER(age)) THEN { ... }

In the case of an array question, then check for each item in the array:

IF (ANSWER(age[1]) AND ANSWER(age[2]) AND etc..) THEN ... If there are a lot of items, use a loop:

VARIABLES kid : lst_kids ROUTE FOREACH kid IN lst_kids DO { IF ANSWER(age[kid]) THEN ... }

It is the inverse of NOANSWER.

ASK: Ask a question

Example ask question Q1

NEWPAGE() ASK(Q1) ENDPAGE()

See ASK to display a question for more inforamtion about ASK

BEGINCANVAS: mark the start of a canvas table

Always accompanied by ENDCANVAS

NEWPAGE() BEGINCANVAS(c) ASK(Q1) ENDCANVAS() DISPLAYCANVAS(c) ENDPAGE()

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()

CLEAR: remove the responses to a question

CLEAR(q5)

COPYBLOCK: copy cells

COPYBLOCK by itself moves the cells. If 'copy=yes' is added it puts the cells in the specified location without affecting the original cells.

The example below moves row 1, column 0 of the canvas table to row 10 and then copies the contents of row 2, column 0 to row 1, column 0.

NEWPAGE() BEGINCANVAS(c) ASK(Q1) ENDCANVAS(c) COPYBLOCK(c:1,0,1,0,c:10,0,10,0) COPYBLOCK(c:2,0,2,0,c:1,0,1,0,'copy=yes') DISPLAYCANVAS(c) ENDPAGE()

COUNT: To count the number of responses to a question.

Examples: n=COUNT(Q1) IF (COUNT(Q1) > 0) THEN ...

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)

The example below shows an older way of specifying decimal number ranges that is still accepted.

Q3 "How much did it cost?" : 10.0:300.0

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" } QUESTIONS Q1 "Are you going to the cinema?" : YesNo Q2 "Do you have an apartment?" : YesNo

DISPLAYCANVAS: Display the canvas table

DISPLAYCANVAS is used to display the table. If a canvas is created with a BEGINCANVAS and and ENDCANVAS it will not be displayed without DISPLAYCANVAS

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 { ... }

ENDCANVAS: marks the end of a table

Always associated with a BEGINCANVAS

NEWPAGE() BEGINCANVAS(c) ASK(Q1) ENDCANVAS() DISPLAYCANVAS(c) ENDPAGE()

ENDPAGE: end of the page

All the information between NEWPAGE() and ENDPAGE() will be on the same web page.

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

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 { ... }

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 brand IN {1,4,7,8} DO { ... }

For more examples using FOREACH with lists click here

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

GETCATTR: Built in function to return the value of a category attribute

Arguments:

The question in which the attribute is defined
The choice to which the attribute is associated
The attribute to be retrieved.
Not used but must be included as ""

Example

DEFINITIONS services = { 1 "Academic Support Office" @[cnotes="Co-ordinating processes for assuring the quality of educational provision",division="Academic Support"], 2 "HR Services" @[cnotes="Central HR processing and administration",division="Human Resources"] } QUESTIONS Q1 "Which service" : services REQUIRED Q2 : services

Example message statements in the ROUTE section if HR Services is selected at Q1 and Q2 is not answered.

MESSAGE("You have selected @ANS:Q1$ in the " + GETCATTR(q1,q1,'division','') + " division: " + GETCATTR(q1,q1,'cnotes','')) MESSAGE("1st row of Q2: cnotes=" + GETCATTR(q2,{1},'cnotes','') + ". Division=" + GETCATTR(q2,{1},'division',''))

To display:

You have selected HR Services in the Human Resources division: Central HR processing and administration 1st row of Q2: cnotes=Co-ordinating processes for assuring the quality of educational provision. Division=Academic Support

GETLABEL: label for the selected category

This example returns the label associated with the response to question.

GETLABEL(sex)

GETQARRAY: Get the current items/categories from an array question.

GETQARRAY looks at the definition of the question, and gets the list from that definition (or the list that was modified by SETQARRAY).

Parameters: a question and a dimension
Returns: a list

Examples: SETQARRAY(s6,SHUFFLE(GETQARRAY(s6,0) \ {98}) | {98})

NEWPAGE() IF NOT(A8 IN {1}) THEN SETQARRAY(B1,0,GETQARRAY(B1,0)\{3}) IF NOT(A9 IN {1}) THEN SETQARRAY(B1,0,GETQARRAY(B1,0)\{4}) ASK(B1) ENDPAGE()

Note: GETQARRAY only applies to questions - you don't do GETQARRAY(lst_q1) - you just use lst_q1 directly, as that is a definition, and can't be changed

If you want GETQARRAY to return the full list, you can do a RESETQARRAY first: Q1 : {1,2,3,4} SETQARRAY(Q1,0,{1,2}) xx = GETQARRAY(Q1,0) // Returns {1,2} RESETQARRAY(Q1,0) xx = GETQARRAY(Q1,0) // Returns {1,2,3,4}

Note: Array questions can have more than one dimension so SETQARRAY needs to know which dimension to operate on. The dimension is specified in the second parameter to SETQARRAY (0 for the first dimension in the example above). In most cases there will be only one dimension.

Note: See GETQLIST for getting lists of non grid/array questions.

GETQATTR: Get the value of a question attribute

Used to get the value of a question attribute.

Can be combined with SETQATTR to append text to the current value.

SETQATTR(Q1,'qnotes',GETQATTR(Q1,'qnotes') + "@|Some additional text")

GETQLIST: Get the current items/choices from a question.

GETQLIST looks at the definition of the question, and gets the list from that definition (or the list that was modified by SETQLIST).

Parameters: a question
Returns: a list

Examples: SETQLIST(s6,SHUFFLE(GETQLIST(s6) \ {98}) | {98})

NEWPAGE() IF NOT(A8 IN {1}) THEN SETQLIST(B1,GETQLIST(B1)\{3}) IF NOT(A9 IN {1}) THEN SETQLIST(B1,GETQLIST(B1)\{4}) ASK(B1) ENDPAGE()

Note: GETQLIST only applies to questions - you don't do GETQLIST(lst_q1) - you just use lst_q1 directly, as that is a definition, and can't be changed

If you want GETQLIST to return the full list, you can do a RESETQLIST first: Q1 : {1,2,3,4} SETQLIST(Q1,{1,2}) xx = GETQLIST(Q1) // Returns {1,2} RESETQLIST(Q1) xx = GETQLIST(Q1) // Returns {1,2,3,4}

Note: See GETQARRAY for getting lists of grid/array questions.

GETQTEXT: get the question text of a question

Put the question text of variable f0 in s

s=GETQTEXT(f0)

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@$"

IF: If Condition

Define a condition under which the subsequent actions should be executed

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

IN: inclusion

Precedes a list of values and used to check if a variable has been given one of the values in the list.

To check if question Q1 contains 1, 2, 7 or 10 :

IF (Q1 IN {1,2,7,10}) THEN { ... }

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

MESSAGE: Display a message on the screen

NEWPAGE() MESSAGE("The following page shows an advert.@|Please look at it closely") MESSAGE("When you are ready, click on Next Page.") ENDPAGE()

NOANSWER: variable not answered

NOANSWER To check if a question has not been answered. It is the inverse of ANSWER.

IF(NOANSWER(Q1)) THEN WARNING(q1,"Please select a response.")

NOT: logical NOT

Example to check that response 4 has not been selected at Q1:

IF (NOT(Q1 IN {4})) THEN { ... }

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

Q1 "Please describe what you saw:" : OPENTEXT

OR: logical OR

The example below checks that Q1=1 or Q2=1:

IF(Q1 IN {1} OR Q2 IN {1}) THEN { ... }

PRINT: To print questions and responses to a pdf file.

On some projects respondents are given the opportunity to download a pdf report of the questions and their responses. The PRINT command is used to specify which questions should be included in this pdf report.

PRINT(Q1)

QUESTIONS: Marks the start of the question declarations

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

REPLACE: Replace an item in a list with another list.

Syntax:

list1 = REPLACE(list1,list2,list3)

Where list2 contains a single item. The item in list2 is replaced by the item(s) in list3.

Examples:

DEFINITIONS lst_A6={ 1,2,3,4,5,6,7,8,9,10,98 @[xchoice='yes'] } lst_A1 = {a1,a2,a3,a4,a5, b1,b2,b3,c1,c2,c3,c4, d1,d2}

QUESTIONS A1 : lst_A1 A6 : lst_A6{*}

VARIABLES items_A1 : lst_A1 items_A6 : lst_A6

ROUTE NEWPAGE() // Shuffle the order of 4 blocks of items, shuffling the items within 2 of them items_A1 = SHUFFLE({a1,b1,c1,d1}) items_A1 = REPLACE(items_A1,{a1},SHUFFLE({a1,a2,a3,a4,a5})) items_A1 = REPLACE(items_A1,{b1},{b1,b2,b3}) items_A1 = REPLACE(items_A1,{c1},SHUFFLE({c1,c2,c3,c4})) items_A1 = REPLACE(items_A1,{d1},{d1,d2}) SETQLIST(A1,items_A1) ASK(A1) ENDPAGE()

NEWPAGE() // Shuffle all items, but keep 3 and 4 together, and 98 at the end items_A6 = SHUFFLE((lst_A6 \ {4,98})) items_A6 = REPLACE(items_A6,{3},SHUFFLE({3,4})) items_A6 = items_A6 | {98} SETQLIST(A6,items_A6) ASK(A6) ENDPAGE()

REQUIRED: Question must be answered

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

Q1 "Age" : 0..99 REQUIRED

RESETQARRAY: Undo any changes made using the SETQARRAY command.

RESETQARRAY(Q10,0)

To reset the first dimension of array question Q10.

RESETQLIST: Undo any changes made using the SETQLIST command.

RESETQLIST(Q2)

RESETQMAXSEL: Undo any changes made with the SETQMAXSEL command

RESETQMAXSEL(Q1)

RESETQTEXT: Set the question text back to how it was originally defined.

Usually used after Question text altered with SETQTEXT.

RESETQTEXT(Q0)

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

ROTATE: to rotate a list from a random start point

In some surveys response choices have to be rotated with one choice being chosen as the first displayed. The other choices follow in the original order until the original last choice is reached after which the original first and following choices are displayed.

Rotation can be done with the ROTATE function in combination with SETQLIST and SETQARRAY.

Example:

DEFINITIONS lst_items = { 1 "Item 1", 2 "Item 2", 3 "Item 3", 4 "Item 4" }

QUESTIONS Q1 "Which item do you prefer?" : lst_items

VARIABLES rot_items : lst_items

ROUTE IF (NOANSWER(rot_items)) THEN rot_items = ROTATE(lst_items) NEWPAGE() SETQLIST(Q1,rot_items) ASK(Q1) ENDPAGE()

This might, for example, display the choices in the order: item3, item4, item1, item2.

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

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

SETBLOCK: canvas instruction

SETBLOCK to set properties of cells in the canvas (e.g. to colour a line, display a call in bold ...).

SETBLOCK(c:0,0,0,0,"You buy this product because...") SETBLOCK(c:1,0,10,4,'shufflerows=Q1') SETBLOCK(c:0,1,0,4,'text-align=center, font-weight=bold')

SETCANVAS: define the cells used in a canvas

Defines the cells of the canvas that will be displayed on the screen.

Display the 9 cells in rows 0-2 and columns 3-5 of canvas ''c''

SETCANVAS(c:0,3,2,5)

SETQARRAY: Set the rows (or categories in other dimension) to be displayed in an array question.

It is common in surveys to modify the list of categories or items to be displayed at a question according to responses given at previous questions. SETQARRAY can be used to control the display of grid/array questions.

Only display Q10 rows that were selected at q9. SETQARRAY(Q10,0,q9)

Only display rows of Q2 that are in the lst_items list. SETQARRAY(Q2,0,lst_items)

Examples of how to use SETQARRAY can be found by clicking here

SETQATTR: Set the value of a question attribute.

To change the value of a question attribute.

SETQATTR(Q3,'qnotes',"Some text to be displayed under the question text")

Note that these changes are not persistent between pages, so should be placed within the NEWPAGE() / ENDPAGE() statements where the question is asked.

SETQLIST: Set the items/categories to be displayed in a question.

It is common in surveys to modify the list of categories or items to be displayed at a question according to responses given at previous questions. SETQLIST can be used to control which categories should be displayed.

Only display Q10 categories that were selected at q9. SETQLIST(Q10,q9)

Only display categories of Q2 that are in the lst_items list. SETQLIST(Q2,lst_items)

Examples of how to use SETQLIST can be found by clicking here

Note: See SETQARRAY for controlling display of grid/array questions.

SETQMAXSEL: Change the maximum number of selections

To change the maximum number of selections in a list of choices question.

Example:

QUESTIONS Q1 : lst_items{*} ROUTE NEWPAGE() SETQMAXSEL(Q1,1) ASK(Q1) ENDPAGE()

This would ask question Q1 as a single-choice question (with radio buttons).

You can use any number up to the maximum number defined in the question definition. So Q1 : lst_items{3} and then SETQMAXSEL(q1,4) would keep the maximum as 3.

RESETQMAXSEL(Q1) reverts back to the original definition.

SETQTEXT: modify the question text

Replace the text of a question. Example to replace f0 with "AAA".

SETQTEXT(f0,"AAA")

SHUFFLE: to randomise the order of a list

In some surveys response categories have to be presented in random order. For example to avoid bias because of the order items are presented. There are parameters that can be used to do simple randomisation but more complex randomisation can be done with the list SHUFFLE function in combination with SETQLIST and SETQARRAY.

Example:

DEFINITIONS lst_items = { 1 "Item 1", 2 "Item 2", 3 "Item 3" }

QUESTIONS Q1 "Which item do you prefer?": lst_items

VARIABLES rand_items : lst_items

ROUTE IF (NOANSWER(rand_items)) THEN rand_items = SHUFFLE(lst_items) NEWPAGE() SETQLIST(Q1,rand_items) ASK(Q1) ENDPAGE()

For more examples of how to use the SHUFFLE function, including how to present questions in random order click here

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 { ... }

STOP(string_argument) : Close interview and redirect respondent:

If an HTML file with the name string_argument.blk exists in the project rsc directory that page will be displayed. Othewise a url can be specified.

Example 1 : Close the interview and dispay the contents of HTML file bye.blk.

urlcp='bye' STOP(urlcp)

Example 2 : Redirect respondent to different web page (url) - for example a panel provider's web page.

urlqf='url=https://survey.xxxx.com/quotasfull' IF (CHECKQUOTA('Global') == 0) THEN { STOP(urlqf) }

Note: If using CAPMI then the text to be displayed should be entered directly as the argument to STOP.

STORE: store a variable to use it in javascript

NEWPAGE('jscript=display') STORE(myvar) ASK(Q1) ENDPAGE()

var display=function(){ var myvar=$('input[name=myvar]').val(); if(myvar==1) { ... } else { ... } }

In this example, if the variable 'myvar' is used in the javascript function 'display' then it must be present in the page to be used in the javascript. STORE allows the the variable to be present and used without actually displaying the variable.

STRING: string variable

To declare a text string variable.

s : STRING

STR_REPLACE: replace characters in a string

Return the characters from slabel after replacing "XXX" with "AAA" :

s=STR_REPLACE(slabel,"XXX","AAA")

The "STR_REPLACE" function accepts an optional 4th parameter that is used to define how/howmany replacements to make, as follows:

0 means "replace all occurrences"
1 means "replace the first occurrence" (default value if not specified)
-1 means "replace the last occurrence"
n means "replace n occurrences" (the first n, if n>0, the last n if n<0)

SUBLIST: returns part of a list

3 parameters:

A list:
- the name of a CHOICE question
- a set or list constant
- a function that returns a set or list (e.g. GETQLIST() or even another call to SUBLIST())
- a more complex expression involving any/all of the above combined with one or more of the list operators &, |, or \
An integer expression that specifies the (1-base) start position of the sub-list (counting from the start, if positive or the end, if negative)
An integer expression that specifies the number of items from the start position to return

SUBLIST({a,b,c,d},1,2) => returns {a,b} SUBLIST({a,b,c,d},-2,2) => returns {c,d} SUBLIST(lst_rot_brands,1,3) => returns the first 3 brands in list lst_rot_brands SUBLIST(Qbrands,1,5) => returns the first 5 brands selected in Qbrands (the order is based on the definition of the question)

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) }

TOFLOAT: Convert to a ''real/decimal'' number

Q1f=TOFLOAT(q1)

TOINTEGER: convert to a ''whole/integer'' number

Q1i=TOINTEGER(q1)

TOSTRING: convert to text

Q1t=TOSTRING(q1)

VARIABLES: Mark the start of the variable declarations section

VARIABLES n : INTEGER s: STRING

WARNING: warning message

The WARNING is often called in the CHECK.

IF(NOANSWER(Q1)) THEN WARNING(q1,"Please specify.")

XASK: Ask a question where the question to be asked is specified as a STRING variable.

This enables computations to be used to control when questions are asked.

Example: The order in which Q2 and Q3 asked depends on the response to Q1.

VARIABLES qtoask1 : STRING qtoask2 : STRING

ROUTE IF (Q1 IN {yes} THEN { qtoask1 = 'Q2' qtoask2 = 'Q3' } ELSE { qtoask1 = 'Q3' qtoask2 = 'Q2' } NEWPAGE() XASK(qtoask1) XASK(qtoask2) ENDPAGE()

Back to start