DKWebServe_Adv Features

Server Deployment	HTML Templates
Template Directives	Configuration File
The Users Database File	Concatenated and Grid Questions
Questionnaire Directives	Online Data Analysis

Overview

DK Web Server Advanced is a program you run on the web server, that enables Internet surveys using standard DKapture compiled files. It is able to store the state of the current interview between each screen that is presented to the interviewee. If there is a power cut, or some other reason the interview is ditched midway through, the respondent can sign in again, and continue from where he/she left off. This is unlike DKHTMLWin which would lose the entire interview.

DKWebServe_Adv shares some common formatting directives with DKHTMLWin, as well as a very similar configuration file. It uses HTML template files to generate screens for the interviewer or respondent. It has a "users" file which is a database of interviewers or respondents for the web survey. This can be a closed list, or can allow new users to "register" for the survey.

For the survey, DKWebServe_Adv uses standard DKapture compiled files. For the sample system, it uses standard DKapture sample files. You can set these up in the normal way (using DK1Win and SuperWin) and then tailor HTML templates for the screens the users will see.

If DKWebServe_Adv finds a sample file in the survey directory (surveyname_spl.dbf), then the Sample System is used, otherwise the normal "single interview per user" system is used.

If DKWebServe_Adv finds a file in the survey directory called "dwsa_suspend.htm", interviewing is immediately suspended for this survey, and the user is redirected to "dwsa_suspend.htm" instead.

Server Deployment

The program expects templates, compiled files and sample files to be in a subdirectory (called the survey directory) off of the ..\data directory (couched relative to where the application sits on the server). If it cannot find a template in the survey directory, it will look for that template in the data directory. This is where you should keep default HTML templates for surveys, which can be tailored to your organisation's desired looks. You would create this folder in your web space prior to publishing your first survey on that server. Subsequent surveys will use the data directory so created. You should set access rights on this folder so that these files (and the resultant data file) are kept out of the public's domain (they cannot access these directories or files). This should be the case by default, since the directory is at the same level as the www root directory. You should have full access rights to the data directory and any subdirectories off of it. You will need to create a directory off of data called dkfiles and deposit the DKapture licence file (dkapt$$$.bin) therein. The application should sit in a scripts (cgi-bin) directory, but it can be anywhere that is accessible to the surfing public. It requires the ADS local server DLLs adsloc32.dll, ace32.dll and axcws32.dll to be present in the same directory as the application itself.

The survey directory should be called the same name as the compiled file (without the path or extension) and should be created as a subdirectory of the "data" directory. Here, you will put the questionnaire compiled file, the optional sample file, and any extra .htm files for tailoring the survey.

The default format for the DKapture data file is .DBF format.

Command Line Usage and Optional Parameters

survey=surveyname - specifies the name of the survey and this must included on the commandline.

un=username - username to override the necessity of logging in.

pw=password - password to override the necessity of logging in.

lang=number - to override the default language of error messages (English is the default and number 1 - see switch -j).

questionlabel=answer - on a fresh survey, this sets questionlabel to answer for this respondent. This can be specified multiple times for different questions in the survey. Labels that cannot be located in the survey, are ignored. You can use the questionlabel @@QWERON@@ to specify which question label to start the survey at.

DKWSA_ANSWS Cookie can be used to take answers from another browser page or session on the same PC. The cookie should be in the form q1=2&q2=7&q3=rabbit, for example. There are Javascript cookie support routines included each time a question screen is presented. The DKWSA_ANSWS Cookie is intially erased on presenting a question screen. You can then use a Javascript line like :-
createCookie('DKWSA_ANSWS','q1=2&q2=7&q3=rabbit',1);
on any browser screen (including the question screen itself) to instruct DKWebServe_Adv to take these answers into the survey. The cookie support routines (amongst others) are in the file dkwsafuncs.js so you can include this into any web page you are interfacing the survey to. The question screen always includes these routines for you. To include them in another HTML page, use :-
<SCRIPT Language="JavaScript" SRC="http://www.YourISPHost.com/dkwsafuncs.js"></SCRIPT>

For example, URL to call the example survey up, attempt to login as "Peter" with password "serum", set q1 to 2 and q2 to 7 if they haven't already been answered, and go straight to question Q5 :-
http://www.YourISPHost.com/scripts/DKWebServe_Adv.cgi?survey=W1002&un=Peter&pw=serum&q1=2&q2=7&@@QWERON@@=Q5

Back to the Top

HTML Templates and Substitution Parameters

The HTML screens returned by DKWebServe_Adv to the user are usually shaped by HTML template files, resident in either the survey directory, or in the data directory above it. There are some generic templates supplied with DKWebServe_Adv, and these are used any time a tailored counterpart cannot be found in the survey directory.

HTML Template	Purpose	Sample System Only?	Optional?
dkwsalogin.htm	Survey Login Screen	No	Yes
dkwebserve_adv_tpl.htm	Survey Question Screen	No	Yes
dwsa_completed.htm	Survey Already Completed Screen	No	Yes
dwsafrontscreen.htm	Sample System Front Screen	Yes	No
dwsa_splexhaust.htm	Sample Exhausted Screen	Yes	Yes
dwsa_splcancel.htm	Sample Cancelled Screen	Yes	Yes
dwsa_appointment.htm	Appointment Screen	Yes	No
dwsa_giveup.htm	Give Up Screen	Yes	No

Template files are located by first searching the survey directory, and then the data directory. All tailored HTML template files should be complete HTML documents.

Example Tailoring a Login Screen

If you specify an HTML template file for the login screen, dkwsalogin.htm, it should contain the login screen template including the titling and username and password prompts. Here is an example :-

