-=---------------------------------------------------------------------=-
     ___            ___ ___ ___
    / _ \ _ _ _ __ | _ ) _ ) __| 
   |  _  | '_| '  \| _ \ _ \__ \  Script commands, conditionals, and macros
   |_| |_|_| |_|_|_|___/___/___/  

   -=---------=- List compiled by Steve Smale, 12th May, 1997 -=----------=-


File Contents:
--------------

    . ArmBBS Script Language - Intro
    . Available Script Commands
    . How menus are defined
    . Menu definition commands
    . Macros ( ¤<macro>¤ )
    . Conditionals (if <s>=<x>)
    . Msgbase Command Parameters
    . Filebase Command Parameters

ArmBBS Script Language
======================

Script file commands are enclosed between the delimiters '{' and '}' and can be
separated by either a comma or a newline. You can put spaces between the
commands but remember to include the ',' or newline.

You can use the /* and */ comment delimiters as with C and C++ to put comments
and non-user-readable information into script files.

Example section of script demonstrating the above points:

{
  fg 7
  bg 4
}
There has been a {fg 3,flash 1}40%{fg 7,flash 0} increase in profits
/* You can not see this bit */

Available script commands
=========================

Command			Description
-------			-----------

abort <n>		disables Ctrl+X aborting if n==0
abortkeys <s>		define keys to abort script/plain file
			($=CR ^=SPC, ~=TAB for control codes)
