Phone File Commands
Change_Owner/CHO
Change owner of sample records to new owner. This causes all records owned by the specified old owner which are not hidden or resolved to be changed so they are owned by the new owner.
Syntax:
CHO <studyname> <old owner> <new owner>
Fix_Up_In_The_Air/FIXUITA
Allows you to retreive a number from up in the air.
Syntax:
FIXUITA <studyname> <password/fonenumber>
Hide
Hide a selected groups of numbers. This will hide all numbers in the .fon (sample) file that match a SELECT statement.
Large phone files may take some time to hide all the requested numbers. The supervisor cannot quit until the hiding is complete. A message will display on the supervisor’s screen when the hide is done.
Several HIDE operations can take place at the same time. Numbers that have been hidden may later be Revealed.
Use FONEUTIL to HIDE numbers when the study is not live (outside of SURVSUPR).
NOTE: You will not be allowed to hide “ALL” numbers in the Supervisor. But, if you really want to hide all the numbers you can do so by using a location specifications such as “[1#0-9] which specifies that all records with a number in the first position of the file (which would be all numbers since that is where the phone number is) will be hidden.
Syntax:
Hide <studyname> <select>
Example:
HIDE mystudy [1.3#415]
In this example, all callable numbers in the study “mystudy” with an area code of 415 will be hidden.
See Reveal below to reveal the hidden numbers.
Hide_Reveal_Status/HRSTAT
Show status of active HIDE/REVEAL operations (% done).
List_Phone_Records/LIST
Print information on a selected group of phone numbers. “LIST_PHONE_RECORDS” prints the same display as the foneutil “list” command, listing phone number information using the select statement to list the numbers you want to see. You can use “LIST” as shorthand.
Example:
LIST STUDY1234 Enter SELECT statement or ALL--> [record_number] = 1 312-888-9988 ACTIVE: FRESH ZONE: 06 STATE: IL (First call to this number) 3128889988 06 Market 134 Male Fred Jones 418 Small lane Chicago, Ill 35462
Market
Display numbers in market or modify market weights. This displays how many numbers are in each system bucket and total within a particular market or displays the total numbers in each market and their market weight. You can modify the market weight to call numbers in the market more or less often. Market weights may be 0-9; if they are set to 0 for a market it is not called.
To display all markets or modify market weights use the command: MARKET <study> To display the status of a particular market is: MARKET <study> <market> To see only the markets with a weight > 0, use the command: MARKET <study> -ZERO To set the market weight for the specified market: MARKET <study> <market>= <weight>
To export markets: MARKET <study> MARKETWEIGHTOUT <filename>
This will export the market weights for <study> to file <filename>. These can be edited and
read back in using the &filename command. This command falls under control of the MODFONE=Yes/No/Pass parameter in the study header to force users to use a password to use the command.
To print the standard time zone grid for all markets to the listfile and/or the screen: MARKET <study> ALLMARKETS To print one line per market, listing its market number, name, current weight and number of people in the market’s available call grid: MARKET <study> PRINTWEIGHTS
Minage_Limits
Controls how much supervisor can limit no answer callbacks.
This option sets the minimum and maximum values that a user can specify on the MINIMUM SYSTEM CALLBACK TIME parameter on the MPF screen. By default, the minimum is 0 and the maximum 9999.
Example:
MINAGE_LIMITS: 0 180
This says that the minimum value users can specify is 0 and the maximum is 180.
Modify_Caseid/MID
Modify the “next case ID” assignment. Displays and allows you to modify the next case ID value to assign for a given study.
Syntax:
MID <study>
Example:
MID STUDY1234 Present case ID for STUDY1234 is 0093 Enter new case ID -->
- Pressing Enter will cause the current case ID to remain unchanged.
- Entering a number followed by Enter will cause that number to become the current case ID value.
- Changing the case ID could be useful in distinguishing the waves of a study.
- If you enter a new case ID, it must be greater than the last one used.
- Depending on the setting of the MODIFY_CASE_ID header option, you may be prevented from changing the ID, or you may be prompted to verify the change.
Modify_Phone_File/MPF
With this option you can modify most phone file control parameters.
Syntax:
MPF <study>
Example:
MPF STUDY1234
Position the cursor on the item you want to modify and then enter in the new value. Use arrow keys to position the cursor on monitors. Press Esc and you will be prompted as to whether to save the changes, then you will return to run mode.
You can also change a specific phone parameter in a single command line. This is very useful if you want to have a command file update a live phone file. The keywords and values that are allowed are the same that are listed under the Phone File Parameters section.
Syntax:
MPF <study> <parameter>=<value>
Example:
MPF STUDY1234 minage=240
This would change the minimum system call time on the study STUDY1234 to 240 minutes.
Items with “*” to the left of them may not be modified after the original phone file has been constructed.
The phone file is immediately updated after every MPF command if UPDATEFONEHEAD:Yes is specified in the PARMFILE; otherwise, some commands may not take effect until interviewers are restarted. When you exit the MPF screen, you will be reminded of the changes just made, and asked whether to save the changes. Changes are logged to the SERVER log file.
NOTE: By making inappropriate changes on this screen, you can stop phone numbers from being available to the interviewers. Make sure you are changing the right parameter in the right way.
Adding MODIFY_FONE_FILE=Y/N/P in the questionnaire header controls whether or not supervisors can use the MPF option. If allowed to use it, they must know the password assigned on the PASSWORD option on the study header. If not allowed to modify the phone file, supervisors can use the SPI command to look at the current setting. You can use FONEUTIL to make phone parameter modifications in any case while the study is inactive.
Disallow MPF
This command lets you control what can be changed on the MODIFY_PHONE_FILE screen.
The “disallow mpf xxxx” command can be placed in the support/suprinit file and those command will be disallowed.
Syntax:
DISALLOW MPF <field name>
The field names must match the name you see when the program prompts you with the “are you sure?” prompt.
Field Names
| Field Name | Description |
| use_holding_area | Controls the use of the holding stack (bucket #9) |
| busyresked | Busy reschedule time |
| callbackage | Time after which uncalled timed numbers are put back |
| exact_timedcalls | Get timed calls at exactly their time, not within 5 min |
| freshfirst | Whether fresh numbers are called first |
| hardmacattempts | Controls whether max attempts applies to timed calls |
| invert_bucketlist | Invert bucket list so call 7-1 instead of 1-7 |
| market_zero_status | Status to five timed numbers coming from zero-weight market |
| maxattempts | Maximum attemps |
| minage | Minimum age of system calls |
| numbusyna | Number of busy numbers at which return no answer |
| numfromnever | Numver from fresh buckets |
| openshut | Open and shut times (Monday-Sunday) |
| outofnumbdelay | Out-of-numbers delay time in seconds |
| ownermode | Owner mode |
| release_allbuckets | Whether to release all “no answer” and new numbers |
| release_alltargeted | Whether to release previously called numbers |
| release_holding_area | Whether to release the holding area (bucket #9) |
| release_timedcalls | Whether to release timed calls now |
| replicate | Value to set as maximum replicate |
| shutofftime | Time when numbers will no longer be released |
| target | Controls target number of attempts for dayparts 1-3 |
| time#bucket | Daypart 1-8 start times |
| timed_limit | Time after which numbers cannot be scheduled |
| timeperiod_option | Controls the days considered for day parts |
| tzweight | Time zone weights (1-8) |
Named_Hide/Reveal
Allows naming the statement to reveal exactly those records, only later. You can now use the “NAMED_HIDE” statement to hide numbers that you want to keep together as a group to be revealed later. This would be used, for example, to hide all the numbers in a quota group and then reveal them later by name. It makes it easier for staff to later reveal the group and it is independent of other hide/reveal operations. The names use the same rules as labels, alphanumeric, with leading alpha, and 1-30 characters in length. Underscores are also allowed.
NOTE: These numbers have their own stack so that you can hide the numbers here, and they will be unaffected by the standard hide/reveal statements.
Syntax:
NAMED_HIDE <study> <name_for_hide> [HIDDEN] <select statement> NAMED_REVEAL <study> <name_for_hide> [HIDDEN] <select statement>
Examples:
NAMED_HIDE bank_study neworleans [51.2$]="NO" NAMED_HIDE bank_study neworleans HIDDEN [51.2$]="NO” NAMED_REVEAL bank_study neworleans ALL
Use the keyword “HIDDEN” To move numbers from the hidden stack as well, otherwise numbers in the hidden stack are ignored.
You can put a select statement on the “NAMED_REVEAL” to get a subset of the numbers returned.
Notice that you can reveal multiple-named hides concurrently.
The “name” you specify is used when you later show a list of the current groups you are hiding so that you can reveal them.
To display the list of available named hides, type “NAMED_HIDE <study> SHOW”.
Phone_<Command>
The following functions are supported in the supervisor for “live” studies or the foneutil utility for studies that are not live or out of the server area.
Phone_Add_Raw_Sample
Allows loading of raw sample like FONEBULD. You can add new sample while a study is live from the supervisor using the “phone_add” command.
Syntax:
PHONE_ADD_RAW_SAMPLE <study> <file to add>
The <file to add> can be a simple name if the file is in the same directory the Survox® server is running in, otherwise you need to specify the directory the file is in:
Example:
Phone_ADD_RAW_SAMPLE mystudy /home/mydir/mysamplefile.txt
The program will add all the valid numbers and print a summary of the records read, added and discarded. Numbers that are invalid are also displayed on the screen with an error code. The error codes are the same codes returned using the !PHONE,ADD_NEW_NUMBER statement to add sample (See Phone Statements for more information.
If you specified a “rejects_to_file” filename when the phone file was built in FONEBULD, any invalid records will be saved in that file as well for later processing.
Phone_Add_Converted_Sample
Allows loading of an ASCII converted sample file from FONEUTIL. You can add sample back into a study while it is live from the supervisor using the “phone_add_converted” command.
Syntax:
PHONE_ADD_CONVERTED_SAMPLE <study> <file to add>
The <file to add> can be a simple name if the file is in the same directory the Survox® server is running in, otherwise you need to specify the directory the file is in:
Example:
Phone_ADD_CONVERTED_SAMPLE mystudy /home/mydir/myconvertedsample.asc
The program will add all the valid records and print a summary of the records read, added and discarded. Error messages for records that were invalid and discarded are displayed on the screen.
If you specified a “rejects_to_file” filename when the phone file was built in FONEBULD, any invalid records will be saved in that file as well for later processing.
Phone_Alter_Timed
Changes time of callbacks.
Syntax:
PHONE_ALTER_TIMED <studyname> <select> <time>
Phone_Erase
Same as Zap but only on active sample.
Syntax:
PHONE_ERASE <studyname> <select>
Phone_Gather_Specials
Move numbers from other stacks to “special interviewer” stacks.
Syntax:
PHONE_GATHER_SPECIALS <studyname> <select>
Phone_Kill
Resolve sample with status 955 immediately.
Syntax:
PHONE_KILL <studyname> <select>
Phone_List
List sample to screen or to LPDEV if specified.
Syntax:
PHONE_LIST <studyname> <select>
Phone_Move_Records
Allows you to move records from stack to stack using a “SELECT” statement to determine which records to move. Used in conjunction with the “Call_Now” stack, this lets you give numbers immediate priority as well, if you choose.
Syntax:
PHONE_MOVE_RECORDS Fromstack=<from stacks> Tostack=<to stack> <select statement>
Stacks can be numbers or names. You can use up to 10 numbered stacks in the “from” field, but only one named stack.
Most Frequently Used Names
| From Names | To Names | Description |
| # | # (<350) | Stack number |
| B# | Bucket Number | |
| CALL_NOW | CALL_NOW | “Call Now” stack |
| EMAIL_INVITE/REMIND | Email Stack | |
| FRESH | FRESH | Fresh Stack |
| M[#/marketname] | Market Number or Name | |
| TZ# | Time Zone X |
Where ”#” is a stack number. Stack numbers go from 1 – 9650. Notice that you can move things FROM most stacks, but you cannot move things TO stacks > 350 (the time zone/market array).
NOTE: Users shouldn’t move things from time zone to time zone or market to market in this way.
The “TZ#B#” syntax means “Time Zone X, bucket Y”.
The TZ#B#M# means “Time Zone X, bucket Y, Market Z”.
You can substitute a market name for the market number.
Also, there is a keyword “older_than” that will allow you to say “older_than 3 days” (to only get older records).
Example:
PHONE_MOVE_RECORDS fromstack=fresh tostack=callnow [1.10$]=”4069954724” PHONE_MOVE_RECORDS fromstack=fresh tostack=callnow [52.3$]="001" PHONE_MOVE_RECORDS fromstack=callnow tostack=emailsend 1=1 PHONE_MOVE_RECORDS fromstack=email_invite tostack=email_remind 1=1 PHONE_MOVE_RECORDS fromstack=tz5b3mMymarket tostack=fresh 1=1 PHONE_MOVE_RECORDS fromstack=tz5b3 tostack=fresh older_than 3 days [52.3#004] PHONE_MOVE_RECORDS fromstack=fresh tostack=callnow [1.10$]=”4069954724” PHONE_MOVE_RECORDS fromstack=350 360 tostack=callnow 1=1
Phone_Return_Owned_Numbers
Returns numbers from “owned” stack to original stack.
Syntax:
PHONE_RETURN_OWNED_NUMBERS <studyname> <select>
Phone_Sort_Specials
Sort “special interviewer” stacks by time for proper call order, use <1-9> to only sort that type.
Syntax:
PHONE_SORT_SPECIALS <studyname> <1-9>
Phone_ZAP
Remove call histories and make sample “new”.
“Last” removes last call history only.
“Save” removes no histories but changes stack.
Syntax:
PHONE_ZAP <studyname> <Last> <Save> <select>
Phone_Number/PHN
Displays information about a particular phone number in a study sample file.
Syntax:
PHONE_NUMBER <study> <phone number or record number>
Example:
PHN STUDY1234 4157770470
Reveal/REV
Reveal previously hidden numbers. This will reveal previously hidden phone numbers which match a SELECT statement. The numbers are revealed as the SERVER is available; large phone files may take some time to search. You can reveal “ALL” numbers if you choose.
The supervisor cannot quit until the revealing is complete. Several REVEAL operations can take place at the same time. Use FONEUTIL to reveal outside SURVSUPR. See Hide above to hide numbers.
Example:
REVEAL [1.3#415] - Will reveal all callable numbers in the 415 area code. REVEAL ALL - Will reveal all callable numbers.
Save_Select
Save SELECT statements used in HIDE or REVEAL to be used later. This command saves each SELECT statement used in a file in the sub-directory study.s_ in the supervisor’s directory with the name C# with # being a number from 1 to 9999. When using this option, the prompt for a HIDE or REVEAL will read as follows:
Select filename: \cfmc\super\exam2.s_\C001
Contents: [1.3#415] T_ake it, N_ext, or Quit--> T will use that Select N will look for the next available Select Q will go to the “Enter SELECT statement or ALL” prompt.
If used, this is typically placed in the SUPRINIT file to be set whenever a supervisor logs on.
Server_Do_Not_Contact_File (SERVERDNC)
Identifies the file for the server to check new and changed phone numbers for call ability.
The SURVSUPR command tells the server that for every phone number retrieved from any fonefile, look in the specified file and if the number is in there, put it back into the fonefile in the “DoNotCall” stack and go get another number. The server’s DNC file can also be specified in the parmfile as “serverdnc: ” The server’s DNC file can be turned off or changed to another file at any time.
This is to allow you to do “real-time” checking of the phone file instead of just depending on what fonebuld did when it built the file looking at the standard DNC files.
Show_Manana
Lists timed calls scheduled for the near future. With this command, you can get a list of the timed calls scheduled for up to 60 days scheduled for the future.
Syntax:
SHOW_MANANA <studyname>
Example:
SHOW_MANANA PHONE show manana_days 7 2 records at 16 NOV 2015 10:00 1 records at 16 NOV 2015 11:00 1 records at 16 NOV 2015 13:00 1 records at 17 NOV 2015 08:00
This is the only way to show calls scheduled beyond today. You may specify “manana_days=#” in FONEBULD when building the sample file to control how many days to display; where ”#” can be a number from 1 to 60. The default is 7 days.
Survent can also get a report of these numbers that can be used to help with call scheduling applications. See the XF(TIMED_CALL) function for more information. Also, you may generate a report using PHONERPT to get these numbers offline or between shifts.
Show_Sample_Operations_Queue/SAMPLEOPSQ
Shows the status of the currently running background process along with all of the other background processes that might have queued up. This can be use to better understand when specific background processes will finish running.
Example:
SHOW_SAMPLE_OPERATIONS_QUEUE Start Sample Operations Queue Status Active: (36) 18:15 HIDE station:373 study2 Select: ([17#4]) Status: Read:8978 Total:719100 Selected:0 Used:0 Queue: (37) 18:14 ZAP station:293 study1 Select: ([55#7]) Queue: (38) 18:14 HIDE station:373 study1 Select: ([405#7]) Queue: (39) 18:14 HIDE station:293 study2 Select: ([210.3#98]) End Sample Operations Queue Status
Show_Phone_Info/SPI
Show phone information for study. This displays up to six screens of phone system information.
Syntax:
SPI <a,b,c,d e,f,g or h> <study>
Example:
SPI STUDY1234
<a,b,c,d,e,f,g, or h> is any of the eight information screens available. The default, if no letter is specified, is all screens except the f and h, one after the other, with an automatic timeout on each screen. Screens F and H are displayed with market information. If markets are not used, these 2 screens will not show any information.
You can change the default by using the option spi default=<letters>.
Example:
SPI DEFAULT=ABCE
Specifying LP or LP! at the end of the command will send a copy of the screen to the file indicated on a previous LPDEV command.
The default SPI screen is updated every 5 seconds with new interviewer information.
Phone Screen Examples
Call Scheduling Status (Phone Screen A)
The Phone Screen “A” table is a cross between time zones and categories for system scheduled numbers. The horizontal axis is divided into the different times zones for the study while the vertical axis is divided into the ten different categories. The values in the table represent the total numbers that satisfy both the time zone and category depending on the cell in the table. Each cell in the table also has a corresponding stack.
Phone Parameters (Phone Screen B)
The Phone Screen “B” table displays the current phone parameters of the study.
Timed Calls Today Summary (Phone Screen C)
The Phone Screen “C” table displays the timed numbers scheduled for today by half hour and hourly counts.
System Calls Summary (Phone Screen D)
The Phone Screen “D” table displays how soon calls will be available in each of the system callback stacks.
Timed Calls Scheduled After Today (Phone Screen E)
This screen displays any timed calls scheduled in the next 7 days.
Call Availability (Phone Screen G)
This report displays how soon calls will be available in each of the system callback stacks.
Markets: Numbers Available (Phone Screen E)
The Phone Screen “F” displays the stack grid for the time zones used and tells you how many numbers are available across all markets. This screen will only have information if markets are used for a study.
Markets: Numbers Available (Phone Screen H)
The Phone Screen “H” displays the stack grid for the time zones used and tells you how many numbers are available in each individual market. This screen will only have information if markets are used for a study.
Show_Stack
Shows the phone record information for a phone number at the top of a stack. The display is the same as that for the PHONE_NUMBER command.
Syntax:
SHOW_STACK <study> <stack number or bucket,timezone>
Stop_Hide_Reveal/STPHR
Stops current HIDE or REVEAL. Remember to use the HRSTATUS command first to see what the current operation is if more than one is running, or you may stop an operation you didn’t want to stop.
Stop_Sample_Operation/STOPSAMPLEOP
Stops either the current background sample operation or any one that might have been started by this supervisor ID. This option is available as of version 8.8.19 and replaces the STOP_HIDE_REVEAL command.
Syntax:
STOP_SAMPLE_OPERATION <parameter>
The parameter maybe the keyword “current” to stop the currently running background process or the “queue” number of any process that is waiting to run. You can use the command Show_Sample_Operations_Queue to find out the “queue” number of any pending background process.