<HTML><HEAD><TITLE>_SURVEYNAME_ Login</TITLE></HEAD>
<BODY BGCOLOR=#CE9B38>
<H2>_SURVEYNAME_ Login</H2>
<H3>_PROMPT_</H3>
<FORM NAME="dkwsalogin" METHOD="POST" ACTION="_EXECUTABLE_?_QUERY_">
<TABLE CELLPADDING=2 CELLSPACING=3 BORDER=1 BGCOLOR="#D0E0D0">
<TR><TD><B>User Name :</B></TD><TD><INPUT TYPE=text NAME="username" SIZE=40 MAXLENGTH=40 VALUE="_USERNAME_"></TD></TR>
<TR><TD><B>Password :</B></TD><TD><INPUT TYPE=password NAME="plywood" SIZE=40 MAXLENGTH=40></TD></TR></TABLE><BR>
<INPUT TYPE=SUBMIT NAME="SUBMLOGIN" VALUE="Login">
</FORM></BODY></HTML>

The login screen template must have the SUBMLOGIN, username and plywood inputs on its form, and the form must be called dkwsalogin.

Special Template Directives

To enable the templates to handle the embedding of information pertinent to the current survey and/or respondent, DKWebServe_Adv uses the following mnemonics :-

Directive	Substituted for	Valid in
_DKQUESTIONSECTION_	HTML Table Containing the Questions and Answers	dkwebserve_adv_tpl.htm
_PROMPT_	Login Screen Prompt	dkwsalogin.htm
_SURVEYNAME_	The Name of the Survey	Any Template
_LICENSEE_	Organisation DKapture is Licensed to	Any Template
_DKWSADATE_	Today's Date	Any Template
_DKWSATIME_	Current Time	Any Template
_QUERY_	Everything after the ? in the URL	Any Template
_HOST_	Name of the Host for this Session of DKWebServe_Adv (eg. www.critical.co.uk)	Any Template
_EXEDIR_	URL to the Directory Housing the DKWebServe_Adv Executable (eg. http://www.critical.co.uk/scripts/)	Any Template
_EXECUTABLE_	Full URL Path to DKWebServe_Adv Executable (eg. http://www.critical.co.uk/scripts/dkwebserve_adv.cgi)	Any Template
_USERNAME_	Login Name	Any Template
_APPSCAPTION_	Details of the Next Appointment	Any Sample Template
_TICKETNO_	Session Pass Key	Any Template
_LASTERROR_	The last reported problem with the survey	Any Template
_SERNO_	Serial Number of the Current Survey	Any Template Except Login
_INTNO_	Interviewer Number	Any Template Except Login
_GIVEUPOPTIONS_	A List of "Give Up" Options	Any Sample Template
_Sample Fieldname_	Whatever the Contents of "Fieldname" are, from the Sample File	Any Sample Template

Notes

In the table above, "Any Sample Template" includes the question screen template.

_DKQUESTIONSECTION_ is substituted for the table generated by DKWebServe_Adv, that holds the question(s) and answers.

_Sample Fieldname_ will cite the contents of any field from the Sample file, when using the optional DKWebServe_Adv sample system. For example, _NUMCALLS_ will be substituted for the number of calls made for this sample respondent so far. See DKapture Sample File Fields for a list of fields you can use.

_PROMPT_ is substituted with the textual prompt for this login screen. There are 5 texts, and they are configurable from the configuration file. The default values are :-
"Please Login"
"Unable to Open Login Database - Please try again"
"Incorrect Password - Please Re-enter"
"Username not Recognised - Please Re-enter"
"Please Confirm New User Details"

The Question Screen Template and Responding to Events on the Page

A typical (and minimal) question screen template (dkwebserve_adv_tpl.htm), with styles for the various DKapture question and answer text highlighting directives, and empty hook procedures for input elements, should look like this :-

<HTML>
<HEAD>
<STYLE TYPE="text/css">
EM { background-color:black; color:white; font-style:normal;}
BLINK { background-color:blue; color:yellow;}
SMALL { font-size:smaller;}
SAMP { display:none;}
</STYLE>
<TITLE>Survey _SURVEYNAME_</TITLE>
</HEAD>
<BODY>
<CENTER><H2>Survey _SURVEYNAME_</H2></CENTER>
_DKQUESTIONSECTION_
<SCRIPT Language="Javascript">
// qid is the ID of the control. This is either the label of the question for numerics and alphas,
// or zXXXopQQQ for singles and multis, where XXX is the (zero-padded to a width of 3) option number,
// and QQQ is the question label. Question labels (QQQ) are always UPPERCASE.
// Use changeop(qq,ops,chg) to enable, disable, check or uncheck any options in the string ops for question qq
// chg should be 1 to disable, 2 to enable, 3 to check, 4 to uncheck, 5 to make invisible and 6 to make visible
// the comma-separated option numbers in ops.
// Use getqlbl(qid) to get the question label from the control id qid.
// Use getanswer(QQQ) to get answer(s) for question label QQQ. For example :-
// document.getElementById(qid).style.backgroundColor='yellow'; [Sets background of element qid to yellow]
// document.getElementById('q3tbl').style.display='block'; [Makes section ID'd by 'q3tbl' visible]
// changeop('Q1','2',1); [Makes option 2 of single or multi question Q1 disabled]
// changeop('Q2','1,3,5',3); [Checks options 1,3,5 of multi question Q2]

function blurd(qid)
{
// Put code after this line to do something when a question loses focus
  return true;
}

function fcusd(qid)
{
  userinput(getqlbl(qid));
// Put code after this line to do something when a question gains focus
  return true;
}

function mseover(qid)
{
// Put code after this line to do something when the mouse pointer enters the region of a control.
  return true;
}

function mseout(qid)
{
// Put code after this line to do something when the mouse pointer leaves the region of a control.
  return true;
}

function userinput(qq)
{
// Put code after this line to do something whenever the question screen is changed or first shown
// qq is the label of the question that changed
  return true;
}
</SCRIPT>
</BODY>
</HTML>

The routines changeop, getqlbl, and getanswer are defined in the dkwsafuncs.js support script which is included in every question screen generated by DKWebServe_Adv.

changeop(qq,ops,chg) can be used to enable, disable, check and uncheck options in a single or multi type question. qq is the question label of the question we wish to change options on, ops is a comma-separated list of options we wish to affect, and chg is a number where 1 means disable, 2 means enable, 3 means check, 4 means uncheck, 5 means make invisible, 6 means make visible, 7 means make selected, and 8 means make deselected, the options specified in ops. 3 and 4 apply to singles and multis. 7 and 8 apply to list-types.

getqlbl(qid) can be used to extract the question label from the ID qid of the element that is part or all of that question. On singles and multis, the ID is for one of the options on that question. On other questions the ID is the same as the question label. The syntax of qid is zXXXopQQQ for singles and multis, where XXX is the (zero-padded to a width of 3) option number, and QQQ is the question label. Question labels (QQQ) are always UPPERCASE. getqlbl will strip away zXXXop from the front of the ID leaving just the question label. For numerics and alphas, getqlbl just returns its argument unchanged.

getanswer(qq) can be used to extract the current answer for question label qq from the screen you are on. qq is the question label identifying which question you want the answer to. The return value is always a string. For singles, numerics and alphas, it returns the value of that question as a string. For multis, it returns the options checked, separated from each other by commas and bearing a leading and trailing comma to aid in testing for certain codings. For example a single with option 4 checked would return '4', a numeric with the value 456 entered would return '456', an alpha with the string hello entered would return the string 'hello', and a multi with options 2, 4 and 6 checked would return the string ',2,4,6,'.

For example, if you wanted to hide a text entry box until the user checked option '12)Other Company' on a single-coded question, you would use a combination of the {TABLE ...} directive and Javascript code in the 'userinput' routine in a question screen template for the survey (dkwebserve_adv_tpl.htm) in the survey directory to override the default one used by DKWebServe_Adv. Example DKapture questionnaire text :-

.cnc0.
{CONCAT}

1)
2)
)
[0]

