MBBS SCRIPTS

MBBS SYSTEM DOCUMENTATION :: ORIGINAL SCRIPT.DOC

Contents:

General information Script file names The script file, an overview Applying commands/variables to users other than the current user Detailed description of commands External commands via scripts Replacing commands with scripts A script example Another example of a script

General information

Scripts provide you with a way of adding extra functions to your BBS system. For example scripts can be used to provide automatic access modifications, collect extra information from users, take 'opinion polls' and even provide an alternative user interface to the system.

Script files are placed by default in the main BBS directory, but may be placed in another directory if you configure such a directory with the CFGBBS program.

Script file names

Certain file names are allocated by convention and the scripts with these names executed at the appropriate time. The following names are used:

ASCRIPT

If this script exists it will be run for every user at the
time they log into the system.

CSCRIPT

If this script exists it will be run every time the BBS
prepares for a new user (NOTE: none of the user-specific
functionality should be used in a script like this, in that
there is no user logged in!)

DSCRIPT

If this script exists it will be run after each download.

NOPASS

This script will be run if three failed attempts are made
to enter a password (note: the failed passwords are available
in %F1, %F2 and %F3).

**NOTE** Because of potential security issues, this script will
*not* be run if the current user has sysop access.

OSCRIPT

If this script exists it will be run for every user at the
time they log out of the system.

RSCRIPT

If this script exists then all new users will execute this
script the first time they are logged into the system.

SCRIPT

This script is run when the main command function 'answer
questionnaire' is used.

USCRIPT

If this script exists it will be run after each upload.

XYxxxxxx

External commands are implemented using scripts that start
with the letter X. See below for a more detailed explanation.

(Your choice)

The SYSOP maintenance function (! S) and/or the !SET SCRIPT
command allow you to set a particular script name for a
particular user. This will be run when that particular user
logs into the system.

The output from the script (if any) is stored on a file which is specified in the script file itself. Two types of file are used, one a pure text file where output is appended with write and writeln commands, and one a random file which is used for registering votes with the vote command.

The script file, an overview

