Notes on how to playback playback files

Search for BUG to find things that need to be fixed.

Playbackfiles
=============

Playback files record the events that occur in survent during an
interview. What makes them different from any other log or list files
is that they may be used as input to survent in order to reproduce
the interviews that they recorded. A second unique feature is that
they allow you to save what was presented to the interviewer in a
separate file so that you can examine it later. This is particularly
useful for web mode interviews. Two meta commands are associated
with playback. Here they are with the options discussed below and
their default values.

>playbackfiles

STORE_FILES_IN_STUDY_DIRECTORY
BASE_FILENAME= (uses study by default)
-MAKE_PRESENTATION_FILE
-ECHO_TELLS
-ADD_COMMENTS
APPEND
-SAME_LISTFILE
PLAYBACK_MODE=full_replay/answers_only (no default value)

>echo_presentation=

HTML (default)
SCREEN
LINE_MODE

The simplest use of this feature is to put >playbackfiles at the start
of your survent session, although it’s most commonly used in an initial
file. (Remember you can have an initial file in ${CFMC}control, $HOME
(on Unix), and your current working directory.) If your questionnaire
looked like:

~prepare compile
[test1]

{Q1:
@ Title text
!fld
1 Yes
2 No
}

~end

And you ran stand alone “survent con con” on this, answering “yes” to
Q1 you would find that a directory named test1.p_ was made, and that
it contained test1.pbf and test1.lst. The .pbf file is the playbackfile
and it will contain:

” **CfMC**: /u/cfmctest/devel/playbackfiles/test1.p_/test1.pbf
” **CfMC**: SURVENT 7.7 v.23aug05 (8:12Oct05)
” **CfMC**: 13 OCT 2005 15:07 ldevs=1,8703,0, compile #772881
”>language character_set=Universal
#:time=13OCT05 15:07:30#
#:c->survmode=1#
#:(what to do=)#
” interview with study test1, signature = 1cee6860,1 compiled at 13OCT05 15:06:58
#:(Q1:5.1)1#
#:nextid=2#
#:(what to do=)q#
” **CfMC**: signature=2081700640

The first three lines log some information about the session. The
commented out >language command records the character set you were
using at the time of the interview. Time= shows the date and time,
survmode= indicates the style of survent that was being run (e.g.
screen, web/html, etc.), and “what to do=” is the “Press <Enter> to
interview” prompt. The “Q1” line contains the question label, the data
location and width, and then the answer given. Nextid= is exactly that,
and then, in this example we quit. This is the basic format of the
contents of any pbf file.
Generally speaking the answers to questions in a pbf file are
recorded just as they would be entered in screen mode. For example a
“^” will record a backup in screen mode or clicking the “previous”
button in web mode. One exception is that the end of text question
input is a “*” by itself as an answer. For example:

#:(Q1:5.1)Here’s the first line in the text box#
#:(Q1:5.1)and this is the second line, then we stop#
#:(Q1:5.1)*# ” <– This says we’re all done.

The default file names for playback files use the study as their root.
By default a directory named study.p_ will be created to contain the
files. Stand alone survent will make study.pbf, web survent is
study_password.pbf, servered survent is study_ldev.pbf, and webcati is
study_interviewerid.pbf.
If you do not want a study.p_ subdirectory to be created, then add
-STORE_FILES_IN_STUDY_DIRECTORY to your >playbackfiles command and the
files will be created in the current direcotry.
If you would like the files to be created with a root name other
than the study then use BASE_FILENAME= on the >playbackfiles command.
the naming rules described above will be followed but using the value
of base_filename instead of the study.

In addition to a pbf file, turning on >playbackfiles will cause a list
file (lst) to be created. This will be a normal survent list file for
the session and can be very useful for debugging problems that occur
behind the scenes while operating in web mode. The list file’s name
will follow the same naming pattern used for pbf files, making it very
easy to tell which lst goes with which pbf.