.Q0.
Please choose the company you used from the list below, or code 'Other Company' and input the name for yourself :-

1)Xerox
2)Jaeger
3)Kleenex
4)Teac
5)Panasonic
6)Apple
7)Vauxhall
8)Polydor
9)Nabisco
10)Royal Doulton
11)Arriva
12)Other Company

.QTXT.
{TABLE ID="txtbl" STYLE="display:none;"}

80)Please Enter the Company Name Below :-
[alpha]

Note the use of STYLE="display:none;" to make the table containing the alpha question initially invisible. Then, we hook into the userinput routine with the following Javascript code :-

function userinput(qq)
{
// Put code after this line to do something whenever the question screen is changed or first shown
// qq is the label of the question that changed
  var txb=document.getElementById('txtbl');
  if (!txb) return true;
  if (getanswer('Q0')=='12') { txb.style.display='block'; document.getElementById('QTXT').focus();}
  else txb.style.display='none';
  return true;
}

Note the use of document.getElementById to obtain a handle to the invisible table in order to change its visibility, and to put the text entry box into focus when necessary. Additionally, singles and multis have IDs that envelope the actual checkbox or radiobutton they refer to. For example, 'z003opQ0' would refer to the checkbox or radiobutton for option 3 on question Q0, 'LBLz003opQ0' would refer to the checkbox or radiobutton and the text next to it (this element does not exist if the single or multi is part of a {GRID...} question), and 'TDz003opQ0' would refer to the entire cell in the table used to hold the checkbox or radiobutton and associated text. An example that highlights the option the mouse is over in yellow and renders it back to the document background colour when the mouse leaves it, for the above example questionnaire text might be :-


var obgc=document.bgColor;

function mseover(qid)
{
// Put code after this line to do something when the mouse pointer enters the region of a control.
  if (qid.indexOf('op')!=-1) qid='LBL'+qid;
  document.getElementById(qid).style.backgroundColor='yellow';
  return true;
}

function mseout(qid)
{
// Put code after this line to do something when the mouse pointer leaves the region of a control.
  if (qid.indexOf('op')!=-1) qid='LBL'+qid;
  document.getElementById(qid).style.backgroundColor=obgc;
  return true;
}

Note how the qid parameter is prefixed with 'LBL' when 'op' is in the ID string (ie. you are on a single or multi), to correctly address the radiobutton and the text next it. Also, note the use of var to set up a variable obgc to hold the document background colour.

Further facilities can be read about at any good CSS reference website, for example W3Schools which also has Javascript and HTML help on the same website. Another useful reference is for when you need to translate a CSS element to a Javascript element. For example, if we have a table where we have changed the background colour to peach using the HTML construct :-

<TABLE ID="tbl1" STYLE="background-color: peach;">

and we want to change the colour to coral when one of the Javascript event handlers is fired, we would use :-

document.getElementById('tbl1').style.backgroundColor='coral';

As you can see, the 'background-color' parameter of the STYLE HTML attribute, when referred to in Javascript, is called 'style.backgroundColor'. For all such translations, a full list is here.

Back to the Top

Configuration File

The configuration file controls various output options and behaviour. The web server program looks for the file DKWebServe_Adv.cfg in the survey directory. If it finds it, it uses this as the configuration. If it does not find it here, it will look for the global configuration file called DKWebServe_Adv.cfg in the data directory. If it still cannot find a configuration file, the program quits with a suitable message. This configuration is most easily maintained using SuperWin's Web Survey Configuration Editor.

