\RequirePackage[use=usebw]{spdef}
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage{graphicx,longtable,array}
%\usepackage[dvipsone,designvi,tight]{web}  % dvipsone, dvips, pdftex, dvipdfm
\usepackage[designv,latextoc,forcolorpaper,centertitlepage]{web}
\usepackage[nodljs,execJS]{exerquiz} %,preview
\usepackage[altbullet]{lucidbry}
\usepackage{pifont}
\usepackage{fancyvrb}
%\usepackage{calc}

\usepackage[active]{srcltx}

%\setlongtables
\def\AEBBook{\textsl{{Acro\!\TeX} eDucation System Tools: {\LaTeX} for interactive PDF documents}}

\hyphenation{Java-Script}

\def\AcroT{Acro\!\TeX}\def\cAcroT{{\textcolor{blue}{\AcroT}}}
\def\AcroEB{\AcroT{} eDucation Bundle}\def\cAcroEB{\textcolor{blue}{\AcroEB}}
\def\AcroB{\AcroT{} Bundle}\def\cAcroB{\textcolor{blue}{\AcroB}}
\def\bUrl{http://www.math.uakron.edu/~dpstory}

% Colors
\ifusebw
\universityColor{black}
\sectionColor{black}
\quesNumColor{black}
\tocColor{black}
\fi

\makeatletter
\ifusebw
\def\@linkcolor{black}
\def\@citecolor{black}
\def\@filecolor{black}
\def\@urlcolor{black}
\fi
\let\bslash=\@backslashchar
%\renewcommand{\paragraph}{\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
    {\normalfont\normalsize\bfseries}}
\renewcommand{\subparagraph}
    {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}%
    {\normalfont\normalsize\bfseries}}
\def\FitItIn{\eq@fititin}
\def\endredpoint{\FitItIn{{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleleft$}}}
\def\chgCurrLblName#1{\def\@currentlabelname{#1}}
\makeatother

\hypersetup{linktocpage}

\def\cs#1{\texttt{\bslash#1}}
\newcommand\redpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
\vskip\medskipamount\noindent
  \makebox[\parindent][l]{\large\ifusebw\color{black}\else\color{red}\fi$\blacktriangleright$}}
\newcommand\handpoint{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
\vskip\medskipamount\noindent
  \makebox[\parindent][l]{\large\ifusebw\color{black}\else\color{blue}\fi\ding{042}}}

\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$}
\def\meta#1{\textit{\texttt{#1}}}
\let\pkg\textsf
\let\env\texttt
\let\opt\texttt
\let\app\textsf
\def\AEB{\textsf{AeB}}
\def\AcroTeX{Acro\!\TeX}
\def\HTML{HTML}\def\FDF{FDF}
\def\PDF{PDF}\def\URL{URL}
\let\amtIndent\leftmargini
\def\bNH{\begin{NoHyper}}\def\eNH{\end{NoHyper}}
\def\nhnameref#1{\bNH\nameref{#1}\eNH}
\def\nhNameref#1{\bNH\Nameref{#1}\eNH}
\def\nhurl#1{\bNH\url{#1}\eNH}
\def\grayV#1{\textcolor{gray}{#1}}
\def\darg#1{\{#1\}}
\def\parboxValign{t}
\renewcommand*{\backrefalt}[4]{%
    See page\ifcase #1\or
       ~#2.\else s~#2.\fi
}
\newenvironment{aebQuote}
   {\list{}{\leftmargin\amtIndent}%
    \item\relax}{\endlist}
\newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{%
    \raisebox{.5\baselineskip+#1}{%
    \expandafter\parbox\expandafter[\parboxValign]%
        {\marginparwidth}{\aebbkFmtMp#2}}}}
\def\aebbkFmtMp{\kern0pt\itshape\small
    \ifusebw\color{gray}\else\color{blue}\fi
    \raggedleft\hspace{0pt}}
\def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

\title{\texorpdfstring{Acro\!\TeX}{AcroTeX} eDucation Bundle\texorpdfstring{\\}{: }
    The \texorpdfstring{\pkg{eq2db}}{eq2db} Package}
\author{D. P. Story}
\subject{Manual of Usage for eq2db Distribution}
\keywords{AcroTeX, LaTeX, PDF, ASP, Database, Email, quizzes}

\university{{\AcroT} Software Development Team}
%\university{THE UNIVERSITY OF AKRON\\
%   Theoretical and Applied Mathematics}
\email{dpstory@acrotex.net}
\version{2.0}
\copyrightyears{1999-\the\year}

% \def\OpenToHere{\OpenAction{\JS{this.gotoNamedDest("Here")}}}
% \def\OpenHere{\hypertarget{Here}{\strut}}\OpenToHere

\reversemarginpar

\makeatletter
\let\web@copyright\@gobble
\let\web@revision\@gobble
\renewcommand\webdirectory
{%
    \par\ifeqforpaper\else\minimumskip\fi\vspace{\stretch{1}}%
    \begin{flushleft}\textbf{\large\web@directory}%
    \vspace{-3pt}
    \begin{itemize}\setlength{\itemsep}{-3pt}%
        \bfseries
        \item \leavevmode\hyperlink{webtoc}{\web@toc}%
        \item Begin \hyperlink{\web@Start.1}{Documentation}
        \item \href{aeb_man.pdf}{\AcroEB}
        \item \textsf{\href{eformman.pdf}{eForm}} Support
    \end{itemize}
    \end{flushleft}
}
\def\maketitle@trailer@ul{\web@copyright\ \copyright\ \webcopyrightyears\ \webversion}
\def\maketitle@trailer@ll{\web@revision\ \@date}
\def\maketitle@trailer@ur{\url{http://www.acrotex.net}}
\def\maketitle@trailer@lr{\href{mailto:\webemail}{\webemail}}

%\renewcommand\titlepageTrailer
%{%
%    \web@copyright\ \copyright\ \webcopyrightyears\ \webversion
%        \hfill\url{http://www.acrotex.net}\\
%    \web@revision\ \@date \hfill\href{mailto:\webemail}{\webemail}
%}
\makeatother

\newcounter{exampleno}
\def\theexampleno{\arabic{exampleno}}
\newcommand\Example{\refstepcounter{exampleno}%
\paragraph*{Example.}}

\begin{execJS}{execjs}
aebTrustedFunctions(this, aebAddWatermarkFromFile, {
    bOnTop: false,
    cDIPath: "C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf"
})
aebTrustedFunctions(this, aebSaveAs, "Save")
\end{execJS}


\begin{document}

\maketitle\tableofcontents

\section{Introduction}

\emph{Short Summary:} Converts a self-contained \pkg{exerquiz} \env{quiz} to one that is
submitted to a server-side script.\endredpoint

\medskip
The \pkg{eq2eb} package is meant to be used with the \pkg{exerquiz} package,
one of the components of the \textbf{{Acro\!\TeX} eDucation Bundle}
(\texttt{ctan.org/pkg/acrotex}). The package redefines the `End Quiz' button
(of the \env{quiz} environment) appropriately so that when the user clicks
the `End Quiz' control, the results of the quiz are sent to a server-side
script. The \pkg{eq2db} Package has six options:
\begin{questions}
\item \texttt{\hyperref[eqRecordOption]{eqRecord}}: Save quiz data
    to a database, such as Microsoft Access. (Supported for FDF submission.)
\item \texttt{\hyperref[eqEmailOption]{eqEmail}}: Email quiz data
    to the instructor. (Supported for FDF and HTML submission.)
\item \texttt{\hyperref[eqTextOption]{eqText}}: Save quiz data
    to a tab-delimited text file. Can then be opened and analyzed
    using Microsoft Excel. (Supported for FDF and HTML submission.)
\item \texttt{\hyperref[customOption]{custom}}: A hook for developers
    to use \texttt{eq2db} with their own script.
\item \texttt{\hyperref[taggedOption]{tagged}}: Write quiz data in an XML-like
    data stream.
\item \texttt{submitAs=\meta{\upshape FDF|HTML|XML}}: (new in v2.0) The
    \texttt{submitAs} option allows the document author to submit as FDF,
    HTML, or XML. The scripts provided by this package are designed FDF
    submittal and HTML submittal. Scripts for an XML submittal type are left
    as an exercise.

    With regard to HTML submission, read Section~\ref{s:IntroHTMLSub} below.
\end{questions}

For FDF submittal, accompanying each of the first three options listed above
is a server-side script. These are ASP pages written with \app{VBScript}.
A \app{Windows} server running Microsoft IIS is required; Adobe \textsl{FDF Toolkit}
is also required to be installed on the server.

\subsection{Introduction to HTML submission}\label{s:IntroHTMLSub}

My upcoming book (if it ever comes), \AEBBook~\cite{book:AEBB}, has a rather extensive chapter
titled ``Server-side Scripting and the \pkg{eq2db} Package.'' In the course
of writing that chapter, I decided to throw in the towel on the \textsl{FDF
Toolkit}, the mainstay for FDF submission, and to look at HTML submission.
Yes, PDF form data can be submitted as HTML form data. As result, I wrote a
number of scripts for general purpose PDF form documents and for quiz
documents (see Tables~\ref{table:QuizScripts1} and~\ref{table:QuizScripts2});
identical functioning scripts were written for the \app{Windows}
server-platform using \app{ASP} and \app{VBScript} and for the \app{Linux}
server-platform using \app{PHP}.

\paragraph*{{\AEB} demonstration websites.}\label{para:SSDemoPages}\leavevmode
These two websites were created to illustrate server-side concepts and examples brought up
in the book. The links on these pages demonstrate the two sets of scripts
listed in Tables~\ref{table:QuizScripts1} and~\ref{table:QuizScripts2}, and much more.
\begin{quote}
\nhurl{http://faculty.nwfsc.edu/web/math/storyd/dps/}
\end{quote}
The above Web page is on a \app{Windows} server hosted by Northwest Florida State
College (NWFSC). The server-side
script is written as ASP pages using VBScript.
\begin{quote}
\nhurl{http://www.acrotex.net/dps/}
\end{quote}
This Web page is on a \app{Linux} server hosted by {\AcroTeX.Net}. The
server-side script is written with PHP.

A parallel development of all scripts is maintained for these two server
platforms. You are invited to navigate your Web browser to each of these
{\URL}s and experience forms submission from a {\PDF} document.


\section{The Distribution and Requirements}

The \pkg{eq2db} Package is distributed with the following files:
\begin{questions}
    \item \texttt{eq2dbman.pdf}: This document, the documentation for
        the {\LaTeX} package \pkg{eq2db} and its related files.
    \item \texttt{eq2db.dtx} and \texttt{eq2db.ins}: The {\LaTeX} package
        with its installation file.
    \item \textsf{eqRecord.asp}: An \textsf{ASP} script for saving \pkg{exerquiz}
        quizzes to a data\-base.
    \item \textsf{eqEmail.asp}: An \textsf{ASP} script for forwarding \pkg{exerquiz}
        quizzes via e-mail.
    \item \textsf{eqText.asp}: An \textsf{ASP} script for saving \pkg{exerquiz}
        quizzes to a tab-delimited file.
    \item \texttt{quiz1.tex}, \texttt{quiz2.tex}, \texttt{quiz3.tex},
        \texttt{quiz4.tex} (quizzes~1 and~2 demo use the \texttt{eqRecord}
        option; \texttt{quiz3} demos \texttt{eqEmail}, and \texttt{quiz4}
        demos \texttt{eqText}.)
    \item \texttt{eqQuiz.mdb}: A Microsoft Access 2000 database is used
        with the demostration files \texttt{quiz1.tex} and \texttt{quiz2.tex}.
\end{questions}

The \pkg{eq2db} package requires the \pkg{exerquiz} package to create online
quizzes and to create supporting buttons and text fields. The \pkg{exerquiz}
package, in turn, assumes a number of packages; a listing of these can be
found in the documentation for the \AcroEB.

\section{The \texttt{eqRecord} option}\label{eqRecordOption}

In this section we describe how to create an online quiz that is to be
submitted to the server-side script \app{eqRecord.asp}\footnote{The script
\textsf{eqRecord.asp} comes with absolutely \emph{no guarantees}. Extensive
testing should be made on your own system to assure yourself script is
reliable enough to use in practice.  Feel free to modify the script to suite
your needs.}. For this option, quiz results are saved to a database. The
\opt{eqRecord} option and its corresponding script \app{eqRecord.asp} require
that Adobe's \textsf{FDF Toolkit} is installed on
your \app{Windows} server\FmtMP[\baselineskip]{FDF Toolkit required}.

\redpoint \texttt{quiz1.tex} and \texttt{quiz2.tex} are the demo
files for this option.

\paragraph*{In the preamble.}
The steps to create a quiz to be submitted to
\textsf{eqRecord} are simple enough. First, the preamble of your
document should look something like this:
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()]
\documentclass{article}
\usepackage[designi]{web}
\usepackage{exerquiz}
\usepackage[eqRecord!grayV(,tagged)]{eq2db}
\end{Verbatim}
You may have other packages loaded, as well as other options for \pkg{web}
and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in
the following sense: If the \pkg{eq2db} package is not loaded, then an
\pkg{exerquiz} \env{quiz} is self-contained, that is, it is not submitted to
a server-side script; if \pkg{eq2db} package is loaded, then the quizzes are
submitted to a server-side script. The \opt{tagged} option may be optionally
included in the option list of \pkg{eq2db}, shown in gray.

\paragraph*{In the body.} Next, you write your \pkg{exerquiz} \env{quiz}:
\begin{equation}
\begin{minipage}{336pt}
\begin{Verbatim}[fontsize=\small]
\eqSubmit{http://www.example.edu/scripts/eqRecord.asp\#FDF}
    {QuizIt}{Math101}
\begin{quiz*}{Quiz1}
Answer each of the following. Passing is 100\%.
\begin{questions}
\item ...
...
\item ...
\end{questions}
\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
\end{Verbatim}
\end{minipage}\label{display:BodyEqRec}
\end{equation}
Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz},
it takes three parameters.
\begin{equation}
\begin{minipage}{225pt}
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\eqSubmit{!meta(submitURL)}{!meta(dbName)}{!meta(dbTable)}
\end{Verbatim}
\end{minipage}\label{display:SubmitRec}
\end{equation}

\subparagraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential
information use by the server-side scripts. The parameters of \cs{eqSubmit}
are briefly described.
\begin{aebQuote}\rightskip0pt
\begin{description}\def\NH{\relax\hspace*{-\labelsep}}%
\item\NH\meta{submitURL} is the {\URL} to the script \texttt{eqRecord.asp\#FDF}.
    Internally, the value of this parameter is saved in the text macro
    \cs{eq@CGI}. Note that the name of the script \texttt{eqRecord.asp} has
    \texttt{\#FDF} appended (the hash mark `\texttt{\#}' followed by the fragment
    identifier {\FDF}\index{fragment identifier (FDF)@fragment identifier (FDF)}).

\item\NH\meta{dbName} is the name of the database to use. My examples use
    ODBC, with \texttt{QuizIt} as the DSN (data source name).

\item\NH\meta{dbTable} is the name of the
table into which the data record is to be inserted (this is \texttt{Math101}
in the example above).
\end{description}
\end{aebQuote}
The three arguments of the command \cs{eqSubmit} are used to define the
values of \cs{db@Name}, \cs{db@Table} and \cs{eq@CGI}, respectively, the
values of which are used to populate the hidden fields.

Assuming \textsf{eqRecord.asp} is installed on your web server, and the
\textsl{FDF Toolkit} has also been installed (see Section~\ref{settingup}),
we are ready to submit the quiz.

\subsection{Field Values Processed by \textsf{eqRecord.asp}}\label{eqRfieldvalues}

The \textsf{eqRecord} script processes two classes of field data: certain
``\hyperref[hardwired]{hard-wired}'' field data; and field data having a
\hyperref[hierarchalfields]{hierarchal} name with a root of either
\anglemeta{dbName} or \texttt{IdInfo}, e.g., \texttt{Quiz1.numQuestions} or
\texttt{IdInfo.Name.Last}. Details of each of these follow.

\subsubsection{``Hard-wired'' Fields}\label{hardwired}

When you compile your source document using the package
\pkg{eq2db} with the \texttt{eqRecord} option, the package
creates three hidden text fields, with field titles of
\texttt{dbName}, \texttt{dbTable} and \texttt{quizName}. These
hidden fields are created under the `End Quiz' button. At submit time,
these fields are populated and submitted. Below is an enumerated list
of these three fields with a brief description of each:
\begin{enumerate}
    \item \texttt{dbName}: The name of the database to which the
        data is to be saved. (I've been using ODBC to reference the database.)
    \item \texttt{dbTable}: The name of the table within \texttt{dbName} where the data
          is to be stored.
    \item \texttt{quizName}: The name of the quiz or test. Name would uniquely characterize
          the quiz/test the student has taken.
\end{enumerate}
The first two hidden fields are populated by the second and third arguments,
respectively, of \cs{eqSubmit}, as defined in
display~\eqref{display:SubmitRec}. The third piece of data,
\texttt{quizName}, is obtained from the first required argument of the
\env{quiz} environment. See the skeleton example in
display~\eqref{display:BodyEqRec}, there you'll see
\verb~\begin{quiz*}{Math101}~. The argument `\texttt{Math101}' is the quiz
name and is passed to the server-side script as the value of the
\texttt{quizName} hidden text field.


\subsubsection{Fields with Hierarchal Names}\label{hierarchalfields}

Other than the fields described in \nameref{hardwired}, \textsf{eqRecord.asp} processes
only fields with hierarchal names that have a root name of \anglemeta{quizName}
(see \nhnameref{hardwired} on page~\pageref{hardwired}) or a root name of \texttt{IdInfo}.

\paragraph*{\texttt{quizName} (\cs{currQuiz}):} \texttt{quizName} is the field title of one of the hidden fields,
its value is picked up as the first argument of the \env{quiz}
environment; the value is stored in the text macro \cs{currQuiz}.

In addition to the ``hard-wired'' hidden fields described earlier, there are actually three
more hidden fields (under the `End Quiz' button) with root name \anglemeta{quizName}. These are
\begin{itemize}
    \item \cs{currQuiz.numQuestions}: The number of questions in the quiz
    \item \cs{currQuiz.numCorrect}: The number of correct questions
    \item \cs{currQuiz.Responses}: a list of all the responses of the user
\end{itemize}
The values of these fields are also sent to \textsf{eqRecord.asp}.
There is a mechanism for creating more hidden fields the values of
which are sent to the script. The technique for doing this will be
discussed later.

\paragraph*{\texttt{IdInfo}:}\chgCurrLblName{IdInfo}\label{para:IdInfo}  As mentioned earlier, \textsf{eqRecord.asp} processes fields
that use a hierarchal naming convention, with root name of \anglemeta{quizName} or \texttt{IdInfo}.
Fields whose root name is \texttt{IdInfo} are meant to hold information about the person
taking the quiz: first name, last name, student number, etc.

For example, you can create fields the user fills in for
self-identifi\-cation. In the preamble, you can define new commands:
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
% User's First Name
\newcommand\FirstName[2]{\textField{IdInfo.Name.First}{#1}{#2}}

% User's Last Name
\newcommand\LastName[2]{\textField{IdInfo.Name.Last}{#1}{#2}}

% User's SSN
\newcommand\SSN[2]{\textField[\MaxLen{11}
    \AA{\AAKeystroke{AFSpecial_Keystroke(3);}
        \AAFormat{AFSpecial_Format(3);}
    }]{IdInfo.SSN}{#1}{#2}}
\end{Verbatim}
\noindent Note that I've defined these fields so that their names
follow a hierarchal name structure, with a root of
\texttt{IdInfo}.  The two required arguments are the dimensions of
the text field being constructed. For example,
\verb+\FirstName{100bp}{10bp}+ creates a text field with a title of
\texttt{IdInfo.Name.First} which is \texttt{100bp} wide and \texttt{10bp} high.

\redpoint See the demo file \texttt{quiz1.tex} for examples.

\medskip\noindent
Additional \texttt{IdInfo} fields can be constructed.

\subsection{Mapping PDF Field Names onto DB Field Names}\label{mappdf2db}

\textsf{eqRecord.asp} is a quasi-general script for mapping the values of PDF fields
into corresponding fields in a database. The way \textsf{eqRecord} is set up, the
DB field name is derived from the PDF field name. For example, the value of the PDF field
\texttt{Quiz1.numQuestions} is stored in the DB under the DB field name of \texttt{numQuestions}.

For field names such as \texttt{IdInfo.Name.Last}, we can't map
this into the DB field name \texttt{Name.Last} because for some
databases (notably, Microsoft Access) database field names
containing a `dot' are not legal.  As a work around,
\textsf{eqRecord.asp} strips all dots from the field name, and
replaces them with the value of the VB Script variable
\texttt{dotReplace}. The definition of \texttt{dotReplace} in \textsf{eqRecord.asp} is
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
Dim dotReplace : dotReplace = "_"
\end{Verbatim}
\noindent That is, a `dot'(\texttt.) is replaced by an `underscore' (\texttt\_).

\medskip\noindent
The table below illustrates the mapping of PDF field name onto database field
names. Suppose the \texttt{quizName} is \texttt{Quiz1}:

\medskip
\begin{longtable}{>{\ttfamily}l>{\ttfamily}ll}
\multicolumn1{>{\bfseries}l}{PDF Field Name}&\multicolumn1{>{\bfseries}l}{DB Field Name}&\multicolumn1{>{\bfseries}l}{Required}\\\hline\endfirsthead
\multicolumn1{>{\bfseries}l}{PDF Field Name}&\multicolumn1{>{\bfseries}l}{DB Field Name}&\multicolumn1{>{\bfseries}l}{Required}\\\hline\endhead
quizName (e.g.,\,Quiz1) & quizName & Yes\\
Quiz1.numQuestions & numQuestions & Yes\\
Quiz1.numCorrect & numCorrect & Yes\\
Quiz1.Responses  & Responses & Yes\\
IdInfo.Name.Last & Name\_Last& No\\
IdInfo.Name.First& Name\_First & No\\
IdInfo.SSN & SSN & No\\
\multicolumn1l{N/A} & TimeOfQuiz & Yes\\
\end{longtable}
\noindent The last entry needs comment: \textsf{eqRecord.asp} generates a time stamp when a quiz is processed. This time stamp
is stored in a field with a name of \texttt{TimeOfQuiz}.  This is a required field in your database.


\subsection{Adding more Hidden Fields}\label{moreHiddenFields}

When you add fields with a hierarchal name with a root of
\cs{currQuiz} or \texttt{IdInfo}---whether hidden or
not---the values of these fields will be submitted and processed
by \textsf{eqRecord.asp}. When you add fields in your document,
there should be a corresponding DB field to receive this data
(see Section~\ref{mappdf2db} for naming conventions). You can also
add hidden fields to transmit information about the quiz that the
user does not need to see.

\Example Suppose you have a point value to each question and want to report
the point score (rather than the number missed).  In this case, you would use
the \cs{PointsField} field instead of the \cs{ScoreField} (though you could
use both).

\cs{PointsField} has a hierarchal name, but its root
does not begin with \cs{currQuiz}; consequently, the value
of this field is not submitted to \textsf{eqRecord.asp}. (The
value of this field is a string what is meant to be read by the
user; it reads, for example, ``Score: 16 out of 20''; we don't
want this string submitted anyway, we would want the point score
(16) and the total points (20) submitted.) We want to transmit the
points scored and the total number of points to the server-side
script.

The \pkg{eq2db} package defines two helper commands for
creating hidden fields (these hidden fields are hidden under the
`End Quiz' button); these are \cs{addHiddenField} and
\cs{populate\-HiddenField}.

Suppose we had a quiz, \texttt{Quiz1}, in which we wanted to
report points scored and total points.  First, we need to add two
hidden fields, we'll call them \texttt{Quiz1.ptScore} and
\texttt{Quiz1.nPointTotal}; we create the hidden fields using
\cs{addHiddenField}:
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\addHiddenTextField{Quiz1.ptScore}{}
\addHiddenTextField{Quiz1.nPointTotal}{\theeqpointvalue}
\end{Verbatim}
\noindent The first parameter is the title (name) of the field,
the second parameter is the default value.  For the first line, no
default value is given; for the second line, a default value of
\cs{theeqpointvalue} is given.  The counter \cs{eqpointvalue}
contains the total number of points for the quiz so we can insert
that value at \texttt{latex} compile-time.

The value of the first field added, \texttt{Quiz1.ptScore}, is not
known until a user takes a quiz and submits results. The \pkg{eq2db} command
\cs{populateHiddenField} inserts the necessary
JavaScript that would populate the specified field. For example,
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\populateHiddenField{Quiz1.ptScore}{ptScore}
\end{Verbatim}
The first parameter is the field name, the second is the value the field
is to hold when the user clicks on `End Quiz'. The command
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\populateHiddenField{fieldname}{fieldvalue}
\end{Verbatim}
expands to,
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
this.getField("fieldname").value = fieldvalue;
\end{Verbatim}
which is the JavaScript for populating the field,
is inserted into the code just prior to the submission of the
data.

\redpoint
See second quiz in the sample file \texttt{quiz1.tex} for
a complete example of creating a quiz with weight set for each
question, and for reporting the point score and total points.
\endredpoint

\medskip\noindent The table below lists some variables (both \LaTeX{} and
JavaScript) that might be useful in extracting desired information from
quiz for submittal.

\begin{longtable}{>{\ttfamily}l>{\PBS\raggedright}p{.55\linewidth}}
\multicolumn1{>{\bfseries}l}{Variable}&\multicolumn1{>{\bfseries}l}{Description}\\\hline\endfirsthead
\multicolumn1{>{\bfseries}l}{Variable}&\multicolumn1{>{\bfseries}l}{Description}\\\hline\endhead
Score & Score of the user with one point per problem. This value is always reported in the hidden text field
\texttt{quizName.numCorrect}. This is a JavaScript variable known when the user finishes the quiz.
This value is always reported in \texttt{quizName.numQuestions}, the hidden text field.\\
\cs{thequestionno} & The number of questions in the current quiz. A \LaTeX{} macro; known at compile-time.\\
Responses & A comma-delimited list of all responses of the user. A JavaScript variable known when
the user finishes the quiz.  Always reported in the hidden field
\texttt{quizName.Responses}\\
ptScore  & The point score of the user's quiz. A JavaScript variable, known when the user finishes quiz.\\
\cs{theeqpointvalue} & The total number of points in the current quiz. A \LaTeX{} macro, known at
compile-time.\\
pcScore& The score expressed as a percent. A JavaScript variable known when the user finishes the quiz. \\
quizGrade & The letter grade of the user's quiz. A JavaScript variable, known at ``run-time''. \\
\cs{eqGradeScale} & The grade scale for the quiz. A \LaTeX{} macro, known at ``compile-time''.\\
\end{longtable}

%\redpoint Other useful variables---perhaps at developers request---will be
%added in the future. \endredpoint


\subsection{Setting Up}\label{settingup}

In this section, we briefly discuss configuring your server and setting up
the demo files that accompany this distribution.

\subsubsection{Configuring the Server}

On the server side, in order for \textsf{eqRecord.asp} to run
correctly, Microsoft Internet Information Server (IIS), version
4.0 or greater, is needed. The script \textsf{eqRecord.asp} needs to be
placed where ASP scripts have execute permissions.

The \textsf{eqRecord.asp} uses the \textsl{Adobe FDF Toolkit}\footnote{Currently located at the
\href{http://partners.adobe.com/public/developer/acrobat/devcenter.html}{Acrobat Family Developer Center}.}, version
6.0. Follow the directions for installation contained in the
accompanying documentation.

Install \textsf{eqRecord.asp} in a folder (perhaps called
\texttt{Scripts}) designated to execute scripts.  If you don't
have such a folder, then the  following steps explain how to
create a virtual directory through IIS that points to this folder.

\begin{enumerate}
\item Create a new folder on the system (\texttt{Scripts}, for example). Its
recommended location is inside the \texttt{Inetpub} folder.

\item Place \textsf{eqRecord.asp} in this newly created folder.

\item In the MMC snap-in for IIS, create a virtual directory by
right-clicking on the Default Web Site and selecting
\texttt{New\;>\;Virtual Directory}.

\item Type ``Scripts'' (or whatever the name of the folder you
created in~Step~1) as the alias for the virtual directory, and
then link it to the physical directory you created in Step~1.

\item Make sure that ``Script execution'' privileges are enabled.
If not, enable them.
\end{enumerate}

\subsubsection{Set Up the Demo Files}

Place the Access 2000 database, \texttt{QuizIt.mdb}, in a folder
that is accessible by the server, such as the root level of your
web server, or perhaps, a folder dedicated to database files.
Register the database with the ODBC Data Source Administrator as a
System DSN under the System Data Source Name of ``QuizIt''.

Modify the first parameter of \cs{eqSubmit} in \texttt{quiz1.tex}
and compile (\texttt{latex}), then create \texttt{quiz1.pdf} using
\textsf{Acrobat Distiller}, \textsf{pdftex} or \textsf{dvipdfm},
and place it on your server. Test  by opening \texttt{quiz1.pdf}
in your web browser and taking a sample test.  Good luck, I hope it works!

\subsubsection{Comments on Demo Files}\label{demofiles}

\paragraph*{\texttt{quiz1.tex}:}  This file has two quizzes,
\texttt{Quiz1} and \texttt{Quiz2}. \texttt{Quiz1} has no frills,
the user enters his/her name and SSN, takes the quiz, and results
are saved to the \texttt{eqQuiz.mdb} Access database.
\texttt{Quiz2} is a bit more interesting as it demonstrates how to
assign points to each question, and how to report the results. The
techniques used in this quiz were discussed in
Section~\ref{moreHiddenFields}.

\paragraph*{\texttt{quiz2.tex}:} The quizzes of \texttt{quiz1.tex}
did not check whether the user is enrolled in the class, and as
such, is allowed to take the quiz. The demo file
\texttt{quiz2.tex} demonstrates how to\dots
\begin{questions}
    \item check whether the user has entered a valid SSN, that is, the
        SSN of someone enrolled in the class, or is permitted to take the quiz

    \item set a deadline date to take the quiz

    \item set a time limit to take the quiz
\end{questions}
Other variations are possible.


\subsection{Accessing Results in the DB}

The database that is to hold quiz results is placed on a
web-server and consequently, is not easily accessible by the
instructor. The ASP  script \textsf{GenericDB}\footnote{\url{http://www.genericdb.com/}} developed by Eli Robillard, is
a tool that can be used to access the database through your web
browser. Using \textsf{GenericDB}, you can view, edit, update, add
new and delete database records---and it's free! Check it out!


\section{The \texttt{eqText} Option}\label{eqTextOption}

In this section, we describe how to submit your data to a server-side script
that save the data to a tab-delimited text field. The \opt{submitAs} option
can be used with the \env{eqText} option. With \texttt{submitAs=FDF}, the
form data is submitted in the FDF format, the native form data format for
PDF, the target script should be \app{eqText.asp}. When
\texttt{submitAs=HTML} is used, the form data is submitted as ordinary HTML
form data, which can then be processed by any public domain script;
alternately, you can use one of the scripts in
Table~\ref{table:QuizScripts1}. These four scripts are available on the
CD-ROM that accompanies the book \AEBBook~\cite{book:AEBB}.


\begin{table}[htb]\centering
\begin{tabular}{r>{\ttfamily\raggedright}p{1.5in}}
\multicolumn{1}{>{\bfseries}r}{Option and return type}&%
\multicolumn{1}{>{\bfseries}l}{Script Files for \app{Windows} \& \app{Linux}}\\
\texttt{eqText}, {\HTML} return&eqText\_h.asp
eqText\_h.php\tabularnewline[3pt]
\texttt{eqText}, {\FDF} return&eqText\_hf.asp\#FDF\penalty0
eqText\_hf.php\#FDF
\end{tabular}
\caption{Scripts for \opt{eqText} \& \texttt{submitAs=HTML} options}\label{table:QuizScripts1}
\end{table}


\subsection{Submit as FDF}

We describe how to create an online quiz that is
to be submitted to the server-side script
\textsf{eqText.asp}\footnote{The script \textsf{eqText.asp} comes
with absolutely \emph{no guarantees}. Extensive testing should be
made on your own system to assure yourself script is reliable
enough to use in practice.}. With this option, you save your quiz data to
a tab-delimited file. The \textsl{FDF Toolkit}\FmtMP[\baselineskip]{FDF Toolkit required} is required to be installed on the
\app{Windows} server.

\redpoint The demo file for this option is \texttt{quiz4.tex}.

\paragraph*{In the preamble.} Begin the document with the usual preamble for an
\pkg{exerquiz} document, but include the \pkg{eq2db} package with the
\opt{eqRecord} option.
\begin{equation}
\begin{minipage}{355pt}
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\documentclass{article}
\usepackage{amsmath}
\usepackage[!grayV(!anglemeta(driver)),designi]{web} % driver: dvips, pdftex, xetex
\usepackage{exerquiz}
\usepackage[!grayV(submitAs=FDF,)eqText]{eq2db}
\end{Verbatim}
\end{minipage}\label{display:PreamEqText}
\end{equation}
Shown in gray are the \anglemeta{driver} and \opt{submitAs} options. The
\opt{pdflatex} and \opt{xelatex} applications are automatically detected, so
only \opt{dvips} needs to be specified if you are building your PDF with
\app{Acrobat Distiller}. The submission type is FDF by default, so
\opt{submitAs=FDF} need not be listed in the options of \pkg{eq2db}.

\paragraph*{In the body.} The following is a rough outline of an \pkg{exerquiz}
quiz document that submits to \app{eqRecord.asp}, the preamble declarations of
display~\eqref{display:PreamEqText}.
\begin{equation}
\begin{minipage}{330pt}
\begin{Verbatim}[fontsize=\small]
\eqSubmit{http://www.example.edu/scripts/eqText.asp\#FDF}
    {c:/Inetpub/Data/math101.txt}{Math101}
\begin{quiz*}{Quiz1} Answer each of the following. Passing
is 100\%.
\begin{questions}
\item ...
...
\item ...
\end{questions}
\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
\end{Verbatim}
\end{minipage}\label{display:eqTextTemplate}
\end{equation}
Notice that `\texttt{\#FDF}' is appended to the path, this informs the PDF viewer to expect
the server-side script to return FDF form data.

\medskip
Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz},
it takes three parameters.
\begin{equation}
\begin{minipage}{276pt}
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\eqSubmit{!meta(submitURL)}{!meta(pathToTabFile)}{!meta(courseName)}
\end{Verbatim}
\end{minipage}\label{display:SubmitTxt}
\end{equation}
\subparagraph*{Description of the parameters.} The \cs{eqSubmit} command
provides essential information use by the server-side scripts. Its parameters
are briefly described.
\begin{description}
\item\meta{submitURL} is the {\URL} to the server-side script
    \texttt{eqText.asp}. Internally, the value of this parameter is saved in
    the text macro \cs{eq@CGI}.

\item\meta{pathToTabFile} is the path to the tab-delimited file on the
    server where the script is to save the data. On \app{Windows},
    \meta{pathToTabFile} is the physical (absolute) path to the file, on
    \app{Linux} it can be a relative path (relative to the folder containing
    the executing script). Internally, this value is saved in the text macro
    \cs{db@Name}.\footnote{Choice for
    the names of \cs{db@Name} and \cs{db@Table} were originally based on the
    \texttt{eqRecord} option where data is saved to a database.}\xdef\fnNameChoice{\thefootnote}

\item\meta{courseName} is the course name of the class taking the quiz.
    Internally, this value is saved in the text macro
    \cs{db@Table}.${}^\text{\fnNameChoice}$
\end{description}


\subsubsection{Field Values Processed by \textsf{eqText.asp}}\label{eqTfieldvalues}

The \textsf{eqText} script processes two classes of field data:
certain ``\hyperref[hardwiredText]{hard-wired}'' field data; and field data
having a \hyperref[hierarchalfieldsText] {hierarchal} name with a root of either
\anglemeta{dbName} or \texttt{IdInfo}, e.g., \texttt{Quiz1.numQuestions} or
\texttt{IdInfo.Name.Last}. Details of each of these follow.

\paragraph*{``Hard-wired'' Fields.}\label{hardwiredText}
When you compile your source document with the package \pkg{eq2db} with the
\texttt{eqText} option, the package creates a number of hidden text fields.
These hidden fields are created under the `End Quiz' button. At submit time,
these fields are populated and submitted along with the quiz data. Below is
an enumerated list of these hidden fields with a brief description of each:
\begin{enumerate}
    \item \texttt{pathToTxtFile}: The value of second argument of
        \cs{eqSubmit} populates this text field.
    \item \texttt{courseName}: The value of the third parameter of
        \cs{eqSubmit} populates this text field.
    \item \texttt{quizName}: The name of the quiz or test, this is
        \cs{currQuiz}. Name should uniquely characterize the quiz/test the
        student is taking.
\end{enumerate}
The first two hidden fields are populated by the second and third arguments,
respectively, of \cs{eqSubmit}, as defined in
display~\eqref{display:SubmitTxt}. The third piece of data,
\texttt{quizName}, is obtained from the first required argument of the
\env{quiz} environment. See the skeleton example in
display~\eqref{display:eqTextTemplate}, there you'll see
\verb~\begin{quiz*}{Math101}~. The argument `\texttt{Math101}' is the quiz
name and is passed to the server-side script as the value of the
\texttt{quizName} hidden text field.

\paragraph{Fields with Hierarchal Names.}\label{hierarchalfieldsText}

Other than the fields described in \nameref{hardwired}, \textsf{eqText.asp} processes
only fields with hierarchal names that have \cs{currQuiz} as a root name
(see \nhnameref{hardwired} above) or a root name of \texttt{IdInfo}.

\subparagraph*{\texttt{quizName} (\cs{currQuiz}):} \texttt{quizName} is the
field title of one of the hidden fields, its value is picked up as the first
argument of the \env{quiz} environment; the value is stored in the text
macro \cs{currQuiz}.

In addition to the ``hard-wired'' hidden fields described earlier, there are
actually five more hidden fields (under the \textsf{End Quiz} button) with
root name \cs{currQuiz}. These are,
\begin{itemize}
    \item \cs{currQuiz.numQuestions}: The number of questions in the quiz.
    \item \cs{currQuiz.numCorrect}: The number of correct questions.
    \item \cs{currQuiz.Responses}: A list of all the responses of the user.
    \item \cs{currQuiz.ptScore}: The point score the student received on
        completion of the quiz.
    \item \cs{currQuiz.nPointTotal}: The total number of points in the
        quiz.
\end{itemize}
The values of these fields are also sent to the server-side script for the
\texttt{eqText} option. There is a mechanism for creating more hidden fields
the values of which are sent to the script. The technique for doing this is
discussed in \Nameref{moreHiddenFields}.

\subparagraph*{\texttt{IdInfo}:}\label{spara:IdInfoText}
As mentioned earlier, the \textsf{eqText} scripts process fields that use a
hierarchal naming convention, with root name of \cs{currQuiz} or
\texttt{IdInfo}. Fields whose root name is \texttt{IdInfo} are meant to hold
information about the person taking the quiz: first name, last name, student
number, and so on. Refer to the paragraph titled \textbf{\nhnameref{para:IdInfo}}
on page~\pageref{para:IdInfo} for more information.

\subsubsection{Setting up the Script}

On the server side, in order for \textsf{eqText.asp} to run
correctly, Microsoft Internet Information Server (IIS), version
4.0 or greater, is needed. The script \textsf{eqText.asp} should
be placed where ASP scripts have execute permissions.

\subsection{Submit as HTML}

When the \opt{eqText} and \opt{submitAs=HTML} options are specified for
\pkg{eq2db}, the form data are submitted as ordinary HTML form data. For the
\opt{eqText} option, it is meant that the server-side script save the form
data as a tab-delimited file. You can develop your own script for doing this,
or you can use one of the scripts of Table~\ref{table:QuizScripts1},
available on the CD-ROM of the book \AEBBook~\cite{book:AEBB}. The advantage of submitting as
HTML is that the \textsl{FDF Toolkit} is not needed, and the techniques for
writing a server-side script are well known.

The preamble of your document should look something like the following.
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\documentclass{article}
\usepackage[designi]{web}
\usepackage{exerquiz}
\usepackage[eqText,submatAs=html,tagged]{eq2db}
\end{Verbatim}
The \opt{tagged} option is recommended for the \opt{eqText} option but
no required. You may have other packages loaded, as well as other options for
\pkg{web} and \pkg{exerquiz}. The \pkg{eq2db} package was designed to be
seamless in the following sense: If the \pkg{eq2db} package is not loaded,
then an \pkg{exerquiz} quiz is self-contained, that is, it is not submitted
to a server-side script; if \pkg{eq2db} package is loaded, then the quizzes
are submitted to a server-side script.

In addition to the introduction of the \pkg{eq2db} package in the preamble,
there are two more important commands:
\begin{equation}
\begin{minipage}{300pt}
\begin{Verbatim}[commandchars=!()]
\eqSubmit{!meta(submitURL)}{!meta(pathToTabFile)}{!meta(courseName)}
\rtnURL{!meta(returnURL)}
\end{Verbatim}
\end{minipage}\label{display:eqSubmitT}
\end{equation}
\cs{eqSubmit}, defined in \pkg{exerquiz}, is required; \cs{rtnURL}, defined
in \pkg{eq2db}, is required only when the return from the server is an
{\HTML} page, but is recommended.

\paragraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential
information use by the server-side scripts, \cs{rtnURL} provides a return
{\URL} that points to where the student should navigate after the quiz.
Their parameters, as indicated in display~\eqref{display:eqSubmitT}, are briefly described.
\begin{description}
\item\meta{submitURL} is the {\URL} of one of the server-side scripts in
    Table~\ref{table:QuizScripts1}. Internally, the value of this parameter
    is saved in the text macro \cs{eq@CGI}.

\item\meta{pathToTabFile} is the path to the tab-delimited file on the
    server where the script is to save the data. On \app{Windows},
    \meta{pathToTabFile} is the physical (absolute) path to the file, on
    \app{Linux} it can be a relative path (relative to the folder containing
    the executing script). Internally, this value is saved in the text macro
    \cs{db@Name}.${}^\text{\fnNameChoice}$

\item\meta{courseName} is the course name of the class taking the quiz.
    Internally, this value is saved in the text macro
    \cs{db@Table}.${}^\text{\fnNameChoice}$

\item\meta{returnURL} is the {\URL} of the page the student should return
    to after finishing the quiz. The value of \cs{rtnURL} is required when
    the script returns an {\HTML} page, and is useful when the return is
    {\FDF}. Internally, \cs{rtnURL} defines the text macro \cs{thisRtnURL}
    to hold \meta{returnURL}.
\end{description}

\paragraph*{The scripts.} The \meta{submitURL} points to the server-side script that is to process the form data.
The scripts of Table~\ref{table:QuizScripts1} were written for the upcoming book
{\AEBBook} and are available on the accompanying CD-ROM. Refer the book for the details of
implementing these scripts.

\paragraph*{HTML versus FDF return.} The scripts of Table~\ref{table:QuizScripts1} are of two types:
HTML return and FDF return. In the first case, after the student has submitted his/her quiz,
the server-side script returns an HTML page to the browser window with an assessment of the
student's efforts on the quiz. In the second case, the script sends back an alert dialog box message saying
the data is received and saved; the quiz is self-marking for the student to review.
Details are laid out in {\AEBBook}~\cite{book:AEBB}.

\section{The \texttt{eqEmail} Option}\label{eqEmailOption}

In this section, we describe how to submit your data to a server-side script
that in turn sends an email message to a list of recipients, the body of the
messages contains the student's quiz results. The \opt{submitAs} option can
be used with the \env{eqEmail} option. With \texttt{submitAs=FDF}, the form
data is submitted in the FDF format, the native form data format for PDF, the
target script should be \app{eqEmail.asp}. When \texttt{submitAs=HTML} is
used, the form data is submitted as ordinary HTML form data, which can then
be processed by any public domain script; alternately, you can use one of the
scripts in Table~\ref{table:QuizScripts2}. These four scripts are available
on the CD-ROM that accompanies the book \AEBBook~\cite{book:AEBB}.

\begin{table}[htb]\centering
\begin{tabular}{r>{\ttfamily\raggedright}p{1.5in}}
\texttt{eqEmail}, {\HTML} return&eqEmail\_h.asp\penalty0eqEmail\_h.php\tabularnewline[3pt]
\texttt{eqEmail}, {\FDF} return&eqEmail\_hf.asp\#FDF\penalty0
eqEmail\_hf.php\#FDF
\end{tabular}
\caption{Scripts for \opt{eqEmail} \& \texttt{submitAs=HTML} options}\label{table:QuizScripts2}
\end{table}


\subsection{Submit as FDF}

We describe how to create an online quiz that is
to be submitted to the server-side script
\app{eqEmail.asp}\footnote{The script \textsf{eqEmail.asp} comes
with absolutely \emph{no guarantees}. Extensive testing should be
made on your own system to assure yourself script is reliable
enough to use in practice.  Feel free to modify the script to
suite your needs. If your improvements are noteworthy, please
allow me to incorporate them into the basic \textsf{eqEmail.asp}
for others to use. }. For this option, quiz results are e-mailed
to the instructor. The \textsl{FDF Toolkit} is required to be installed on the
\app{Windows} server\FmtMP[\baselineskip]{FDF Toolkit required}.

\redpoint \texttt{quiz3.tex} is the demo file for this option.

\medskip\noindent The steps to create a quiz to be submitted to
\textsf{eqEmail} are simple enough. First, the preamble of your
document should look something like this:
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\documentclass{article}
\usepackage[designi]{web}
\usepackage{exerquiz}
\usepackage[eqEmail]{eq2db}
\end{Verbatim}
\noindent You may have other packages loaded, as well as other
options for \pkg{web} and \pkg{exerquiz}. The \pkg{eq2db}
package was designed to be seamless in the following sense: If the
\pkg{eq2db} package is not loaded, then an \pkg{exerquiz}
\env{quiz} is self-contained, that is, it is not submitted to a
server-side script; if \pkg{eq2db} package is loaded, then the
quizzes are submitted to a server-side script.

Next, you write your \pkg{exerquiz} \env{quiz}:

\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\eqSubmit{http://www.example.edu/scripts/eqEmail.asp\#FDF}
    {dpspeaker@example.edu}{Math101}
\begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%.
\begin{questions}
\item ...
...
\item ...
\end{questions}
\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
\end{Verbatim}
Preceding the quiz is the \cs{eqSubmit} command, defined in the \pkg{exerquiz}.
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small,commandchars=!()]
\eqSubmit{!meta(submitURL)}{!meta(recipients)}{!meta(courseName)}
\end{Verbatim}
The first parameter is the URL to the server-side script, in the example
above, we have \texttt{http://www.example.edu/scripts/eqEmail.asp\#FDF} (note
the suffix of \texttt{\#FDF}); the second parameter, \meta{recipients},
is the e-mail address of the person to receive the quiz results; the third
parameter, \meta{courseName} is the course name. In the above example,
the course name is \texttt{Math101}.

\redpoint If meta{recipients} is a comma-delimited list of e-mail addresses, then
\textsf{eqEmail.asp} will parse the list, and use the first e-mail in the list in the
\texttt{From} field of the e-mail. Other email addresses in the list also receive copies
of the quiz results.\endredpoint

\medskip
There is another parameter of importance. The first argument of
the \env{quiz} environment is the \texttt{quizName} of the quiz, this is
\texttt{Quiz1} in the above example.

Assuming \textsf{eqEmail.asp} is installed on your web server, and
the \textsl{FDFToolkit} has also been installed (see
Section~\ref{settingup}), we are ready to submit the quiz. Below
is the body of one of my test e-mails I made using
\texttt{quiz3.pdf}:

\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
Course Information
    Course Name: Math101
    Quiz: Quiz1
    TimeOfQuiz: 8/23/2003 8:12:40 PM

Student Results
    Name_First: Don
    Name_Last: Story
    SSN: 121212121
    Responses: Leibniz,2x e^(x^2),-1,-cos(x)
    numCorrect: 4
    numQuestions: 4
\end{Verbatim}
\noindent If you add more fields, as described in
Section~\ref{moreHiddenFields}, this information should be appended to
the body of the e-mail.

\subsubsection{Field Values processed by \textsf{eqEmail.asp}}

Actually, \textsf{eqEmail.asp} is a variation of
\textsf{eqRecord.asp} and many of the details of this section are
the same \hyperref[eqRfieldvalues]{Section~\ref*{eqRfieldvalues}}.

The ``hard-wired'' fields are \texttt{mailTo}, \texttt{courseName}
and \texttt{quizName}. These fields are hidden under the `End
Quiz' button, and are populated at submit time.  As in the \texttt{eqRecord}
option, the value of the \texttt{quizName} field comes from the argument of
the \env{quiz} environment:
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\eqSubmit{http://www.example.edu/scripts/eqEmail.asp\#FDF}
    {dpspeaker@example.edu}{Math101}
\begin{quiz*}{Quiz1} Answer each of the following. Passing is 100\%.
\begin{questions}
\item ...
...
\item ...
\end{questions}
\end{quiz*}\quad\ScoreField\currQuiz\CorrButton\currQuiz
\end{Verbatim}
In this quiz, the field with name \texttt{quizName} will have a value of \texttt{Quiz1}.

\medskip See paragraph ``\nameref{hierarchalfields}'', page~\pageref{hierarchalfields}, as well as
Section~\ref{moreHiddenFields} on page~\pageref{moreHiddenFields} for
the \texttt{eqRecord} option, the details are the same.

\subsubsection{Setting up and Modifying the Script}

On the server side, in order for \textsf{eqEmail.asp} to run
correctly, Microsoft Internet Information Server (IIS), version
4.0 or greater, is needed. The script \textsf{eqEmail.asp} should
be placed where ASP scripts have execute permissions. There are
two methods of sending e-mail:
\begin{questions}
    \item \texttt{CDONTS}: This method (which is commented out by default) can be used on
        an NT server. Uncomment if you want to use CDONTS, and comment out the CDOSYS code lines
        that follow.
    \item \texttt{CDOSYS}: This can be run on a Win2000 or WinXP server.
\end{questions}

The script needs to be modified appropriate to your server, in particular, search down
in \texttt{eqEmail.asp} for the configuration line
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
eqMail.Configuration.Fields.Item
    ("http://schemas.microsoft.com/cdo/configuration/smtpserver")
        = "mySMTP"
\end{Verbatim}
\noindent replace \texttt{mySMTP} with your SMTP server.

The subject heading of the returning e-mail has the following format:
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
Quiz Results: Quiz1 of Math101
\end{Verbatim}
If you want another subject format, modify \texttt{eqMail.Subject} as
desired.

\subsubsection{References}

The following links were used as a reference in the development of the
\texttt{Email.asp} script.
\begin{itemize}
    \item CDOSYS:
    \begin{itemize}
        \item \href{http://invisionportal.com/show_tutorial.asp?TutorialID=160}{Invision Portal}  Tutorial: CDOSYS email tutorial
        \item \href{http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cdosys/html/_cdosys_imessage_interface.asp}
                {MSDN}: CDO for Windows 2000. The IMessage Interface. (Use MIE to view this page.)
        \item \href{http://www.asp101.com/articles/john/cdosmtprelay/default.asp}{ASP 101} Sending Email Via an External SMTP Server Using CDO
    \end{itemize}
    \item CDONTS
    \begin{itemize}
        \item \href{http://www.juicystudio.com/tutorial/asp/cdonts.html}{Juicy Studio} The ASP CDONTS Component
        \item \href{http://www.devasp.com/Samples/mail.asp}{DevASP} Sending Mail from ASP with CDONTS.NewMail Object
    \end{itemize}
\end{itemize}

\subsection{Submit as HTML}

When the \opt{eqEmail} and \opt{submitAs=HTML} options are specified for
\pkg{eq2db}, the form data are submitted as ordinary HTML form data. For the
\opt{eqEmail} option, it is meant that the server-side script should take the
incoming form data, build an email the body of which reports the quiz
results, and send the message to a list of recipients. You can develop your
own script for doing this or you can use the scripts provide with the book
\AEBBook~\cite{book:AEBB}. The advantage of submitting as HTML is that the \textsl{FDF
Toolkit} is \emph{not needed}, and the techniques for writing a server-side
script are well known.

The preamble of your document should look something like the following.
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\documentclass{article}
\usepackage[designi]{web}
\usepackage{exerquiz}
\usepackage[eqEmail,submatAs=html]{eq2db}
\end{Verbatim}
The \opt{tagged} option is \emph{not recommended} for the \opt{eqEmail}. You
may have other packages loaded, as well as other options for \pkg{web} and
\pkg{exerquiz}. The \pkg{eq2db} package was designed to be seamless in the
following sense: If the \pkg{eq2db} package is not loaded, then an
\pkg{exerquiz} quiz is self-contained, that is, it is not submitted to a
server-side script; if \pkg{eq2db} package is loaded, then the quizzes are
submitted to a server-side script.

In addition to the introduction of the \pkg{eq2db} package in the preamble,
there are two more important commands:
\begin{equation}
\begin{minipage}{300pt}
\begin{Verbatim}[commandchars=!()]
\eqSubmit{!meta(submitURL)}{!meta(recipients)}{!meta(courseName)}
\rtnURL{!meta(returnURL)}
\end{Verbatim}
\end{minipage}\label{display:eqSubmitE}
\end{equation}
\cs{eqSubmit}, defined in \pkg{exerquiz}, is required; \cs{rtnURL}, defined
in \pkg{eq2db}, is required only when the return from the server is an
{\HTML} page, but is recommended.

\paragraph*{Description of the parameters.} The \cs{eqSubmit} command provides essential
information use by the server-side scripts, \cs{rtnURL} provides a return
{\URL} that points to where the student should go to next after the quiz.
Their parameters, as indicated in display~\eqref{display:eqSubmitE}, are briefly described.
\begin{description}\def\NH{\relax\hspace*{-\labelsep}}%
\item\NH\meta{submitURL} is the {\URL} of one of the server-side scripts in
    Table~\ref{table:QuizScripts1}. Internally, the value of this parameter
    is saved in the text macro \cs{eq@CGI}.

\item\NH\meta{recipients} is a comma-delimited list of email addresses to
    whom the quiz results are sent. For example,
\begin{Verbatim}[xleftmargin=\amtIndent]
dpspeaker@talking.edu,taofdps@talking.edu
\end{Verbatim}
The first email address is picked off and used in the `From' field of the
email while the whole list is entered into the `To' field. Internally, this
value is saved in the text macro
\cs{db@Name}.${}^{\text{\fnNameChoice}}$
\item\NH\meta{courseName} is the course name of the class taking the quiz.
    Internally, this value is saved in the text macro
    \cs{db@Table}.${}^{\text{\fnNameChoice}}$

\item\NH\meta{returnURL} is the {\URL} of the page the student should return
    to after finishing the quiz. The value of \cs{rtnURL} is required when
    the script returns an {\HTML} page, and is useful when the return is
    {\FDF}. Internally, \cs{rtnURL} defines the text macro \cs{thisRtnURL}
    to hold \meta{returnURL}.
\end{description}

\paragraph*{The scripts.} The \meta{submitURL} points to the server-side script that is to process the form data.
The scripts of Table~\ref{table:QuizScripts2} were written for the upcoming book
\AEBBook~\cite{book:AEBB} and are available on the accompanying CD-ROM. Refer the book for the details of
implementing these scripts.

\paragraph*{HTML versus FDF return.} The scripts of Table~\ref{table:QuizScripts2} are of two types:
HTML return and FDF return. From the student's point of view, his/her
experience is the same as the \opt{eqText} option with
\texttt{submitAs=HTML}. In the first case, after the student has submitted
his/her quiz, the server-side script, as sending out an email response to the
\anglemeta{recipients}, returns an HTML page to the browser window with an
assessment of the student's efforts on the quiz. In the second case, the
script sends back an alert dialog box message saying the data is received and
results are sent to the instructor (the \anglemeta{recipients}); the quiz is
self-marking for the student to review. Details are presented in \AEBBook~\cite{book:AEBB}.


\subsection{The \texttt{tagged} option}\label{taggedOption}

When the student submits online quiz data to one of the server-side scripts,
just prior to submission, the hidden field \cs{currQuiz.Responses} is
populated with the student's answers. For example,
\begin{Verbatim}[xleftmargin=\amtIndent]
Newton,2x,-1,-cos(x)
\end{Verbatim}
is how the responses field is populated, by default. This data gives no
indication of which are correct, how many points for each question, and so
on.

To obtain more information about the quiz taken by the student and his
responses, you can specify the \opt{tagged} option. When this
option is taken, the quiz data is written as a ``XML-like'' string. Figure~\ref{fig:tagXML} is
an example of the data that populates the \cs{currQuiz.Responses} field and
which is sent to the server when the \opt{tagged} option is specified.

\begin{figure}[htb]
\begin{minipage}{5.45in}
\begin{Verbatim}[fontsize=\small]
<results id="Quiz1" file="quiz1.pdf" n=4>
    <question n=1 type="text" ptype="na" points="3" credit="0" correct="1">
        <value>Newton</value>
    </question>
    <question n=2 type="math" ptype="na" points="4" credit="0" correct="0">
        <value>2x</value>
    </question>
    <question n=3 type="math" ptype="na" points="3" credit="0" correct="1">
        <value>-1</value>
    </question>
    <question n=4 type="math" ptype="na" points="5" credit="0" correct="1">
        <value>-cos(x)</value>
    </question>
</results>
\end{Verbatim}
\end{minipage}%
\caption{Example of a tagged XML string}\label{fig:tagXML}
\end{figure}

Referring to Figure~\ref{fig:tagXML}, the XML string packs
more information in it than the default string. The quiz name is
\texttt{Quiz1}, the {\PDF} file the student used is \texttt{quiz1.pdf} and
there are four questions (\texttt{n=4}).  The first question was a text
fill-in type, worth $3$ points, the student responded correctly. The second
question was a math fill-in worth $4$ points, he missed this one with an
answer of \texttt{2x}.

The root element \texttt{results} contains child elements or
nodes called \texttt{question}. Each \texttt{question} node contains
information about one of the questions in the quiz. The \texttt{question}
node has several attributes, these attributes are seen in
Figure~\ref{fig:tagXML} above:
\begin{itemize}
    \item \texttt{n} is the question number. This is not the question
        number the user sees, but the value of an internal counter that
        increments each time a new question is posed.
    \item \texttt{type} is the type of question, possible values are
        \texttt{"text"} (text response), \texttt{"math"} (math response),
        \texttt{"mc"} (multiple choice), \texttt{"ms"} (multiple
        selection), \texttt{"grp"} (grouped response), and \texttt{"essay"}
        (multi-line text response). The latter is not graded by
        \pkg{exerquiz} but simply transmitted to the server.
    \item \texttt{ptype} is the problem (question) type, its value is
        normally \texttt{"na"} for `not applicable'. This attribute is used
        to describe the question in more detail within the XML. The value
        of \texttt{ptype} is set within the {\LaTeX} source file with
        \cs{QT\texttt{\darg{\meta{ptype}}}} command.
        Placement of this command is just after the \cs{item} command
        within the \env{questions} environment.
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\item\PTs{4}\QT{limits} Compute $\lim_{n\to\infty}...$
\end{Verbatim}
Now, the \texttt{ptype} attribute will read \texttt{ptype="limits"}. If
each problem is so tagged, the \texttt{ptype} attribute can be queried as
part of larger quiz management system to view a student's effort with
respect to all questions having the specified \texttt{ptype}. Such a system
was never implemented, but the attribute is available.
\item \texttt{points} is the number of points assigned to this question.
\item \texttt{credit} is the amount of partial credit the student earned
    for this question. Questions types where this attribute can be nonzero
    are \texttt{"mc"}, \texttt{"ms"}, \texttt{"text"} (in response to a
    \cs{RespBoxTxtPC} question), and \texttt{"grp"}.
\item \texttt{correct} is normally \texttt{"0"} (a wrong answer) or
    \texttt{"1"} (a correct answer); multiple selection (\texttt{"ms"}) and
    grouped (\texttt{"grp"}) questions use an array of values for the
    \texttt{correct} attribute, however. When calculating the score field
    (\cs{ScoreField}), the problem is either right or wrong; however, the calculation
    of the points field (\cs{PointsField}) takes into account the partial
    credit so a problem may be partially correct.
\end{itemize}

\paragraph*{Reconstructing the quiz.} Using the XML data as well as the
information provided by the \texttt{IdInfo} collection of fields, it is
possible to reproduce the {\PDF} document exactly as the student submitted
it. A demonstration file was developed for exactly this purpose and is
available on the CD-ROM that accompanies the \AEBBook~\cite{book:AEBB}.
The \app{Acrobat} application is required.

\section{The \texttt{custom} Option}\label{customOption}

This option allows a script developer to utilize the macros of the
\pkg{eq2db} Package to prepare an {\ifusebw\AcroT\else\cAcroT\fi} document to submit
to a custom script.  Simple create a file named
\texttt{eq2dbcus.def} and include any custom creation of fields
you may need for your script. When you then take the \texttt{custom} option,
\begin{Verbatim}[xleftmargin=\leftmargini,fontsize=\small]
\documentclass{article}
\usepackage[designi]{web}
\usepackage{exerquiz}
\usepackage[custom]{eq2db}
\end{Verbatim}
After the command definitions of \pkg{eq2db} are read,
\texttt{eq2dbcus.def} is input. The rest is up to you.

\redpoint That's all for now! Hope you find the package
useful. Now I really must get back my retirement. \dps

\addtocontents{toc}{\protect\vspace{2ex}}
\newpage
\markright{References}

\begin{thebibliography}{[1]}\label{references}
\addcontentsline{toc}{section}{\protect\numberline{}References}

\bibitem{book:AEBB}\hypertarget{references}{}%
   \textsl{\AEBBook}, D. P. Story, in preparation.

\end{thebibliography}

\end{document}
