NAME

jamlib - a JAM subroutine library

DESCRIPTION

These are a collection of subroutines that encapsulate much of the format-specific and tedious details of the JAM message base format. The idea is that application programmers by using these routines can concentrate on the more high-level issues of their programs instead of worrying about their JAM routines.

I [Bjorn Stenberg] wrote these routines primarily because I needed them myself. I was trying to implement JAM support in my FrexxLink BBS system and was frustrated by the poor level of documentation supplied in the JAMAPI archive distributed by the JAM authors. Finally, I dove into the JAMAPI source code in a desperate attempt at finding out how to use it. To my despair, I discovered that the JAMAPI is targeted at a very low level. I would need to implement a lot of JAM-handling code into my own program.

This library is an attempt to do two things:

Firstly, provide an, at least sparingly, documented API, allowing application programmers to easily implement JAM into their programs.

Secondly, raise the level of functionality above that of the original JAMAPI package, so that the application programmer does not have to learn and understand all the internals of the JAM message base format to implement support for it.

I have not succeded completely on any of the two points, of course. Documentation can never be too good, and there are still a few things about JAM you must know in order to use it. But I think I have made it somewhat easier than perhaps was the case before.

The Source Code

I made a point of making this library as system independant as I could. Only one function needs to be altered when porting this to another system: The file locking. ANSI C does not include file locking so there is not much I can do about it.

The choice of C over C++ is a part of this philosophy aswell. More systems have C compilers than C++ compilers, and more people know C than C++. Also, converting this library to a C++ class should be fairly simple. If you do, send me a copy.

I use some naming conventions throughout the code and in the examples. These are invented by myself as a reaction to the stunningly ugly and hard-to-read Hungarian Notation promoted by some people. The rules of my notation are simple:

•

All library-global identifiers are prefixed with ´JAM_´. All file-global identifiers are prefixed with ´jam_´. Local identifiers do not have prefixes.

•

All variables have a suffix describing their basic type. Suffixes used in this library are:

  _I - integer                        (int      Example_I)
  _C - character                      (char     Example_C)
  _S - struct                         (struct   Example_S)
  _P - pointer                        (void*    Example_P)
  _A - array

Suffixes are then combined, to show the correct type:

  _PI  - pointer to integer           (int*     Example_PI)
  _PC  - pointer to char              (char*    Example_PC)
  _AC  - array of char                (char     Example_AC[x])
  _PPS - pointer to pointer to struct (struct** Example_PPS)

•

Functions do not have suffixes

The whole idea is that it is quicker to read and comprehend a variable called ´Text_PC´ than one called ´pszText´. We read from left to right, and thus the most important information - the name - should be the leftmost data in the word. The variable type is additional information and is therefore added to the end where it does not disturb the reader.

The Functions

The library is divided into five groups:

•: Message base functions
•: Message functions
•: Subfield functions
•: LastRead functions
•: Miscellanous functions

Message base functions

These functions handle JAM message bases, by opening, locking, scanning etc the contents of a message base. These are fairly straight-forward and simple routines that you should have little, if any, trouble with.

A message base is identified by a message base handle, which is obtained from either JAM_OpenMB(3) or JAM_CreateMB(3). All functions that read or write from the message base take this handle as parameter, to know which message base to use.

JAM_OpenMB(3): Open a message base
JAM_CloseMB(3): Close message base
JAM_CreateMB(3): Create a new message base
JAM_RemoveMB(3): Remove a message base
JAM_LockMB(3): Lock message base for exclusive access
JAM_UnlockMB(3): Unlock message base
JAM_ReadMBHeader(3): Read message base header
JAM_WriteMBHeader(3): Write message base header
JAM_FindUser(3): Find message to a user
JAM_GetMBSize(3): Get the number of messages in message base

Message functions

These functions handle individual JAM messages. A JAM message contains of three parts:

•: Message Header
•: Message Header Subfields
•: Message Text

The message header is a simple C structure and the message text is a simple text buffer.

The subfields, however, are a bit more tricky. These contain everything that is not covered by the header, including the TO, FROM, SUBJECT fields, origin and destination network adresses etc. There can be an unlimited number of subfields to a message.

In this routine library the subfields are encapsulated by a ´subfield packet´, which is handled by its own set of routines. See a later section of this document for an explanation of those.

JAM_ReadMsgHeader(3): Read a message´s header and its subfields
JAM_ReadMsgText(3): Read a message´s text
JAM_AddMessage(3): Add a message to message base
JAM_AddEmptyMessage(3): Add a empty message entry to a message base
JAM_ChangeMsgHeader(3): Change a message´s header
JAM_ClearMsgHeader(3): Clear a message header structure
JAM_DeleteMessage(3): Delete message from messagebase

Subfield functions

As described earlier, a subfield is a part of the message header. Due to the complexity of the different network types in use, it is not feasible to try and cram all data into one header struct. Therefore, JAM uses a fairly small header struct and instead marks all additional data fields as ´subfields´.

In order to make life a little more easy, I have used the concept of a container for all subfields. I call it a ´Subfield Packet´. It is identified by a struct pointer, and should be looked upon as a file or a list that you manipulate via the following five functions:

JAM_NewSubPacket(3): Create a new subfield packet
JAM_DelSubPacket(3): Delete a subfield packet
JAM_GetSubfield(3): Get a subfield from a subfield packet (not reentrant)
JAM_GetSubfield_R(3): Get a subfield from a subfield packet (reentrant)
JAM_PutSubfield(3): Put a subfield into a subfield packet

LastRead functions

JAM implements the often-used concept of high water marking for remembering which user read how many messages in each area.

Personally I think this concept stinks, since it does not store *which* messages a user has read, only the number of the highest message he has read. But since it´s a part of JAM and it´s fairly straightforward and easy, I´ve implemented two support functions for it.

I would, however, strongly recommend all BBS programmers to use proper message mapping systems instead, so your users can read their messages in whatever order they wish.

JAM_ReadLastRead(3): Read a lastread record
JAM_WriteLastRead(3): Write a lastread record

Miscellanous functions

JAM_Crc32(3): Calculate CRC32 on a block of data
JAM_Errno(3): Specify I/O error

HISTORY

JAMLIB 1.0 was originally released by Bjorn Stenberg 1996-03-06. Since the original license did not permit modification of the library, Johan Billing contacted Bjorn Stenberg and asked him to change the license. Bjorn Stenberg agreed to change the license to the GNU Lesser General Public License 1999-12-21.

After that, some minor additions and bug fixes were made by Johan Billing and JAMLIB 1.1 was released under the new license.

Somewhen, after 1.2 release or so, Sir Raorn moved JAMlib to GNU autotools, again with some minor additions an bugfixes.

AUTHOR

All original code except for the CRC32 routine was written by Bjorn Stenberg. The CRC32 code was rewritten by Johan Billing for JAMLIB 1.1 to replace the original CRC32 code whose origin and copyright was unclear. The jam.h header file is a compilation of the best from the various header files in the JAMAPI package with some of additions by Bjorn Stenberg as well. Additions and modifications by Johan Billing and Sir Raorn.

The JAM message base proposal is:

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

For questions about JAMLIB, please contact:

Sir Raorn <raorn@altliux.ru>

Johan Billing <billing@df.lth.se>

If you wish to contact Bjorn Stenberg, his current e-mail address (as of 1999-12-21) is bjorn@haxx.nu.

This manual page was created by Sir Raorn <raorn@altlinux.ru>, based on original JAMlib documentation by Bjorn Stenberg <bjorn@haxx.nu> and Johan Billing <billing@df.lth.se>.