Category : BBS Programs+Doors
Archive   : WAF165.ZIP
Filename : FILES.DOC

Waffle v1.65 / Transfer Section Manual
(C) Copyright 1992 Darkside International, All Rights Reserved.

C O N T E N T S

I About the FILES section
II Setting up the FILES section
III Support files
IV Format of DIRS file
V The ARCLIST Program
VI Additional Information


A B O U T T H E F I L E S S E C T I O N

The file transfer area of Waffle permits callers to the BBS to
upload and download software or other files. This portion of Waffle
is targeted towards two groups of people:

a) Bulletin board operators, to allow their callers
to access software from the BBS.

b) The user who wants to access his computer remotely,
for "that file you forgot to take to work."

If you are primarily interested in E-Mail, you can probably
disregard this entire document.


S E T T I N G U P T H E F I L E S S E C T I O N

1. Choose the initial FILES directory

The "files" line in the static file determines what directory
Waffle will place the user in when he enters the FILES areas.

Most sysops will make this a general directory, perhaps with
many subdirectories underneath it. Another common configuration
is several unrelated toplevel directories, such as one for
Macintosh software, one for PC software, and so forth.

You must create this directory; waffle will not do it for you.

2. Edit the /waffle/system/dirs file

Normal users will not be able to access any directory unless
an entry has been added for it in the /waffle/system/dirs file.

The first directory that a user will enter is the initial
FILES directory, and thus the permissions there will determine
access to the rest of the section.

Entries in the /waffle/system/dirs file may contain a number
of parameters, described later in this document. For now, place
as the first line in this file:

(For DOS systems)

1 /dir="c:/files" /access=1

(For Unix systems)

1 /dir="/u/files" /access=1

Here, the first field (which should be in the first column)
is an identifier that will be used with a future version.

The /dir= specifies the location where you will store files
for that file area, and /access= determines the minimum access
level that may enter that file area.

3. Create other file areas

Think about what you want your FILES section layout to be.
There are two obvious approaches.

Scenario #1 -- Tree structured example

/files

/files/pc /files/mac
/files/pc/comm /files/mac/comm
/files/pc/utilities /files/mac/graphics

Here, there are two hierarchies with different
subdirectory structure. From any level, users can
see what the lower levels are.

Scenario #2 -- Multiple tree structure

/pc /mac
/pc/comm /mac/comm
/pc/utilities /mac/graphics

In this instance, there are two separate
directory trees. This has the advantage of smaller
filenames, but the user needs to know the names
of the other trees in order to get to them.