If you would like to create a presentation file include the
MAKE_PRESENTATION_FILE opton on the >playbackfiles command. The contents
of the presentation file may be line mode, screen mode, or html. The
type is controlled by the >echo_presentation command which takes the
values HTML, SCREEN, or LINE_MODE.
HTML presentation files are a representation of all of the pages
presented during the interview to the respondent, but strung together
as if the interview were on a very long scroll. You should be able to
look at one of these files with a browser and see a good representation
of what the interviewer saw during the interview. You may need to give
the file an html extension to get your browser to recognize the file as
being html. If you need to do that, and you expect to be looking at
these files frequently use “>cfmcextension prs=html” to make prs files
have an html extension. HTML is the default for >echo_presentation.
SCREEN presentation causes a prs to be made with a listing of calls
to write to the screen. These files are not very accessable, but do
contain all of the text that was sent to the screen. This mode is most
useful for testing that the screen presentation is remaining constant
by comparing new screen presentation files with ones known to be good.
LINE_MODE gives a very simple text version of what was presented to
the user. This can be a useful way of simplifying what went on in an
interview when you are trying to sort out a complicated problem.
The important thing to realize is that with >echo_presentation set
to HTML you can run stand alone screen mode interviews and get prs
files that will show you what the web user would see.
One thing that may be disconcerting at first when using prs files is
that they contain what survent presented to the interviewer to be
answered, and thus you will not see the answers to questions unless
a backup occurred in the interview.

The ECHO_TELLS >playbackfiles option causes some additional parts of
the interview dialog to be saved. The ADD_COMMENTS option causes a
very large amount of information about what’s going on during the
interview to be recorded in the pbf file. In particular c=#### is added
to the lines indicating the “caller”, which a programmer can use to help
debugging problems.

By default the files created by >playbackfiles are appended to existing
files of the same name. Thus a web survent interview can suspend and
when resumed will continue using the original pbf file since the default
name is study_password.pbf. In a shop where every interviewer uses
their own ID this can also be useful also to collect all of any one
interviewer’s activity in a single file even if they’ve quit and
restarted survent. (BUG: God knows what a mess you’ll make if all the
interviewers use the same ID and APPEND is in effect.) In some cases
however appending to existing files may not be desirable, in which case
the -APPEND option should be used on >playbackfiles.
A related option is SAME_LISTFILE. Turning this option on makes it
so that if a list file is already open when survent starts a new
study.lst will not be created but instead the run will continue with
the existing list file. Usually this only makes a difference in test
and debugging setups, especially those using “interview from_specs”.

In order to replay a pbf file use a specfile like the following as
input to survent:

>playbackfiles basefilename=replay playbackmode=fullreplay
test1
dbug
y
&test1.pbf

Note that if you didn’t use basefilename here this run would try to
make a new test1.pbf, which is being ampersanded into the run, since
that would be the default pbf name.
Usually you will want to set playbackmode to fullreplay because this
will allow the replay to pay attention to such things as the random
calls, and therefore be able to reproduce rotations etc. The other mode
is answers_only which only uses explicit answers to questions and thus
drives the interview forward somewhat blindly, much the same way a
keyfile does.
When replaying an earlier interview if the question that the pbf
attempts to answer is not the question that survent was expecting you
will get an error in the form:

(error #0) playback (ref=15387) expected match for “#:(Q1:5.1)” but got input “#:(Q2:5.1)1#”

Depending on why you are doing a replay you may be happy or not about
this. What this error means is that this trip through the interview
isn’t doing what it did when the pbf was made.
You can use the usual CfMC “”” comments in pbf files and any of
the meta commands that you would normally be allowed to use in survent
(you will have to be DBUG). In the case of making certain types of
demos and tests you can even use >repeat to do things like suspend and
resume 100 times in a row.
———————————————————

As yet undocumented:

APPLICATION=
LOG_MESSAGES
REAL_ODBC
REAL_PHONEFILE
REAL_QUOTAFILE
UNAUTHORIZED_CONSOLE_USE=