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

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. *QUESTION and *Q are 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, *SCALE and *GRID bodies.
  • 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 *Q200 mean *Q 200 and are accepted.

Blocks come in two kinds:

KindBlocksEnds at
Header blocks*QUESTION, *FORM, *INTRO, *INFO, *PAGE, *PNW, *INSTRUC, *HELP, *LIST, *LANGUAGEthe next command or block that replaces it
Explicit blocks*INIT, *REPEAT, *SUBROUTINE, *CONJits 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:
*END

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

TypeAnswerNotes
*CODESOne code, or several with *MULTIThe ordinary choice list.
*ALPHAFree text, single lineWidth comes from the field length.
*OPENFree text, verbatim boxDisplayed as a larger text input.
*NUMBERA numberL3 allows whole numbers; L3.2 declares two decimals.
*LINEA bounded numeric positionRendered as a slider; a negative *MAX asks for a vertical one.
*SCALEA point on a rating scaleDefaults to 7 points; *MAX sets the count (2–26).
*FORMOne answer per numbered fieldEach field carries its own type and constraints.
*DUMMYA value the respondent never seesFilled 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.

CommandEffect
*MULTIMore than one answer. On *CODES it also changes the stored shape.
*NONThe answer may be left blank.
*MIN, *MAXBounds for a number, line or scale; the allowed count for a multiple answer.
*RANGEAn allowed value or interval, written in brackets.
*NMULMarks an exclusive code in a multiple-answer question.
*BUTA supplementary button answer, such as “Unsure”, outside the ordinary scale.
*OPENOn a code line: an attached text box for that code.
*SAVECopies 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?
*END

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

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

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

DeclarationRecord footprintStored form
101L22 bytes, at 101–102Positioned field; alignment follows the type
*CODES L33 bytesSelected code number as digits
*CODES L3 *MULTI3 bytesOne byte per code: 1 selected, 0 not
*CODES L3 *MULTI L43 + 4 bytesBitmap, then mention order as zero-padded codes
*NUMBER L3.25 bytesScaled integer with an implied decimal point
*ALPHA L2020 bytesLeft-aligned text
*OPEN L2020 bytesCoded positions; the verbatim text stays in the answer store

Two consequences follow.

  • A decimal field occupies len + dec bytes. There is no byte for the decimal point, so L4.1 needs five bytes.
  • A *MULTI question 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.

ExpressionMeaning
Q1The answer to question 1.
Q1,2True when code 2 was selected.
Q1,1;3;5True when any of those codes was selected.
Q1,2-5True when a code in the range was selected.
Q4F2Field 2 of form question 4.
Q4F(?R)A form field chosen by the repetition number.
Q1M1First mentioned code of question 1.
Q1R1First displayed code of question 1.
?RThe current repetition number.
RAN 10A seeded integer from 0 to 9.
#Q2,1Negation. # 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.

CallResult
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

  1. Names are case-insensitive and are stored in upper case.
CommandEffect
*PUT name [expression]Assign a calculated value.
*PUT name "text"Assign literal text.
*COPY target sourceCopy the interpreted answer or value.
*MOVU target sourceCopy literal record-field contents, including padding.
*INCLUDE Qn [codes]Add codes to an answer.
*EXCLUDE Qn [codes]Remove codes from an answer.
*COUNT var QnStore the number of selected codes.
*FORMAT width.decimalsFormat 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
*END

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

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

Repetition

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

CommandEffect
*RANDOMRandomises the eligible codes.
*ROTRotates eligible codes.
*INVInverts eligible code order.
*GROUPStarts a block of codes that moves together.
*STOPRANDOMMarks the boundary after which codes stay outside random ordering.
*NOCONExempts a code from control and order restrictions.
*ORDERUses an explicit array, a stored mention order (QnM) or a stored display order (QnR).
*CONTROL Qn WShows codes mentioned in Qn; N shows the codes not mentioned.
*VCONTROLControls grid columns from an earlier answer.
*NOHIDEKeeps 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
*END

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

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

Languages

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

Endings