(The following note applies to DOS systems. Unix systems
running Waffle don't have to worry about what disk FILES
directories are on, unless they're out of space.)

NOTE: The /pc and /mac hierarchies in the second example
may be on different disks.

For each directory you create, add a corresponding entry
to the /waffle/system/dirs file.

Here is a sample DIRS configuration file:

1 /dir="g:/files" /access=1
2 /dir="g:/files/waffle" /access=0 /free
3 /dir="g:/files/pc" /access=2
4 /dir="g:/files/pc/comm" /access=2
5 /dir="g:/files/pc/language" /access=2

This allows level 1 access to the FILES section, but
requires level 2 for getting to PC software.

Also in this sample, free downloads are allowed from
the /files/waffle directory. We do this exact thing by
defining a SNARF command with /waffle/extern/snarf:

/access=0 /command="files /files/waffle" /waffle

Anyone who types SNARF from the main Waffle menu thus
bypasses the usual level 1 requirement to enter the FILES
section, and can download files immediately.

4. Set the "disks" line in the static file

This mainly applies to DOS systems (since Unix systems
have a single "virtual disk") although Unix systems should set
this parameter as an abbreviation aide.

The "disks" line in the static file will tell Waffle where
to look for FILES directories. If your FILES areas are split
across several drives, this might look like:

disks : D: E: F:

When someone tries to log "/pc", Waffle will check the
current disk. If it doesn't find a PC directory there, it
will try D:\PC, E:\PC, and F:\PC. This hides the location
of directories from the BBS user.

If you're running a Unix system, or a DOS system where
the files directories are all on the same disk, you might
set the "disks" line to something like

disks : C: D: D:\FILES
or
disks : /files

When someone tries to log "/mac", first /mac will be
checked, and then /files/mac. The disks line thus becomes
a shorthand to help move around.

5. Add file descriptions, if desired

Files may have a one line description associated with it.
Descriptions are kept in a @files file in each directory.
Waffle prompts for a description before every upload, which
may then be entered by the user.

If you have an existing file base in these directories
you may create a @files list. The format of @files is very
simple; the name of the file, followed by a spaces or tab,
then the description of the file.

read.me About the Transfer Section
dmedia.txt Datamedia Emulation Codes

Subdirectories may also have descriptions.

6. Enable any transfer protocols

(For DOS systems)

If you are running DSZ, place a copy of DSZ in
the C:\WAFFLE\BIN directory. Waffle for DOS comes
configured for use with DSZ.

DSZ is a trademark of Omen Technologies Inc. We
recommend registering a copy if you use it, though
their technical support department could use a
boot to the head. DSZ was written by Chuck Forsberg.

(For Unix systems)

If you are running RZ/SZ, place a copy of rz and
one of sz in the /waffle/bin directory. Use the ln
command to link sx and sy to sz, and rx and ry
to rz. Waffle for Unix is configured for RZ/SZ.

There are no restrictions on the RZ/SZ program.
RZ/SZ was written by Chuck Forsberg.

If you don't run DSZ or RZ/SZ, you must modify your
/waffle/extern/_send and /waffle/extern/_receive files to
run with your external protocol program(s).

All external protocols are handled by Waffle as single
character names, such as "X" for XMODEM, "K" for Kermit,
and so forth. A line for each protocol should be added
under that name in the _send and _receive file. The exact
command line will vary from program to program, so you
must consult the documentation of the specific program.


S U P P O R T F I L E S

These are the support files for the FILES section.
If you do not have a FILES section, they may be safely
removed, although you may wish to leave the UNFILES
file if you run a BBS system.

/waffle/system/dirs

This is a listing of all the FILES directories,
used by the FIND and MASTER commands. Only these
directories are inspected when searching for
files or giving a list of all files.

/waffle/text/files

Banner which is displayed on entry to the FILES
section. This can notify users about changes,
policy, and give them an idea of where to look
for for help.

/waffle/text/master

This file is displayed at the start of every
MASTER file directory listing.

/waffle/text/unfiles

Message displayed when someone does not have
access to the FILES section. This is also displayed
if you have no FILES section at all. You might
explain that they must send a postcard to obtain
access, donate their firstborn, or whatnot.

/waffle/menus/areas

When the "*" command is entered while in FILES,
this file is displayed to tell the user what file
areas are available.

/waffle/menus/files

A short summary of all the FILES commands,
displayed when someone wants HELP or hits ?.

/waffle/menus/protocols

Menu containing a list of the transfer protocols
available. If you use DSZ or RZ/SZ, this will
normally be Xmodem, Ymodem, and Zmodem. You must,
however, update this manually if the protocol
list should change at any time.

Displayed when ? or any unknown protocol is
entered when selecting a protocol.


F O R M A T O F D I R S F I L E S

To make a directory accessible to users, place an entry for it
in the /waffle/system/dirs file. Each line in this file contains
options to specify location and permissions of a file area.

Valid options in the /waffle/system/dirs file include:

/access Access level required to log the directory.
This is the most commonly used option. Example,

/access=1

permits validated users & above to access the
given directory.

This line is required. Also see /download.

/banner Filename of a message to display upon
entering this area.

/banner=@banner

If a full pathname is not given, the file
is assumed to reside in the /dir directory.

/column Column at which the file description is
assumed to begin at.

/column=22

Usually this is used when existing file
descriptions are present in a foreign format;
the filename must still be the first
component of the line.

This option is intended mainly for CD ROM
description files, such as that present on
the SIMTEL20 CD ROM.

When /column is used, no attempts are made
to update file descriptions.

/deny Deny access to all users, even sysops.

/deny

It is not necessary to place a /deny in all
directories on the system, as the system will
not allow access to those not listed in the
/waffle/system/dirs configuration file.

Attempts to enter this directory are recorded in
the events log.

/deposit No downloads are allowed from the directory,
except by sysops.

/deposit

This is useful for the "uploads" directory
if you've defined it in the static file.

In this manner, files can be previewed by the
sysop before enabling public downloads.

/dir Directory that is used for this particular
file section.

/dir="/u/files/text"

For DOS systems, this must contain the drive
letter as well as a full path:

/dir="c:/files/text"

This line is required.

/download Restricts downloads to those with the
appropriate levels:

/download=4

allows those with access 4 or higher to
download files from the directory. Others
with /access may still look, though.

/free All downloads from the specified directory
will not be charged against the UL:DL ratio.

/free

Furthermore, people with UL:DL ratios that
have been exceeded can download here.

/group A list of groups permitted to log the directory.
All other users are not allowed except in the
case of a privilege 9 uses. Example,

/group=4,9,16

permits anyone in the named groups to enter. The
user need only be a member of one of the groups.

/hide In a MASTER or FIND command, ignore this
directory in the scan.

/hide

This allows directories to exist for
hidden or private use.

/info Pointer to a description file. By default
this is whatever "fileinfo:" is defined in
the static file, which is usually @FILES.

/info=index.txt

If a full pathname is not given, the file
is assumed to reside in the /dir directory.

/pass Places a password on the directory in question.

/pass="rosebud"

Users must enter the appropriate password, in
this case rosebud, before access is allowed.

/priv Grade of sysop privilege required to enter
the directory. Privileges can be set with the
"ADMIN X username" command.

/priv=6

/rom Files directory resides on a readonly or
write protected device, such as a CD ROM.

/rom

When this is set, no uploads are allowed to
the given directory and no attempts will be
made to update the file descriptions.

Directories not in the /waffle/system/dirs file may only be
logged by SYSOPs, with the exception of a user's personal home
directory, which may be logged by that user.


T H E A R C L I S T P R O G R A M

Included with the Waffle distribution disk (though not the ZIP file)
is the ARCLIST program, which will list the contents of the following
archive formats, listed with the author's names --

ARC MS DOS ARC, Thom Henderson

The original archive packer. Use of SEA's ARC
utilties have fallen into disfavor after SEA sued
PKWARE for trademark infringement.

ARC is a trademark of System Enhancement Associates.

LZH MS DOS LZH, Haruyasu Yoshizaki

A new archive program with fairly tight compression.
However the file structure is very weak and it is
difficult to recover files from a damaged archive.

SIT Macintosh Suffit, R. Lau

The de facto standard for Macintosh archives, which
require a nontraditional file format because of the
two forks (resource fork and data fork) of files in the
Macintosh file system.

TAR Unix Tar(1), AT&T Bell Laboratories

Unix tape archive. The tar(1) command can write to
files in addition to tapes with the -f flag.

Unfortunately, many people compress .tar files, turning
them into .tar.Z files. It is impossible to get a
directory of a .tar.Z file without uncompressing the file.

ZIP MS DOS ZIP, Phil Katz

After settling out of court Phil Katz did the Right
Thing and developed a better archive technology.

The ZIP files are tightly compressed and have a well
thought-out file structure. The ZIP format is in the
public domain.

There exists a portable UNZIP for Unix.

ZOO Zoo, Rahul Dhesi

Like ZIP, a well thought-out file structure with
decent compression. The format is in the public domain.

This is the first archive format defined with portability
in mind. There are ZOO archivers and tools for MS DOS,
Unix, and VMS.

(To Unix people)

We have tried to make the ARCLIST program independent of the
architecture of the host computer.

The source to ARCLIST is kept in ./waffle/tools/arclist.*,
and to build a copy of it, type "make arclist" from within the
tools directory.

(To DOS people)

The file ARCLIST.EXE comes installed in the /waffle/bin directory.


A D D I T I O N A L I N F O R M A T I O N

o Restricting uploads to a single directory

Normally Waffle will allow users to upload files to any directory.
Usually they will upload to the proper directory. If your users aren't
so well behaved, uploads can be restricted to a single directory
by adding the line

uploads : /files/uploads (for Unix systems)
or
uploads : C:\FILES\UPLOADS (for DOS systems)

This directory must have an entry in the /waffle/system/dirs
file, and the user must be able to access the directory. You can
use the /deposit flag to prevent people from downloading from
this directory, though.

Registered copies of DSZ also have a "restrict upload directory"
option that will force this behavior as well.

o An example display from the FILES section:

(>Directory: *.*

apple < DIR > 10-Feb-89 Apple ][ software
mac < DIR > 10-Feb-89 Macintosh software
pc < DIR > 10-Feb-89 IBM & MS-DOS software
unix < DIR > 15-Feb-89 UNiX software

read.me 1285 15-Feb-89 * About the Transfer Section *
dmedia.txt 976 23-Nov-88 Datamedia Emulation Codes
pascal.jok 13116 1-Jan-89 Is Pascal a joke? We're not laughing
chak.ai 6583 4-Jan-89 Fiction: Chak the Unspeakable

o File descriptions

File descriptions in each directory are contained within a
"@files" file, which is created when needed. The limit to the
number of files allowed is the "buflines:" parameter in the
static file; extra lines be ignored. Files without description
entries have no descriptions displayed.

After files have been deleted from a directory, the corresponding
descriptions in @files are purged the next time the directory is
listed from with Waffle's FILES section.

o Hidden Files

Files whose names begin with @ or . will not show in directory
listings. A file whose name is just "@" will cause a blank line
in the listing, to allow directories to be separated from files.
It is suggested that DOS people use a directory sorter (Norton
Utility DS, or ARRANGE) occasionally to alphabetize directories.
This results in a more pleasing appearance.

o External Protocols

Protocols used by Waffle must be provided by external programs.
These are configurable through the _send and _receive files in the
/waffle/extern directory. It is possible to add protocols to these
files (for example, Kermit could be 'K' protocol) but make sure the
result code is what Waffle expects it to be: 0 for success, nonzero
for lack of success.

Under DOS, the XMODEM, YMODEM and ZMODEM protocols are often run
using an external program, DSZ, by Omen Technologies. DSZ is a $20
shareware program, and well worth it.


Here is a sample configuration of the /waffle/extern/_send file
for MS DOS. You must have a copy of DSZ in /waffle/bin:

/waffle/extern/_send

X /command="DSZ port %d sx %i"
Y /command="DSZ port %d sb %i"
Z /command="DSZ port %d sz %i"

/waffle/extern/_receive

X /command="DSZ port %d rx %i"
Y /command="DSZ port %d rb %i"
Z /command="DSZ port %d rz %i"

Under Unix the same functionality may be provided by rz/sz, or a
standalone XMODEM may be used.

Here are sample configurations for Unix. These also assume you
have copies of sx, sb, sz, rx, rb, and rz in your ./waffle/bin directory.
Sx, sb, and sz may be linked to each other, as may rx, rb, and rz.

/waffle/extern/_send

X /command="sx %i"
Y /command="sb %i"
Z /command="sz %i"

/waffle/extern/_receive

X /command="rx %i"
Y /command="rb"
Z /command="rz"

If you wish to have these files resident in a directory other than
./waffle/bin, place a full path inside the /command argument.

o Extra sysop commands in FILES

Privileged users may use the following two commands to help
maintain the FILES section.

^E Edit a file, this can be used to help maintain
the @files description files.

^D Delete a file.

o Notes

Waffle does not have to be logged in a specific directory to run,
and the FILES command will not restore the original directory when
leaving. We try to minimize the number of chdir's required, because
certain versions of Unix take a long time to chdir.

A directory may be specified as the argument for a FILES command.
In order to access a directory in this manner, the usual access checks
are still performed. However the /waffle/text/files file will not
be displayed, but instead a @BANNER file in the directory specified
will be displayed if one is present.

o Example for the SIMTEL20 CD ROM

An example DIRS entry for accessing the SIMTEL20 CD ROM under DOS:

1 /access=1 /rom /info=00_index.txt /column=33 /dir="e:/msdos/waffle"

The CD ROM drive is E:, and the directories contain 00_index.txt
files with descriptions starting at column 33. Use of the /rom excludes
the directories from N(ew) list, and prevents 00_index.txt from having
missing files purged, since there is also English text in 00_index's.

o Miscellania

It would be an interesting project to write a replacement FILES
section, accessed as an external program.

--
[email protected]
(C) Copyright 1992 Darkside Int'l.