A script file is a normal text file that you may edit with your usual editor program. Most lines of the script program will contain just text which will be printed out on the users terminal (they will be printed with a new line after the text - for special lines where you don't want the extra new line, for example when accepting input from the user, you can end the line with a '& character and you won't get the extra new line after thsi particular line).

However, some special lines have a different meaning, and will tell the BBS program that you want to do something else. These lines begin with an exclamation mark (!). Here is an overview of the commands that are available:

!access test user access in current conference !accessin test user access in named conference !assign set a value for one of the 9 internal variables !calc calculate a value !chain give control to another script file !choice multiple choice specification !choicex same, but allow invalid choice !command execute a BBS command !conf transfer control if in specific conference !ddos execute a direct DOS command !ddosx execute a direct DOS command (no swapping) !delay delay, tenths of a second !dos execute a DOS command !dosx execute a DOS command (no swapping) !exists does a file exist !file specify output file name !goto go to label of same name !ichoice 'immediate' multiple choice specification !ichoicex same, but allow invalid choice !if test on internal switch ON !ifc see if one string contains another !ife compare two strings !ifg compare numbers, branch if greater !ifl compare numbers, branch if less !ifnot test on internal switch OFF !input get input from user !join join a conference (quietly) !label specify label for goto !local transfer control if local user !log log a line to CALLERS log !logout log the current user out of the system !marked transfer control if any marked msgs !member test membership in a conference !menu switches to one of the other menus !message posts a message from the SYSOP to the current user !nextconf go to next conference with unread messages !nextmsg show next unread message !nlogged transfer control if user has not been fully logged in !nodestat sets node status to one of 10 'user' texts !nodeqwk sets node status to 'using QWK' !places set number of decimals for !calc command !points select points value depending on multiple choice !poll identifies which poll is being taken !probe send a string and wait 1 second for any reply !pzero zeroes current points value !quit end of script !receive receive a file !relog log in new user !resume branch if user has written resume !sdelim set delimiter for !split command !send send a file to the user !set sets user parameters !setacc sets user access !setaccin sets user access in a particular conference !show display the contents of a file !sigop transfer control if sigop at least !silent execute a BBS command silently !split split a string !subs extract a substring !syslog log data for TOSYSOP !sysop transfer control if sysop !switch transfer control depending on multiple choice !tempsysop transfer control if temporary sysop !tlog log a line to CALLERS log, including time !turnoff turn off an internal switch !turnon turn on an internal switch !uread read data from script area on users record !uwrite write data on script area on users record !vote register vote on file after multiple choice !write write a string to the output file !writeln write a line to the output file

Any lines beginning with the ! sign that have commands not in this list will be treated as labels, in other words

!here

is the same as

!label here

Before going into a detailed description of the commands, another function of the system must be understood, and that is that of 'substituted' arguments. These begin with a percent sign (%) and may be used in any line, also output lines that are not commands. The % argument will be replaced with its value before the line is processed. The following %-arguments are available:

%%            just inserts a single % in the line
%n            (n=1 to 9) use value of internal variable
%A1           first line of user address
%A2           second line of user address
%A3           home telephone number
%A4           work telephone number
%BA           BBS area number
%BB           BBS subarea number
%BC           BBS system number
%BI           BBS system ID
%C            inserts the name of the current conference
%D            inserts the current date
%F1-%F3       failed attempts at password entry
%FC           Y if using FOSSIL, N otherwise
%FD           last downloaded file name
%FE           last uploaded file extension
%FR           file time remaining in minutes (9999 = no limit)
%FT           last downloaded/uploaded file description
%FU           last uploaded file name
%FX           Y if last !receive/!send was successful, N if not
%FZ           last uploaded file size in bytes
%I            inserts the most recent user input (!input)
%J            inserts the current julian date
%K            inserts command parameters for external commands
%K1-%K9       as above, but extracts parameter 1-9 from %K
%LC           inserts last msg number in current conference
%LR           inserts highest msg read in this conference
%LV           inserts last viewed msg number
%M            inserts the current time in minutes past midnight
%N            inserts the number of the most recent choice
%O            inserts the number of the current node
%P            inserts current points scored
%Qnnn         inserts text nnn from BBSTXT.x
%R            remaining time online in minutes
%Sx           inserts various user statistics
*:Sysop availability (Y or N)
#:User ref number (unique through life of
the user)
1:User time limit
2:User file limit
A:ANSI (gives Y or N)
B:bytes downloaded
C:first name
D:files downloaded
E:messages entered
F:bytes uploaded
G:msgs grabbed
H:hours on system
I:number in user file
J:char for default protocol, else N
K:MNP/ARQ in use (Y or N)
L:language (gives language code or space)
M:message filter level
N:times on system
O:page length
P:line speed
Q:Y if quick login, else N
R:messages read
S:last name,
T:total read+grabbed
U:files uploaded
V:character set being used
X:expert mode (gives N/J/X/S)
Y:terminal type (T/A/V)
Z:archive preference (gives A/T/Z/L/J for
ARC, TEXT, ZIP, LHARC, ARJ)
_:file browse mode (Y or N)
%T            inserts the current time
%R            inserts time spent online in minutes
%U            inserts the name of the current user
%Vm.n         inserts the poll results for question m, choice n
(requires preceding !file command, but not !poll)
(choice of zero gives total votes cast)
%W            inserts name of current config file
%XB           inserts comms port base address (decimal)
%XC           inserts any caller id string from the modem
(if option configured in CFGBBS)
%XE           status of last !COMMAND/!SILENT (Y=ok, N=not OK)
%XI           inserts comms port IRQ
%XP           inserts comms port number (0=local, 3=custom)
%XS           inserts modem rate (bps)

A special format of the '%' argument can be used to provide formatting commands:

%#<justification><length>

<justification>    L = Left

R — Right
C — Centered

This should be used IMMEDIATELY prior to the substituted argument to which it will apply. If several arguments are to receive such special formatting then the formatting command must be specified for each of them. For example, you could use the following to provide a neatly formatted list of numbers:

Files uploaded:      %#R12%SU
Files downloaded:    %#R12%SD
Bytes uploaded:      %#R12%SF
Bytes downloaded:    %#R12%SB

Applying commands/variables to users other than the current user

Usually you will want to access and update data for the user on whose behalf the script is being run. However, for sysop usage you may often want to write scripts that update other users instead. ALL script commands and script variables may be prefixed with a 'Z' character, and in this case they will apply to the

LAST USER ACCESSED IN THE SYSOP MAINTENANCE (! S) MENU

or the user that has been set with the

SCRIPT !USER or !IUSER command

For example, if you wanted to implement a new command 'OK' in the sysop maintenance menu that set the user daily time limit to 60, the file time limit to 45, and give the user download access in the conference 'Main', then you would write a script called XYOK (X=external, Y=sysop maintenance) containing:

!zset time 60 !zset filetime 45 !zsetaccin Main +D

