blue wave mail packet file structures


the blue wave offline mail system
mail packet file structures
revision level 2

copyright 1990-1994 by cutting edge computing
all rights reserved

created by george hatchew

documentation by martin pollard and george hatchew
revision 2.01 - january 18, 1994



===================
table of contents
===================

introduction
filename conventions
files in blue wave packets
byte ordering in file structures
using the file structures
unused and reserved structure fields
the *.inf file (inf_header & inf_area_info)
the *.mix file (mix_rec)
the *.fti file (fti_rec)
the *.dat file
the *.xti file (xti_rec)
the *.upl file (upl_header & upl_rec)
the *.upi (upi_rec) and *.net (net_rec) files
the *.req file (req_rec)
the *.pdq file (pdq_header & pdq_rec)
appendix a - how to create a blue wave mail packet
appendix b - how to create a blue wave reply packet
appendix c - the blue wave structures and turbo pascal
appendix d - serial numbers in mail and reply packets


============================
copyright and restrictions
============================

the blue wave packet structures were created by george hatchew, and
are the copyrighted property of cutting edge computing. permission is
granted for third parties to use these structures in their own pro-
grams, without any royalties or licenses required. cutting edge
computing reserves the right to make any changes to these structures,
at any time. as such, third parties are requested not to make any
unauthorized changes to these structures, as cutting edge computing is
not bound to follow these changes. any proposed changes should be
brought to the attention of cutting edge computing, where they may be
included in future revisions of the structures.

authors that use these structures are allowed to claim that their
programs are "blue wave compatible". however, to avoid confusion and
complications, authors are not allowed to use "blue wave" as any part
of the name of their programs (as "blue wave" is a product line from,
as well as a trademark of, cutting edge computing).



===================
trademark notices
===================

the following are products, trademarks, or registered trademarks of
the following individuals and/or companies:

arc - system enhancement associates
blue wave - george hatchew and cutting edge computing
fidonet - tom jennings and fido software
megareader - kip compton
ms-dos - microsoft corp.
pkzip - pkware inc.
qwk - mark "sparky" herring
silver xpress - hector santos and santronics software
turbo pascal, borland pascal - borland international
xrs - michael y. ratledge

any omissions from this list are purely unintentional.
blue wave mail packet file structures - revision level 2


introduction
============

the world of offline mail has virtually exploded since the late 1980s,
due mostly to the ever-increasing interest in electronic mail networks
(such as fidonet and the internet). as the flow of mail increased,
more and more users became aware of the benefits of downloading mail,
reading it offline, and uploading replies at a later date, thus maxi-
mizing efficiency and minimizing the time spent online.

several competing formats for storage of offline mail have come into
existence during this period, with the minimalist qwk format emerging
as the dominant one due to its open specifications. (the megareader,
silver xpress, and xrs, formats also exist, but never really achieved
"critical mass" due to the proprietary nature of their file formats.)
qwk enjoys widespread popularity, but its technical limitations make
it less than suitable for handling the wide variety of electronic mail
that currently exists (and which will appear in the coming years).

the blue wave format was designed as a superior method of providing
offline mail capabilities, particularly for networks based on the
fidonet standard (which means full support for fidonet-style private
mail, or netmail). its design is simple enough that virtually any
programmer can create a blue wave-compatible product in a short amount
of time, yet flexible enough to provide plenty of room for future
needs (such as fax capabilities). it also has basic support for non-
fidonet style mail, such as that required by internet mail, usenet
newsgroups, and qwk-based network mail.

note that this is a reference document, not a programming tutorial. a
tutorial on programming is beyond the scope of this document. thus,
we do not recommend the use of these structures by the novice.


filename conventions
====================

the blue wave format was originally designed for the blue wave series
of offline mail readers and doors running on an intel-compatible pc
using ms-dos (or a dos-compatible operating system). this means that
filenames are limited to the dos standard "8.3" format (up to eight
characters, optionally followed by a period and a one to three charac-
ter extension, with no distinction made between upper and lower case
letters). for maximum compatibility across different platforms,
programs utilizing the blue wave format should limit filenames to the
dos format as well.

