Interview Control Commands
Interview control commands controls operations during the interview, such as rotation of questions, keyword operation, and screen format.
AFTER_BLOW/END_AFTER_BLOW
You can specify a set of questions to execute at the time of a blow using the AFTER_BLOW block. Start the block with !AFTER_BLOW and end it with !END_AFTER_BLOW.
You cannot branch into or out of (GOTO, SKIPTO) an After_Blow block nor can you back out of the block. Interviewers cannot use keywords SPECIAL, SUSPEND, or TERMINATE while in this block.
AFTER_QUIT/END_AFTER_QUIT
Commands in this command block will be executed after the interviewer types “Quit” to end their interviewing session, or if the program forces them to quit by using a SYSTEM,SET_FOR_INTERVIEW_END command. This is typically used to gather summary information on the interviews or offer the interviewer options when they are quitting the session. It will create a separate data record from the one that is stored for the interview and it will generate its own case id. Use a SPECIAL,ABORT_INTERVIEW statement to abort out of the block if you don’t want to save a data case. GRID and CALL statements can be used within this block. However, you cannot ROTATE a block within this block.
ALLOW_ABORT
Allows the interview command ABORT. -ALLOW_ABORT is the default (unless ALLOW_ABORT is specified in the header statement) and need only be specified to override a previous ALLOW_ABORT.
ALLOW_BACKUP
Enables backing up in the interview using the caret (^) in terminal mode or the previous button in online mode after the point that it’s specified. The default is to allow backing up. -ALLOW_BACKUP will disable the caret (^) or previous button until the end of the interview or when another ALLOW_BACKUP is specified.
ALLOW_LANGUAGE_CHANGE
Controls whether the interviewer can change languages by typing “L=”. The default is to not allow unless the interviewer is in “debug” mode.
ALLOW_MONITOR
Allows monitoring of the following part of the questionnaire by SURVSUPR or SURVMON. This is the default and need only be specified after a -ALLOW_MONITOR has disabled monitoring.
ALLOW_RESET
Re-enables the Survent interview command RESET. The default is not to allow RESET.
-ALLOW_RESET will disable RESET until the end of the interview or an ALLOW_RESET is specified.
ALLOW_RETAKE
Re-enables the Survent interview command RETAKE. The default is not to allow RETAKE.
-ALLOW_RETAKE will disable RETAKE until the end of the interview or an ALLOW_RETAKE is specified.
ALLOW_SPECIAL
Enables the Survent interview command SPECIAL in terminal mode or enables the special button in online mode. The default is to allow the use of the special block. -ALLOW_SPECIAL will disable SPECIAL or the special button until the end of the interview or when another ALLOW_SPECIAL is specified.
ALLOW_SUSPEND
Enables the Survent interview command SUSPEND in terminal mode or enables the suspend button in online mode. The default is to allow suspends. -ALLOW_SUSPEND will disable SUSPEND or the suspend button until the end of the interview or when another ALLOW_SUSPEND is specified.
ALLOW_TERMINATE
Enables the Survent interview command TERMINATE in terminal mode or enables the terminate button in online mode. This default is to allow terminates. -ALLOW_TERMINATE will disable TERMINATE or the terminate button until the end of the interview or when another ALLOW_TERMINATE is specified.
ALLOW_TEXT_EDIT
Allows the interviewer to modify a TEXT question response in the on-line editor. This is the default. ALLOW_TEXT_EDIT will force the interviewer to re-enter the response for an EDIT question.
AUTO_RETURN
Causes responses to be accepted as soon as they reach their maximum length without the need for an Enter. An Enter will still be needed for responses having less than the maximum number of characters or responses.
For a single-response FIELD question, this would be as soon as the code is typed. For a multiple response FIELD question, this is when the maximum number of responses is typed.
For NUMERIC or VARIABLE questions, this is as soon as the maximum length of the question is reached. This is especially useful for keypunch type applications, where speed is important, or for self- administered questionnaires where you want to move directly from one screen to the next.
This can be disabled during a session with -AUTO_RETURN. AUTO_RETURN overrides HIGHLIGHT_CATS and ECHO_CATS.
Enter the response code of the desired choice and it will accept and move on immediately, without an additional Enter. You may also arrow through the list (on monitors; use Ctrl-U,D,R,L for terminals) to an item and then choose it with Enter , or enter a response code for a different item. For multiple-response questions, you’ll need to arrow to the appropriate code, then press INS or a plus sign (+) to accept.
BACKUP_HERE
This option controls where you will back up when using the BACKUP key, usually the caret (^), or previous button but also whatever key is specified on the “BACKUP: xx” parmfile command. By default you back up to the previous question asked, but if you specify BACKUP_HERE before a question and back up from a question further down in the questionnaire, it will back up all the way back to the question asked just after the BACKUP_HERE command. To return to regular backup mode, use the BACKUP_WHEREAT command.
BACKUP_WHEREAT
See the BACKUP_HERE command above. This returns you to regular backup mode.
BEFORE_SESSION/END_BEFORE_SESSION
This block executes as first set of questions in an interview session. This will be executed before the first interview of any questionnaire, similar to the other special blocks.
The syntax is:
BEFORE_SESSION <questions> END_BEFORE_SESSION
Use this to indoctrinate the interviewer or start counters. This can be used instead of using a flag in the local scratch area to only display a set of questions once.
COLOR_LIST
COLOR_LIST <color 1> <color 2> <color n>
The color list directive allows you to create a “color list” to assign colors to templates “on the fly” without having to know which question or screen is coming up next. These are used in rotations or questions where you want to maintain a consistent color scheme. As with many of the HTML commands, this does not get reset when backing up, so it should be put inside of a GRID statement. The maximum number of colors allowed is 32 and the default color is the first color listed. The colors should be specified as they are in HTML code, as either hexadecimal color codes or names.
Options:
- \cxc will display the current color
- \cxd will set the “current” color to the next in the list and display it
- \cxn will set the “current” color to the next in the list but will NOT display it
- \cx## will set the “current” to ## (nth color in the list) and display it
EXAMPLE:
{!COLOR_LIST BLUE, RED, YELLOW, GREEN }
NOTE: (See Color Lists for more information.)
DISPLAY_MODE
DISPLAY_MODE=terminal/webcati/websuper/ websurvent
This keyword controls what things are allowed in a compiled questionnaire. This is used to make sure you don’t use features that were designed for some other display mode.
The default for web surveys is {!DISPLAY_MODE=WEBSURVENT } to ensure that the specs conform to web standards.
ECHO_CATS
Places the interviewer in Echocats mode. -ECHO_CATS will turn it off. See the header option ECHO_CATS for more information.
ERROR_LEADIN
ERROR_LEADIN text
This command allows overriding the “ERROR #” leading text on error messages; typically this is to use some other language for the word “ERROR”.
NOTE: The text “ERROR: ” is in msgfile message #7222 and can be given other language equivalents there.
ERROR_MSG
ERROR_MSG #### text
If a respondent fails to answer a question or answers a question improperly, an on-screen error will display when they attempt to submit the page. Using ERROR_MSG will sets the value of the numbered message #### in the MSGFILE to “text”. This is so you can replace standard Survox error messages with your own error messages or warnings for a particular study without rebuilding the MSGFILE.
You can use this command more than once for the same message number if you want to change the message during the survey for specific questions.
EXAMPLE:
{!ERROR_MSG 7611 Please enter a valid value from 1 to 10 }
(Questions where this messages could occur)
{!ERROR_MSG 7611 Please enter a valid value }
If there are multiple languages in your questionnaire, you can include changed error messages for all languages using the syntax:
{!ERROR_MSG NNNN
xxNNNN <xx language message for NNNN>
yyNNNN <yy language message for NNNN>
NNNN <default message for NNNN> }
Where “xx” is the language and “NNNN” is the message number. You may use “back-references” to display prior responses in the message like you can with any other Survox question text. For instance, this adds the response to Q1 to the message:
EXAMPLE:
{!ERROR_MSG 1234 response does not match previous (\:Q1) }
NOTE: See HTML_ERROR/HTML_GRIDERROR below for more information on error messages.
FIELD_SAMEAS_USE_ORIGINAL_WIDTH
This controls what width to use when using the [SAMEAS label] feature on response lists. This has been added to allow users to set a default width for questions using the same list, in the case where you want to pre-allocate columns that may be used for coding later.
The default is to generate a width based on the standard formula for FIELD questions, which is (# codes allowed) * (code width). If the keyword above is specified, the program will use the width of the originating question instead; so if you have a width specified on the original question, or you allow more codes on the originating question, it will use the width generated for that question when assigning widths for the succeeding [SAMEAS label] using questions.
EXAMPLE:
{!FIELD_SAMEAS_USE_ORIGINAL_WIDTH }
{ QFIELD1:
QFIELD1 TEXT
!FIELD,,MAXIMUM_RESPONSES=5
01 CODE 1
02 CODE 2
03 CODE 3
04 CODE 4
05 CODE 5 }
{ QFIELD2:
QFIELD2 TEXT
!FIELD
[SAMEAS QFIELD1] }
In this case, QFIELD2 will have a width of 10 columns, because that was the width of QFIELD1. If the keyword was not there, QFIELD2 would have a width of 2 columns.
FILL_VIEW
VIEW mode by default shows the responses to questions as they are executed in the view session. This can cause some logic problems. For instance, if you have quota checking statements and the quotas have changed since the questionnaire was recorded, it could cause the logic to change.
FILL_VIEW says “Fill the answers to questions from the data regardless of the calculation in the VIEW session or whether the question is responded to”. In this way, HIDDEN questions and EXPRESSIONS will be filled exactly as they were filled in the original data.
NOTE: This may be a bit misleading within the VIEW session as some response will be displayed as if they were answered if queried when they were just used as a placeholder variable. This does not change the data that was actually recorded at the time of the interview, it is just a matter of how the VIEW session executes.
FLAG_DISALLOWED_CATS
Turns on the flagging of categories that are not allowed on FIELD_INCLUDE_EXCLUDE question lists. Turn back off again by using -FLAG_DISALLOWED_CATS.
GET_MARKET_ONLY
This command forces the interviewer to only get records from the specified market if you are using !PHONE,GET_FROM_MARKET to get numbers from a certain market. By default, if there are special interviewer numbers or timed numbers that are in a different market, the program will get those numbers for the interviewer, who must decide what to do with the numbers.
But if GET_MARKET_ONLY is specified, and a number is picked up from another market, the program puts it into Holding area (bucket #9) for the market it picked the number from. If you want these numbers delivered to someone else working in that market, make sure you use the RELEASE_HOLDING_AREA=Yes option to release those numbers and override the MINIMUM SYSTEM CALLBACK TIME for the number and call it immediately. You can disable this with -GET_MARKET_ONLY.
GRID/ENDGRID
Grids are used in Survox’s Web programs any time you want to put more than one question on the screen at the same time. To specify a grid, type the {!GRID} command followed by your questions, then {!END_GRID}.
By default, grids require that all questions be answered. You may specify that particular questions may be unanswered by using the question subype “BLANK_OK” on that question, or you may specify GRID,BLANK_OK if you wish to allow all questions to be left blank or unanswered.
Grids may have a !ROTATE/!ENDROTATE block inside of a GRID to rotate lists of attributes to be rated or other items on FIELD questions. Grids show any answers previously responded to, even when backing up to the grid. Without a grid, some questions will not keep their answers when you back up to them. Therefore, some questionnaires have every question that requires a response contained inside of a GRID.
You will often build HTML “tables” for formatting inside of grids. The tables are generally used to group similar questions so that they are formatted in columns and rows. The HTML syntax starts with “<table>” and ends with “</table>”.
When you make Web pages inside of GRID statements, keep in mind how much information you want to display per page; if you display too much information, the respondent will have to do a lot of scrolling. If you don’t put enough questions on each page, the respondent will have to click on the “next” button more often.
A few additional rules to using Grids:
- We recommend that all GRID statements have a label; A label on the ENDGRID statement is optional
- You can include conditions on the GRID statement that applies to all questions on the page
- You cannot skip “INTO” a grid but you can goto a Grid label
- You cannot skip “OUT” of a grid
- You cannot rotate grids using a !ROTATE statement
- Any Javascript calls must be inside of the GRID/ENDGRID statements
- Any ENDGRID_ERROR statements must be inside of the GRID/ENDGRID statements
- You cannot program EXPRESSION, GENERATE, or Alias type of questions inside of GRID/ENDGRID statements
- You cannot set HTML_DEFINE variables inside of the GRID/ENDGRID statements
- Grid statements do not take up any data locations and will not be displayed in the CHK file
EXAMPLE:
{ GRIDLABEL:
!IF CONDITION (OPTIONAL)
!GRID }
QUESTIONS...
{!ENDGRID }
HIGHLIGHT_CATS
HIGHLIGHT_CATS option(s)
Creates a special screen format for field type questions. The user is positioned on the first category, which is highlighted. For single-response questions, to accept the category, the user presses an ESC or Enter (unless = was used as the first code; interviewer must first move to a valid response). To move to another category, the user types the response code, or uses the arrow keys (on a monitor; use CTRL-U,D,R,L on a terminal) to move to the relevant category.
For multiple-response questions, the space bar or “+” key is used to accept a response, and the space bar or “-” key takes away an accepted response (monitors can use the INS and DEL keys; terminals can use Ctrl-N in addition to the “+” key and Ctrl-P in addition to the “-” key). ESC or Enter accepts the question after all responses have been marked. This is especially useful for self-administered questionnaires.
This can be turned off during a session with -HIGHLIGHT_CATS. You can specify various options after HIGHLIGHT_CATS to control what type of questions to use it on and what to do when a response is specified.
The options ALL, SINGLE, and MULTIPLE, control which types of questions to apply HIGHLIGHTCATS to. ALL is the default, SINGLE affect single response questions only, and MULTIPLE affects multiple response questions only.
The options ERASE and SELECT control what to do when an item is picked. SELECT puts highlightcats in SELECT mode on whatever question type is specified. SELECT mode is the standard mode for multi-reponse lists, where you must select a code using the spacebar or “+” key or INS key to go on. Specifying HIGHLIGHTCATS ALL SELECT forces single response questions to be treated the same as multiple response questions.
The option ERASE causes the text for the response to be ERASED when chosen. It can also be used with the ALL, SINGLE, and MULTIPLE statements.
HTML_<keyword>
You can control the standard display of different parts of the question by using commands.
NOTE: (See HTML Enhancements for more information.)
KEEP_RESPONSE_CODES
This displays the response code in addition to the text of the response when using \#(LABEL) or \:LABEL: to display the answer to a response list item. For instance, it will display something like “01 Likes Apples” instead of just “Likes apples” when back-reference a question which was answered with “01”.
LANGUAGE SET
LANGUAGE SET=(lang1 lang2 langn) CHARACTER_SET=charset SPEAKING=langx
The compiler directive LANGUAGE controls what languages you are using and which character set. SET= IS required. The languages being used can have two character codes or can have the two character codes converted to a 1 character code for ease of coding.
EXAMPLE:
{!LANGUAGE SET=(e=en f=fr s=sp) }
This says to use English, French, and Spanish, and allow coding of them as 1 character codes in the questionnaire (eg. \le, \lf, \ls).
NOTE: It is best practice to keep the two character codes.
The “character sets” are UTF8 or Extended_ASCII.
NOTE: It is best practice to use UTF8 as the default which allows all character sets.
The “Speaking=<language>” parameter would be used if you want to set the starting and default language; if you don’t specify it defaults to the first language on the list.
MAXIMUM_CONSECUTIVE_BACKUPS
MAXIMUM_CONSECUTIVE_BACKUPS=#
This command controls the number of consecutive backup commands that can be issued.
Backup commands include clicking on the previous button, using the caret “^”, “reset”, and “retake.”
You can enter MAXIMUM_CONSECUTIVE_BACKUPS=1 to only allow users to back up one question at a time without going forward again. Since users have to retype data (or use the ”=” command to save the answer) after backing up multiple questions, this will keep them from mistakenly losing their answers.
In addition, commands BACKUP_HERE and BACKUP_WHEREAT allow you to control where interviewers or respondents back up to if necessary when they enter “^” to back up or click the previous button. This allows you to force respondents to start at the top of a section when they back into the section. Intermediate questions are cleared.
READ_NAMED_QUOTAS
This does an immediate read of the quota file as it now stands. This eliminates the need for many QUOTANOW functions. This can be done anywhere in the questionnaire, but is usually used at the point in the questionnaire that you are doing quota checks. Any subsequent QUOTA functions will reflect the values at the time of the READ.
RESPONSE_LIST_COLUMNS
RESPONSE_LIST_COLUMNS=#
This allows you to have an even number of codes in each column for as many columns desired on a screen (as long as the items will all fit). This lets you have a more standardized format for your lists as they are displayed on the screen.
If you are using Highlightcats mode, the program will split the codes into columns across pages.
If you use “1” as the number of columns, you will force Survent to put each item on a separate line.
The maximum number of columns you can specify is 4. If Survent cannot display the list in the number of specified columns, it will reduce the number of columns to make it fit.
RESUME/END_RESUME
These commands mark a block of questions for execution when an interview is resumed. Questions are otherwise ignored. You cannot branch into or out of (GOTO, SKIPTO) a Resume block.
GRID and CALL statements can be used within this block. Interviewers may not type SPECIAL, SUSPEND, or TERMINATE while in this block.
NOTE: You cannot ROTATE blocks inside these blocks.
RESUME_HERE
Interviews suspended after this statement will come back here to start. Often used at the beginning of a block of related questions, such as before a Rotate block. Use as many in a questionnaire as needed. Using the RESUME_HERE command guarantees that all iterations of a given rotation will be re-executed when the interview is resumed.
RESUME_WHERE_AT
Used after a RESUME_HERE to say “resume at the question suspended at” from now on. This is the default and need only be specified to turn off a previous RESUME_HERE. Use as many in a questionnaire as needed.
ROTATE/ENDROTATE
ROTATE,type,#,label
Begins a Rotate block, causing the questions to be asked in some type of rotating order (for specific information on types and uses, see ROTATIONS).
END_ROTATE Ends the Rotate block. This is placed at the end of the questions to be rotated. Required with ROTATE.
FIX,n
Within a Rotate block, this fixes the position of the next N questions. This must follow a ROTATE command. If N is specified, that number of questions cannot include other rotate commands. If N is omitted, all questions until the next relevant command (FIX, GROUP, or END_ROTATE) at the same rotate level are fixed. You cannot fix the first question inside a Rotate block. (For more information see the FIX AND GROUP section in ROTATING QUESTIONS.)
GROUP,n
Within a Rotate block, this keeps the next N questions together as a group when they are rotated. This must follow a ROTATE command. If N is specified, that number of questions cannot include other rotate commands. If N is omitted, all questions until the next relevant command (FIX, GROUP, or END_ROTATE) at the same rotate level are grouped. (For more information, see the FIX AND GROUP section in ROTATING QUESTIONS.)
RECODE_ROTATE_ORDER
RECODE_ROTATE_ORDER,label,[noblow]
The RECODE_ROTATE_ORDER compiler directive stores the order of the response codes in a FIELD type question asked in a following ROTATE block. It will work for all rotate types, but is most useful when a ROTATE,SCRAMBLE is used as there is no easy way to record the order.
The syntax for the RECODE_ROTATE_ORDER is:
{ QLABEL: <location.length> HIDE
!VARIABLE }
{!RECODE_ROTATE_ORDER,QLABEL,[noblow] }
You first need a question to store the result in. This needs to be big enough to store the order. For instance, if you have 101 codes, it needs to be 3 * 101 = 303 columns long to store the order for all codes.
Then the statement just requires RECODE_ROTATE_ORDER,LABEL. It will store the position of the codes in the order they are asked, for instance, “4321” if the fourth code was displayed first, the third code displayed second, the second code displayed third, and the first code displayed last.
NOTE: Best practice is to always turn off the RECODE_ROTATE_ORDER using a -RECODE_ROTATE_ORDER.
If you have five ROTATE blocks but only one RECODE_ROTATE_ORDER statement, each ROTATE block in succession will save its order to the question referenced in the RECODE_ROTATE_ORDER statement unless you use -RECODE_ROTATE_ORDER to turn it off.
Sometimes you will only want to record the first “N” items asked; to do so, set the variable length to the length needed for that many items and add the parameter NOBLOW to the statement. This will allow the program to save just that many items without blowing due to lack of space.
ROTATE_ORDER
ROTATE_ORDER,label,[asked,noblow]
The ROTATE_ORDER compiler directive stores the order of the questions asked in a following ROTATE block. It will work for all rotate types, but is most useful when a ROTATE,SCRAMBLE is used, as there is no easy way to record the order.
The syntax for a ROTATE_ORDER is:
{ QLABEL: <location.length> HIDE
!VARIABLE }
{!ROTATE_ORDER,QLABEL,[asked,noblow] }
You first need a question to store the result in. This needs to be long enough to store the order, for instance, if you have 101 questions, it needs to be 3 * 101 = 303 columns long to store the order for all questions.
Then the statement just requires ROTATE_ORDER,LABEL. It will store the position of the questions in the order they are asked, for instance, “4321” if the fourth question was asked first, the third question asked second, the second question asked third, and the first question asked last.
NOTE: Best practice is to always turn off the ROTATE_ORDER using a -ROTATE_ORDER.
If you have five ROTATE blocks but only one ROTATE_ORDER statement, each ROTATE block in succession will save its order to the question referenced in the ROTATE_ORDER statement unless you use -ROTATE_ORDER to turn off the storing of rotate orders.
To limit the list to the questions that are askable, for example, to exclude GENERATE or EXPRESSION statements in the rotate, add the parameter ASKED.
To record only the first “N” items asked, set the variable length to the length needed for that many items and add the parameter NOBLOW to the statement. This will allow the program to save just that many items without blowing due to lack of space.
NOTE: Both ASKED and NOBLOW can be used together.
SET_INTERVIEWER_CAPABILITIES
SET_INTERVIEWER_CAPABILITIES=+ – options
This allows you to change interviewer capabilities on the fly. Be careful when toggling TRAINING MODE on and off because it will cause you to lose data if you turn it on during a real interview. But this allows you to make a menu of options instead of using the keywords at the Survent command prompt.
Valid Options
- B Can Abort or Break or Change interviews.
- C Can Change interviews.
- D DEBUG mode (overrides interviewer controls, allows GOTO forwards and backwards, can Abort, Break or Change interviews).
- N Interviewer has no capabilities, and cannot VIEW prior interviews.
- E interviewer started in Echocats mode.
- L do interviewer logging and save at end of interview.
- Q do interviewer logging and save after every question.
- T interviewer started in Training mode.
The syntax for the SET_INTERVIEWER_CAPABILITIES is:
SET_INTERVIEWER_CAPABILITIES=BCDENTLQ
For more information on these options, refer to SPECIAL,EMPLOYEE_FILE_INFO which describes each of these in more detail.
Using “+” before the list of letters means the capability will be in addition to whatever is already set, using “-“ means to remove that capability from the interviewer.
SHOW_LAST_RESPONSE
This allows you to show what was entered on the previous question at the bottom of the current screen, if space is available. This is useful so that users don’t have to back up to remember what the answer was to the previous question. This, of course, will only show the very last response and not the contents of grids or within a grid. If more than one line of information was entered, the line is truncated. -SHOW_LAST_RESPONSE turns off the directive.
SHOW_QUESTION_LABELS
SHOW_QUESTION_LABELS=option
Displays question labels in the corner of the interviewer’s screen. The default is to not show them.
Options are UR to show in the upper right corner, or LR to show in the lower right corner.
SPECIAL/END_SPECIAL
These compiler commands mark a block of questions for execution when an interviewer enters the keyword SPECIAL or clicks on the SPECIAL button. This can be done at any place in the questionnaire except in Suspend or Resume blocks, and can be done more than once during an interview, so put some logic in the Special block to control what happens if you enter the block more than once. At the end of the block the interviewer or respondent will return to the point in the questionnaire where she/he had entered SPECIAL or clicked the SPECIAL button.
You may put this block anywhere in the questionnaire; in the normal flow of the interview, the program will branch around this block without you having to tell it to. You can programmatically execute the Special block by using a SPECIAL, GOTO_SPECIAL_BLOCK command. You may not skip to a question inside a Special block, or skip out of one. GRID and CALL statements can be used within this block. Interviewers may not use commands SPECIAL, SUSPEND, or TERMINATE while in the Special block. They may, however, use the caret (^) or click the previous button to back up within a Special block (and possibly back up out of it as well or, having finished the block, back up into it again). You cannot ROTATE a block within this block.
START_CD_BLOCK/END_CD_BLOCK
There are multiple HTML commands that you can use to give your surveys a certain look. These blocks of commands can be used in conjunction with the SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK command that can be used when you want to have the same look and feel from screen to screen on your Web surveys.
You can define a block of these commands and call them anywhere in your spec where you want to use them. All defined blocks MUST begin with a LABEL that is the “name” of the block. All defined blocks begin with a START_CD_BLOCK and end with a END_CD_BLOCK.
EXAMPLE:
{ DEFAULT: !START_CD_BLOCK }
{!HTML_ } COMMANDS
Place all !HTML commands to be used in this block.
It is recommended that you define all of the !HTML commands for a particular cd block
to insure that all commands are set exactly as you intend them to be.
{!END_CD_BLOCK }
The above example will create a Compiler Directive block called Default. When you want to use this block of code in your spec, simply place a SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK,DEFAULT command that references the name of the block in front of any questions where you’d want to use it.
NOTE: (See HTML Enhancements for more information).
STATUS_BAR
STATUS_BAR <display option>
A status bar may be added to all webSurvent or webCATI screens to show a respondent or interviewer how far along they are within the survey. By default, Survent will provide a percent based on the question number the respondent or interviewer is on. The percent displayed is controlled within the spec.
The following syntax is used to update the value on the status bar:
{!STATUS_BAR <qq/##/val=\|statusbr|> }
Status Bar Options:
- qq – This is the default. QQ is calculated by the current question / total # of questions and will display the percentage that the respondent or interviewer has advanced through the survey.
- “##” – ## sets the status bar value to a specified number. The value must be between 1-100.
- val=\|qlabel| – Assigns a value calculated within the spec using an EXPRESSION type question. The value must be between 1-100 and this is the best practice method if there are many rotations within the survey.
The program will update the percentage each time it sees a new STATUS_BAR “##”, “qq”, or “val=” option.
NOTE: (See Using a Status Bar for more information)
SUSPEND/END_SUSPEND
These commands mark a block of questions for execution when an interviewer enters the keyword SUSPEND or clicks on the SUSPEND button. Questions are otherwise ignored. You cannot branch into or out of (GOTO, SKIPTO) a Suspend block, but you can back out of one by using the caret (^) or clicking the previous button. GRID and CALL statements can be used within this block. You can programmatically execute the Suspend block by using an SPECIAL,FORCE_SUSPEND command. Interviewers cannot use keywords SPECIAL, SUSPEND, or TERMINATE while in this block. You cannot ROTATE a block within this block.
VIEW/VIEWX
These commands will turn on or off the allowing of View mode for a section of the questionnaire. -VIEW will turn off View mode for a particular section of the questionnaire until another VIEW or VIEWX is seen. Use this to cause quota checks and choose procedures based on quotas not to be re-executed during the viewed interview.
!-VIEWX will not show questions in that section but will execute them. Use -VIEWX when you don’t want to see a block of questions in View mode, but still need them executed (skip patterns, for example), so that the interview will behave the same as the original.
VIEW_QUOTA
VIEW_QUOTA=letter
This controls how Survent will evaluate QUOTA functions read while in View mode. The default is that IF conditions with quotas on them will be false and EXPRESSION questions will return a “0” for the quota value. This is to avoid complications trying to execute the questionnaire using current quota values when the data was collected with quotas that probably were different.
VIEW_QUOTA=E means “evaluate”, and it will return whatever the current value is for the quota reference in the quota file.
VIEW_QUOTA=F will return False for IF conditions and is the default.
VIEW_QUOTA=N will return 0 in EXPRESSION QUOTA() references and is the default.
VIEW_QUOTA=T will return True for IF conditions and EXPRESSION QUOTA() references will
return 1.
VIEW_QUOTA is overridden by -VIEW; if -VIEW is set, the whole section will not be executed.
VIEWX after -VIEW will return control to the VIEW_QUOTA.