If you wanted a sysop command to display a users number in the user file on the other hand you write a script containing:

!iuser nochoice User number %ZSI in USERS.DAT !nochoice !quit

and call it XZUNUM (for example).

Detailed description of commands

!ACCESS X label_name

This command causes a branch depending on the access the user has in the current conference. More than one access type can be specified, using the normal letters for access:

R   Read access
W   Write access
U   Upload access
D   Download access
O   Open door access
S   Sigop access

The branch will occur if the user has all the specified access types in the current conference. For example

!access UD nextlabel

will branch to 'nextlabel' if the user has upload and download access in the current conference.

!ACCESSIN conference_name X label_name

This command is the same as !access except that you specify the conference name to test on. For example:

!accessin Main D HasDownload

tests whether the user has download access in the 'main' conference and branches if this is true.

!ASSIGN n value

This command saves a value in an internal variable. There are 9 of these, each one holding up to 80 characters. The value is extracted again using the %n substitution command. The internal variables are useful for saving data that you do not wish to write out to the output file immediately. For example if you wished to collect the users machine type and modem type but not write them out to the output file before both had been confirmed by the user you could do as follows:

!askuser Please enter your computer type: & !input !assign 1 %i Please enter your modem type: & !input !assign 2 %i Computer : %1 Modem : %2 Is this OK (YN): & !choice yn switch writefile askuser !writefile !writeln ---------------------------------------- !writeln %u %d %t !writeln Computer: %1 !writeln Modem : %2

!CALC n formula

The !calc command allows you to calculate a value using any of the inserted variables and assign it to one of the internal variables. Normal rules for evaluating the formula are used, and any number of parentheses are allowed. You may also use the functions SQRT, LOG, LN, EXP ABS, and RAND (RAND returns a random number from zero to one less than the value you specify).

For example, if you wanted to show the percentage of users who had answered 'yes' (option 1) to a certain question you could do something like:

!calc 1 (%v1.1 / %v1.0) * 100 %1%% of users answered Yes to this question.

Or if you want to simulate throwing three dice:

!calc 1 3+rand(6)+rand(6)+rand(6)

NOTE! You are yourself responsible for not writing formulas that would give errors; if you for example make the mistake of dividing by zero then the program will stop. For example, if you would like to calculate the ratio of bytes downloaded to bytes uploaded you would FIRST test that the number of bytes was not zero.

!CHAIN scriptname

This procedure passes control to another script file. The name of the file must not have an extension, as all the normal rules for graphics and user-language menuname extensions are supported.

!CHOICE abc...

This command specifies a list of options the user must choose between, each specified by a single character. The system will stop and wait for the user to type one of the characters (only the characters you specify in the list will be accepted). The result of typing the character may either be used to pass control to another part of the script, using the !switch command, or to register a vote for the relevant choice, using the !vote command.

Usually the line before the !choice command should be the prompt that will ask the user for input. For example:

Please choose A, B or C: !choice ABC !switch Aroutine Broutine Croutine

Note that the case of letters in the command is irrelevant, in the above example either 'a' or 'A' would be a valid input.

!CHOICEX abc...

This is just the same as !CHOICE with one exception; if the user types an invalid letter with CHOICE then he will get an error message and be asked to retype. With CHOICEX control continues in the script, with a value of one more than the highest possible value from the list of choices.

!COMMAND command

Executes an MBBS command. All commands are permissible with the exception of commands that are specific to the main menu. If the command is not complete then the normal prompts will be given.

Example:

!command J POST

Note that also sysop commands may be allowed in the !COMMAND if you have used the SET SYSOP ON command to give the user temporary sysop access. Remember to turn it off again afterwards! Make sure that the command you execute is a valid one and that you don't leave the user sitting interactively in the sysop menu. For example, to give user JOE BLOGGS read and write access in the current conference you would use

!set sysop on
!command ! a JOE BLOGGS;N;RW

Note also that in this particular example you are not able to exit from the sysop menu at the end of the command because of the special syntax used for access rights. However you are still under script control and can return to the main menu status after execution by adding

!command q

as your next script command.

You can test whether or not the command was valid or not with the %XE variable (useful if you are executing something that was input by the user).

!CONF conference_name label_name

This command allows you to transfer control to another part of the script if you are in a specific conference, thus allowing you to make your script depend on which conference the user is logged into. Example:

!conf soft softmenu

(if the user is in the 'software' conference then control passes to the 'softmenu' label). As with other transfer of control statements you may use the syntax '!then script_statement' instead of specifying a label. For example:

!conf soft !then This is the software conference

would display 'This is the software conference' if you are in the 'soft' conference, but otherwise do nothing. Or

!conf soft !then !chain soft.scr

would start the script 'soft.scr' if you were in the 'soft' conference.

!DDOS command

Executes the specified DOS command directly instead of through COMMAND.COM. The fully qualified file name of the program to run must be specified, and piping and redirection may not be used.

!DDOSX command

Same as !DDOS, except that the BBS will not swap itself to make more room for the program being executed.

!DELAY n

Stops the script for n tenths of a second.

!DOS command

This will execute the specified DOS command. NOTE that no redirection of the communications port will be applied, this must be included in the DOS command itself if required.

NOTE also that the command will be passed to COMMAND.COM for execution (so that you can make use of the PATH, redirection and internal DOS commands) but that if you do not have complete control of the contents of the command then you should use the !DDOS command instead. For example, a user name may contain pipe or redirect characters, and if you pass the user name as a parameter to !DOS then unexpected results may occur.

!DOSX command

Same as the DOS command, but the BBS will not swap out to make more room for the command being executed. See the notes under the !DOS command for when to use !DDOSX instead.

!EXISTS filename label_name

Branches to label_name if the named file exists, otherwise not. For example:

Enter a filename:
!input
!exists %i ok
Sorry, it isn't there.
!quit
!ok
We found your file.
!quit

Alternatively you may use !then in the same way as for the !conf command.

!FILE filename

This command is used to specify the name of the file on which the output data is to be registered, and MUST be present before any of the output commands (for example !write) are used. You may use more than one !file command if you want to register the output on several files. It's a good idea to specify the complete pathname for the output file, for example:

!file c:\bbs\scripts\answers

!GOTO label_name

This command is used to transfer control to another part of the script. The name specified in the !goto command must match a corresponding name in a !label command, for example,

!goto para.2

... ...

!label para.2

!ICHOICE abc...

This command is exactly the same as !CHOICE; for details see the documentation of !CHOICE. The only difference is that while !CHOICE waits for the user to press enter, and allows correction of the choice being made, !ICHOICE reacts as soon as the user presses a valid key (it beeps at him if he presses something else). Also, you may include control characters as valid choices using ^x syntax (^M means CR for example; as special cases, ^^ means a single ^ and ^- means a space).

!ICHOICEX abc...

This is just the same as !ICHOICE with one exception; if the user types an invalid letter with CHOICE then he will not be allowed to continue (the BBS will beep at him). With ICHOICEX control continues in the script, with a value of one more than the highest possible value from the list of choices set up for the following SWITCH command.

!IF x label_name

Transfers control to 'label_name' if switch x is ON. There are 26 internal switches available, named from 'A' to 'Z'. These switches are set to FALSE at the start of the script and may be manipulated using the !TURNON and !TURNOFF commands.

Alternatively you may use !then in the same way as for the !conf command.

!IFC string1 string2 label_name

Checks to see whether string1 contains string2, and transfers to 'label_name' if it does. If either of the strings contain embedded spaces then they may be quoted. For example:

!ifc "%U" "hack" L1

goes to label L1 if the user has used 'hack' anywhere in the name they have used to register on the BBS. The comparison is case-independent. Note that %U had to be enclosed in quotes because it contains a space when expanded.

Alternatively you may use !then in the same way as for the !conf command.

!IFE string1 string2 label_name

Compares two strings, and transfers to 'label_name' if the two strings are equal. If either of the strings contain embedded spaces then they may be quoted. For example:

!ife "%U" "John Smith" L1

goes to label L1 if the user is called John Smith. The comparison is case-independent. Note that %U had to be enclosed in quotes because it contains a space when expanded.

Alternatively you may use !then in the same way as for the !conf command.

!IFL N1 N2 label_name

Compares N1 with N2 and branches to label_name if N1 is less than N2. For example:

!ifl %st 10 WarnHim

will branch to the WarnHim label if the user in question has read and/or grabbed a total of less than 10 messages.

Alternatively you may use !then in the same way as for the !conf command.

!IFG N1 N2 label_name

The same as !ifl but tests whether N1 is greater than N2.

!IFNOT x label_name

Transfers control to 'label_name' if switch x is OFF. Alternatively you may use !then in the same way as for the !conf command.