additionally, dos allows for some non-alphanumeric characters to be
used in filenames. these characters, while suitable for dos, may
cause problems on non-dos platforms. therefore, it would be wise to
restrict the allowable characters in filenames to uppercase letters
("a" to "z") and digits ("0" to "9").

files in blue wave packets
==========================

there are two main components to the blue wave system: mail packets,
which consist of messages obtained from the host system (such as a
bbs), and reply packets, which consist of messages written by the user
via an offline mail reader (such as the reader that bears its name,
the blue wave offline mail reader). each type of packet contains its
own set of unique files.

blue wave mail and reply packet filenames are based around what is
called a "packet id". the packet id is a one to eight character
string that uniquely identifies a particular host system, and is used
as the basis for all packet files. "packets", as defined here, are
groups of files contained in an archive file, which uses the packet id
as the base filename and is created using a file archive utility (such
as arc or pkzip, or the equivalent for non-dos platforms). the three-
character extension for a mail packet is comprised of the first two
letters of the day of the week, followed by a digit from 0 to 9.
fidonet sysops will recognize this as the same scheme used for the
extensions on echomail packets. (an alternate scheme is to use a pure
numerical extension, i.e. "001" through "999".) the extension for a
reply packet is "new". (note that door implementations should include
code to keep track of the last mail packet extension used, so that
multiple mail packets created on the same day won't have the same
filename.) examples of packet archive names and internal filenames,
based around the packet id, are given below (after the list of files).

a mail packet consists of, at minimum, the following files:

*.inf information about the host system and its message
areas, as well as information about the user who
obtained the mail packet.

*.fti the headers for each message in the mail packet.
the headers consist of such things as the from:,
to:, and subject: fields, and the date/time the
message was written.

*.mix an index file that points to the messages for each
message area, designed for quick access to messag-
es.

*.dat the text for all messages in the mail packet.

optional text/ansi files may also be included in the archive. in
addition to the "reader" files specified in the *.inf header, there
are two other types of files, not defined in the *.inf header, that
may be included. the first, a list of new files available for down-
load, can be included as "newfiles.*" (any extension is valid). the
second, system bulletins, can be included as "blt*.*" (any filename is
valid, as long as it begins with "blt"). the methods used to display
these bulletins is implementation dependent.


a reply packet consists of, at minimum, the following files:

*.upl contains the information (name, network address,
message attributes, filename of message text,
etc.) for each reply message. replaces the *.upi
and *.net files (see below) used in older blue
wave implementations.

*.upi contains the information (name, network address,
message attributes, filename of message text,
etc.) for each non-netmail reply message. this
file has been obsoleted by the *.upl file, but is
documented here for compatibility purposes (as
some older systems are not yet compatible with the
*.upl file).

*.net contains the information (name, network address,
message attributes, filename of message text,
etc.) for each netmail reply message. this file
has been obsoleted by the *.upl file, but is
documented here for compatibility purposes (as
some older systems are not yet compatible with the
*.upl file).

*.req an optional file that specifies the information on
file requests made through the offline mail read-
er.

*.pdq an optional file that specifies the information on
remote configuration (such as adding and dropping
message areas) made through the offline mail
reader.

to clarify, let's say a bbs is using the packet id of "wildblue". a
mail packet from that bbs would contain (at minimum) the files wild-
blue.inf, wildblue.fti, wildblue.mix, and wildblue.dat, and when
archived, would be called "wildblue.su1" (the extension may differ,
depending on the criteria described above). consequently, a reply
packet destined for that bbs would contain (at minimum) the files
wildblue.upl, wildblue.net and wildblue.upi (for compatibility), plus
the individual files that comprise reply messages, and when archived,
would be called "wildblue.new".

the text of each reply message is stored in individual files in the
reply packet. each *.upl record contains the name of the text file
corresponding to the particular reply message. the naming convention
used to assign names to each text file is up to the programmer. (the
blue wave reader uses "xxx.yyy", which stands for "message 'xxx' in
area 'yyy', but you are not limited to this format as long as the
filename is properly stored in the *.upl, *.upi, or *.net record.)


byte ordering in file structures
================================

