SYSTEM Statements

SYSTEM statements are used to access outside systems and allow you to escape from the Survent program to execute outside programs, use operating system commands, or talk to the modem port in DOS or UNIX. You can also change languages or quit the interviewing session using SYSTEM statements.

The syntax for a SYSTEM statement is:

!SYSTEM,subtype

Valid Subtypes

  • Do_Command
  • Run_Program
  • Do_Command_Save_Data
  • Run_Program_Save_Data
  • Execute_Compiler_Directive_Block
  • Set_For_Interview_End
  • Set_Interviewer_Time_Zone
  • Set_Language
  • Write_To_Interviewer_Log_Record
  • Write_To_Serial_Port

DO_COMMAND and DO_COMMAND_SAVE_DATA

Short form: SYS,DOCOMMAND / SYS,DOCOMMANDSAVEDATA 

Old form: SYS,1 / SYS,4

This executes an external program. When the SYSTEM, DO_COMMAND_SAVE_DATA executes, Survent is exited, and saves the existing data case as “cfmd####” where “####” is the station number of the device executing the SYSTEM command. Once the external program has finished the file “cfmd####” is read back into the memory.

EXAMPLE:

{ DO_LOTUS:
EDIT MYFILE
LOTUS %1 %2
!SYSTEM,DO_COMMAND }

Adding an additional sub option to the command will give you the 
return code of the command, 1 = failed and 0 = success

The sub option can be a data location or a label.

{ DO_LS_COMMAND:
ls -l myfile
!SYSTEM,DO_COMMAND,101.1 }
If you provide a data location on the label it will store up to 100 bytes
 of STDOUT from the command and it can be used within survent.

{ DO_LS_COMMAND: 102.100
ls -l myfile 
!SYSTEM,DO_COMMAND,101.1 }

 

RUN_PROGRAM or RUN_PROGRAM_SAVE_DATA

Short form: SYS,RUNPROGRAM / SYS,RUNPROGRAMSAVEDATA Old form: SYS,2 / SYS,5 This statement sends operating system commands. When the SYSTEM,RUN_COMMAND_SAVE_DATA executes, Survent is exited, and saves the existing data case as “cfmd####” where “####” is the station number of the device executing the SYSTEM command. Once the external program has finished, the file cfmd#### is read back in to the memory. EXAMPLE:

{ COPY_OUTPUT:
cp /u/cfmc/output_file* dir output*
!SYSTEM,RUN_PROGRAM }


Adding an additional sub option to the command will give you the 
return code of the command, 1 = failed and 0 = success

The sub option can be a data location or a label.

{ DO_LS_COMMAND:
rm /u/cfmc/output_file 
!SYSTEM,RUN_PROGRAM,101.1 }
If you provide a data location on the label it will store up to 100 bytes
 of STDOUT from the command and it can be used within survent.

{ DO_LS_COMMAND: 102.100
rm /u/cfmc/output_file 
!SYSTEM,RUN_PROGRAM,101.1 }

 

EXECUTE_COMPILER_DIRECTIVE_BLOCK

Shortform: SYS,EXECCDBLOCK There are multiple HTML commands that you can use to give your surveys a certain look. These blocks of commands can be used in conjunction with the SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK command that can be used when you want to have the same look and feel from screen to screen on your online surveys. You can define a block of these commands and call them anywhere in your spec where you want to use them.  When you want to use this block of code in your spec, simply place a SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK command that references the name of the block. The syntax for the SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK statement is:

!SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK,<name of block>

EXAMPLE:

{!SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK,DEFAULT }

The example above will call in a block of code called DEFAULT. This block of code will apply until another !SYSTEM,EXECUTE_COMPILER_DIRECTIVE_BLOCK command is called. You can change individual commands at any time. Keep in mind that once changes are made to individual commands they will apply until another block is called or the individual command is changed again.

The name of the block of code being applied needs to be predefined before using it.  The block is defined within a CD_BLOCK. (See Interview Control Commands – Start_CD_Block for more information).

