summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/eq2db/doc/eq2dbman.tex
blob: 201474bcfc006df5b8e35d19d58610d4ac2e84b5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
\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}