since the blue wave packet structures were initially written for ibm
pcs and compatible systems, the format for multi-byte fields in the
data structures is expected to be in intel format (i.e. the least
significant byte first, followed by the most significant byte[s]).
some cpus, particularly the motorola 68000 series, store multi-byte
fields as most significant byte first. if you are writing a blue wave
compatible program for a system that does not store data in the intel
format, you will have to write a routine that will convert data bet-
ween the two formats.


using the file structures
=========================

the file structures, as presented here, are provided as a header file
for use with the c programming language. simply use the #include
statement in your program source code to incorporate the header file:

#include "bluewave.h"

each file structure is defined as a data structure ("struct") using
the "typedef" feature, making it easy to define variables. for exam-
ple, to define a variable used to store the *.inf file header, simply
use:

inf_header infhdr;

in your program.

to make the structures as compatible across platforms as possible, all
data types used in the structures are user-defined via "typedef". for
example, to use a 16-bit unsigned integer, the data type "tword" is
used instead of "unsigned int". this way, data fields are guaranteed
to be the same size across platforms. (for more information, refer to
the information contained in the bluewave.h file.)

also, if your program is being written for a cpu that does not store
data in intel format (as described earlier), you should insert:

#define big_endian

before you include the bluewave.h file. this will define the data
types as arrays of bytes, making it easier to create routines that
will convert data fields between intel format and the format native to
your cpu. (refer to "byte ordering in file structures" for more
information.)

several of the file structures -- the *.inf and *.upl headers --
include fields that define the lengths of the other file structures
used in mail and reply packet files. these fields are used to ensure
that programs can use future releases of the file structures without
breaking... as long as programs are coded to use them, that is.

door authors should take the few extra lines of code to fill in the
structure length fields. reader authors need to take the time to code
for possible extensions to this file format. if the data fields are
longer than expected, simply do a seek to move to the next record, and
ignore the extra information. (if the data fields are shorter than
expected, a simple "please upgrade your reader" should suffice.
however, you should never encounter a record size smaller than the
ones defined here.) any extra information that is sent in the packets
probably would not be crucial, and you may be able to continue with
reading the packet anyway.

(it should be noted that all blue wave doors earlier than the version
3.0 series set these fields to 0, as this extensibility was not added
until recently. if the structure sizes are 0, readers should assume
that all records are of the sizes defined in the header file as the
"original_xxxx_len" macros, and should use these macros when field
lengths of 0 are encountered. there is no definition for the original
length of the *.upl structures, as the older doors did not recognize
the *.upl file.)

to see an example of how to use these structure length fields, refer
to the comments in the bluewave.h file. there, you will see a c code
snippet that not only demonstrates the length fields, but the
original_xxxx_len macros as well.

important note: all blue wave file structures must be stored in
"packed" format (i.e. the compiler must not insert padding between
fields in order to force fields onto word boundaries). most compilers
default to "packed" mode, but if yours does not, you must use the
appropriate settings or preprocessor directives to set "packed" mode.
failure to do so will all but guarantee that your program will gener-
ate incompatible blue wave packets!


unused and reserved structure fields
====================================

some fields and flags in the blue wave structures are either not
defined, or are marked as being reserved for future use. these areas
are not to be used by programmers, unless otherwise indicated. they
are reserved for future expansion and enhancement of the blue wave
packet structures, and if you use them for your own purposes, you run
the risk of making your program incompatible with future updates of
the file structures.

furthermore, future structure updates will assume that these unused
areas are "garbage-free" (i.e. they are filled with 0 values). in
order to cover all bases, then, all unused areas should be set to 0.
this can be easily done with the standard c function memset(). for
example, using:

memset(&infhdr, 0, sizeof(inf_header));

before you begin adding information to the *.inf header structure will
ensure that all unused fields are set to 0. this should be done
before adding information to *any* blue wave file structure.


the *.inf file (inf_header & inf_area_info)
===========================================

the *.inf file consists of two "parts": a header, which contains
information about the host system and the user to whom the packet is
intended, and a series of records that contain the information on all
message bases available on the host system. (the latter is used in a
reader both for posting replies and offline configuration.) the
header structure is known as inf_header, and the record structure is
known as inf_area_info.

