SREAD/SPLUS Version 1.04. The multi-
script script Door. Uses DScript(tm)
language to allow interactive scripts,
branch to subscripts, parsing of
responses, run DOS programs during and
after Door. SPLUS adds screen
positioning, full screen data entry and
dBase like control.

SREAD/SPLUS Version 1.04 Documentation:

LEGAL STUFF:

I am responsible for NOTHING! You are using this system totally at your
own risk! There is only one file that I write to at this time and that
is the answers file. All other files are simply either not used or read
only! User takes sole responsibility for security and safety of any data
while using this program.

Sread is not in the Public Domain. It is shareware. This means that you
are free to copy it, upload it to bulletin boards, and share it with
friends so long as no modification is made to the files contained in
this archive but you must either register it or stop using it after
thirty (30) days. No changes made be made to the contents or archive
except as required to accommodate the default archive format of a
particular BBS. No -AV's or ads for any BBS may be placed on, or in,
this archive without the express permission of the author.

Files in this archive are:

SREAD.EXE <- The main program
SPLUS.EXE <- Extended version
SREAD.DOC <- This file
EXAMPLE1 <- Batch File used to run the door with DOOR.SYS
EXAMPLE2 <- Batch File used to run the door with PCBOARD.SYS
SREAD.QES <- Sample script file covering two possible scripts
SPLUS.QES <- Sample extended script file.
REGISTER.FRM <- Registration form
FILE_ID.DIZ <- Description file

SREAD GENERAL INFORMATION:

All lines start with a some form of formatting information or that line will
be considered to be the question that you want to ask. The script format
is totally compatible with PCBoard's script file while adding ProScript
compatibility and my extensions via my own script commands using the
DScript(tm) language. This is basically a full featured multiple
script door.

PCBOARD COMPATIBLE FORMAT INFORMATION:

; Lines that start with a semicolon are all treated as displayed lines
but the semicolon is not displayed. There is nothing done with the
line, as it is only displayed.

PROSCRIPT COMPATIBLE FORMAT INFORMATION:

\ All lines that start with this symbol will be treated as a input
formatting string. These are the ProScript extensions and I have
tried to remain totally compatible with them. They are fully
documented in the ProScript documentation.

ProScript extensions:

\? ;require Y or N response
\# ;require numeric response
\$ ;require any character as response
\_ ;optional but allowed response

SREAD FORMAT EXTENSIONS:

! These lines are considered to be comments. They are not displayed nor
are they written to the answer file.

] This line will be written to the answer file. This will not be displayed
but will be written to the answer file.

% This line will be written to the answer file and displayed. You may use
any valid variables in this line.

$ This indicates that this is a label. The label must be on a line by
itself and be the first thing on the line (at the leftmost margin).

^ This is a command line and indicates a DScript(tm) command. The
commands are not case sensitive, so you may enter them in lowercase
if you want but recommend uppercase for readability. See the following
pages for commands and syntax.


ABORT

Purpose:

Used to handle the times that you don't want to save the information
that the user has entered.

Syntax:

^ABORT

Comments:

This is typically used after a question to see if the user is happy
with the answers they have given. This is most useful when you do
not want extraneous information in your answer file.


Example:

^JMP|$HAPPY|Are you happy with your answers?
^ABORT
^END

$HAPPY
!
!This is where you could save the information or continue on in
!the script file.
!
^ADJUST


ACP

Purpose:

This command is a shortcut method for quickly getting out of the
door depending on the users answer

Syntax:

^ACP|{question}

Comments:

This command is used when you want to minimize the content of the
script or just don't want to worry about exiting details. The user
is presented with the question and then system will wait for
a response. If the response is in the negative, the door will
immediately exit, and no further action or script information is needed.

Example:

^DSP|RULES
^ACP|Do you agree to abide by our rules?

!The user must have agreed with our rules, so lets continue on.

^JMP|$ADULT|Do you want access to our adult section?
^ABORT
^END

$ADULT
!
!You could continue from here
!


ADJ

Purpose:

This command will allow you to adjust the user level of the user
based on their answers.

Syntax:

^ADJ|{Level}
^ADJ|{+Level}
^ADJ|{-Level}

Comments:

The reason for different syntax is so that you can do a number of
things with this command. If you select only the level, the system
will set the user level to this value. If you preface the level with
a minus or plus sign, the user's level will be adjusted by the level.

