The Phone System
6.1 INTRODUCTION TO PHONE SYSTEM
The Survent phone system is designed to reduce much of the labor and paperwork associated with managing phone numbers for telephone interviewing. The phone system performs the following:
-
If a predictive dialer is being used, it assigns the interviewer to a study; the dialer calls numbers until it reaches a person, at which time the call is directed to the available interviewer to complete the survey.
-
If a preview dialer is being used, numbers are called for that interviewer until a person is on the phone, at which time the call is directed to the interviewer. In this case the interviewer waits until one of the numbers dialed for them reaches a person with whom to complete a survey.
-
If a modem or autodialer is used, the number is dialed by the system, the interviewer waits for the call status and records it or completes the survey.
-
If no dialing equipment is directly connected to the computer, it gets the next number for the interviewer; the interviewer dials the numbers and records its status until they reach someone to complete a survey.
-
Alternately, the phone system can get specific records requested by phone number, name, address or other information in the sample file (e.g. for respondent call-in studies or Web surveys).
-
Once retrieved, the program records the outcome of the call (busy, no answer, etc.) along with any notes associated with the call. If the call is partially completed, it saves the responses and makes them available when the call is continued.
-
Unanswered or busy phone calls are rescheduled according to rules that you set up. (You may change the rules at any time.)
-
Numbers may also be assigned to specific interviewers or interviewer types for special handling.
-
Unanswered or busy phone numbers are retrieved according to your rules, keeping a log of each attempt. This feature eliminates the need for comp lex callback schedules.
-
Allows interviewers to enter a specific callback time, date, or time-of-day and retrieves the phone number at that time.
-
Generates summary reports, including interviewer productivity and call scheduling status reports.
There are many features available in the phone system. Some things are best explained by example. So, throughout the chapter, there are “example file” references. These files are either questionnaire specification files (e.g. PHONE^QPX) or Mentor specification files (e.g. MOVER^SPX) that are working examples of phone system features. (NOTE: for DOS users, Mentor spec files may require a key to be run). The files are located in the /cfmc/survent directory. We encourage you to compile and run these examples to get a clear picture of how the related feature works.
At the heart of the phone system is the phone file. The phone file consists of two parts: the phone parameters and the phone records.
The phone parameters are the set of rules used to dial numbers, such as how many time zones, times available to call, and number of calls to make. There is a default parameter list you maintain that is loaded when the phone file is built.
The phone sample is generally provided by an outside source, or you can generate a sample of phone numbers with Mentor. If provided, it generally comes with information about the business or household at that number. You must put this file in a specific format (telephone # first, text starting in column 51, etc.) using Mentor or some other file processing program (see example file MOVER^SPX and 6.1.1 Building the Phone File).
The program FONEBULD reads the formatted sample file to build the phone file for your study. It first reads the standard calling parameters into the phone file (which you may modify as you see fit), then it reads the file of phone numbers. The phone numbers are linked in “stacks” according to your calling rules as the file is built.
Each record in the phone file contains the phone number, user- supplied text, system-related information and a history of each previous call. Survent chooses a phone number to retrieve based on the calling parameter rules and loads it in memory to be used during the interview. It writes back into it data you specifically place there and additional information about what happened to the number (it was dialed but not answered, answered but not qualified, etc.).
To use the phone file for dialing, PHONE statements must be added to the questionnaire. These statements cause the number to be retrieved, display phone information, change parameters, and get or put information to/from the phone record. If the call does not result in a completed interview, the interviewer is prompted to enter a call status or the program provides one; otherwise, the interview is completed and the phone record is marked as having been completed.
When the number receives a non-complete status, Survent reschedules the number according to your calling rules. For example, if the number is busy, the system might schedule it for callback in X minutes. If it is disconnected or inoperative, it will never appear again. Or, it may be scheduled for a callback at a later time that is convenient for the respondent.
Most parameters may be changed by the supervisory program SURVSUPR while the study is in progress (see the MPF option in 4.4.2 SURVSUPR MAIN MENU, Options). Using SURVSUPR, you also have access to information about the numbers: how many have been called, how many are to be called back, the number of disconnects and unused numbers, etc.
In terminal mode, if Survents lose contact with the CfMC server (UNIX/MPE) the phone record will be saved back to the phone file with status 190. In addition, the data record is suspended and saved, allowing you to resume the interview immediately or later on. The call is re-scheduled as a timed call 24 hours later. This is done by checking for the terminal’s “SIGHUP” signal periodically; if it disappears the program suspends the call.
FONEUTIL provides many functions regarding management of the phone file. It can report on subsets of the numbers, clear unwanted call histories, verify and/or fix a file, print numbers according to your criteria, or make a copy of the phone records which can be changed and added back in later for callback.
See 6.7.1 Managing the Phone File with FONEUTIL for more information. Mentor and Utilities will read a phone file for reporting, even while the study is active.
6.1.1 Building the Phone File (FONEBULD)
FONEBULD builds the phone file by reading the default “shop” file of calling parameters (or some other file you specify), then reading the sample records provided and loading them in the appropriate “stack” to be called.
The raw file to be loaded into FONEBULD must have the following column-specific format. If necessary, you must use your data processing package or example file MOVER^SPX to get your data into the proper column positions:
Column
1-18 Phone number (area code, exchange, number), left- justified. Spaces, parentheses, dashes and
other non-digit characters are cleaned to return the remaining digits as the phone
number. This is the only REQUIRED field. Note: U.S. numbers must be exactly 10
digits long; for international phone numbers, the minimum is 6 digits, and the
maximum is 18.
6-19 ID:xxxx If assigning interviewer ownership, this specifies the ID of the interviewer
to make the call (see //6.6.5 Ownership Mode//). **Note**: Notice that this
overlaps the phone number field, so the phone number is limited to 12 or fewer
digits if this option is used. If used, this must be placed immediately after the
last digit of the phone number. Optionally, you may use the keyword
OWNER_LOC=<location.width> and place the ID of the owner there.
20 D Daylightsavings switch - A D here says that this phone number is in an area that
does NOT observe daylight savings time.
21 Targeted Dialing Flag (T) This can be used to cause numbers to be "targeted" dialed by a dialing even if
the study is being run in "predictive mode"
22 Special interviewer type (0-9) This can be used to assign the number to a special-language interviewer
or for some other reason assigned to a particular group of interviewers; the number will
go to the standard calling stacks but be moved to the special interviewer stack at the
time it is scheduled to be called.
23-24 Time zone (01-24) This is REQUIRED for time zones or area codes not supported by the CfMC zone table;
it is optional if you are using standard North American phone numbers; time zones start
at 01 for Greenwich Mean Time; “Eastern time” is time zone 05 and “Pacific time” is time
zone 08.
25-34 Case ID (4-10 digits) If pre-assigning a data record to use with the phone number, this is the data
record’s case ID (See //6.6.5 Existing Case Mode//). Another option that you can use
is CASEID_LOC=<location.width> where you should place the case ID other than in the user
text area.
31-46 Initial calling state If blank, the number is placed in a ‘fresh number' stack.
Other options are:
1. The date/time to make the first call. You may use any of the standard CfMC date/time formats, including
the format “YYYYMMDDHHMM", where YYYY=year, MM=month, DD=day, HH=hour of day, and MM=minute. For example,
“201712231530” would make the first call to the number on DECEMBER 23, 2017 at 3:30pm. Note that these times
are always machine time. Numbers with times already set up for other time zones will need to be adjusted.
2. "SPECIAL=#" to put the number directly into a special interviewer stack (#=0-9, see also column 22 above).
3. BUCKET=# Where # is 1-8 to call in a particular daypart, or BUCKET=9 to save the number to be called later
(see the USE_HOLDING_AREA parameter for more information).
4. STACK=# to put the record in a particular stack (see //6.4.1 How the Phone System Schedules Calls//).
47-49 “Replicate” (001-999) If this is used, phone numbers are loaded in numbered groups so you can control
when the group is released for calling using SURVSUPR. If replicates are used, the sample
file must be loaded in replicate order.
50 Not used (Used by CfMC when reading ASCIIfied phone files)
51-4950 User-supplied information Information, such as respondent name and address.
This can be limited using the TEXTLENGTH=XXXX command for smaller files.
EX:
1 2 3 4 5 6
1234567890123456789012345678901234567890123456789012345678901234567890
2125551212 R. Cramden Bus Co.
FONEBULD will check for valid phone numbers before loading them. If the phone records are in North America, the program will attempt to verify that the area code and exchange are valid and assigns numbers to the proper time zone. It will also check for duplicate numbers and valid phone parameters if they are preset on a record. Additionally, FONEBULD removes all non-digit characters from phone numbers before trying to process them. This means you can get phone number info in any format (eg. ”(415) 444-0470”), and it will be readable into FONEBULD without additional cleaning of the data.
You can create a phone file of up to 999,999 numbers. If you have a limited disk space or a busy system for outbound calling, CfMC recommends that you only load enough numbers to call over a limited time period, because the processes you need to run on the file may take a long time to process for larger files.
In addition, FONEBULD allows you to specify a filename instead of a study code. In particular, this allows you to reference files in other directories when trying to add sample. Fonebuld allows the use of paths or the use of environment variables (for example, !CFMCFONE!) as part of the filename.
FONEBULD supports THE “FONESTAT” file to use different status labels for different studies Fonebuld creates a ”.fst” file with the labels to use for this study when you create a .fon file. You can edit this file and copy it to $CFMC/control and Survent, and the phone reports will use the labels as you describe them. By default, the server and phone reports will look for <study>.fst before using the default “fonestat” file in $CFMC/control.
You can also specify a name of a file to use for your study. The file with the name you specify MUST be placed in the $CFMC/control directory. If you use the name ”<study>.fst”, the phone reports will also pick up the statuses from that file.
FONEBULD supports quota names in phone record so server suppresses overquota records in lieu of market controls
FONEBULD now allows you to specify the location of the quota name you want checked before the server releases the phone number. If the quota name is greater than it’s target, the record will be assigned the status you want. This allows you to suppress the release of numbers to a dialer or interviewers that are over quota.
This feature is similar to the “market” feature, but it has a disadvantage because it has to check each record for its quota information and then give statuses based on whether it is over quota or not. Markets will disallow access to the stack if the market weight is set to zero so the records are not processed at all.
The advantage of this feature is that it can be used with as many quota names as you want (up to 1000 triple quotas and even more numbered quotas). Also, used in conjunction with the quota_percentage feature, you can control the release of sample if you have for instance daily quotas. You may also use this in addition to market controls.
The keywords and their meanings are as follows:
Keyword Meaning
quota_name_location=#,# The location of the quota name in the phone record. The quota name can be up
to 28 characters. If the name is all digits it will use a numbered quota.
quota_target_name_location=#.# The location of the target quota in the record (otherwise it uses quotaname.T
if you are using "triple_quotas").
quota_full_phone_status=# The status to assign if the quota is full.
quota_full_callback_minutes=# The number of minutes to call overquota numbers back in if the status is a
callback status.
The server counts the number of records released so far in that quota group and will never release more numbers than what would fill the target quota if all the released records were completes. If the quota is a numbered quota, the server will not keep track of the number of records submitted for each number, so it will be a simple shutdown of the quota once it is full.
Once the quota name value is greater than or equal to the target value, the record is given the “quota_full_phone_status”. If no status is specified it gives it status 80 by default. You can specify the status to assign in the parmfile as well using “QUOTA_FULL_PHONE_STATUS: #”, but if you assign a status in FONEBULD that will be the one it uses.
If there is no quota name in the field the record is treated normally. To show the active quotas, say “show_phone_quotas <study>” in the supervisor.
Examples of the show_phone_quotas option:
Enter a SUPERVISOR command-->showphonequotas quota_in_phone / from TNM server: ( CELL_ONE: val= 0 inc 1) from TNM server: ( CELL_FOUR: val= 0 inc 1)
The above example shows that 2 interviewers are running, with 1 interviewer on a cell_one record and 1 interviewer on a cell_four record.
Enter a SUPERVISOR command-->showphonequotas quota_in_phone \ from TNM server: ( CELL_THREE: val= 1 inc 2) from TNM server: ( CELL_FIVE: val= 2 inc 1)
The above example shows that 3 interviewers are running with 2 interviewers on cell_three records and 1 interviewer on a cell_five record.
The val= is the current quota value, and the inc is the number of interviewers who currently have that type of quota record.
FONEBULD supports quota percents in phone record so server suppresses overquota records in lieu of market controls
Related to the QUOTA_NAME_LOCATION feature, this allows you to specify a percentage of the target that you want to call for now, and give a status for the server to assign if that percentage is met. Then, you can change the percentage to release those numbers later. This way, you are, in effect, spreading calls evenly across the supported quotas as they are filled. You use a quota to set the percentage you want to try currently.
The keywords are:
Keyword Meaning
quota_percentage_target_location=# The place in the record where the name of the quota with the target
percentage is. This could be updated by a supervisor during the study. If it contains
a number it is a numbered quota.
quota_percentage_full_phone_status=# The status to assign numbers that are attempted to be picked up when
their quota is greater than the percentage of the target specified above. This should be
an active status > 100 so the numbers can be re- released later.
NOTE: You can use the command USE_MASTER_QUOTA=yes in the fone header of worker studies to have all of the above quota commands refer to the master quota file study if the project is set up as a Master Quota project.
In addition, FONEBULD supports clusters in phone record.
You can now specify phone records in “clusters” such that the server will only hand out one number in that cluster at a time. Once the number is put back in the phone file, it can retrieve another number in that cluster. If you want to control what happens when you get a complete in that cluster you need to do that with quotas or other logic.
The keywords are:
Keyword Meaning
cluster_location=#.# Contains a number which identifies the 'cluster' the record is in.
cluster_active_callback_minutes=# Specifies the number of minutes to schedule numbers rejected
because their cluster was busy for. The default is one minute.
To show the cluster activity in the supervisor, type “show_phone_clusters <study>”.
The syntax for running FONEBULD is:
FONEBULD <listfile>
The listed output will go both to the screen and to the disk file named <listfile>.
To read in a file (or part of a file) of commands to begin FONEBULD, this is the syntax:
FONEBULD “&myfile.spx(1/20)” con
FONEBULD expects an option, HELP for a display of the options, or GO to begin entering file and study names. You can give commands from a file, but it is often used interactively to set initial parameters, etc. Here is the list of FONEBULD options displayed when you type “Help”:
ASCII – Reload an ASCII sample file converted from a CfMC converted sample file using FONEUTIL.
When using the ASCII option to load numbers that have previously been called, if any ascii record has more history slots than the current configured maximum, the program will stop loading numbers with an immediate fatal error UNLESS the FONEBULD command DROP_EXTRA_HISTORY_SLOTS has been specified. If this is the case for ALL ascii records loaded, the first slot and the last n-2 slots will be kept, where n is the number of configured history slots, and all other call histories will be discarded.
COMPRESS – Takes the existing .fon file and removes the space used by the deleted records.
Duplicates_file <name> – Name of file to save the list of numbers that you attempted to add to a file with duplicates=no for some index, such that the number was resolved with status 91 and not available for calling.
DO_NOT_CONTACT file <name> – Name of CfMC system (.tr) file that contains the list of number to compare to when loading records such that if there is a match the record will be put in the “Do not call” stack and will not be available for calling.
Rejects_to_file <name> – Save rejected numbers to file <name>
Stop_after=# – Stop reading phone records at record number #
Shop_file – Work with phone parameters in interactive mode
Read_shop_file <name> – Read a named shopfile, or ‘shopfile’ if no <name>
Write_shop_file <name> – Write a shopfile of the current parameters. Will be written with <name> or ‘shopfile’
Index loc,wid/no_index – Make (default-fnx)/don’t make an index to call specific phone numbers, loc,wid is position for up to two additional indices (fny,fnz)
Market_loc <loc,wid> -Location in phone text where market names are read from. The maximum width is 20.
Max_markets <num> – Maximum number of markets allowed
Market <name> [,<number>] [,<weight>] – Name, number, and initial weight for market. Specify all markets in market location or use ‘???’ as a “catchall” category for non- matches.
Header <name><,AFTERGO> – Write phone parameters to an ASCII file now or after “GO”.
&<name> – Read an ASCII file of phone parameters
Allowdups=yes/no/XXX – Whether to allow duplicate phone numbers or index values. There are three values, so use YNN, for instance, to allow duplicates in the phone number field but not other indices, where “Y” is yes and “N” is no.
Textlength <length> – Specify phone text length for this (new) file
Timezones #-#, #, … – Specify the valid time zones this (new) file
Go – Last command; prompts for study code and file of new/ASCII records to read in and indexes the file
These are most of the FONEBULD commands that do not have anything to do with setting parameters (see 6.2.1 The Phone File Parameters).
PHONE SYSTEM COMMANDS
Here is a more detailed description of the commands:
ASCII causes the program to expect a file of converted ASCII phone records from FONEUTIL to be read. These records will have system information and call histories that will be saved into the new file. You might use this to move records from one study to another or to rebuild records. The program will only allow these type of records as input if this option is specified, although you can add as many ASCII files as you want in one FONEBULD run.
The ASCII command also allows loading numbers with extra history slots from other projects or suppliers. When using this command to load numbers that have previously been called, if any ascii record has more history slots than the current configured maximum, the program will stop loading numbers with an immediate fatal error UNLESS the FONEBULD command DROP_EXTRA_HISTORY_SLOTS has been specified, in which case for ALL ASCII records loaded, the first slot and the last n-2 slots will be kept, where n is the number of configured history slots, and all other call histories will be discarded.
COMPRESS takes the existing .fon file and removes the space used by the deleted records. This allows you to clean up the empty space in a file without converting the file to ASCII and re- building it. Just say “compress”, then “go”, then the study code, and “yes” to add numbers/rebuild index.
DO_NOT_CONTACT_FILE <name> is a file that contains numbers that are NEVER allowed to be added to a phone file. This list is used to make it possible (and relatively easy and inexpensive) to honor peoples’ requests to not be called by telephone research marketers. The DNC file should be a TR file. Currently, there is no data in the cases. It is an indexed CfMC TR file with phone numbers assigned as the case id for the file. For more detailed information, see section 6.6.2 The Do Not Contact (DNC) File.
DUPLICATES_FILE <name> is a file of numbers that are allowed to be duplicates even if you have set “allow_duplicates=nnn” (note: full command is “ALLOW_DUPLICATES_FILE”).
REJECTS_TO_FILE <name> causes FONEBULD to save “bad” records to file <name>. “Bad” records have badly formatted phone numbers or bad information in one of the other system information fields.
In addition, arguments can be added to REJECTS_TO_FILE command:
Syntax: Rejects_to_file [,-error][,-append]
Or, it can be “none” to have output go to the screen only.
The ”-error” keyword controls whether the FONEBULD run counts rejects as errors or not. The default is, if any input records are rejected then the programs ends with the error flag set. ”-Error” means records can be rejected but FONEBULD does not end in error.
“Append” means that rejected records will be appended to the specified file. The defaults are that fonebuld ends in error if rejects are found and records are not appended.
There is also the parmfile keyword REJECTFILE: [-error] [append] which can control the defaults.
STOP_AFTER=# causes FONEBULD to only read # records from the raw file into the phone file. This is often used to build a test phone file.
SHOPFILE brings up the current phone parameters in interactive mode, which can then be modified on the screen. This is the same screen as the MPF screen in SURVSUPR and the FONEUTIL “M” screen. The difference is that there are some parameters that can only be modified here before the phone file is built, such as the number of time zones or phone number size. This command can be used multiple times in a FONEBULD session.
READ_SHOPFILE <name> reads a shopfile previous written to a file with the WRITESHOPFILE command. This will reset all phone parameters to the parameters in the file being read. READ_SHOPFILE NONE may be specified to INITIALIZE the shopfile so you may make parameter changes without having loaded an actual shopfile.
WRITE_SHOPFILE <name> writes the current phone parameters to a file, which can be later be read. To set up your standard ‘shopfile’, run FONEBULD, use the SHOPFILE command, make the changes you want, then save the file to the CfMC CONTROL area with the name SHOPFILE; eg. In DOS, say “WRITESHOPFILE \cfmc\control\shopfile”. You may also make standard files for particular types of studies.
INDEX <loc.wid>/NOINDEX these commands control whether to make indices for the phone file of the phone number and/or other fields. Indices allow the program to retrieve numbers when you ask for a specific number (see the !PHONE,5 statement). NOINDEX says don’t make any index at all. The default is to make an index of the phone number only. INDEX <loc.wid> says to make an index using the field <loc.wid> in the user text. The maximum index width is 18. You can have up to 2 indices in addition to the phone number field. Example: INDEX 51.14 will make an index of the data in the field from column 51-64. The indices are checked for duplication if you have the ALLOW_DUPLICATES option set to NO for that index, e.g., “Allowdups=NNN”.
MARKET_LOC <loc.wid> tells the program where the market name is in the user text area of the phone record (See discussion of MARKETS below). MARKET_NAME_LOCATION 61.20 would say that the market name is in the field 61-80. This may also be filled in on the SHOPFILE screen. The maximum width is 20.
MAX_MARKETS # tells the program how many markets to allow for. Set this high if you expect to add more markets later (MAXIMUM_MARKETS).
MARKET <name>,<number>,<weight> must be specified for each market that you plan to add. The market number and weight are not required, just the name. If the number is omitted, the next number is assigned. It is a good idea to keep the market name specification in a file to remake the markets later and document the market number/order assigned.
HEADER <name> writes an ASCII list of the phone parameters to file <name>. This list can be edited and read in using “&<name>” in future FONEBULD runs, or just saved for documentation purposes. If you want it to write out the phone parameters after the raw records are compiled, use the syntax “HEADER <name>,AFTERGO” (note: the full command is “ASCII_FONE_HEADER”).
&<name> reads in lines from the file <name>, usually previously created with a HEADER command. This might also be a set of MARKET commands or any other FONEBULD command (See the utilities manual for more &<name> options).
GO Causes the program to ask for a study code and the name of a file or files to process, then start processing phone numbers. Sample records are checked for valid syntax and valid phone numbers. If ALLOWDUPS=no, duplicates are resolved with status 91. All valid numbers are added to the phone file and placed in the proper calling stack. If a phone file exists with the study code specify, the program will ask if you wish to add numbers to the existing file, and will add the new numbers to the file if you say so. The INDEX files are refreshed each time GO is specified as well (See INDEX below).
The rest of the options on the help screen are phone parameters that are discussed in 6.2.1 The Phone File Parameters below. The following command is not on the help screen but may be needed on occasion:
INDEX_FILE_SIZE=XXXXX tells the program the maximum number of items to allow in the indices; the default is twice as many entries as the number of records initially built into the phone file. This is used in case you are adding phone records “on the fly” during the interview and you want to allow for many records to be added later. The current maximum is 999,999.
When building the phone file, if the SHOPFILE option is not used, the initial phone parameters are read from the local file called SHOPFILE; if there is none, the program uses the shop file in \CFMC\CONTROL.
Here is a listing from a sample run showing the creation of a phone file with FONEBULD:
EX: FONEBULD option, HELP, GO, or QUIT---> go Type a study code (up to 6 characters)--> bank Name of a file of phone numbers or Enter to quit---> phon1 Here we go (1 dot per 10 records) put 3032772782 in bucket 3 put 3032772117 in bucket 4 put 3032775222 in bucket 6 call 3032778371 at 27 MAR 2012 11:00am call 3032771630 at 13 APR 2012 09:31am Added 135 record(s) Name of a file of phone numbers or Enter to quit---> <Enter> Added 135 record(s) in all Total records in phone file bank.fon = 135 Total reads to phone file: 388 Total writes to phone file: 256 ***THAT IS ALL ***
In this example, FONEBULD created a phone file called BANK.FON from a file of phone numbers (PHON1), using the standard shop file parameters. If you already have a phone file corresponding to the study code specified, then FONEBULD will ask you if you want to add to the old phone file or if you used an existing name by mistake. You answer the same prompts, but you will see new information as the program finds and reads the existing file and adds to it. You cannot add numbers to an active file with FONEBULD (see 6.3.1 The PHONE Statement, Phone, Letter Subtypes to add numbers to a live file with Survent).
FONEBULD creates the phone file with the parameters taken from the standard shop file (SHOPFILE in the current directory or the CfMC CONTROL area), or the one specified with the SHOPFILE option. The phone file will be named with the study name and the extension FON, e.g., JB123.FON. If INDICES are created for the phone number or other fields, the files <study>.FNX (phone number index file), <study>.FNY (second index file), and <study>.FNZ (third index file) will be created.
FONEBULD looks in two places to determine the time zone of each number. First, it looks in columns 23-24 of the raw file to see if you have told it what time zone it is in. If you have a value there, it uses that. You MUST have a value there for numbers not in NORTH AMERICA. If you do not have a value there and the INTERNATIONAL_DIALING_OPTION is not set, it uses the file \CFMC\CONTROL\ZONETABL, to check the area codes and exchanges and assigns them to the proper time zone in North America. If it does not find a valid time zone match by then, FONEBULD prints an error message, and does not add the number to the phone file.
NOTE: The phone file is by default created indexed. This allows the interviewer to ask for specific phone numbers. See 6.3.1 The Phone Statement for more details on this. An FNX file will be created in addition to the FON file, and both files must be moved to the CFMCFONE subdirectory.
The BREAK key is disabled when adding to an existing phone file. Ctrl-Y will tell you what record it’s currently processing. FONEBULD will check for bad numbers, i.e., non-existent area code, and issue an error message like the following example:
EX: "Invalid phone number (999 555 1212), will not add."
800, 888, and 900 phone number area codes will be set to time zone 6 unless you override this in columns 23-24 of the raw record, or change the ZONETABL using the MAKEZONE utility (see 5.13 MAKEZONE).
Unless DUPLICATES OK has been set to YES in the shop file, duplicate numbers will be resolved with status 91. These numbers will be put in the phone file but never be called. To keep a duplicate number OUT of the phone file, see example file DUPES^SPX, or use FONEUTIL to delete the numbers after they have been built into the file.
FONEBULD will prompt for another study when you are done processing the first. If you type “newfile” at the prompt, it will prompt you again for commands to start building or adding to another phone file.
6.1.2 Adding Records to an Existing Phone File
FONEBULD also allows you to add more phone numbers to an existing phone file, or to rebuild a phone file once it has been converted to ASCII(but still keep histories, etc.). To add new numbers to an existing file, use the command GO, enter the study name, and then enter the file name of new numbers.
The ASCII option of FONEBULD allows you to rebuild phone files from records converted to ASCII by FONEUTIL or Mentor. This will allow you to retain the original phone histories of these records. It also means you can edit the records and read them to a phone file, or convert records from some other study to be continued in your new study.
To rebuild a phone file or add records converted from some other study, use the ASCII option, enter the name of the study, say GO, then enter the name of the converted ASCII file.
6.2 THE PHONE FILE
When the phone file is built, the parameters are loaded into the top of the file followed by the phone records. The records are given a record number and linked together in “stacks” with pointers that point from one record to the next record in its stack. The number of phone records allowed per study is 10 million. A phone file can have up to 4.28 gigabytes for systems that support files greater than 2.1 gigabytes.
The records contain detailed information including when it was initially loaded, information on the status of the number, and a call history for each call. The following is a description of the parameters in the file that control how Survent will retrieve phone numbers and a description of the fields recorded in the phone file.
6.2.1 The Phone File Parameters
When you run FONEBULD, the initial set of phone file parameters are read into the phone file. These control how Survent behaves when it goes to retrieve phone numbers for calling. They can be modified interactively in FONEBULD using the SHOPFILE screen, in SURVSUPR while a study is live, or in FONEUTIL when a study is not live. Each parameter also has a command that can be used to change it. The set of commands to create the parameters can be created using the HEADER command in FONEBULD or FONEUTIL, which may then be edited and read into any of these programs. Here is the standard parameters screen:
-------------------- PHONE PARAMETERS for -------------------
Phone file version: 62.1 Phone number size: 10 Allow duplicates?: No
Daylight savings?: No Phone text length: 200 Preferred TOD loc: 0 .0
Intv owner mode?: No # Call histories: 10 Market name loc.: 0 .0
# of time zones: 4 File-type: 0 Zero weight status: 0
Time zones: 5 6 7 8 Country Code : 0
Time zone weights: 1 1 1 1 Max attempts: 10
Outofnumbers delay: 10 seconds Timed use MaxAtt?: No
-------------------- SYSTEM 'NO ANSWER' CALLS --------------------
Maximum replicate: -1 New numbers first?: No
Dp time1: 08:00am time5: 12:00am #Att Dp1: 1 New numbers avail.: -1
time2: 12:00pm time6: 12:00am #Att Dp2: 1 Release system #s?: No
time3: 05:00pm time7: 12:00am #Att Dp3: 1 Release AllTrgAtt?: No
time4: 09:00pm time8: 12:00am Dp opt.: 0 Min sys callback: 180 min
Use bucket order?: No # busys --> NA: 2
Invert bucket list?: No Holdarea option: 0 Release HoldArea?: No
-------------------- TIMED CALLS --------------------
Shop MON: 09:00am | 09:00pm SAT: 09:00am | 09:00pm Release timed?: No
open/ TUE: 09:00am | 09:00pm SUN: 09:00am | 09:00pm Timed exact?: No
shut WED: 09:00am | 09:00pm Max callbackage: 30 min Retry busy in: 30 min
times THU: 09:00am | 09:00pm Last scheduled: NONE SPECIFIED
FRI: 09:00am | 09:00pm Last delivered: NONE SPECIFIED
<Enter> or arrow keys to move, ESC to exit
To change a setting, use the arrow keys (monitor) or Ctrl-U (for up on a terminal; use D for down, R for right, and L for left) to position the cursor on the item, and enter the new value. When you are finished, press ESC to exit.
What follows are explanations of the items included on the parameters screen. After each description the corresponding command is given with a sample value. An asterisk (*) before an item means that that option can be changed in the CONSOLE or from a terminal using the SURVSUPR MPF or FONEUTIL M commands once the phone file is built. Items that do not have an asterisk before can only be changed by building a new phone file.
GENERAL PARAMETERS
FILE VERSION The version of the software and phone file. The software version is for major changes in the structure of the phone file and is hard-coded in the software.
(PHONE_SYSTEM_VERSION=1)
Shortform: (PHONESYSVERS=1)
DAYLIGHT SAVINGS Controls whether the system should adjust calling times for Daylight Savings Time. When set to Y(YES), DST is in effect. This will cause the program to make the appropriate time adjustment for those areas that do not observe daylight savings time. For example, Arizona, which is in the Mountain time zone and does not observe daylight savings, will have all its numbers act as though they were in the Pacific time zone.
NOTE: For North American phone numbers the daylight savings switch can be gotten from the zone table, but for international numbers it will need to be manually set. See FONEUTIL options SPRING_FORWARD and FALL_BACK to change this once the phone file is built.
DAY_LIGHT_MODE=YES/NO
Shortform: DAY_LIGHT=Y/N
*INTERVIEWER OWNERSHIP MODE Specifies whether you are using interviewer ownership mode in this study. This option allows numbers to be assigned to particular interviewers. The default is NO. (See OWNERSHIP MODE discussion below)
OWNER_MODE=YES/NO
NUMBER OF TIME ZONES The number of time zones into which phone numbers may exist. The maximum is 24. They need not be consecutive
NUMBER_OF_TIME_ZONES=7
Shortform: NUMTIMEZONES=7
TIME ZONES The time zones used. A time zone is specified as a number, where 24 is Greenwich Mean Time. The zone to the west is 1 and each subsequent zone to the west is incremented by 1, up to 24. Time zones 5, 6, 7, and 8 are Eastern, Central, Mountain, and Pacific times in North America. Alaska is in time zone 9 and Hawaii is in time zone 10 during non-daylight savings time and is in 11 during daylight savings time. Time zones 22, 23, and 24 are for Eastern Europe, Western Europe, and the UK. Half time zones are dealt with by using a letter (A-X) to stand for the time zone in column 23 and a 5 in column 24. A5 would be timezone 1.5, B5 is 2.5, and so on. You must set at least one time zone before exiting. The time zones used do not have to be consecutive
TIME_ZONES=5,6,7,8,9,10,11
Abreviation |November,AT,CVT |Oscar,VTZ,FDT |Papa,BST,ART |Quebec,AST,BOT |Romeo,EST,COT |Sierra,CST,MEX |Tango,MST |Uniform,PST |Victor,AKST,YST |Whiskey,HST,THAT|X-ray,NT,SST |Yankee,IDLW,Mike,NZST |Lima,UZ10,SBT |Kilo,USZ9,GST |India,USZ8,JST |Hotel,USZ7,CCT |Golf,USZ7,JT |Foxtrot,USZ5,BDT |Echo,USZ4,PKT |Delta,USZ3,GST |Charlie,MSK,BT |Bravo,EET,R1T |Alpha,CET,MET |Zulu,GMT,UTC,WET UTC Time Zone |UTC-1 |UTC-2 |UTC-3 |UTC-4 |UTC-5 |UTC-6 |UTC-7 |UTC-8 |UTC-9 |UTC-10 |UTC-11 |UTC-12/+12 |UTC+11 |UTC+10 |UTC+9 |UTC+8 |UTC+7 |UTC+6 |UTC+5 |UTC+4 |UTC+3 |UTC+2 |UTC+1 |UTC CfMC Time Zone |1 |2 |3 |4 |5 |6 |7 |8 |9 |10 |11 |12 |13 |14 |15 |16 |17 |18 |19 |20 |21 |22 |23 |24
Time Zone City Lookup – http://www.worldtimezone.com/
*TIME ZONE WEIGHTS Used to change the proportion of non- timed dialings made to each time zone. Setting WEIGHTS= 2 1 1 1 would cause the first time zone to be called twice as often as would otherwise be expected (see How Survent Chooses a Phone Number). Setting a given time zone’s weight to zero will exclude that time zone from attempts, except for specific-timed callbacks, Weights can be integers from 0-9.
TIME_ZONE_WEIGHTS=1121112
Shortform: TIMEZONEWGHTS=1121112
*OUT OF NUMBERS DELAY Number of seconds to pause between attempts to get a number by an interview when the system has run out of numbers. The accepted range of values is 0-99 seconds. The default is 10 seconds. Typically if a study is out of numbers only a modification to one of the dialing rules or a change in the clock time so that another time period is entered will cause numbers to become available.
OUT_OF_NUMBERS_DELAY=20
Shortform: OUTOFNUMDELAY=20
PHONE NUMBER SIZE Maximum number of digits in the phone number. The accepted range of values is 5 to 18. If the International Dialing Option is set to no and the phone number size=10, all numbers must have 10 digits.
PHONE_NUMBER_SIZE= 10
Shortform: PHONENUMSIZE= 10
PHONE TEXT LENGTH The amount of user text the phone file is to hold. This number may be up to 4900 and must be a multiple of 100.
PHONE_TEXT_LENGTH=900
Shortform: TEXTLEN=900
NUMBER OF CALL HISTORIES The maximum number of call attempt results saved for a number. A history includes a call’s start time, seconds on the call, the interviewer ID, the call number, and its assigned status. If more calls are made to a number than allocated here, call result information will be lost. The program will save the first attempt and the last N-1 attempts where N is this setting. The maximum value here is 99.
NUMBER_OF_HISTORIES=20
Shortform: NUMHIST=20
FILE-TYPE Can be set to any number 1-99 and is used for just informational purposes.
FILE_TYPE=3
ALLOW_DUPLICATES Controls whether to check the phone number or the other 2 indices in the phone file for duplicates. If set to Yes (YYY is “yes” for each index), it will allow duplicates in all the indices the phone file. If set to No (NNN), duplicates will not be allowed in any of the indices. The three characters are “Ys and “Ns” where “Y” means duplicates are allowed for that index, and “N” means they are not. ALLOW_DUPS=NYY means duplicates are disallowed for the phone number index, but allowed for the other two indices. Numbers that are duplicates are resolved with status 951 and stored in their own stack. NOTE: You may get duplication in your file later if you allow phone numbers or the other indices to be changed during interviewing.
ALLOW_DUPLICATES=YYY/NNN
Shortform: ALLOWDUP=YYY/NNN
The allowable settings are:
NNN duplicates not ok for any index.
NNY duplicates not ok for phone numbers nor index 1, but ok for index 2
NYN duplicates not ok for phone numbers nor index 2, but ok for index 1.
NYY duplicates not ok for phone numbers, but ok for index 1 and 2.
YNN duplicates are ok for phone numbers but not for index 1 nor 2.
YNY duplicates are ok for phone numbers and for index 2, but not index 1.
YYN duplicates are ok for phone numbers and for index 1, but not index 2.
YYY duplicates OK for all indices.
PREFERRED TIME OF DAY LOCATION This tells FONEBULD which bucket to use when scheduling system calls (1-9); you may specify a different order for groups of records or all records, allowing independent call scheduling for each phone record. You can fill the field specified with the values to control the order before the file is built, or “on the fly” during interviewing by using !PHONE,PUT_FONE_TEXT” statements to fill the proper field before the system schedules the next call. This does not affect the first call to the number, because this is controlled by the initial call state setting in the raw phone record (columns 31-45). See the section on PREFERRED TIME OF DAY calling for more information on how to use preferred time of day sampling.
PREFERRED_TIME_OF_DAY_LOCATION=151.5
Shortform: PREFTODLOC=151.5
MARKET NAME LOCATION This indicates where the market name is in the phone text area. Specifying markets allows you to control the release of sample by the number of numbers in the market and by using market weights. Small markets will be released slower than large markets. The market name consists of a position and width, the position must be in the phone text area and the width must be 1-20.
MARKET_NAME_LOCATION=181.7
Shortform: MARKETLOC=181.7
MARKET WEIGHT ZERO STATUS Says what status to give to timed numbers that attempt to come up when the market weight for their market is set to “0”. Because some statuses are used by CfMC and some statuses cause inappropriate actions, this is limited to the following statuses: Release number status: 0 Resolved statuses: 10-70 Nonspecific callback statuses: 107-156 or 191-199 Nonspecific callback statuses/No history: 201-209 or 213-214.
NOTES: If it is set to 0, no status is given and the number comes up to be called. This option appears as “ZERO WEIGHT STATUS” in the Console and in the Supervisor on the MPF screen.
MARKET_WEIGHT_ZERO_STATUS=213
Shortform: MARKETZEROSTATUS=213
INTERNATIONAL_DIALING_OPTION If you set the international dialing option to 1, the system will not check for valid North American numbers. You will have to supply the time zone information though for these records in columns 23-24 of the raw record. Phone numbers are displayed without extra formatting characters, i.e., (415) 777-0470 is displayed using INTERNATIONAL_DIALING_OPTION=0 but it is displayed as 4157770470 otherwise.
INTERNATIONAL_DIALING_OPTION=1
Shortform: INTDIALOPT=1
*MAXIMUM ATTEMPTS Specifies the number of calls to make to a phone number. If you wish to hold some of the attempts back for additional calls later on then set this number to be >= the sum of attempt1, attempt2, and attempt3. By default, timed call backs do not pay attention to this setting, unless you use the TIMED USE MAXIMUM ATTEMPTS setting or you assign status 184 .
Calls that are resolved due to maximum attempts are assigned a final status of 973, but are still assigned their current status in the “last call status” field. For instance, if maximum attempts is set to 5 and on the 5th attempt the call is a No Answer, the final status will be 973, but the last status will be a 101. See the USE HOLDING AREA setting for additional ways to override this setting. The maximum value is 999.
MAXIMUM_ATTEMPTS=10
Shortform: MAXATT=10
*TIMED USE MAXIMUM ATTEMPTS If set to “Yes,” then the system will resolve timed numbers with a status of 973 when the hit the maximum attempts value. The default is that timed numbers get rescheduled instead of being resolved
TIMED_CALLS_USE_MAXIMUM_ATTEMPTS=NO
Shortform: TIMED_USE_MAX_ATTEMPTS=NO
SYSTEM CALL PARAMETERS
These parameters control the release of new numbers and rescheduling of “no answer” callbacks.
*MAXIMUM REPLICATE If ‘replicates’ have been assigned in your phone records, then only those new numbers with a replicate number less than or equal to MAXIMUM REPLICATE will be released to the system. For example, if you set this to 3, then any new phone number with a replicate number of 4 or more will not be released. Once a number has been dialed, it is no longer under replicate control. If set to -1, then replicate control is ignored. This cannot be changed to/from –1 once the phone file is built as the program checks for valid replicate numbers when it builds the file.
MAXIMUM_REPLICATE=23
Shortform: MAXREP=23
*DAY PART TIME 1 The beginning of the day during the week (Monday – Friday) in respondent time for system scheduled calls. This also defines the beginning of the day for Saturday if SATURDAY START TIME is not set and for Sunday if SUNDAY START TIME is not set. No respondent will ever receive a system scheduled call before this time, although timed call backs are allowed. (See the options SCHEDULE_WITHIN_DAYPARTS_ONLY and CALLS_RELEASED_WITHIN_DAYPARTS_ONLY to override this.
DAYPART1=11:00am
*DAY PART TIME 2 The end of the first time period and the start of the second time period during the week for system scheduled calls. The time is respondent time. DAY PART TIME 2 must be later in the day than DAY PART TIME 1.
DAYPART2=1:30pm
*DAY PART TIME 3 The end of the second time period and the start of the third time period during the week for system scheduled calls. The time is respondent time. DAY PART TIME 3 must be later in the day than DAY PART TIME 2.
DAYPART3=5:30pm
*DAY PART TIME 4 The end of the day during the week. This also defines the end of the day for Saturday if SATURDAY STOP TIME is not set and for Sunday if SUNDAY STOP TIME is not set. The time is respondent time. DAY PART TIME 4 must be later in the day than DAY PART TIME 3. No respondent will ever receive a system scheduled call before this time, although timed call backs are allowed. (See the options SCHEDULE_WITHIN_DAYPARTS_ONLY and CALLS_RELEASED_WITHIN_DAYPARTS_ONLY to override this.
DAYPART4=9:00pm
*SATURDAY START TIME The start of the day for Saturday. This will also be the start of the day for Sunday if SUNDAY START TIME is not set. Set both SATURDAY START TIME AND SUNDAY STOP TIME to 12:00 am to not use them.
SATURDAY_START_TIME=10:00am
*SATURDAY STOP TIME The end of the day for Saturday. This will be the end of the day for Sunday if SUNDAY START TIME is not set.
SATURDAY_STOP_TIME=6:00pm
*SUNDAY START TIME The start of the day for Sunday. Set both SUNDAY START TIME AND SUNDAY STOP TIME to 12:00 am to not use them.
SUNDAY_START_TIME=11:00am
*SUNDAY STOP TIME The end of the day for Sunday.
SUNDAY_STOP_TIME=5:00pm
NOTE: Using the Time Period Option (TPO) will affect how day parts are handled.
USE BUCKET ORDER Says whether or not to use a custom bucket priority order for calling system scheduled callbacks. If set to Yes, a prompt will appear, requesting the bucket order. The default is that system scheduled callbacks are called using bucket order 1-7.
USE_BUCKET_ORDER=NO
BUCKET_ORDER=#,#,#,#,#,#,#,#,#,# Determines the priority order of buckets to look for system callbacks to be called.
The default is 1-7 then 0, with buckets 8 and 9 having special controls.
This means calls that have had the most system attempts have the highest priority. If you say “BUCKET_ORDER=0,7,6,5,4,3,2,1”, new numbers will have the highest priority, then numbers available in all time periods, then numbers in some periods, and finally numbers only available in this period. If you just want to dial new numbers with the highest priority use the NEW_NUMBERS_FIRST option.
BUCKET_ORDER=1,3,5,2,4,6,7,0,9,8
*INVERT BUCKET LIST If set to YES, this will reverse the bucket order search so that instead of looking for numbers in the call specific buckets first (1-3), then the call in some time period buckets (4-6), and then the call in any time period bucket (7), the program will look first in bucket 7, then in 6-4, and then in 3- 1.
INVERT_BUCKET_LIST=NO
*NUMBER OF CALLS PER DAY PART Three numbers specify the number of attempts to make in each time period. TARGET1 sets the number of calls in day part 1 which by default is Monday through Friday from day part time 1 to day part time 2. TARGET2 sets the number of calls in day part 2 which by default is Monday through Friday from day part time 2 to day part time 3. TARGET3 sets the number of calls in day part 3 which by default is Monday through Friday from day part time 3 to day part time4 and anytime on the weekend. The order in which the attempts are made cannot be specified unless using preferred time of day sampling. If a call’s length causes it to go across dayparts, it counts as an attempt in the earlier day part.
TARGET1=2
TARGET2=2
TARGET3=3
*DAY PART CALLING OPTION (DP Opt) The day part calling option controls how the system handles the scheduling of “system” callbacks. “System” callbacks include no answers, multiple busies, answer machines, and all other non-timed call-backs. The day part calling option is also referred to as the Time Period Option (TPO).
The default is that there are three time periods called:
-
morning (or day part 1)
-
afternoon (or day part 2)
-
evening (or day part 3)/weekend
If you assign one call to be made in each period, then if you call in the morning the first time, the number will be assigned to the ‘call afternoon or evening/weekend’ category. The next call will only occur in one of those two time periods. If the next call occurs on a weekday afternoon, then the third attempt will be scheduled for an evening/weekend call. Note that timed calls get counted as having occurred in their time period also.
TIME_PERIOD_OPTION=1
Shortform: TPO=1
The Day Part Calling Option (TPO) can be set as follows:
TIME_PERIOD_OPTION=0 (or 1) is the default setting described above, where morning/day part 1 is between day part time 1 and day part time 2, afternoon/day part 2 is between day part time 2 and day part time 3, evening Monday-Friday is between day part time 3 and day part 4, and weekends are Saturday-Sunday between day part time 1 and day part time 4 anytime. See section on day part times for setting start and stop times for the weekend.
Day part 1 = Time1 to Time2 (Monday-Friday morning)
Day part 2 = Time2 to Time3 (Monday-Friday afternoon)
Day part 3 = Time3 to Time4 (Monday-Friday evening, or Saturday-Sunday any time)
TIME_PERIOD_OPTION=2 causes the program to treat all seven days of the week the same; whatever you set your times to, those times are used the same for each day of the week.
Day part 1 = Time1 to Time2 (Monday-Sunday morning)
Day part 2 = Time2 to Time3 (Monday-Sunday afternoon)
Day part 3 = Time3 to Ttime4 (Monday-Sunday evening)
TIME_PERIOD_OPTION=3 causes the program to treat each weekday as if it only had two day parts, any calls scheduled for day part 3 will be called on the weekend only. No “system” calls will be made after day part time3 during the week.
Day part 1 = Time1 to Time2 (Monday-Friday morning)
Day part 2 = Time2 to Time3 (Monday-Friday afternoon)
Day part 3 = Saturday-Sunday any time
TIME_PERIOD_OPTION=4 treats each weekday as having three time periods, but Saturday and Sunday are ignored. This is for weekday-only calling. Note, the only difference between this and the default is if an interviewer were to accidentally try to dial on the weekend, the system would not release any numbers.
Day part 1 = Time1 to Time2 (Monday-Friday morning)
Day part 2 = Time2 to Time3 (Monday-Friday afternoon)
Day part 3 = Time3 to Time4 (Monday-Friday evening)
TIME_PERIOD_OPTION=5 treats the weekend days as having three time periods, but Monday to Friday are ignored. This is for weekend-only calling.
Day part 1 = Time1 to Time2 (Saturday-Sunday morning)
Day part 2 = Time2 to Time3 (Saturday-Sunday afternoon)
Day part 3 = Time3 to Time4 (Saturday-Sunday evening)
*HOLDING AREA OPTION The “Holding Area Bucket” is an extra bucket in each time zone where numbers can be saved to be released using the RELEASE_HOLDING_AREA setting. Numbers can be saved there either by giving them phone status 189 or 214, pre-assigning them in the phone record using the BUCKET=9 command in columns 31-45, or using this option.
USE_HOLDING_AREA=0
Shortform: USEHOLDAREA=0
The USE_HOLDING_AREA option can be set as follows:
2= maximum number of attempts have been made to a number
3= Both 1 and 2
4= used to ignore minimum system callback time. Users that have markets who want their timed numbers moved to the holding area when the market weight is zero, and called as soon as an interviewer is available to call that market.
Note that the 3 holding area options (1,2 and 4) can be combined so they get used in tandem. For example, Use_holding_area=6 would cause numbers hitting the max attempts to be put in the holding area, and those numbers would ignore the minsyscallbacktime.
*RELEASE HOLDING AREA This allows numbers currently in the “Holding Area Bucket” to be dialed. Numbers can be stored here for use at some later date. This is often useful for putting aside number when you have daily or weekly quotas and the number is currently in a full quota cell, but would be usable when quotas reset.
RELEASE_HOLDING_AREA= Yes
Shortform: RELEASEHOLDAREA=Y
*NEW NUMBERS FIRST Controls the priority of new (never called) numbers. If set to YES, it will cause new numbers to come up before system scheduled callbacks. Otherwise, callbacks have a higher priority than new numbers. You may also set this to a percentage value from 1-99 to have new numbers get an xx% chance of coming up first, but you may only do this using the keyword, not on the SHOPFILE screen, eg. FRESHFIRST=80. This is for cases where you want to “blend in” new numbers with the scheduled callbacks.
FRESH_FIRST=NO
Shortform: FRESHFIRST=N
*NEW NUMBERS AVAILABLE Controls the availability of new (never called) numbers. The allowable range is -1 to 1000000. The default is set to –1; this setting is ignored, allowing an unlimited number of new phone numbers to be used by the system. If greater than 0, each new number that comes up decrements NEW NUMBERS AVAILABLE by 1; when it reaches 0, new numbers will no longer be called. This allows you to call the first 100 new numbers, then stop calling new numbers until these are called again (don’t retrieve any more), then you can set it to 100 again, etc. If set to 0, new numbers will not be used. This allows you to force calling of callbacks only.
NOTE: This option appears as “#FRESH” in the Survox Console and on the MPF screen in the Supervisor
NUMBERS_FROM_FRESH=-1
Shorthand: NUMFROMFRESH=-1
*RELEASE SYSTEM NUMBERS This allows calls to all system-scheduled callbacks even though they may only have attempts left in other day parts. For example, suppose you are trying to complete a study on the weekend, but have no new numbers left, and have exhausted all evening/weekend attempts on existing numbers. By setting this item to YES, you would make numbers that only had morning or afternoon attempts left available now. All system numbers are still subject to the MINIMUM SYSTEM CALL TIME setting though.
RELEASE_ALL_STACKS=YES
Shortform: RELEASESTACKS=Y
*RELEASE ALL TARGETED ATTEMPTS When a number has had all day part attempts (as specified in DAY PART TARGETS), but has not reached the maximum number of calls (as defined in MAXIMUM CALL ATTEMPTS), it is placed in the ATA (all targeted attempts) bucket (bucket 7).
It remains there until RELEASE ALL TARGETED ATTEMPTS is set to Y(YES). This can be used to make three attempts on a number now, but save it so you can make a fourth attempt later on, if you are running low on available numbers.
ALL_TARGETED_ATTEMPTS= YES
Shortform: ATA=Y
*MINIMUM SYSTEM CALLBACK TIME The minimum time in minutes before a number scheduled as a “system” call-back can come up to be called again. Regardless of any other settings, no “system” number will be called before this amount of time has elapsed since its last attempt. Numbers scheduled for callback at a specific time by the interviewer are not subject to this restriction. The accepted range of values is 10-9999 minutes.
MINIMUM_AGE=180
Shortform: MINAGE=180
NOTE: Also refer to parmfile option MINAGE_LIMITS which controls what users can specify for minimum age limits of “no answer” call backs.
NUMBER OF BUSIES CHANGED TO NO ANSWER This setting allows you to control how busies are treated. This controls two things: first, how many busies will be allowed before treating the number as a No Answer (call status 103); second, whether to count the intermediate busy calls toward the total number of calls made.
The value specified can be any number from -9 to +9. 0 means that each busy is given a busy status and treated as one attempt. A negative number says how many busies in a row to allow before getting a status of No Answer, with each call counting as one attempt. A positive number says how many busies in a row to allow before getting a status of No Answer, but the intermediate busy calls will not count towards the maximum number of attempts.
The default is 2 in the standard phone system; that is, two busies in a row are treated as one No Answer, with this only counting as one call for the purpose of counting attempts.
NUMBER_OF_BUSY_GETS_NO_ANSWER=2
Shortform: NUMBUSYNOANSWER=2
Example1: NUMBER_OF_BUSY_GETS_NO_ANSWER=4 and you get two busies and one no answer, that will count as a single attempt with 3 calls. The histories will get status codes 102, 102, and 101. The first two busies are not counted as attempts.
Example2: NUMBER_OF_BUSY_GETS_NO_ANSWER=4 and you make four busy calls, that will count as one single attempt with 4 calls. The histories will get status codes 102, 102, 102, and 103.
TIMED CALL PARAMETERS
These parameters control the scheduling and release of specific- timed callbacks and some additional parameters to control release of saved numbers and bucket priority list inversion.
*SHOP OPEN <day of week> Indicates when the study is started, machine time, for a particular day of the week. Timed numbers cannot be scheduled for callback before this time, they can only be scheduled between the open and shut time for each day of the week. The goal is not let interviewers scheduled call backs for times of day when the study will not be active and have interviewers available to make that call back. These times are independent of the DAY PART TIMEs and in no way affect the current availability of numbers.
OPEN_MONDAY= 09:00AM
Shortform: OPENMONDAY= 0900
Shortform: Every day of the week can be shortened to the first 3 letters in the day:MON/TUE/WED/THU/FRI/SAT/SUN.
*SHOP SHUT <day of week> Indicates when the study is shut down machine time, for a particular day of the week. Timed numbers will not be scheduled for callback after this time, they can only be scheduled between the open and shut time for each day of the week. These times are independent of the DAY PART TIMES and in no way affect the current availability of numbers.
SHUT_MONDAY= 11:00PM
Shortform: SHUTMONDAY= 2100
Shortform: Every day of the week can be shortened to the first 3 letters in the day:MON/TUE/WED/THU/FRI/SAT/SUN.
NOTES: OPEN and SHUT times are both machine time, that is, the time in the time zone where the computer resides. When OPEN and SHUT times are both “12:00 am,” the study is available for timed call backs anytime on that day; when both are “12:00 pm,” the study is never available for timed call backs on that day. If SHUT time is less than OPEN time, then it is assumed to be that time the following day.
*MAXIMUM CALLBACK AGE The maximum time in minutes beyond the scheduled callback time that a call can still be made. When exceeded, the call is immediately moved to stack 313 (timed later calls) and the scheduled date/time of the call is updated to the original time on the following day. If that time is not within the open/shut and day part times, it is rescheduled as a timed call in the next available day part time. Since scheduled callbacks are of high priority, this is unlikely to happen unless your shop was not open during the original scheduled time or too many numbers are all scheduled for the same time. If MAX TIMED CALLBACK AGE is set to a negative number, and a number is not called by that time, it is resolved with status 95.
CALL_BACK_AGE=60
Shortform: CALLBACK=60
*LAST SCHEDULED The last date/time timed callbacks can be scheduled for. You will not be able to schedule a time beyond this date/time. This is to keep interviewers from scheduling calls after the study will be completed.
LAST_SCHEDULED=17DEC16 9:00PM
Shortform: LASTSCHEDULED=17DEC 2100
*LAST DELIVERED The date/time after which phone numbers for this study will no longer be released. Use only if you certain that you will not be making any calls after that date/time.
LAST_DELIVERED=31DEC16 11:59PM
Shortform: LASTDELIVERED=31DEC 2359
*RELEASE TIMED CALLS This releases specific time callbacks to be called now even though they are scheduled for later than now. If a number gets a busy status when this is set, it is given status 182 and treated as a No Answer call. Interviewers cannot schedule any timed calls when this is set because they would be called back immediately since timed calls are of very high priority. This option should be used with caution and usually only on the last few hours that a study will be active. Calls are released in callback time order.
RELEASE_TIMED_CALLS=NO
Shorthand: RELTIM=N
*TIMED EXACT Tells the program whether to try and make timed calls at EXACTLY the minute they are scheduled for, or whether to do the default of calling within 5 minutes of the scheduled time.
EXACT_TIMED_CALLS=NO
Shorthand: EXACTTIMECALLS=N
*RETRY BUSIES IN The number of minutes in the future that a busy number will be scheduled for re-dialing. The maximum is 32000. Consecutive busies act as a No Answer depending on the value of NUMBER_OF_BUSIES_GETS_NO_ANSWER. A (0) setting will cause busies to always act like No Answers. If a number is given a busy status, but the ‘busy reschedule’ time would occur after the “CLOSED” time, the number is given status 182 and scheduled to be called like a No Answer (i.e., in the next bucket time it would be available to be called in).
If the time specified is negative, for example -15, callbacks will be attempted every 15 minutes until you reach the respondent or give a different status. This is so you can get to those very busy respondents who are on the phone constantly. In this case, each call is treated as an attempt, but the number is not resolved when the maximum number of attempts is reached until it gets some other non-timed status.
BUSY_RESCHEDULE=30
Shortform: BUSYRESCHED=30
OTHER PARAMETERS NOT SPECIFIED ON SHOPFILE SCREEN
PHONE HISTORY NOTE LENGTH Sets the length of the call note field on each call history. Recommended values are either 0 (no note field) or 64 (maximum call note length).
PHONE_HISTORY_NOTE_LENGTH=64
Shortform: NOTELEN=64
SPECIAL_ONLY_SPECIAL Tells the program to not allow “normal” non-special numbers to go to special interviewer types. This is typically used when you are doing a multiple language CATI survey and you have interviewers who speak other languages, but they are not bilingual so you do not want them to conduct interviews with English speaking respondents.
SPECIAL_ONLY_SPECIAL= YES
CALLS_RELEASED_WITHIN_DAYPARTS_ONLY Does not allow the system to release a number to be dialed outside of daypart times. This keeps you from accidentally calling a respondent too early or too late. For instance, if a call was scheduled for 8:45pm respondent time and daypart time4 was set for 9:00pm, you would have only 15 minutes to make that call even if your CALL_BACK_AGE was 30.
CALLS_RELEASED_WITHIN_DAYPARTS_ONLY: YES
Shortform: CALLS_RELEASED: YES
SCHEDULE_WITHIN_DAYPARTS_ONLY Does not allow an interviewer set up timed call back outside of the daypart times for the respondent. It will keep interviewers from scheduling a call at a time the respondent is requesting even though an interviewer would be available during that time to make the call if it is outside of daypart times.
SCHEDULE_WITHIN_DAYPARTS_ONLY: YES
Shortform: SCHEDULE_WITHIN_DAYPARTS: YES
CALLER_ID_LOCATION_WIDTH Sets the location and width in the phone text area from which to get the caller ID for each record. This allows you to have a different caller ID for different records in the same study.
CALLER_ID_LOCATION_WIDTH=401.10
Shortform: CALLERIDLOC=401.10
CONSECUTIVE_NO_ANSWERS Sets the number of consecutive ring no answers in a row to a single number before the number is resolved with the associated final status. This can be used in dialing plans when you will be dialing each number a lot of times, but if you consistently get a ring no answer you want to stop. The first parameter is the number of consecutive no answers and the second parameter is the status to assign.
CONSECUTIVE_NO_ANSWERS=10,25
Shortform: CONSECUTIVENOANSWERS: 10,25
parmfile PARAMETERS USED BY THE PHONE SYSTEM
The CfMC server reads a file called parmfile in the CFMC CONTROL directory when starting up. This will set some phone parameters that may be overridden for a particular study or some that may ONLY be set for the whole system. Here is a list of the parmfile parameters used in the standard phone system:
DO_NOT_CONTACT_FILE: tells the name of the file for FONEBULD to check to disallow certain phone numbers from being added into any phone file. The file must be sorted by phone number and may have up to 70 columns of associated comments. Phone numbers that are marked as “do not contact” are saved in stack 331 of the phone file. (DO_NOT_CONTACT_FILE: BADNUMS). See Section 6.6.2, The ‘Do Not Contact File’, for more information.
END_OF_DAY: this determines what time-of-day the program will use when it decides to move timed numbers from the “tomorrow” stack to the “current” days timed stacks. For instance, if you have “END_OF_DAY: 3:00” in the parmfile, then numbers whose scheduled callback time is 2:00 am will be move to tomorrows timed stacks if a call was scheduled for 2:00am the following morning.
Similarly, if the CfMC server is running at 3:00am on that study, the phone file will be integrated following the usual rules. This command also causes the server’s log file (l<a-l><date>) to be closed and a new one started so all log records for a particular date are named with that date.
Also, it closes the “lp<date>” log of ASCII phone records if “server_write_ascii_phone_records: Yes” is set for the same reason.
HOLD_SPECIALS: YES/NO tells the phone system integrate function to ignore numbers in the special interviewer stacks. The default “NO” causes the integrate function to read through all of the special interviewer stacks to see if there are any timed call-backs that missed their appointment time and moves them back into the original time assuming that is probably a good time to call them. Setting this to NO causes the integrate to not check the special stacks and can speed up the integrate function substantially if you have a lot of numbers in those stacks.
KEEP_BEFORE_PHONE_9: YES/NO tells Survent what to do relative to questions asked prior to the !PHONE,9 statement when resuming SUSPENDED interviews. The default is that the original (old) responses are replayed when the resume occurs (when KEEPBEFOREPHONE9:NO is used). If you use the “YES” option, it will save the responses given in the current interview instead of the original. NOTE: Be careful when using this because it could affect questionnaire logic if you say “YES” and questions in the main part of the questionnaire are based upon actions done by questions prior to the !PHONE,9.
SERVER_WRITE_ASCII_PHONE_RECORDS: this command saves an ascii copy of the phone record each time you write a status to the phone file. The purpose is so that you can get realtime phone reports or transfer the data to other systems without having to convert records from your phone files.
The server writes to a file LP<ddhhmm> (DOS) or lp<ddhhmm.yyyy_mm> (UNIX) in whatever directory the server is running from (XXXXX is the day, hour, and minute the file was created, yyyy is the year and mm the month).
If you type “server:log” at a supervisor, the server closes the current lpXXXXX file and starts a new one, so you would want to do this just before running your application. Also, the “END_OF_DAY: HH:MM” parameter will cause the program to start a new “lp” file so that each “day”s files has all the records for that day.
TIME_ZONE: specifies the “local” time zone for your server to determine when to make calls to numbers. This is a required parameter for Survent.
TIMEZONE: 05
UPDATE_FONEHEAD: tells the program to update phone header information for a study as soon as the user modifies the parameters in the supervisor. The default is that the program waits until the next phone update.
UPDATEFONEFONE: YES
6.2.2 The Phone Record Layout
The file is treated as fixed-column format. In many places you can reference the field by its variable name or data location, but sometimes only the location may be referenced.
The “Type” determines how the data is stored; type S for “string variable” means the data is left-justified in the field and treated as a string, type N for “numeric variable” means it is right-justified in the field with leading spaces and can be treated as a numeric field using CfMC software.
Here is the phone record format:
LOCATION DESCRIPTION VARIABLE NAME TYPE
-------- --------------- ----------------- ----
1.18 Phone number PHONE_NUMBER S
1.3 Phone area code AREA_CODE N
4.3 Phone prefix/exchange PREFIX N
7.4 Phone suffix SUFFIX N
19.2 Reserved for system
21.1 Targeted Dialing Flag (T) TARGETED_FLAG S
22.1 Special interviewer type (1-9) SPECIAL_TYPE N
23.2 Time zone (01-24) (A-X for half time zones) TIME_ZONE A
25.10 Case ID to get for data case mode S
31.14 Callback time (yyyymmddhhmm) CALLBACK_TIME S
47.3 Replicate number (001-999) REPLICATE N
50.1 Reserved for system
51.4900 Phone text PHONE_TEXT S
4951.49 Reserved for system
5000.5 Total time in seconds on number TIME_ON_NUMBER N
5005.5 Number of attempts to number so far ATTEMPTS_MADE N
5010.5 Stack came from last call PREVIOUS_STACK N
5015.5 Time zone bucket (0-9; -1 if not in grid) BUCKET N
5020.5 Current calling stack number is in STACK_NUMBER N
5025.5 Stack was in when last hidden HIDDEN_FROM N
5030.8 Short study name (or ** if longer than 8) SHORT_STUDY_NAME N
5038.3 Length of call history field HISTORY_NOTE_LEN N
5041.3 Length of phone text area PHONE_TEXT_LEN N
5044.1 Error stack flag, 1=yes, 0=no IN_ERROR_STACK N
5045.1 1 if approx. time status APPROX_TIMED N
5046.2 Phone file version PHONEFILEVERSION N
5048.8 Name of file to resume if suspended RESUME_FILE S
5057.1 Suspend flag, 1=yes, 0=no SUSPENDED N
5058.5 If using Phone Says Datarecord mode, 1=yes PHONE_SAYS N
5063.5 Number of times phone file written to NUM_WRITES N
5068.5 Number of history slots in phone file NUM_HISTORY N
5073.2 Number of attempts, no day part ATTEMPT_0 N
5075.2 Number of attempts, day part 1 ATTEMPT_1 N
5077.2 Number of attempts, day part 2 ATTEMPT_2 N
5079.2 Number of attempts, day part 3 ATTEMPT_3 N
5081.10 Case ID of complete(left-justified) CASEID S
5091.18 Old phone number,if changed OLD_PHONE_NUM S
5110.1 Observes Daylight time, 1=yes, 0=no NO_DAY_LIGHT N
5111.3 Final status of resolved call 0=unresolved FINAL_STATUS N
5114.3 Total number of calls CALLS_MADE N
5117.3 Last history slot used LAST_HISTORY N
5120.1 If changed phone number, 1=yes, 0=no PHONE_NUM_CH N
5121.2 State code (AL-WY) STATE_CODE S
5123.3 # of times changed phone number NEW_PHONE N
5126.3 # of times cleared histories(w/ZAP/ERASE) HISTORY_CLEARED N
5129.3 Market number (0-255) MARKET_NUMBER N
5132.3 Whether number is on do not contact list DNC_FLAG N
5135-5143 Unused space
5144.7 Record number in phone file RECORD_NUMBER N
5151.1 Interviewer ownership mode:1=yes,0=no OWNER_MODE N
5152.1 Interviewer ownership changed:1=yes,0=no OWNER_CHANGED N
5153.4 Interviewer ID who owns number OWNER S
5157.4 Interviewer ID,previous number owner OLD_OWNER S
5161.15 Stack name of stack currently in STACK_NAME S
5176.3 Country code (0 or 1=U.S/Canada,or > 1) COUNTRY_CODE N
5179.8 Name of file the phone record was added from
(first 8 characters) RAW_FILE_NAME S
5187.12 Date/time phone record added to phone file
(YYYYMMDDHHMM) TIME_ADDED S
5199.8 First 8 characters of market name SHORT_MARKET_NAME S
5207.2 Market weight when converted MARKET_WEIGHT N
5209.2 Time zone weight TIMEZONE_WEIGHT N
5211.1 Whether number is “in-the-air” UP_IN_THE_AIR N
5214.3 Previous market number PREV_MARKET N
5217.3 Number of times market was changed MARKET_CHANGES N
5220.2 User Specified Phone file type PHONE_FILE_TYPE N
5222.30 Study name (30 characters) STUDYNAME S
5252.18 Time added to last stack TIME_ADDED_TO_STACK N
5270.30 Name of group hidden NAMED_HID S
5300.20 Market name MARKET_NAME S
5320.16 8 2-digit codes showing last 8 operation LAST OPERATIONS N
5336.16 Callback time of last call yyyymmddhhmmdjjj CALLBACKTIME_A N
5352.30 Label of question suspended at SUSPEND_LABEL S
5382.5 Number of "blow" if had Survent blow BLOW_NUMBER N
5387.5 Stack came from when put in "Special" stack SPECIAL_FROM N
5392.5 Stack came from when put in Targeted stack TARGETED_NUMBER_FROM N
5397.3 Actual time zone (not adjusted for DST) HOME_TIME_ZONE N
5400.3 Previous time zone (not adjusted for DST) PREV_TZ N
5403.30 Original Sample File name ORIGINAL_SAMPLE_FILE S
5433.16 Date/Time phone record originally added
(YYYYMMDDHHMMDJJJ) ORIGINALDATETIMEADDED N
5449.18 Date/Time phone record last updated by
Mentor Server access (YYYYMMDDHHMMSSDJJJ) MENTOR_MOD_DATE N
5467.2 Number of times modify by mentor/server MENTOR_MOD_COUNT N
5469.3 Version of ASCII layout (1=10.1.1) ASCII_VERSION N
Information from last call recorded: LAST_CALL S 6000.3 Call number of last call CALL_NUM_LAST N 6000.100 Position for each call history HISTORY00-HIST99 S 6003.3 status of last call STATUS_LAST N 6006.4 interviewer ID INTV_LAST S 6010.14 call time (yyyymmddhhmmss) CALL_TIME_LAST N 6028.5 # of seconds on last call e.S_SECS_LAST N 6033.1 "Daypart" (1=morn, 2=aft, 3=eve/wknd) DAYPART_LAST S 6034.64 call note on last call CALL_NOTE_LAST S Call history for each call made (1-99): FIRST_CALL S 6100.3 number of first call (001) CALL_NUM_01 N 6103.3 status of first call STATUS_01 N 6106.4 interviewer ID INTV_01 S 6110.14 call time (yyyymmddhhmmss) CALL_TIME_01 S 6124.1 day of week of first call (Mon=1, Sun=7) DAY_OF_WEEK_01 N 6125.3 Julian day of year of first call JULIAN_DAY_01 N 6128.5 # of seconds on first call CALL_SECS_01 N 6133.1 “Daypart” (1=morn, 2=aft, 3=eve/wknd) DAY_PART_01 S 6134.64 call note on first call CALL_NOTE_01 S ++ Locations incremented by 100: 6000.100, 6100.100 Locations and names are repeated for other calls: (locations incremented by 100) 6100.3,6200,...,15900 number of first call CALL_NUM_01,CALL_NUM_02,…,CALL_NUM_99 6103.3,6203,...,15903 Status of first call STATUS_01,STATUS_02,…,STATUS_99 6106.4,6206,...,15906 Interviewer ID INTV_01,INTV_01,…,INTV_99 6110.14,6210,...,15910 Call time(yyyymmddhhmmss) CALL_TIME_01,CALL_TIME_02,…,CALL_TIME_99 6128.5,6228,...,15928 first call, # seconds CALL_SECS_01,CALL_SECS_02,…,CALL_SECS_99 6133.1,6233,…. .15933 Daypart,first call (1-3) DAYPART_01, DAYPART_02, DAYPART_03 6134.64,6234,...,15934 Call note on first call CALL_NOTE_01,CALL_NOTE_02,…,CALL_NOTE_99 Note that for the slots, the last history slot comes first, and then the slots are in order from call 1 to call n. This is so you can find the last call easily.
Additional Information about Phone File Fields
TIME_ON_CALL (5000.5) Total time in seconds on this call record, which is the sum of all calls from the time the phone record is retrieved until it is put back in the phone file. For individual call times, see the call history for a particular call.
ATTEMPTS_MADE (5005.5) This is the total number of attempts that count toward MAXIMUM ATTEMPTS, that is, once this value equals the MAXIMUM ATTEMPTS value and the current status is not a timed callback, the phone record will be resolved with status 94. Also for ATTEMPTS_MADE, by default 2 busies only count as 1 attempt. This is different from the CALLS_MADE (5114.3) field, which would count the 2 busies as 2 calls. Also, ATTEMPTS_MADE gets reset when you use the “Z”ap or “E”rase options in FONEUTIL, while CALLS_MADE does not, so you always know how many calls were actually made to the number.
LAST_HISTORY (5117.3) The number of history slots used so far. If you pull this into the Survent interview using the Phone,GetInfo command it will include the current call, so it will be 1 on the 1st call. Note, other counters do not behave this way and only update at the end of the call.
STACK_ NAME (5161.15) The STACK_NAME shows the name of the stack the number is currently in. It matches the STACK_NUMBER (5020.5) but is in a more readable format. This is often used in reports; for instance, you can do a frequency report with Mentor’s ~FREQ command on this field to get a list of how many records are in each stack, or display the name when looking at a particular phone number.
It’s most useful feature, though, is that you can change the stack name and then add numbers into another file with a different version or time zone scheme and have the number go to the correct stack, without changing any other fields. To read in numbers from an old phone file and change their stack without losing any history information:
In FONEUTIL, enter D to delete (if you will be reading back into the same file), or C to convert records (to copy to a new file). Modify the STACK_NAME variable in the ASCIIfied phone file to the name of the stack you want it to be placed in. The name(s) to use are as follows:
Description: Stack #: Keyword:
Timed today 1-288 T????
where ???? is the time in 5 minute increments. "T1205" would be for 12:05pm.
Approximate timed today 289-312 TAPROX??
where ?? is the hour of the day 00-23.
Timed later 313 MANANA
Complete/resolved 314 COMPLETED
Error 315 ERROR
Duplicates 316 DUPLICATE
Hidden numbers 317 HID_(Keyword of stack came from)
e.g. HID_MANANA came from the MANANA stack.
Special Interviewers 1-9 318-326 SPEC-#
where # is for special interview types 1-9
Owned by Interviewer 327 OWNEDRECS
‘Up In The Air’ Records 328 UITA_(Keyword of previous stack)
Records for Dummy 329 DUMMYDO
‘Do Not Contact’ Records 330 NEVERCALL
Unknown Timezone Records 331 BADZONE
At the Dialer 332 ATDIALER
Created on the web 333 WEB
Email Invite 334 EMAILSEND
Email Remind 335 EMAILRMND
Call Right Now 336 CALLNOW
Named Hide 337 NHID_(Keyword of stack came from)
Get Specific Only 338 SPECIFIC_ONLY
Blow Records 339 BLOW
Email Problem 340 BAD_EMAIL
Good to Go 341 GOODTOGO
Targeted Records 342 TARGETED
343-348 Currently Not Used
Deleted records 349 FREE
System numbers 350-??? TZnnBn
where nn is the time zone relative to Greenwich (01-24), and B is the bucket (0-9).
These numbers will be put back into the correct time zone for your file, regardless of whether you have changed the time zone scheme.
TZ05B0 would be a number in time zone 5, bucket 0.
Numbers in markets 350-9600 TZnnBnMmmm
The STACK_NAME for numbers in markets is “TZnnBnMmmm” where nn is the time zone, n is the bucket, and mmm is the market number (1-255). TZ08B3M023 would be time zone 08, bucket 3, market 23.
Once you have changed the names to what you want, use the ASCII option of FONEBULD to read the records back in. The numbers will be placed in the appropriate stack.
INTERNATIONAL_DIALING_OPTION (5176.3) This field controls 2 things: Whether to check the timezone table for a proper area code/time zone, and how to format the phone number in displays. If the country code is ‘0’ or ‘1’, the zone table will check for valid area codes/time zones, and place the number in the proper time zone if not specified in the time zone field. Also, the number will be displayed like (xxx) yyy-zzzz, that is, area code in parentheses, followed by the prefix and then the exchange.
Other country codes have their numbers displayed without parentheses or dashes, and are REQUIRED to have a time zone specified in columns 23-24 of the phone record.
LAST_CALL (6000.100) LAST_CALL information is a copy of the most recent call’s call history. The information is placed in the “LAST_CALL” field as well as the field for it’s particular call number (#1, #2, etc.). This is often used for reports, for it tell the current status of the record.
WRITING THE QUESTIONNAIRE FOR THE PHONE SYSTEM
When using the phone system, the questionnaire must include PHONE statements. It may also include functions or other statements related directly to the phone system.
-
PHONE statements are used to interact with the sample file. This includes: getting a phone number from the sample file for use in the survey, displaying the phone number or any other piece of data from the sample record, retrieving data from the sample record for later use, updating the sample record, plus many other sample related functions. Note, with only a couple of exceptions noted below, you must first retrieve a sample record from the sample file before executing any of the other phone sub-types.
The syntax for the PHONE statement is:
!PHONE,subtype,<parameter1,…,parameter n>
PHONE SUBTYPES that retrieve a record from the sample file
PHONE,GET_NUMBER gets a phone number only. This is the recommended way to get the next available phone record. In predictive mode, only connected calls will be delivered to the interviewer. If you in targeted mode though, you can check quotas, display information to the interviewer, or anything that makes sense before sending the number to the dialer or even displaying it to the interviewer. See PHONE,DIAL_NUMBER to see how to then get it to be dialed in targeted mode.
PHONE,GET_NUMBER_AND_DIAL gets the number and dials it if you are connected to a dialer in targeted mode. This is only different from the PHONE,GET_NUMBER sub-type when in targeted mode. This option immediately dials the number as soon as it is retrieved.
PHONE,GET_SPECIFIC_NUMBER prompts for and retrieves a specific phone record. It is often useful to be able to get a specific phone number from the phone file, rather than one that the system automatically presents. For example, you may have 800 inbound lines set up for respondents to call in on at their convenience. The interviewer would then want to get that phone record when a particular person calls. NOTE: This sub-type can be used prior to the PHONE,GET_NUMBER command.
To get a specific number, you must have an indexed phone file (Building The Phone File) and a PHONE,GET_SPECIFIC_NUMBER statement in your questionnaire. When Survent encounters the PHONE,GET_SPECIFIC_NUMBER statement, a switch is set so that when a PHONE,GET_NUMBER or PHONE,GET_NUMBER_AND_DIAL statement is encountered, the interviewer is prompted for a number to get from the phone file. If the interviewer presses Enter at this point, instead of entering a number, the system will get the next available phone number as if in usual mode. Here is the standard prompt:
EX: Enter number to call -->
If the phone system cannot find the requested number, the interviewer is asked to enter another. If the number found is either hidden, resolved, currently being interviewed on, or otherwise unavailable a message will print to that effect and the interviewer will have to try another number. See the phone sub-type ALLOW_TO_GET_RECORD_TYPE below for options to override this.
The same will occur if the number is resolved or owned by some other interviewer or interviewer type, unless other statements are in effect to override this (see PHONE OWNERSHIP AND ALLOW_TO_GET_RECORD_TYPE sub-types).
The syntax for the PHONE,GET_SPECIFIC_NUMBER statement is:
!PHONE,Get_Specific_Number,column,width,label or location OR <col>.2 !PHONE,Get_Specific_Number,column,width,label or location
The first syntax is used when getting a number in conjunction with the PHONE,GET_NUMBER statement. The “column,width” specification tells the program what text to display from the phone file case there are duplicate numbers to choose from. The duplicates are numbered on the screen and displayed for the interviewer to choose from. The idea is to display text such as their full name or address so the interviewer will know which record to choose.
EX: !PHONE,Get_Specific_Number,101,50
This will display 50 columns of phone text information starting in column 101. Up to 650 duplicate numbers will be offered to the interviewer, who will look at the phonetext information displayed and pick the appropriate one. By default, the first 70columns of the phone text are displayed.
When looking at a screen of duplicate numbers, numbers will be shown that are hidden or resolved (and so not available) but they will be marked as “(hid)” or “(res)” on the screen.
The <label or location> is used to get a phone number using your own question display instead of the standard display. This allows you to do the following:
-
You can put whatever text you want on a prior question when asking for the phone number. NOTE: You can use the VAR,P question to get data in phone number format; that is, the interviewer can enter numbers in any of the formats ‘1- (xxx)
-
xxx-xxxx’ or such, and the program will strip everything except the phone number itself from the response.
-
You can put phone numbers in a disk-based-response list in the questionnaire and have interviewers pick which phone number they want to call. When they pick the number, you give the disk-based-response question as the label of the phone number, and the PHONE,GET_SPECIFIC_NUMBER will retrieve that number. This way, the interviewer will avoid typing mistakes.
-
You can have two additional indices with the phone file to get numbers with. The indices may be from 5 to 20 characters wide. To get a number by an index value, use a question to get the name/address/etc. desired from the interviewer (using a response list or an open-end), then send that response as the entry to look for in the PHONE,GET_SPECIFIC_NUMBER. If the index value is not found, you will be prompted for a valid phone number as always. Whatever you use as the index must exactly match what is entered–you cannot use wild cards or subsets.
If you wish to prompt for another index value, see below.
If the second syntax above is used, and you put a two-digit location on the PHONE,GET_SPECIFIC_NUMBER question label line, the program will search immediately for the number, rather than waiting for a subsequent PHONE question. Also, a value will be returned to the data that tells you the results of the search. This value can be used to do different operations (e.g. using conditional statements to display different error messages). The values returned are as follows:
Value Description BM Bad market name NI No index file. This aborts the interview. NO No more numbers OA Number is owned by someone else. SB Number is not valid (ie: too few digits) SC Specific number completed SD Number at dialer SH Specific number is in hidden stack SJ Specific number was in the BLOW stack SN Specific number not found SR Specific number resolved (but not completed) SS Number for a special interviewer SU Number currently in use by another interviewer SW Specific number wrong record (bug somewhere) SX Number not wanted on duplicates screen (reset and ask again) SZ Specific number was in “Do Not Contact” stack TA No number returned, but wait a while and try again later <blank> Good phone record returned
Using the indexing example above, if a good number was not retrieved, you could RESET to the question asking for a name/address/etc. and try again.
PHONE, GET_FROM_MARKET is used to call a number in the market specified. The syntax for the PHONE,GET_FROM_MARKET question type is:
<!PHONE,GET_FROM_MARKET,<label or location>
This is used in conjunction with special interviewer types or specific interviewer IDs to have numbers from a particular market called by particular interviewers. When using PHONE,GET_FROM_MARKET you do not need a prior PHONE,GET_NUMBER or PHONE,GET_NUMBER_AND_DIAL to get the number.
This works like the !PHONE,GET_SPECIFIC_NUMBER statement; you give it a two-digit data location, and it returns a code to the data which you use in case the number cannot be retrieved to determine what to do.
In addition, !PHONE,GET_FROM_MARKET enables you to put a list of markets or a file pattern to match a list of markets instead of a single market name.
Where <label or location> can contain up to 80 characters of market name references such as “m*,r*” to get numbers from all markets starting with m or r.
See the list of returned codes under PHONE,GET_SPECIFIC_NUMBER above.
NOTE: To handle the situation of timed calls coming up from other markets (since they are not under the control of markets), you should pick up timed numbers and immediately reassign them to the holding area (BUCKET #9), which will put it back into its proper market and cause it to be called when the market weight is set above 0; make sure you have RELEASE_HOLDING_AREA is set to “yes” if you want to retrieve it today.
PHONE,GET_AND_STATUS_NUMBER gets and displays the phone number, its call history (up to 5– last four and first), and the default status screen (see Status Codes Returned From Survent). This type is seldom used because clients want to design their own status screen, use a code list and a PHONE,GET_NUMBER and/or PHONE,GET_SPECIFIC_NUMBER statement (see Sample Prepare Specifications Using PHONE Statements).
PHONE SUBTYPES that get information from the sample record
The following sub-types only work if a record has already been retrieved by Survent using an earlier !PHONE,GET_NUMBER or similar sub-type.
PHONE,SHOW_CALL_HISTORIES gets and shows the phone history and any suspend text. Here is a sample call history display:
Call # 1: FRI NOV 1 2013 16:57 – 16:59 ID: TEST STATUS: NO ANSWER Call # 2: TUE NOV 5 2013 10:23 – 10:28 ID: MARY STATUS: TIMED CALL
The default is to show all histories. You may specify two numbers that control the histories shown:
!PHONE,SHOW_CALL_HISTORIES, # from end, # from start, SHOWNOTE
This will let you see from start histories from the first call and from end histories from the last call made. If the *SHOWNOTE parameter is used, it will show the call note in addition to the call history information. Note that *SHOWNOTE can only be used if you have 100-column call histories, the last 64 columns are the note.
EX: !PHONE,SHOW_CALL_HISTORIES,3,1
This will show the first call and the last three calls. If only one number is specified, that many histories from the end will be shown.
The text describing the phone status on the phone history can be controlled using the file *FONESTAT in the CFMC CONTROL directory. Each label can be up to 16 characters. Add a line to the file for every status you will be using consistently, or modify the text for existing statuses. If you do not provide text, the program will list the status number instead.
EX: 1: COMPLETE … 13: DON’T RESPOND (example added status) … 101: NO ANSWER 102: BUSY … 113: LIKES TO TALK (example added status) …
PHONE,GET_PHONE_INFORMATION gets information from the phone record and puts it in the data record. See The Phone Record Format for phone record locations. In PHONE,GET_PHONE_INFORMATION and PHONE,PUT_PHONE_TEXT statements, you can reference the fields using the field name or the data location in the phone file. Here is the syntax and an example for the PHONE,GET_PHONE_INFORMATION question type:
!PHONE,GET_PHONE_INFORMATION,<FROM label or location,width (phone record)>
EX: !PHONE,GET_PHONE_INFORMATION,STATECODE
This PHONE,GET_PHONE_INFORMATION example gets the information from the STATECODE field (1121.2) in the phone record (state code) and puts it into the data location specified on the question label line (or the next available field if none is specified). If a width is used, it may be specified either on the !PHONE line or in the data location field on the question label line.
The PHONE,GET_PHONE_INFORMATION statement will check for valid phone positions if a location is used. The number of columns that you’re getting (the width) can be from 1-4900 per statement in the phone text area, but must be the actual width of the field for non-text area items, except the time zone and call history field. In large phone file systems, references to CfMC variable locations can be “actual” or “standard”; standard is the default and would start in position 5000. Phone,G statements can move 4,900 columns of data between the phone file and the data file.
See the phone parameter “PHONE_REC_LOC_STYLE” above for more information.
The fields can also be referenced by *name inside brackets (eg. [time_on_number#1-60]) in FONEUTIL and SURVSUPR “SELECT” statements (Managing the Phone File with FONEUTIL). Note that underscores are optional in the field names. In the table below, items are labeled ‘S’ (String data) or ‘N’ Numeric data). Numeric fields may be referenced using ranges and numeric equations in addition to comparisons. ‘Fields referenced as ‘Strings’ must have “$” at the end of the name when referred to and must be compared to items in quotes to (eg. [caseid$]=”0001”).
Other rules apply. See Using Data Location References.
The names can also be used in Survent where the phone file is specifically referenced, such as PHONE,GET_PHONE_INFORMATION and PHONE,PUT_PHONE_TEXT statements to get or put data to/from the phone file, and \[phone location] text display references.
PHONE,SHOW_SUSPEND_TEXT shows the suspend text if the call had been suspended on the previous call. Note: You can also display the suspend text in the text of a question by using the syntax “\[20001.80]” ( DISPLAYING PRIOR RESPONSES AND DATA).
PHONE,GET_SUSPEND_FILENAME statement records a suspended file name to be used. If you add a !PHONE,GET_SUSPEND_FILENAME statement to your !SUSPEND block to get the name of the suspend file written to the data file. The syntax is:
!PHONE,GET_SUSPEND_FILENAME,<label or location>
So, you insert {suspname: !phone,get_suspend_filename} to store the eight-character name in the next available location as “suspname”. or you can set up a question to write to and say {!phone,get_suspend_filename,suspname} to write the name to an existing variable called “suspname”.
This is useful for marking the record as suspended and matching the data record to the corresponding suspend file name in the sample file.
PHONE SUBTYPES that update information on the sample record
PHONE,CHANGE_NUMBER Replaces the phone number in the phone file with the one found in the question or data location referenced. If it is replacing the original phone number, the original is saved in the “OLD_PHONE_NUM” location in the phone file (The Phone Record Format). The length of the question retrieved must match the phone number size as specified in the phone file. The data must be in valid phone number format. That is, it must have the right number of digits with optional dashes or parentheses around the numbers, (i.e., (415) 777-0470). Here is the syntax and an example for the PHONE,CHANGE_NUMBER question type:
!PHONE,CHANGE_NUMBER,<label or location>
EX:
{New_Phone_Num: 41.15
Enter new number
!VARIABLE,PHONE_NUMBER_FORMAT}
{!PHONE,CHANGE_NUMBER,New_Phone_Num }
This PHONE,CHANGE_NUMBER example replaces the old phone number with the new. The number is checked for a proper area code and prefix. The time zone, state and daylight mode of the number is adjusted if necessary.
There is another setting for the !PHONE, CHANGE_NUMBER where you can set the length as well.
EX: !PHONE,CHANGE_NUMBER,label,<length>
The length is not required, but if it is not set, it defaults to 10.
PHONE, CHANGE_MARKET is used to change a number from one market to another. You specify the name of the market you want to move the number to in the !PHONE,CHANGE_MARKET statement.
The syntax for a PHONE,CHANGE_MARKET statement is:
{!PHONE,CHANGE_MARKET,<market name>}
In addition, the old market name and the number of changes made to the market is now stored in the phone file; “Prev_market,” which is the previous market number, is in column 5214.3. “Market_changes,” the number of times the market has been changed, is in column 5217.3.
PHONE, CHANGE_INDEX allows you to change the value of an index on the fly for a particular record. You specify the index number you want to change (y=2, z=3) along with the name of the field that contains the new value. The syntax is:
{ !PHONE, CHANGE_INDEX, <index number>, <question label or location>}
The command not only updates the index field in the record, but also re-indexes the record in the file, so it can be readily retrieved in the future. The “Phone number” index is considered index #1 and can only be changed using the “!PHONE,CHANGE_NUMBER” command.
PHONE,ASSIGN_SPECIAL_TYPE sets the special interviewer type in the phone record. Special interviewer types are used in the case of different languages, interviewers better at closing suspends, etc. This can be a number between 0 (no special type) and 9. It causes the phone number to be sent to a special interviewer stack when it comes up to be called at its scheduled time. It will be offered only to a special interviewer until the special interviewer type is changed to 0 “zero” again.
NOTE: This does not immediately put the number in the special interviewer stack, but is put in a stack depending on the value in the PHONE,SET_CALL_STATUS statement; when the number comes up to be called, it is moved to the special interviewer stack. To put the number in the special interviewer stack immediately, use PHONE,SET_CALL_STATUS,191-199 or PHONE,SET_CALL_STATUS,201-209. This will also mark the record as a “Special Interviewer number from that point on (column 22). If you put the number in the stack and do not use the PHONE,O, the following call(s) again will be released to go to any interviewer.
Here is the syntax and an example for the PHONE,ASSIGN_SPECIAL_TYPE question type:
!PHONE,ASSIGN_SPECIAL_TYPE,interviewer type
EX: !PHONE,ASSIGN_SPECIAL_TYPE,1
PHONE,PUT_PHONE_TEXT moves information from the data record to the phone text area. PHONE,PUT_PHONE_TEXT is the reverse of PHONE,G, but data may only be written to the phone text area or to columns 25-34 (caseID field) to attach a case ID and change the phone record to Phone Says Datarecord mode. See PHONE,G for details on the phone text area.
The syntax for the PHONE,PUT_PHONE_TEXT question type is:
!PHONE,PUT_PHONE_TEXT,TO location(phone text),FROM location(data),width
The TO location must be a field name or column in the phone text area. The FROM location can be a question name or question number, in which case the width is optional; or a data location, which requires a width. The width can be specified on the PHONE,PUT_PHONE_TEXT line or as part of the data location (i.e., [161.10]). If the data location is a question label, the width will be assumed to be the width of the labeled question unless overridden by a separate width.
EX: !PHONE,PUT_PHONE_TEXT,51,[161],80
This PHONE,PUT_PHONE_TEXT moves 80 data columns starting at column 161 to the first 80 columns of the phone text area.
The PHONE,PUT_PHONE_TEXT statement can move up to 4,900 columns of data between the phone file and the data file.
PHONE,SET_CALL_STATUS specifies the status code for the current phone record when it is put back in the phone file. Only the last status code assigned is saved when the phone record is returned to the phone file. Status codes 1-99, and 301-500 will resolve a number, codes 101- 199, 501-699 will record a history and assign for callback, codes 200-249 will not save a history but will assign for callback. See Status Codes Returned From SURVENT for available status codes.
If no status code is assigned, the program will assign status code “1” for a completed interview (case written), “104” for a suspended interview (timed callback), otherwise it will display the standard status screen to the interviewer for them to assign a status. If you back up over a PHONE,SET_CALL_STATUS statement, the status is reset to 0.
Here is the syntax and an example for the PHONE,SET_CALL_STATUS question type:
!PHONE,SET_CALL_STATUS,status code,<option>
EX: !PHONE,SET_CALL_STATUS,5
This PHONE,SET_CALL_STATUS will assign status 5 (nonworking number) to this call attempt. See the following section for a more detailed example. NOTE: Statuses that put the number in special interviewer stacks (191-199, 201-209) also put the special interviewer flag in column 22. This flag stays in effect for future calls unless you either 1) use Phone,Assign_Special_Type to change it to something else, or 2) You put the number in some other special interviewer stack.
Timed callbacks have an additional “time to call” parameter. These statuses (status 104, 160-179, or 601-628), allow you to specify a number from 1 to 2 billion as the number of minutes later to call back (1 minute to 20 years from now), or -2 to -60 which means this time tomorrow minus these many minutes). Here is an PHONE,SET_CALL_STATUS,104 example specifying to call back 50 minutes from now:
EX: !PHONE,SET_CALL_STATUS,104,50
You may also specify a number of days from now to call back in. The number of days can be any number from 0 (in the next 24 hours) to 5000.
EX: !PHONE,SET_CALL_STATUS,104,5 DAYS
This will set the call as an “approximate time” call in this time period 5 days from now. The time (number of minutes) specified can also be in the form of a label or data location.
NOTE: If the data location is not enclosed in brackets and looks like an integer number, it will be treated as a constant, not a data location.
EX: !PHONE,SET_CALL_STATUS,104,TimeToCallBack
Specify date/times with the standard date/time format, such as: YYYYMMDDHHMM. For instance, 202010251525 is for October 25, 2020 at 3:25pm.
If you specify PROMPTNOW as the option after the status value, the program will prompt for the time to call immediately instead of at the end of the interview. This may be useful when using a dialer, for instance. Be careful not to override the status later in the interview if you have already prompted for a time.
PHONE,SET_CALL_STATUS,156 puts numbers in “GET SPECIFIC ONLY” stack , (stack 338), and they will be held there until you retrieve them specifically.
PHONE,SET_CALL_STATUS codes 188 and 213 will put numbers in the “HIDDEN” stack (stack 317). Status 188 stores a history while status 213 does not. You can provide a “name” as an option after the status code and it will hide the number and put it in the NAME_HIDDEN stack (stack 337). You can use the NAME_HIDDEN stack to keep numbers that were hidden for a “specific” reason, from being revealed when a general reveal is done.
EX: !PHONE,SET_CALL_STATUS,213
This will hide the number, but not record any history information about the attempt, so in fact it will not count as an attempt.
EX: !PHONE,SET_CALL_STATUS,188,Storm_Hide
This not only will hide the number and record a history information about the attempt, but will also put it in the named_hide stack under the name “storm_hide”. It can only be revealed back into the regular sample pool by using that name.
Status codes above 900 signify special features of the PHONE,SET_CALL_STATUS. Specifically, here area a few useful examples of the use PHONE,SET_CALL_STATUS:
PHONE,SET_CALL_STATUS statuses 222-224 are used to move records to particular stacks:
222 move to ‘call now’ stack
223 move to ’email send’ stack
224 move to ’email reminder’ stack
The “call now” stack is the first place Survent looks for numbers, so those are called before any numbers. The “email send” and “email reminder” stacks are holding stacks used in conjunction with webSurvent.
If you mistakenly do not set a phone status, by default you get a CfMC status screen from which you can choose one of the standard statuses. But, there are times when you don’t want interviewers picking from the list of standard statuses and you want to fix the error not setting a status. To do this, use !PHONE,SET_CALL_STATUS,998 at the top of the questionnaire, and if a new status is not set before the end of the interview, the questionnaire will get a blow error that explains that no status was set (and maybe the programmer will fix the error after this is reported a few times).
The blow error you will see is:
BLOW #318: Tried to get default fone status screen after it was disabled
In addition, the software will check to make sure the status code you try to use on a !PHONE,SET_CALL_STATUS statement is an available status for users. The statuses that are considered “Bad” are statuses that are reserved for CfMC or a dialer’s use. See the section Status Codes Returned from Survent for a list of which status codes are allowed.
If you use the special status 999, you may then specify a question label or data location to get the status from. Here is the syntax and an example for the PHONE,SET_CALL_STATUS status 999 question type:
!PHONE,SET_CALL_STATUS,999,<label or data location>
EX: !PHONE,SET_CALL_STATUS,999,STATUS1
PHONE,SET_CALL_STATUS,999 supports the PROMPTNOW keyword (above)You can now get a status out of the data using the syntax:
!Phone,SET_CALL_STATUS,999,<label>,PROMPTNOW
And, the program will prompt for a time to call immediately instead of at the end of the interview. Note that this feature is already supported for !Phone,SET_CALL_STATUS,104,Promptnow and also for statuses 160-179, or 601-628 (all TIMED statuses).
PHONE,CALL_NOTE moves information from the data record to the “call note” area for this call (see PHONE,GET_PHONE_INFORMATION call history syntax above). The call note may be up to 64 columns wide. The syntax for the PHONE,CALL_NOTE question type is:
!PHONE,CALL_NOTE,TO location(call note),FROM location(data),width.
The TO location is the absolute location in the call history field for this particular call (e.g. Call #5) and has to be a number between 35 and 99. The total length of the call note may not exceed 64 columns. This option may only be used if you have set the phone_history_note_length is set to >0 in the phone header.
The date/time in the FROM field must be 12-18 characters of the format YYYYMMDDHHMMSSXJJJ which matches the standard SPECIAL,JULIAN_DATETIME date/time format. If the date/time in this location is bad, then (BAD DATE) is put into the data. The width of the receiving location must be 12-18.
Here is the syntax and an example for the PHONE,CONVERT_TO_RESPONDENT_TIME question type:
!PHONE,T,FROM location
EX:
{ RespTime: 221.10
!PHONE,CONVERT_TO_RESPONDENT_TIME,[201.10]
PHONE,ERASE_CURRENT_CALL_HISTORY erases the history for the current call (saves the number without a history for this call) even though you gave it a status to move it to some other calling stack. There are no parameters.
PHONE,ERASE_ALL_CALL_HISTORIES initializes a phone number, taking the current record and making it look as if it were a fresh number. All history fields are cleared, but other system fields (time on call, calls made) are not. There are no parameters.
PHONE,OVERRIDE_OWNER programmatically executes the OVERRIDE keyword for Ownership mode. Allows an interviewer who is not the owner of the record to retrieve it. There are no parameters to this command (See Ownership Mode).
PHONE,ASSIGN_NEW_INTERVIEWER_OWNER programmatically executes the NEWOWNER keyword for Ownership mode. There are no parameters to this command (See Ownership Mode).
PHONE,ASSIGN_CURRENT_INTERVIEWER_OWNER assigns ownership of this phone number to the current interviewer if the number is not currently already owned by someone else. This writes the interviewer ID into the owner field of the phone record. There are no parameters to this command (See Ownership Mode).
PHONE,OWNER_OFF clears Ownership mode in the phone record and sets the current owner to blanks. There are no parameters (See Ownership Mode).
Dialer Related PHONE SUBTYPES
PHONE,DIALNUMBER Sends a number to the dialer to be called. This lets you use autodialers or Getspecific mode with a dialer (not used by predictive dialers, they use PHONE,GETNUMBER_AND_DIAL). It will allow dialing to numbers other than the one you have the phone record for. Provide a label or location specification where the phone number to call is stored.
!PHONE,DIALNUMBER, <label or location>
If you are calling a different number, you would most likely use this in conjunction with a PHONE,CHANGEUMBER (Phone,C) to reset the phone number to the number you called in the phone record. Note that this command reloads the phone number from the phone file, which means that any PHONE,PUT_PHONE_TEXT statements prior to the PHONE,DIALNUMBER will be lost.
PHONE,HANGUP with no other options on it causes the current Survent to send a message to the dialer to hangup the phone call. This is often used before a block where you let the interviewer edit the open ends or other “wrap up” type functions.
!PHONE,HANGUP
If you include a second parameter on the command, then the !PHONE,HANGUP will perform other functions. If you are using a PRO-T-S dialer and the second parameter is a label or location, then Survent will send the contents of the label/location to the dialer on a ‘USER_INFO’ message (AUTOMATIC PHONE DIALERS for more information). If you are using a SER dialer, then the contents of the label/location will be sent to the dialer on a PM command.
!PHONE,HANGUP,<label or location>
In addition, you can use the DONTHANGUP parameter with the !PHONE,HANGUP statement. This will keep an interviewer on the phone when another interview is started at that number. This suppresses the “HANGUP” and “IVR status” messages to the dialer until the next phone record is sent to this interview. This is only in effect until the interviewer gets another phone number.
!PHONE,HANGUP,DONTHANGUP
PHONE,HELDIN will cause the current inbound IVR call to be put into the “HELDIN” queue to wait for the next available interviewer and will then transfer the call to that interviewer.
PHONE,FREE_HELDIN will remove the current inbound IVR call from the wait queue if it was put there by an earlier PHONE,HELDIN command.
PHONE,DIALER_WARN_IF_OFF_HOOK is used with a dialer to tell Survent what to do if the dialer has sent an interviewer a CONNECT and the phone is off the hook. The default is that a message is displayed to “PICK UP THE PHONE, INCOMING CALL”. PHONE,DIALER_WARN_IF_OFF_HOOK sets this back to the default after using PHONE,DIALER_STATUS_IF_OFF_HOOK to change it.
PHONE,DIALER_STATUS_IF_OFF_HOOK is used with a dialer to tell Survent what to do if the dialer has sent an interviewer a CONNECTed call and the phone is on-hook (hung up). If PHONE,DIALER_STATUS_IF_OFF_HOOK is specified, the dialer hangs up on the respondent’s end of the call and gives the call a status of 109 to be called back later. If you specify PHONE,DIALER_WARN_IF_OFF_HOOK, the program will return to the default, which displays a message to the interviewer to pick up the phone. Note: This command is not supported for all dialer types.
Other PHONE SUBTYPES
PHONE,START_RESUMEABLE_INTERVIEW is used with the PHONE,GET_NUMBER if you allow suspending of interviews. When a callback is made to a number that was suspended, by default the following occurs: questions prior to the PHONE,START_RESUMEABLE_INTERVIEW are executed, then, if contact is made and the interview continues, the answers given so far this interview are dropped, the RESUME block is executed, and the suspended questionnaire’s answers are re-executed, including those questions prior to the PHONE,START_RESUMEABLE_INTERVIEW. An interviewer cannot SUSPEND prior to the PHONE,START_RESUMEABLE_INTERVIEW. The PHONE,START_RESUMEABLE_INTERVIEW is normally placed at the end of the contact screen or screener, as soon as the proper respondent is on the phone.
The server parameter file parmfile has an option, “STUFFBEFOREPHONE9: NEW”, which changes this slightly. When the RESUME occurs, it does not re-execute the suspended interview’s questions prior to the PHONE,START_RESUMEABLE_INTERVIEW, but uses the answers from the current interview prior to the PHONE,START_RESUMEABLE_INTERVIEW instead. There are no additional parameters to this option.
NOTE: Only one phone number will be retrieved per questionnaire. That is, once the system has picked up a number, it will not pick up another until another interview is started.
PHONE,ASSIGN_MARKET_WEIGHT sets the market weight. This is usually used to set the market weight to “0” when a quota target has been reached for the market and you no longer want to attempt to get numbers from there. See Controlling The Sample With Markets for more information.
The syntax for the PHONE,ASSIGN_MARKET_WEIGHT question type is:
!PHONE,ASSIGN_MARKET_WEIGHT,<market name or [location or label],weight>
Market name is the name of the market to apply the weight to. This can be referenced directly or placed in the data and referenced by data location or label name. Weight is a number between 0 and 9. If you set it to 0, the market is no longer called.
Using the “label or location”, you would store the name of the market and then reference it from the data. In this manner, you can update all your market weights with the following few statements instead of one statement for each market:
EX:
{mkt: !phone,g,51,4}
{!if quotan([quotanum]) >= quotan([targnum])
!phone,assign_market_weight,[mkt],0}
Note that you can reference quota names or numbers in the same fashion.
PHONE,ADD_NEW_NUMBER writes a new phone record to the phone file via the CfMC server with information you specify. Here is the syntax and example for the PHONE,A question type:
!PHONE,ADD_NEW_NUMBER,<label or location of phone info>
EX: !PHONE,ADD_NEW_NUMBER,[25.900]
Like the !PHONE,GET_SPECIFIC_NUMBER statement, if you specify a two-digit location on the !PHONE,ADD_NEW_NUMBER statement you will get a return code saying what happened to the record as follows:
{Label: .2 !PHONE,ADD_NEW_NUMBER,<label or location of phone info>}
The return codes are:
Value Description OK Good number added AC Bad area code, not added BB Specific bucket bad, not added BR Column 21 of phone record not B, R or blank BS Special type is bad BT Time zone not in this phone file DP Duplicate number (if disallow duplicates) FU Fonefile doesn’t exist ID Case ID is bad MK Bad market name NA Phone number starts with 911 NB Column 50 of phone record not blank SC Bad stack number ND Phone number not all digits NZ Couldn’t load zone table OW Owner name is bad RP Replicate number bad TZ No time zone and area code not in zone table TX Phone text too long WL Phone number wrong length, not added
This sends the specified data to the server where it will be treated just as FONEBULD treats an incoming raw number. If it has a valid format, the number will be added to the phone file. If it isn’t added, there will be appropriate error messages in the SERVER log file. Survent itself gets no messages back. NOTE: You cannot use this feature with Standalone Survent. You may set all the parameters described regarding loading raw phone numbers including the time zone, the special interviewer type, an associated case ID, a particular time to call, or a particular bucket or stack.
PHONE,ADD_NEW_NUMBER provides users with the ability to use four major features:
1 Random Digit Dialing
Using this scheme, the phone file is built with ‘x’ numbers. Once one of those has made its maximum number of calls without a complete, resolve that number with some status 2- but add one to the phone number and have Survent generate a new number with the PHONE,A. Do this up to 10 times until it you get a complete. Note that the generated number may want to keep some of the phone text from the prior number but not the call histories.
2 Generate new leads, ask about additional products
This is used to add a phone record for a new contact or because the client is willing to do a second interview on a new product. If either is true, get the phone number and any other information, add it to your current information, and use the PHONE,A to save the number to be called later. Or, if you would like to do another interview immediately, save the info with the PHONE,A statement, then copy the phone number to the “local scratch” area, start a new interview, get the number back from the scratch area, and call up the new phone record using a PHONE,5 statement (See SPECIAL types K and L in 3.1.5 System Information Statements for how to save data to the local scratch area, see also example file ADDPH^QPX).
3 Add numbers to an 800-number (inbound) dialing database
When a new person that is not in your current sample file calls, you can ask them for their name, address and phone number, etc., build a record, and add it to your phone file.
4 Add sample while a study is live.
This is accomplished by reading your raw sample file with a questionnaire to read the file and generate new phone records. The questionnaire would look like this:
~PREPARE COMPILE –SPECS
[PHONA,CASE_LENGTH=2000,QFF_FILE_NAME=ADDNM^QFF,FONE_TEXT_LENGTH=900]
{
!GOTO,AROUND } ‘‘ NEED TO HAVE A PHONE,4 STATEMENT TO NOTIFY
{!PHONE, 4 } ‘‘ THE PROGRAM THAT WE WILL BE USING PHONE FILES,
{AROUND: !GOTO } ‘‘ BUT DON’T ACTUALLY WANT TO GET A NUMBER SO SKIP
{RETURNCD: 5
!VAR,A,1 }
{FILENAME: 10.12 ‘‘ THIS IS THE NAME OF THE FILE OF NEW RECORDS
ADDNM^RAW ‘‘ IT SHOULD BE PUT WHERE THE SERVER RUNS
!SPC,9 }
{‘‘ THIS READS THE ASCII FILE AND GETS THE DATA FOR SURVENT
!ZSPC,11,6,[RETURNCD],[FILENAME],[81.950]}
{‘‘ THIS PUTS THE DATA INTO THE PHONE FILE AS A NEW RECORD
!PHONE,A,[81.950]}
{!IF [RETURNCD^B] ‘‘ IF RETURN CODE IS BLANK WE GOT A NUMBER
!SPC,H } ‘‘ AND ARE DONE, SO ABORT AND GET ANOTHER
{Errtype: [RETURNCD] !IF RETURNCD$<>”N” If error, display the problem
!FLD,A
A Doesn't have 2 arguments
B Bad subtype
O File open failure
N Nothing to read (No file or off end)
}
{
The return code is \:RETURNCD: due to \:Errtype
!DISPLAY,2 }
{!IF RETURNCD$=”N”
You are either done adding phone records with \:FILENAME: Or you gave the file \:FILENAME: did not exist or was not In the right place. Congratulations or try again.
!DISPLAY}
~END
Then, whenever you have sample to add, copy your spec file, change the study name of this questionnaire to match the one you are updating (make sure the other header parameters match), and start a dummy interviewer on the study with questionnaire addnumber.qff. Once interviewing commences, the sample will be loaded as the SERVER finds time to load it (See example file phoneadd.qpx to run and test this).
PHONE,ALLOW_TO_GET_RECORD_TYPE lets you get numbers that are not allowed by default when using PHONE,GET_SPECIFIC_NUMBER to get specific numbers. The PHONE,ALLOW_TO_GET_RECORD_TYPE must be specified before the PHONE,GET_SPECIFIC_NUMBER. The syntax for PHONE, ALLOW_TO_GET_RECORD_TYPE is:
!PHONE,ALLOW_TO_GET_RECORD_TYPE,type to get
It has other parameters:
PHONE,ALLOW_TO_GET_RECORD_TYPE,HIDDEN allows you to get hidden numbers using a “get specific number” prompt.
PHONE,ALLOW_TO_GET_RECORD_TYPE,RESOLVED allows you to get numbers that have been resolved.
PHONE,ALLOW_TO_GET_RECORD_TYPE,SPECIAL allows you to get numbers that usually require a special interviewer type to get.
PHONE,ALLOW_TO_GET_RECORD_TYPE,BLOW allows you to get numbers that previously have a blow error and were placed in the blow stack.
PHONE,ALLOW_TO_GET_RECORD_TYPE,EMAIL allows you to get numbers that are in either the email send or email invite stacks.
PHONE,ALLOW_TO_GET_RECORD_TYPE,ALL allows you to get numbers normally not available for any of the above 5 circumstances: HIDDEN, RESOLVED, SPECIAL, BLOW or EMAIL.
Once a number has been retrieved, it uses the existing information to determine what to do with the number next. For example, if you get a number that has already met the maximum number of calls, it will be returned to the resolved stack with a status 94 when you are done, if you do not get a complete.
NOTE: Once PHONE,ALLOW_TO_GET_RECORD_TYPE has been executed, it stays in effect for the entire interviewing session. It is not turned off from interview to interview and is not turned off until you exit Survent.
PHONE,ADD_TO_DO_NOT_CALL_LIST adds the current record’s phone number to the server_dnc file which will keep that number from being used in any future study under that study server. Note, the study server now opens the serverdnc file read/write so you cannot have multiple study servers on the same machine accessing the same server dncfile. If you have multiple study servers reading the same dncfile and you do not want to use this option, then you can add “READONLY” to the server_dnc file line in the parmfile, but this also disables this option. If you want it to work on multiple servers you will have to make a copy of the dncfile for each server and then combine them overnight.
!PHONE,ADD_TO_DO_NOT_CALL_LIST
PHONE,GIVE_TO_VALIDATOR marks the interview as one to be validated by a validator; when the interview is finished, the phone record and associated data record are sent to a validator to be reviewed or for additional questions. This works with the SER/EIS dialer or without a dialer, in which case the call has to be forwarded to the validator as well (See Validation of Completed Interviews). A Status of 97 is given to the call after it has been validated.
6.4 PHONE SYSTEM OPERATIONS
This section discusses how numbers are scheduled, how Survent determines which phone number to get, and what it does when it is done with a number.
6.4.1 How the Phone System Schedules Calls
The phone system tracks records according to how they are scheduled to be called. We will refer to a group of records with the same call scheduling state as a stack. Think of this as a stack of paper, with each phone number being a piece of paper and sets of these placed on top of each other. When Survent needs a phone record, it uses a formula (explained in 6.4.2 How SURVENT Chooses A Phone Number) to determine which stack should be used. It then takes the top record off of that stack and presents it to an interviewer. When the interviewer finishes that call, the phone record is returned to the phone file with a status (busy, no answer, complete, refusal, etc.). The phone system uses this status to determine which stack to put this record at the bottom (or top) of.
There are three types of stacks:
1 Specific timed call stacks
2 System scheduled call stacks
3 Special purpose stacks.
Each phone record contains the current stack by number and by name. One or the other can be referenced in FONEUTIL (see 6.7.1 Managing the Phone File with FONEUTIL) and in producing reports where you want to categorize by stack. You can also see the previous stack number and the number of the stack last hidden from.
SPECIFIC TIMED CALL STACKS (1-313)
Specific timed calls use stacks 1-313. These are records where the interviewer has entered a callback time to the respondent or there was a preset time to call in the original raw phone number record.
Stacks 1-288 hold calls scheduled for a specific time today. Each of these stacks holds calls scheduled for a 5-minute period (12 per hour multiplied by 24 hours = 288 stacks). Stack 1 is for calls scheduled from 12:00am to 12:04am, stack 2 from 12:05am to 12:09am, etc. If you scheduled a call to be made at 2:32pm today, the number will be put in the stack that holds all timed calls between 2:30pm and 2:34pm.
Stacks 289-312 are used to call records within a certain hour (approximate time calling). 289 is for Midnight until 1 am, 290 is for 1am to 2 am, etc.
Stack 313 holds all the timed calls scheduled to be called later than today. Whenever the current time reaches the time of a number in stack 313, the program moves all the records that are still in stack 313 (from yesterday), but are now scheduled for today, to the appropriate stack between 1 and 312. Note: This integration of records takes place when the first record is asked for on each day, or can be done in FONEUTIL using option I (Integrate).
SYSTEM-SCHEDULED CALL STACKS (350-9650)
System-scheduled calls (such as new numbers and no answers) are stored in stacks 350 to 9999. The number of stacks used depends on how many different time zones and market areas you are calling. There are 10 stacks for each time zone, and up to 8 time zones.
Each market contains all stacks in all the time zones. Each relative stack has the same meaning for its time zone. The stacks are assigned in low to high time zones. Here are the stacks for the first time zone specified:
Stack Numbers and Descriptions 350 New numbers 351 Call in day part time 1 (respondent time). Calls that will only be made for day part time 1 interviews are stored here. 352 Call in day part time 2 only. 353 Call in day part time 3 only. 354 Call day part time 1 or time 2. Calls that allow either DPT1 or DPT2 interviewing are stored here. 355 Call day part time 1 or time 3. 356 Call day part time 2 or time 3. 357 Call day part time 1, time 2, or time 3. Calls that can be made during any part of the day are stored here. 358 All targeted attempts made. Calls that have had all targeted attempts made for each of the available day parts, but have not made the maximum number of calls are stored here. 359 Holding Area (Bucket #9), a place to save numbers to be released later for this time zone. 350 New numbers 351 Call in day part time 1 (respondent time). Calls that will only be made for day part time 1 interviews are stored here. 352 Call in day part time 2 only. 353 Call in day part time 3 only.
Subsequent time zones use 10 stacks each, starting at 360. Note: Time zones do not need to be consecutive; for instance you may use time zones 5,6,7,8,10,11,23,24.In the following table each cell represents that time zone’s corresponding call stack for different call conditions.
1st 2nd 3rd 4th 5th 6th 7th 8th Description 350 360 370 380 390 400 410 420 Fresh numbers 351 361 371 381 391 401 411 421 Call in day part 1 352 362 372 382 392 402 412 422 Call in day part 2 353 363 373 383 393 403 413 423 Call in day part 3 354 364 374 384 394 404 414 424 Call in day part 1 or 2 355 365 375 385 395 405 415 425 Call in day part 1 or 3 356 366 376 386 396 406 416 426 Call in day part 2 or 3 357 367 377 387 397 407 417 427 Call in day part 1, 2, 3 358 368 378 388 398 408 418 428 All targeted attempts 359 369 379 389 399 409 419 429 Holding Area
If you use markets, the stacks change. The first market by the first time zone uses stacks 350- 359, and the second time zone for that first market is 360-369, the third is 370-379, etc. until all of the time zones for the first market have been defined. The next set of 10 stack numbers will be used to assign the first time zone for the second market. The next 10 will be for the second time zone for the second market and so on.
The maximum stack number is 9,650, and the maximum market is 255, so you may use 255 markets with 1-3 time zones, 241 markets with 4 time zones, 193 with 5 time zones, 160 with 6 time zones, 137 with 7 time zones, and 120 with 8 time zones (See 6.6.3 Controlling The Sample With Markets).
SPECIAL-PURPOSE STACKS (314-349)
The special purpose stacks are numbered 314-342.
Stack 314 contains resolved records. This includes completed interviews, non-working numbers, terminations, refusals, maximum number of attempts, etc. Any number that is resolved will not be presented to be called again. (COMPLETED)
Stack 315 is the error stack. Problem records (a new or changed number given during the interview and its time zone is unknown) get put here. They will never be presented for dialing, will never move to another stack, and don’t show up on displays of the active stacks. If a record is put in the error stack while the study is live, it will keep all of it’s information as it was prior to being moved, but the “error stack” flag will be set. This allows us to better track what happened to the phone number. When you delete the number and add it back in using FONEBULD, the “error stack” flag will be ignored. (ERROR)
Stack 316 is for records that have a duplicate phone number or a duplicate of one of the other indices. They will never be presented for dialing, will never move to another stack, and don’t show up on displays of the active stacks (e.g., FONEUTIL’s P option). You can allow for duplicates using the phone header option DUPLICATES=YES and if you do no records will be put in this stack. (DUPLICATE)
Stack 317 is for records that are hidden with FONEUTIL or SURVSUPR. These records will not be accessible until they have been revealed, where they will return to the stack they were in before being hidden. (HID_<stackname>)
Stacks 318-326 are for records to be called back by a special type interviewer, an interviewer who may have a special skill, such as one who speaks a foreign language. (SPEC-1 to SPEC-9)
When records are assigned to a special interviewer (using the PHONE,O statement or assigning it using column 22 of the raw phone record) they are initially put in one of the of the regular stacks. When that record reaches the time when it normally would go to Survent, it is immediately rerouted to the special interviewer stack. If an interviewer of that special type is available, the record will be presented to them; otherwise it is presented as soon as the special interviewer is available (and prior special interviewer numbers have been called). Within the special interviewer stacks, numbers that come from timed stacks have priority. Stack 318 for special interviewer type 1. Stacks 319-326 are for special interviewer types 2-9, respectively.
Stack 327 is for the owned records stack. This is where records that are scheduled to go to specific interviewers that are not currently signed on are put. (OWNEDRECS)
Stack 328 is for “on-the-floor” records. These are records that were up in the air (in use by an interviewer and never returned to the phone file), but a FONEUTIL V option put them here. (UITA_<stackname>)
Stack 329 is the place where numbers for the “dummy” interviewer are stored. A “dummy” interviewer is a Survent session that handles numbers returned from a dialer before they are sent to interviewers for calling. (DUMMYDO)
NOTE: You can logon to as many stations as you wish with special interviewer type 9 to handle the server statusing activity.
Stack 330 is where FONEBULD puts records that matched records in the “do not contact” file. This file is used to keep studies from calling numbers of people who asked never to be called, were called previously, etc. (NEVERCALL)
Stack 331 is where records that have an unsupported time zone or other problem when interviewers try to change the phone number. This usually occurs when a PHONE,C is used to change a phone number and the changed number is in a time zone that is not supported by the current phone file. For more on this, refer to the !PHONE,Change_Number description. (BADZONE)
Stack 332 is where numbers are placed when they are sent to a predictive dialer. Numbers in stack 332 get marked as “ATDIALER” in the stack name field. If a number is connected to an interviewer it is moved from the atdialer stack and marked as “uita” (upintheair). If a number comes back with some other status it is moved from the “atdialer” stack to the appropriate stack based on the call result from the dialer. When the study is shut down, numbers are returned from the atdialer stack to the top of the previous stack they came from whether or not the dialer sends them back. (ATDIALER)
Stack 333 is where records are put if you have an open web survey and a new record was created. In most cases, records will only be temporarily here as they will be moved to another stack when the result of online attempt ends. (WEB)
Stacks 334 and 335 can be used to handle online only records in a multi-mode study. Records in these stacks are not available to be dialed, but can be gotten by webSurvent using a direct link. Stack 333 is usually used for records that have either the invite pending or it has been sent. Stack 334 can be used for records that have already had reminders sent. (EMAILSEND & EMAILRMND)
Stack 336 is for records that you want called “now”. You can use the phone_move command in the Supervisor to move records into this stack and they will be the next set of numbers that will be dialed. Be careful not to move too many records into this stack as they will no longer have any daypart time dialing restrictions on them. (CALLNOW)
Stack 337 is where records are put if they are hidden with a name. Like records hidden without a name that are in stack 314 these records will not be accessible, unless they are later revealed. What is different about these records though is you will need to know what name they were hidden under in order to reveal them. (NHID_<stackname>)
Stack 338 is where records are put that you do not want to have automatically delivered by the study server and can only be gotten by using the GET_SPECIFIC option. (SPECIFIC_ONLY)
Stack 339 is where records are put if they experience a “BLOW” during the interview process. (BLOW)
Stack 340 is where records are put if you are using the integration with an email package and the record got a bounce on the email send or if the record was assigned a status 225 in Survent.
Stack 341 is where records are put if they have “okayed” by the selector process. Records should only temporarily be here as they will be the next set of records that will go to the dialer when it requests records. (GOODTOGO)
Stack 342 is where targeted records are put in a predictive study. Records should only temporarily be here as soon as the next interviewer becomes available they will get the record from that stack and be able to dial it in targeted mode (power or preview). (TARGETED)
Stacks 343-348 are reserved for future use.
Stack 349 is for “free” or deleted records. They are records that were deleted from the file using FONEUTIL’s “D” option.
These records are not generally accessible by any of the programs, except if you use FONEUTIL’s USEFREESTACK option, which allows the program to read and/or convert the records to be readded to a phone file. Each number occupies a physical slot in the phone file. When a number is deleted in FONEUTIL, the slot for that number becomes free. FONEBULD, when adding numbers to a phone file, first fills any free slots before appending to the file.
6.4.2 How Survent Chooses a Phone Number
Here is the inquiry order when Survent gets a phone number with a PHONE statement:
1 Is the interviewer asking for a particular number?
If so, look for that number. If it is available, get it. If it is resolved or owned by a special interviewer type, only get it if the proper PHONE,ALLOW_TO_GET_RECORD_TYPE option is used.
2 Is the interviewer a special type?
If so, look in the special interviewer type stack. If the interviewer has more than one special type, start looking in type 1, then type 2, etc. Timed callbacks that are due to be called will be at the top on the special interviewer call stacks.
3 Is Owner mode on?
If so, check the owned records stack for any records this interviewer may own. (See 6.6.5 Ownership Mode for more information on this.)
4 Are there any specific timed calls scheduled for now?
If so, use the first one available (regardless of time zone). Are there any approximate time calls for this hour?
5 What time zone will be used for system scheduled calls?
If the TIME ZONE WEIGHTS are equal, the zones are picked randomly in proportion to the number of phone numbers they currently have available. For example, if at 3:00 pm EST there are 1000 numbers available in the Eastern time zone and 100 numbers in the Pacific time zone, then the Eastern numbers will be used approximately ten times as often as Pacific time zone numbers. If weights are applied, they change the proportion for each time zone by its weight.
6 What markets will be used for system-scheduled calls?
If the market weights are equal, get a number from any market, in the same fashion as for time zones. If a market weight is zero, no numbers will be retrieved from that market. (See 6.6.3 Controlling the Sample with Markets for more information.)
7 Are there any system-scheduled callbacks available for the current day part?
If the “bucket_order” parameter is used, Survent searches the system’s scheduled buckets for the time zone chosen in the order specified. If not, it looks for numbers in the “this day part only” stack first, then the “this day part or one other” second and then the “any day part” stack third, in time zone order. If no system scheduled callbacks are found in any time zones then it looks for new numbers in time zone order.
If NEW NUMBERS FIRST is set to YES in the phone file (either by having been set by FONEBULD’s SHOPFILE command or changed in FONEUTIL or SURVSUPR), it changes the above search order so that it looks at new numbers first.
If a specific time-scheduled call isn’t attempted within MAX TIMED CALLBACK AGE minutes past its scheduled time, it is rescheduled for the same time the next day, unless the MAX TIMED CALLBACK AGE is a negative number, in which case it is resolved with a status 95.
Timed calls are not subject to ZONE WEIGHTS or MARKET WEIGHTS. In general, since timed callbacks are first priority, they will seldom reach the max callback age (the amount of time to allow before rescheduling for tomorrow) without being attempted.
For system-scheduled calls, the four-day part times are used to separate days into morning, afternoon, and evening. The DAY PART TARGETS parameter is used to determine how many calls you want in each day part, unless overridden by ‘preferred time of day’ sampling. Here is an explanation of how system-scheduled calls are handled:
Initially, a number is assigned as a new number in its time zone by FONEBULD unless specifically placed in a call stack with BUCKET=, STACK=, or a time to call in the CALLBACK_TIME field (columns 31-45).
Each call during a day part decrements the number of calls allowed to that day part by that phone number by one. If the DAY PART TARGETS are set to 1 1 2 (which means 1 morning attempt, 1 afternoon attempt, and 2 evening or weekend attempts), the first attempt can be made at any part of the day since all day parts are available. If the first attempt is made in the evening and is a no answer, the program will still put the number into the “call morning, afternoon, or evening” stack, because it still has one attempt available for each day part. Suppose the second attempt is made in the afternoon, and it is also a no answer. It will be returned to the “call morning or evening” stack, because it has exhausted all of its afternoon attempts.
If the third call is made in the evening and again is a no answer, it will be returned to the “call morning only” stack.
When the fourth call is made and if it is also a no answer, it will either be resolved (total call attempts made), or it will be put in the “All Targeted Attempts Made” stack, where it may be released to be called at a later time. The maximum call attempts will determine where it goes.
Once a number is in the “All Targeted Attempts Made” stack, it cannot be called again until the option to release these numbers has been specified. SURVSUPR or FONEUTIL can be used to release the ATA numbers. This is used to make additional attempts to a number at the end of a study when you may be short on sample.
System-scheduled calls are subject to ZONE WEIGHTS. If you set ZONE WEIGHTS=0 for a time zone, no system scheduled calls will be available for that time zone. NOTE: Use ZONE WEIGHTS with caution. By overweighting a specific time zone, you may be introducing sampling errors by causing the times people were called to be skewed.
If preferred time-of-day sampling is used, you will specify which day parts you want each call to be scheduled for after each succeeding No Answer in each phone record.
Timed calls (busies, specific time) do not count in the number of day part attempts, even though they occur during them. Busies are considered extensions of the initial call; timed callbacks are given the same consideration.
6.4.3 Status Codes Returned from Survent
Each time Survent gets a phone number, it will return the number to the phone file with a status code for that call. This status code determines which stack the phone number will be returned to, and gets stored along with the history for that call.
Additionally, each phone number is assigned a final status. This is 0 while the number is active, and some resolved status when the number is no longer active.
Status codes are also used for tracking the numbers called by the interviewing staff and to produce interviewer productivity reports. They are divided into two groups, resolved status codes and callback status codes.
-
Resolved status codes are 1-100,301-499, 701-849, 901-999 and are assigned to numbers that will not be called back.
-
Callback status codes are 101-249, 501-699, 851-899 and maybe called again.
If the end of the interview is reached and no previous status has been set or status is 800 (connect from a dialer), then Survent assigns a status of 1 for a completed interview. Resolved status 973 is assigned to numbers that have made the maximum number of calls without completing the interview. All other status codes are assigned by the system (in case of errors), the default status screen (see below), or by using the PHONE,S question to specifically assign a status. There are many status codes available to you for your own purposes: 13-100,108-156,301-499,501-599. All other status codes have a specific meaning, so be sure to use them in the appropriate situation since or you may get unexpected results. (see following pages for a list of the status codes and their meanings).
Here is the default status screen used by the PHONE,0 statement. The status codes that the system assigns are listed in parentheses. This default screen will also appear if an interview is aborted with an SPC,B or SPC,H and no prior status code has been set.
Reasons to Call Back Reasons Not to Call Back
A-->No Answer (101) D -->Refused to start (2)
B-->Busy (102) E -->Language (3)
C-->Call Back (104) F -->Terminated interview (4)
G -->Not a working number (5)
H -->Not residential (6)
I -->Not business (7)
J -->Ineligible A/Stop Interview (8)
K -->Ineligible B/Stop Interview (9)
L -->Ineligible C/Stop Interview (10)
M -->Ineligible D/Stop Interview (11)
N -->Ineligible E/Stop Interview (12)
It is highly recommended though that you design your own status screen. There is an example file PHONE.QPX that can be used as the basis for creating your own screen. The basic design though is to use a single-response FIELD question for the screen display and use PHONE,S type questions to set the status code based on the response to the FLD question.
To give a status without completing the interview on this call (i.e., assign a callback status): use an SPC,B or SPC,H statement to abort the interview after assigning the status. (See 6.3.3 Sample Prepare Specifications using PHONE Statements for examples.)
Here is a list of the status codes and their meanings:
0 No status set %% Can use "0" status to reset !phone,s 1-100: Resolved statuses: Will not be called again (goes to stack 314) 1 Complete Default "Complete" status 2-99 User Defined Resolved Statuses
101-180 Callbacks, some with specific meanings:
101 No Answer ("Dialer no answer" moved to 851)
102 Busy Call in X minutes, ("dialer busy" moved to 852)
103 Busy Changed To No Answer ("Dialer busy to na" moved to 853)
104 Timed Call Default for 'suspend' and "timed" calls
105 Timed Call Non-Specific Time Said 104, but did not give time (treated like "no answer")
106 Abandoned Call ("Dialer abandoned call" moved to 856)
107 Answering Machine ("Dialer answer machine" moved to 857)
108-156 User Defined 'No Answer" statuses-same callback rules as status 101
156 (Moved to 181)
157 (Dialer trunk busy moved to 867)
158-159 User Defined 'busy' statuses-like 102
157 Treated the same as new 681, busy->na goes to 682, out of time bounds busy goes to 683
158 Treated the same as new 684, busy->na goes to 685, out of time bounds busy goes to 686
159 Treated the same as new 687, busy->na goes to 688, out of time bounds busy goes to 689
160-179 User defined timed callback statuses (like status 104, see also 660-679)
180-199 Set to Specific Callback Type, Save History:
*See Corresponding 201+ Stacks that Don't Save a Call History
180 Put to "Targeted Dialing only" stack (stack 342)
181 Put to 'get-specific only' stack (stack 338)
182 Force Busy to NA because busy won't work right now-treated like a No Answer.
*Note: like status 103 (busy2na), make sure you are using it that way
183 Not currently used
184 Timed status, but if call #=maxcalls, always resolved with status 973
185 Put to front of "holding area" bucket #9 (stack xxx9) - goes to holding area for it's market/time zone
186 Put to front of stack came from
187 Put to back of stack came from
188 Put to hidden stack (stack 317)
189 Put to "holding area" bucket #9 (stack xxx9) - goes to holding area for it's market/time zone
190 Not currently used
191-199 Put Direct to Corresponding Special Interviewer Type 1-9 (stacks 318-326)
200 Not currently used
201-299 CfMC Callbacks that don't save a call history:
201-209 Put to corresponding Special Interviewer 1-9 (stacks 318-326)
210 Not currently used
211-226 Set to Specific Callback Type, Don't Save a Call History:
*Note: See corresponding 180+ stacks that save a call history
211 Put to front of stack came from
212 Put to back of stack came from
213 Put to hidden stack (stack 317)
214 Put to back of "Holding area" bucket #9 (stack xx9) for it's market/time zone
215 Put to front of "Holding area" bucket #9 (stack xx9) for it's market/time zone
216 Put to "Targeted Dialing only" stack (stack 342)
217 Put to "Goodtogo" stack (stack 341, release to server/dialer)
218-221 Not currently used
222 Put to 'Call now' stack (stack 336)
223 Put to 'Email invite' stack (stack 334)
224 Put to 'Email remind' stack (stack 335)
225 Put to 'Bad email' stack (stack 341)
226 Put to "Get specific only" stack (stack 338)
227-249 Not currently used
250 Return from server as a targeted dial number - not dialed
251-299 Not currently used
300 Terminated (Entered TERMINATE or clicked button)
301-499 User Defined Resolved Statuses (stack 314):
401-499 Survox Reserves these (They can be used, but may cause issues with standard reports)
500 Not currently used
501-599 User Defined No Answer Callback Statuses (like status 101)
551-599 Survox Reserves these (They can be used, but may cause issues with standard reports)
551-560 Email results
600 Suspended (typed Suspend or clicked button), assume qualified (timed status) 601-679 User defined timed callback statuses: 601-628 User timed callback statuses (like 104) 629 Suspended before qualify (typed Suspend or clicked button) 630 Suspended (status 600), but gave no time 631-658 Timed call, no time given on status 601-628 respectively (like status 105 for 104) 659 Suspended before qualify, not time given (at 629) 660-679 Timed call, no time given on status 160-179 respectively (like status 105 for 104) 680 Not currently used 681-700 User Defined Busy Callback Statuses (like statuses 102, 103, and 182) *These are in groups of 3 681 - User assigned busy status (like 102) 682 - User assigned busy status changed to NA (like 103) 683 - User assigned busy status changed to NA because busy recall would be outside time bounds (like 182) 684,687,690,693,696 like 681 respectively 685,688,691,694,697 like 682 respectively 686,689,692,695,698 like 683 respectively 699-700 Not currently used 701-799 AAPOR (resolved) statuses (pending)
Current list of 800 series dialer status codes.
== 800-997 CfMC Reserved Statuses: (reserved, cannot be specified on !phone,set_call_status statement)
== 800-899 Statuses Handled by the Dialer:
800 Dialer Connect (connected, but no survent status yet) (was status 1)
== 801-850 Resolved statuses handled by the dialer: (stack 314)
801 Number Not Dialed (was 71)
802 Timed Number Not Dialed (was 72)
803 Unknown Number (was 73)
804 Not currently used
805 Number Not In Service ('Ser' dialer only) (was 75)
806 Incomplete ('Ser' dialer only) (was 76)
807 Bad Number (was 77)
808 Modem Answered (was 78)
809 Disconnected (was 79)
810 Forced Resolved (was 80)
811 Not currently used
812 Changed Number (was 82)
813-814 Not currently used
815 Number too old to call (was 95)
816-817 Not currently used
818 Sip Nonworking
819 No Connect
820 Not currently used
821 Interviewer hung up during dial
822 Call Blocked
823 Call is Ringing (Test Mode Only)
824-849 Not currently used
850 Preview mode dial in progress
== 851-899 Callback statuses handled by the dialer:
851 No Answer (was 101)
852 Busy (was 102)
853 Busy To Na (was 103)
854 Trunk-line Busy (was 104 then 157)
855 Incomplete Callback (was 185)
856 Abandoned Call (was 106)
857 Answering Machine (was 107)
858 'G' Status ('Ser' Dialer Only, Was 108)
859 Hung Up Phone (was 109)
860 Not currently used
861 Connect then Abort
862 Hungup
863 No Ringback (was 183)
864 Connected Atd (was 181)
865 Interviewer Hung UP their phone while dialer was dialing number
866 Did not dial the number (some error occurred)
867 Abandoned Call, but marked as targeted number do do not abandon again
868-869 Not currently used
870 Rejected Call
871 NO User Responding
872 Channel Unavailable
873 Temporary Failure
874 Socket Unavailable (Likely an Asterisk File Limit Issue)
875 Network bad - Temporary Failure
876-890 Not currently used
891 Manual Dial Number entered Incorrectly
892 IVR Connect detected Answering Machine
893-899 Not currently used
900-997 CFMC Reserved Statuses: 900 Number "In the Air" (at the interviewer station) 901-949 CfMC Survent callback statuses: 901 Survent had blow error (was 180) 902 Survent Sighup, terminal abort, suspend/cb in 24 hrs (was 190) 903 Survent AutoSuspended (web) survey 904 Not currently used 905 Survent Suspended due to "max idle time" 906 Not currently used 907 Phone Quota Retry (was 997, rescheduled like a busy) 908 Phone Cluster Retry (was 998, rescheduled like a busy) 909-949 Not currently used 950-979 CfMC Resolved Statuses: 950 Not currently used 951 Server Found Duplicate, don't call (was 91) (stack 316) 952 Server Found # In 'DNC Prefix' List, don't call (was 70)(stack 330) 953 Server Found # In 'DNC' List, don't call (was 96)(stack 330) 954 Number completed by Validator (was 97) (stack 314) 955 Phone Number Killed by Foneutil or Survsupr (was 81) (stack 314) 956 Server Found # In 'DNC Email' List, don't call (stack 330) 957-970 Not currently used 971 Forced resolved by dialer (was 80) (stack 314) 972 Not currently used 973 Max Calls Limit reached (was 94, Final Status Only) 974 Max Calls Ever Reached (was 99, Final Status Only) 975 Over Phone Quota, resolved (stack 314) 976 Over Quota Percent, resolved (stack 314) 977 Dialer Failed transfer to Validator (stack 314) 978 Server Failed Transfer to Validator (stack 314) 979 Hit maximum number of possible attempts (99) 980-998 CfMC error statuses (Put in Error Stack 315) 980 Bad Status Set (was 250) 981-982 Not currently used 983 Bad Phone Record (was 83) 984 Dialer status returned with no corresponding CfMC status (was 84) 985 Invalid Time In Timed Callback (was 85, put in stack 331) 986 Bad 'Putfone' With Zero in Field (was 86) 987 Bad Field in Phone Record (was 87) 988 Unknown Status (was 88) 989 Bad Special Interviewer Type Value (was 89) 990 No Stack Found (was 90) 991 Max History Check Error (was 98) 992 No Next Bucket (was 92) 993 Bad 'Putfone' (was 93) 994 Invalid SIP Cause 995-997 Not currently used 998 Reserved for !phone,s,998 (will "blow" if dialer connect status 800 or 0) 999 Reserved for !phone,s (!phone,s,999,location=use status in this location)
NOTE: All callback statuses are treated as system scheduled callbacks except status codes 102,104,160-179, and 601-699 that are treated as timed calls.
6.5 INTERVIEWING WITH THE PHONE SYSTEM
To start a study which has PHONE statements, the phone file must be built and in the proper directory. It should be where the CFMCFONE system variable points. Also, the phone records must have the proper study code, so you cannot rename a phone file from its built study name to another name and start interviewing with it. If you need to change the name, you must convert the records out using FONEUTIL and rebuild the file with the new name using FONEBULD.
If the phone file is not “integrated” yet, the CfMC SERVER will integrate the file (move next day’s calls to today’s calling stacks) for you, depending on the value of the FORCE_INTEGRATE: server parameter in the parmfile (in the CONTROL directory under CFMC). If you get an error message, you will have to integrate the file with FONEUTIL before starting. By default, the server will integrate if there are up to 200 numbers in the “call later” stack, otherwise it will force you to run FONEUTIL to integrate the file offline.
Generally, when using the phone system with Survent, you will want to write your own status screen for more control (see 6.3.3 Sample PREPARE Specifications Using PHONE Statements). If you do not have your own status descriptions, you may use CfMC’s standard status display question with the PHONE,0 statement.
When Survent executes a PHONE,0 statement, it displays the number, along with its history, and a default status screen.
Here is an example of a PHONE,0 screen display:
THE NUMBER TO CALL IS: 312-428-0393 (6) 17:30
HISTORY:
Call # 1: THU AUG 27 1992 15:04 - 5:04 ID:DANN STATUS:Busy
Call # 2: THU AUG 27 1992 15:34 - 5:35 ID:MARY STATUS:Callback
Reasons to Call Back: Reasons Not to Call Back:
A-->No Answer D-->Refused to start
B-->Busy E-->Language
C-->Call Back F-->Terminated interview
G-->Not a working number
H-->Not residential
I-->Not business
J-->Ineligible A/Stop Interview
K-->Ineligible B/Stop Interview
L-->Ineligible C/Stop Interview
M-->Ineligible D/Stop Interview
N-->Ineligible E/Stop Interview
This screen gives the number, its time zone (6), and the time the number was due to be called back (17:30, or 5:30 pm). The history line gives the date, start and stop times of all calls, the interviewer’s ID, status of the call, and number of calls made to this number so far. This is followed by the status screen (see 6.4.3 Status Codes Returned From SURVENT).
If you have reached the prospective respondent and wish to proceed with the interview, press Enter. If you are not going to conduct the interview, you must enter the appropriate response to either provide for a callback or end calls to that number. The status screen will also appear if you end an interview by responding ABORT to any question {!ALLOW_ABORT} must be set), or there is an SPC,B or SPC,H.
To arrange a specific callback time, enter “C” and you will receive the following prompt:
WHEN TO CALL BACK (415-777-0470)?-->
This is the same prompt you will see when you set a status using PHONE,S,104 or PHONE,S,<160-179>.
Note: You may back out of this prompt if you need to, unlike the situation where you reach this prompt by entering SUSPEND and cannot backup.
There are many different formats that may be used when entering the date/time. You may enter a specific date and/or time or an “approximate” date/time. Here is a list of the allowable specific date formats:
Format type Examples
Date: Month day Dec 1 or December 1
Day Month 1 Dec or 1 December
M/D/Y 12/3
12/3/11
12/3/2011
DDMMMYY 03DEC
3DEC
03DEC11
03DEC2011
YYYYMMDD 20111203
MM-DD-YY 12-03-11
DD-MM-YY 03-12-11
MM/DD/YY 12/03/11
DD/MM/YY 03/12/11
Day: DDD or DAY TUE or Tuesday
TODAY
TOMORROW
To enter dates in the format of D/M/Y or DDMMYY like it is common to do in Europe, put DATE_FORMAT:DDMMYY in your parmfile. See 4.4.4 INTERVIEWING CONFIGURATIONS for more information.
Here are the time formats:
Format type Examples
Time: H:M 9:00 (assumes the hext open a.m./p.m. time)
H:M <AM/PM> 9:00 PM
H <AM/PM> 9 PM
HHMM 2100 (military time)
+MMM mins +120 or + 120 mins (120 minutes from now)
+# HouRs +10 hrs (10 hours from now)
+# DAYS +2 days (2 days from now - approximate time)
+ WeeKs +1 wk (1 week from ow - approximate time)
+# MONTHs +1 month (1 month from now - approximate time)
+H:MM + 2:30 (2 hours, 30 minutes from now)
Either date (or day) or time may be entered first; they must be separated by a space. A time entered without a date means the next time it is that time. A date entered without a time means at the current time on the date I’m giving you. A time without AM or PM defaults to the next time the shop is open, eg. If it is 6:00pm, if I say “9:00” it will be for 9PM unless the shop is closed then. A day of the week may be entered instead of a date. Enter the 3- letter abbreviation (MON, TUE, WED, THU, FRI, SAT, SUN) or spell out the day fully (MONDAY, etc.).
The month may be specified as 12/10 or December 10 or Dec 10 (using a three-letter abbreviation).
Let’s say today is Monday, April 20th. If the respondent says call me on the 24th at 2 o’clock, interviewer enters:
4/24 2:00PM
If the respondent says call me tomorrow at the same time, the interviewer enters:
4/21 or +24:00
If the respondent says call me later today at 3 o’clock, the interviewer enters:
3:00 or 3:00PM or 1500
If the respondent says call me back in 20 minutes, the interviewer enters:
+20 or +20 mins
If the respondent says call me back in 3 hours, the interviewer enters:
+3 hrs or +180 or +3:00
If the respondent says call me next Tuesday at 5 p.m., the interviewer enters:
TUE 5 PM
You can also respond to this prompt with a date and time string (yyyymmddhhmm), such as:
201104231530
This means to call back on April 23, 2011 at 3:30 pm.
When arranging a callback time, ALWAYS enter the time given by the respondent. If the interviewer’s time zone is different from the respondent’s time zone, the callback time will automatically be translated into the interviewer’s time. Survent will also make any necessary adjustments for Daylight Savings Time differences.
As an example, suppose a Pacific time zone interviewer called an Eastern time zone respondent at 9 AM, Pacific Time, on December 4th. If the respondent requested a 1 PM callback, the following translation would be performed by the system:
EX:
WHEN TO CALL BACK (415-777-0470)? --> 1:00 PM CALL BACK AT: DEC 4, 2011, 10:00 AM (TIME HERE)
DEC 4, 2011, 1:00 PM (TIME THERE)
THIS OK? (Y OR N)?--> Y
Callback times are checked for validity by the program. They must be between the OPEN times and CLOSED times for the day and prior to the date/time specified as the “Last Scheduled” time.
If you specify a time before Day Part Time 1 and after Day Part Time 4, you will get a warning message. Once you have entered the time, you will be asked to verify it. If you enter a time that is not allowed, an error message will appear and you will have to choose another time. Press “N” to re-enter the time, or press Enter if you wish to have the call automatically rescheduled. Once you have arranged the callback, the number will be available to call at the scheduled time.
If you enter a time without specifying AM or PM, Survent will look forward for the next time that the shop is open at that time (AM or PM) and ask if that is what you want. If it is December and you say to call in January, the next year is assumed. If you specify a time in the format of +30 or +30 mins, the time specified must be at least 10 minutes in the future unless you are in Debug mode.
NOTE: If you get to the callback prompt by mistake, you can enter any of the allowed interviewer commands (^, TERMINATE, etc.) at the prompt, as long as you have used the PROMPTNOW option on the PHONE,S statement that requested a time. Otherwise, you MUST indicate a time to call and status the number because the prompt is displayed after the interview is over.
APPROXIMATE TIME CALLING
You can also set a call to be made some time ‘about’ a particular hour of the day, or at ‘some’ time in the morning, afternoon, or evening. The program will pick an hour to call, and the call will have the next priority behind specifictimed calls. There are 24 stacks (289-312) that are ‘call at this hour’ stacks. If you say to call ‘tomorrow afternoon’, the program will pick a random stack from 12pm to 5pm tomorrow. If you say “about 3,” it will pick the 2pm or 3pm stack. In all other ways they will act like timed calls. When the hour comes along, whenever specific-timed calls are all distributed, the system will attempt to call these numbers. You may specify any date format in conjunction with an approximate time format. The list of supported ‘approximate time’ keywords at the “WHEN TO CALL–>” prompt is as follows:
LATER/TODAY/LATER TODAY Some time later today ABOUT / APPROXIMATELY / APPROX <time> BEFORE / AFTER <time> MORNING / MORN From 8am to 11:59am AFTERNOON / AFT From 12 noon to 4:59pm EVENING / EVE / TONIGHT / NIGHT From 5pm to 9:59pm
NOTE: MORNING, AFTERNOON, and EVENING will be further restricted by your daypart times (i.e., must be between DAYPART1 and DAYPART4) and also between your OPEN and CLOSED times. For example, if your shop is shut at 5pm, the system will not let the interviewer schedule a callback at NIGHT.
The interviewer will see a note on the screen that the call will be made approximately at a specific time. This allows you to make a distinction between “hard” appointments and “soft” appointments. The “minute” part of the note always reflects the current minute, the call will actually be available any time after the hour prompted with.
EX: 7/15 before 3pm TUE NIGHT TOMORROW MORNING