most of the fields in inf_header are self-explanatory. the following
fields, however, deserve extra attention:

ver packet version level. this is a crucial
field, as it allows doors and readers to
determine the revision level of the file
structures used to create the packet. pro-
grams should check this field to insure that
they can properly handle the packet; doors
should store in this field the current packet
revision level, shown at the top of this
document.

readerfiles files that can be displayed by the reader.
these are usually bulletins, sign-on banners,
etc. up to five files can be specified.

keywords specifies the keywords used while bundling
messages. door authors that wish to provide
keyword support should refer to the blue wave
user documentation for more information.

filters same as above, but specifies the filters used
while bundling messages.

macros same as above, but specifies the macros used
in the door to specify message bundling
operations.

can_forward indicates that the user can forward messages
to other message areas from within a reader.

inf_header_len length of inf_header used in mail packet.
door authors are required to fill this field;
reader authors should use this field to
properly parse the *.inf file. the current
crop of blue wave doors properly fill this
field, but older versions may not. refer to
the header file for more information on using
this field.

inf_areainfo_len same as above, but specifies the length of
the inf_area_info structure.

mix_structlen same as above, but specifies the length of
the *.mix file structure (mix_rec).

fti_structlen same as above, but specifies the length of
the *.fti file structure (fti_rec).

uses_upl_file a non-zero value in this field indicates that
the door which create the mail packet can
process reply packets stored in the *.upl
format. if zero, the door can only handle
reply packets stored in the older *.upi and
*.net formats. (these formats are discussed
later.)

packet_id the packet id used by the host system, which
can be used by readers to properly access
mail packet control files even if the mail
packet itself has been renamed. (if this
field is not filled, readers should assume
that the root name of the mail packet is the
packet id.)

the inf_area_info structure fields are defined as follows:

areanum the area number on the host system for which
the record defines, specified as an ascii
string. this field will correspond to the
similar field in the *.mix structure (dis-
cussed later). this does not necessarily
have to be a number, so a case-insensitive
match should be performed when doing any
comparisons using this field.

echotag the area tag name for which the record de-
fines. this field is used in the reply
packet to link reply messages to the destina-
tion areas on the host system, and must be
unique (i.e. there cannot be two or more
identical area tags).

title the message area description.

area_flags specifies the unique characteristics of the
message area for which the record defines.
most of the flags are self-explanatory, as
specified in the header file; the network
area flags, however, need to be clarified.
if the message area is part of a network
(i.e. fidonet), the inf_echo flag should be
set; this will allow a reader to properly
handle network mail. if the area is for
private network mail, the inf_netmail flag
should also be set.

network_type specifies the network type for which the
defined message area belongs. note that the
network type is specified as a full byte
value, not as a bit flag. (if the inf_echo
flag is not set, the network type can be
ignored, obviously.)


the *.mix file (mix_rec)
========================

each record in the *.mix file points to the beginning of the area in
the *.fti file that contains the header information for messages that
were obtained from each message area. note that *only* the areas for
which messages were extracted will have a corresponding *.mix record.

each structure field is defined as follows:

areanum corresponds to the identical field in the
*.inf record for the particular message area.
it is used by the reader to coordinate the
information between the *.inf and *.mix
records. again, case-insensitive comparisons
should be performed when using this field, as
this field does not have to contain a numeri-
cal value.

totmsgs total number of messages in this area. up to
65,535 messages per area are allowed (the
limit of an unsigned 16-bit integer).

numpers total number of messages in this area that
are directed specifically to the user who
bundled the mail packet. this value is
usually obtained during message bundling by
comparing the name in the "to:" field to the
user name for every message, and incrementing
a counter if they match. (reader authors can
feel free to disregard this value and perform
their own search for personal messages, once
the packet is loaded into the program.)

msghptr pointer to the first record in the *.fti file
that corresponds to this message area. note
that this specifies the byte offset into the
*.fti file, *not* the record number; thus,
programmers can use the seek() or lseek()
functions to quickly point to the proper
section of the *.fti file.


the *.fti file (fti_rec)
========================