Example:


^JMP|$HAPPY|Have you answered all the questions honestly?
^ABORT
^END

$HAPPY
^ADJUST
^ADJ|+10
^END


ADJUST

Purpose:

Used to handle the times that you want to update the pointer that
keeps track of the position in the answer file.

Syntax:

^ADJUST

Comments:

This is used usually used to update the pointer when you have a number
of pieces of a script file in one file. The reason to use this is
so that ^ADJUST will be up to the point that you want to reset the
file to. For example, if the user answered the first part of the
script and is happy with those answers, you would use ^ADJUST to
now move the pointer to the point after those saved answers. That way,
if the users is not happy with the next section, it will only throw
away the next section of answers.

Example:


^JMP|$HAPPY|Are you happy with your answers?
^ABORT
^END

$HAPPY
^ADJUST
^JMP|$ADULT|Do you want access to our adult section?
^ABORT
^END

$ADULT
!
!You could continue from here
!


ASK

Purpose:

This command is used to get multiple lines of input. This is not
full screen capable.

Syntax:

^ASK|{Lines}

Comments:

You specify the maximum number of lines that the user may enter. You
should also explain to the user that they may get out by entering a
single blank line.

Example:


$ADDRESS

;Please enter you address. You may enter up to 5 lines. When you
;are finished, you may press on a line by itself and you
;will exit immediately.

^ASK|5
;
;JMP|$HAPPY|Are you happy with the way you entered your address?
^ABORT
^JPP|$ADDRESS

$HAPPY
^ADJUST
^ADJ|+10
^END


ASSIGN (SPLUS only)

Purpose:

Used to setup the formatting information for full screen data entry.

Syntax:

^ASSIGN|{row}|{col}|{Format String}

Comments:

The formatting string is any valid ProScript format string.

Example:


! Start assigning the field input information

^ASSIGN| 7|24|\$$_________________________________________
^ASSIGN| 8|24|\$$_________________________________________
^ASSIGN|10|24|\$$_________________________________________
^ASSIGN|12|24|\?______
^ASSIGN|13|24|\?______
^ASSIGN|14|24|\?______
^ASSIGN|12|60|\?______
^ASSIGN|13|60|\?______
^ASSIGN|14|60|\?______

^GET
^GETSAVE


CHG

Purpose:

This will allow you to change the answer file that the results are
currently going to.

Syntax:

^CHG|{Filename}

Comments:

Use this command any time you wish to change only the answer file.
This is useful when you may want to start saving the answers to
an alternate file.

Example:


$ADDRESS

;Please enter you address. You may enter up to 5 lines. When you
;are finished, you may press on a line by itself and you
;will exit immediately.

^ASK|5
;
;JMP|$BUSINESS|Do you wan to add your business address?
^END

$BUSINESS
^CHG|BUS.ANS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5


CLS

Purpose:

This is used to clear the screen.

Syntax:

^CLS

Comments:

Use this command any time you want to clear the screen.

Example:


^CLS
^DSP|RULES
^ACP|Do you agree to abide by our rules?


DEFICOLOR
DEFQCOLOR

Purpose:

These are used to set default color codes for data entry and
question displays.

Syntax:

^DEFICOLOR|{@Xxy}
^DEFQCOLOR|{@Xxy}

Comments:

^DEFICOLOR is used to set the default color for data entry and
when a user is typing something.

^DEFQCOLOR is used to set the default color for questions that are
displayed.

Example:


^DEFICOLOR|@X0E
^DEFQCOLOR|@X0F

^JMP|$HAPPY|Are you happy with your answers?


DEL

Purpose:

Used to delete the specified file.

Syntax:

^DEL|{Filename}

Comments:

You can use this whenever there is a file that you want to delete.

Example:


!
!The board may have created a temporary file that we want to get
!rid of.

^DEL|THRASH.TMP


DSP

Purpose:

Used to display a file.

Syntax:

^DSP|{Filename}

Comments:

If the user is in a graphics mode, the system will append a "G" to
the filename and try to display that file. If there is no graphics
version it will try to non-graphics version.

Example:


^CLS
^DSP|RULES
^ACP|Do you agree to abide by our rules?


END

Purpose:

Used to end the processing of a script file.

Syntax:

^END

Comments:

You can place this any number of time throughout the script file.
When the system gets to this command, it will end all processing
of the scrip file. Close all files, and return to the system.

