Global META Commands
Global and Miscellaneous Meta Commands.
ALLOW_INDENT
Allows Meta commands, comments and &filename commands to be indented; by default, they must start at the first column of the file. You can turn off this command by specifying >-ALLOW_INDENT.
CASE_SENSITIVE
CASE_SENSITIVE <filename>
This command allows you to run jobs in directories with names such as /home/study/TEST/One. It is to be used with caution if there are very long file names. When you use CASE_SENSITIVE, the filenames, whether upper or lower case, will remain the same. So, your specs can be:
~In store/producesection/apples OR ~IN STORE/PRODUCESECTION/APPLES OR ~In Store/Producesection/Apples
This command keeps the case the way it was entered. It will not change the name to the default, which is all lowercase. Thus, each of the three statements would look for the exact filename.
In addition, the software can read all filenames and paths regardless of the length or case (Use ” “s around filenames with special characters or spaces). The program will lowercase all input and output names you specify unless you use >CASESENSITIVE, in which case the program, will look for and write names exactly as specified.
In ALL cases, lowercase file extensions are output, unless otherwise specified. It is assumed that setenv ENVIRONMENT variables are uppercase unless you specify >CASESENSITIVE_ENV, in which case the program pays attention to the exact case.
For example, when turned on, files referenced, such as “Study.db”, will look for “Study.db” and not “study.db”. By default, it will look for “study.db” or “Study.db” or “STUDY.DB”.
CFMC_FILE_EXTENSION
This says that Survox programs expect certain program-generated file extensions, such as TR for input files. This is the default. It allows the user to define alternate extensions for those usually used with files created by Survox.
You can specify $filename on any program command (e.g., ~INPUT $myfile) to tell a Survox program to accept the file name as given and not to add or check for standard Survox extensions. This applies only for files with an expected default extension: data (TR); print (PRT); or db (DB). This allows you to specify your own file names up to the maximum allowed by your operating system (eight plus three character extension for DOS and 14 for UNIX (some UNIX versions have no character limit).
>CFMC_FILE_EXTENSION makes $filename the default.
The current list of 16 controllable extensions are: CHK, DB, DEF, DLM, HRD, LAB, LPR, PRT, QFF, QSP, QUO, RFL, RFT, SUM, TAB, and TR
CHARACTER_SET
CHARACTER_SET=<character set>
This is used to say what character set is allowed in spec files. See the >LANGUAGE meta command.
DUMP
DUMP <letter#>/DUMP <letter>
Sets the switches which will display information useful for programmers or turn on special features. Dump switches will continue to display until they are turned off.
Dump switches are case sensitive. You can turn several switches on in one command.
EXAMPLE:
>DUMP S1g2
Use a minus sign to turn off a dump switch.
EXAMPLE:
>DUMP -g2
You can also turn on or off all of the switches set with a particular letter.
EXAMPLE:
>DUMP S
Use this syntax with extreme caution since this will turn on several switches at once and may cause unexpected results.
Use the SHOW option to see which dump switches are set.
EXAMPLE:
>DUMP SHOW
ERROR_AND_WARNING_SUMMARY
Adds a summary of errors to the bottom of your compile and table runs by default. The same type of summary prints for Mentor table runs as well. To turn off the summary, add
>-ERROR_AND_WARNING_SUMMARY to your specfile or MENTINITIAL file.
EXAMPLE:
****** ERROR AND WARNING SUMMARY ****** 6 WARN #7105 SPC,3 format changed in ver 7.6+. Are you sure 10 is the width? 1 WARN #4152 TAB(s) converted to BLANKs starting at character 8 below 4 WARN #1406 GOTO to a previous question 3 WARN #2779 Specified width (2) is larger than needed (1) 2 WARN #2722 This question uses columns already used by another question 2 WARN #2797 SKIPTO to a previous question. May overwrite data! 1 WARN #3443 This question (13.43) might not fit on the screen (32 > 23) 5 ERROR #4014 Expected a '$' here: q13lw_$a: 21/$a.1 5 errors, 19 warnings
FAKE_TIME
FAKE_TIME <day month year time>
Allows you to set the system clock for Survox programs. This is useful to set the same run date/times on output printed at different times (for instance, if you are checking for differences between output files over time), or to test a phone study questionnaire by setting different times and seeing which numbers are coming up using the FONESIM utility.
>FAKE_TIME reports the time it sets the system clock to when you use it.
NOTE: Check this carefully. >FAKETIME never generates an error for bad syntax. It leaves the module with the illegal value unchanged.
EXAMPLE:
>FAKE_TIME 22 JUN 2015 11:15
Valid Options
- Day – The day of the month field must contain a number that could occur in the month specified.
- Month – Only the first three letters of the month field are recognized. JUN, June, and JunXXX will all set the month to June.
- Year – Legal values for the year are two digits for 1980-1999 and four digits for 2000-2027.
- Time – Use 24 hour clock time, between 00:00 to 23:59 (use 00:00 for midnight, not 24:00). The colon (:) is optional.
>FAKE_TIME without any options returns you to actual system time. The >FAKE_TIME command controls the time and date information that will be displayed in a Survox program run. The >FAKE_TIME setting can be changed during the course of a run.
The >FAKE_TIME command affects the Mentor System variable, DATE_TIME. It will also affect the results of >STOP_WATCH commands. Once a >FAKE_TIME is set, >STOP_WATCH will only report 0 minutes and 0 seconds in its total time field, unless a >FAKE_TIME command with no arguments is encountered. When >FAKE_TIME has been reset to the actual time, the total time reported by >STOP_WATCH will be more or less correct.
The >STOP_WATCH command will report the difference between two FAKETIMEs in its second field. When the difference between two FAKETIMEs is a negative number, 0 minutes 0 seconds is returned.
LANGUAGE
LANGUAGE <character set=> <SPEAKING=xx>
The “Speaking=<language>” parameter is used to set the starting language for a survey or reporting run; if you don’t specify it, it defaults to the first language on the “set=()” list. In addition to the language set (set=(en sp) for example), you can also use the 2 special options “**”, which means by default use all languages, and “!!” which means show all the text, including the “\Lxx” text, on the screen and/or in all output files.
These same options can be used on the >LANGUAGE command to affect output files from Mentor “print” statements or ~reformat output.
EXAMPLE:
PREPARE: [xxxx,language=(speaking=en) MENTOR: >language speaking=en
LISTFILE
LISTFILE <filename> option1
The >LISTFILE command is used to switch to a new list file from within a spec file. The original list file will be the list file defined on the command line. This can be used with the same options as the listfile: command-line keyword.
EXAMPLE:
>listfile list1 (This will be directed to the list file named “list1”) >listfile list2,echo (This will be directed to the list file named list2 and it will echo to the screen) >listfile list1 append (This will be appended to the list file named “list1”)
LOCATION_FORMAT
LOCATION_FORMAT <option>
Allows the user to specify the format of data locations in Script Composer, the QSP comment line, CHK, HRD and SUM file data locations, data locations in HOLE tables, CLEANIT displays, and error and warning messages. You can enter data locations in any of the three formats, but output will be formatted according to the specification in this command.
Valid Options
- 1 Displays data locations as absolute columns (i.e., 113).
- 1/1 Displays data locations as record/column (default) (i.e., 2/33).
- A01 Displays data locations as letterdigitdigit (i.e., B33).
You can specify >LOCATION_FORMAT in the file INITIAL in CFMC\CONTROL (DOS or UNIX). This will globally control location format for any Survox program.
NUMBER_ADJUSTMENT
NUMBER_ADJUSTMENT=#
Controls truncation in the addition of binary real numbers. For example, the sum of a set of weights may be 340.5 in decimal, but 340.499999999998656 binary, which rounds to 340, not 341.
The number you specify on this command will be added (or subtracted if negative) to every number printed. The default is .0000001.
EXAMPLE:
>NUMADJ=*
Specifying * as the adjustment will tell the program to return to the default adjustment.
PASS_COMMENTS
This directs whether or not you want to pass “comments” from user spec files to the .QSP file when compiling questionnaires. The default is NO. This is put in the MENTINITIAL file. Comments made using the comment syntax (!comment xxxxx) are always passed when this is set to YES.
PLAYBACKFILES
Saves Survent session information for playback later for showing problems or remaking interviews.
Playbackfiles can be replayed to test a bug or just remake the data file in case it was lost. This can be set in the local initial file or in $cfmc/control/initial if you want it for all interviewers.
EXAMPLE:
>PLAYBACKFILES make_presentation_file echo_tells -store_files_in_study_directory
This says to make a play back file (.PBF) and make a presentation file (.PRS), including “tells” in the pbf/prs (call history dialog, etc.). It also says to write the pbf/prs/lst from Survent into the current directory (the default is to make a study.p_ directory and put them there).
>echo_presentation=html
This says the style of .prs file that you want is html (linemode and screen are other possibilities).
Put these two lines in your local initial file and do some simple interviews. Standalone or servered is fine. You can edit the .pbf file or add comments to it when submitting a bug.
If you look at the .prs file with a browser (you may need to rename it to study.html in order to get your browser to display it correctly), you’ll see an html representation of the interview you did written out as if it were one long scroll instead of individual screens. You’ll get this web mode file even if the interview you did was a standalone screen interview. This is extremely helpful to show someone exactly what happened.
The person receiving the pbf file can compile your questionnaire and make a Survent spec file that looks like:
>playbackfiles basefilename=mytest playbackmode=fullreplay study dbug y &study.pbf
By using this you can exactly reproduce the run. Basefilename, above, means use mytest instead of study as the root of the name for the pbf etc. files.
WebSurvent by default will make “study_password.pbf/prs/lst”, and servered Survent or webCATI will make “study_ldev.pbf/prs/lst”.
A .pbf file made in web mode will need a couple of lines at the end commented out in order to run:
'' #:fonestatus=1# '' #:callbacktime_actionword=0# '' #:fonestatus=0##:nextid=xxx# #:(what to do=)q# '' **CfMC**: signature=980436404
.pbf files from WebSurvent that were suspended will have a “quit” command at the end of the suspend process. Resuming continues appending to the pbf file, so to replay you need to comment out the mid-stream lines.
PRINT_REPEAT
As a repeat sequence (>REPEAT) is expanded in the program it will be printed to a list file as it is generated (or it will be shown on screen if no list file is specified). This lets you see how the program is treating the repeat. This is the default and need not be specified unless you need to turn off
>-PRINT_REPEAT, which suppresses the listing of the expanded repeat sequence.
PURGE_EMPTY_TR
PURGE_EMPTY_TR (files)
If a TR file is built and no records are added to it, this controls whether or not you want to keep or delete the files when the job is done. The default is to keep the files.
PURGE_EMPTY_ASCII
PURGE_EMPTY_ASCII (files)
If an ASCII file is built and no records are added to it, this controls whether or not you want to keep or delete the files when the job is done. The default is to delete the files.
PURGE_SAME
Purges any existing file (except the list file) that has the same name as any new file created by the program. Without PURGE_SAME, the program renames old files by changing the file name’s first letter to the next alpha character. (AFILE, for example, would become BFILE.) You need to specify this before the program creates the new file.
Use >-PURGE_SAME to return to having files renamed. If you want >PURGE_SAME to be a default for all of your runs, put in your INITIAL or MENTINITIAL file.
PUT_CHARACTERS
Allows you to specify three characters which designate how to fill a field containing zeros (either integer or floating point) or missing data.
The syntax is:
>PUT_CHARACTERS=abcd
The first character specifies the field filler for integer zeros, the second is for floating point zeros, and the third character is for missing data. A fourth character may be specified for empty cells.
The default value for >PUT_CHARACTERS is “-” for integer zeros, “0.00” (to the appropriate decimal significance) for floating point zeros (indicated as “0”), and “?” for missing data values; to return to these defaults, specify >PUT_CHARACTERS=-0?.
Any character (except for B or Z) can be printed in the rightmost column of all appropriate fields by entering that character in the location corresponding to the type of field. Put B in any of the fields to indicate blanks, or Z for zeros.
NOTE: If you have more than one PUT_CHARACTERS set (from >PUT_CHARACTERS, ~DEFINE_EDIT=PUT_CHARACTERS, or ~DEFINE_COLUMN_INFO=PUT_CHARACTERS), the >PUT_CHARACTERS values are read first, then individual tables may override that with an EDIT=PUT_CHARACTERS, and individual columns or rows in a table may override that with COLUMN_INFO=PUT_CHARACTERS or STUB=[PUT_CHARACTERS] respectively.
QUIT
Immediately quits the current program and returns to the operating system prompt. Temporary files used by the program are not purged. Use this command with caution because changes made to open data files will not be saved.
If there is any text on the line after the QUIT, that text will be displayed by the program when it terminates.
The syntax is:
>QUIT ERRORS=#
The job will quit if the number of errors up to this point is greater than or equal to the number specified here (#). The default is 200.
RANDOM_SEED
RANDOM_SEED=#
Allows you to set a specific seed for the Mentor vector function RANDOM_CATEGORY, and the Survent function RANDOM. This way, you can always generate the same results for these functions.
READ
Allows the user to enter one command from the console (including Enter) before the program returns to processing. The user will see this prompt: ===> This command can only be used on an interactive run (e.g., Mentor &spec.spx con)
EXAMPLE:
~INPUT data.asc SELECT=& >READ ~OUTPUT subset.asc, WRITENOW ~END
REPEAT/END_REPEAT
Sets up a repeating pattern to produce multiples of specifications, using variable names for changing items within the repeated sequence. This can be used to create PREPARE specifications for repeated questions (e.g., rating scales), blocks of questions, or text. The repeat elements are then used in the specifications (which must be between >REPEAT and >END_REPEAT commands). The program will repeat the specifications as many times as needed, based on the number of repeat elements, up to 10,000 iterations. The maximum number of variables allowed is 1,000. The maximum line width that can be generated by >REPEAT has a default of 132 characters. This can be changed by the command line keyword SPEC_WIDTH.
The syntax for a repeat block is:
>REPEAT $NAME1=Element1a,...,Element1n; $NAMEN=Elementna,…,Elementnn . Text or command lines to be repeated ... . >END_REPEAT
$Name1=
The repeat elements (limited to 19 alphanumeric characters) must be preceded by a dollar sign ($). They are followed by an equal sign and the specific variables.
Element1a
Variables must be enclosed in quotes if they contain spaces, commas, or semicolons, or if they don’t begin with a letter or numeric digit. Repeat elements are not case sensitive.
EXAMPLE:
>REPEAT $A=1,2,3;$B=Apples, Oranges, Bananas
{ RATE$A:
How would you rate $B?
!FIELD
3 Excellent
2 Fair
1 Poor }
>END_REPEAT
This example would generate three different questions, the first one being:
{ RATE1:
How would you rate Apples?
!FIELD
3 Excellent
2 Fair
1 Poor }
Any dollar signs needed as part of the specification that precede a letter (e.g., $M) must be preceded by an extra dollar sign (e.g., $$M). Single dollar signs in other places are fine.
To return a quote, use two quotes in a row.
EXAMPLE:
>REPEAT $A="The title is ““My Fair Lady!””
Repeat elements must end with an underscore ( _ ) if the next character runs into the element name (i.e., $A_01 so the program looks for $A, not $A01. See REPEAT_VARS_ALPHA_ONLY.)
EXAMPLE:
>REPEAT $A=1,2,3;$B=30,31,32 VAR$A_A: [$B^1//4] >END_REPEAT
Would generate the following:
VAR1A: [30^1//4] VAR2A: [31^1//4] VAR3A: [32^1//4]
You can also use an ellipsis ( . . . ) to designate a pattern in the variables. 10, . . . ,15 means 10,11,12,13,14,15, while 10,12, . . . ,20 means 10,12,14,16,18,20. The pattern can decrement as well as increment. The default pattern is 1; you can establish a different pattern by specifying two single variables before the ellipsis. Text cannot be set up in an ellipsis other than simple uses (i.e., a, . . . ,g).
EXAMPLE:
VAR15: & >REPEAT $A=19,...,22;STRIP="WITH &" [$A^1//5] WITH & >END_REPEAT
Would generate:
VAR15: & [19^1//5] WITH & [20^1//5] WITH & [21^1//5] WITH & [22^1//5]
STRIP
Strip= lets you specify a string or literal that will be removed from the final element in the repeat string.
By default, Mentor replaces >REPEAT variables with their values as soon as it encounters them. >REPEAT can “pass through” variables as variables when >REPEAT is used in conjunction with >ALLOW_INDENT. When >ALLOW_INDENT is ON and file name with an ampersand within a >REPEAT is indented, variables are passed through rather than expanded. All variables will be passed through, including $text strings.
In this example, Mentor will not bring in the contents of the referenced file:
>ALLOW INDENT >REPEAT $F=1,2,3 &file$F >END_REPEAT
Mentor will pass through the variables in file1, file2 and file3 and issue a warning:
**gen** &file1 (WARN #4275) AMPERSAND file &file1 being passed thru **gen** &file2 (WARN#4275) AMPERSAND file &file2 being passed thru **gen** &file3 (WARN #4275) AMPERSAND file &file3 being passed thru
See also >ALLOW_INDENT, >END_REPEAT, >PRINT_REPEAT and >REPEAT_VARS_ALPHA_ONLY.
INLINE_REPEAT
The >inline_repeat command works just like >repeat, except that “ampersanded” files are not read into the specs until after the repeat has completely “unwound.” This makes it possible for the filename itself to contain a repeat dollar substitution. This command was created to help make international/multi-language questionnaires easier to write.
EXAMPLE:
~def >inline_repeat $f=a,b,c &mt2426$f.spx >endrepeat **gen** &mt2426a.spx one: 1 two: 2 three: 3 **gen** &mt2426b.spx four: 4 five: 5 six: 6 **gen** &mt2426c.spx seven: 7 eight: 8 nine: 9 ~end
REPEAT_VARS_ALPHA_ONLY
Has the program read repeat element names as alphabetic only. Use this command before doing repeats so that when the program sees ‘$A01’ in a spec line it knows that the ‘01’ is not part of the repeat name. Otherwise you need to write it as ‘$A_01’.
SAVE_AS_FILE
SAVE_AS_FILE <filename>
Saves all input entered prior to the command in a file of the specified name. This includes both what you type and commands called in from other files.
For example, you could use this command if you are working interactively in C-Mentor and have gotten several errors and you want to save what you have entered so far so that you could edit it. You could then use the edited file as your spec file.
You can also put this command in your INITIAL or MENTINITIAL file to have it create a file of commands each time you use Survent or Mentor.
STATUS
STATUS <option>
Displays the current status of the specified files.
Valid Options
- ALL – Displays the status of all files currently opened. This is the default and can also be done by entering >STATUS with no option.
- DB – Displays the status of your DB file(s).
- FILES – Displays a list of all open files including msgfile, console, temp files, input, and output files. It also lists how many blocks of far memory are available.
- INPUT – Displays the status of your input file, and lists the study code (if any).
- OUTPUT – Displays the status of your output file, and lists the study code (if any).
STOP_WATCH
Displays timing information in minutes and seconds. This command works in tandem with the ~STOP_WATCH command. Two numbers are returned; the first is the elapsed time since the beginning of the run, and the second is the elapsed time since the last >STOP_WATCH or ~STOP_WATCH command. You will get a total timing at the end of the run regardless of the use of >STOP_WATCH or ~STOP_WATCH.
TAB_WARN
Controls whether the warning “converting tabs to spaces” for text lines in spec files prints or not. Default is on, so use >-TAB_WARN to suppress the warning. Mentor converts tabs to spaces (one space per tab).
TERMINAL SCREEN SIZE
“>SCREENSIZE ## ##” COMMAND ALLOWS BIGGER SCREENS FOR TERMINAL MODE SURVENT
You can now set up a standard screen size for terminal mode interviewing with Survent. Previously you were restricted to 24 lines in DOS mode and 23 lines in Unix mode. If your terminal mode client supports it, you can do as many lines and columns per screen as you want.
For instance: >screensize 80 100
Would make screens 80 lines by 100 columns wide. You would place the command in the file control/initial or in a “local” initial file. The command only affects screens in Survent, not other Survox applications
TRANSLATE ASCII_VALUE ASCII_VALUE
Translates one ASCII character to another.
EXAMPLE:
>TRANSLATE 65 97
This will change all capital “A”s (ASCII 65) to lower case “a”s (ASCII 97). A separate translate command must appear for each different character to be translated.
The >TRANSLATE command operates on all characters which appear in the spec following it, not just those that are a part of titles, stubs, etc.
NOTE: Be careful not to issue a >TRANSLATE command that will change Mentor commands and keywords. This command not only affects text you enter at the keyboard, but also affects text generated by Mentor, such as automatic labels.
Tables may be run and stored in a DB file, then a >TRANSLATE command issued just before the load and print phase of a run, as in the example below.
EXAMPLE:
>USE_DB trans1 >TRANSLATE 65 97 >TRANSLATE 66 98 ~EXECUTE load=T001 print ~END
Miscellaneous Meta Commands
DB_TO_FILE
DB_TO_FILE <filename> <dbentryname>
Writes the DB entry to an ASCII format file. You must have a DB file open to use this command (see >USE_DB). This works for ASCII type entries only (i.e., titles, labels), DB item type=123. This is the reverse of the FILE_TO_DB command.
EXAMPLE:
>DB_TO_FILE ban1 banner1_bn
In this example, the DB entry BANNER1_bn is sent to the text file BAN1.
FILE_TO_DB
FILE_TO_DB <name> <filename or #>
Writes a file with variable specifications to the DB file (opened with ReadWrite access). This is the reverse of the >DB_TO_FILE command.
EXAMPLE:
To put specs in a DB file under a ‘name’: >FILE_TO_DB name filename
A pound sign (#) after the name means to read from the spec file immediately following until an end-of-file is encountered.
EXAMPLE:
>FILE_TO_DB mystub # TOTAL NO ANSWER [print_row=AR] ANY RESPONSE } >EOF
This example would store the lines listed after the pound (#) sign in the ‘save to’ DB file under the name MYSTUB. This item could then be referenced to build tables with this label set as the tables’ stub preface.
KEY_DELAY
KEY_DELAY # <filename>
Sets the speed of keystroke display (in milliseconds) for replaying a >SAVE_KEYS file.
The higher the #, the slower the rate of replay. The KEY_DELAY command is optional. By not specifying KEY_DELAY you allow the key file to replay at maximum speed but you will not be able to follow the keystrokes. 100 is a reasonable speed.
There are several # values that do special tasks:
- 1 – Requires that a key be pressed at each word, Enter, ESC, or F – # key to continue the display.
- 2 – Requires that a key be pressed at each keystroke to continue the display.
- #, # – The first number controls the replay speed of text and the second number controls the replay speed of all other keystrokes (e.g.,: Enter, ESC, cursor arrow keys, function (F) keys).
- This option is very useful for demonstration purposes, since text can be played back to the screen quickly while other “operational” keystrokes can be slowed down enough for the observer to see exactly how something was executed in that particular program.
SAVE_KEYS
SAVE_KEYS <filename.key>,#
Saves all keystrokes after the command (up through the next >SAVE_KEYS, if any), in a file of the name specified. The file can then be called in (&filename.KEY) and the program will rerun all keystrokes.
Valid Options
- filename.KEY – The extension is optional; if left off, it will be added to the filename. No other extension can be entered.
- # – This saves and closes the file after n number of keystrokes is saved. Any number may be specified here. The default is to only save the keystrokes when the file is closed.
EXAMPLE:
>SAVE_KEYS keeper,1
This will save and close the file after each keystroke. This is valuable when your system is crashing and you are losing the SAVE_KEYS file. This will slow response time considerably!
The key file can be edited, allowing you to delete or add key commands such as Halt which causes the keystroke display to stop at that point and wait for an Enter to continue.