NAME access - a general purpose application that processes user-supplied (client)
data from an HTML request form, stores information at the host location
(server), sends e-mail notifications to the account owner, and returns
appropriate actions or response messages. All saved transaction records
are verified and formatted for the direct loading of the database file
into an external spreadsheet or database application. SYNOPSIS
<FORM METHOD='POST' ACTION='/cgi-bin/access[?[[<subdirectory>]<filename>]+[<options>]]'
[ENCTYPE='multipart/form-data']>
···
[<INPUT TYPE='hidden' NAME='_alias' VALUE='username@hostname'>]
[<INPUT TYPE='hidden' NAME='_alias' VALUE='username'>]
[<INPUT TYPE='hidden' NAME='_confirm'>]
[<INPUT TYPE='text' NAME='_mailto'>]
[<INPUT TYPE='hidden' NAME='_name'>]
[<INPUT TYPE='hidden' NAME='_nocntrl'>]
[<INPUT TYPE='hidden' NAME='_nodate'>]
[<INPUT TYPE='hidden' NAME='_nomail'>]
[<INPUT TYPE='hidden' NAME='_nosave'>]
[<INPUT TYPE='hidden' NAME='_nouser'>]
[<INPUT TYPE='hidden' NAME='_noverify'>]
[<INPUT TYPE='hidden' NAME='_nowarn'>]
[<INPUT TYPE='hidden' NAME='_onsubmit'>]
[<INPUT TYPE='password' NAME='_password'>]
[<INPUT TYPE='hidden' NAME='_public'>]
[<INPUT TYPE='text' NAME='_query'>]
[<INPUT TYPE='submit' NAME='_redirect' VALUE='...'>]
[<INPUT TYPE='hidden' NAME='_replace'>]
[<INPUT TYPE='submit' NAME='_search'>]
[<INPUT TYPE='file' NAME='_source'>]
[<INPUT TYPE='hidden' NAME='_subject' VALUE='Owner-Defined Subject...'>]
[<INPUT TYPE='submit' NAME='_submit'>]
[<INPUT TYPE='hidden' NAME='_subst'>]
[<INPUT TYPE='hidden' NAME='_verify' VALUE='NAME1 : NAME2 : NAME3'>]
[<INPUT TYPE='submit' NAME='_upload' VALUE='...'>]
[<SELECT NAME='_url' ...>...</SELECT>]
[<INPUT TYPE='text' NAME='_username'>]
[<INPUT TYPE='submit' VALUE='...'>]
···
</FORM>
where <filename> is composed of any alphanumeric, - (hyphen), or
. (period) characters; where <options> includes any order of the
characters [++]; and where <subdirectory> is a valid path starting
from the current host location (the location of the request form). The
<subdirectory> option requires that the specified folder(s) already
exist on the server, whereas the <filename> option will automatically
create any record transaction files. The ENCTYPE='multipart/form-data'
term in the <FORM ...> tag is only required to enable the NAME='_upload'
(attachment) feature. Field NAME attributes begin with the reserved '_'
character and are case-sensitive. Brackets [] are used in this document
to denote optional values and are not used in the actual syntax. AVAILABILITY
http://www.eiu.edu • http://www.ux1.eiu.edu
DESCRIPTION The script accepts a record of data from an HTML request form on standard
input, stores the record in a tab-deliminated format in a UNIX text file,
and then displays either a generic or owner-supplied response page. Each
data record is stored by as a tab-deliminated string of characters on
a single line terminated by an end-of-line (<EOL>) linefeed character.
Submitted information will be placed in the same directory (folder) as
the HTML web page that displays the request form, unless a modifying<subdirectory>
is specified as an option. The script can also control password-protected
access to submit information. The script will also transfer (upload) a file (attachment) of any format
from the client's local computer to a host location on the server. The
uploaded file will be placed in the same directory (folder) as the HTML
web page that displays the form to do the upload, unless a modifying<subdirectory>
is specified as an option. The script can also control password-protected
access to the upload destination and the subsequent ability to download
files from this location. Use of this feature requires the client to use
a browser that supports the <INPUT TYPE='file'...'> feature. The script will also redirect a client's browser to a selection made
from a 'drop-down' menu of host (URL) locations. This capability takes
precedence over the processing of transaction records. OPTIONS The script is controlled by values passed through the equivalent of both
the GET and POST methods. Single character options passed by the GET method
use the <options> part of the Query String (see above), located
within the ACTION attribute of the <FORM> tag, and are prefixed
by a single '+' character. Options passed by the POST method use NAME
attributes prefixed by a single '_' character in tags within the <FORM>...</FORM>
block. All option specifiers are case-sensitive.
|
++ |
Display the current documentation and disable
all other actions of the script.
(No other Query String options are available at this time.) |
|
_alias |
Send an e-mail notification to another address.
By default, all transaction records and critical error messages
are copied as e-mail messages and sent to the owner of the host
location. The _alias option allows another e-mail address to be
specified in the VALUE attribute. A default hostname of '@eiu.edu'
will be appended to the alias unless another hostname is specified
in the VALUE attribute.
<INPUT TYPE='hidden' NAME='_alias' VALUE='username@hostname'>
...or...
<INPUT TYPE='hidden' NAME='_alias' VALUE='username'>
|
|
_confirm |
Enable a confirmation response page before client data is saved
to the host location. By default, all valid transaction records
are saved to the host location before displaying a response page.
The _confirm option allows the client to personally verify the information
before completing the transaction. The _subst option may not be
used in conjunction with the _confirm option.
<INPUT TYPE='hidden' NAME='_confirm'>
|
|
_mailto |
Send a copy of the transaction record to an e-mail
address specified by the client. By default, all transaction records
are only copied to the display screen of the client. The _mailto
option allows the client to specify an e-mail address in the VALUE
attribute to send the transaction record.
<INPUT TYPE='text' NAME='_mailto' VALUE='username@hostname'>
|
|
_name |
Prefix values in the transaction record with corresponding
field names. By default, all transaction record files are created
with the first record containing only field NAME attributes sorted
in alphabetical (ASCII) order to facilitate transfer to an external
spreadsheet application. The _name option overrides this feature
and prefixes each stored VALUE attribute with the corresponding
NAME attribute, using the format NAME=VALUE. This option is not
recommended if the data (<filename>.data) or log files (<filename>.upload
for uploads) will be used in spreadsheet or database applications.
<INPUT TYPE='hidden' NAME='_name'>
|
|
_nocntrl |
Override removing control characters from a transaction record.
By default, all transaction records are processed to remove control
characters from all NAME and VALUE pairs, which is useful for importing
a database file directly into an spreadsheet or database program
where extraneous carriage returns would conflict with the parsing
of the data fields. The _nocntrl option cancels this processing
of the transaction record.
<INPUT TYPE='hidden' NAME='_nocntrl'>
|
|
_nodate |
Override appending a date·time stamp to the
transaction record. By default, all transaction records are appended
with a date·time stamp of the form YYYY-MM-DD @ HH:MM:SS.
With the _name option enabled, the default stamp will also have
a DATE= prefix. The _nodate option cancels the date·time
stamp feature.
<INPUT TYPE='hidden' NAME='_nodate'>
|
|
_nomail |
Override sending an e-mail notification. By default,
all transaction records are copied as e-mail messages and sent to
the owner of the host location. The _nomail option cancels sending
an e-mail message of the transaction record.
<INPUT TYPE='hidden' NAME='_nomail'>
|
|
_nosave |
Override saving a transaction record in a data file.
By default, all transaction records are saved (appended) in a data
file at the host location. The _nosave option cancels saving the
transaction record.
<INPUT TYPE='hidden' NAME='_nosave'>
|
|
_nouser |
Override appending the user location to the transaction
record. By default, all transaction records are appended with a
remote host (address). With the _username option enabled, the remote
host (address) will have the client's username prefixed. With the
_name option enabled, the remote host (address) will also have a
USER= prefix. The _nouser option cancels the remote host feature.
<INPUT TYPE='hidden' NAME='_nouser'>
|
|
_noverify |
Override verifying any/all fields contain data in
the transaction record. By default, all field names in every transaction
record are required to contain information other than white-space,
provided that the field names are actually passed by the client's
browser. The _noverify option cancels this feature. This option
is not recommended if the data (<filename>.data) or log files
(<filename>.upload for uploads) will be used in spreadsheet
or database applications.
<INPUT TYPE='hidden' NAME='_noverify'>
|
|
_nowarn |
Override sending an e-mail notification warning
of a critical error. By default, all critical error messages are
copied as e-mail messages and sent to the owner of the host location.
The _nowarn option cancels sending an e-mail message warning of
the error.
<INPUT TYPE='hidden' NAME='_nowarn'>
|
|
_onsubmit |
Enable a specific default submit option when none is
selected by the client. The VALUE attribute must be one of the submit
NAME options defined in the request form.
<INPUT TYPE='hidden'
NAME='_onsubmit' VALUE='defaultsubmitname'> |
|
_password |
Restrict who may submit the form by a username
and a password. Must be used in conjunction with the _username option.
Information cannot be submitted without the client providing a username
and password for verification with those stored in '<filename>.passwd'.
To specify a username and password for access verification, the
form should include the following additional tags.
<INPUT TYPE='text' NAME='_username'>
<INPUT TYPE='password' NAME='_password'>
The access file '<filename>.passwd' may be in either the
same directory as the HTML request form that uses the access file
or in the modifying <subdirectory> location. Usernames and
their passwords are delimited by a ':' character in the access file,
as shown in the following example for three different clients.
username1:password1
username2:password2
username3:password3
|
|
_public |
Allow subsequent download by the public (anyone) of a file previously
uploaded by the script. Must be used in conjunction with the _upload
and _source options. By default, file uploads are treated as private
transactions, where the file can only be accessed by the owner of
the host location. The _public option enables anyone to access the
file with a web browser.
<INPUT TYPE='hidden' NAME='_public'>
|
|
_query |
Enable the client to write a query to search in
a database. Must be used with the '_search' option.
<INPUT TYPE='text' NAME='_query'>
<INPUT TYPE='submit' NAME='_search' VALUE='...'>
|
|
_redirect |
Activate redirection to the location selected in
the drop-down menu. Must be used with the '_url' option.
<SELECT NAME='_url' ...>
<OPTION VALUE='http://...'>...</OPTION>
<OPTION VALUE='http://...'>...</OPTION>
<OPTION VALUE='http://...'>...</OPTION>
</SELECT>
<INPUT TYPE='submit' NAME='_redirect' VALUE='...'>
|
|
_replace |
Allow replacing an existing file by the same name at the host location.
Must be used in conjunction with the _upload and _source options.
To prevent accidental loss of files associated with the form, the
<subdirectory> option must be also be specified. The _replace
option will not allow any of the following filenames to be overwritten.
<subdirectory><filename>.data
<subdirectory><filename>.html
<subdirectory><filename>.passwd
<subdirectory><filename>.redirect
<subdirectory><filename>.shtml
<subdirectory><filename>.upload
By default, file uploads are treated as private transactions, which
prevents anyone from uploading a file that already exists by the
same name at the host location. The _replace option enables anyone
to overwrite an existing file at the host location with another
file by the same name.
<INPUT TYPE='hidden' NAME='_replace'>
|
|
_search |
Activate the search option. Must be used with the
'_query' option.
<INPUT TYPE='text' NAME='_query'>
<INPUT TYPE='submit' NAME='_search' VALUE='...'>
|
|
_source |
Enable selecting an upload or file attachment. Must
be used with the '_upload' option.
<INPUT TYPE='file' NAME='_source'>
<INPUT TYPE='submit' NAME='_upload' VALUE='...'>
|
|
_subject |
Specify a custom subject in an e-mail notification message. By
default, all saved transaction records are copied and sent to the
owner of the host location. The message will have a subject of '<filename>.data
@ ' followed by the address for the location of the database file
(e.g., table.data @ http://www.eiu.edu/itshelp/survey/). With the
_upload option the message will use a default subject of the uploaded
file name followed by the address for the location of the uploaded
file (e.g., table.xls @ http://www.eiu.edu/itshelp/survey/). The
_subject option allows for a custom subject to be defined in the
VALUE attribute.
<INPUT TYPE='hidden' NAME='_subject' VALUE='Owner-Defined
Subject...'>
|
|
_submit |
Enable the default submit action for a request form.
Only useful when a single request form uses multiple submit options,
for example, the '_redirect' or '_search' or '_upload' options.
<INPUT TYPE='submit' NAME='_submit' VALUE='...'>
|
|
_subst |
Substitute a custom page '<filename>.html' for the response
file. By default, a saved transaction record is displayed to the
client in a fixed format. The _subst option allows for a custom
response that can be further tailored with specific values of the
transaction record. The _subst option may not be used in conjunction
with the _confirm option.
<INPUT TYPE='hidden' NAME='_subst'>
Within a custom response file, the following substitution tag may
be used to automatically and dynamically insert values from the
current transaction record
<!--META NAME-->
Substitution tags, where NAME corresponds to the case-sensitive
field NAME attribute used in the request form, are replaced with
corresponding VALUE attributes from the current transaction record.
If the substitution tags are located within an HTML tag, the second
and equivalent entity form of the substitution tag should be used.
By default, the following case-sensitive NAME values are also available
for use in a custom response page.
NAME |
DESCRIPTION
|
_date |
the date-time stamp of the transaction. |
_host |
the host location web address (only with the
_upload option). |
_query |
the query submitted by the client (only with
the _search option). |
_size |
the file size in bytes (only with the _upload
option). |
_source |
the file name selected by the client (only
with the _upload option). |
_target |
the file name used at the host location (only
with the _upload option). |
_url |
the address selected by the client (only with
the _redirect option). |
_user |
the remote host (address) of the client. |
_username |
the client username (only with the _username
option). |
|
|
_upload |
Activate the upload feature. Must be used with the
'_source' option.
<INPUT TYPE='file' NAME='_source'>
<INPUT TYPE='submit' NAME='_upload' VALUE='...'>
|
|
_url |
Enable a drop-down menu of host (URL) locations.
Must be used with the '_redirect' option.
<SELECT NAME='_url' ...>
<OPTION VALUE='http://...'>...</OPTION>
<OPTION VALUE='http://...'>...</OPTION>
<OPTION VALUE='http://...'>...</OPTION>
</SELECT>
<INPUT TYPE='submit' NAME='_redirect' VALUE='...'>
|
|
_username |
Restrict who may submit the form by a username and
a password. Must be used in conjunction with the _password option.
Information cannot be submitted without the client providing a username
and password for verification with those stored in '<filename>.passwd'.
To specify a username and password for access verification, the
form should include the following additional tags.
<INPUT TYPE='text' NAME='_username'>
<INPUT TYPE='password' NAME='_password'>
The access file '<filename>.passwd' may be in either the
same directory as the HTML request form that uses the access file
or in the modifying <subdirectory> location. Usernames and
their passwords are delimited by a ':' character in the access file,
as shown in the following example for three different clients.
username1:password1
username2:password2
username3:password3
|
|
_verify |
Verify (require) only specific field names contain
information before saving a transaction record. By default, all
field names in every transaction record are required to contain
information other than white-space, provided that the field names
are actually passed by the client's browser. The _verify option
allows for a custom verification of only those field names specified
in the VALUE attribute. Field names in the VALUE attribute are case-sensitive
and must be separated by a : character as the delimiter.
<INPUT TYPE='hidden' NAME='_verify' VALUE='NAME1 : NAME2
: NAME3'>
|
USAGE The default settings of the script perform the following operations.
All transaction records are written to either a database (<filename>.data)
or log file (<filename>.upload for uploads) depending on whether
the '_upload' option was requested in the form. The fields of the transaction
record are placed in alphanumeric (ASCII) order and stored in tab-deliminated
fields in the following format.
NAME1=VALUE1<TAB>NAME2=VALUE2<TAB>NAME3=VALUE3<EOL>
UPLOAD ATTACHMENT To allow only known clients to transfer files to a 'private' <subdirectory>
at your current host account location, create a form with the following
information. Please note the case of the letters in the values for the
<...ACTION='/cgi-bin/access'> and <INPUT TYPE='...'> tags.
<FORM METHOD='POST' ACTION='/cgi-bin/access?private/attach'
ENCTYPE='multipart/form-data'>
<INPUT TYPE='hidden' NAME='_alias' VALUE='itsus@www.eiu.edu'>
<INPUT TYPE='file' NAME='_source'>
<TEXTAREA NAME='comment' cols="25" rows="5">Comments...</TEXTAREA>
<INPUT TYPE='text' NAME='_username'> Username
<INPUT TYPE='password' NAME='_password'> Password
<INPUT TYPE='submit' NAME='_upload' VALUE='UPLOAD'>
</FORM>
The Browse... button, which allows a user to select an existing file
at their local computer, indicates that the upload feature is available
on the client's browser. The _username and _password options determine
who may transfer files to the host location. These options do not restrict
web access to the files located in the private subdirectory. Permission
for a client to upload files will be verified from entries in the 'attach.passwd'
file, which could be located in the current host location or in it's private
subdirectory. Any uploaded files will be saved in the 'private' subdirectory
of the current host location because of the <subdirectory> option
in the ACTION part of form. A copy of each successful transaction will
mailed to the address specified by the option. The 'attach' <filename>
option in the ACTION part of the form also indicates that, after a file
has been successfully uploaded, a record of the transaction (including
the Comments... section) will be stored in the 'attach.upload' file located
in the private subdirectory. REDIRECTION To create a drop-down menu that provides links, for example, to various
state universities, create a form with the '_redirect' option and the
following information. Please note the case of the letters in the values
for the <...ACTION='/cgi-bin/access'>, the <SELECT NAME='_url'
...>, and the <INPUT TYPE='submit' NAME='_redirect' ...> tags.
<FORM METHOD='POST' ACTION='/cgi-bin/access'>
<INPUT TYPE='hidden' NAME='_nomail'>
<INPUT TYPE='hidden' NAME='_nosave'>
<INPUT TYPE='hidden' NAME='_redirect'>
<SELECT NAME='_url' SIZE='1' onChange='submit()'>
<OPTION SELECTED VALUE='http://www.eiu.edu/'>Eastern Illinois
University</OPTION>
<OPTION VALUE='http://www.ilstu.edu/'>Illinois State University</OPTION>
<OPTION VALUE='http://www.niu.edu/'>Northern Illinois University</OPTION>
<OPTION VALUE='http://www.siu.edu/'>Southern Illinois University</OPTION>
<OPTION VALUE='http://www.uic.edu/'>University of Illinois (UIC)</OPTION>
<OPTION VALUE='http://www.uis.edu/'>University of Illinois (UIS)</OPTION>
<OPTION VALUE='http://www.uiuc.edu/'>University of Illinois (UIUC)</OPTION>
<OPTION VALUE='http://www.wiu.edu/'>Western Illinois University</OPTION>
</SELECT>
<INPUT TYPE='submit' NAME='_redirect' VALUE='Go'>
</FORM>
The _nomail and _nosave options suppress all record and notification
of the form's use. Without the _nosave option, a detailed log of the usage
would be stored in a '.redirect' file at the host location. Note that
even without a <filename> option, a data file will still be created
and appended. The onChange='submit()' attribute in the <SELECT...>
tag is an option that uses JavaScript to automatically submit the form
when the value in the menu is changed. The JavaScript enhancement requires
the following additional hidden tag to ensure proper execution of the
script.
<INPUT TYPE='hidden' NAME='_redirect'>
Additional working examples of these features and more are listed in
the SEE ALSO section of this documentation. FILES A database file will be created by default with a name of '<filename>.data'
in the same directory as the HTML page that presents the request form
(the current host location). Similarly, the '_upload' option will create
by default a log file with a name of '<filename>.upload' in the
current host location. In either case, the first record in a newly-created
file will contain the form's field NAME attributes, unless either the
'_noverify' or the '_name' options are specified in the form. All field
NAME attributes in these two files are stored in alphanumeric (ASCII)
order. To store the file in an existing subdirectory from the current
host location, specify the <subdirectory> option in the ACTION part
of the form. Any specified <subdirectory> option will always begin
without a slash (/) and will always end with a slash (/). A password access
file named '<filename>.passwd' or a custom response page named '<filename>.html'
may be located in either the <subdirectory> or the current host
location. In all cases, <filename> is the same filename specified
in the ACTION part of the form. SEE ALSO
CGI Suite (Collection of General Purpose Scripts)
Accounts @ Virtual Course
Environment
Contact Us @ Virtual Course
Environment
DIAGNOSTICS access was developed to handle all types of user-, owner-, and server-related
errors. The script will send back to the client various well-behaved error
messages that will diagnose problems in creating the application form.
WARNINGS Permissions to the '<filename>.data' database file, the '<filename>.upload'
upload log file, and the '<filename>.passwd' file are set to 600
to only allow read/write accessibility by the owner of the account. Permissions
to any uploaded files are also set to 600 to only allow for read/write
accessibility by the owner of the account, unless modified by the '_public'
option, which sets permissions of 604 to allow for the subsequent downloading
of files to a client's web browser. NOTES access has been tested without problem on Windows NT Workstations with
Netscape Communicator 4.x and Microsoft Internet Explorer 3.x web browsers.
Older versions of these and other browsers that do not support JavaScript
and Cascading Style Sheets will not display the response messages and
documentation as fully designed. This browser limitation, however, has
no effect on the function of the script. BUGS There are no known bugs in the current version. AUTHOR Gerald Charles Wagner. Version 2.0 (Release January 2000). |
