Login to your gamut/orion account and enter:
    ~rspatema/http/cpoll/install
This command can be re-run at any time.
The Installer sets up a default manager (if not already set) and creates and copies several directories and files in your account. It emails your account with the default manager info and other installation details.

Login to your gamut/orion account and enter:   cpam
Create a new cpoll file -
At the task prompt enter:   nc
For the filename enter:   cpoll01
Copy the reference url that is displayed and paste it into a browser's location bar, and optionally save it in one of your web pages.
Create a new user file -
At the task prompt enter:   nu
For the filename enter:   users-dept
Use the reference that is displayed to access the file: UserFile=../cpoll/users-dept

From the browser, login as the default manager, select the Edit Parameters link and edit each of the six sections. Basic sections: 1 - Overall layout, 2 - Users and Manager, 6 - Questions and Answers. Add the reference for the users-dept file to section 2.
Edit users-dept file with the Edit User File link on the manager page (after reloading the page). Follow the notes included at the top of the file.
After editing always check the Setup Log on the manager page (after reloading the page). Finally, do several submits to test cpoll01 operation, and then do any mailing(s) to users as needed.

Login to your gamut/orion account and enter:   cpam
At the task prompt enter:   dm
For each of the five items give a new value or hit 'Enter' to leave the value unchanged.
Note - this command can be used to view the default manager values without changing any.

Use- survey, evaluation, scheduler, etc. Set the Type and Title parameters to reflect this use.
Users- ID's and passwords are required, names and e-addresses are optional. Store users in the cpoll file, in separate user file(s) or both (see the next paragraph for several ways that users can be arranged in the files). User ID suggestion to avoid duplicates and ease searching: first name initial + first 3 - 6 char of last name. Alternate: first name + first 1 - 3 char of last name.
Manager- If the Mgr parameter is unset, the default manager is used to access the Cpoll; if it is set, the given ID and password (a custom manager) is used when accessing the Cpoll. If a user exists with the same ID as the manager (default or custom), a Setup Log record is created, and the manager can login but the user cannot.
What users will see- Open & Close dates (if any), View Without Login, View All Users, Report Format (if any), etc.
Questions and Answers- Each question can have zero or more answers, plus a comment. For each question, if any answers are given, decied if the user can select any number of answers or just one. Questions with no answers but which allow a comment are useful for gathering user data, such as general comments, user preferences, mailing addresses, etc.

Users are read from the cpoll file, then from each user file. User files are processed in the order they are given in the cpoll file. If there are duplicate ID's, within a file or between files, the last user record read is the one used.
cpoll01 - Two users in cpoll file.
cpoll02 - One user in cpoll file, one user file, no duplicate ID's.
cpoll03 - Two users in cpoll file, one user file, one duplicate ID. users-music shared with cpoll04.
cpoll04 - Two user files, one duplicate ID. users-music shared with cpoll03.

Naming files.  File names for cpoll and user files can be any Unix allowed name, which are case sensitive. The names: cpoll01, cpoll02, ..., and users-art, users-music, etc, are suggested for convenient display in file listings

Install procedure sets up these directories and copies these files:

home dir. holds cpam, the Cpoll account manager program, used for updating the default manager and creating new cpoll's and user files.
cpoll dir. is off of the http dir. for security. cpoll00 and cpoll00lite are templates for cpoll files, users00 is the template for user files, and defmgr holds the default manager info.
cpoll/archive dir. is for older files and has very secure permissions.
http dir. is created if it does not exist. It stores the cpoll.cgi program and nph- link, and all cpoll file relative references are in relation to this dir.
Ex: An image ref:  cpoll/linnenbak.gif
Ex: A users file ref:  ../cpoll/users01
http/cpoll dir. stores image files and any cpoll.html files you create, plus it has a protective index.html file. You can replace this index file if needed. The install procedure copies several button and background image files into this dir. for your use, and two Cpoll documentation files.
Damaged files - cpoll.cgi, cpoll00, cpoll00lite and users00 are always replaced when running the install command. Consequently do not use any of these files for any application, as they will be over-written during the next install/upgrade.

cpam provides a number of commands to easily create, copy, move and delete files in your Cpoll directories. To use this program, login to your gamut/orion account and enter:  cpam
At the task prompt enter any of the following commands.

NC - creates a new cpoll file in the cpoll directory (from cpoll00).
NL - creates a new cpoll lite file in the cpoll directoty (from cpoll00lite).
NU - creates a new user file in the cpoll directory (from users00).
DM - allows you to view and set the individual items of the default manager.

