Functions

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

Note that date functions are not included in this list - see 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 {
             .....
   }

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

NOT: logical NOT

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

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

OR: logical OR

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

IF(Q1 IN {1} OR 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[i1])==1 AND ANSWER(age[i2])==1 AND etc..) THEN ...

If there are a lot of items, use a loop:

FOR i=1 TO 30 DO {
    xTEST("ANSWER","age[i"+TOSTRING(i)+"]")<>1 THEN ...
  }

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

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 {

### DISPLAYCANVAS: Display the [canvas](20103#canvas) table

DISPLAYCANVAS is used to display the table. If a [canvas](20103#canvas) is created with a BEGINCANVAS and and ENDCANVAS it will not be displayed without DISPLAYCANVAS

### 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.


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

Arguments:

1. The question in which the attribute is defined
2. The choice to which the attribute is associated
3. The attribute to be retrieved.
4. 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)

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

Built in FUNCTION.

Parameters: Returns:

Example

X=GETMODLABEL(XX)

-->

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

Built in FUNCTION.

Parameters: Returns:

Example

X=GETQARRAY(XX)

-->

### GETQATTR: Get the value of a question attribute

Used to get the value of a [question attribute](20102#qattributes).

Can be combined with [SETQATTR](#setqattr) to append text to the current value.

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

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

Built in FUNCTION.

Parameters: Returns:

Example

X=GETQLIST(XX)

-->

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

Built in FUNCTION.

Parameters: Returns:

Example

X=GETQNAME(XX)

-->

### GETQTEXT: get the question text of a question

Put the question text of variable f0 in s

s=GETQTEXT(f0)

### 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.")

<!--### PAGE: To be documented-->

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

<!--### PRINTCANVAS To be documented-->


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

### RESETQARRAY: Undo any changes made using the [SETQARRAY](#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](#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)

### 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](#setqlist) and [SETQARRAY](#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.


### SETBLOCK: [canvas](20103#canvas) instruction

SETBLOCK to set properties of cells in the [canvas](20103#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-weigh=bold")

### SETCANVAS: define the cells used in a [canvas](20103#canvas)

Defines the cells of the [canvas](20103#canvas) that will be displayed on the screen.

Display the 9 cells in rows 0-2 and columns 3-5 of [canvas](20103#canvas) ''c''

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

### SETQARRAY: Set the rows (or categories in other dimension) to be displayed in an [array](20102#dimension) 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](20102#dimension) 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)

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.

Examples of how to use SETQARRAY can be found by [clicking here](20103#setqarray)

### SETQATTR: Set the value of a question attribute.

To change the value of a [question attribute](20102#qattributes).

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.

See also: [GETQATTR](#getqattr)

### 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](20103#lists)

Note: See [SETQARRAY](#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](#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](#setqlist) and [SETQARRAY](#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](20103#shuffle)

### STOP(*string_argument*) : Close interview and redirect respondent:

If an HTML file with the name *string_argument*.blk exists in the project [rsc](30101) 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=http://survey.xxxx.com/quotasfull"

IF (CHECKQUOTA("Global") == 0) THEN { STOP(urlqf) }

Note: If using [CAPMI](40000) 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(mavariable) ASK(Q1) ENDPAGE()

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

In this example, if the variable "mavariable" 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.



### STR_REPLACE: replace characters in a string

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

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

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

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

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

Built in FUNCTION.

Parameters: Returns:

Example

X=XGETQLIST(XX)

-->

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

Built in FUNCTION.

Parameters: Returns:

Example

X=XGETQVALUE(XX)

-->

<!--
### XRANDOM: Creates an array of random numbers

VARIABLES rand[10] : INTEGER n : INTEGER FUNCTION XRANDOM RETURNS INTEGER

ROUTE IF(NOANSWER(rand[0])) THEN n = xRANDOM("rand") ``` -->