the *.fti record specifies the header information for messages in the
mail packet, along with additional information such as the length of
the message and the pointer to the message stored in the *.dat file.
these records are stored sequentially in the *.fti file, with all the
headers for the first message area stored first, followed by the
headers for the second message area, and so forth.

most of the fields are self-explanatory, with the following fields
described in more detail:

msgnum the message number as stored on the host
system. this provides an "absolute" message
number for use with message threading.

replyto indicates the absolute message number for
which this message is a reply (the "previous"
message). if zero, there is no previous
message.

replyat indicates the absolute message number of a
reply to this message (the "next" message).
if zero, there is no next message.

msgptr pointer to the start of the message text in
the *.dat file. this is a byte offset, thus
a programmer can use the seek() or lseek()
functions to quickly point to the proper
position in the *.dat file.

msglength length of the message text (in bytes) plus 1.
the addition of 1 is done to compensate for
the required space character in front of the
message text (described below).

flags bit-mapped message status flags. note that
for fidonet network messages, these flags are
*not* stored in the exact same order as
specified in the fidonet technical standards,
even though they are identical in function.

the *.dat file
==============

the *.dat file contains the text of all messages obtained from the
host system. valid messages begin with an ascii space character (" ",
decimal 32, hexadecimal 20), followed by the message text itself.
note that the space character is *not* to be considered a part of the
message text; it is simply a marker used to indicate the start of a
valid block of text, and *must* be present for each message specified
in the *.fti file (even if there is no message text at all). the
messages in the *.dat file should be in the same order as specified in
the *.fti file, though this is not a requirement (due to the fact that
the *.dat file is unstructured).


the *.xti file (xti_rec)
========================

each record in the *.xti file corresponds to a record in the *.fti
file, and specifies extended status information for each message (the
"save", "reply", "print", and "delete" flags used by the blue wave
reader). note that this file is *not* created by any blue wave door;
it is created on-the-fly by the blue wave reader. (the fields and
flags used in xti_rec are self-explanatory, thus they will not be
explained here.)

note: the *.xti file is not an official part of the blue wave
specification. it is documented here solely for the benefit
of third-party authors who might wish to create a similar
file for their own applications. if so, authors should not
use the "xti" extension on their own files if they differ
from the xti_rec format, as this extension is used on the
file created by the blue wave offline mail reader (which
expects the file to use the xti_rec format). on the other
hand, authors can use the "xti" extension as long as the
xti_rec format is used.


the *.upl file (upl_header & upl_rec)
=====================================

the *.upl file consists of two "parts": a header, which contains
information about the reader used to create the reply packet, and a
series of records that contain the information on all messages con-
tained in the reply packet.

most of the fields in the *.upl file are self-explanatory. the fol-
lowing, however, deserve extra attention, starting with upl_header:

upl_header_len length of upl_header used in the reply
packet. reader authors are required to fill
this field; door authors should use this
field to properly parse the *.upl file.
refer to the header file (under the
inf_header section) for more information on
using this field.

upl_rec_len same as above, but specifies the length of
the upl_rec structure.