Example:


$BUSINESS
^CHG|BUS.ANS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^END


GET (SPLUS Only)

Purpose:

This command is used to get all the data from the ^ASSIGN command etc.

Syntax:

^GET

Comments:

You use this command when you want to retrieve all that information from
the ^ASSIGN commands. The user will have up and down cursor capability.

Example:


$DATAENTRY
^GET

^GOSUB|$TURNEMOFF
^LOCATE|18|4
^JMP|$DATAENTRY|Are you happy with your answers?
^GOSUB|$TURNEMON
^GETSAVE
^ADJ|10
^END

$TURNEMOFF
^LFOFF
^LINESOFF
^RETURN

$TURNEMON
^LFON
^LINESON

^RETURN


GETSAVE (SPLUS Only)

Purpose:

This command is used to save the information with the ^GET command.

Syntax:

^GETSAVE

Comments:

Your information will not be saved until you call this command.

Example:


$DATAENTRY
^GET

^GOSUB|$TURNEMOFF
^LOCATE|18|4
^JMP|$DATAENTRY|Are you happy with your answers?
^GOSUB|$TURNEMON
^GETSAVE
^ADJ|10
^END

$TURNEMOFF
^LFOFF
^LINESOFF
^RETURN

$TURNEMON
^LFON
^LINESON
^RETURN


GOSUB

Purpose:

Used to call a sub-routine in the script.

Syntax:

^GOSUB|{$Label}

Comments:

This will call a sub-routine that may be called any number of times
through the use of the script. The sub-routine must end with a
^RETURN

Example:


$PERSONAL
;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED

$BUSINESS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED
^END

$COMPLETED
;All done. Thank you.
^RETURN


ISGRAPHICS (SPLUS Only)

Purpose:

This command is used to check for graphics mode.

Syntax:

^ISGRAPHICS|{$Label}

Comments:

You should always use this command to determine whether the user
is in the ANSI graphics mode. Most SPLUS commands make extensive
use of the ANSI control codes, and the user must be in that mode.

Example:


^ISGRAPHICS|$NEED_ANSI
!
!Normal execution continues here
!
^END

$NEED_ANSI
;@FIRST@, you need to be in the ANSI graphics mode. Please switch
;to that mode.
;
^PAUSE
^END


JMP

Purpose:

Used to branch in the script file depending on the user response.

Syntax:

^JMP|{$Label}|{Question}

Comments:

This command will present the user with a question. If the response
is negative, the script will jump to the $Label.

Example:


$BUSINESS
;Please enter your business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5

^JMP|$BUSINESS|Are you happy with your answers?
^END


JPP

Purpose:

Used to branch in the script file unconditionally.

Syntax:

^JPP|{$Label}

Comments:

This is used to force a jump to a particular $Label.

Example:


$BUSINESS
;Please enter your business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5

^JPP|$NEXTPART


LFOFF
LFON

Purpose:

Used to control line feeds after displaying a question.

Syntax:

^LFOFF
^LFON

Comments:

^LFOFF - Used to turn off the line feeds.
^LFON - Used to turn on the line feeds. (Default state)

Example:


^GOSUB|$TURNEMOFF
^JMP|$DATAENTRY|Are you happy with your answers?
^GOSUB|$TURNEMON
^END

$TURNEMOFF
^LFOFF
^LINESOFF
^RETURN

$TURNEMON
^LFON
^LINESON
^RETURN


LOCATE (SPLUS Only)

Purpose:

Use this command to locate the information at an x by y coordinate.

Syntax:

^LOCATE|{row}|{col}|{Text Information}

Comments:

This will allow you to display information at a give location. You
do NOT have to include the text information. If you do not, the next
displayed information will be at the location. You MUST place all the
text information inside of double quotes or it will be ignored.

Example:


! Setup the prompts for the screen

^LOCATE| 7| 4|"@X0BFirst Name ...... :"
^LOCATE| 8| 4|"Last Name ....... :"
^LOCATE|10| 4|"Account number .. :"
^LOCATE|12| 4|"Adult access .... :"
^LOCATE|13| 4|"Previous user ... :"
^LOCATE|14| 4|"Mailing list .... :"
^LOCATE|12|40|"Lifetime sub. ... :"
^LOCATE|13|40|"Warnings ........ :"
^LOCATE|14|40|"Locked out ...... :"