!INPUT [{X|N} [max_length [E] [I]]

This command is used to collect input from the user. In the same way as for the !choice command the command will usually be preceded by the prompt asking the user for the input. Normally the system will accept any input of up to 80 characters, you may change this by adding some information after the !input command. The first character may either be an X (any input) or an N (numbers only). You may after this specify a maximum input length for the input, and after this again add an E if you want the user to be forced to enter input (i.e not just press Enter) and/or an I (to specify that the entry is to be 'invisible' and that the BBS should echo dots rather than what's typed). So to ask the user for a number, at most two characters, you could use

!input N 2

or to ask for up to 40 characters of data with any type of characters allowed but input of some kind required you would use:

!input X 40 E

The same thing, but echoing dots:

!input X 40 E I

The data entered by the user is available in the %I variable.

!USER none

Asks for a user name. If no name is chosen then control will pass to the specified label. If a name is chosen that does not exist then a list of alternatives will be presented (in the same way as is done when you enter a message on the BBS). When a valid name has been selected, the command will set the user name for commands and variables using the Z prefix (overriding the default, the last user displayed in the Sysop maintenance menu). See the earlier section on "applying commands/variables to users other than the current user".

!JOIN conference_name

This command lets you switch from one conference to another. The basic difference between !JOIN and !COMMAND JOIN is that !JOIN will join the user to the conference with no output from the normal MBBS conference join procedure.

!LABEL label_name

This command provides a place for the !goto and other commands of this sort to go to. The text LABEL is not actually necessary, the system will accept the format !label_name.

!LOCAL label_name

Control passes to the named label if the current user is running locally.

Example:

!local localmenu .....

!label localmenu

Alternatively you may use !then in the same way as for the !conf command.

!LOG log data

This puts the data into the CALLERS file for this node. Extra space will be added automatically to line up the data with normal entries. For example:

!log This script doesn't seem to be working

See also !SYSLOG and !TLOG

!LOGOUT

This command terminates the script and logs out the current user.

!MARKED label

Will go to 'label' if there are any marked messages. Alternatively you may use !then in the same way as for the !conf command.

!MEMBER conference_name label_name

This command will give control to 'label_name' if the current user is a member of (or has been invited to) the conference you have specified.

Alternatively you may use !then in the same way as for the !conf command.

!MENU x

Switches to the R(ead), U(tility), F(ile) or M(ain) menu depending on the value of 'x'.

!MESSAGE filename subject

This posts the contents of the named file as a message to the current user (from the SYSOP) with the specified title. For example:

!message c:\msg\message.1 Welcome to this BBS

!NEXTCONF

Joins the next conference with unread messages.

!NEXTMSG

Shows the next marked (unread) message.

!NLOGGED label

This command transfers control to 'label' if the current user has not been completely logged in (specifically, if the user has not arrived at the main command prompt, with all scripts that are supposed to be run completed without the user having been loggeed out or carrier dropped).

This command is primarily intended for use from an OSCRIPT script to check whether or not ASCRIPT has been run.

Alternatively you may use !then in the same way as for the !conf command.

!NODESTAT n

This command sets the node status for the current node to one of 10 'user' statuses. The values shown for these are in the BBSTXT files, numbered from 717 to 726 (using !NODESTAT 1 will display the text from BBSTXT text number 717 and so on).

!NODEQWK

This command sets the node status for the current node to the 'using QWK' status. This is for use by QWK procedures.

!PLACES

This command sets the number of decimal places to be used when calculating with the !calc command. The default is no decimals.

!POINTS value_1 value_2 value_3 ...

This selects the value corresponding to the most recent choice made, and adds it to the current points. Points are reset to zero when the script function is entered, and also by the 'zero' function. Normal usage would be something like:

Choose a, b or c:

!choice abc !points 10 0 -5

!POLL poll_number

This command identifies which 'poll' is being taken. A number between 1 and 16 must be specified, and the name of a label which the program is to go to if the user already has taken part in this poll. This command need not be present, but if it is missing then the program will not check that the user only votes once (in fact the command may also be used for normal script questionnaires if you wish to prevent users from answering more than once). You should have a different number for each script alternative in your system. Note that the NP (newpoll) command in the sysop menu may be used to reset this indicator for all users when you install a new poll on a number that has already been in use. Example:

!poll 2 byebye ....

!label byebye Sorry, you can only vote once! !quit

The !poll command MUST follow the !file command if it is used.

!PROBE N text_to_send

This command sends the specified string and waits the specified time (in tenths of a sxecond) for any reply (which will be available in %I in the same way as for the !INPUT command). This would typically be used for sending an 'enquiry' type of command; for example testing ANSI capability by sending a device status request (<esc> here must be a 'real' escape character):

!probe 10 Testing ANSI capability...<esc>[s<esc>[3;4H<esc>[6n<esc>[u !ifc "%I" "<esc>[3;4R" HaveANSI !ifc "%I" "<esc>[03;04R" HaveANSI !ifc "%I" "<esc>[003;004R" HaveANSI

(The above ANSI sequence saves the cursor position, moves the cursor to (3,4), asks for a cursor position report, and restores the cursor position. It then checks to see whether the correct answer was provided; several different answers are checked in that not all emulators answer the same way.)

!PZERO

Zeroes the current points counter.

!QUIT

This command terminates the questionnaire and returns control to the main board.

!RECEIVE filename pathname protocol

This command receives a file from the user. 'Filename' is the name that the user will be asked for (max 12 chars, normal PC rules) for those transfer protocols where this is sent to the user. 'Pathname' is the absolute filename to which the file will be received, and 'protocol' is the single-letter identifier for the transfer protocol to use (same as in the utility menu when setting default protocols). If this is set to 'N' then MBBS will ask the user to select a protocol in the normal way, so you would normally use the %SJ variable to insert this in the line. When setting the filename locally on a multinode system remember that the script might possibly be run from more than one node at the same time. A status for the transfer (with the usual proviso that it's not always possible to return an accurate status for external protocols) is available in the %FX variable. A typical command might be:

Please send your file now! !RECEIVE MYPADS.ZIP C:\BBS\PADS\PADFIL%O.ZIP %SJ

!RELOG

Has the same effect as the G;A interactive command.

!RESUME label_name

This command branches to 'label_name' if the user has left resumé information about himself.

Alternatively you may use !then in the same way as for the !conf command.

!SEND name pathname

This command starts a download of the specified file to the user. 'Name' is the name that will be presented to the user and written in the callers log; pathname is the actual file that is to be sent. In all but special cases you should use the actual filename in the first parameter.

!SET ......

This command allows the script to change various user parameters (most useful in the RSCRIPT possibility for new users on the system, if you want to provide extra help in choosing the correct settings for running your system. The following possibilities are provided:

SET ALIAS       {name|NONE}  Set user Alias
SET AVAILABLE   {ON|OFF}     Set sysop availability
SET ANSI        {ON|OFF}     ANSI menus on/off
SET AUTO        {ON|OFF}     G&R file transfer on/off
SET BROWSE      {ON|OFF}     File browse mode on/off
SET CHARACTERS  {cset}       Character set being used
SET CHAT        {ON|OFF}     Control access to NODE/CHAT
SET COLOURS     {ON|OFF}     Colours in messages on/off
SET CSHOW       {ON|OFF}     Conference display at login on/off
SET FILETIME    nn           Sets file menu time limit
SET FSE         {ON|OFF}     Full screen editor on/off
SET GRAB        {ASCII|ARC|ZIP|LHA|ARJ}
Set preferred GRAB method
SET LANGUAGE    {x}          Choose language key
SET MARGIN      nn           Set margin in screen editor
SET PAGELENGTH  nn           Set page length
SET PROTOCOL    {protocol}   File transfer protocol
SET SCRIPT      {name}       Change users default script
SET SYSOP       {ON|OFF}     Temporary sysop status toggle
SET TERMINAL    {type}       Terminal type
SET TIME        nn           Sets daily time limit
SET WARN        {ON|OFF}     Controls warning about nested scripts

{cset} : one of IBM, IBN, US7, ISO, UK7, GE7, SF7, NO7, DE7, IT7, FR7 or SP7. {x} : single letter language key or DEFAULT. {protocol} : one of NONE, ASCII, XMODEM, XMODEM-C, YMODEM, YMODEM-B, YMODEM-G, MODEM-7 or TELINK, or name of external protocol if configured. {name} : simple name, no extension; or NONE {type} : one of TTY, ANSI or VIP

!SETACC {+|-}X

This command sets the current users access rights for the current conference. The first character of the rights being set must be a plus or a minus, depending on whether you are adding access or removing it. The other characters specify which rights are being added or removed:

R   Read access
W   Write access
U   Upload access
D   Download access
O   Open door access

For example:

!setacc +D

adds download access to the access rights for the current conference.

!SETACCIN conference_name {+|-}X

This command is the same as !setacc except that you specify the conference name in which rights are to be set. For example:

!setaccin Main -D

will remove download access in the 'Main' conference.

!SHOW filename

This command will show the named file (paging its output in the normal way).

!SIGOP label_name

Control passes to the named label if the current user has at least SIGOP status in the current conference.

Example:

!sigop sigopmenu .....

!label sigopmenu

Alternatively you may use !then in the same way as for the !conf command.

!SILENT command

This is exactly the same as !COMMAND, but all output from the BBS will be suppressed while the command is being executed.

!SPLIT left right string-to-split

This command looks for a delimiter in 'string-to-split' and places the left-hand part in the variable 'left' and the right-hand part in the variable 'right'. The delimiter is by default the space character but may be changed with the !sdelim command. For example the first 'word' of user input could be extracted with

!split 1 2 %I

The first word will have been placed in variable %1, and the remainder of the input will be in %2.

!SUBS result start length string-to-subs

This command extracts a substring from 'string-to-subs'. The result is placed in the 'result' variable and consists of 'length' characters starting from position 'start' in the input string.

!SYSLOG log data

This command lets you write a line on the TOSYSOP file that will be displayed to the SYSOP next time he logs in. The time and node number will be autoamtically inserted for you as for 'normal' TOSYSOP entries.

External commands via scripts

You may implement additional commands on your system using script files. These files use the name of the command as part of the name of the script. For example, the script named XMORDER would give you a new command, ORDER in your main menu. The X at the start of the name is always present, and the M tells MBBS that the command applies in the main menu only (commands that are to apply everywhere use a G in the second character of the name). The following may be used in the second character:

A     Archive format preference menu only
C     Chat menu only
D     Read Mode menu only
F     File menu only
G     Global, applies everywhere
K     Mark menu only
M     Main menu only
P     Transfer protocol menu only
R     Read menu only
S     Search menu only
U     Utility menu only
Y     Sysop user maintenance menu only
Z     Sysop menu only

Note that the rest of the command entered by the user is available in the %K variable. For example, if the user typed:

ORDER T-Shirt CD;G Y

then %K will give you 'T-Shirt CD' (input after the semicolon is considered to be a new command). Also %K1 will give you 'T-Shirt' and %K2 will give you 'CD'.

Replacing commands with scripts

A special syntax in the BBSTXT file (where the commands are defined) allows you to use this functionality to replace a command, either replacing it completely or adding extra functions before or after the original function. Let's suppose that you want to replace the download command (D) with your own version. You would make a file XFD (and equivalents in other languages if necessary) to do this. Obviously you now have to edit BBSTXT to make sure that D is no longer a valid command as recognized by the BBS. Rather than delete it by removing the text between the / characters, add a tilde (~) character IN FRONT of the command. This means that in text number 138 in BBSTXT you replace the part

...DEL/DIR/Down/EXT/GET....

with

...DEL/DIR/~Down/EXT/GET....

Commands edited in this way cannot be used interactively at all, and will be shown without the initial ~ character when a list of valid commands is presented to the user.

In the script XFD you can on the other hand use the ~Down command (with the initial ~) in the !COMMAND (or !SILENT) script commands. In other words:

This is the initial script processing (before download) !COMMAND ~D %K This is processing that takes place after downloading.

NOTE!

Remember to edit ALL your BBSTXT files if you are going to use this functionality. Also note the use of %K to insert the rest of whatever the user originally entered in his command to the BBS.

A script example

Here are a couple of simple scripts that you could use to control upload/download ratios. For the sake of this example we'll assume that you want the user to upload a new file for every 10 files that he downloads (the first 10 downloads being "free"). We'll also assume that the name of conference zero is "Main" (because this is where general upload and download access is given).

You need two scripts, first DSCRIPT (which is run after every download):

!rem Calculate ratio, taking account of first free downloads !rem (this also avoids having to deal with zero uploads) !calc 1 %SD / (%SU + 1) !rem --> If less than 10 then all is OK !ifl %1 10.0 AllOK !rem --> Otherwise he loses his access! !setaccin Main -D !rem --> Tell the user what happened...

You must upload a file before you will *
be allowed to download any more! *

!rem --> Now we are finished !AllOK !quit

And also USCRIPT which will give the access back again:

!rem Calculate ratio, taking account of first free downloads !calc 1 %SD / (%SU + 1) !rem --> If less than 10 then OK for download again !ifl %1 10.0 GiveDownload !rem --> Otherwise leave him be !goto AllOK !GiveDownload !setaccin Main +D !rem --> Tell the user what happened...

Your download access has been given *
```
     back to you, thanks!       *
```

!rem --> Now we are finished !AllOK !quit

Another example of a script

The following example uses several of the functions described above:

!starthere

SCRIPT QUESTIONNAIRES

We currently have four options available:

For supplying information about your computer that other users may read.
Read the information entered using option 1.
A trial 'opinion poll'.
View the current opinion poll status.

Choose an option from 1-4, or type G to exit: !choice 1234G !switch getinfo showinfo pollin pollout leaveit

!getinfo

Computer types questionnaire

Please note that the information you enter here will be available to other users of the board!

What make of computer do you use (not the model, we will ask you for that next, e.g. if you have an IBM AT then just enter 'IBM').

Your computer manufacturer is: !input x 20 e !assign 1 %i

Which model of %i computer are you using: !input x 30 e !assign 2 %i
What brand of modem do you use (make and model this time please, as exactly as you can): !input x 30 e !assign 3 %i
What is your opinion of your %1 %2 computer? Choose between: 1: Excellent 2: Good 3: Just OK 4: Unsatisfactory

Choose 1-4: !choice 1234 !switch m.exc m.good m.ok m.bad !m.exc !assign 4 excellent !goto q5 !m.good !assign 4 good !goto q5 !m.ok !assign 4 OK !goto q5 !m.bad !assign 4 unsatisfactory !q5

What is your opinion of your %3 modem? Choose between: 1: Excellent 2: Good 3: Just OK 4: Unsatisfactory

Choose 1-4: !choice 1234 !switch c.exc c.good c.ok c.bad !c.exc !assign 5 excellent !goto q6 !c.good !assign 5 good !goto q6 !c.ok !assign 5 OK !goto q6 !c.bad !assign 5 unsatisfactory !q6

Which communications program are you using? !input x 30 e !assign 6 %i

Your answers: Computer manufacturer : %1 Computer model : %2 Modem make and model : %3 Opinion of computer : %4 Opinion of modem : %5 Communications program : %6

Are these answers OK? (Y if they are, N to answer again, X to exit): !choice ynx !switch writeinfo getinfo starthere !writeinfo !file c:\bbs\main\machines One moment while I register your answers...

!writeln -----------------> !writeln %u !writeln Computer: %1 %2 (%4) !writeln Modem : %3 (%5) !writeln Program : %6 !goto starthere

!showinfo

Answers received so far: !show c:\bbs\main\machines

!goto starthere

!pollin !file c:\bbs\main\poll !poll 1 badluck

Todays public opinion poll

Please don't take this too seriously....

Question 1: What do you consider the main use of a modem to be?

A) I don't know what a modem is B) Collecting greek characters from telephone lines C) Data communications D) A place to put my ashtray E) Breaking into other computer systems F) Modems are no use to anyone

Your choice: !choice abcdef !vote 1 %n

Question 2: If you had an Amiga computer, would you use it to

A) toast bread B) sit on C) bang nails in with D) sail single-handed round the world in E) none of the above

Your choice: !choice abcde !vote 2 %n

!q3

Question 3: What is your favourite BBS system?

A) MBBS B) BBS-PC! C) PC-board D) RBBS E) Fido F) Opus G) Wildcat

