Odin reference

Odin is the second survey language in QubeSurvey. Use it when an existing questionnaire or your team’s experience makes Odin the practical choice. QubeScript is the default for new work. Each language has its own parser and interview engine; they share Scripts, versions, Runs, participants and exports.

This reference describes QubeSurvey’s implementation. We use our own parser and runtime, following established Odin syntax and behavior 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.

Reading a script

Commands start with * and are case insensitive. A question begins with *QUESTION (or *Q), a number and its options. The following lines contain its wording and numbered answer codes. ** starts a comment. L specifies a field length; a preceding position, such as 101L2, specifies a fixed record field. Use fixed, non-overlapping positions when a legacy record layout matters.

These examples are independent small scripts, rather than 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:
*END

*END finishes the interview, except inside *INIT, where it finishes initialization, or inside *REPEAT, where it leaves the repetition block. *NON makes an input optional. *DUMMY declares a question that is not an ordinary respondent input; it can hold a value for later calculations or control.

Answers and validation

Command	Use
`*CODES`	A numbered choice list; one answer unless `*MULTI` is present.
`*ALPHA`	A text field.
`*OPEN`	An open text answer, or an associated text box on an answer code.
`*NUMBER`	Numeric input. `L3` permits whole numbers; `L3.2` declares two decimal places.
`*LINE`	Numeric line/slider input with its own input contract.
`MIN`, `MAX`	Bounds for numbers, scales or the number of selected answers, according to the question type.
`*RANGE`	Allowed numeric values or intervals, written inside brackets.
`*MULTI`	Multiple answers; on `*OPEN`, a multiline text input.
`*NMUL`	An exclusive code in a multiple-answer question.
`*BUT`	A supplementary answer, such as “Unsure”, outside the ordinary numeric or form inputs.

*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?
*END

Specify decimal precision explicitly. *RANGE [0 TO 10;99] permits the interval 0–10 and the separate value 99. A range is a validation rule, not a list of displayed choices.

*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 associated open field can save its text separately. Keep “None”, “Not applicable” and “Unsure” distinct when the analysis needs different bases.

Values, calculations and inserted text

Declare numeric variables with *VARS, text variables with *TEXTVARS and an array with a size, such as order[3]. Array indexes start at 1. *PUT assigns a value. *? inserts a variable or question value into displayed text; calculate an expression with *PUT before showing its result. *FORMAT controls subsequent numeric-to-text formatting; it does not change the original answer’s declared precision.

*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
*END

Expression	Meaning
`Q1`	The answer to question 1.
`Q1,2`	A test or reference involving code 2 of question 1.
`Q4F2`	Field 2 of form question 4.
`?R`	The current repetition number.
`[a + b * 2]`	Arithmetic; brackets delimit an expression.
`[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.

*COPY transfers an interpreted answer/value. *MOVU transfers literal record field contents, so field lengths and positions matter. *INCLUDE and *EXCLUDE change a coded answer; they do not merely change what the next page displays. *COUNT stores the number of selected codes.

*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
*END

Routing and reusable sections

*IF executes 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.

*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
*END

Define 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. 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 run at the beginning of the interview. Its closing *END continues into the questionnaire.

*VARS initial
*INIT
*PUT initial [4]
*END
*QUESTION 1 *NUMBER L1 *MIN 0 *MAX 9
The initial value is *? initial. Enter your own value:
*END

Repeated questions and record fields

*REPEAT and *ENDREP repeat a block. *REPNUM selects actions for a particular iteration. *FIELD supplies the destination record region for repeated or subroutine record fields. It is not a quota cell or participant identifier.

*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

Back and endings

*BACK n returns to question n using replay. *NOTBACK places a Back barrier. 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
*END

Ending	Native result	Hosted fixed policy
`*END`	Completed, code 18.	Complete; retain answers.
`*ENDNGB`	Partial, code 19.	Partial; retain answers.
`*ENDST 19`	Script-selected code 19, with its own native provenance.	Partial; retain answers.
`*ABORT`	Broken off, code 22.	Stop; discard answers.

*ENDST records a script-selected code, rather than giving every possible code a platform meaning. Hosted collection currently accepts the fixed endings 18, 19 and 22. Other codes and dynamic endings need a supported policy before Start.

*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 *ABORT

Lists, visibility and order

*LIST name defines reusable codes. A question’s *LIST name option uses the list; *USELIST name inserts it into its body.

*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

Command	Effect
`*RANDOM`	Randomizes the eligible codes. The session seed and recorded history preserve replay.
`*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 remain outside random ordering.
`*NOCON`	Exempts a code from control/order restrictions; useful for an always available “None”.
`*ORDER`	Uses an explicit array or a stored answer/display order. Do not combine it with random/rotation/inversion.
`*CONTROL Q1 W`	Displays codes mentioned in Q1; `N` selects codes not mentioned. It can also control repetitions/form rows.
`*NOHIDE`	Keeps a code visible through the applicable hide rule.
`*VCONTROL`	Controls the columns of a grid from an earlier answer.

*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
*END

Forms and scales

*FORM puts numbered input fields on one page. Each field has its own type and constraints. *SCALE defines a rating scale; *LEFT and *RIGHT label its ends. *GRID declares a grid field, including dimensions in its positional parameters. *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.

*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:
*END

*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 L3 3.2 3.10
2: Adequate
3: Good
*END

Display text and help

*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. Their legacy layout instructions are interpreted by QubeSurvey’s web renderer.

*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

Languages

*LANGUAGE starts a translated section. Repeat the same question identities and compatible answer structure with translated wording. *SWILANG selects a language; the interview can also expose an available-language choice.

*SWILANG "French"
*QUESTION 1 *CODES L1
Continue?
1: Yes
2: No
*END
*LANGUAGE "French"
*QUESTION 1 *CODES L1
Continuer ?
1: Oui
2: Non
*END

Clock and conjoint contexts

*DATE and *TIME assign an environment clock value to a question or declared variable. Native replay uses recorded observations rather than taking another clock reading. Availability of that environment must also be checked for the hosted input-trace path.

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

*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
*END

Host contexts: sample and database 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. *STRAT asks the environment for a quota decision and routes to the supplied question when full. This syntax needs a configured, authorized 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/count arguments and 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
*END

Legacy profile and partial presentation commands

The following examples are checked in the permissive local profile, not offered as CATI/CAPI product workflows. The CAWI profile refuses *AUTO, *NOENTER, *READ, *WRITE, *SIZE and *APPOINT. The block forms of *INSTRUC and *PNW are legacy instruction/no-wait text; the current 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 legacy screen coordinates.
`*INSTRUC`	Interviewer/test instructions.
`*PNW`	Display text without a waiting page.
`*NOENTER`	Automatic confirmation behavior 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`	Partial native ending support (code 10); 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
*END

Metadata 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
*END

Recognized names without supported execution coverage

Recognition lets the checker explain an imported script; it is not evidence that a command will perform its original function. Some retain partial native behavior, 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/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/output behavior.
`NONRESP`, `REC`	Incomplete nonresponse/recording workflow support.

Checking 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 bounded input-trace capabilities. Question-level indexed *SAVE, for example, is not currently eligible for that hosted path; use a supported scalar or appropriately checked form/code-line destination.

When moving a study, test all screeners, Other/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.

QubeSurvey Guide

Documentation