
















			       Baja Version 1.10
	       Shell/Module Compiler for Synchronet BBS Software
			Copyright 1995 Digital Dynamics
				Updated 02/17/95









**********************************
* IMPORTANT PRINTING INFORMATION *
**********************************

This document is formatted for 96 columns. Make sure your
printer is set for this mode (also referred to as 12 cpi
or "Elite"). Otherwise, the document will not print with
correct formatting.


Table of Contents
=================
&&Contents

Introduction....................................................@@INTRO___
	Command Shells..........................................@@CMDSHELL
	BAJA.EXE................................................@@BAJA_EXE
	Modules.................................................@@MODULES_
Programming Syntax..............................................@@SYNTAX__
Programming Style...............................................@@STYLE___
	Suggested Rules.........................................@@STYLERUL
Functions.......................................................@@FUNCTION
	Display.................................................@@DISPLAY_
	Input...................................................@@INPUT___
	Miscellaneous...........................................@@MISC____
	Mail....................................................@@MAIL____
	Message Base............................................@@MESSAGE_
	File Base...............................................@@FILE____
	Chat....................................................@@CHAT____
	Information.............................................@@INFO____
Instructions....................................................@@INSTRUCT
Quick Reference.................................................@@QUICKREF


Introduction
============
&&Introduction
$$INTRO___
Baja (b„'h„) is a tool used to create command shells and modules for Synchronet
multinode BBS software. The programmable command and menu structure (PCMS)
technology in Synchronet version 2 allows sysops to modify the user interface
for the BBS by replacing or modifying command shells. Synchronet version 2.00
shipped with six stock command shells (Classic and Novice Synchronet shells as
well as emulations of PCBoard, Wildcat, Major, and Renegade BBS packages).
These shells can be modified, removed, or replaced with ease. Up to 500 shells
can be made available to the users of the BBS with configurable security access
to each shell via ARS (see the Synchornet Sysop manual for details on ARS).

Note:

If you come across an undefined term in this document, please read through
the document to possibly find the term defined later or used again to clarify
its meaning by context or see the glossary in the Synchronet sysop manual.

Command Shells
==============
&&Intro: Command Shells
$$CMDSHELL
Command shells consist of a text source file with a .SRC extension. These .SRC
files can be edited with any ASCII text editor (e.g. EDIT, QEDIT, EDLIN, etc).
The contents of the text file must conform to the Baja language specifications
defined in this document. An extremely basic example of a shell source file:

----------------------------------[ Begin ]-----------------------------------

# EXAMPLE1.SRC

# Label for later "goto" commands
:TOP

# Clear the screen
CLS

# Show menu of commands
MNEMONICS "~Comment to Sysop\r\n"
MNEMONICS "~Goodbye (Logoff)\r\n"

# Show command prompt
PRINT "\r\nCommand: "

# Get command key
GETCMD "CG"

# Comment to sysop?
COMPARE_KEY C
IF_TRUE
	MAIL_SEND_FEEDBACK
	GOTO TOP
	END_IF

# Logoff?
COMPARE_KEY G
IF_TRUE
	LOGOFF
	GOTO TOP
	END_IF

-----------------------------------[ End ]------------------------------------

The syntax of the above text will be explained later in this document.

For more elaborate examples, please see the *.SRC files in your Synchronet EXEC
directory.

BAJA.EXE
========
&&Intro: BAJA.EXE
$$BAJA_EXE
After the source file has been created, BAJA.EXE is used to compile the .SRC
file into a binary file with a .BIN extension that Synchronet can execute as a
command shell. If the source filename is EXAMPLE1.SRC, then the command line
would be:

BAJA EXAMPLE1

The program's output:

BAJA v1.01 ú Synchronet Shell/Module Compiler ú Copyright 1994 Digital Dynamics

Compiling EXAMPLE1.BIN...
Resolving labels...

Done.

This creates the command shell binary file EXAMPLE1.BIN.

Warning: Do not attempt to edit, view, or print .BIN files.

Shell source and binary files as well as the BAJA program itself are normally
stored in the Synchronet EXEC directory. This is where Synchronet loads
command shells and modules from, so the .BIN files must be created in or copied
to this directory before they can be used.

After a command shell has been compiled, it must be added to the list of
available command shells in SCFG (Synchronet Configuration program) to be
available for the users to use. If using a multinode BBS, the other nodes
must be re-run before the new command shell will be available on those nodes.

If modifying an existing command shell, SCFG does not need to be run and nodes
do not have to be re-run since command shell binary files are dynamically
loaded for each logon.

Modules
=======
&&Intro: Modules
$$MODULES_
Baja modules are very similar to command shells with the main difference being
that they are not automatically loaded upon logon as command shells are.
Instead, modules must be loaded from a command shell with the EXEC_BIN
instruction described later in this document or launched as an external program
or event configured in SCFG. Binary module files, like command shell binaries,
must be located in the Synchronet EXEC directory.

Modules can be used to consolidate identical portions of multiple command
shells into one binary that can be loaded from each command shell so that if a
modification needs to be made to that portion, then only one source file needs
to be modified and compiled as opposed to making the same change to every
command shell and recompiling them all.

Another use for modules is for third-party add-ons. Rather than distributing
Baja source that must be merged into command shell source by sysops, developers
can distribute module binaries that can be loaded directly from a command
shell with a very small modification to the existing shells.

To load a Baja module in place of a DOS executable in SCFG, prepend an asterisk
(*) to the name of the module (e.g. "*MYMOD").

Programming Syntax
==================
&&Programming Syntax
$$SYNTAX__
Basics:
	Execution always begins at the top of the source code and continues
	downward until an instruction is executed which changes the flow of
	execution. Only one instruction or function is allowed per line.
	The total length of each line cannot exceed 255 characters.

Whitespace:
	All whitespace (TAB and SPACE characters) at the beginning of each line
	are ignored. The first printable character of a line is considered
	the first character. Completely blank lines are ignored.

Comments:
	If the first character of a line is the pound symbol (#), the
	line is ignored. These are normally used for text comments about the
	following source code line(s). Comments CANNOT be included on the
	same lines as code (instructions or functions). Comments are more
	easily read if there is a space after the pound symbol (#) and before
	the comment text begins.

Labels:
	If the first character of a line is the colon symbol (:), the line
	is considered a label to be used for the GOTO or CALL instructions.
	Labels are not case sensitive. There should be no space between the
	colon and the name of the label. Label names may contain spaces.

Case Sensitivity:
	The only text that is case sensitive (where upper or lower case is
	significant) is text that will be displayed to the end user. One
	important element of this, is that @-Codes must be upper case
	(as documented in the Synchronet Sysop manual).

Arguments:
	When an instruction requires an argument, there must be exactly one
	space between the function name and the argument. For example, the
	line:
		PRINT "Hello"
	there is one space beteween the function name (PRINT) and the argument
	("Hello"). No more, no less.

C Strings:
	Some character string arguments are defined as being C type. This
	indicates the contents of the string use the same control character
	escape sequences as defined for the printf() function in the ANSI
	definition of the C programming language. The only exception to the
	ANSI definition, is that \### defines a character value in decimal,
	not octal. All escape sequences begin with the backslash (\) character.
	The valid escape sequences are:

	\\	Backslash
	\?	Question mark
	\'      Single quote
	\"      Double quote
	\r	Carriage return
	\n	Line feed
	\t	Horizontal tab
	\b	Backspace
	\a	Bell
	\f	Formfeed
	\v	Vertical tab
	\###	Character value in decimal
	\x##	Character value in hexadecimal

	The double quotation marks delimiting the string are optional, but
	required if you want to leave space at the end of the string. It is
	suggested that quotation marks be used always, to maintain consistency.

Programming Style
=================
&&Programming Style
$$STYLE___
As stated in the previous section, white space characters at the beginning
of a line are ignored and have no effect on the resulting compilation. But,
whitespace can be very useful in making the source code readable by indenting
conditional blocks of code, and using blank lines to separate blocks of
related code. Comments are also very helpful in making the code readable.

Compare the following source to the example given in the Command Shell
chapter:

----------------------------------[ Begin ]-----------------------------------

:TOP
CLS
MNEMONICS "~Comment to Sysop\r\n"
MNEMONICS "~Goodbye (Logoff)\r\n"
PRINT "\r\nCommand: "
GETCMD "CG"
COMPARE_KEY C
IF_TRUE
MAIL_SEND_FEEDBACK
GOTO TOP
END_IF
COMPARE_KEY G
IF_TRUE
LOGOFF
GOTO TOP
END_IF

-----------------------------------[ End ]------------------------------------

Without the whitespace and the comments, the code appears much more cryptic
and the control flow (or conditional blocks of code) is not obvious. But the
code will compile into exactly the same binary file as the earlier example.

Consider this more elaborate example using indentation only:

With indentation:

----------------------------------[ Begin ]-----------------------------------

COMPARE_ARS FILE_CMDS=0
IF_TRUE
	COMPARE_USER_MISC ASK_NSCAN
	IF_TRUE
		YES_NO "\r\n\r\nSearch all libraries for new files"
		IF_TRUE
			FILE_NEW_SCAN_ALL
			END_IF
		END_IF
	END_IF

-----------------------------------[ End ]------------------------------------

Without indentation:

----------------------------------[ Begin ]-----------------------------------

COMPARE_ARS FILE_CMDS=0
IF_TRUE
COMPARE_USER_MISC ASK_NSCAN
IF_TRUE
YES_NO "\r\n\r\nSearch all libraries for new files"
IF_TRUE
FILE_NEW_SCAN_ALL
END_IF
END_IF
END_IF

-----------------------------------[ End ]------------------------------------

As you can see without the indentation, you can get lost in nested IF
statements trying to understand how the code will execute.

Suggested Rules of Style
========================
&&Suggested Rules of Style
$$STYLERUL
There isn't a "right" or "wrong" way to use indentation, blank lines,
or comments, but we will present a set of suggested "rules" here. If you decide
you prefer another style, that is fine. The most important thing is that you
are consistent in your use of whatever style you choose.

Top of File Comments
--------------------
Place a comment as the very first line of the file with the name of the .SRC
file. Example:

# EXAMPLE.SRC

Then a block of comment lines that describe what the shell or module's purpose
is, who programmed it, when, where, etc.

Label Comments
--------------
Labels normally represent the beginning of a sub-routine and should be
well commented. A graphical line to show the beginning of a new sub-routine
is often helpful. Example:

############################### My Sub-routine ################################
:MY-SUB

CMD_HOME Comments
-----------------
The CMD_HOME instruction marks the beginning of a command/menu loop and should
be well commented. Example:

#############
# MAIN MENU #
#############
CMD_HOME

Conditional Indentation
-----------------------
Whenever a block of code is conditionally executed (only executed under
specific conditions), the block of code should be indented one tabstop past
the block header (IF_TRUE, IF_FALSE, ELSE, CMDKEY, or CMDSTR). The block of
code to be indented includes the block terminator (END_IF or END_CMD). Example:

GETCMD ABCD

CMDKEY A
	COMPARE_ARS LEVEL 50
	IF_TRUE
		PRINT "You have level 50 or higher.\r\n"
	ELSE
		PRINT "You have level 49 or lower.\r\n"
		END_IF
	END_CMD

Separate Code Blocks
--------------------
Use blank lines to separate medium to large code blocks from other code
(most especially CMDKEY and CMDSTR code blocks). Example:

GETCMD ABCD

CMDKEY A
	PRINT "You hit A.\r\n"
	END_CMD

CMDKEY B
	PRINT "You hit B.\r\n"
	END_CMD

End of File Comment
-------------------
Place a comment at the end of the file. Example:

# End of EXAMPLE.SRC

$$FUNCTION
Display Functions
=================
&&Display Functions
$$DISPLAY_
Display functions are used to display output to the user either locally,
remotely, or both.

PRINT <str>
-----------
This function sends a string of characters to the user (both locally and
remotely, if applicable). The str argument is a C type string of printable
ASCII characters optionally delimited by double quote (") characters.
The string to be printed can extend beyond the 80th column of the screen, but
when printing multiple lines, multiple consecutive PRINT statements are
preferrred.

Example:
		PRINT "hello, world\r\n"

The string can contain color codes using Synchronet Ctrl-A codes. See the
Synchronet sysop manual for the definition of Ctrl-A codes and their usage.
If you are using an ASCII editor that does not support control characters,
a "\1" can be used in place of the Ctrl-A (smiley face) character.

Variables can also be included in the string (example: user's name, sysop's
name, BBS name, etc) by using Synchronet supported @-codes. See the Synchronet
sysop manual for the definition of @-codes and their usage.

PRINT_LOCAL <str>
-----------------
This function works identical to the PRINT function with the exception that
the output is only displayed locally (on the BBS console).

PRINT_REMOTE <str>
------------------
This function works identical to the PRINT function with the exception that
the output is only displayed remotely (on the user's terminal). If the current
user is not logged on remotely, then no output is performed.

PRINTSTR
--------
This function works identical to the PRINT function with the exception that
this function does not accept a string argument, and instead uses the current
string variable (set with SETSTR, GETSTR, or similar function) as the character
string to print.

Example:
		SETSTR "hello, world\r\n"
		PRINTSTR

PRINTKEY
--------
This function displays the current command key. The command key is normally
obtained with the GETKEY, GETCMD, or similar function.

MNEMONICS <str>
---------------
This function works identical to the PRINT function with the exception that
the output is automatically colorized and characters following a tilde (~)
are considered a mnemonic command character (hot key) and are high-lighted
or placed in parentheses if the user's terminal does not support ANSI. If
Ctrl-A codes are included in the str argument, then the automatic colorization
and high-lighting is not used.

Example:
		mnemonics "Select: ~Good, ~Bad, or ~Indifferent: "

CLS
---
This function clears the user's text screen (both locally and remotely, if
applicable).

CRLF
----
This function displays a carriage return/line feed (new line). It is equivalent
to PRINT "\r\n", but requires less memory and executes faster.

PRINTFILE <str>
---------------
Displays the contents of the file 'str' to the user (both locally and remotely,
if applicable).

Example:
		PRINTFILE C:\TEXT\HELP.TXT

PRINTFILE_STR
-------------
This function is indentical to the PRINTFILE function, with the exception that
there is no argument, the current string is used for the path and filename
instead.

PRINTFILE_LOCAL <str>
---------------------
This function works identical to the PRINTFILE function, with the exception
that the contents are only displayed locally.

PRINTFILE_REMOTE <str>
----------------------
This function works identical to the PRINTFILE function, with the exception
that the contents are only displayed remotely. If the user is not logged on
remotely, then no output is performed.

LIST_TEXT_FILE
--------------
This function works similar to the PRINTFILE function, with the exception
that the system password is required when run remotely and the user is prompted
to enter the path and name of the file to list.

EDIT_TEXT_FILE
--------------
This function is generally for sysop use only. It will automatically prompt
the user (if remote) for the system password, and then prompt them for the
path and name of the file to edit.

PAUSE
-----
This function produces a "[Hit a key]" prompt and waits for the user to hit a
key.

MENU <str>
----------
This function is similar to the PRINTFILE function with the exception that the
TEXT\MENU directory is assumed to be the root path for the file and the file's
extension (.ASC, .ANS, .MON, or .RIP) should not be specified. This function
will automatically display the correct file based on the what the user's
terminal supports and which menu files are available. To display a menu file
in a different directory, a sub-directory can be specified before the filename.
For example, do display the MAIN.* menu file in the TEXT\MENU\SIMPLE directory,
you would use the following:

	MENU SIMPLE\MAIN

To display the MAIN.* menu file in the TEXT\MENU directory, you would use the
following:

	MENU MAIN

You can also change the default menu directory with the SET_MENU_DIR function.
Using the SET_MENU_FILE function, you can override the location and filename
for MENUs that are displayed from within core functions of Synchronet.

NODELIST_ALL
------------
This function displays the current status of all nodes.

NODELIST_USERS
--------------
This function displays the current status of all nodes that are in use.

USERLIST_SUB
------------
This function displays all users that have access to the current message
sub-board.

USERLIST_DIR
------------
This function displays all users that have access to the current file
directory.

USERLIST_ALL
------------
This function displays all users that have active accounts on the BBS.

USERLIST_LOGONS
---------------
This function displays a list of the users who have logged on today.

YES_NO <str>
------------
This function displays the C type string argument 'str' with automatic
colorization followed by the text " (Y/n) ? " and waits for the user to
hit 'Y', 'N' or CR. If CR (enter) is hit, then 'Y' is assumed. If the answer
to the prompt is 'Y', then the current logic state is set to TRUE, otherwise
it is set to FALSE.

Example:
		YES_NO "Logoff Now"
		IF_TRUE
			LOGOFF
			END_IF

NO_YES <str>
------------
This function is identical to the YES_NO function with the exception that the
string is followed by text " (y/N) ? " and if CR is hit, then 'N' is assumed.
If the answer to the prompt is 'N', then the current logic state is set to
TRUE, otherwise it is set to FALSE.

Example:
		NO_YES "Logoff Now"
		IF_FALSE
			LOGOFF
			END_IF

Input Functions
===============
&&Input Functions
$$INPUT___
Input functions are used to obtain input data from the user (most often from
the user's keyboard).

GETKEY
------
Waits for a single key from the user. The key is converted to upper case (if
a letter) and becomes the current command key for instructions such as CMDKEY,
COMPARE_KEY, etc. The key is not echoed (displayed). Use the PRINTKEY function
to display a key accepted with this function.

GETKEYE
-------
This function is identical to the GETKEY function with the exception that
"slash commands" are allowed. That is, if the user hit's the slash (/) key,
then the slash is echoed and the system waits for another key from the user.
The second key is converted to upper case (if a letter) and the slash/key
combination becomes the current command key for instructions such as CMDKEY,
COMPARE_KEY, etc. The second key is not echoed (displayed). Use the PRINTKEY
function to display a key accepted with this function.

GETCMD <keys>
-------------
This function is very similar to the GETKEY function, except that the 'keys'
argument specifies the only valid key to be accepted. The keys arguments is
a C style string, so carriage return (ENTER) is specified with a \r. If, for
example, you wanted to allow the user to hit A, B, C or ENTER, then you would
use the following:

GETCMD "ABC\r"

When an allowed key is hit, the key is converted to upper case (if a letter)
and echoed (displayed) followed by a CRLF automatically. The key then becomes
the current command key for instructions such as CMDKEY, COMPARE_KEY, etc.

Ctrl-C will always be allowed, in which case the command key becomes ^C.

GETSTR <maxlen>
---------------
This function ("Get String"), is used to accept a string of characters from
the user. The 'maxlen' argument specifies the maximum length allowed for the
string. 'maxlen' should not exceed 79 characters for most uses. This function
allows the user to enter any valid ASCII characters to form command words,
sentences, etc. Control will not return to the shell until the user either
hits CR (ENTER) or Ctrl-C. The resultant string can then be used in functions
and instructions such as CMDSTR, COMPARE_STR, SHIFT_STR, XTRN_EXEC,
FILE_DOWNLOAD, etc.

GETLINE <maxlen>
----------------
This function is identical to GETSTR with the exception that an inverse line
is displayed to the user (if the user has an ANSI terminal) to show the maximum
length of the input string.

GETSTRUPR <maxlen>
------------------
This function ("Get String Upper") is identical to GETSTR with the exception
that the string is automatically converted to uppercase as the user types.

GETNAME <maxlen>
----------------
This function is identical to GETSTR with the exception that the string is
automatically converted to "Capitalized" words (as in a proper noun) as the
user types.

GETFILESPEC
-----------
This function is specifically used to accept a file specification (name and/or
wildcard characters) from the user. It will automatically display a prompt
similar to:

Filespec [*.*]:

before waiting for the user to input the file specification. If the user hits
CR, *.* is assumed to be the file specification. If a period is not included
in the string, a ".*" is automatically appended (so CR, "*" and "*.*" all
result in the same string: "*.*"). If the user enters "A*", the string becomes
"A*.*". If the user enters "A*." the string remains unchanged. If the user
hits Ctrl-C, the current logic state is set to FALSE. Otherwise, the logic
state is set to TRUE.

Example:

GETFILESPEC
IF_TRUE
	FILE_DOWNLOAD
	END_IF

GETLINES
--------
This function only has an effect if the user is logged on remotely, has
ANSI terminal capability and their screen lines set to "Auto-detect". It
sends an ANSI sequence to detect the number of screen lines in the text window
of the remote terminal and waits for a response.

GETNUM <maxnum>
---------------
This function is similar to GETSTR with the exception that it only excepts
numbers as input and automatically stops accepting input if the number being
input would exceed maxnum (maximum of 32767). The current string will contain
the number and the current logic state will be true unless the user hit 'Q',
Ctrl-C, or enter instead of a number.

GET_TEMPLATE <str>
------------------
This function is much line GETLINE except that an input template is passed
as an argument to this function. The template is useful when requiring the
user to input a string of a fixed format, like a date, for example. The
characters in the template have special meaning: N indicates only number can
be used in this position, A indicates only an alphabetic character, and !
indicates any character can be used in that position. Characters other than
N, A, or ! are automatically displayed and used in the current string in those
positions. The first character of the template must be either N, A, or !.
An example (date format):

GET_TEMPLATE NN/NN/NN

would require the user to input a two numbers, then automatically skip the
slash characters, two more numbers, skip the slash, then two more numbers.

Another example (Canadian postal code):

GET_TEMPLATE ANA NAN

would require the user to input a letter, then a number, another letter,
automatically skip the space, another number, another letter, and one more
number. No other characters (symbols or otherwise) would be allowed in the
string using the above template example.

CHKSYSPASS
----------
This function ("Check System Password") displays an SY: prompt to the user
and waits for the user to input the system password (with no echo). If the
password is correct, the current logic state is set to TRUE, otherwise it
is set to FALSE.

Miscellaneous Functions
=======================
&&Miscellaneous Functions
$$MISC____

SET_MENU_DIR <dir>
------------------
This function sets the default menu directory for the MENU function (normally
..\TEXT\MENU). This function is useful for globally changing the directory
where MENU files will be retrieved from (including internal Synchronet
functions that can not be modified with a shell). The following is an example
of how to use this function along with the MENU function:

# The next line would display ..\TEXT\MENU\MAIN.*
MENU MAIN

# Change the directory for menus

MENU_DIR ..\TEXT\MYMENUS

# This next line would now display ..\TEXT\MYMENUS\MAIN.*
MENU MAIN

SET_MENU_FILE <path\filename.ext>
---------------------------------
This function is used to OVERRIDE the filename specified for a menu displayed
in an internal Synchronet function. Example:

SET_MENU_FILE ..\TEXT\MYMENUS\EMAIL.RIP
MAIL_READ

SYNC
----
This function synchronizes the local and remote displays (waits for the remote
terminal to catch up), displays any internode messages waiting for this node,
and synchronizes the current node status with the shared node database file.
It should be called before all command prompts are displayed.

ASYNC
-----
This function is identical to the SYNC function with the exception that any
pending output (menu, text file, etc.) can be aborted by hitting any key.

PAUSE_RESET
-----------
This function resets the line counter used for the automatic screen pause
feature.

CLEAR_ABORT
-----------
This function clears the abort (Ctrl-C) status flag.

SHIFT_STR <len>
--------------
This function ("Shift String") shifts the current string (obtained with GETSTR
or similar function) to the left 'len' number of characters. If for example,
the user enters "HELLO" for a GETSTR function, a shell line of:

SHIFT_STR 1

would change the current string to "ELLO".

This function is most often used to parse command string arguments or "stacked"
commands.

SETSTR <str>
------------
This function sets the current string to the C type 'str' argument given.
This is useful when you want to use a function that uses the current string for
a variable, but don't want the user to have to enter that string (via GETSTR
or similar function). Example:

SETSTR NEWFILES.ZIP
FILE_DOWNLOAD

UNGETKEY
--------
This function puts the current command key into the input buffer to be the
next key retrieved with GETKEY, GETCMD, GETSTR, or similar functions.

UNGETSTR
--------
This function puts the entire contents of the current string (obtained with
GETSTR, SETSTR, or similar function) into the input buffer.

HANGUP
------
This function immediately disconnects and logs the user off.

EXEC <cmd>
----------
This function calls the operating system to spawn the 'cmd' command line
specified. Remote users will not see or be able to interact with the program
executed unless the program is aware of the remote user and is specifically
designed to be run remotely (i.e. DOORs).

If an internal DOS command is to be executed, a command processor must be
loaded. Example:

EXEC COMMAND /C COPY C:\FILES\NEWFILE.TXT C:\DOWNLOADS

Synchronet's command line specifiers can also be used:

EXEC %!dsz portx %u,%i sz file.zip

See the Synchronet sysop manual, appendix A for a list of valid specifiers.
When used from a command shell or module, %f will be replaced with the path
to the current file directory, and %s will be replaced with the current string
(obtained with GETSTR, SETSTR, or similar function).

EXEC_INT <cmd>
--------------
This function ("Execute with I/O intercepted") is identical to the EXEC
function with the exception that DOS I/O interrupts (screen output and keyboard
input) is intercepted and redirected to the COM port if the user is logged on
remotely. This allows programs that use standard DOS I/O for screen output
to be displayed remotely. Example:

EXEC_INT COMMAND /C DIR C:\FILES\*.TXT

EXEC_BIN <name>
---------------
This function loads and executes a Baja module. A .BIN file with the filename
specified as the 'name' argument must exist in the Synchronet EXEC directory
for this function. If for example, you want a shell to load and execute
MYMOD.BIN from your EXEC directory, you would add the following to one or more
command shells:

EXEC_BIN MYMOD

EXEC_XTRN <code>
----------------
This function executes the external program specified by it's internal code
with the 'code' argument. If an external program is not found with a matching
internal code or the user does not have access to that program, this function
does nothing.

LOG <str>
---------
This function writes the C type 'str' argument to the system's activity log
file for the current date if the user is logged on remotely.

LOGSTR
------
This function is identical to the LOG function with the exception that a
string argument is not used, but instead the current string (obtained with
GETSTR or similar function) is written to the system's activity log file.

LOGKEY
------
This function writes the current command key to the system's activity log file
for the current date if the user is logged on remotely.

LOGKEY_COMMA
------------
This function is identical to the LOGKEY function, with the exception that a
comma (,) is prepended to the command key to separate it visually from other
logged command keys.

NODE_ACTION <action>
--------------------
This function is used to set the current node status to either "At main menu"
or "At transfer menu". The valid arguments are either "MAIN" or "XFER"
respectively. Other valid node actions will be added to the list of valid
arguments in the near future.

INC_MAIN_CMDS
-------------
This function increments the "main menu command" counter that can be used in
ARS comparisons.

INC_FILE_CMDS
-------------
This function increments the "file menu command" counter that can be used in
ARS comparisons.

TOGGLE_USER_MISC <flags>
-----------------------
This function is used to toggle specific flags on or off for the current
user. One or more of the following flags can be toggled:

Flag		Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
EXPERT		Expert menu mode
DELETED 	Deleted user
INACTIVE	Inactive user
AUTOTERM	Automatic terminal type detection
ANSI		ANSI terminal
COLOR		Color terminal (ANSI)
RIP		RIPscrip terminal
NO_EXASCII	Extended ASCII not supported
UPAUSE		Automatic screen pause
SPIN		Spinning cursor
ANFSCAN 	Automatic new file scan
CLRSCRN 	Clear screen between messages
QUIET		Default to quiet mode (if 'Q' exempt)
BATCHFLAG	Batch flagging mode enabled
NETMAIL 	Forward E-mail to NetMail
CURSUB		Remember current sub-board and directory
ASK_NSCAN	Ask for new-scans at logon
ASK_SSCAN	Ask for your message scan at logon
COLDKEYS	Cold keys (CR required - opposite of Hot Keys)
EXTDESC 	Extended file descriptions in listings

You cannot specify if you want the flag turned ON or OFF with this command.
Use in combination with the COMPARE_USER_MISC function to specifically enable
or disable a miscellaneous flag.

COMPARE_USER_MISC <flags>
-------------------------
This function is used to compare the current user's miscellaneous flags to
the flags argument specified. The valid flags for the argument are identical
to those used for the TOGGLE_USER_MISC function. If all the flags specified
are ENABLED for the current user, then the current logic state is set to TRUE,
otherwise it is set to FALSE. Example to turn the NETMAIL misc flag OFF for
the current user:

COMPARE_USER_MISC NETMAIL
IF_TRUE
	TOGGLE_USER_MISC NETMAIL
	END_IF

TOGGLE_NODE_MISC <flags>
------------------------
This function is used to toggle the miscellaneous flags associated with the
current node. The valid flags are:

Flag		Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ANON		Anonymous node
LOCK		Locked node (sysop's and N exempt users only)
INTR		Interrupted node (log user off ASAP)
MSGW		Short message waiting for this node
POFF		Not available for paging
AOFF		No node activity alerts
UDAT		User data has been updated by another node
RRUN		Re-run this node after user logs off
EVENT		Run node daily event after user logs off
DOWN		Down this node after user logs off
NMSG		Node message waiting for this node
EXT		Extended status information available for this node

ADJUST_USER_CREDITS <adj>
-------------------------
This function is used to add or subtract credits from the current user. The
'adj' argument must be either a positive or negative number (in Kilobytes).
Example, to subtract 100K in credits from the current user:

ADJUST_USER_CREDITS -100

TOGGLE_USER_FLAG <set> <flag>
-----------------------------
This function is used to toggle the state of one of the current user's flags.
The first argument is a single character indicating the flag set. Valid
flag sets are 1, 2, 3, 4, E for exemption, or R for restriction. The
second argument is actual flag character to toggle (A through Z).

SET_USER_LEVEL <level>
----------------------
This function changes the current user's security level to the number passed
as the argument.

SET_USER_STRING <user_string>
-----------------------------
This fucntion changes one of the current user's text string fields to the
value of the current string. The user_string argument must be one of the
following:

ALIAS			User's alias or real name on real name based BBSs
REALNAME		User's real name or company name
HANDLE			User's chat handle
COMPUTER		User's computer type description
NOTE			User's note/Caller-ID
ADDRESS 		User's street address
LOCATION		User's city, state
ZIPCODE 		User's zip/postal code
PASSWORD		User's password
BIRTHDAY		User's birthday (MM/DD/YY or DD/MM/YY)
PHONE			User's phone number
MODEM			User's modem type description
COMMENT 		User's secret sysop comment

LOGOFF
------
This function prompts the user if they really wish to log off. If they
answer Yes, then any logoff events are executed and the LOGOFF menu file
is displayed before they are disconnected.

LOGOFF_FAST
-----------
This function immediately drops carrier and logs the user off. It differs
from the HANGUP function in that it performs a SYNC function, then it
immediately drops carrier, as opposed to the HANGUP function wich does not
perform a SYNC operation and has a buffer flush delay before actually
dropping carrier.

AUTO_MESSAGE
------------
This function allows the user to read and write to the auto-message. If the
user has the 'W' restriction, they will not be allowed to write to the
auto-message.

USER_DEFAULTS
-------------
This function takes the user to the default configuration menu where they
can modify their default settings (e.g. Terminal type, Command Shell, etc).
If the user selects a new command shell while in this function, the new
shell is loaded and executed immediately (from the top) instead of resuming
with the shell that originally called this function.

USER_EDIT
---------
This function is used to edit the user information for the user name or number
specified in the current string (set with SETSTR, GETSTR, or similar function).
Since almost all user information can be changed and other users can be
edited from this section, this is normally reserved as a "sysop only"
operation.

TEXT_FILE_SECTION
-----------------
This function takes the user to the General Text File section of the system.

XTRN_EXEC
---------
This function is identical to the EXEC_XTRN function with the exception that
the external program's internal code is contained in the current string (set
with SETSTR, GETSTR, or similar function) instead of an argument.

XTRN_SECTION
------------
This function takes the user to the external program section of the system.

MINUTE_BANK
-----------
This function allows the user to convert credits into minutes, or deposit
unused free minutes (if allowed) in their minute bank.

CHANGE_USER
-----------
This function prompts the user for the system password and if entered
correctly, then prompts them for the user name or number to change into.
This is normally reserved as a "sysop only" operation. After changing into
a "non-sysop" user, the temp sysop status is set so the user may change back
into the original or another user.

ANSI_CAPTURE
------------
This function enables the capture of ANSI terminal escape sequences when the
local capture (Alt-L) is in use. This is normally reserved as a "sysop only"
operation.

CHKFILE <file>
--------------
This function checks for the existence of the file parameter 'file'. The
'file' parameter should contain path and possibly drive specifications
(i.e. CHKFILE C:\MYDIR\MYFILE.TXT). If the file exists the current logic state
is set to TRUE, otherwise it is set to FALSE.

REPLACE_TEXT <#> <str>
----------------------
This function is used to replace a default internal text string (read from the
CTRL\TEXT.DAT file) in a shell or module. The first argument is the text number
to replace (see TEXTNUMS.DAT for the number of the text you wish to replace).
The second argument is the C type string to use in place the current one. All
text replacements are lost (back to default TEXT.DAT) when the user logs off.
Example, to replace the "[Hit a key]" prompt with a different string:

REPLACE_TEXT 563 "\1n\1h\1b{\1wPAUSE\1b} "

If you wish to globally replace a string (for all shells and modules), you may
want to just edit the CTRL\TEXT.DAT file directly instead.

Mail Functions
==============
&&Mail Functions
$$MAIL____
The following functions are related to private E-mail.

MAIL_READ
---------
This function retrieves and displays mail waiting in the box of the current
user, if any.

MAIL_READ_SENT
--------------
This function retrieves and displays mail that the current user has sent and
is still pending deletion in the box(es) of the recipient(s).

MAIL_READ_ALL
-------------
This function retrieves and displays all the e-mail on the system. This
function is normally reserved as a "sysop only" operation.

MAIL_SEND
---------
This function attempts to send mail to the user specified by the current string
(obtained with GETSTR, GETNAME, or similar function). If the user name or
number specified in the string cannot be located, the operation is aborted
and the current logic state is set to FALSE. If the user name or number is
located, the current logic state is set to TRUE. Example usage:

PRINT "Send mail to who? "
GETNAME 25
MAIL_SEND

MAIL_SEND_FILE
--------------
This function is identical to the MAIL_SEND function with the exception that
a file attachment is included with the mail message.

MAIL_SEND_BULK
--------------
This function is used to send bulk (multiple destination) mail. The function
is normally reserved as a "sysop only" operation, but some sysops may want
some or all users to have the ability to send bulk mail.

MAIL_SEND_FEEDBACK
------------------
This function is identical to the MAIL_SEND function with the exception that
"Re: Feedback" is placed at the top of the mail message.

MAIL_SEND_NETMAIL
-----------------
This function prompts the user for a username and netmail address. If the
user just hits CR, the current logic state is set to FALSE, otherwise a NetMail
operation is attempted and the logic state is set to TRUE.

MAIL_SEND_NETFILE
-----------------
This function is identical to the MAIL_SEND_NETMAIL function with the exception
that if the NetMail file attachments are allowed, this function will allow the
user to send an attached file to a netmail message (for FidoNet or Internet).

Message Base Functions
======================
&&Message Base Functions
$$MESSAGE_
The following functions are related to the system's message base.

MSG_SET_AREA
------------
This function uses the current string (obtained with GETSTR, SETSTR, or
similar function) to search all sub-boards the current user has access to
for an internal code matching the current string. If the internal code is
found, that sub-board becomes the current sub-board and the current logic
state is set to TRUE, otherwise it is set to FALSE and the current sub-board
remains unchanged.

MSG_SELECT_AREA
---------------
This function prompts the user to select a message group (if the user has
access to more than one) and sub-board. If the user aborts the selection,
the current logic state is set to FALSE and the current sub-board is unchanged.
Otherwise, the logic state is set to TRUE and the selected sub-board becomes
the current sub-board.

MSG_SHOW_GROUPS
---------------
This function displays a list of message groups the current user has access to.

MSG_SHOW_SUBBOARDS
------------------
This function displays a list of sub-boards within the current message group
that the user has access to.

MSG_GROUP_UP
------------
This function moves the current message group up by one. If already at the
highest group, then it wraps to the first group.

MSG_GROUP_DOWN
--------------
This function is the opposite of the MSG_GROUP_UP function.

MSG_SUBBOARD_UP
---------------
This function moves the current message sub-board up by one. If already at
the highest sub-board in the current group, it wraps to the first sub-board
in the current group.

MSG_SUBBOARD_DOWN
-----------------
This function is the opposite of the MSG_SUBBOARD_UP function.

MSG_GET_SUB_NUM
---------------
This function accepts a number from the user to change the current sub-board.

MSG_GET_GRP_NUM
---------------
This function accepts a number from the user to change the current message
group.

MSG_READ
--------
This function is used to read messages in the current sub-board. If the
read is aborted, the current logic state is set to FALSE, otherwise it is set
to TRUE.

MSG_POST
--------
This function attempts to post a message on the current sub-board. If the user
does not have posting access on the current sub-board or the posted is aborted,
the current logic state is set to FALSE, otherwise it is set to TRUE.

MSG_QWK
-------
This function puts the user in the QWK message packet section.

MSG_PTRS_CFG
------------
This function allows the user to manipulate their new-message scan pointers.

MSG_PTRS_REINIT
---------------
This function resets the user's new-message scan pointers to their value at
logon.

MSG_NEW_SCAN_CFG
----------------
This function allows the user to manipulate their new-message scan
configuration.

MSG_NEW_SCAN
------------
This function performs a new message scan on either the current sub-board,
current message group, or all sub-boards.

MSG_NEW_SCAN_ALL
----------------
This function performs a new message scan on all sub-boards.

MSG_CONT_SCAN
-------------
This function performs a continuous new message scan on either the current
sub-board, current message group, or all sub-boards.

MSG_CONT_SCAN_ALL
-----------------
This function performs a continuous new message scan on all sub-boards.

MSG_BROWSE_SCAN
---------------
This function is identical to the MSG_NEW_SCAN function, with the exception
that if there are no new messages in a sub-board, the last message posted
will be displayed.

MSG_BROWSE_SCAN_ALL
-------------------
This function performs a browse scan on all sub-boards.

MSG_FIND_TEXT
-------------
This function prompts for a search string from the user and searches the
current sub-board, current group, or all sub-boards for the text.

MSG_FIND_TEXT_ALL
-----------------
This function performs a text search on all sub-boards.

MSG_YOUR_SCAN_CFG
-----------------
This function allows the user to configure their un-read personal message
scan.

MSG_YOUR_SCAN
-------------
This function peforms an un-read personal message scan on the current
sub-board, current message group, or all sub-boards.

MSG_YOUR_SCAN_ALL
-----------------
This function peforms an un-read personal message scan on all sub-boards.

File Base Functions
===================
&&File Base Functions
$$FILE____

FILE_SET_AREA
-------------
This function uses the current string (obtained with GETSTR, SETSTR, or
similar function) to search all directories the current user has access to
for an internal code matching the current string. If the internal code is
found, that directory becomes the current directory and the current logic
state is set to TRUE, otherwise it is set to FALSE and the current directory
remains unchanged.

FILE_SELECT_AREA
---------------
This function prompts the user to select a file library (if the user has
access to more than one) and directory. If the user aborts the selection,
the current logic state is set to FALSE the current directory is unchanged.
Otherwise, the logic state is set to TRUE and the selected directory becomes
the current directory.

FILE_SHOW_LIBRARIES
-------------------
This function displays a list of all file libraries the current user has
access to.

FILE_SHOW_DIRECTORIES
---------------------
This function displays a list of all directories within the current library
that the user has access to.

FILE_LIBRARY_UP
---------------
This function increments the current file library. If already at the last
library, it will wrap to the first library.

FILE_LIBRARY_DOWN
-----------------
This function is the opposite of teh FILE_LIBRARY_UP function.

FILE_DIRECTORY_UP
-----------------
This function increments the current file directory. If already at the last
directory in the current library, it will wrap to the first directory of the
library.

FILE_DIRECTORY_DOWN
-------------------
This function is the opposite of the FILE_DIRECTORY_UP function.

FILE_GET_DIR_NUM
----------------
This function waits for the user to enter a number to be used to change the
current file directory.

FILE_GET_LIB_NUM
----------------
This function waits for the user to enter a number to be used to change the
current file library.

FILE_LIST
---------
This function displays the contents matching the filespec contained in the
current string (obtained with GETFILESPEC, GETSTR, or similar function)
of the current file directory. If the listing is aborted, the current logic
state is set to FALSE, otherwise it is set to TRUE. Example:

GETFILESPEC
IF_TRUE
	FILE_LIST
	END_IF

FILE_LIST_EXTENDED
------------------
This function displays the extended information about the files in the current
directory that match the filespec contained in the current string (obtained
with GETFILESPEC, GETSTR, or similar function).

FILE_VIEW
---------
This function views the contents of the files that match the filespec in the
current string.

FILE_UPLOAD
-----------
This function attempts to upload to the current file directory. If the user
cannot upload for some reason, the current logic state is set to FALSE.
Otherwise, it is set to TRUE.

FILE_UPLOAD_USER
----------------
This function allows a user to upload a file specifically to another user,
provided the sysop has created a "User" file transfer directory for
user-to-user transfers. If the user cannot upload to the user directory or one
doesn't exist, the current logic state is set to FALSE, otherwise it set to
TRUE.

FILE_UPLOAD_SYSOP
-----------------
This function allows the user to upload file to the invisible sysop directory.
If ther user does not have upload access to the sysop directory or a sysop
directory has not been created, the current logic state is set to FALSE,
otherwise, it is set to TRUE.

FILE_DOWNLOAD
-------------
This function attempts to download all files matching the filespec contained
in the current string (obtained with GETFILESPEC, GETSTR, or similar function).

FILE_DOWNLOAD_USER
------------------
This function attempts to download any user-to-user files pending for the
current user. If there are no files waiting for the user or the user does not
have download access to the user directory, the current logic state is set
to FALSE, otherwise it is set to TRUE.

FILE_DOWNLOAD_BATCH
-------------------
This function attempts to download any files in the batch download queue.
If there are no files in the queue or the user answer No to the question if
they wish to download the files now, then the current logic state is set to
FALSE. If there are files in the queue and the user answers Yes to the question
if they wish to download the files, then the logic state is set to TRUE.

FILE_REMOVE
-----------
This function attempts to remove any files the user has uploaded (unless
R exempt) that match the filespec contained in the current string (obtained
with GETFILESPEC, GETSTR, or similar function).

FILE_BATCH_ADD
--------------
This function attempts to add the filename contained in the current string
to the batch download queue. If the filename is not found, the current logic
state is set to false.

FILE_BATCH_CLEAR
----------------
This function clears the current batch download queue.

FILE_BATCH_SECTION
------------------
This function takes the user to the Batch/Bi-dir transfer menu where they
can edit the batch queues and initiate batch or bi-directional file transfers.

FILE_TEMP_SECTION
-----------------
This function takes the user to the temporary archive menu where they can
extract archives, create file listings, and compress temporary files for
download.

FILE_NEW_SCAN
-------------
This function scans the current directory, current library, or all directories
for new files.

FILE_NEW_SCAN_ALL
-----------------
This function scan all directories for new files.

FILE_FIND_TEXT
--------------
This function prompts the user to enter a search string which is used in a
text search of all file descriptions in the current directory, current library,
or all directories.

FILE_FIND_TEXT_ALL
------------------
This function prompts the user for a search string to use in a text search
of file descriptions in all directories.

FILE_FIND_NAME
--------------
This function prompts the user for a filespec and searches the current
directory, current library, or all directories for files matching the
specification.

FILE_FIND_NAME_ALL
------------------
This function prompts the user for a filespec and searches all directories for
files matching that specification.

FILE_PTRS_CFG
-------------
This function allows the user to change their new file scan date/time. If the
pointer is changed, the current logic state is set to TRUE, otherwise it is
set to FALSE.

FILE_SET_ALT_PATH
-----------------
This function sets the current upload path to the alternate path number
contained in the current string (obtained with GETSTR or similar function).
This function is normally reserved as a "sysop only" operation, used to
upload files on CD-ROM in most cases.

FILE_RESORT_DIRECTORY
---------------------
This function is used to resort (if directory's sort order or type has changed)
and compress (if any deleted file slots exist) the current directory, current
library or all directories. All other nodes must be inactive for this function
to work. The current string must be set (with SETSTR, GETSTR, or similar
function) to "ALL" (resort all directories), "LIB" (resort current library),
or "" (current directory only).

FILE_GET
--------
This function is used to remotely download a file that is not in the file
database. This function is normally reserved as a "sysop only" operation.
The path and filename to be downloaded are contained in the current string
(obtained with GETSTR, SETSTR, or similar function).

FILE_PUT
--------
This function is used to remotely upload a file to the system's hard disk,
but not place the file in the file database. This is normally reserved as a
"sysop only" operation. The path and filename to be uploaded are contained in
the current string.

FILE_UPLOAD_BULK
----------------
This function is used to do a local bulk upload of files that are in the
physical DOS directory, but not already in the file database. This is normally
reserved as a "sysop only" operation. If the current string is set to "ALL",
then all directories will be scanned, "LIB" then only the current library,
and "" indicates only the current directory.

FILE_FIND_OLD
-------------
This function is used to search directories for files that have not be
downloaded since the current new file scan date (set with FILE_PTRS_CFG).
For each file that is found, the user is prompted if they wish to remove the
file. This is normally reserved as a "sysop only" operation. If the current
string is set to "ALL", then all directories will be scanned "LIB" indicates
only the current library, and "" indicates only the current directory.

FILE_FIND_OPEN
--------------
This function searches for file records that are currently open. This function
should not be used with other nodes in use. For each open file that is found,
the user is prompted if they wish to close the file record. As with the
FILE_FIND_OLD function, the current string must contain "ALL", "LIB", or ""
to specify the search range.

FILE_FIND_OFFLINE
-----------------
This function searches for files that are in the database, but not in the
physical DOS directory. For each open file that is found, the user is prompted
if they wish to move or remove the file. This normally reserved as a "sysop
only" operation. As with the FILE_FIND_OLD function, the current string must
contain "ALL", "LIB", or "" to specify the search range.

FILE_FIND_OLD_UPLOADS
---------------------
This function search for files that were uploaded before the current new
scan date (set with FILE_PTRS_CFG). For each file that is found, the user is
prompted if they wish to remove the file. This is normally reserved as a
"sysop only" operation. As with the FILE_FIND_OLD function, the current string
must contain "ALL", "LIB", or "" to specify the search range.

Chat Functions
==============
&&Chat Functions
$$CHAT____
The following functions are chat related in nature.

PAGE_SYSOP
----------
This function is used to page the sysop at the local console.

PRIVATE_CHAT
------------
This function is used to initiate private node-to-node chat.

PRIVATE_MESSAGE
---------------
This function is used for private internode messages, telegrams, or chat.
Same as the Ctrl-P initiated function.

CHAT_SECTION
------------
This function takes the user immediately to the chat menu where they can
join multinode chat and perform various other chat related operations.

Information Functions
=====================
&&Information Functions
$$INFO____

INFO_SYSTEM
-----------
This function displays various system information.

INFO_SUBBOARD
-------------
This function displays information about the current message sub-board.

INFO_DIRECTORY
--------------
This function displays information about the current file directory.

INFO_USER
---------
This function displays information about the current user.

INFO_VERSION
------------
This function displays version information about the system software.

INFO_XFER_POLICY
----------------
This function displays the system's transfer policy.

GURU_LOG
--------
This function displays the GURU.LOG file from the DATA directory and prompts
the user if they wish to delete the log. This is normally reserved as a
"sysop only" operation.

ERROR_LOG
---------
This function displays the ERROR.LOG file from the DATA directory and prompts
the user if they wish to delete the log and/or clear the error counters for
the nodes. This is normally reserved as a "sysop only" operation.

SYSTEM_LOG
----------
This function displays the system's detailed activity log for the current date.
This is normally reserved as a "sysop only" operation.

SYSTEM_YLOG
-----------
This function displays the system's detailed activity log for the previous day.
This is normally reserved as a "sysop only" operation.

SYSTEM_STATS
------------
This function displays cumulative system usage statistics.
This is normally reserved as a "sysop only" operation.

NODE_STATS
----------
This function displays cumulative usage statistics for the current node.
This is normally reserved as a "sysop only" operation.

SHOW_MEM
--------
This function displays the amount of free memory available.
This is normally reserved as a "sysop only" operation.

Instructions
============
&&Instructions
$$INSTRUCT
Instructions are loosely defined as code lines that have no direct input from
or output to the user, but instead control the flow of the code or other
low-level operations.

GOTO <label>
------------
This instruction is used to immediately jump to another part of the code. A
valid label name must follow GOTO as an argument. This instruction is very
similar to the GOTO command used in the BASIC and C programming languages or
the JMP instruction used in the Assembly programming language.

CALL <label>
------------
This instruction is identical to the GOTO instruction with the exception that
control will return to the next line of the code after a RETURN instruction
is executed in the block of code following the label. This is often referred
to as a sub-routine or procedure. The CALL instruction is very similar to
the GOSUB command used in the BASIC programming langauge or the CALL
instruction used in the Assembly programming language. At least one RETURN
instruction must exist in the sub-routine. Sub-routines should not use a
GOTO instruction to "jump out" of the sub-routine.

RETURN
------
This instruction is used to exit a sub-routine and return to the point in the
code from which it was called with the CALL instruction. If a RETURN
instruction is executed without a prior CALL, then the shell or module is
immediately terminated. If a shell is terminated with a user online, they
are immediately logged off. If a module is terminated, execution control
returns to the shell that loaded the module with an EXEC_BIN instruction.

SETLOGIC <TRUE or FALSE>
------------------------
This instruction is used to set the current state of logic to either TRUE
or FALSE. The logic state is set by many functions and instructions, and tested
by the IF_TRUE and IF_FALSE instructions to control the flow of execution.
The word TRUE or FALSE must follow the SETLOGIC instruction.

IF_TRUE
-------
If the current logic state is set to TRUE, then following block of code
(ending in an END_IF or ELSE instruction) will be executed. Otherwise,
Synchronet will skip the code until an ELSE or END_IF instruction is found
and resume execution from that point.

IF_FALSE
--------
This instruction is identical to the IF_TRUE instruction except that is
works in the opposite manor in regards to the current logic state.

ELSE
----
This instruction marks the end of an IF_TRUE or IF_FALSE block of code and
begins an alternate block of code to be executed if the condition is not
met for the IF_TRUE or IF_FALSE instruction. The block of code is terminated
with an END_IF instruction.

END_IF
------
This instruction is used to terminate an IF_TRUE, IF_FALSE, or ELSE code
block. Every IF_TRUE and IF_FALSE instruction must be followed by an ELSE
or END_IF instuction, and every ELSE instruction must be followed by
an END_IF.

CMD_HOME
--------
This instruction (called "Command Home") is very similar to a label. It is
a convenience instruction for programming menu commands. It sets a return
point (or anchor, if you will) for the automatic looping on a specific menu.
Execution control is returned to the point in the code where the last CMD_HOME
was specified by the END_CMD instruction.

CMDKEY <key>
------------
This instruction (called "Command Key") is like a combination of the
COMPARE_KEY and IF_TRUE instructions. It is usually immediately preceded by
a GETCMD, GETKEY, GETSTR or similar instruction.

The key argument is a single key to be used for the comparison. The key is not
case sensitive. Control keys can be specified by prepending the carot (^)
symbol (e.g. The escape key or Ctrl-[ would be specified as ^[, Carriage Return
or Ctrl-M woud be specified as ^M). Slash keys can be specified by prepending
the slash (/) symbol. When preceded by the CMDSTR instruction, the first
character (or two in the case of slash characters) of the string are considered
the current command key.

If the current command key matches the key argument, then the block of code
following (terminated with an END_CMD instruction) will be executed. When the
END_CMD instruction is executed, execution control returns the most recently
executed CMD_HOME instruction. If a RETURN or GOTO instruction will be executed
before the END_CMD instruction, then a CMD_POP instruction must be executed to
tell Synchronet to "forget" the previous CMD_HOME instruction. Even if
execution control will cause the END_CMD instruction to never be executed,
it still must be present to define the code block so that it can be skipped
if the CMDKEY comparison is false.

CMDSTR <str>
------------
This instruction (called "Command Str") is identical to the CMDKEY instruction
with the exception that the argument is a C type string. It is usually
immediately preceded by a GETSTR or similar instruction.

END_CMD
-------
This instruction is used to mark the end of a CMDKEY or CMDSTR code block.

CMD_POP
-------
This instruction tells Synchronet to "forget" the most recently executed
CMD_HOME instruction. It should only be used when a CMDSTR or CMDKEY code block
contains a GOTO or RETURN instruction.

COMPARE_KEY <key>
-----------------
This instruction is identcal to the CMDKEY instruction in regards to the
key argument. The current command key is set by the GETCMD, GETKEY, GETSTR
or similar instructions. If the current command key matches the key argument,
the current logic state is set to TRUE, otherwise it is set to FALSE.

As with all COMPARE instructions, it is usually immediately followed by an
IF_TRUE or IF_FALSE instruction.

COMPARE_STR <str>
-----------------
This instruction compares the current string (set by the SETSTR, GETSTR, or
similar instructions) against the C type string argument and sets the current
logic state to TRUE or FALSE accordingly. The comparison is not case
sensitive.

COMPARE_WORD <str>
------------------
This instruction is identical to the COMPARE_STR instruction with the
exception that the current string must only match the string argument for
as many characters as included in the string argument.

If for example, the current string is "OPEN BLACKJACK" the the line:

COMPARE_WORD "OPEN"

would set the current logic state to TRUE since the first 5 characters of
each string match, but the line:

COMPARE_STR "OPEN"

would set the current logic state to FALSE since the strings do not entirely
match.

COMPARE_ARS <str>
-----------------
This instruction compares the requirement string argument 'str' against the
information on the current user and sets the current logic state to either
TRUE or FALSE based on the result of the comparison. See the ARS chapter of
the Synchronet sysop manual for details on the syntax of ARS.

Example:
		COMPARE_ARS LEVEL 60
		IF_TRUE
			PRINT "You have level 60 or higher.\r\n"
			END_IF

Quick Reference
===============
&&Quick Reference
$$QUICKREF

Display Functions
-----------------
PRINT <str>
PRINT_LOCAL <str>
PRINT_REMOTE <str>
PRINTSTR
PRINTKEY
MNEMONICS <str>
CLS
CRLF
PRINTFILE <str>
PRINTFILE_STR
PRINTFILE_LOCAL <str>
PRINTFILE_REMOTE <str>
LIST_TEXT_FILE
EDIT_TEXT_FILE
PAUSE
MENU <str>
NODELIST_ALL
NODELIST_USERS
USERLIST_SUB
USERLIST_DIR
USERLIST_ALL
USERLIST_LOGONS
YES_NO <str>
NO_YES <str>

Input Functions
---------------
GETKEY
GETKEYE
GETCMD <keys>
GETSTR <maxlen>
GETLINE <maxlen>
GETSTRUPR <maxlen>
GETNAME <maxlen>
GETFILESPEC
GETLINES
GETNUM <maxnum>
GET_TEMPLATE <str>
CHKSYSPASS

Miscellaneous Functions
-----------------------
SET_MENU_DIR <dir>
SET_MENU_FILE <path\filename.ext>
SYNC
ASYNC
PAUSE_RESET
CLEAR_ABORT
SHIFT_STR <len>
SETSTR <str>
UNGETKEY
UNGETSTR
HANGUP
EXEC <cmd>
EXEC_INT <cmd>
EXEC_BIN <name>
EXEC_XTRN <code>
LOG <str>
LOGSTR
LOGKEY
LOGKEY_COMMA
NODE_ACTION <action>
INC_MAIN_CMDS
INC_FILE_CMDS
TOGGLE_USER_MISC <flags>
COMPARE_USER_MISC <flags>
TOGGLE_NODE_MISC <flags>
ADJUST_USER_CREDITS <adj>
TOGGLE_USER_FLAG <set> <flag>
SET_USER_LEVEL <level>
SET_USER_STRING <user_string>
LOGOFF
LOGOFF_FAST
AUTO_MESSAGE
USER_DEFAULTS
USER_EDIT
TEXT_FILE_SECTION
XTRN_EXEC
XTRN_SECTION
MINUTE_BANK
CHANGE_USER
ANSI_CAPTURE
CHKFILE
REPLACE_TXT <#> <str>

Mail Functions
--------------
MAIL_READ
MAIL_READ_SENT
MAIL_READ_ALL
MAIL_SEND
MAIL_SEND_FILE
MAIL_SEND_BULK
MAIL_SEND_FEEDBACK
MAIL_SEND_NETMAIL
MAIL_SEND_NETFILE

Message Base Functions
----------------------
MSG_SET_AREA
MSG_SELECT_AREA
MSG_SHOW_GROUPS
MSG_SHOW_SUBBOARDS
MSG_GROUP_UP
MSG_GROUP_DOWN
MSG_SUBBOARD_UP
MSG_SUBBOARD_DOWN
MSG_GET_SUB_NUM
MSG_GET_GRP_NUM
MSG_READ
MSG_POST
MSG_QWK
MSG_PTRS_CFG
MSG_PTRS_REINIT
MSG_NEW_SCAN_CFG
MSG_NEW_SCAN
MSG_NEW_SCAN_ALL
MSG_CONT_SCAN
MSG_CONT_SCAN_ALL
MSG_BROWSE_SCAN
MSG_BROWSE_SCAN_ALL
MSG_FIND_TEXT
MSG_FIND_TEXT_ALL
MSG_YOUR_SCAN_CFG
MSG_YOUR_SCAN
MSG_YOUR_SCAN_ALL

File Base Functions
-------------------
FILE_SET_AREA
FILE_SELECT_AREA
FILE_SHOW_LIBRARIES
FILE_SHOW_DIRECTORIES
FILE_LIBRARY_UP
FILE_LIBRARY_DOWN
FILE_DIRECTORY_UP
FILE_DIRECTORY_DOWN
FILE_GET_DIR_NUM
FILE_GET_LIB_NUM
FILE_LIST
FILE_LIST_EXTENDED
FILE_VIEW
FILE_UPLOAD
FILE_UPLOAD_USER
FILE_UPLOAD_SYSOP
FILE_DOWNLOAD
FILE_DOWNLOAD_USER
FILE_DOWNLOAD_BATCH
FILE_REMOVE
FILE_BATCH_ADD
FILE_BATCH_CLEAR
FILE_BATCH_SECTION
FILE_TEMP_SECTION
FILE_NEW_SCAN
FILE_NEW_SCAN_ALL
FILE_FIND_TEXT
FILE_FIND_TEXT_ALL
FILE_FIND_NAME
FILE_FIND_NAME_ALL
FILE_PTRS_CFG
FILE_SET_ALT_PATH
FILE_RESORT_DIRECTORY
FILE_GET
FILE_PUT
FILE_UPLOAD_BULK
FILE_FIND_OLD
FILE_FIND_OPEN
FILE_FIND_OFFLINE
FILE_FIND_OLD_UPLOADS

Chat Functions
--------------
PAGE_SYSOP
PRIVATE_CHAT
PRIVATE_MESSAGE
CHAT_SECTION

Information Functions
---------------------
INFO_SYSTEM
INFO_SUBBOARD
INFO_DIRECTORY
INFO_USER
INFO_VERSION
INFO_XFER_POLICY
GURU_LOG
ERROR_LOG
SYSTEM_LOG
SYSTEM_YLOG
SYSTEM_STATS
NODE_STATS
SHOW_MEM

Instructions
------------
GOTO <label>
CALL <label>
RETURN
SETLOGIC <TRUE or FALSE>
IF_TRUE
IF_FALSE
ELSE
END_IF
CMD_HOME
CMDKEY <key>
CMDSTR <str>
END_CMD
CMD_POP
COMPARE_KEY <key>
COMPARE_STR <str>
COMPARE_WORD <str>
COMPARE_ARS <str>