Here is an example default file with comments to help with meaning (SuperWin's Web Survey Configuration Editor strips these comments out, since the dialog explains all of the elements) :-

* Compiled and Data File names separated by semi-colon
* Use "Default" or "DefaultDat" for names based on the survey name
Default
* Email Return Address, Host and Username details (comma-separated)
me@myorg.co.uk,smtp.freeserve.net,myusername
* Button Back Text (Use "None" for no button)
* If this is a URL or Filename to an Image file, an image button will be used
Back
* Button Back Alt Key
@
* Button Forward Text
* If this is a URL or Filename to an Image file, an image button will be used
Next
* Button Forward Alt Key
@
* Display full question details on each screen (Yes or No)
No
* Display "Characters Remaining" on verbatim questions (Yes or No)
Yes
* Progress Bar
* Use </TD></TR></TABLE> for no progress bar
* Use %a% for %ge thru and %b% for %ge left
</TD><TD align=right valign=center>Progress: %a%% done</TD></TR></TABLE>
* Survey Completion URL or File (Use "None" for default screen)
None
* Main Question Table Definition
<TABLE height=375 cellSpacing=0 cellPadding=5 width=95% border=1>
* Answers Table Definition
<TABLE cellSpacing=0 cellPadding=3 width=95% border=0>
* Buttons Table Definition
<TD valign=bottom align=left height=1><TABLE width=100%><TR><TD width=*>
* Number of Columns for Answers (minimum 1, maximum 20)
2
* Number of Codings Before Multicolumn is Used (0 for all)
10
* Confirm a New User (Yes or No)
Yes
* User List
* Open - New user names AND passwords can be entered by the respondent.
* Closed - User names AND passwords must be on the database.
* Auto - User names will be generated (6-random alphabetic chars) and,
*        optionally, overwritten by the user. No password is required.
* Useronly - Like a Closed list, but no password is required.
* Usersetpw - User names have to be in the users database.
*             Password is required but, if blank, can initially be set by the user.
* OneHit - User names will be generated (20-random alphabetic chars)
*          but the respondent doesn't see it and, therefore, can't change it.
Open
* Email errors/problems to address :-
* If following has @ in it, it will go there, else nothing is emailed.
* If you use "display" it will show technical details in the browser
Nobody
* Login Screen Prompts
* Please Login
Please Login
* Unable to Open Login Database - Please try again
Unable to Open Login Database - Please try again
* Incorrect Password - Please Re-enter
Incorrect Password - Please Re-enter
* Username not Recognised - Please Re-enter
Username not Recognised - Please Re-enter
* Please Confirm New User Details
Please Confirm New User Details

Compiled and Data File can be specified here. Please use a semi-colon to separate the compiled file name from the data file name. If you use "Default", it will set the compiled file name to whatever the survey name is plus a .cpd extension, and name the data file likewise, with _DAT.DBF for its ending. If you use "DefaultDat", it will set the compiled file name to whatever the survey name is plus a .cpd extension, and name the data file likewise, with .DAT for its ending.

Email Return Address, Host and Username details are used when you want DKWebServe_Adv to email the survey operator any error messages which arise from running the survey (see "Email errors/problems" below). The Return Address and Username have to be a valid email address and user respectively, on the Host. Otherwise, your email will disappear into the "ether".

Survey Completion URL contains the URL of an HTML page, which will be displayed on completion of the survey. If "None" is used, a simple thankyou screen is displayed.

Confirm a New User will prompt for a password again, after a new user logs into the survey for the first time. This setting is ignored if you are using a "closed user list".

User List

Closed means the system checks the username against the users database for the survey. If the username exists in the database, and the password matches, they are allowed into the survey. Otherwise the user is prompted with the "Username not Recognised - Please Re-enter" login screen.

Open means that any unrecognised details are entered as new users into the users database.

Auto means that a 6-character random username is generated for the user and no password is required to log in. The user can change the username to something more memorable if they like.

Useronly is like a Closed list, but no password is required. Only the username is required to log in to the survey. If it is not in the users database, you are prompted to re-enter it.

Usersetpw means that user names have to be in the users database, like a Closed list, and a password is required but, if blank, can initially be set by the user.

OneHit means that a 20-character random username is generated for the user and no password is required to log in. The user is immediately put on to the first question in the survey, bypassing any login screen.

Email errors/problems can be the email address of someone who will receive all error messages from DKWebServe_Adv for that survey. If an error occurs and this is a valid email address, the technical details of the error are sent to the address, and the interviewee sees the message "Apologies. There has been a technical problem. Staff have been informed by email." on the screen. If you use the word "display", it will send the technical error details to the interviewee's screen. If you use anything else, it will put the error details into the system error log, and display "Apologies. There has been a technical problem. The error has been logged."

Login Screen Prompts allows you to reword the default login screen prompts used by DKWebServe_Adv. These are what _PROMPT_ is replaced by, depending on what stage of login the interviewee is on.

Main Question Table Definition and Answers Table Definition
You have to lay out the questions and answers in a table, which ensures that the Back and Next buttons stay in the same place on most screens. The default definitions above show you a typical arrangement. Both the attributes must have a table definition in them, even if it is in its simplest form <TABLE>. You can override the Answers Table Definition on any particular question using the {TABLE ...} question text directive.

Buttons Table Definition allows you to specify the entire table cell definition for the row holding the Back and Next buttons. This should start with <TD...

Progress Bar is used as a partner for the Button Table Definition when tables are being used. Any element, apart from the initial <TD>, that is started in the Button Table Definition, must be terminated in the Progress Bar line. See above example configuration for how this works. Progress Bar allows you to present an indication of how far through the questionnaire you are, using %a% (percentage through questionnaire) and optionally, %b% (percentage remaining). Any new tags opened in the Buttons Table Definition should be closed on this definition line, except the <TD...>. This should start with </TD>. The buttons and progress bar are usually laid out on the same row of a table.

Number of Codings Before Multicolumn is Used enables the multiple column layout of answer texts to occur only when the number of answers for the question (including the no answer code) equals or exceeds the specified number.

Back to the Top

The Users Database File

This file controls and records the state of the interview for each user. It is created for you when you have the "Closed User List" set to "No" and it doesn't already exist.

To set one up for a closed user list, set "Closed User List" set to "No", login to the survey and input the first user's details. This will then create the users database in the survey directory and call it dkwebusers.dbf. It will create index orders for you too. It will also create the record for the user whose details you input. You can use ViewDBFWin to create more user records, or you could continue adding your users using the login screen. When you have finished entering the closed user list, you set the "Closed User List" configuration option back to "Yes", and you're ready to publish the survey.

To set up for an open user list survey, you do not need to create a users database. The system will handle everything for you.

Let's discuss some of the fields in this users database :-

SERIAL_NO
This is used to hold the serial number that has been allocated to this user. When they complete the survey, the DKapture data record is written out with this serial number.

USERNAME
This field stores the username. If the list is "closed", then the survey's operator has to set up users by typing names into these fields.

INTNO
Interviewer number corresponding to this USERNAME.

LOGINDATE, LOGINTIME, NUMLOGINS and IPADDRESS
Each time the interviewee logs into the survey, these record the login date and time, number of logins, and IP address of the PC.

COMPLETED
This is a simple system-maintained flag which denotes whether this user has finished the survey they are on yet.

WRITTENOK
This flag denotes whether the finished survey was written to the data file successfully.

DOENCRYPT and PASSWORD
These are a flag and a text field that are used for setting or resetting passwords. When a user logs into the survey and enters their password, the password is stored in the users database in an encrypted form. This is awkward if you are trying to reset or set a password to something specific, for example, when setting up usernames and passwords for a closed user list. With this flag set to true, the password field becomes unencrypted, so you can type a password directly into the password field, and it will encrypt it when the user logs in for the first time with his/her new credentials. You could also use this on open user list surveys, where a user might have forgotten their password, and needs it setting up again, whilst retaining what survey data they may have already entered. You would set this flag to true, enter the password, and inform the user of his/her new credentials.

USERNOTES
A spare field into which the survey operator can enter any notes about the user, or use it for analysis purposes within ViewDBFWin.

SVYSTATE
This field stores the current state of the survey for each user record. The format used is precisely the same as that used for the appointment system in DK2Win. Question labels followed by 2 equals signs followed by the answer, and finally, an @@QWERON@@== to denote which question label the user was on last. Using this format coupled with the default DKapture database data file format, should give the survey operator some leeway as to questionnaire redesign halfway through interviewing, without major upheavals.

LQDATE and LQTIME
These record the last date and time the interviewer had a question on their screen.

LQSCREEN
This is the last screen the respondent saw, stored as the HTML code sent to their browser.

Back to the Top

Concatenated and Grid Questions

To make more than one question visible on the screen at the same time, or even make a grid of coded responses from several single- or multi-coded questions, DKWebServe_Adv recognises what are termed "concatenation screens". Keywords are added to the question texts in the questionnaire to "dress up" a concatenation screen as follows :-

{CONCAT}
or {CONCAT xx}
This is used as part of the question text to introduce a concatenation screen section in the questionnaire. It should be used on a single-coded dummy question (having [0] at the end), and it should have as many options on it as there are questions to follow making up the concatenation screen. If there are more questions on the concatenated screen than the maximum allowable codes on a coded question (currently 64), then use the second syntax. For example, if there are 87 questions on the one screen, then use {CONCAT 87} instead, and just have one answer code. The question text (minus the {CONCAT}) will be used as a header for the screen. The answer texts for the {CONCAT} question are ignored. You can have different types of question on the same concatenation screen. The {CONCAT} question can be used to randomise, rotate, reverse or alphabetise the order of the questions in the concatenation screen using the standard DKapture language constructs to do the same with sections of a CATI questionnaire.

{GRIDHEAD colour1, colour2, title parameters, cell parameters, first col parameters, section header, samerow divider cell}
or {GRIDNOHD colour1, colour2, title parameters, cell parameters, first col parameters, section header, samerow divider cell}
This is used on the first question of a set of questions that will form a grid. The question's answer texts are used as the column headers in the grid if you use {GRIDHEAD ...}. There are no column headers used if {GRIDNOHD ...} is used. The question text is used as the label for the left-hand column of the first row. All parameters are optional.

colour1 is the colour of the even rows in a grid

colour2 is the colour of the odd rows in a grid

title parameters are HTML attributes for the table header elements for the grid question (TH)

cell parameters are HTML attributes for the table cell elements of this row, and possibly subsequent rows, of the grid question (TD)

first col parameters are HTML attributes for the table cells that form the first column containing the question text for each question in the grid

section header is an optional definition of the row that follows the column headings (if there are any) but precedes the rows of the grid. It requires <TD...> ... </TD> to be specified with the text and should not contain any commas. It is always on its own row.

samerow divider cell is an optional cell definition for separating questions laid out in a grid on the same row. It requires <TD...> ... </TD> to be specified with the text and should not contain any commas. For example, <TD bgcolor=gray WIDTH=5px></TD>

{GRID cell parameters}
This is used on questions that are part of a grid (each row in the grid is a new question with options going across the screen), and as such, its question text and radio buttons / checkboxes / entry fields are to be laid out in one row on the grid. The answer texts are ignored. If the optional cell parameters are not specified, they are taken from the GRIDHEAD definition, if there is one.

cell parameters are HTML attributes for the table cell elements for this row, and possibly subsequent rows, of the grid question (TD)

{SAMEROW}
This is used to attach this question to the same row as the previous question in a grid concatenation. If you wanted to put a multi, a numeric and a single-coded all on one line of a grid, then this will enable you to do so. Usually used in conjunction with {GRID}. If this is a {GRID} and the preceding question is a {GRIDHEAD ...}, then column headers from the answer texts for this question are added to the grid header. All {SAMEROW} questions that have {GRID} join their headers onto the initial {GRIDHEAD ...} answer texts to form the header for the whole grid.

For example, with DKapture question text as follows (2 multis and a list-type) :-

.qg1.
{CONCAT}Let's <B>Grid</B> this one up now :-

1)
2)
3)
[0]
.qg2.
{GRIDHEAD aqua,silver,width=50px,width=50px align=center}Which countries have you been to?