answer <n>		makes an answer to readline mandatory if n!=0
anykey			'press any key' prompt
givehelp		display online help (see 'help' menu command)
bg <n>			set background colour n
bold <n>		set bold text on if n==1
chat			initiate a sysop<>user chat
cll			clear to end of line
close			close the file
cls			clear screen
checkuploads		inform user of any outstanding files
checkdnloads		inform user of any outstanding files in queue
defitem <n>		define menu option n
disp <s>		type a plain file (no script interpreting)
tab <p>			position cursor at position p along line
door [X] <t> [<#>] <p>	starts a door of type t, number [#] using path and
			parameters p. Types are 0=armbbs, 1=arcbbs, 2=riscbbs;
			number needed for type1 only. Initial parameter X
			forces door output to avoid snoop window which would
			otherwise cause garbage to appear and slow the process
			down
doing <s>		note current activity
else			otherwise do what follows this
endif			ends conditional execution
eof			terminates execution of script file
eschelp <s>		sets text for 'help on Escape press' feature
fg <n>			set foreground colour n
fgbg <f> <b>		set foreground f and background b colours
flash <n>		turn flashing text on if n==1; preserves colours
filechgarea [n]		change file area in current base; if number not
			supplied user is asked
filechgbase [n]		change filebase; if number not supplied user is asked
filedate <v><s> 	returns timestamp of file <f> in variable <v>
filekill		kill last listed file
filelist <s>		list files with parameters s
filelistareas		list current filebase areas
filelistbases		list filebases
filemodify		modify filenames/short description of current file
filemove		move current file to another base
filequeue <s>		queue maintenance
filerecv <s>		receive a file with parameters s
filereset <s>		initialise pointers before listing files with
			parameters s
filesend <s>		send a file with parameters s
addkey <k>		add userkey k to this user's userkeys
delkey <k>		remove userkey k to this user's userkeys
togkey <k>		toggle userkey k on/off in in user's keys
flushib			flush input buffer
getkey <v>		waits for a keypress and stores in var v
if <s>			conditional execution if <s> equates TRUE
importkey <s>		add keypress to input buffer
listusers		display a list of users, asking for search details
log <s>			write s to logfile
logoff <n>		logs off (n=0 - immediate, n=1 - display logoff script,
			n==2 - ask if sure, display logoff script)
menu <s> [I]		execute menu script s and act on valid response; I
			means immediate effect (use return to exit)
more <n>		temporarily turn off more? prompts if n==0
msgchgarea [n]		change msgbase area; if no number supplied, user asked
msgkill			kill last read message
msglistareas		list msgbase areas
msgread <s>		read a message with parameters s
msgread p[u]		read private mailbox; if u is supplied, read user u's
msgreset <s>		initialise pointers before reading msg with parameters s
msgwrite <s>		write a message with parameters s
onlineusers		display list of users currently online
open <s>		open and append (or create) a user defined textfile
outchr <n>		output single character (ASCII n)
page <n>		page sysop n times
passchange		change user password
pause <n>		pause n centiseconds
popmenu	[n]		retrieve stored menu - see pushmenu
pos <x> <y>		set cursor position x,y
print <s>		output string s
pushmenu [n]		store current menu name for later retrieval; optional
			parameter enables retreival of specific menus
quitsys			kill armbbs immediately
rate <n>		temporarily alter time between wimppolls for file
			displaying in cs
readline <v><l><f>	reads line of text into var v, l characters max, flags f
			flags are: e=edit (var), f=field (blue bg) d<x> display
			(conceal) characters as <x>
relogon			cause a re-logon (simulates hangup followed by re-call)
script <s>		execute <s> as a script command
sendfile <s>		send a file Zmodem
set_flags....		set user's flags, eg set_flags A0 M1 C0 = ansi off,
			more on, cls off
			flags are:	[R]egistered [E]xpert [I]nvisible
			[L]ocked out [U]nlimited time [S]ysop [D]eleted
			[Z]-Userdir [T]-Chat status (0=norm, 1=always, 2=never)
			[*<s>] set userflags to s (keys) eg set_keys *ABCJE
set_level [+/-] <n>	sets level to n or +'s or -'s n from current!
set_lines		informs user of current lines setting & asks for new one
set_maxtime [+/-] <n>	sets user's maximum time for a day
set_ratio <d:u>		set download ratio eg {{set_ratio 10:1}
set_var <n> <c>		sets variable n to contain c
shellcli <slot>		start a shell to the supervisor (* prompt)
set_time [+/-] <n>	sets amount of time user has left for today in minutes
			or increase/decrease by n if + or - supplied
std			reset to basic white on black, non flashing, non bold
task <s>		run a task (uses Wimp_StartTask)
timetravel <d> <h>	time travel back (sets last logon date) d days, h hours
timeout <d>		set daily time/inactivity timeout; d=0 = disable timeout
tprint <d>		displays d for a short period then remove from screen
type <s>		type a script file
userchange		change username
getfile <p> <f>		get file using protocol p to filename f
write <s>		write s to the file
yesno <n>		yes/no prompt (default YES if n==1)

How menus are defined
=====================

{
  defitem <key>          <key> is the required key for this option
  display <chrs>         <chrs> is a string displayed when this option is
                         selected
  access <level>         <level> is the minimum userlevel allowed to select
  [                      denotes start of command list for this option
    .                   
    .                    place command(s) for this option here
    .
  ]                      denotes end of command list
  enditem                denotes end of menu option definition
}

e.g.

{
  defitem L              This defines a menu option activated by
  display List users     pressing 'L' which then displays 'List users'
  access 20              if the current user has a userlevel of 20 or
  [                      greater. The commands list the users and then
    listusers            asks for any key to be pressed.
    anykey
  ]
  enditem
}

N.B. All acceptable script commands can be used in menus, including 'type'
and 'menu'.


Menu definition commands
========================

defitem <k>		Start of menu option definition (k=key or \ascii)
access <n>		Minimum userlevel required to access menu option
display <s>		Print s up when option selected
password <s>		Password required to access option
keys <s>		Userkeys required to access option
help <str>		set help for the option (see givehelp scripty)
fail <str>		message to send user if they done have required access
[			Start of commands list
]			End of commands list
enditem			End definition of menu option
noredisplay		if this is placed in a menu option, as soon as it comes
			across that command, control will be returned back as
			if no selection made (without redisplaying menu)

Macros ( ¤<macro>¤ )
====================

Macros are expanded by the use of the surrounding '¤' characters. On machines
with non-archimedes keyboards, eg the RiscPC, this character can be obtained by
holding the alt key down while typing '164' on the numeric keypad.

For example if the user was called fred, {print `Hello, ¤user¤!`} would result
in "Hello, Fred!" being printed.

ansi			user's ansi state (1==on)
call_no			call counter; number of calls to the bbs
calls			number of calls the user has made
cls			cls state of user
con_baud		baud rate of user's connection
con_info		extra connection info (ARQ/RISCBBS/LOCAL/NONE etc)
date			current date
dl_avail		number of files available for d/l before upload necessary
dl_bytes		number of bytes user has downloaded
dl_ratio		u:d ratio e.g. 10:1
downloads		number of files user has downloaded
fileareaname		current filearea's name
filebasename		current filebase's name
filedir			current direction of filelisting e.g. >> or <<
filebaseno		number of currently selected filebase
filedesc		contains description of current file
filedir			current direction of filelisting e.g. >> or <<
filedownloads		contains number of times file has been d/loaded
filename		contains name of current file
filesize		contains size of current file
filesqueued		number of files in download queue
fileuploaddate		contains date of current file's uplaod
fileuploader		name of user who uploaded current file
lastlogon		date and time of user's previous login
lastup			date and time of last update to linetask
level			user's userlevel
line			current line number (line as in phone line, port# etc)
lines			current lines per screen e.g. 24
logontime		amount of time spent on this call so far
m_retval		mailer returncode (errorlevel) - during aftermail script
maxtime			maximum time in minutes user has for call
memfree			memory free in kbytes
more			more prompting status (1==on)
msgareaname		current message area's name
msgareano		currently selected msg area number
msgareatype		message area type 1 = echomail
msgdir			current direction of msgreading ( >> or << )
pager			pager status (1==on)
pos_x			current cursor x position
pos_y			current cursor y position
ret			script function returncode to indicate failures etc
svrlastup		last date of server module update
sysinfo1		current number of tasks
sysinfo2		wimp mode (extended RPC mode support)
sysinfo3		wimp version
sysop			sysop's username
t_handle		wimp task handle
time			current time (HH:MM)
timeleft		time left for this login (MM:SS) or -- if unlimited
todaytime		total time user has spent online today
ul_bytes		number of bytes user has uploaded
uploads			number of files user has uploaded
user			user's name
user_f			user's first name
user_l			user's last name
userdir			path to user's userdir
userno			user's user number
var<n>			contents of variable n
version			current armbbs version

Conditionals (if <s>=<x>)
=========================

f_reg			user registered? 1==yes
f_sysop			user has sysop flag? 1==yes
more			state of More? flag (x = 0 or 1)
ret			state of RET (set _after_ execution of script command), x = number
user			username (x = user to match) e.g. if user=Keith Hall

Parameters for msgbase and filebase commands:
=============================================

msgreset
	A		Only search messages addressed to All
	S		Only search messages from the sysop
	G		Global search
	><s>		Search for msgs to user s
	#<n>		Search from area n
	N		Search new msgs
	U		Search unread msgs
	D		Search deleted msgs
	Q		Quiet - Dont print 'Scanning... etc'

msgwrite
	P<n>		Private if n!=0
	O		Override any write restrictions for area
	R		Replying to msg
	#<n>		Write in area n
	><s>		Write to user <s>
	^<x>		Write to address <x> (netmail)

msgread
	F		Scan direction forwards
	O		Override read restrictions for area
	B		Scan direction backwards
	C		Read current message again
	S		Go to start of area
	E		Go to end of area
	#<n>		Read from area n
	+		Go to next area
	-		Go to previous area
	U		Unkill message
	Q		Create scratchpad
	no parameter	Read next message in current direction

filereset
	G		Global search
	><s>		Search for filename/description containing s
	S		Short format list
	#<n>		Search from area n
	N		Search new files
	Q		Quiet - Dont print 'Scanning... etc'

filewrite
	P<n>		Private if n!=0
	O		Override any write restrictions for area
	#<n>		Upload in area n
	><s>		Private Upload to user s

filelist
	F		Scan direction forwards
	O		Override read restrictions for area
	B		Scan direction backwards
	C		List current file again
	S		Go to start of area
	E		Go to end of area
	#<n>		Read from area n
	+		Go to next area
	-		Go to previous area
	no parameter	Read next file in current direction

filequeue
	L		List queue
	C		Clear queue
	D		Delete individual item in queue
	no parameter	Add (or remove) last seen file to/from queue

filesend
	Q		Download queue
	#		Download list of files by name/#number
	G		Global search for # parameter
	Z		Use Zmodem protocol
	X<n>		Use Xmodem protocol (1k blocks if n=1)