home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Share Gallery 1
/
share_gal_1.zip
/
share_gal_1
/
CO
/
CO023A.ZIP
/
SX4-1.EXE
/
SAPPHIRE.DOC
< prev
next >
Wrap
Text File
|
1992-01-14
|
64KB
|
2,250 lines
S A P P H I R E
COMPUTER BULLETIN BOARD SYSTEM
Release: 4.00A
Operation Manual
PINNACLE SOFTWARE, Box 714 Airport Road, Swanton VT 05488 USA
PINNACLE SOFTWARE, CP 386 TMR, Quebec, Canada H3P 3C6
CUSTOMER SERVICE LINE (VOICE): (514) 345-9578
DATA LINE (9600 baud, V42bis): (514) 345-8654
=====================================
LEGAL NOTICES AND SUPPORT INFORMATION
=====================================
Shareware and Registration
--------------------------
This version of Sapphire is distributed as shareware. With respect to Sap-
phire, "shareware" means that you may try out the program for 45 days without
paying for it. If you continue to use it after that time, though, you are
indicating that the product fulfils your needs and as such you are legally
required to register it ($45). When you register Sapphire, you gain the
following benefits:
- You get a disk containing the most recent version of Sapphire available
- The "Program under evaluation" message disappears from your BBS
- You get bonus software sent along with the registered Sapphire
- You get substantial discounts on our other products
- You get privileged access to our free files BBS
- You get privileged access to our voice support line
- You get unscheduled news mailings and software samples
- You get access to Sapphire source code (extra fees may apply here)
- You help keep down the high cost of software -- by supporting shareware!
Shareware terms do not extend to the source code of Sapphire, nor to later
versions, nor accessories, unless they are declared as shareware by Pinnacle
Software.
Sapphire is Copyright (C) 1986, 1992 by Pinnacle Software.
Turbo Pascal is a Trademark of Borland International.
DSZ is a Trademark of Omen Technology.
ii
Support for Registered Sysops
-----------------------------
The Sapphire release number follows this pattern:
Version Number Internal ID
| |
4 . 0 0 A
/ \
Upgrade Level Correction Level
A registered Sapphire owner is entitled to operate any release of Sapphire with
the same Version and Upgrade Level, and the same or different Internal ID or
Correction Level. Thus, corrections to the program ("bug fixes") can be
obtained at no cost by downloading them from our support board, or for a $3
shipping fee, by mail.
Installation and Trouble-Shooting
---------------------------------
For complete information about installation and trouble-shooting, refer to the
INFO section of the SYSOP utility that accompanies Sapphire (type SYSOP at the
DOS prompt). The information there can be viewed online or printed to LPT1 or
LPT2.
If you are installing Sapphire for the first time, you may call Pinnacle
Software for assistance if you can not complete the basic installation success-
fully. But you may be able to save yourself time and long-distance charges:
experience has shown us that 90% of all installation problems can be solved by
the advice in the trouble-shooting section of the SYSOP utility.
Upgrading From Earlier Versions
-------------------------------
Refer to the INSTALL article in the INFO section of the SYSOP utility for
instructions for upgrading from earlier versions of Sapphire.
iii
=================
TABLE OF CONTENTS
=================
LEGAL NOTICES AND SUPPORT INFORMATION . . . . . . . . . . . . . . . . . . ii
Shareware and Registration
Support for Registered Sysops
Installation and Trouble-Shooting
Upgrading From Earlier Versions
BASIC SYSTEM OPERATION . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Duties of the System Operator
Signing on Locally
Signing on as SYSOP
Function Keys
The Status Line
Online Validation and Banishment
Yoo-Hoo and Rename
AUTO-MAINTENANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
User File Auto-Maintenance
Message File Auto-Maintenance
Library Auto-Maintenance
Files Auto-Maintenance
CUSTOMIZING YOUR SYSTEM'S APPEARANCE . . . . . . . . . . . . . . . . . . . 8
An Overview of Your Customization Options
Option 1. Configuration
Option 2. Application
Option 3. Hardware
Option 4. Stock Files
Option 5. Message Bases
Option 6. Doors and Events
Option 7. Custom Programming
CUSTOMIZING MEMBERSHIP LEVELS . . . . . . . . . . . . . . . . . . . . . . 13
Overview of Membership Levels
Why Change Anything?
The COMMANDS.LEV File
Default Membership Design
CUSTOMIZING STOCK FILES . . . . . . . . . . . . . . . . . . . . . . . . . 18
The Two Types of Stock Files
Drawing with Graphic Characters
Stock File Naming Convention
Stock File Commands
iv
DOORS AND EVENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Definitions
Applications for Event Processing
Applications for Doors Processing
Coding Your Batch Files
Writing Door and Event Programs
FILE TRANSFER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
What is File Transfer?
Installing File Transfer
Adding Software Locally
Adding Software Remotely
How Online Documentation Works
Transfer Protocols
MISCELLANEOUS TOPICS . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Gear Shift
Password Changes
Command Abbreviations
Additional Documentation
v
======================
BASIC SYSTEM OPERATION
======================
Duties of the System Operator
-----------------------------
The user-name for the System Operator is: SYSOP. You may prefer to sign up
with your real name and set yourself at the highest user level (level 8). As
the sysop, your main duty is to "validate" (grant membership to) new members.
You do this with Sapphire's VALIDATE command.
Signing on Locally
------------------
When Sapphire is waiting for a caller, press a key. This will "wake up"
Sapphire, and freeze out the modem by putting it "off-hook". You can then sign
on as if you had dialled up.
If you don't want your phone off the hook, you can start up Sapphire in
non-modem mode by selecting LOCAL in the SYSOP utility. This completely
ignores anything to do with the modem.
Signing on as SYSOP
-------------------
The information presented below is based on the default set-up. For security
reasons, the password shown here should be modified (using the BYE PASSWORD
command) as soon as possible.
1. Wait until Sapphire is waiting for a visitor.
2. Press a key to wake it up.
3. When asked for your name, press Space-bar, then Return.
4. When you are asked for the password, type SYSOP then Return.
You can then type Sapphire commands (the menu lists most of them; the HELP
command lists all of them), or press some function keys...
1
Function Keys
-------------
Sapphire's function keys are assigned as follows:
REGULAR FUNCTION KEYS
F 1 Function-key help. Also lists meanings of the status line icons.
F 2 Enable Yoo-Hoo. Makes a noise when a specified person shows up.
F 3 Removes 10 minutes online-time from whoever is connected.
F 4 Adds on 10 minutes online-time to whoever is connected.
F 5 Enable/Disable instant chat (type-to-sysop) via the CHAT command.
F 6 Break in to chat with the person who is currently online.
F 7 Not used.
F 8 Not used.
F 9 Modify number-of-hours-between-calls
F10 Sound effects on/off.
ALT FUNCTION KEYS
F 1 Turn printer on and off (uses LPT1).
F 2 Freeze out the person on the modem. You do this if you want to enter a
few quick commands on his behalf but don't want him to see what you are
typing. Press ALT-F2 again to restore communication.
F 3 Subtract 1 from the membership level of the person who is signed on.
F 4 Add 1 to the membership level of the person who is signed on.
F 5 Announce mode on/off. In announce mode, nobody can log on. All
people get to see is your sign-on logo, which is contained in the
text file LOGOXX.STD. This lets you run your BBS as a "News and
Announcements System".
F 6 Send file. This is used to transmit a text file -- usually while chat-
ting with a remote user. While the file is being transmitted, you can
cancel, pause or slow down the output in the usual ways (spacebar, "P" or
number keys, respectively).
2
F 7 Changes the name of the visitor to one that you specify. The new
name is checked to prevent duplication.
F 8 Instant banishment. Removes visitor from the valid caller list.
If you change your mind before he logs off, you can hit F8 again to
reinstate the user.
F 9 Shut-down. If nobody is signed on, Sapphire ends immediately. If
somebody is logged on, Sapphire will end when he or she logs off.
F10 Turn Ultra-Mode on or off. Ultra-Mode is a kind of "Super-Sysop"
mode. While in this mode, a user may...
- Execute commands of any level
- Use the CHANGE command on somebody else's message
- Read all private messages
- Call back in less than the usual time (Level 6+ can always do this)
- Skip around a devalidation message at sign-on and proceed normally
- Use the VALIDATE command on people at his level or higher
The user named SYSOP is automatically in Ultra-mode. Other users -- even
other Level 8 users -- must have it turned on explicitly by the ALT-F10
key. When ALT-F10 is pressed, a long, raucous sound is emitted from your
computer's speaker. This tends to discourage people from hitting the key
"by accident".
The Status Line
---------------
The top two lines of the Sapphire screen provide you with some information
about what is going on. The top line lists membership level, time left, state
icons (explained later), and the last item that went in the system log. The
second line lists the member's sign-on name and full name, and phone number.
The state icons are single-character indicators. You can think of them as
on/off lights, if you wish. For an short description of each icon, press the
F1 key. This displays a table describing each icon.
Here is a more detailed explanation of each icon:
Downwards-pointing triangle: The ALT-F9 key was pressed to put the system in
"shutdown mode" and will be closed when it next disconnects (i.e. when the
current visitor logs off).
Infinity symbol (sideways 8): Ultra-mode is on. This is turned on and off by
the ALT-F10 key.
Diamond: The system is waiting for somebody in particular to show up. You can
specify a list of names by pressing the F2 key.
3
Happy face: People who use the CHAT command will be placed directly in
conversation, instead of seeing an "unattended" message. This is handy if
somebody is online who usually asks you for a chat.
Question mark: the current user entered the CHAT command to try to get in
touch with you. The CHAT command makes a noise if you have sound turned on.
Exclamation mark: You pressed the ALT-F6 key to put the system into "announce
only" mode. People will only see the LOGOXX stock file before getting discon-
nected.
Double-note: Sound is on. Turn it on or off with the F10 key.
Triple-line: Printer is active. The printer (which should be connected to the
parallel port LPT1) is turned on or off by the ALT-F1 key.
These icons may take a while to get used to, but before long, you'll be able to
tell at a glance what's happening on your system.
Online Validation and Banishment
--------------------------------
ALT-F8 will banish the current visitor. However, the ALT-F8 key does not
update the file until the member disconnects, so if you have a system crash,
the file will still reflect the old value. In general, all data affecting a
member's current session is lost if your system crashes, since the members
information is written only "on the way out". For this reason, it is not
possible for a sysop-level member to banish himself!
If you press ALT-F8, but change your mind before the user logs off, you can
press the key one more time to reverse your decision.
Yoo-Hoo and Rename
------------------
If you intend to run a BBS that does not tolerate aliases, but insists that
people use real names, the combination of F2 (Yoo-Hoo) and ALT-F7 (Rename) will
prove useful.
When you press the Yoo-Hoo key, you will be prompted to enter a list of names,
separated by slashes. For example, you might enter:
Robert Libman/Rene Levesque/Elizabeth Mountbatten-Windsor
When somebody signs on under any of the indicated names, Sapphire will make a
distinctive noise to alert you.
4
You can then break in (using F6 -- Chat) and tell the person that you are
changing his sign-on name to his real name. This can be done with the Rename
key. The Rename function will not allow you to change the name to an existing
name. Thus, if you already have a John on your system, you can't change
somebody else's name to John.
5
================
AUTO-MAINTENANCE
================
Sapphire is designed to perform all maintenance tasks automatically. The
following "maintenance" sections are simply an explanation of how it does this,
so if you are browsing this manual for the first time, you can safely skip them
without any problem.
User File Auto-Maintenance
--------------------------
The user file will hold up to 350 user names. When a new user signs up,
Sapphire looks for an inactive user to replace. The higher the level of the
member, the longer it takes for him to be considered inactive. Here are the
required call-back times:
Level Time-Out (Days) Member Level Description
1 10 Non-Member
2 50 Basic Member
3 60 Special Member
4 70 Top Notch Member
5 80 Inner Circle Member
6 90 Aide-de-Sysop
7 100 Co-Sysop
8 110 Sysop
Note that this is only the time after which a user is eligible for replacement.
If there are no new sign-ups to replace his name on the list, his user-record
can remain valid forever.
The user named SYSOP is never eligible for replacement.
Message File Auto-Maintenance
-----------------------------
Sapphire maintains 225 message files. When the last one is used up, the first
one is replaced, thereby "deleting" the oldest one.
All messages share the same space. There is no way to preserve a message
permanently. If you have something you want to keep available for a long time,
place it in the library directory as a .TXT file and tell the members to use
the LIBRARY command to review it.
6
If you have to get rid of a message, use Sapphire's ERASE command. There is no
need to use DOS DEL or ERASE.
Library Auto-Maintenance
------------------------
Any .TXT file that appears in the Library directory will appear on the Library
list. The 39-character description of each article is taken from the first
line of each file (leading blanks are ignored).
Thus, you can add to the Library simply by copying text files into the Library
directory, and remove articles using the DOS DEL command. For your members'
convenience, you might sort the directory in reverse-date order, using a
utility such as Norton's DS command.
Files Auto-Maintenance
----------------------
Sapphire maintains a list of up to 500 uploads. When the list is full,
programs are dropped from the list and deleted from the file directory accord-
ing to a formula based on:
(A) Number of times the file has been downloaded
(B) How many days have elapsed since the last request
(C) How many days the file has been on the list
In other words, Sapphire will identify and replace the least popular file.
All files are protected from this auto-maintenance if they have seen some
activity (download, or the initial upload) in the past 14 days.
7
====================================
CUSTOMIZING YOUR SYSTEM'S APPEARANCE
====================================
Sapphire comes preconfigured as a "private online conversation club" named "The
Pinnacle Club". Some Sapphire sysops find this approach appropriate to their
requirements, so there are a few Pinnacle Clubs around the world.
After running the basic system for a while, many sysops decide to fine-tune its
function and appearance to suit their needs...
An Overview of Your Customization Options
-----------------------------------------
There are several areas of customization for you to consider, which are listed
below in order of increasing difficulty:
1. Configuration
2. Application
3. Hardware
4. Stock files
5. Message bases
6. Doors and events
7. Custom programming
These are described, in order, below.
8
Option 1. Configuration
------------------------
The configuration program (CONFIG on the main menu of the SYSOP utility) lets
you specify some general information about your hardware and how you want your
BBS to run. In particular, you may wish to change some of the following items:
1. Settings on the console ("Video settings" on the CONFIG menu)
- Use of color
- Number of lines displayed on the console (25, 43, or 50)
2. General preferences
- Console sound on/off
- Key click at the console
- Phone number format (e.g. 999-999-9999 or (999) 999-9999)
- Command prompt (e.g. ==> or "Enter your command now")
3. User settings ("Sign-up and security" on the CONFIG menu)
- Minimum baud-rate to sign on
- Length of time a user may spend on the system
Option 2. Application
----------------------
In deciding how to customize your system, you should keep in mind what goals
you have set. For example, if you are running a purely conversational system,
your users will benefit more from hearing your thoughts on the current topic
than they will if you spent time writing online documentation.
Similarly, if you are running a files system, your users want files, so your
time may be well spent reading shareware catalogs, or calling other systems.
In other words, sometimes the best customization is none at all. Because when
you come right down to it, BBS's are about people interacting, not text files.
In order to best support your system's goals, you may decide to change the
privileges accorded the various membership levels. For more information about
this, see the chapter entitled "Designing Membership Levels".
9
Option 3. Hardware
-------------------
Without a doubt, the easiest way to improve your BBS is to add a faster modem.
This attracts more members -- especially those who own fast modems, since they
tend to avoid systems that now seem "slow". Since people can move more data in
less time, the traffic on your system picks up, which in turn attracts more
traffic.
Sapphire supports modem speeds up to 19200, although at higher baud-rates you
may find that you need a faster computer. For example, although an old 4.77
Mhz XT can support 9600 baud calls, it doesn't actually send the text out at
that speed; the connection will look more like a 2400-baud connection.
TECHNICAL NOTE: The current version of Sapphire does not explicit-
ly support "locked baud rates", but you can simulate it by setting
all but one connect string to "XXX" (i.e. some nonsense string) and
the locked baud-rate as "CONNECT". This will cause all connections
to be interpreted as a connection at that speed. In order to do
this, though, you must be sure that your computer can support the
locked baud-rate. For example, you could not lock at 4.77 MHz XT
at 9600 baud; it would miss characters.
If you are running a file-transfer system, you can improve it by increasing the
disk space. When you increase your disk capacity, you should set your related
configuration items ("upload free space" and "maximum files") accordingly,
using the CONFIG option of the SYSOP utility.
Option 4. Stock Files
----------------------
The easiest and most immediately gratifying way to customize your system is to
modify the "Stock files". These are explained in the chapter entitled "Stock
Files".
Option 5. Message Bases
------------------------
A "message base" is a logical grouping of messages. For example, if your
system catered to dog breeders, you might group messages about Dalmatians
separately from messages about Spaniels. Thus, somebody with no interest in
Dalmatians would not have to read messages about that breed of dog.
In the preceding example, the messages were grouped by subject ("breed of
dog"). You may decide to group messages by some other criterion, such as how
10
long the person has been a member of your system, or how much they paid to
join.
Sapphire is initially configured with 5 general message bases, which group
messages according to membership level. That is to say, a Level 1 (lowest)
member has access to no message bases, a Level 2 member has access to one
message base, and so on. A Level 5 member has access to 5 message bases. (The
sysop, at Level 8, has access to all message bases.)
These message bases, along with three other special-case message bases, are
defined in a text file named MESSAGES.DEF. You can edit this file with a
standard text editor, such as DOS's EDLIN or EDIT, a programmer's editor, or a
word-processor in non-document (generic DOS text) mode.
The format of the file is literally self-explanatory, since the file itself
contains an explanation of its format. In order to view the file, enter the
following command at the DOS prompt:
SEE MESSAGES.DEF
The SEE command can also print the file. Before you modify the file, it is a
good idea to either print it out or make a backup copy. You can make a backup
copy by entering the following DOS command:
COPY MESSAGES.DEF MESSAGES.OLD
This creates a second copy of the file, named MESSAGES.OLD. Thus, if you make
a mistake and Sapphire no longer understands the file, you can restore it to
its original form with the command:
COPY MESSAGES.OLD MESSAGES.DEF
In general, the MESSAGES.DEF file allows you to define up to 15 message bases
(including logon announcements, feedback to sysop, and E-Mail).
After modifying the MESSAGES.DEF file, log on and use the command
==> BASES
to verify that the messages bases are set up the way you want. You can use the
level-change function keys (ALT-F3 and ALT-F4) to try the BASES command at each
membership level.
Option 6. Doors and Events
--------------------------
Doors and Events are covered in their own chapter, "Doors and Events", pre-
sented later in this manual.
11
Option 7. Custom Programming
-----------------------------
You might find that Sapphire is excellent for your application, but needs just
one little change to make it perfect. For example, you may have an idea for a
new command that you think your users would find exciting.
In such case, you will require some custom programming. We can do it for you,
or -- if you are familiar with Turbo Pascal -- you can do it yourself.
There is, of course, a cost associated with custom programming, but this cost
can frequently be lowered if your idea can be applied to other customers'
systems. For example, Sapphire's file download and message reading systems
were largely influenced by custom work. Since in each case the customer had a
good idea, we performed the modifications for an extremely low price.
Similarly, if you wish to purchase a source code license to make the modifica-
tions yourself, we are willing to offer discounts if your work has a wider
application. If you have a good idea and you are handy with Turbo Pascal, give
us a call!
12
=============================
CUSTOMIZING MEMBERSHIP LEVELS
=============================
Overview of Membership Levels
-----------------------------
Sapphire supports 8 membership levels. In general, these levels function as
follows:
Level 1 Non-members
Levels 2-5 Members
Levels 6-8 System operations staff
Each membership level has a set of privileges associated with it:
- Message bases that can be read (see previous chapter)
- Commands that can be used
For example, as initially configured, Sapphire provides a non-member (Level 1)
with the SEND command, but no READ command. This means that a non-member can
ask for greater access privileges ("tell us a bit more about yourself,
please!") but can not really use the system (i.e. read messages). A basic
member (Level 1) gets the READ command and (as defined in the MSGBASES.DEF
file) gets to use one message base.
The initial setup described above works well, because it forces new users to
type in a message. You'll find that you can judge just by reading that one
message, whether or not to make the person a full member.
Why Change Anything?
--------------------
No BBS design works for everybody! You may find it necessary to change the
initial configuration. For example, if you are a shareware author, you might
want to make the GET (i.e. download software) command available to non-members,
so that people can obtain your software without waiting around to become a full
member.
13
Or you might decide to give non-members their own message base, so you can
watch them in action. You could give them access to a message base by modify-
ing the MSGBASES.DEF file (as explained in the last chapter), but you would
also have to give them access to the READ command. You would do this by
modifying the COMMANDS.LEV file.
The COMMANDS.LEV File
---------------------
COMMANDS.LEV is a text file that defines the minimum membership level required
for each of the internal (non-door) commands that Sapphire supports.
You can edit COMMANDS.LEV with a standard text editor, such as DOS's EDLIN or
EDIT, a programmer's editor, or a word-processor in non-document (generic DOS
text) mode.
The format of the file is literally self-explanatory, since the file itself
contains an explanation of its format. In order to view the file, enter the
following command at the DOS prompt:
SEE COMMANDS.LEV
The SEE command can also print the file. Before you modify the file, it is a
good idea to either print it out or make a backup copy. You can make a backup
copy by entering the following DOS command:
COPY COMMANDS.LEV COMMANDS.OLD
This creates a second copy of the file, named COMMANDS.OLD. Thus, if you make
a mistake and Sapphire no longer understands the file, you can restore it to
its original form with the command:
COPY COMMANDS.OLD COMMANDS.LEV
After modifying the COMMANDS.LEV file, log on and use the command
==> HELP S
to verify that the commands are set up the way you want. You can use the
level-change function keys (ALT-F3 and ALT-F4) to try the HELP command at each
membership level.
14
Default Membership Design
-------------------------
Before designing your membership levels, you may find it helpful to understand
our rational is designing the default setup. This is explained below.
Level 1: Non-member
May post: Non-member message base
Commands: BYE Disconnect from system (i.e. logoff)
HELP Display a list of commands you can use
INFO Membership requirements for this system
SEND Leave a message for other users to read
SPECS Change the way things look around here
TIME Display how much time is left for visit
VERSION Display software version and copyright
Comments: Note the absence of the READ command. Note also that we do
NOT put the BASES command at this level. New users who try
out that command tend to get miffed and log off. It's better
for them to read the INFO article, and thus get some idea of
what you are trying to accomplish with your system.
Note: The BYE, TIME and VERSION command are locked at level 1 and
can not be assigned to a different membership level.
15
Level 2: Basic Member
May post/read: Non-member and Basic member message bases
May post: Feedback to Sysop message base
May read: Report from Sysop message base
Added commands: EXPERT Switch between casual and expert mode
BASES Summary of message bases you can use
GIMMICKS Describes various tricks for messages
GRAPHICS Switch graphic characters on and off
HINTS Tricks and tips for using this system
LIBRARY Browse and read in our online library
MESSAGES Quick summary of messages (time & user)
NAMES Specify names for selecting READ etc.
PROTOCOL Select method used for file transfer
READ Read new messages left by other users
REVIEW Inspect a single message by DATE:MINUTE
SET Modify the DATE:MINUTE for READ command
TEXT Specify text to reduce READ output etc.
USERS Display information about our users
Level 3: Special Member
Added base: Special Member
Added commands: ACTIVITY Display system activity for past 7 days
CHANGE Modify a message you've sent previously
FILES List software available for downloading
GET Get some software from our collection
GIVE Contribute software to our collection
MOVE Move a message from one base to another
Level 4: Top Notch Member
Added base: Top Notch
Added commands: CHAT Page system operator for a conversation
OBSERVE Overview of logon/logoff activity, etc.
Comments: Note that lower-level members, when doing the USERS command,
see Top Notch members listed as "Special". Top Notch messag-
ing is completely hidden from lower levels. The idea here is
to avoid displaying membership-level differences where it is
not relevant, while providing higher-level members with a
measure of privacy.
16
Level 5: Inner Circle Member
Added base: Inner Circle
Added commands: None
Comments: Lower-level members, when doing a USERS command, see an Inner
Circle member listed only as "Special" (or "Top Notch", in
the case of Level 4 members). Inner Circle messaging is
hidden from lower levels. See Level 4 for explanation.
Level 6: Aide-de-Sysop
Added commands: ERASE Remove message (resets it to time 0:0)
Comments: This level of authority allows people to keep the system tidy
without having access to personal member information, such as
phone numbers.
Level 7: Co-Sysop
May read: Feedback to Sysop
Added commands: BANISH Devalidate user (remove from user list)
DOORS Update your list of "Door" programs
DOS Shell out to DOS; type "EXIT" to return
DUMBTERM Start dumb terminal for outgoing calls
EVENTS Schedule your BBS's close-down events
PROBE Display user info (see also USERS cmd)
VALIDATE Grant a user a higher membership level
Comments: At this level, the USERS command gives more detailed informa-
tion, such as password and phone number. A co-sysop can run
the entire system remotely. He can not, however, find out
the sysop's password.
Level 8: Sysop
May post: Logon Announcements
Added commands: CLOSE Shut down system; prevent further calls
Comments: The user named "SYSOP" is automatically placed in "Ultra-
Mode". See the explanation of "Ultra-Mode" (Alt-F10) in the
"Function Keys" section.
17
=======================
CUSTOMIZING STOCK FILES
=======================
Stock files are files that contain "stock" (i.e. generic) text -- material that
is displayed frequently. For example, the BBS sign-on logo is contained a
stock file (named LOGOXX.STD). The welcoming message is also contained in a
stock file. And so on.
To modify a stock file, you need a text editor, such as DOS EDLIN or EDIT, or a
programmer's editor, or a word-processor in non-document (generic DOS text)
mode.
Each stock file contains text, and sometimes contains comments; any line that
begins with a semi-colon is not displayed when the stock file is shown.
In order to browse through the various stock files, enter the following command
at the DOS prompt:
SEE *.STD
This will let you select and display all files with a STD extension. (Stock
files also use the GRA extension.)
The SEE command can also print the file. Before you modify the file, it is a
good idea to either print it out or make a backup copy. You can make a backup
copy by entering the following DOS command:
COPY *.STD *.OLD
This creates a second copy of each stock file, named <filename>.OLD. (For
example, LOGOXX.STD would be duplicated in LOGOXX.OLD) Thus, if you make a
mistake and Sapphire no longer understands the file, you can restore it to its
original form with the command:
COPY <filename>.OLD <filename>.STD
18
The Two Types of Stock Files
----------------------------
Stock files come in two varieties, identified with the .STD and .GRA file
extensions...
EXTENSION MEANING
--------- -------
.STD Contains standard ASCII (no value greater than 128)
.GRA Contains IBM-PC extended ASCII ("graphics")
For example, a standard stock file might be named MAINXX.STD, while its graphic
equivalent would be named MAINXX.GRA.
A user will normally see only the standard stock files (i.e. those with a STD
extension). However, the user can use Sapphire's GRAPHICS command to turn on
the GRA stock files.
The current version of Sapphire does not explicitly support full ANSI stock
files (e.g. color changes and animation). The next version will address this
need.
For a description of the purpose of each stock file, select the INFO section on
the SYSOP utility main menu, then select FILES.
Drawing with Graphic Characters
-------------------------------
In order to put graphic (extended ASCII) characters into a .GRA stock file, you
can use one of the following methods:
1. Press and hold the ALT key, followed by three digits on the numeric
keypad. This lets you enter any extended ASCII character. For example,
to enter a solid block character, hold down ALT then press (on the
numeric keypad) 2, then 1, then 9. Release the ALT key.
The problem with this method is that it is more than a little cumbersome,
and it does not work on all machines. Also, some pop-up (TSR) programs
prevent it from working.
2. Define the graphics characters via a keyboard macro program, such as
Cruise Control, NewKey, PRD+, ProKey, SmartKey or SuperKey. If you would
like an example of how we set up SuperKey macros to perform this task,
just drop us a line asking for our SuperKey PC-ASCII macros, enclosing $3
to defray the cost of the disk and postage.
19
Note that ANSI animator programs (such as TheDraw) are NOT appropriate for
creating GRA stock files. GRA files are ordinary text files, except that they
use extended ASCII. This has two benefits:
1. The files transmit quickly (ANSI is notoriously slow).
2. People dialling in can scroll back and see the screens. (Many
terminal programs do not reinterpret ANSI when scrolled back,
resulting in some user confusion.)
Stock File Naming Convention
----------------------------
Most of the files that come with Sapphire follow the naming format of four
characters and two X's for the root name (e.g. LOGOXX.STD). These files will
be displayed to any user who encounters the situation in which it is appropri-
ate to display the stock file.
But you can exercise a measure of control over which files get displayed,
depending on how you name the stock files. The "XX" part of the file name
holds the key:
FORMAT: AAAABC.DDD
EXAMPLE#1: UPFNXX.GRA
EXAMPLE#2: MAINX1.STD
In the FORMAT given above, the letters have the following meaning:
AAAA Four letters identifying the purpose of the stock file. In the
examples, UPFN is the file that is displayed when the user has to
supply an UPload File Name. MAIN is displayed as the MAIN menu.
B User membership level (1 to 8)
C User expertise level (1 to 3)
DDD File extension (STD or GRA -- as explained previously)
Whenever Sapphire has to display a stock file, it will first try to find a file
that matches the user membership and expertise level. Thus, a level 3 user
with expertise set at level 1 would see a file named MAIN31.STD when it is time
to show the main menu. That is to say, he would see the file if it existed.
If it does not exist, Sapphire tries to find a file that matches but has an X
in one or both positions. It will then pick the one that matches best.
20
EXAMPLE: User is at membership level 4, expertise 3.
FILES: MAIN43.??? would be shown (??? here means STD or GRA)
MAIN4X.??? would be shown if MAIN43.??? didn't exist
MAINX3.??? would be shown if the previous two didn't exist
MAINXX.??? would be shown if none of the previous existed
Nothing would be shown if none of the previous existed
The final line introduces an important concept in the use of stock files. By
leaving out XX files for a given stock file application, you will prevent
certain people from seeing that type of file.
The most obvious application is for the main menu. Only MAINX1 is defined,
which means that any membership level can see that file, but only if their
expertise level is set to 1. If their expertise level is set to 2 or 3, they
will NOT see a menu.
You may wish to define some additional main menus. This is, in fact, an ideal
way to get familiar with stock file operations. In order to provide complete
coverage of all membership and expertise levels, you could define the following
48 files (where ??? means both a STD and GRA file):
MAIN11.??? MAIN12.??? MAIN13.???
MAIN21.??? MAIN22.??? MAIN23.???
: : :
: : :
MAIN71.??? MAIN72.??? MAIN73.???
MAIN81.??? MAIN82.??? MAIN83.???
In actual practice, however, you probably won't define menus for users at
expertise level 2 or 3, so you'll actually define the following files...
MAIN11.??? to MAIN81.???
which is a more manageable task -- only 16 files.
21
Stock File Commands
-------------------
Stock files can contain, apart from text, special lines that the user does not
see. These are as follows:
COMMAND EXAMPLE MEANING
------- ---------------- --------
;<space> ; Hello world! A comment
;<number> ;8 Keep following lines together on screen
;LOG text ;LOG Pistachio Places text in the system (OBSERVE) log
;FNC color ;FNC WOE Sets functional color of file display
The comment and log functions are self-explanatory. You can find examples of
both in the file UPDFXX.STD, which is the stock file that is displayed when the
user tries to upload and there is not enough free space on the disk. In such
case, you want to log this fact to the OBSERVE log so that you will find out
about it when you read the log later on.
The "semicolon number" command is known as "The Keep Command". It is used when
you want to ensure that certain text in a stock file is kept together on one
screen, instead of being broken in the middle with a "More, Notepad, Quit"
prompt (which is displayed when the screen is full).
Let's say you had placed, in a stock file, a list of phone numbers that was 8
lines long. It would be annoying to the reader if it was broken up in the
middle. So you could start the table like this:
;8
PHONE NUMBER CONTACTS
------------ --------
514-345-9578 Pinnacle Voice Support
514-345-8654 Pinnacle Free Files BBS
:
etc.
The ;8 line will ensure that the next 8 lines are always presented on the
same screen, even if it means presenting the "More, Notepad, Quit" prompt a
little early.
For examples of the keep command, refer to the stock file HINTXX.STD.
22
The "functional color" command lets you specify the color of the following
text. Normally, stock files are displayed in light grey. You can switch
colors by using the ;FNC command. The command works this way:
COMMAND COLOR USED THEME OR FUNCTION
------- ---------- -----------------
;FNC HLP Yellow Helpful or explanatory information
;FNC INP Light Cyan User input
;FNC QUE Light Green Text preceding user input (a prompt)
;FNC WOE Light Red Something unusual or troublesome is happening
;FNC INF Green Regular information and progress messages
;FNC FIL Light Grey Stock and message file output
;FNC HDG Light Blue A heading or title
;FNC INI Light Grey Initializes an alternating-color list
;FNC LIS LtGry/Cyan Switches to opposite color in list
;FNC HEY Lt Magenta Emphasized output
By defining colors using this method (which we call "thematic color specifica-
tion") we make possible the rapid reconfiguration of color on the BBS. The
value of this is not immediately obvious, because color redefinition is a
feature planned for the next version of Sapphire. (See the "NEXT" item on the
INFO menu of the SYSOP utility for details.)
For the time being, it does mean that you can control the color of stock files
so that they do not always appear in Light Grey.
The INI and LIS colors are a little different from the others. When you
specify INI, it initializes "list color processing". Thereafter, every time
Sapphire sees ;FNC LIS it will switch between Light Grey and Cyan. This
technique is very handy for distinguishing lines in a list.
23
================
DOORS AND EVENTS
================
The information presented in this chapter is addressed to experienced sysops.
If you are new to the joys of sysoping, it would probably be best to avoid the
DOORS and EVENTS commands until you are more familiar with your new BBS.
Sapphire will function perfectly well without DOORS and EVENTS installed, so
you can safely skip this chapter and come back to it later.
Definitions
-----------
Doors and events are both instances where the Sapphire program ends and control
is returned back to DOS. In the case of a door, the shut-down is initiated by
a user; for events, the shut-down happens automatically, according to a
schedule you set up.
Applications for Event Processing
---------------------------------
Consider the following batch file. (Note that the <-- arrow and following text
are comments, not part of the batch file.)
REM Batch File Autoback
:START <-- A batch file "label"
SRUN <-- The main Sapphire program
COPY SAPPHIRE.USR A:SAPPHIRE.USR <-- Copy the user list
GOTO START <-- Start over again
If you could arrange to have the BBS come down every night at 3:00, it could
make a spare copy of the user list on the A: drive. This would be very useful,
although of course you would have to make sure that the A: drive always had a
floppy inserted and ready to go!
Set up in this way, you could leave town for a long weekend, confident that
your user list was being backed up every day.
This is only a very simple example of the benefits of event processing.
Another possible application is automatic dial-out via your favourite communi-
cations program (to pick up mail, perhaps). Of course, you would have to write
a "script" (i.e. a program that your comm program understands) in order to have
it dial out, sign on, pick up the mail, then return to DOS.
24
One very common use for event processing is to support network systems such as
Fido -- a very complicated topic beyond the scope of this manual.
Applications for Doors Processing
---------------------------------
A door is an external program that a user can run from Sapphire. (It is, in
effect, a "door" into programs written by other people.)
There are dozens of door programs available. One example is the Pyroto
Mountain gaming system, which was also written by Pinnacle Software. You can
call it as a door, giving your members a chance to play this intriguing game of
magic and politics. We also publish the Free Speech "open forum" system, which
can be run as a door.
Before making a door available to your members, you should review it carefully.
The quality of door software varies greatly; some may crash, thereby failing to
return to DOS and consequently taking your BBS "off the air".
In order to run most doors (i.e. those not created by Pinnacle Software), you
will require a door-data conversion program such as DoorMaster or DoorWay or a
specific converter program such as SP2QBBS. The latest version of these
converters can usually be obtained on your local or national BBS, or from a
telecomputing service such as GEnie or CompuServe.
Coding Your Batch Files
-----------------------
In an environment using doors and events or both, everything is tied together
with batch (.BAT) files. (For detailed information about batch files, consult
your DOS reference manual.)
The simplest kind of batch file was illustrated in the "automatic user list
back-up" example shown earlier. This was a just a loop, executing one func-
tion. One problem, though ... you'll note that there was no way to get out of
the loop! So it was not a particularly useful program.
If you want to call Sapphire from any directory, put a batch file like the
following one (which you could call S.BAT) in one of the directories in your
PATH:
ECHO OFF <-- Stop display of batch lines
C: <-- Change to the right drive
CD \SAPPHIRE <-- Change to your Sapphire directory
SAPPHIRE %1 %2 <-- Jump to batch file SAPPHIRE.BAT
25
SAPPHIRE.BAT is a batch file that comes with Sapphire. It looks like this:
ECHO OFF <-- Stop display of batch lines
SAPPHIRE %1 %2 <-- Start up Sapphire
EXTERNAL <-- Jump to batch file EXTERNAL.BAT
This batch file must be in the directory where SRUN.EXE resides.
The %1 and %2 after the SAPPHIRE allows you to pass parameters to Sapphire, so
you can start up the batch file with SAPPHIRE LOCAL to run without a modem.
(This is how the SYSOP utility does it.)
How EXTERNAL.BAT Works
----------------------
Don't look for a file named EXTERNAL.BAT in the Sapphire package -- there isn't
one. EXTERNAL.BAT is created whenever Sapphire ends.
If Sapphire is shutting down because you are closing it (using the CLOSE
command, for example), EXTERNAL.BAT will be empty. As a result, you'll drop
straight through to the DOS prompt.
For doors and events, however, Sapphire copies other batch files into EXTER-
NAL.BAT. So whatever was in those other batch files will get executed.
But how does this get us back to Sapphire?
After Sapphire copies the other batch file into EXTERNAL.BAT, it appends some
additional instructions, as in this example:
C: <-- Switch to Sapphire's "home" drive
CD \SAPPHIRE <-- Switch to Sapphire's "home" directory
SAPPHIRE <-- Jump to the SAPPHIRE.BAT batch file
And thus, the circle is completed.
Of course, the extra instructions may vary, depending on where your copy of
SRUN.EXE resides and the way you started up Sapphire.
26
Batch Templates
---------------
You will use the DOORS and EVENTS commands to specify which batch files will be
copied to EXTERNAL.BAT. We will call these files "Batch Templates", because
although they end in .BAT, they are never actually run directly.
You can write the templates without regard to what happens after the program
ends, because that's taken care of when Sapphire copies them to EXTERNAL.BAT.
NOTE: A template must not call another batch file, unless that batch file
contains the code to get back to SAPPHIRE.BAT. You can, however, use the batch
file command "CALL", which is explained in your DOS reference manual.
For example, to call up the PYROTO door, you could write a template file named
PYROTO.BAT, which looks like this:
C: <-- Make sure you are on the right drive
CD \PYROTO <-- Change to the Pyroto directory
PYROTO <-- Start up the program
Writing Door and Event Programs
-------------------------------
When Sapphire calls a door or event, it always creates a file in the root
directory of the drive containing Sapphire, named:
SAPPHIRE.DAT
This file contains important information for doors and events. If you plan to
write door or event programs, you'll need access to this data.
Turbo Pascal source-code, describing the layout of the file, can be found in
the file named SDOOR.INC.
27
=============
FILE TRANSFER
=============
What is File Transfer?
----------------------
With Sapphire's file-transfer feature installed, you will be able to exchange
software with people who dial into your system, using the popular Xmodem,
Ymodem and Zmodem protocols.
Sapphire maintains a list of up to 500 programs (providing there is enough
space on your hard disk), along with statistics and documentation.
The file-transfer feature requires a system equipped with a hard-disk with a
minimum of 1 Megabyte free space.
Installing File Transfer
------------------------
In order to enable file-transfer (Xmodem, Ymodem and Zmodem), you must install
the DSZ file-transfer program, which is included in the Sapphire package with
the permission of its author, Chuck Forsberg.
In order to install DSZ, select the DSZ option on main menu the SYSOP utility.
This will enable the GET, GIVE, PROTOCOL or FILES.
Adding Software Locally
-----------------------
To add a file to the software collection while you are at the console, you must
first place it in the files directory (usually named C:\SAPPHIRE\FILES).
Sapphire's DOS command comes in handy, here, for moving files around.
Afterwards, use the GIVE command. For example, if you had moved the file
PYROTO.LZH into the files directory, you would then enter this command:
==> GIVE PYROTO.LZH
You would then be asked who this file is for (everybody, sysop, etc.), then
asked to write some documentation about the file. (This step is described
later, in more detail.)
28
Adding Software Remotely
------------------------
A remote user follows essentially the same steps as a local user, but obviously
he cannot place the file directly into the files directory. So he must upload
the file, using one of the file-transfer protocols used by Sapphire (Xmodem-
Checksum, Xmodem-CRC, Ymodem, Zmodem).
As a reward for contributing software, he is granted "double-your-minutes-back
for this visit and the next". For example, if it took him 10 minutes, he gets
an extra 20 minutes for the current visit, plus 20 extra minutes for the next
session.
How Online Documentation Works
------------------------------
After contributing a file, the contributor may write up to 48 lines of documen-
tation, which other people will be able to read before deciding whether or not
to download this file.
Online documentation that has already been written can be re-used. For
example, if you are making available a multi-file software package, you can
tell Sapphire to use one documentation file for all of the files.
Incidentally, if one of those software files is deleted, the documentation file
is retained -- as long as some other file is using it.
The documentation step uses the usual text editor that you use for writing
messages. No new skills need be learned. In fact, you can even include
private and exclusive messages in your documentation.
NOTE: If the entire documentation is private (i.e. the first line,
or the summary line are private), then the file can be accessed
only by the people listed in the private header. This enables you
to exchange files privately with a limited group of people.
The documentation is saved in the files directory, in a file with the same
root-name as the original file. For example, a file named VARITALE.ARC would
have a documentation file named VARITALE.S-D associated with it. (S-D stands
for Software Documentation.) If you don't like the documentation that a user
has written, you can copy some better documentation over the S-D file. All S-D
files are standard text files, prepared with a text editor.
29
Transfer Protocols
------------------
The Ymodem supported by Sapphire is proper Ymodem, per the original specific-
ation. Some very respectable communications programs confuse the protocol
Xmodem-1K with Ymodem. If your users complain that Ymodem doesn't work for
them, suggest they switch their communications program from Ymodem to Ymodem-
Batch.
You should encourage your users to use the Zmodem protocol, because it has
built-in crash recovery. That means that if the user is cut off while down-
loading a file, he can pick up where he left off.
Crash recover also works on uploaded files. If the user is disconnected during
an Xmodem or Ymodem transfer, Sapphire has no choice but to delete the partial
file. If the user used Zmodem, though, Sapphire retains the partial file in
the files directory -- though it does not add it to the files list. This
enables the user to call back and pick up where he left off, using Zmodem's
crash recovery.
30
====================
MISCELLANEOUS TOPICS
====================
Gear Shift
----------
Sapphire supports adjustable output speed. During output, a user can press one
of the number keys to "shift gears" for a comfortable reading speed. The keys
run from 1 (slow) to 9 (fast). The 0 key is the "top gear" key. It sets
output speed to maximum.
When the main command prompt comes up, output is reset to full speed. This has
proven to be a convenient arrangement. However, the user can reset his
"default gear", via the SPECS command. Certain types of line-noise problems
have been solved by selecting a lower output speed.
Password Changes
----------------
There is an undocumented feature in Sapphire which allows users to change their
passwords. If you sign off by typing BYE PASSWORD (no abbreviations) you will
be asked for a new password.
This feature was not explicitly documented because there has long been an
argument among computer security experts about the wisdom of letting users
change (or even select) their passwords.
It might be best to keep the BYE PASSWORD feature secret if you give users a
new password when you validate them. Or perhaps you'll decide to avoid letting
them change their password simply because they tend to forget what their new
password is.
Whether or not you let your users know about this feature is up to you.
Command Abbreviations
---------------------
If Sapphire forced users to type every command in full, the advantages of using
words (instead of single letters, as other BBS's do) might seem unimportant.
Fortunately, Sapphire lets users abbreviate and stack commands. These tech
niques are described online, by the HINTS command.
31
Additional Documentation
------------------------
You can find additional information about Sapphire in the SYSOP utility (enter
SYSOP at the DOS prompt). In particular, refer to two sections:
1. The INFO menu provides a wide variety of information about Sapphire
and also lets you print the order form, so you can register your
copy of Sapphire.
2. The CONFIG program has pop-up help for each field you can con-
figure. There is a lot of useful information here, which you might
find interesting to read even if you don't change the configured
values.
32