Number Handling Phone Statements

These phone statements do various things.  They write a new phone record to the phone file, replace the phone number in the phone file, and specify the status code for the current phone record.

Valid Subtypes

  • Add_New_Number
  • Change_Number
  • Set_Call_Status

ADD_NEW_NUMBER

Shortform: !PHONE,ADDNUM

ADD_NEW_NUMBER writes a new phone record to the phone file via the Survox server with information you specify.

The syntax for the PHONE,ADD_NEW_NUMBER question type is:

!PHONE,ADD_NEW_NUMBER,<label or location of phone info>

Example:

{ PHONEADD:
!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:

{ QLABEL: .2
!PHONE,ADD_NEW_NUMBER,<label or location of phone info> }

The return codes are:

Value Description
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
ND Phone number not all digits
NZ Couldn’t load zone table
OK Good number added
OW Owner name is bad
RP Replicate number bad
SC Bad stack number
TX Phone text too long
TZ No time zone and area code not in zone table
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.

PHONE,ADD_NEW_NUMBER provides users with the ability to use four major features:

  • 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 but add one to the phone number
      • Have Survent generate a new number with the PHONE,ADD_NEW_NUMBER
      • Do this up to 10 times until it you get a complete.
    • NOTE: The generated number may want to keep some of the phone text from the prior number but not the call histories.
  • 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 based on criteria.
    • If either is true:
      • Get the phone number and any other information
      • Add it to your current information
      • Use the PHONE,ADD_NEW_NUMBER to save the number to be called later
    • OR, if you would like to do another interview immediately:
      • Save the info with the PHONE,ADD_NEW_NUMBER statement
      • Copy the phone number to the “local scratch” area
      • Start a new interview
      • Get the number back from the scratch area
      • Call up the new phone record using a PHONE,GET_SPECIFIC_NUMBER
  • 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.
  • 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.

NOTE: See Ways to Add phone records to a live fone file in the Survox Customer Support Solution Center for examples on how to use the PHONE,ADD_NEW_NUMBER question type.

CHANGE_NUMBER

Shortform: !PHONE,CHANGENUMBER

The CHANGE_NUMBER statement 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 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).

The syntax for the PHONE,CHANGE_NUMBER question type is:

!PHONE,CHANGE_NUMBER,<label or location>,<length>

Example:

{ PHONENUMBER: .18
Enter the new number:
!VARIABLE,PHONE_NUMBER_FORMAT }

{ CHANGEPHONE:
!PHONE,CHANGE_NUMBER,PHONENUMBER }

This example replaces the old phone number with the new captured in the PHONENUMBER question. 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.

NOTE: The <length> is not required, but if it is not set, it defaults to 10 characters.

SET_CALL_STATUS

Shortform: !PHONE,SETSTATUS

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. (See Status Codes for a complete list).

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), or 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.

The syntax for the PHONE,SET_CALL_STATUS question type is:

!PHONE,SET_CALL_STATUS,<status code>

Example:

{ NONWORKING:
!PHONE,SET_CALL_STATUS,5 }

This example assigns status 5 (nonworking number) to this call attempt.

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 or 160-179), 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 example specifying to call back 50 minutes from now:

{ CALLBACK:
!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.

{ CALLBACK:
!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.

Example:

{ CALLBACK:
!PHONE,SET_CALL_STATUS,104,[53.20] }

If you specify PROMPTNOW in the “time to call” field, the program will prompt for the time to call immediately instead of at the end of the interview. This may be useful when using an auto dialer, for instance. Be careful not to override the status later in the interview if you have already prompted for a time.

Example:

{ CALLBACK:
!PHONE,SET_CALL_STATUS,104,PROMPTNOW }

You can specify date/times with the standard date/time format, such as: YYYYMMDDHHMM.

The syntax is:

!PHONE,SET_CALL_STATUS,<104 or 161-179>,<label with date/time string>

Example:

{ CALLBACK:
!PHONE,SET_CALL_STATUS,104,201510301525 }

In this example, the respondent will be called on October 30, 2015 at 3:25pm.

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,998 indicates that if at the end of the interview, the program has not been given a status. It does not present the standard status screen, but instead gets a Survent Blow error #318 and it is left up-in-the-air. This is so you can detect if you have forgotten to set the status programmatically.

If you mistakenly do not set a phone status, by default you get a Survox 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.

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 Survox or a dialer’s use.

If you use the special status 999, you may then specify a question label or data location to get the status from.

The syntax for the PHONE,SET_CALL_STATUS status 999 question type is:

!PHONE,SET_CALL_STATUS,999,<label or data location>

Example:

{ SETSTATUS999:
!PHONE,SET_CALL_STATUS,999,STATUS1 }

The PHONE,SET_CALL_STATUS,999 supports the PROMPTNOW keyword.

The syntax is:

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

Next Topic