reader_tear contains the abbreviated name of the reader
that created the reply packet (i.e. "blue
wave", "q-blue", "wave rider", etc.). this
text can be used by the door to append tear
lines and other reader-identifying lines to
the message text, if desired. (door authors
should take steps to use alternate text in
case this field is not filled; using the name
of the door is usually a good alternative.)

likewise, here is additional detail on several fields in the upl_rec
structure:

unix_date the date/time that the reply message was
written, specified as the number of seconds
since 01/01/1970 (i.e. "unix-style"). this
value can easily be obtained by c programmers
via the time() function; in addition, the
ansi c standard library contains additional
functions to manipulate a unix-style time
field, enough to satisfy most any require-
ment (provided your compiler has support
for them, though any compiler that claims to
be ansi c compliant will contain all those
functions and more).

filename the name of the file that contains the text
of the message. there is no requirement on
how this file is to be named; such schemes
are left to the individual. (the blue wave
reader uses "xxx.yyy", where "xxx" is the
area number -- derived from the "areanum"
field in inf_area_info -- and "yyy" is a
unique number for each message that corre-
sponds to that area. note that this is only
provided as an example; you are not required
to use this scheme, so long as the filenames
are properly specified.)

area_flags this field is used internally by the blue
wave reader; as such, it *must not* be used
by any other application.

net_dest used to specify the destination address, as a
text string, on messages destined for non-
fidonet networks. (fidonet addresses are
specified by the "destzone", "destnet",
"destnode", and "destpoint" fields in
upl_rec.) the format of the address is,
naturally, dependent on the network in ques-
tion. if the message is for a non-networked
message area, this field is ignored.


the *.upi (upi_rec) and *.net (net_rec) files
=============================================

the *.upi and *.net files are similar to the *.upl file, in that they
specify the information for all messages in the reply packet (*.upi
for non-netmail messages, *.net for netmail messages only). the
fields in these files are similar in form and function to those in the
*.upl file, thus they will not be elaborated upon here.

*.upi and *.net were used in older versions of the blue wave reader,
and have effectively been replaced by the more informative (and
flexible) *.upl file. however, some older blue wave doors cannot
handle the new *.upl file; for this reason, authors should provide
support for *.upi and *.net, as well as *.upl. readers should create
all three files, and doors should include code to process all three
(giving preferential treatment to *.upl, of course). eventually,
*.upi and *.net will be phased out altogether.


the *.req file (req_rec)
========================

the *.req file is simply a list of files that the user wishes to
obtain (download) from the host system. the implementation of such a
feature is left to the individual programmer.

note: current blue wave doors do not allow wildcard characters
("*" and "?") in filenames, nor do they provide support for
requesting more than 10 files. these are limitations of the
blue wave doors themselves, *not* of the blue wave file
specifications. this information is provided merely for
informational purposes; authors should not feel bound by
these restrictions in their own programs.


the *.pdq file (pdq_header & pdq_rec)
=====================================

the *.pdq file is used to perform offline configuration of the door
via the reader. this file consists of two parts: a header, which
contains non-message area configuration information, and a series of
records that indicate the message areas to enable for scanning.

the fields in both pdq_header and pdq_rec are mostly self-explanatory,
though the process of selecting message areas needs elaboration. if
the pdq_area_changes flag is set (in the "flags" field of pdq_header),
the door should enable all the message areas (specified in pdq_rec
records) that follow the header. this is most easily accomplished by
first turning off all message areas that were active, then turning on
each area indicated by the pdq_rec records (provided the user has
access to them on the host system, of course). this is the method
used by the blue wave doors, as it seems to be the easiest way to
accomplish the task.

note: this method of performing offline configuration will change
in a subsequent revision of the blue wave specifications, so
be ready for it!


appendix a - how to create a blue wave mail packet
==================================================

the following steps outline the basic method for creating a blue wave
mail packet. note that this outline is highly generalized; the
details of such a process are left to the programmer to implement as
desired.

1. open the *.inf, *.mix, *.fti, and *.dat files for writing; if
they currently exist, they should be truncated and overwritten.

2. fill the inf_header structure and write it to the *.inf file.

3. obtain the information for the first message area, fill the
inf_area_info structure, and writing it to the *.inf file.

4. repeat step 3 for all remaining message areas.

5. scan through the messages for the first message area and
determine how many messages need to be packed. if messages need
to be packed, fill the mix_rec structure and write it to the
*.mix file, then perform the following steps:

a. read the next new message from the message area.

b. fill the fti_rec structure and write it to the *.fti file.

c. write the message text to the *.dat file.

d. repeat steps a through c until all messages are packed.

6. repeat step 5 for all remaining message areas.

note: an alternate method for the actions described in steps
5 and 6 is to scan through the message base and write
the fti_rec records and the *.dat text first, then
write the mix_rec. as mentioned above, however, the
method you use is entirely up to you.

7. use an archiving utility (arc, pkzip, etc.) to pack the *.inf,
*.mix, *.fti, and *.dat files into an archive file. the file
should be named according to the naming convention specified
earlier in this document.

note that these steps do not take into account such things as bulletin
files, keywords, filters, macros, and so forth, but again, these are
the details which are left to the programmer to implement.


appendix b - how to create a blue wave reply packet
===================================================

unlike creating a mail packet, the creation of a reply packet is not a
linear process; there is no outline that can be followed. basically,
when the reader creates a reply message, a upl_rec record is filled
and written to the *.upl file for each reply created by the reader; if
the *.upl file doesn't exist, then it will have to be created (natu-
rally) by filling and writing a upl_header to the *.upl file before
adding upl_rec records. this process is performed on-the-fly, at the
time the user creates reply messages.