DIR - lists the files in the cpoll dir. in two column format.
MV - allows a file to be renamed (moved); the new file name cannot already exist.
CP - allows a file to be copied; the new file name cannot already exist.
RM - allows one or more files to be removed (deleted).

DIRA - lists the files in the cpoll archive directory.
MVTA - move a file to the archive dir. (from the cpoll dir.) The file cannot already exist in the archive dir.
MVFA - move a file from the archive dir. (to the cpoll dir.) The file cannot already exist in the cpoll dir.
CM - display the individual items of the custom manager, if any, in a cpoll file.

Notes - cpam allows items (space separated) on the task input line following the task name, which will be used to satisfy the required input for the given task. For example:  nc cpoll09  will create the new Cpoll file cpoll09. This feature is useful after you become familiar with the required items for each task. Note that any such item which contains spaces must be surrounded by double quotes, for example: "John Q. Roberts".

Cpoll file and user file updating, during a manager session, is done only after a manager function's Submit button (if any) is pressed. Thus you can use the Back button to return to the manager page from any function, and if the Submit button wasn't pressed, any referenced file will not be modified.
Simultaneous manager access to one cpoll file thru two or more browser sessions is not recommended. This is especially dangerous if two or more sessions simultaneously Edit Parameters or Edit User File (on the same file). Changes made in one session or the other will inevitably be lost.

User records with duplicate IDs. For any Cpoll application, all users given in the cpoll and user files (if any) are merged into one allowed user list. There is only one entry in this list for multiple user records containing the same ID (case-insensitive); this entry will have the information from the last user record processed. For this reason you should keep the records in the user file(s) in ID sequence and check the User Report in the Setup Log whenever you modify or add users, to prevent inadvertent duplication of user ID's.
This Cpoll feature allows for easy updating of user files, where each appended record with a given ID is an update of the last record with the same ID. Additionally, if two or more user files are given, and the same user exists in two or more of them, only one allowed user will appear; this is useful to prevent duplicate mailings when using several user files in one Cpoll application.

For users, do not change their ID's, even the case of the ID.
For questions, do not delete or re-arrange existing questions. However new questions can be added at the end of the question list. Internally, questions are numbered sequentially (from 1) and these numbers are stored in the user response records; deleting or moving existing questions will cause a mismatch between questions and existing user responses.
For answers, the code-text should never be changed (or the answer-text, if code-text was not given), and the answers for any question should not be deleted. But existing answers can be re-arranged, and new answers can be added in any sequence to any question.
Edit parameters, users and user responses thru the Cpoll program. Although a cpoll file can be viewed with pico, pico should never be used to edit it, since pico's 255 char/line limit will improperly break any long comment lines.

Emailing Users. For non-NEIU addresses, if a bad address is given and the email can not be delivered, no error message will be sent to the manager. This occurs because the webserver is used and mail is sent from the 'nobody' system account.
Change SetEmailFromAddr= to yes to have non-delivered mail returned to the manager's email address (NEIU or non-NEIU address). But note that an X-Authentication-Warning header is automatically put into each email by the sendmail system program. If this causes mail problems, turn this parameter back to no.
Save a copy of the email send log for your records. This is especially helpful when diagnosing mailing problems, should they occur.

For input in all comment boxes.
HTML is allowed, the most useful being ' <br> ' used to create a line break when comments are displayed. But avoid other uses of ' < ' and ' > ' since these characters delimit HTML tags. Also avoid HTML special characters such as ' &amp; ' due to idiosyncracies in Windows' textarea processing.
Text starting http:// is turned into a hyerlink, which when clicked opens into a new window. The text is unchanged in the file, making for easy user editing.
Image tags can be used, such as:
But absolute image references should be used, pointing to web available images.

In Edit Parameters page.
HTML is allowed, for those parameters where noted, but do not use special HTML characters such as ' &#149; ' and ' &nbsp; ' due to the idiosyncracies of Windows' textarea processing.