LVL

Purpose:

Used to control the branching of the script depending on the user
level.

Syntax:

^LVL|{min_level}|{max_level}|{$Label}

Comments:

Use this command when you want to only allow users in the range
of user levels to do the script. If the user level is equal to
or greater than min_level and the user level is less than or
equal to max_level, the command will fall through, otherwise it
will ^JMP to $Label.

Example:


^LVL|1|9|$ALREADY_DONE

;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^END

$ALREADY_DONE
;
;@FIRST@, you don't have to answer this script again. Thank you.
;
^PAUSE
^END


MUL

Purpose:

Used to control the branching of the script depending on the users
answer.

Syntax:

^MUL|{$Label}|{$Label}|{$Label}|{$Label}|{$Label}|{$Label}

Comments:

You may use up to ten labels or as few as two. The user will be
presented with a prompt of enter a number from 1 to Label count.
If the user does not give a valid response, the command will drop
through, so it is highly recommended that you respond to the user
in some way to tell them it is an invalid response.

Example:


$MAIN_MENU

^CLS
;
;1. Script for access to our adult section.
;2. Script for subscribing to our board via Visa/MC/Amex.
;3. Script for validation.

^MUL|$ADULT|$CCARD|$VALIDATE
;
;Invalid response.
;
^PAUSE
^JPP|$MAIN_MENU


NEW

Purpose:

Used to run another script.

Syntax:

^NEW|{Question File}|{Answer File}

Comments:

Use this command to run a new script file. This command will change
script file and answer file. Use ^CHG if you only want to change the
answer file. Also, this will loose any pending ^GOSUB commands.

Example:


$MAIN_MENU

^CLS
;
;1. Script for access to our adult section.
;2. Script for subscribing to our board via Visa/MC/Amex.
;3. Script for validation.

^MUL|$ADULT|$CCARD|$VALID
;
;Invalid response.
;
^PAUSE
^JPP|$MAIN_MENU

$ADULT
^NEW|ADULT.QES|ADULT.ANS

$CCARD
^NEW|CCARD.QES|CCARD.ANS

$VALID
^NEW|VALID.QES|VALID.ANS


PAUSE

Purpose:

Used to prompt the user to press any key to continue.

Syntax:

^PAUSE

Comments:

Use this anywhere you want to pause the script long enough for the
user to be able to see something on the screen.

Example:


$MAIN_MENU

^CLS
;
;1. Script for access to our adult section.
;2. Script for subscribing to our board via Visa/MC/Amex.
;3. Script for validation.

^MUL|$ADULT|$CCARD|$VALID
;
;Invalid response.
;
^PAUSE
^JPP|$MAIN_MENU

$ADULT
^NEW|ADULT.QES|ADULT.ANS

$CCARD
^NEW|CCARD.QES|CCARD.ANS

$VALID
^NEW|VALID.QES|VALID.ANS


RETURN

Purpose:

Used to return from a sub-routine.

Syntax:

^RETURN

Comments:

This command MUST be used at the end of a subroutine or you will
"fall through" to additional commands and never return.

Example:


$PERSONAL
;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED

$BUSINESS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED
^END

$COMPLETED
;All done. Thank you.
^RETURN


RTRN

Purpose:

Used to return a DOS-Error level when exiting the system

Syntax:

^RTRN|{Level}

Comments:

This command is used to return a DOS-Error level when you exit the
door. You are allowed to use error levels in the range of 31 - 255.
1 - 29 are reserved for the system. Level 30 is used to indicate
the ^RUN command was used to exit.

Example:


$PERSONAL
;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED

$BUSINESS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED
^RTRN|35
^END

$COMPLETED
;All done. Thank you.
^RETURN


RUN

Purpose:

This is used to run any valid DOS commands.

Syntax:

^RUN|{Complete DOS line}

Comments:

This command will actually remove the system from memory and then
execute any command you give it. If you called the system from
a batch file, you will be returned to the command just following
the command that call the system when then run command is finished.

Example:


$PERSONAL
;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED

$BUSINESS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED
^RUN|cd \

$COMPLETED
;All done. Thank you.
^RETURN


SHL

Purpose:

This is used to run any valid DOS commands and then return.

Syntax:

^SHL|{Complete DOS line}

Comments:

This is used to shell out to DOS for any miscellaneous commands.
There may not be much memory left, so use this with caution.

Example:


$PERSONAL
;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED

$BUSINESS
;Please enter you business address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5
^GOSUB|$COMPLETED
^END

$COMPLETED
;All done. Thank you.
^SHL|BEEP
^RETURN


UPPEROFF
UPPERON

Purpose:

Used to control the forcing of all information written to the answer
file to be in upper case only.

Syntax:

^UPPEROFF - Turns off upper case forcing. (Default)
^UPPERON - Turns on upper case forcing.

Comments:

Place this anywhere that you would like to make the system write only
upper case information to the answer file. All information written
will be converted and then written.

Example:


^UPPERON
;Please enter your address. You may enter up to 5 lines.
;When you are finished, you may press on a line by itself
;and you will exit immediately.
^ASK|5


WRITEOFF
WRITEON

Purpose:

This is used to control information being written to the answer file.

Syntax:

^WRITON - Turns on writing to the answer file. (Default)
^WRITEOFF - Turns off writing to the answer file.

Comments:

Use this command to control all writing to the answer file. If you
turn off the writing, be sure to remember to turn it back on or you
will throw all your information away.

Example:


^WRITEOFF
Do you really want this information saved?
^WRITEON


REPLACEABLE VARIABLES CURRENTLY SUPPORTED:

@NUMCALLS@ Caller number
@BPS@ Connect Speed
@CITY@ City of the caller
@DATAPHONE@ Data phone number
@EXPDATE@ Expiration Date
@FIRST@ First name with the first letter Capitalized
@HOMEPHONE@ Home phone number
@LASTDATEON@ Last Date On
@LASTTIMEON@ Last Time On
@NUMTIMESON@ Number of Times on
@SECURITY@ Security Level
@USER@ Users full name

@Xyz variables:

Background (y) (blinking) Foreground (z) (Bold)
---------------------------------------------------------------------
Black = 0 8 Black = 0 8
Blue = 1 9 Blue = 1 9
Green = 2 A Green = 2 A
Cyan = 3 B Cyan = 3 B
Red = 4 C Red = 4 C
Magenta = 5 D Magenta = 5 D
Yellow = 6 E Yellow = 6 E
White = 7 F White = 7 F
---------------------------------------------------------------------

This information is included only to show how PCBoard uses the @X
variables. Clark Development has created this format. I do NOT
claim any rights to this format. Also, I do NOT support the @X00
or @XFF commands in this release.

@X00 - Save the current color
@XFF - Restore the saved color

SETUP:

Setup of SREAD or SPLUS is very simple. Create a directory for the
files somewhere on your system. You will then have to use a batch file
(Examples included) to run the door. There are a number of parameters
that need to be given to the door. They are as follows:

SREAD DOOR.SYS USERS SREAD.QES SREAD.ANS {option1} {option2}
SPLUS DOOR.SYS USERS SPLUS.QES SPLUS.ANS {option1} {option2}

DOOR.SYS can be replaced with PCBOARD.SYS if your system does not support
DOOR.SYS files.

USERS is the name and path to your users file.

SREAD.QES or SPLUS.QES is the name of the script file.

SREAD.ANS or SPLUS.ANS is the answers file for the script question.

Options:

/debug - used to debug your scripts. Will create an output of
the commands as they happened.

$LABEL - A label to start executing at in a script.


Error Levels Currently defined:

1 Unable to open BBS system file (pcboard.sys,door.sys etc)
2 Problem reading BBS system file
3 Unrecognized BBS file type
4 Unable to open pcboard USERS file
5 Invalid User record or problem seeking to user record
6 Problem reading USER record
7 PORT command syntax error
8 Fossil driver specified but no Fossil driver installed
9 Memory allocation problem

10 Script file not found
11 Unable to open answer file
12 Malloc failure
13 Refusal through ^ACP (See documentation for more details)
14 Calloc failure
15 Undefined Door open failure
16 Possible virus infection
17 Original DOOR.SYS not found
18 Unable to open SREAD.TMP file

30 ^RUN command used

19 - 29 Reserved for SRead

31 - 255 Available for ^RTRN command

Acknowledgements:

PCBoard is a registered trademark of Clark Development Company, Inc
ProScript is a registered trademark of Samuel H. Smith.
PDFC is a trademark of Kevin Carr.
DScript is a trademark of DSoftware.