Odin reference
Odin is QubeSurvey’s compatibility language for questionnaires written in the established NIPO ODIN style. QubeScript is the default for new work; use Odin when an existing script or your team’s experience makes it the practical choice. Each language has its own parser and interview engine. Both share Scripts, versions, Runs, participants and exports.
This reference describes QubeSurvey’s implementation. QubeSurvey uses its own parser and runtime and follows established Odin syntax and behaviour for the supported CAWI commands. Ordinary CAWI scripts written here should be practical to exchange with NIPO. Test routing, answers, display and exports in QubeSurvey and in the particular NIPO version you need to exchange it with. The section Differences from NIPO Odin lists what is known to differ, so you can judge an exchange before you rely on it.
Local CAWI testing and hosted fieldwork have separate capability checks. Upload preparation reports commands outside the hosted collection subset.
How this page is organised
- Files and lines — what a script looks like.
- Questions — question types and their answer shapes.
- Answers and validation — options, bounds and controls.
- Forms, scales and grids — multi-field pages and ratings.
- Data positions — fixed-record fields and their widths.
- Expressions — conditions, code tests and string functions.
- Variables and calculations — variables,
*PUT,*COPY,*FORMAT. - Routing and reusable sections —
*IF,*GOTO,*SUBROUTINE. - Repetition —
*REPEAT,*REPNUM,*FIELD. - Order, randomisation and control — presentation order.
- Presentation — pages, help, fonts and layout hints.
- Languages — translated sections.
- Endings — how an interview stops and what is recorded.
- Host and environment commands — sample, SQL, clock and files.
- Metadata retained on import.
- Recognised names without supported execution.
- Command index — every name QubeSurvey recognises.
- Differences from NIPO Odin.
- Checking, testing and hosting.
Files and lines
NIPO questionnaires conventionally have DOS-style filenames without an
extension, with the leafname ending in q, such as p1234q. QubeSurvey uses
.odin for VS Code language recognition, so an editor copy might be named
p1234q.odin. That suffix is a QubeSurvey integration convention, not the NIPO
naming convention. Keep the extensionless name when you hand the script to NIPO.
See Using existing Odin scripts.
Source may be UTF-8, UTF-16 (with or without a byte-order mark) or a single-byte legacy encoding such as cp1252. QubeSurvey detects the encoding when it reads the file; an existing script does not need converting first.
Rules for reading and writing source:
- Commands begin with
*and are case-insensitive.*QUESTIONand*Qare the same command. **starts a comment that runs to the end of the line.- Each line is one statement, or a question header, or body text. Several commands may share a line after a question header or a code line.
- Whitespace inside wording, labels and display text is significant, including
tabs. Tabs align columns in
*FORM,*SCALEand*GRIDbodies. - A question starts with
*QUESTION <number>(or*Q) and stays open until the next command that closes it. Its wording and its numbered answer codes follow on their own lines. - Compact headers such as
*Q200mean*Q 200and are accepted.
Blocks come in two kinds:
| Kind | Blocks | Ends at |
|---|---|---|
| Header blocks | *QUESTION, *FORM, *INTRO, *INFO, *PAGE, *PNW, *INSTRUC, *HELP, *LIST, *LANGUAGE | the next command or block that replaces it |
| Explicit blocks | *INIT, *REPEAT, *SUBROUTINE, *CONJ | its own closing command |
Explicit blocks close with *END (*INIT), *ENDREP, *ENDSUB and
*ENDCONJ. Nothing else closes them.
These examples are independent small scripts, not consecutive sections of one questionnaire. They use invented content. Examples labelled local profile or host context show syntax outside ordinary hosted collection.
** One question, followed by normal completion.
*QUESTION 1 *CODES L1
Did you use the shared workspace this week?
1: Yes
2: No
*Q 2 *ALPHA L20 *NON
Optional note:
*ENDThe script above shows the two shapes you read most often: a coded question and
a text question. *NON makes the second question optional. *END closes the
interview normally.
Questions
A question’s type determines the answer it collects and the control the respondent sees.
| Type | Answer | Notes |
|---|---|---|
*CODES | One code, or several with *MULTI | The ordinary choice list. |
*ALPHA | Free text, single line | Width comes from the field length. |
*OPEN | Free text, verbatim box | Displayed as a larger text input. |
*NUMBER | A number | L3 allows whole numbers; L3.2 declares two decimals. |
*LINE | A bounded numeric position | Rendered as a slider; a negative *MAX asks for a vertical one. |
*SCALE | A point on a rating scale | Defaults to 7 points; *MAX sets the count (2–26). |
*FORM | One answer per numbered field | Each field carries its own type and constraints. |
*DUMMY | A value the respondent never sees | Filled by *COPY, *PUT or a calculation. |
*QUESTION 2 with no type is legal. It is a display page: it shows its wording
and continues, and it is the usual target of a *GOTO.
A *FORM question puts numbered input fields on one page. Each field names its
own type: 1: Seats: *NUMBER L2 *MIN 1 *MAX 20 is a numeric cell and
2: Note: *ALPHA L30 *NON is an optional text cell. The form example
shows a complete question.
Form field numbers are optional. A line such as Day *NUMBER L2 still defines a
real field; QubeSurvey structures and renders it as one.
Answers and validation
Answer behaviour is set by commands on the question header or on an individual code line.
| Command | Effect |
|---|---|
*MULTI | More than one answer. On *CODES it also changes the stored shape. |
*NON | The answer may be left blank. |
*MIN, *MAX | Bounds for a number, line or scale; the allowed count for a multiple answer. |
*RANGE | An allowed value or interval, written in brackets. |
*NMUL | Marks an exclusive code in a multiple-answer question. |
*BUT | A supplementary button answer, such as “Unsure”, outside the ordinary scale. |
*OPEN | On a code line: an attached text box for that code. |
*SAVE | Copies the answer into a declared variable. |
*RANGE takes an interval, a list of values, or both:
*RANGE [0 TO 100;999] allows 0–100 and the separate value 999.
A range is a validation rule; it does not change which options are displayed.
*QUESTION 1 *NUMBER L3 *MIN 0 *MAX 365
How many days did you use the workspace in the last year?
*QUESTION 2 *NUMBER L3.2 *RANGE [0 TO 100;999]
Monthly cost in units; enter 999 if unknown.
*QUESTION 3 *LINE L3 *MIN 0 *MAX 100
How likely are you to return, from 0 to 100?
*QUESTION 4 *OPEN L120 *MULTI
What would you change?
*ENDSpecify decimal precision explicitly. *RANGE [0 TO 10;99] permits the interval
0–10 and the separate value 99.
*TEXTVARS other
*QUESTION 1 *CODES L3 *MULTI *MIN 1 *MAX 2
Which facilities did you use?
1: Desks
2: Meeting rooms
3: Other *OPEN L30 *SAVE other
9: None *NMUL
*QUESTION 2 *NUMBER L2 *MIN 0 *MAX 30 *BUT 99 "Unsure"
How many visits did you make this month?
*END*SAVE copies the answer into a declared variable. An attached open field can
save its text separately; the text variable receives the typed value, not the
code. *NMUL keeps “None” exclusive: a proposal that combines it with another
code is rejected without being stored. Keep “None”, “Not applicable” and
“Unsure” distinct when the analysis needs different bases. *BUT appears as a
button beside the input, not as a numbered choice.
Forms, scales and grids
*SCALE defines a rating scale; *LEFT and *RIGHT label its ends. The default
is 7 points. *GRID declares a grid field inside a *FORM, including its
geometry in the positional arguments. *TAB sets layout tab positions. Check the
rendered result on a narrow screen.
*TAB 30
*QUESTION 1 *FORM
Your booking:
1: Seats: *NUMBER L2 *MIN 1 *MAX 20
2: Note: *ALPHA L30 *NON
*QUESTION 2 *SCALE L1 *MAX 5 *LEFT "Poor" *RIGHT "Excellent"
How was the booking process?
*END*SCALERANGE sets the stored values of subsequent scale boxes. A single value
starts an offset sequence; an explicit set assigns values individually. The
command without an argument restores the default sequence. The visible labels stay
1, 2, 3 … while the stored values follow the range.
*SCALERANGE [0;1;2;3;4]
*QUESTION 1 *FORM
Rate each item from 0 to 4:
1: Booking: *SCALE L1 5 10
2: Equipment: *SCALE L1 5 10
*SCALERANGE
*QUESTION 2 *SCALE L1 *MAX 5
Overall rating from 1 to 5:
*ENDA *GRID argument pair gives rows and column text spacing, then columns and
spacing: *GRID L4 3.2 2.1 is three rows, two columns, with spacing hints. A
single grid stores one code per column; a *GRID *MULTI stores one character per
cell, so its length must be at least rows × columns.
*QUESTION 1 *CODES L3 *MULTI
Which spaces did you visit?
1: North room
2: South room
3: Studio
*TAB 20,30,40
*QUESTION 2 *FORM *VCONTROL Q1 W
Rate the spaces you selected:
1: Poor *GRID L4 3.2 3.10
2: Adequate
3: Good
*ENDData positions
A length such as L3 gives the answer a field in the fixed-width record. A
preceding number fixes the field position, as in 101L2. Positions are 1-based;
the first 60 bytes are administrative and interview data conventionally starts at 61.
| Declaration | Record footprint | Stored form |
|---|---|---|
101L2 | 2 bytes, at 101–102 | Positioned field; alignment follows the type |
*CODES L3 | 3 bytes | Selected code number as digits |
*CODES L3 *MULTI | 3 bytes | One byte per code: 1 selected, 0 not |
*CODES L3 *MULTI L4 | 3 + 4 bytes | Bitmap, then mention order as zero-padded codes |
*NUMBER L3.2 | 5 bytes | Scaled integer with an implied decimal point |
*ALPHA L20 | 20 bytes | Left-aligned text |
*OPEN L20 | 20 bytes | Coded positions; the verbatim text stays in the answer store |
Two consequences follow.
- A decimal field occupies
len + decbytes. There is no byte for the decimal point, soL4.1needs five bytes. - A
*MULTIquestion stores one byte per code, so the length must reach the highest code. The optional second length is a separate mention-order field.
A question with no length or position is still asked and still keeps its answer in the interview record; it simply has no column in the fixed-width record. Add a length when the export or a legacy U-file needs the column.
Unfixed lengths are resolved top to bottom into free positions. Mixing authored positions and unfixed lengths is normal: authored positions are kept verbatim and unfixed lengths fill the gaps. Use fixed, non-overlapping positions when an existing record layout matters.
*QUESTION 1 *CODES 61L3 *MULTI L2 *MIN 1 *MAX 2
Which facilities did you use?
1: Desk
2: Room
3: Locker
*QUESTION 2 *NUMBER 66L3.2 *MIN 0 *MAX 999.99
Monthly cost in units:
*QUESTION 3 *ALPHA 71L20 *NON
Anything else?
*QUESTION 4 *CODES 91L1
Continue?
1: Yes
*END*CODES 61L3 *MULTI L2 uses three bytes for the bitmap and two for mention
order, because a one-digit code needs one byte per mention and two mentions are
allowed. 66L3.2 then needs five bytes, 66–70, so the next field starts at 71.
Expressions
Conditions, calculations and variable references are written inside square brackets.
| Expression | Meaning |
|---|---|
Q1 | The answer to question 1. |
Q1,2 | True when code 2 was selected. |
Q1,1;3;5 | True when any of those codes was selected. |
Q1,2-5 | True when a code in the range was selected. |
Q4F2 | Field 2 of form question 4. |
Q4F(?R) | A form field chosen by the repetition number. |
Q1M1 | First mentioned code of question 1. |
Q1R1 | First displayed code of question 1. |
?R | The current repetition number. |
RAN 10 | A seeded integer from 0 to 9. |
#Q2,1 | Negation. # is Odin’s Boolean NOT. |
[a + b * 2] | Arithmetic. |
[Q1,1 & Q2 > 0] | Both conditions. \ combines alternatives. |
[value = 2], [value <> 2] | Equality and inequality. |
[1;3;5], [1 TO 5] | A code set and an inclusive range. |
Operator precedence, lowest first, is: \ (or), & (and), comparisons, + -,
* /, unary # - +. Comparisons chain left to right, so 99 > Q40 > 74 means
(99 > Q40) > 74. Split intended chains with &; QubeSurvey reports the chain
as a finding.
String functions
These functions are available in expressions. They count characters, not bytes.
| Call | Result |
|---|---|
STRLENGTH(s) | Number of characters. |
STRINDEX(s, part) | One-based character position of part, or 0. |
STRSUBSTR(s, start, length) | Substring from a one-based start; a length of -1 means “to the end”. |
STRUPPER(s), STRLOWER(s) | Upper- or lower-case text. |
STRTRIM(s) | Text without surrounding whitespace. |
STRHASMATCH(s, pattern) | 1 when the regular expression matches, otherwise 0. |
STRFINDMATCH(s, pattern) | The first matching text, or empty text. |
*TEXTVARS note,short
*VARS size
*QUESTION 1 *ALPHA L40 *SAVE note
Your booking reference:
*PUT short [STRSUBSTR(note, 1, 3)]
*PUT size [STRLENGTH(note)]
*QUESTION 2 *CODES L1
Reference *? short has *? size characters.
1: Continue
*END*? short prints a text variable and *? size a numeric one. Calculate first
with *PUT; there is no general expression display.
Printing values
*? inserts a variable into displayed text. It does not read a question
answer directly: use *SAVE, *COPY or *PUT to place the value in a variable
first. Numeric variables print blank while they are zero and no *FORMAT is
active.
A name resolves by the longest declared prefix, so a declared LANG followed by
literal text Small prints the variable and then the word. *? 0 through
*? 9 read the numbered system variables. *? [expression] also selects a
numbered system variable from the result, as the NIPO DLL does; the result must
be 0–9 and anything else prints nothing. Use *PUT when you want to display a
calculated value.
Variables and calculations
Declare numbers with *VARS and text with *TEXTVARS. Both take a
comma-separated list. An array takes a size, such as order[3]; indexes start at
- Names are case-insensitive and are stored in upper case.
| Command | Effect |
|---|---|
*PUT name [expression] | Assign a calculated value. |
*PUT name "text" | Assign literal text. |
*COPY target source | Copy the interpreted answer or value. |
*MOVU target source | Copy literal record-field contents, including padding. |
*INCLUDE Qn [codes] | Add codes to an answer. |
*EXCLUDE Qn [codes] | Remove codes from an answer. |
*COUNT var Qn | Store the number of selected codes. |
*FORMAT width.decimals | Format subsequent numeric-to-text output. |
*COPY uses answers as values, so [Q1M1] copies the first mentioned code and
[Q1R1] the first displayed code. *MOVU copies the raw field, so field lengths
and positions matter. *INCLUDE and *EXCLUDE change the stored answer, not
just what the next page displays.
*FORMAT pads the number to a total width and states how many decimals to show.
*FORMAT 6.2 renders 7 as 7.00. It changes presentation only; the answer’s
declared precision is unchanged.
*VARS visits,total
*TEXTVARS message
*QUESTION 1 *NUMBER L2 *MIN 0 *MAX 30 *SAVE visits
Visits this month:
*PUT total [visits * 2 + 1]
*PUT message "Estimated points"
*FORMAT 3.2
*QUESTION 2 *CODES L1
*? message: *? total
1: Continue
*ENDThe answer-copying example below runs in the local interview engine. Hosted
fieldwork currently refuses *COPY, *MOVU, *INCLUDE and *EXCLUDE.
*VARS selected
*QUESTION 1 *CODES 101L3 *MULTI
Choose facilities:
1: Desk
2: Room
3: Locker
*QUESTION 2 *CODES 104L3 *MULTI *DUMMY
Copied selection
1: Desk
2: Room
3: Locker
*COPY Q2 Q1
*INCLUDE Q2 [3]
*EXCLUDE Q2 [2]
*COUNT selected Q2
*QUESTION 3 *CODES 107L3 *MULTI *DUMMY
Literal field copy
1: Desk
2: Room
3: Locker
*MOVU Q3 Q2
*QUESTION 4 *CODES 110L1
Number selected: *? selected
1: Continue
*ENDRouting and reusable sections
*IF runs its actions when the condition is true; *ELSE supplies the other
branch. On a question header, *IF controls whether the question is asked.
*GOTO jumps to a question number. A question reached by ordering alone is still
asked in source order when nothing routes away from it.
*QUESTION 1 *CODES L1
Did you use a meeting room?
1: Yes
2: No
*IF [Q1,1] *GOTO 2 *ELSE *GOTO 3
*QUESTION 2 *NUMBER L2 *MIN 1 *MAX 30 *IF [Q1,1]
How many room bookings did you make?
*QUESTION 3 *CODES L1
Would you recommend the workspace?
1: Yes
2: No
*ENDDefine a named section with *SUBROUTINE and *ENDSUB, enter it with *GOSUB
and return with *RETURN. Define it once; the runtime preserves the call context
of its answers. Keep subroutine nesting shallow and avoid recursion in
questionnaires.
*TEXTVARS item
*SUBROUTINE rating
*QUESTION 2 *NUMBER L1 *MIN 1 *MAX 5
Rate *? item from 1 to 5:
*RETURN
*ENDSUB
*PUT item "booking"
*GOSUB rating
*QUESTION 3 *CODES L1
Thank you.
1: Continue
*END*INIT marks a section that runs before the first page. Its closing *END
continues into the questionnaire instead of finishing the interview.
*VARS initial
*INIT
*PUT initial [4]
*END
*QUESTION 1 *NUMBER L1 *MIN 0 *MAX 9
The initial value is *? initial. Enter your own value:
*ENDRepetition
*REPEAT and *ENDREP repeat a block. *REPNUM n: selects actions for one
iteration; the rest of the line after the colon is the action list for that
iteration. ?R is the current iteration number, counting from 1.
*FIELD supplies the destination record region for a repeated body. It is not a
quota cell or a participant identifier. In a repeat, the inner fields are laid
out relative to that region, so iteration 1 and iteration 2 do not overwrite each
other.
A question inside a repeat keeps one answer per iteration. The runtime records the whole chain of iteration values, so a nested repeat still has a distinct answer for every combination.
*TEXTVARS item
*VARS iteration
*REPEAT 2 *FIELD 201L2
*PUT iteration [?R]
*REPNUM 1: *PUT item "desk"
*REPNUM 2: *PUT item "room"
*QUESTION 1 *NUMBER L1 *MIN 1 *MAX 5
Rate the *? item from 1 to 5. Item *? iteration.
*ENDREP
*QUESTION 2 *CODES 205L1
All items rated.
1: Continue
*END*END inside a *REPEAT leaves the repetition block and continues after
*ENDREP.
Order, randomisation and control
These commands change presentation order. They do not change option identity, and the recorded history keeps a replayable decision.
| Command | Effect |
|---|---|
*RANDOM | Randomises the eligible codes. |
*ROT | Rotates eligible codes. |
*INV | Inverts eligible code order. |
*GROUP | Starts a block of codes that moves together. |
*STOPRANDOM | Marks the boundary after which codes stay outside random ordering. |
*NOCON | Exempts a code from control and order restrictions. |
*ORDER | Uses an explicit array, a stored mention order (QnM) or a stored display order (QnR). |
*CONTROL Qn W | Shows codes mentioned in Qn; N shows the codes not mentioned. |
*VCONTROL | Controls grid columns from an earlier answer. |
*NOHIDE | Keeps a code visible through an applicable hide rule. |
Do not combine *ORDER with *RANDOM, *ROT or *INV on one question.
*QUESTION 1 *CODES L1 *RANDOM
Which option do you prefer?
1: Early session *GROUP
2: Late session
3: Remote session *GROUP
4: Local session
9: No preference *STOPRANDOM *NOCON
*QUESTION 2 *CODES L1 *ROT
Choose a day:
1: Monday
2: Tuesday
3: Wednesday
*QUESTION 3 *CODES L1 *INV
Choose a period:
1: Morning
2: Afternoon
3: Evening
*END*VARS order[3]
*PUT order[1] [3]
*PUT order[2] [1]
*PUT order[3] [2]
*QUESTION 1 *CODES L1 *ORDER order
Choose a session:
1: Morning
2: Afternoon
3: Evening
*END*QUESTION 1 *CODES L3 *MULTI
Which facilities have you used?
1: Desk
2: Room
3: Locker
*QUESTION 2 *CODES L1 *CONTROL Q1 W
Which of those was most useful?
1: Desk
2: Room
3: Locker
9: None *NOCON *NOHIDE
*ENDThe controlling question must declare the complete code list; *CONTROL filters
what is shown, it does not supply options. *NOCON keeps an always-available
code such as “None” outside the filter.
Mention and display order
A *MULTI question with a second length records the order in which the
respondent selected codes. QnM reads that order, and QnR reads the order in
which codes were displayed to them. Both are stored as numbers in the record.
*QUESTION 1 *CODES L3 *MULTI L4 *MIN 1 *MAX 2
Which facilities did you use first?
1: Desk
2: Room
3: Locker
*QUESTION 2 *CODES L1 *ORDER Q1M
Which did you use first?
1: Desk
2: Room
3: Locker
*ENDThe second length must be large enough for the allowed number of mentions. Here
a one-digit code and two mentions need two positions; L4 leaves room for the
written order to be padded.
Presentation
*INTRO supplies introductory text, *INFO informational text and *PAGE a
display page. *NCLS keeps the relevant preceding content with the next page.
*HEADING, *CENTRE and *FONT describe presentation. QubeSurvey’s web renderer
interprets these instructions; it does not reproduce terminal screen
coordinates.
A conditional page puts *IF before *PAGE on the same line:
*IF [condition] *PAGE text. The reversed *PAGE *IF [...] spelling is not the
documented form and is reported as an error.
*FONT 1 "12 Arial"
*INTRO
This short example asks about a shared workspace.
*INFO
Use the last month as your reference period.
*PAGE
You can review your answers before finishing.
*QUESTION 1 *CODES L1 *NCLS *HEADING Workspace *CENTRE 1
*FONT 1 Your experience *FONT 0
1: Continue
*END*HELP n defines numbered help; the same option on a question attaches that
help. Help wording belongs to the study, not to the stored answer.
*HELP 1
Count every visit, even if it was brief.
*QUESTION 1 *NUMBER L2 *MIN 0 *MAX 30 *HELP 1
Visits this month:
*END*LIST name defines reusable codes. A question’s *LIST name option uses the
list; *USELIST name inserts it into its body. Lists may carry *FONT, *?,
*HEADING, *GROUP and *PICT lines between their codes.
*LIST facilities
1: Desk
2: Room
3: Locker
*QUESTION 1 *CODES L1 *LIST facilities
Which did you use most recently?
*QUESTION 2 *CODES L3 *MULTI
Which do you plan to use next month?
*USELIST facilities
*END*QUESTION 1 *CODES L1
Did you use a shared desk?
1: Yes
2: No
*IF [Q1,1] *PAGE Shared desks are booked one day at a time.
*QUESTION 2 *CODES L1
Continue?
1: Yes
*ENDLanguages
*LANGUAGE starts a translated section. Repeat the same question identities and a
compatible answer structure with translated wording. *SWILANG selects a
language; the interview can also expose an available-language choice.
A *LANGUAGE section closes only at the next *LANGUAGE or at the end of the
file. It is not closed by an ordinary block command.
*SWILANG "French"
*QUESTION 1 *CODES L1
Continue?
1: Yes
2: No
*END
*LANGUAGE "French"
*QUESTION 1 *CODES L1
Continuer ?
1: Oui
2: Non
*ENDEndings
| Ending | Native result | Hosted default |
|---|---|---|
*END | Completed, code 18. | Complete; retain answers. Fixed. |
*ENDNGB | Partial, code 19. | Partial; retain answers. |
*ENDST n | Script-selected code n, with its own native provenance. | Its code’s meaning on the Run; see below. |
*ABORT | Broken off, code 22. | Stop; discard answers. |
*APPOINT | Code 10, an appointment for the next questionnaire. | Not available; CAWI refuses the command. |
*ENDST records a script-selected code rather than giving every possible code a
platform meaning. A hosted Run lists the literal codes in the script, spelled as the
runtime reports them (*ENDST 41 is code 41; *ENDST "041" is the different code
041), plus 18, 19 and 22. Each code has a meaning and a keep-answers choice on the Run.
Codes 08, 16, 21 and 23 default to the meanings NIPO’s default response-code table
gives them; any other code defaults to other and keeps nothing. A survey.ini file is
not read, so its response-code labels do not apply. The argument must be a literal of
1 to 4 digits, at most 64 different codes per script; an *ENDST on a variable or
expression is refused on a hosted Run. See
Endings and retained responses.
Reaching the end of the source without an ending also completes the interview with code 18.
*QUESTION 1 *CODES L1
Choose how this example should finish:
1: Complete *END
2: Partial *ENDNGB
3: Script-selected partial *ENDST 19
4: Stop and discard *ABORTBack and navigation
*BACK n returns to question n using replay: commands and answers between the
current page and that question are undone, and the respondent continues from
there. A question that was never shown is not a valid target. *NOTBACK places a
Back barrier at that point in the questionnaire.
Test changed answers after Back wherever routing, ordering or repeated sections depend on earlier answers.
*QUESTION 1 *NUMBER L2 *MIN 0 *MAX 30
Number of visits:
*QUESTION 2 *CODES L1
Keep that answer?
1: Yes
2: Change it *BACK 1
*NOTBACK
*QUESTION 3 *CODES L1
This is the final page.
1: Finish
*ENDClock and conjoint contexts
*DATE and *TIME assign an environment clock value to a declared variable.
Native replay uses the recorded observation rather than taking another clock
reading. Hosted collection currently refuses these commands, so a script that
depends on them cannot be traced there.
*TEXTVARS day,clock
*DATE day
*TIME clock
*QUESTION 1 *CODES L1
Date: *? day. Time: *? clock.
1: Continue
*END*CONJ and *ENDCONJ define an adaptive conjoint section using attribute lists.
*LEFT and *RIGHT label the comparison ends. Conjoint has its own native
interaction and answer structure; qualify that workflow separately from an
ordinary question list. It is a CAWI-only block.
*LIST location
1: Central
2: Local
*LIST access
1: Daytime
2: All day
*CONJ L12 *LEFT "Prefer first" *RIGHT "Prefer second"
*LIST location
*LIST access
*ENDCONJ
*QUESTION 1 *CODES L1
The comparison is finished.
1: Continue
*ENDHost and environment commands
These commands have native environment hooks. They are not a connection to a NIPO sample database or arbitrary SQL on QubeSurvey. Hosted sample ownership, quota counts and permissions belong to the platform; a local script cannot replace that authority. QubeScript’s configured quota services are a separate integration.
*SAMPLEDATA declares sample fields. *COPY brings a declared sample value into
a variable. *STRAT asks the environment for a quota decision and routes to the
supplied question when the quota is full. This syntax needs a configured,
authorised host, so it is host context, not an ordinary hosted Odin collection
example.
*SAMPLEDATA area
*TEXTVARS areaText
*COPY areaText area
*STRAT 99
*QUESTION 1 *CODES L1
Sample area: *? areaText
1: Continue
*END
*QUESTION 99 *DUMMY
*ENDNGB*SQLGET reads records, *SQLPUT updates existing records and *SQLADD adds
records through the native environment. Their destination and count arguments and
their selection text are part of the legacy interface. The following is an
isolated syntax example, not permission to execute SQL or a hosted database
setup.
*VARS matched
*TEXTVARS label
*SQLGET matched label "SELECT Label FROM ExampleItems"
*PUT label "Updated item"
*SQLPUT matched label "SELECT Label FROM ExampleItems"
*SQLADD matched label "SELECT Label FROM ExampleItems"
*QUESTION 1 *CODES L1
Host operation count: *? matched
1: Continue
*ENDNon-CAWI and terminal presentation
The following examples run in the permissive local profile, not as
CATI/CAPI product workflows. The CAWI profile refuses *AUTO (the command),
*NOENTER, *READ, *WRITE, *SIZE and *APPOINT. The block forms of
*INSTRUC and *PNW are traditional instruction and no-wait text; the static
profile check does not flag those blocks. They are not ordinary CAWI pages.
| Command | Local meaning and current boundary |
|---|---|
*AUTO | Automatic code-column layout. |
*STOPAUTO | Ends the automatic column region. |
*NEWCOLUMN | A column-break hint. Inspect its web rendering rather than assuming fixed terminal coordinates. |
*INSTRUC | Interviewer/test instructions. |
*PNW | Display text without a waiting page. |
*NOENTER | Automatic confirmation behaviour for supported input types. |
*READ, *WRITE | Environment file-record operations; not direct browser file access. |
*SIZE | Partial sizing support; not a guarantee of matching desktop dimensions. |
*APPOINT | Records ending code 10 in a profile that allows it; no appointment scheduling workflow. |
*INSTRUC
Local test instruction: inspect the generated layout.
*PNW
Preparing the example.
*NOENTER
*QUESTION 1 *CODES L1 *AUTO
Choose a period:
1: Morning
2: Afternoon *NEWCOLUMN
3: Evening
9: Unsure *STOPAUTO
*QUESTION 2 *OPEN L20 *MULTI *SIZE 200 100
Local note:
*QUESTION 3 *CODES L1
Choose an ending:
1: Complete *END
2: Appointment context *APPOINT*TEXTVARS record
*PUT record "Synthetic record"
*WRITE record "example.txt"
*READ record "example.txt"
*QUESTION 1 *CODES L1
Read value: *? record
1: Continue
*END*PICT is partially implemented for image references and presentation. A path in
a script neither uploads the image nor makes a private asset public. The hosted
input-trace collector currently refuses this image capability.
*QUESTION 1 *CODES L1
*PICT "example-image.jpg"
Does the example image explain the layout?
1: Yes
2: No
*ENDMetadata retained on import
*VAR names an export variable and *LABEL supplies a label. *ADDRESS and
*TABLE retain legacy metadata; they do not create participant records or an
external export system. *MOVA is obsolete metadata; use a supported *COPY
operation for an actual value transfer. *~IMPORTED is an import marker.
*~IMPORTED
*MOVA
*QUESTION 1 *ALPHA L20 *NON *VAR visitNote *LABEL "Visit note" *ADDRESS
Optional example address text:
*QUESTION 2 *FORM *TABLE *LABEL "Booking"
1: Seats: *NUMBER L2 *MIN 1 *MAX 20
*ENDRecognised names without supported execution
Recognition lets the checker explain an imported script; it is not evidence that a command will perform its original function. Some retain partial native behaviour, such as a suspension, without the corresponding host workflow. These names do not have supported execution coverage:
| Names | Area |
|---|---|
*MERGE, *SKIP, *NEW, *NEXT, *NEXTRECORD, *GETREC | Legacy record and sample iteration. |
*HOOK, *RUN | External program or integration hooks. |
*SHOWDOCUMENT, *BMP, *PLAY, *WAITPLAY | External documents, drawing or playback. |
*DTIME, *DELAY, *WAITCR, *KEY | Timing and legacy keyboard interaction. |
*CUT, *ENDG, *NP | Legacy control and output behaviour. |
*NONRESP, *REC | Incomplete nonresponse and recording workflows. |
Command index
Every name QubeSurvey recognises. Implemented commands run in the local engine; partial ones run with a stated limit; metadata ones are retained and reported but do not execute; the last group is recognised only.
Questions, fields and answers
| Command | Applies to | Meaning |
|---|---|---|
*QUESTION, *Q | header | Start a question. |
*CODES | header | Choice question or code field. |
*ALPHA | header, form field | Single-line text. |
*OPEN | header, code line | Verbatim text, or attached text for a code. |
*NUMBER | header, form field | Numeric input. |
*LINE | header | Bounded numeric slider. |
*SCALE | header, form field | Rating scale. |
*FORM | header | Multi-field page. |
*GRID | form field | Grid inside a form. |
*DUMMY | header | Hidden value holder. |
*MULTI | header, form field | Multiple answers; mention order on a codes field. |
*NON | header, form field | Optional answer. |
*MIN, *MAX | header, form field | Lower and upper bounds. |
*RANGE | header, form field | Allowed values or intervals. |
*NMUL | code line | Exclusive code. |
*BUT | header | Supplementary button answer. |
*SAVE | header, code line, form field | Copy the answer to a variable. |
*CONTROL | header | Filter codes from an earlier answer. |
*VCONTROL | header | Filter grid columns from an earlier answer. |
*NOHIDE | code line | Keep a code visible. |
*FIELD | header, code line | Record region for a repeated body. |
*REC | header | Legacy recording (recognised only). |
Order and group
| Command | Applies to | Meaning |
|---|---|---|
*RANDOM | header, code line | Randomise eligible codes. |
*ROT | header | Rotate codes. |
*INV | header | Invert code order. |
*ORDER | header | Apply a stored or explicit order. |
*GROUP | code line | Start a code group. |
*STOPRANDOM | code line | End the randomised run. |
*NOCON | code line | Exempt a code from control and order. |
Values, text and calculations
| Command | Applies to | Meaning |
|---|---|---|
*VARS, *TEXTVARS, *SAMPLEDATA | statement | Declare numeric, text or sample variables. |
*PUT | statement, code line | Assign a value or text. |
*COPY | statement, code line | Copy an interpreted answer or value. |
*MOVU | statement | Copy literal record bytes. |
*MOVA | statement | Obsolete metadata (does not transfer a value). |
*INCLUDE, *EXCLUDE | statement, code line | Add or remove codes. |
*COUNT | statement | Store the number of selected codes. |
*FORMAT | statement | Numeric-to-text width and decimals. |
*? | display text | Insert a variable. |
*DATE, *TIME | statement | Read the environment clock. |
Routing, blocks and endings
| Command | Applies to | Meaning |
|---|---|---|
*IF, *ELSE | statement, header, code line | Conditional actions or conditional question. |
*GOTO | statement, code line | Jump to a question number. |
*BACK | statement, code line | Return to a question by replay. |
*NOTBACK | statement | Back barrier. |
*GOSUB, *RETURN, *SUBROUTINE | statement, block | Named section and return. |
*INIT | block | Initialisation run before the first page. |
*REPEAT, *ENDREP, *REPNUM | block, statement | Repetition. |
*END | statement, code line | Finish, or close *INIT. |
*ENDNGB | statement, code line | Partial ending, code 19. |
*ENDST | statement, code line | Script-selected ending code. |
*ABORT | code line | Broken-off ending, code 22. |
*APPOINT | code line | Ending code 10 (partial). |
*NONRESP | statement, code line | Nonresponse suspension (recognised only). |
*ENDG, *NP, *CUT | code line, statement | Legacy control (recognised only). |
Presentation and help
| Command | Applies to | Meaning |
|---|---|---|
*INTRO, *INFO, *PAGE, *PNW, *INSTRUC | block | Display text. |
*NCLS | header | Keep preceding content with the next page. |
*HEADING, *CENTRE | header | Heading and centring hints. |
*FONT | statement, header, code line | Font definition or switch. |
*TAB | header, statement | Column positions. |
*SCALERANGE | statement, form field | Stored values for scale boxes. |
*AUTO, *STOPAUTO, *NEWCOLUMN | header, code line | Column layout hints. |
*SIZE | header | Window size (partial). |
*NOENTER | header | Automatic confirmation. |
*HELP | header, block | Numbered help and its attachment. |
*LIST, *USELIST | block, header | Reusable codes. |
*LANGUAGE, *SWILANG | block, statement | Translation sections and language selection. |
*PICT | header, code line | Image reference (partial). |
Environment, integration and metadata
| Command | Applies to | Meaning |
|---|---|---|
*STRAT | statement | Quota decision from the environment. |
*SQLGET, *SQLPUT, *SQLADD | statement | Environment database access. |
*READ, *WRITE | statement | Environment file records. |
*CONJ, *ENDCONJ | block | Adaptive conjoint. |
*LEFT, *RIGHT | header | Scale and conjoint endpoint labels. |
*VAR, *LABEL, *ADDRESS, *TABLE | header, statement | Retained export metadata. |
*~IMPORTED | statement | Import marker. |
*MERGE, *RUN, *HOOK | statement | External program or merge hooks (recognised only). |
*SKIP, *NEW, *NEXT, *NEXTRECORD, *GETREC | statement | Record iteration (recognised only). |
*SHOWDOCUMENT, *BMP, *PLAY, *WAITPLAY | statement, code line | Media and documents (recognised only). |
*DTIME, *DELAY, *WAITCR, *KEY | statement | Timing and keyboard (recognised only). |
Differences from NIPO Odin
QubeSurvey implements the Odin language; it is not the NIPO DLL. The syntax you write is intended to be the same, but the engine, the host and the renderer are different. This section states what is known to differ so you can decide what needs checking in NIPO before an exchange.
Engine and fidelity
- A different engine. QubeSurvey parses and executes the source itself. It follows the DLL where the manuals and the implementation disagree, but it is not a byte-for-byte copy of NIPO’s behaviour. Error messages, recovery and diagnostics are QubeSurvey’s own.
- Decoded, not byte-identical. Source is decoded from UTF-8, UTF-16 or a legacy single-byte encoding. A script round-trips as text; it is not preserved as the original byte stream.
- Stricter authoring checks. QubeSurvey reports some constructs the DLL
silently accepts: a chained comparison, a bare-number code test, an undersized
codes field, a reversed conditional page, answer-code syntax under
*LINE, and comparisons used as membership tests on a multiple-answer question. These are findings, not a different language. !is not Boolean NOT. Use#. The DLL also rejects!, but it is the most common mistake when writing Odin from another language’s habits, so QubeSurvey reports it explicitly.- Leniencies kept for compatibility. Compact headers (
*Q200), whitespace inside question references (Q 71,Q340 F1), category-shaped lines inside*INSTRUC/display blocks, optional form cell numbers and sample/list text after a declared variable list are all accepted, as the DLL accepts them.
Answer and record model
- Answers, not U-files, are the source of truth. The fixed-width record is a projection. Positions still matter for exports and for resume-style record exchange, and a question without a length has no record column — but the answer itself is never lost.
- Decimal fields are
len + decbytes.L4.1occupies five bytes with an implied decimal point. Tools that assume a separate point byte will disagree. *LINEis a bounded value. QubeSurvey renders a slider and stores the chosen number in the field. The legacy description of the answer as “the length of the line” is a terminal-screen model and does not apply.*SCALEkeeps its labels and changes its values. The visible boxes stay 1, 2, 3 …;*SCALERANGEchanges what is stored. A scale with no code lines has 7 points unless*MAXsays otherwise.- Mention and display order are stored separately.
QnMreads the respondent’s selection order;QnRreads the order the codes were offered in. A*CODES … *MULTI Lksecond field is what makesQnMavailable. *OPENis a verbatim box. QubeSurvey always renders it as a larger text input; its coded record positions are separate from the text the respondent typed.
Commands that do not run
- Twenty-one recognised names have no execution coverage:
*MERGE,*SKIP,*NEW,*NEXT,*NEXTRECORD,*GETREC,*HOOK,*RUN,*SHOWDOCUMENT,*BMP,*PLAY,*WAITPLAY,*DTIME,*DELAY,*WAITCR,*KEY,*CUT,*ENDG,*NP,*NONRESPand*REC. The checker can still explain them, and the extension can navigate to a*MERGEtarget, but running them is not supported. - A restricted command is skipped, not executed. Each channel profile allows a documented set of commands. A command outside the profile is reported by the profile check before Start; if execution reaches it anyway, QubeSurvey records a runtime diagnostic and skips it. Treat the profile check as the gate, and do not rely on the runtime skip.
- CATI and CAPI are not product workflows. The channel presets exist for checking and local testing. CAWI is the supported collection mode.
Presentation
- The web renderer replaces terminal layout.
*AUTO,*NEWCOLUMN,*SIZE, tabs and screen coordinates are hints, not guarantees.*SIZEis partial, and*PICTis partial. - Instruction and no-wait text is not a CAWI page.
*INSTRUCand*PNWblock text does not create an ordinary respondent page. - Fonts are approximate.
*FONTsizes and faces are interpreted by the web renderer. *APPOINTrecords code 10 where the profile allows it but schedules nothing.
Host and fieldwork
- Sample and SQL commands are host hooks, not database access. There is no arbitrary SQL or NIPO sample database connection on QubeSurvey. Quotas, sample ownership and permissions belong to the platform.
- Hosted collection is a subset. Hosted fieldwork refuses
*COPY,*MOVU,*INCLUDE,*EXCLUDE,*DATE,*TIME,*FORMAT, sample, SQL, file and image commands. A profile-accepted script can still be outside the hosted subset; upload preparation reports it. - Ending codes are listed from the script. 18 completes, 19 is partial and 22
is broken off by default. Other literal
*ENDSTcodes are mapped on the Run; a computed*ENDSTcode andsurvey.iniresponse-code labels are not supported. The Odin export includes every response whose code keeps answers; itsoutcome_namecolumn holds the response code. - Question-level indexed
*SAVEis not eligible hosted. Use a supported scalar or a checked form/code-line destination.
What to re-test when exchanging
When a script moves between QubeSurvey and NIPO, test these in the target host:
- Every screener and route, including conditions on unanswered questions.
- Other/exclusive answers,
*BUTbuttons and attached open text. - Validations, especially
*RANGE,*MIN/*MAXon multiple answers and*LINEbounds. - Repetitions,
*FIELDlayouts and mention order. - Changed answers after Back and across a
*NOTBACKbarrier. - Languages,
*SWILANGand translated sections. - Endings and their recorded codes.
- Export columns and field widths.
Checking, testing and hosting
Check syntax first, then the CAWI profile, then run the intended answer paths in Test. Profile acceptance checks commands; it does not configure a sample database, image library or service endpoint. Hosted Start also checks the source and the bounded input-trace capability.
The QubeSurvey extension reports placement and authoring findings as you type. It can also fix data positions, renumber questions and extract a translation section. Those transforms rewrite source, so review the result before you upload it.
When moving a study, test all screeners, Other and exclusive answers, validations, repetitions, Back changes, languages, endings and export columns against independent expected results. The fictional paired examples provide complete original studies to practise with.