EndingNative resultHosted default
*ENDCompleted, code 18.Complete; retain answers. Fixed.
*ENDNGBPartial, code 19.Partial; retain answers.
*ENDST nScript-selected code n, with its own native provenance.Its code’s meaning on the Run; see below.
*ABORTBroken off, code 22.Stop; discard answers.
*APPOINTCode 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 *ABORT

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

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

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

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

CommandLocal meaning and current boundary
*AUTOAutomatic code-column layout.
*STOPAUTOEnds the automatic column region.
*NEWCOLUMNA column-break hint. Inspect its web rendering rather than assuming fixed terminal coordinates.
*INSTRUCInterviewer/test instructions.
*PNWDisplay text without a waiting page.
*NOENTERAutomatic confirmation behaviour for supported input types.
*READ, *WRITEEnvironment file-record operations; not direct browser file access.
*SIZEPartial sizing support; not a guarantee of matching desktop dimensions.
*APPOINTRecords 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
*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

Recognised 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:

NamesArea
*MERGE, *SKIP, *NEW, *NEXT, *NEXTRECORD, *GETRECLegacy record and sample iteration.
*HOOK, *RUNExternal program or integration hooks.
*SHOWDOCUMENT, *BMP, *PLAY, *WAITPLAYExternal documents, drawing or playback.
*DTIME, *DELAY, *WAITCR, *KEYTiming and legacy keyboard interaction.
*CUT, *ENDG, *NPLegacy control and output behaviour.
*NONRESP, *RECIncomplete 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

CommandApplies toMeaning
*QUESTION, *QheaderStart a question.
*CODESheaderChoice question or code field.
*ALPHAheader, form fieldSingle-line text.
*OPENheader, code lineVerbatim text, or attached text for a code.
*NUMBERheader, form fieldNumeric input.
*LINEheaderBounded numeric slider.
*SCALEheader, form fieldRating scale.
*FORMheaderMulti-field page.
*GRIDform fieldGrid inside a form.
*DUMMYheaderHidden value holder.
*MULTIheader, form fieldMultiple answers; mention order on a codes field.
*NONheader, form fieldOptional answer.
*MIN, *MAXheader, form fieldLower and upper bounds.
*RANGEheader, form fieldAllowed values or intervals.
*NMULcode lineExclusive code.
*BUTheaderSupplementary button answer.
*SAVEheader, code line, form fieldCopy the answer to a variable.
*CONTROLheaderFilter codes from an earlier answer.
*VCONTROLheaderFilter grid columns from an earlier answer.
*NOHIDEcode lineKeep a code visible.
*FIELDheader, code lineRecord region for a repeated body.
*RECheaderLegacy recording (recognised only).

Order and group

CommandApplies toMeaning
*RANDOMheader, code lineRandomise eligible codes.
*ROTheaderRotate codes.
*INVheaderInvert code order.
*ORDERheaderApply a stored or explicit order.
*GROUPcode lineStart a code group.
*STOPRANDOMcode lineEnd the randomised run.
*NOCONcode lineExempt a code from control and order.

Values, text and calculations

CommandApplies toMeaning
*VARS, *TEXTVARS, *SAMPLEDATAstatementDeclare numeric, text or sample variables.
*PUTstatement, code lineAssign a value or text.
*COPYstatement, code lineCopy an interpreted answer or value.
*MOVUstatementCopy literal record bytes.
*MOVAstatementObsolete metadata (does not transfer a value).
*INCLUDE, *EXCLUDEstatement, code lineAdd or remove codes.
*COUNTstatementStore the number of selected codes.
*FORMATstatementNumeric-to-text width and decimals.
*?display textInsert a variable.
*DATE, *TIMEstatementRead the environment clock.

Routing, blocks and endings

