Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
JAMLIB(3)		    JAM	subroutine library		     JAMLIB(3)

NAME
       jamlib -	a JAM subroutine library

DESCRIPTION
       These are a collection of subroutines that encapsulate much of the for-
       mat-specific and	tedious	details	of the JAM message  base  format.  The
       idea  is	 that application programmers by using these routines can con-
       centrate	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  sys-
       tem  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  ap-
       plication 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 sys-
       tem: 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 sys-
       tems  have  C compilers than C++	compilers, and more people know	C than
       C++. Also, converting this library to a C++ class should	be fairly sim-
       ple.  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:

       o      All library-global identifiers are  prefixed  with  'JAM_'.  All
	      file-global  identifiers are prefixed with 'jam_'. Local identi-
	      fiers do not have	prefixes.

       o      All variables have a suffix describing their  basic  type.  Suf-
	      fixes 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)

       o      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 informa-
       tion  and  is  therefore	added to the end where it does not disturb the
       reader.

   The Functions
       The library is divided into five	groups:

       o      Message base functions

       o      Message functions

       o      Subfield functions

       o      LastRead functions

       o      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  ob-
       tained  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:

       o      Message Header

       o      Message Header Subfields

       o      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 sec-
       tion 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 fea-
       sible 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 iden-
       tified 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	remem-
       bering 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	 auto-
       tools, 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 un-
       clear.  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 Jo-
       han Billing <billing@df.lth.se>.

SEE ALSO
       If you are extra	curious	about the JAM message format,  I  suggest  you
       get  a  hold  of	 an archive called JAMAPI.ARJ. That archive contains a
       file called JAM.DOC which is the	file I have used as reference for  the
       development of these routines.

				  2002-11-07			     JAMLIB(3)

NAME | DESCRIPTION | HISTORY | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=jamlib&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help