1)Turkey
2)Cyprus
3)Spain
4)Brazil
5)Laos
6)Iceland
)
[-6]
.qg3.
{GRID}Which have you yet to visit?

)=qg2
[-6]
.q1.
{GRID}Please select a representative code

2000)reps.cfg

you would see something like :-

Let's Grid this one up now :-

	Turkey	Cyprus	Spain	Brazil	Laos	Iceland
Which countries have you been to?
Which have you yet to visit?
Please select a representative code

Progress: 26% done

Clicking the "Next" button having not selected any options in the first 2 rows of this grid, would result in the "invisible" no answer codes for these 2 rows being selected automatically.

Back to the Top

Questionnaire Directives

See also New DKapture Language Features

{NOBRS}
Prevents extra <BR> tags being added to the output when a newline is encountered in the question or answer text. When this is used, new lines have to be introduced using an explicit <BR> tag. Using this directive allows for complex HTML screens to be built as question screens. Without it, you would have to input all the HTML on one line. Also, prevents double spaces being converted to   plus space, so HTML indentation is preserved.

{DISABLE}
When used in the question text of single and multi-coded questions, this will render the checkboxes or radiobuttons for that question disabled. When used on a numeric or alpha, the text input box for that question becomes read-only.

{NOBACK}
A question containing this directive will not present the user with a "Back" button, and hence forces the user to move on to the next question.