CommandApplies toMeaning
*IF, *ELSEstatement, header, code lineConditional actions or conditional question.
*GOTOstatement, code lineJump to a question number.
*BACKstatement, code lineReturn to a question by replay.
*NOTBACKstatementBack barrier.
*GOSUB, *RETURN, *SUBROUTINEstatement, blockNamed section and return.
*INITblockInitialisation run before the first page.
*REPEAT, *ENDREP, *REPNUMblock, statementRepetition.
*ENDstatement, code lineFinish, or close *INIT.
*ENDNGBstatement, code linePartial ending, code 19.
*ENDSTstatement, code lineScript-selected ending code.
*ABORTcode lineBroken-off ending, code 22.
*APPOINTcode lineEnding code 10 (partial).
*NONRESPstatement, code lineNonresponse suspension (recognised only).
*ENDG, *NP, *CUTcode line, statementLegacy control (recognised only).

Presentation and help

CommandApplies toMeaning
*INTRO, *INFO, *PAGE, *PNW, *INSTRUCblockDisplay text.
*NCLSheaderKeep preceding content with the next page.
*HEADING, *CENTREheaderHeading and centring hints.
*FONTstatement, header, code lineFont definition or switch.
*TABheader, statementColumn positions.
*SCALERANGEstatement, form fieldStored values for scale boxes.
*AUTO, *STOPAUTO, *NEWCOLUMNheader, code lineColumn layout hints.
*SIZEheaderWindow size (partial).
*NOENTERheaderAutomatic confirmation.
*HELPheader, blockNumbered help and its attachment.
*LIST, *USELISTblock, headerReusable codes.
*LANGUAGE, *SWILANGblock, statementTranslation sections and language selection.
*PICTheader, code lineImage reference (partial).

Environment, integration and metadata

CommandApplies toMeaning
*STRATstatementQuota decision from the environment.
*SQLGET, *SQLPUT, *SQLADDstatementEnvironment database access.
*READ, *WRITEstatementEnvironment file records.
*CONJ, *ENDCONJblockAdaptive conjoint.
*LEFT, *RIGHTheaderScale and conjoint endpoint labels.
*VAR, *LABEL, *ADDRESS, *TABLEheader, statementRetained export metadata.
*~IMPORTEDstatementImport marker.
*MERGE, *RUN, *HOOKstatementExternal program or merge hooks (recognised only).
*SKIP, *NEW, *NEXT, *NEXTRECORD, *GETRECstatementRecord iteration (recognised only).
*SHOWDOCUMENT, *BMP, *PLAY, *WAITPLAYstatement, code lineMedia and documents (recognised only).
*DTIME, *DELAY, *WAITCR, *KEYstatementTiming 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 + dec bytes. L4.1 occupies five bytes with an implied decimal point. Tools that assume a separate point byte will disagree.
  • *LINE is 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.
  • *SCALE keeps its labels and changes its values. The visible boxes stay 1, 2, 3 …; *SCALERANGE changes what is stored. A scale with no code lines has 7 points unless *MAX says otherwise.
  • Mention and display order are stored separately. QnM reads the respondent’s selection order; QnR reads the order the codes were offered in. A *CODES … *MULTI Lk second field is what makes QnM available.
  • *OPEN is 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, *NONRESP and *REC. The checker can still explain them, and the extension can navigate to a *MERGE target, 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. *SIZE is partial, and *PICT is partial.
  • Instruction and no-wait text is not a CAWI page. *INSTRUC and *PNW block text does not create an ordinary respondent page.
  • Fonts are approximate. *FONT sizes and faces are interpreted by the web renderer.
  • *APPOINT records 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 *ENDST codes are mapped on the Run; a computed *ENDST code and survey.ini response-code labels are not supported. The Odin export includes every response whose code keeps answers; its outcome_name column holds the response code.
  • Question-level indexed *SAVE is 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:

  1. Every screener and route, including conditions on unanswered questions.
  2. Other/exclusive answers, *BUT buttons and attached open text.
  3. Validations, especially *RANGE, *MIN/*MAX on multiple answers and *LINE bounds.
  4. Repetitions, *FIELD layouts and mention order.
  5. Changed answers after Back and across a *NOTBACK barrier.
  6. Languages, *SWILANG and translated sections.
  7. Endings and their recorded codes.
  8. 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.