the reply archive itself is created by an archive utility (arc, pkzip,
etc.), using the filename conventions specified earlier in this docu-
ment. in order to prevent "orphaned" files -- messages deleted by the
reader -- from showing up in the reply archive, reader authors should
delete the archive before running the archive utility; this will force
a "fresh" file, free from excess clutter, to be created from scratch.


appendix c - the blue wave structures and turbo pascal
======================================================

the blue wave packet structures are provided as a header file for c
compilers, since the blue wave offline mail reader and the blue wave
offline mail doors from cutting edge computing are written in c.
however, for the convenience of programmers who write programs using
borland's pascal compilers (turbo pascal and borland pascal), a header
file for use in pascal programs (bluewave.inc) is provided. please
note the following changes and restrictions from the c header imple-
mentation:

1. as implemented, the pascal header is to be included within a
source file, i.e.:

{$i bluewave.inc}

industrious pascal programmers can easily convert this header
file to a unit if so desired.

2. the structure names and constants remain identical, i.e. mix_rec,
fti_rec, and so on, and are defined as "record" data types.
thus, defining a structure is similar to any other pascal data

type, i.e.:

var infheader : inf_header;
infrec : inf_area_info;
mixrec : mix_rec;
ftirec : fti_rec;

also note that unlike c, pascal is not case-sensitive with re-
gards to variable and type names. thus, inf_header can also be
accessed as "inf_header", "inf_header", or even "inf_header".

3. due to a conflict with reserved keywords in pascal, the "from"
and "to" fields in fti_rec, msg_rec, upi_rec, and upl_rec have
been renamed to "mfrom" and "mto". all other field names are
identical between the c and pascal headers.

4. bit flags are defined as sets in the pascal header, and are set
and reset using the pascal set operators (+ and -). for example,
to set the inf_echo and inf_netmail flags, the following state-
ment:

infrec.area_flags := infrec.area_flags + [inf_echo,
inf_netmail];

can be used.

5. with one exception, data types in pascal are stored identically
to their c counterparts (i.e. pascal "longint" and c "long int"
are stored, identically, in 4 bytes.). the lone exception is
strings. in c, strings are stored as a series of characters
terminated with a 0 byte. in pascal, strings are stored as a
length byte followed by the characters that make up the string.
since the blue wave format is centered around the c language,
pascal programmers will have to convert strings between c and
pascal formats. to aid in this endeavor, strings in the pascal
header are defined as arrays of bytes (i.e. "array[1..43] of
byte"), but you will have to devise your own routines to convert
strings between the two formats.

there are undoubtedly other areas where c and pascal differ, but this
should get you started in the right direction.

please note that cutting edge computing does not provide support for
pascal programmers using these structures. the pascal header is
provided solely for your convenience; other than that, you are on your
own. thus, it is recommended that only pascal programmers with some
experience in using data created by (and expected by) c programs use
these structures, as handling the differences between the languages is
not something that is easily handled by the novice.


appendix d - serial numbers in mail and reply packets
=====================================================

the serial number fields in the *.inf, *.upi, and *.upl structures are
used mainly by the blue wave reader and doors from cutting edge com-
puting (using what is, naturally, a proprietary algorithm to determine
the actual serial numbers). authors are free to use these fields as
they see fit, though the values in the fields will undoubtedly be
meaningless to other blue wave-compatible programs. in fact, unless
you're creating your own series of blue wave-compatible doors and
readers, the serial number fields are practically useless to third-
party authors.

(as an example, the blue wave doors will examine the reader name field
in the *.upl header to determine if a reply packet was created by the
blue wave reader. if it was, then the serial number is used to deter-
mine if "[nr]" should be added to the tear line. on the other hand,
if the packet was created by a different reader, the blue wave doors
will ignore the serial number and never put "[nr]" in the tear line.)