2009-08-03
QPL Reference Manual

Building your questionnaire web site files from the console prompt is basically a two-step process:

Below are the steps, in cookbook fashion, to build various types of projects. The word "job," will be used as the name of the sample project. Replace this name with the name of your project when following these steps.

Compiling Your Source Questionnaire Program

Step Description Comments
1. Create a new directory/folder on your computer for your new project. Each project must be put in its own directory.
2. Unzip the contents of the qpl_public_master_files.zip file into this directory. The qpl_public_master_files.zip file will be found in your C:\Program Files\GAO\QPL directory. This Zip file contains the standard files that will be used to support your questionnaire web site, including the QPL CSS style sheet file. The remaining files will be generated when you run the qpl_convert program.
3. Draft your source program using an ASCII or ANSI line editor. Using word processing programs, such as Microsoft Word, should be avoided. These programs will insert various unusable codes even when the text is saved as an ASCII text file. You can safely use the Windows Accessory program, Notepad, to edit your source questionnaire text. Specialized HTML editors, such as Macromedia's HomeSite, may also be used. Each line in your program should not exceed 240 characters.
4. Save this file in your new project directory. QPL source programs are typically saved with a ".pg6" file name extension. Do not uses spaces in your file name. While file names with spaces are supported under Windows, they are not supported in the Linux operating system (which is often used to run the web server where you will be deploying your web questionnaire). This name is also used to name your MySQL database for this project. It too does not use data base names with spaces.
5. Launch a console window and make your new project directory the default directory. Use the "CD" command to change directories at the "C:\>" prompt:
C:\> CD "\my project"
6. Compile your your program. Run the qpl_compile.exe to compile your questionnaire file.
C:\my project\> qpl_compile job.pg6
7. Correct any errors, if necessary. If your program has errors, review the error log file (which has the same name as your source questionnaire program but with a ".err" file name extension, ex. job.err) and make corrections to your source questionnaire program. The error log file is an ASCII text file, which you can view with your text editor. Save your corrected program and compile it again.
8. If your program has no errors, you may use the qpl_convert program to build various project files. (See steps below.) When your program compiles successfully, a new file is created that has the same name as your source questionnaire program but with a ".qpl" file name extension (ex. job.qpl). The qpl_convert program always uses this file when building projects or analysis files.

You can speed up the edit/compile/convert sequence by

With all three windows open, you can quickly move from one step to another.

The DOSKEY program is a console utility that lets you retrieve and edit previous commands by pressing the up-arrow key. You can start this program by either (1) running DOSKEY program at the console prompt when you first open a console window or, (2) by including the DOSKEY command as the last line in your computer's C:\AUTOEXEC.BAT file. In the second case, the DOSKEY program is automatically started every time you open a new console window. Please note, however, the DOSKEY program only remembers commands that were entered in the current window while it was active. If you close the window, all the commands you entered are lost.

Building Projects

When you have successfully compiled your program, you can run the qpl_convert program from the console command line to create various files. Some of the more commonly created projects are listed below. See the Converter Command Line Options for a list of all of the qpl_convert options.

Build Sample Command Line Comments
HTML files for local testing
C:\my project\> qpl_convert job.qpl /htm
Main HTML file will be called job.htm. You may also launch project from the home page that is also created called hello.htm. You may edit the hello.htm file where indicated. The qpl_convert program will not recreate the hello.htm file if it exists. (That is, any changes you make to the file will not be overwritten the next time your rebuild your project.)
PHP files for web server deployment
C:\my project\> qpl_convert job.qpl /d /f /l /php
The PHP version of the questionnaire may only be viewed from your web server. It also creates a new version of the home page, index.htm, which you should edit where indicated. The qpl_convert program will not recreate the index.htm file if it exists. (That is, any changes you make to the file will not be overwritten the next time your rebuild your project.)
SAS system file
C:\my project\> qpl_convert job.qpl /d /f /l /sas
A SAS program that uses the fixed-format file that is exported from the web-questionnaire site to build a SAS system file.
SPSS system file
C:\my project\> qpl_convert job.qpl /d /f /l /sps
A SAS program that uses the fixed-format file that is exported from the web-questionnaire site to build a SAS system file.

Note: The /d, /f, and /l options used above tell the qpl_convert program to include descriptive statistics, frequency statistics, and string lists where appropriate.

Use the File-Open command on your browser to view the HTML files that the qpl_convert program generates when you use the /htm option to build the local version of the files. To see all of the pieces in action (i.e., the home page and the questionnaire with the menu and navigation frames), use your browser's File-Open command to open the hello.htm file. Once that is displayed in your browser, click on the Start Log In button top launch the questionnaire file with the menu and navigation frames.

The questionnaire will look and behave the same as the version you will post on your web server except for the following:

The text layout, menu, default responses, keyboard filtering, and skip instructions will all appear and work as they will when deployed on a web server.

See Deploying a QPL Project That Was Built Using the Console Tools for more information about deploying your finished project.