2009-08-03
QPL Reference Manual

Warning! This page is in the process of being rewritten for QPL Version 6. It may still have references to QPL Version 5.

The QPL HomeSite add-in tools can simplify setting up your project for your web server. All of these tools are accessed using the buttons on the QPL tool bar.

QPL Tool Bar

Before your build your first web site project, however, you should coordinate updating your HomeSite/QPL system with various settings that are specific to your web server, or collection of web servers. The Server Set Up page lists all the one-time steps that your web site administrator must perform in order to host a QPL questionnaire, such as setting data base passwords, creating directories for various standard files, and installing encryption software.

1. Fill Project Directory With Standard Files

To take advantage of these tools, you should always use the "Create New Project" button () on the QPL tool bar to start a new project. The Create New Project button creates a template program and fills your project directory with all of the standard web site files.

2. Set the Convert and Build Options

The template file created by Create New Project button includes two special lines, "CONVERT Options" and "BUILD Options," that you can use to store the configuration settings for your project. These lines are embedded with in QPL language comment lines so they are not read by the QPL compiler. Instead, they are read by the PHP () QPL tool bar function that builds the web-site version of your project.

QPL Program Template

*****************************************************************************
** PROGRAM:                                                DATE:           **
**  AUTHOR:                                                 JOB:           **
**                                                                         **
**   TITLE:                                                                **
**                                                                         **
** PURPOSE:                                                                **
**                                                                         **
**                                                                         **
**                                                                         **
**                                                                         **
**                                                                         **
***************************************************************************** 
** CONVERT Options: /d /f /l
** BUILD Options: /s= /d= /u= /p= /a=
***************************************************************************** 
continued...

CONVERT Options

The CONVERT Options line lets you include any command line options for the qpl_convert.exe program to modify how it builds the web site, statistical files, or other items. See Converter Command Line Options for a list of all the options. By default, it includes options to build a tabulation report for the project administrative page the will include descriptive and frequency statistics and lists of narrative responses for each question as appropriate.

You may used the CONVERT Options button on the QPL tool bar to create a new CONVERT Options line in your program. Pressing this button displays a dialog box that lets you select among commonly used options and then inserts a correctly formatted line into your program at the current cursor position.

Only one CONVERT Option line should be used in your program and it must be used in one of the comment lines at the start of your program. (If a blank line or a command line appears before this line, then this line will be ignored.)

BUILD Options

Use the Build Options line to automatically set the server configuration and MySQL account information in the qpl_config.inc file. The settings needed here should be supplied by your web server administrator. (See Server Set Up.) If used, a setting should be typed immediately after the "=."

Option Comment
/s= The type of server, either "QPL_LINUX" for a Linux server or "QPL_NT" for a Windows server.

This will usually be left blank. If you web server administrator has installed the QPL configuration file, qpl_config.inc, in a PHP include directory as recommended in the Server Set Up instructions, then this setting will not be used.
/d= Name of the MySQL data base for this project. If this is left blank, which is usually done, then the data base name will be the same as your project file (i.e., the .pg6 file) name.
/p= MySQL password. This should be provided by your web site administrator and will be the same for all of your QPL projects.
/u= MySQL user name. This should be provided by your web site administrator and will be the same for all of your QPL projects.
/a= QPL System Administrator password. The system administrator user name is "admin." If you do not set a password here, the password will be set to "changeme." QPL passwords are not case-sensitive.
** BUILD Options: /s=QPL_LINUX  /d= /p=tigerlily /u=smithj

In this example, the Linux settings will be used in the QPL configuration file and the MySQL user name will be "smithj" and the password will be "tigerlily." The data base name will be the same as the project name since no /d= option was used.

These options update the qpl_config.inc file. This file may have already been setup for use on your web server. (See Server SetUp.) It also updates the job.sql file that is used to create the MySQL database for your project, thus ensuring that the same MySQL user name and password are used both when the data base is created and when it is accessed by the questionnaire web site.

If a shared copy of the qpl_config.inc file has been installed on your server, you must use the same user name and password here as were used on that copy of the qpl_config.inc file. Further, you should not deploy the copy of the qpl_config.inc file generated here to the web site with the rest of the files.

3. Build Web Files

Click on the PHP button () in the QPL toolbar to build the files that will be deployed on your web site.

A number of files will be generated or modified in this process. Generally, you will only need to further customize two of these files: index.htm, the home page, and job.sql, the MySQL script that builds your database.

4. Modify index.htm

The home page file, index.htm, and the MySQL database file, job.sql, need to be modified before they are copied to the web server.

index.htm

The index.htm file is similar to the hello.htm file that is created when building a local test version of your project. Generally, you will insert your content into the hello.htm file while developing your application (which should include a greeting and information about who to contact if the respondent has questions). Then, when you are ready to deploy your project on a web server, you will copy your content from the hello.htm file into the index.htm file where indicated. You should be careful not to change anything else in the index.htm file.

job.sql

The job.sql file (again, replace "job" with the name of your project) builds the MySQL database for your project. Here you need to

...
GRANT ALL ON job.* TO qpladmin@localhost idENTIFIED BY "surfclam";
...

INSERT INTO user (q_uname, q_pswd, q_name, q_user_status)
    valueS ('admin', 'changeme', 'System Administrator', 5),
...

In this example, you should change the MySQL account, "qpladmin," and the password, "surfclam," to the accounts set by your system administrator.

Next, you should change the QPL System Administrator password from "changeme" to a password that you define.