The write-to-jam C function, Dec 1993
An example of a function to write to the
JAM(mbp) (the message base format by Joaquim
Homrighausen, Andrew Milner, Mats Birch, and
Mats Wallin). This message base is in use
with many BBS's and this sample code is meant
primarily for door authors needing a hand in
writing JAM messages. Includes JAM library
for MSC & Borland C compilers. By Michael
Lecuyer Fidonet 1:2600/140, Internet
[email protected]

V 1.2


THE "WRITE MESSAGE TO JAM BASE" FUNCTION


Copyright 1993 Michael Lecuyer.
ALL RIGHTS RESERVED.

FidoNet: 1:2600/140, Internet: [email protected]


Note from the JAM authors:

All applications that support JAM must include one of the following
notices in their documentation and somewhere in the product's credit
section:

"JAM(mbp) - Copyright 1993 Joaquim Homrighausen, Andrew Milner,
Mats Birch, Mats Wallin.
ALL RIGHTS RESERVED."

or

"This product uses the JAM(mbp) API -
Copyright 1993 Joaquim Homrighausen, Andrew Milner, Mats Birch,
Mats Wallin. ALL RIGHTS RESERVED."

No organization, company, person, entity, or other being may impose
any fees for any reason for providing this document or the
accompanying API. This document and the accompanying API may not be
sold or otherwise transferred for personal or company gain under any
circumstances.

This version is for the JAMAPI 1.001.

There is another version of the JAMAPI due out in the first quarter
of 1994. At that time an update of JAMwrite will be issued if
necessary.

My reasons for presenting this function to the door writing world are
both to promote the JAM base and for barter. If you find this code
has helped your door support the JAM message base I would appreciate
a registered copy of your programme sent to 1:2600/140 in return.

The JAM message base provides an important step out of the dark ages
of previous message bases, such as the Hudson Message Base. Although
the finest features of the JAM base may escape most non-programmers
and possibly some software authors you may find yourself in need of
JAM support. Probably you only need to be able to send a message or
two to a BBS caller or the sysop and you don't give a damn about the
new upstart format.

True believer or curmudgeon, this function can save you time while
lining your pockets with gold as the registration fees pour in, all
because your product supports the JAM message base format 🙂

A sample programme will show how easy it is to send a JAM message.
You need to capture one piece of information from either the BBS
itself or from the sysop installing your product. The path to the
JAM message base is the only externally supplied information needed
by this function. The rest of the information is up to you.

Included in the archive are libraries in small and large model of the
JAMAPI for both Borland 3.00 C/C++ and the MicroSoft V7.00
compilers. You must work with the JAMAPI to produce libraries for
other compilers. The Borland V3.0 libraries are in the file
BORLAND.ZIP and the Microsoft V7 libraries are in MSC.ZIP.

To compile and link with your programme the libraries and header
files should be in the directory with your own source. Imaginitive
people will find a way around this.


A sample programme:

#include "writejam.h"

main()
{
char *jambase = "C:\\mail\\test";
char *from = "System Operator";
char *to = "Michael Lecuyer";
char *subject = "Testing the jamwrite";
char *text = "This is a test message that we will want to test\n"
"which should be easy enough\n";

JAMcopyright(); // Legal requirement for using the JAM API


write_jam(jambase, from, to, subject, text, MSG_LOCAL | MSG_PRIVATE);

return 0;
}


The write_jam() function takes 6 parameters.

1) The path to the JAMbase - this might look something like "C:\MAIL\TEST"
This path includes the file name for the jam base but no extensions
are used. The JAM base API will create the files:
TEST.JDT (message text)
TEST.JDX (index to messages)
TEST.JHR (JAM header information)
TEXT.JLR (JAM last read pointers)

2) From Field: This is the name of the sender

3) To Field: The name of the receiver

4) Subject Field: What the message is about

5) Text: pointer to a buffer containing the entire text of the message

6) Flags: these flags are found in the file JAM.DOC and JAM.H in the
JAMAPI.

The JAM Api header files and JAM library are expected to be in the
current directory.

The function returns 0 if it fails, 1 if it succeeds in writing to
the message base. Some parts of the function will print out an error
on the console. For those who find that unacceptable the print
statements should be removed or modified.

The flags are defined as (as found in the file JAM.H):

MSG_LOCAL 0x00000001L Msg created locally
MSG_INTRANSIT 0x00000002L Msg is in-transit
MSG_PRIVATE 0x00000004L Private
MSG_READ 0x00000008L Read by addressee
MSG_SENT 0x00000010L Sent to remote
MSG_KILLSENT 0x00000020L Kill when sent
MSG_ARCHIVESENT 0x00000040L Archive when sent
MSG_HOLD 0x00000080L Hold for pick-up
MSG_CRASH 0x00000100L Crash
MSG_IMMEDIATE 0x00000200L Send Msg now, ignore restrictions
MSG_DIRECT 0x00000400L Send directly to destination
MSG_GATE 0x00000800L Send via gateway
MSG_FILEREQUEST 0x00001000L File request
MSG_FILEATTACH 0x00002000L File(s) attached to Msg
MSG_TRUNCFILE 0x00004000L Truncate file(s) when sent
MSG_KILLFILE 0x00008000L Delete file(s) when sent
MSG_RECEIPTREQ 0x00010000L Return receipt requested
MSG_CONFIRMREQ 0x00020000L Confirmation receipt requested
MSG_ORPHAN 0x00040000L Unknown destination
MSG_ENCRYPT 0x00080000L Msg text is encrypted
MSG_COMPRESS 0x00100000L Msg text is compressed
MSG_ESCAPED 0x00200000L Msg text is seven bit ASCII
MSG_FPU 0x00400000L Force pickup
MSG_TYPELOCAL 0x00800000L Msg is for local use only (not for export)
MSG_TYPEECHO 0x01000000L Msg is for conference distribution
MSG_TYPENET 0x02000000L Msg is direct network mail
MSG_NODISP 0x20000000L Msg may not be displayed to user
MSG_LOCKED 0x40000000L Msg is locked, no editing possible
MSG_DELETED 0x80000000L Msg is deleted

For a private message to the sysop or caller the flags might be:

MSG_LOCAL | MSG_PRIVATE

or for more a public message:

MSG_LOCAL

The MSG_LOCKED flag means no editing by anyone implying that the
message base cleaning programmes aren't to touch it either.

Preparing messages for a Fidonet type tosser is beyond the scope of
this writejam() function. If you need such a function contact the
author.

One of the best (and possibly only) ways to test that the function
has worked properly is to use the JAMUTIL programme included in the
JAM API.

This programme has been compiled successfully under Borland C/C++
V3.0 and Borland C V2.0. The PRO version of V3.0 has a builtin
getpid() function. Because not all libraries include getpid() there
is code to to simulate this call. Although the function very close
to what Borland uses, it can be removed and the Borland Runtime
Library version used if you have the right version of the compiler.
For people compiling for another OS this function must be replaced.

The function also requires the appropriate JAM API library be created
and made available. Help on compiling the library is available with
the JAMAPI. It is important to make the correct model library for
your project. The JAM API will compiler under Microsoft, Borland,
and several other compilers for DOS, Windows, OS/2 and for the Sun
workstation using the GNU GCC compiler.

I can be reached at Fidonet address 1:2600/140 or on the Internet
as [email protected]. I also be contacted through the RA_UTILITY echo
on Fidonet. Please report problems and suggestions through any
of these channels.


Borland and Microsoft are registered trademarks of their respective
companies.