SET_FOR_INTERVIEW_END

Shortform: SYS,SETFORINTERVIEWEND

This statement causes the interviewing session to end immediately after the current interview. It will save the current data case if the interview is completed. If an AFTER_QUIT block is used in the questionnaire, it will execute the questions in that block after ending the interview and before ending the interviewing session, and it will generate a separate data case with the same case ID for the answers in that block.

SYSTEM, SET_FOR_INTERVIEW_END allows you to specify the reason for the exit from the interview.

The syntax for the SYSTEM,SET_FOR_INTERVIEW_END statement is:

!SYSTEM,SET_FOR_INTERVIEW_END,<QUIT/LUNCH/BREAK>

EXAMPLE:

For instance, if you enter

{!SYSTEM,SET_FOR_INTERVIEW_END,LUNCH }

to send an interviewer to lunch, it will display a note on their terminal that they have gone to lunch.

SET_INTERVIEWER_TIME_ZONE

Shortform: SYS,SETIVRTIMEZONE

This command allows you to specify which time zone the interviewer is in and pass it to the Survox server so that calls get routed properly, according to which time zone the interviewer is in. The time zone can be either a two-digit or three-digit number. If it is two digits, it is a regular Survox time zone 01-24. If it is three digits and the last digit is “5” then it is a “half” time zone, eg. “225” would be time zone 22 and 1/2.

This feature is designed for phone applications where you cannot predetermine which time zone an interviewer will be in. In other cases you can set the time zone as part of the login script or in the Survox ttyinfo file. But, it will work in either terminal or online mode.

SET_LANGUAGE

Shortform: SYS,SETLANG

This system command sets the language to be used in the questionnaire from this point. Languages must have been programmed into the questionnaire for this to take effect. Interviewers may also set the language by using the “L=xx” command where “xx” is the language they wish to use.

EXAMPLE:

{ SET_FRENCH:
!IF Language(F)
!SYSTEM,SET_LANGUAGE,FR }

If you are using “1 character language coding” by specifying “language set=(e=en f=fr)”, then on the !SYSTEM,SET_LANGUAGE command you also use one-character codes such as “!SYSTEM,SET_LANGUAGE,E”.

WRITE_TO_INTERVIEWER_LOG_RECORD

Shortform: SYS,WRITEIVR

This command sends data to the end of the INTVRLOG record for this interview. The statement is designed so that you can add custom information to the standard Survox log records saved in the INTVRLOG file.

The syntax for the SYSTEM,WRITE_TO_INTERVIEWER_LOG_RECORD statement is:

!SYSTEM,WRITE_TO_INTERVIEWER_LOG_RECORD,<column in log record>,<width>

EXAMPLE:

{ LOG_TEXT:
<standard Survox text line with \: & \| stuff>
!SYSTEM,WRITE_TO_INTERVIEWER_LOG_RECORD,2001,1000 }

This will put the specified text line into the INTVRLOG in the user area (2001-3000) of that interviewer’s log record. The column must be between 2001 and 3000, and the column-width must be ⇐1000.

You can also retrieve what you have stored in the interviewer log file or other information in the file by using the syntax “\|%column.width|”.

WRITE_TO_SERIAL_PORT

Shortform: SYS,WRITEPORT

This command talks to a port on the local computer.

The syntax for the SYSTEM,WRITE_TO_SERIAL_PORT statement is:

!SYSTEM,WRITE_TO_SERIAL_PORT,<port #>,<baud rate>

EXAMPLE:

{ INITIALIZEMODEM:
!SYSTEM,WRITE_TO_SERIAL_PORT,2,9600 }

This initializes a modem on port 2 to 9600 baud.

{ CALLCFMC:
atdt14157770470
!SYSTEM,WRITE_TO_SERIAL_PORT }

This sends an “AT” command string to the modem. Once the port and the baud rate have been identified, they do not need to be re-specified.

Next Topic