{NONEXT}
A question containing this directive will not present the user with a "Next" button, and hence forces the user to move back to the previous question. It also has the effect of not advancing the progress bar (if there is one) on reaching this question.

{ROWS=xx}
This sets how many rows are visible in alphas and list-type questions. By default, list-types display a single row with a drop-down list. When {ROWS=30}, for example, is specified on a list-type, a scrolling list of 30 rows is displayed instead of a single row with a drop-down. When specified on an alpha question, the entry box for text is made to be this many rows instead of the default 7 rows.

{TABLE ...}
If this appears in the question text, then that question's Answer Table Definition is overridden with the definition contained in the ellipsis. If this appears on a {CONCAT} question, the answer table definition is overridden until the end of the {CONCAT} section.

{EXTRA ...}
If this appears in the question text, then, after the answers have been laid out for that question, the text contained in '...' is appended to the input cell for that question. If the question is single or multi-coded, and there is a no answer code, the '...' text appears after the no answer input cell only. If there isn't a no answer code for the single or multi-coded question, then the '...' text is appended to each input cell for each code that appears on the screen for this question.

No Answer Codes and the Alt+255 Character
Usually, if the interviewee moves on from a coded question with a no answer code, having not selected any options, the no answer code is checked automatically. The question is deemed to have been answered as zero (not skipped). However, if the no answer code text contains an invisible Alt+255 character in the answer text (but not as the last character), the question has to be explicitly answered (coded) before the respondent can move on.

The @ character
When a coded question has a no answer code but no text associated with it, this checkbox or radio button is not displayed on the screen, but is checked if no response is selected for the question and the interviewee moves on. The answer to this question is deemed to be skipped. When a coded question has a no answer code whose answer text is the single character @, this checkbox or radio button is not displayed on the screen, but is checked if no response is selected for the question and the interviewee moves on. The answer to this question is deemed to be zero. If a coded response is prefixed with the '@' sign, then it is presented at the bottom of the list of codes, even after the no answer code, if there is one.

Back to the Top

DKapture Data File Analysis Methodologies

There are 2 methods you can use to analyse data collected in an online survey.

For those with Javascript-Enabled Browser Access, use the ONLINE.CGI program

The online.cgi application enables live data analysis and drill-down through a complex HTML template which relies heavily on Javascript for its functionality. The application presents a screen with Side and Break variable lists for table and chart generation, and also allows report listings through a toggleable set of options which allow for multi-selection of verbatim and non-verbatim questions in the survey to be listed out in HTML, or other formats. Report listings and tables/charts can be saved for future use. The data can be analysed with no changes to the online survey files (in situ) by calling up a link, for example,
http://www.YourISPHost.com/scripts/online.cgi?survey=OurSurvey

There are some extra optional parameters that can be appended to the URL :-

&cpd=compiled file
&dat=data file
&un=username
&pw=password

These should be fairly self-explanatory and allow for multiple compiled and data files in the same analysis directory on the server.

A separate database for online analysis users is required. It is called onlinea_users.dbf and should reside in the same directory as the data being analysed on the server. Its presence enables online analysis for that survey. It should be indexed on the USERNAME field. It has the following structure :-