Bold typeface is used to display a number of parameters, such as Instructions, ResponseMsg, PreText and Q. Turn off bold anywhere in these parameters using the ' </b> ' tag, and turn it back on with ' <b> '. Also of use, to highlight words or phrases, are the italicize and underline tag pairs: ' <i> ' plus ' </i> ' and ' <u> ' plus ' </u> '
Determine the primary QuestionFormat (CheckboxMulti, CheckboxSingle, CheckboxExclusive) and AnswerLayout (Vertical, Horizontal, PackedHoriz) for questions in the Cpoll and set these parameters accordingly. For those questions which do not match these defaults, set the individual question options (ie, M, S, X and V, H, P).
AnswerLayout = PackedHoriz for any question generally works best with ReportGen = no (ie, for the entire Cpoll).

Carefully analyse what infomation you want to collect, and phrase questions with enough detail to elicit this info.
Sequence the questions - introductory, detailed, summary; place questions into logical groups and create a flow from general to detailed within each group. For long surveys, turn off question numbers, easing the user's view, and use the PreText parameter to identify and describe question groups.
Use scales in preference to yes-no questions. Sample scale: Excellent, Good, Average, Fair, Poor. Assign scale values for those questions where an average calculation is desired, and usually add 'Don't Know', 'None' or 'Not Applicable' to the scale (with value = 0).
Place comments judiciously. Don't comment every question, since valuable information may be collected at the wrong place.
External review. Have several other people review the survey questions and layout, and incorporate their suggestions. It is difficult for one person alone to anticipate how a variety of users will read and interpret a list of questions.
Case study - cpoll07
Question #1 should not be commented, comment was misunderstood.
Add question (with a scale): User's experience level.
Add question (with a scale): Should NEIU renew LIO.

Submit several test entries and check for correct submit response and report layout. Erase these test submits with the manager's Delete Responses link before doing the main mailing.
Set a Close Date, giving users about two weeks to respond.
Do a test mailing to a few users before the main mailing, and send a followup email to quiet users after one week.

After the Close Date save the report page as an html file; edit the file with a text editor, not an html editor.
Analyze the results, looking for patterns in the data and especially note any ideas and suggestions mentioned in the user comments.
Add to the header:  <base href="http://www.neiu.edu/~username/http"> so that any images used are referenced correctly. Be sure to replace 'username' with your gamut/orion account name. Include any analysis of results at the top of the page.
Post the html file to your http/cpoll dir, for quick download, and announce the survey results, referencing this report page.

The system account 'nobody' runs the web server. Files in the 'username' account must have permissions set for 'all' (or 'other') access. Cpoll generates html pages based on contents of cpoll01 file.

Two or more users can simultaneously access cpoll01 file since the file is locked during the brief reading and writing periods.
How to test file locking.
User updates are appended to the file so that existing data is not disturbed.
User update posting is nearly atomic, ie indivisible, so that system crashes are very unlikely to cause corrupt or incomplete data.

• Possible problem with browser history list after several submits, problem of inadvertent re-submit; same as amazon.com functionality.
• Security problem with auto-login url in browser history list, can be reloaded on public PCs.
• Web server timeout during email send to long lists; if program run with CGI parsed headers, the Timeout param (for Apache, in httpd.conf) controls num. seconds cpoll can run before output discarded; set $pgmTimeLimit well below this value.
• With CheckboxExclusive question, double booking can occur under rare occurance when one user retrieves w/o submit, second user retrieves, then both submit for same Exclusive answer.

The non-parsed header version of Cpoll is setup with this Unix command:
    ln -s cpoll.cgi nph-cpoll.cgi
Then the name: nph-cpoll.cgi  is used in all URL's.
Doc. nph- effects, how to test if functional.

Quest# ^ ID ^ 'A' ^ value [ ^ value ... ] (^ = tab)
Quest# ^ ID ^ 'C' ^ text (^ = tab)

If value=all blank, no answer for this qnum+ID
If text=all blank, no comment for this qnum+ID
When comment text is recorded in the file, newlines are transl. to space.
Comment text saved and displayed on report with: " => ' and \ => space.
If qnum < 1 or > num. quest., or has non 0-9 char, record ignored.
If ID = blank, record ignored. If rec-type not 'A' or 'C', record ignored.
Only the last record in the file for a given qnum & ID & rec-type ('A' or 'C') is processed, all other records are ignored.
Orphan answers are always reported, to user ID and in report; and orphan comments force the display of a comment text box for a user ID and are always shown in the View Comments window.

AC Survey ==> ETLT Survey ==> Muscon Eval ==>
+ Dyn. Cal ==> Cpoll ==>
+ ckgrade ==> Cpoll2 ==>
+ webref + formq (partial) + fmaint (partial) ==> Adv. Cpoll