Your choice (careful now): !choice abcdefg !switch q4 novote novote novote novote novote novote !novote You can't be serious! Please reconsider your answer (or you may not be allowed back into the system). !goto q3

!q4

Question 4: (just to have something serious....) How often do you use 'read reference'?

A) always B) sometimes C) never, I don't like it D) never, I have never tried

Your answer: !choice abcd !vote 3 %n

!goto starthere

!badluck

Sorry, I can only allow you to vote once! !goto starthere

!pollout

Results so far

!file c:\bbs\main\poll

Question 1: total votes cast - %v1.0

We have %v1.1 ignorant users, %v1.2 frustrated users, %v1.3 optimistic users, %v1.4 practical users, %v1.5 criminal users and %v1.6 pessimistic users.

Question 2: total votes cast - %v2.0

We have %v2.1 burnt Amigas, %v2.2 squashed Amigas, %v2.3 dented Amigas, %v2.4 rusty Amigas and %v2.5 otherwise useless Amigas.

Question 3: total votes cast - 2721

We have 2720 sensible users and 1 user who got into serious trouble with the SYSOP and has been blacklisted (let that be a warning to you all!)

Question 4: votes cast - %v3.0

Read reference always : %v3.1 sometimes : %v3.2 never : %v3.3 never tried : %v3.4

!goto starthere

!leaveit

!quit