Field Name	Field Type	Length	Description
USERNAME	Character	50	Login name.
PASSWORD	Character	50	Login password. If this field is blank, the first password used by this user is encrypted, stored in here, and used for future logins.
USERCLASS	Character	20	The level of user. If "Administrator", then more technical information is shown on the screen.
FILESUSED	Memo	-	A list of intermediate temporary files used by the system on the server during any session. These are deleted when the user logs out, or the session times out after 30 minutes of inactivity.
HISTSLOT	Numeric	8	As the user defines and generates filters, tables, charts and listings, a history is built up which the user can go back into if necessary. This number represents how deep their history trail is.
LOGINDATE	Date	8	Last login date.
LOGINTIME	Character	8	Last login time.
IPADDRESS	Character	30	Last login IP address.
USERNOTES	Memo	-	Spare field for notes about the user.
CURFILTER	Memo	-	The current filter expression in use on the data.
QSIDE	Numeric	10	Question number of the chosen side variable.
QBREAK	Numeric	10	Question number of the chosen break variable.
QTBLREQD	Numeric	3	1 - Table Required, 2 - No Table.
QCHART	Numeric	3	Chart type: 1 - Pie, 2 - Bar, 3 - Horizontal Bar, 4 - No Chart.
QTHREED	Numeric	3	Chart perspective: 1 - 3-Dimensional, 2 - Flat.
QSIDEPCTS	Numeric	3	1 - Counts Only, 2 - Counts and Column Percentages, 3 - Column Percentages Only.
QCHWID	Numeric	4	Chart Width in screen pixels.
QCHHEI	Numeric	4	Chart Height in screen pixels.
SHOWRPTOPS	Character	9	Denotes the visibility of the report listing options section.
SHOWADVOPS	Character	9	Denotes the visibility of the advanced options section.
CURROPS	Character	80	The name of the last loaded/saved report.
CHTBGCOL	Character	30	Chart start background colour.
CHTBGCOL2	Character	30	Chart end background colour.
PIECUTOFF	Numeric	4	The percentage below which slices are grouped into an "Other Values" slice (default 0 - all slices detailed).
BARTYPE	Numeric	3	Type of bar used: 1 - Solid 2 - Cylinder 3 - Arrow 4 - Gradient Fill 5 - Ellipse 6 - Pyramid 7 - Inverted Pyramid
BRKDETAIL	Numeric	3	Bar Layout on Multi-Dimensional Bar Charts: 1 - SIDE BY SIDE - plot separate bars next to each other 2 - STACKED - stack the bars on top of each other 3 - STACKED "100%" - stack the bars on top of each other and scale them 4 - BACK TO FRONT - plot separate bars in a 3-D perspective from back to front 0 - No Detail
BARWIDTH	Numeric	4	The percentage of the column width occupied by a bar (default 70%).
LEGENDPOS	Character	9	Legend position: right, left, top, bottom, or invisible
LABELSIN	Character	2	Labels Inside Bars/Segments? (Y means yes)
QVERB	Character	200	Comma-separated list of verbatim question numbers for questions to appear in a report listing.
QNONVERB	Character	200	Comma-separated list of non-verbatim question numbers for questions to appear in a report listing.
QJUSTCODES	Character	2	Non-Verbatim Codes Instead of Texts? (Y means yes)
RCSPERPAGE	Numeric	4	Number of records per page on report listings.
DIRECTRIX	Character	20	Last action performed (internal use).
BGRNDFILE	Character	90	Name of the image file used to tile the background for the session.
HILITCELLS	Memo	-	!-delimited cell coordinates for highlighted cells.
BANDING1	Character	200	Banding used for the current side variable numeric.
BANDING2	Character	200	Banding used for the current break variable numeric.
REPORTHDR	Character	2	Output question label key at top of each page on report listings? (Y means yes)
XPLODE	Character	2	Explode largest pie slice on pie charts? (Y means yes)
OUTPUTTO	Numeric	3	Output report listings or table/charts to: 1 - Microsoft Excel Spreadsheet 2 - Microsoft Word Document 3 - Microsoft Powerpoint Presentation 4 - PDF Document 0 - Web Browser (Default)
QBLANKRECS	Character	2	Output blank records? (Y means yes)
INCDKCODES	Character	2	Include dkapture codings in tables/charts? (Y means yes)
INCSDBLANK	Character	2	Include blank rows in tables/charts? (Y means yes)
INCBRBLANK	Character	2	Include blank columns in tables/charts? (Y means yes)
HYPERLNK	Character	230	The hyperlink to associate with the cells in a table - see the documentation for HYPERLINK
CATEGORIES	Memo	-	The report visibility categories for this user. Put each category name on a new line. These appear in the Report Visibility dropdown list and enable reports to be shared across users with the same categories as each other. You can save a report into a certain category, and any user that has that category in this field, will be able to select that category and load that report.
EMAIL	Character	90	Information only - not used by the online.cgi application currently.
ADDCHTOPS	Memo	-	Additional chart options eg. +flipped (sticky - these options are applied to all output until changed and are only visible to USERCLASS Administrator)
ADDPIVOPS	Memo	-	Additional table options eg. DROPCODES (sticky - these options are applied to all output until changed and are only visible to USERCLASS Administrator)
LQDATE	Date	8	Date of last generated output.
LQTIME	Character	8	Time of last generated output.

When setting up this database, you have to populate the USERNAME fields. Others you can consider, but are not obligatory, are the USERCLASS, CATEGORIES, ADDCHTOPS and ADDPIVOPS fields.

The screen presented to the online analysis user is shaped by the template file onlinemain.htm. You can override this file by placing your own version into the survey directory. Otherwise it picks up the one resident in the "data" directory. Mnemonics within the template are substituted for information relevant to this survey and session. Here is a complete list of template mnemonics and what they are substituted for :-

Mnemonic	Substituted for
_SYSTEMNAME_	"Critical Research Online Analysis System".
_SURVEY_	Survey Name (Directory where the files are!).
_LICENSEE_	The company name stored in the licence file on the server running the online system. In the case of www.critical-surveys.co.uk it is "Critical Research".
_DATE_	Today's date in the format used by the server for short dates.
_TIME_	The time in the server's time format (as appears in the taskbar clock).
_QUERY_	Everything after the question mark in the URL used to run online.cgi
_USERNAME_	The username used to logon to this session. Same as _USER.USERNAME_
_USERTITLE_	Whatever is held in the USERCLASS field for this user. Same as _USER.USERCLASS_
_TICKETNO_	Internal security number used to maintain a "session" after logon.
_HOST_	The name of the host that houses this server, eg. "localhost" or "www.critical-surveys.co.uk"
_FILTER_	The currently imposed database expression that filters the data records (usually as a result of drill-down).
_FILTERTEXT_	The currently imposed filter expressed in verbose terms using abbreviated question texts and answer texts.
_BASE_	Gives the string " - Base : xxx" where xxx is the number of records in the current base.
_BASENUM_	Gives the number of records in the current base.
_CAPTION_	Gives a "key" for report listings and table/chart outputs.
_SIDEFLD_	Gives the side variable database field name prefixed with a space.
_BREAKFLD_	Gives the break variable database field name prefixed with a space.
_SIDEDESC_	Gives the first 999 characters of the question text for the side variable.
_BREAKDESC_	Gives the first 999 characters of the question text for the break variable.
_QPICKLIST_	A list of all questions in SELECT (<OPTION>...</OPTION>) format.
_APICKLIST_	A list of verbatim questions in SELECT (<OPTION>...</OPTION>) format.
_NPICKLIST_	A list of non-verbatim questions in SELECT (<OPTION>...</OPTION>) format.
_RESULT_	A set of table rows that define the current table and/or chart.
_SAVEDOPS_	A list of the saved reports for the current user in SELECT (<OPTION>...</OPTION>) format.
_RPTVIZOPS_	A list of the report visibility categories for the current user in SELECT (<OPTION>...</OPTION>) format.
_COLOUROPS_	A list of colours to paint the chart background in SELECT (<OPTION>...</OPTION>) format.
_RPTLISTOUT_	URL to the spawned output when doing a report listing or table/chart output.
_RPTFLDLIST_	This is either the list of semi-colon-delimited fields in a report listing, or "Table/Chart " in a table/chart output.
_BGIMAGES_	A list of background image filenames found in the "online_images" directory off of the cgi-bin or scripts directory on the server. Add more .bmp,.jpg,.jpeg,.gif,.png files to increase your choice of backgrounds for the analysis system pages.
_USER.<fieldname>_	Any field from the users database. <fieldname> should be the fieldname required, for example _USER.ADDCHTOPS_
_EXEDIR_	The full URL (including the trailing slash) to the directory on the server housing the online.cgi executable.
_EXECUTABLE_	The full URL to the online.cgi executable.

Report listings and printable table/chart output can be configured further through the use of output templates. The following nomenclature, protocol and hierarchy describes their deployment, using Excel as an example :-

For table/chart outputs to Excel :-
onlinetablechartxls.htm in the survey directory
onlinetablechartxls.htm in the data directory
onlinetablechart.htm in the survey directory
onlinetablechart.htm in the data directory

For report listing outputs to Excel :-
onlinelistingxls.htm in the survey directory
onlinelistingxls.htm in the data directory
onlinelisting.htm in the survey directory
onlinelisting.htm in the data directory

For the other types of output, substitute htm/doc/ppt for xls above.

online.cgi comes with pre-defined templates for onlinemain.htm, onlinelogin.htm (a login screen template similar to the one for DKWebServe_Adv.cgi), and all report listings and printable table/chart outputs. You can also design a template called onlinelogout.htm and put it in the survey directory. If such a file is found, then this is what is visited when a user logs out of the online analysis system, instead of returning to the login screen.

For those with Javascript-Disabled Browser Access, use the following techniques

A combination of DKWebServe_Adv, NiceWin, and DKWebStats can be used to enable on-line analysis of DKapture data for clients using their web browsers. The analysis consists of the client selecting a filter for the data, followed by side and break variables. To set up on-line analysis for a survey called "OurSurvey", follow these steps :-

Ensure that the DBF-format data you want to analyse is in a directory called "OurSurvey" off of the "data" directory (see Server Deployment above). The main data file is called OurSurvey_dat.dbf but there may be a second if you have longish alphas in the data, called OurSurvey_dat.fpt. Put the matching compiled file OurSurvey.cpd in here too. This should already be the case, if it's an on-line web survey.
Create a directory off of the "data" directory called "OurSurvey_analysis" (the analysis directory), and copy the questionnaire text file OurSurvey.txt into it.
Change any texts in this copy of OurSurvey.txt with a text editor, so that the client will have meaningful prompts for the variables used in the analysis. Only the first 90 characters of question texts will be visible to the client on most screens during analysis definition. Only singles, multis and numerics will be available for analysis by default. Drop any questions you do not require for analysis purposes. Routers and display type questions are dropped automatically. Question routing is also dropped. All changes you make are optional and cosmetic.
Compile this (possibly) altered questionnaire text file with DK1Win. Open it in NiceWin. Use the menu option "File, Generate Analysis Questionnaire" to generate OurSurvey_analysis.txt in the "OurSurvey_analysis" directory.
This will create a list-type database called OurSurvey_anlist.dbf in the analysis directory. Optionally set the field RANGES_PCH for any numerics you wish to suggest comma-separated ranges to band that numeric value into.
Optionally tweak OurSurvey_analysis.txt with a text editor, and then compile it with DK1Win. Change the look of the pages of the analysis survey your clients will see, by using HTML Templates in the analysis directory. Configure the survey by copying the Configuration File into the analysis directory and tweaking it.
Give your clients a link to the analysis survey, with optional username and password (to save them having to log in if so desired). For example :-
http://www.YourISPHost.com/scripts/DKWebServe_Adv.cgi?survey=OurSurvey_analysis&un=Fiona&pw=quire

For multiple analyses, the client revisits the link and, because all the old answers will be in place, analysis refinements will be easy to do.