.\" $Id: JAM_AddMessage.3,v 1.1 2002/11/09 00:37:16 raorn Exp $
.\"
.TH JAM_AddMessage 3 2002-11-07 "" "JAM subroutine library"
.SH NAME
JAM_AddMessage \- Add a message to message base
.SH SYNOPSIS
.nf
.B #include <jamlib/jam.h>

.BI "int JAM_AddMessage(s_JamBase*      " Base_PS ","
.BI "                   s_JamMsgHeader* " Header_PS ","
.BI "                   s_JamSubPacket* " SubPack_PS ","
.BI "                   uchar*          " Text_PC ","
.BI "                   ulong           " TextLen_I ");"
.RE
.fi
.SH DESCRIPTION
Adds a message to the message base. Fully automatic.
.SS Arguments
.TP
.I Base_PS
The message base to use
.TP
.I Header_PS
A pointer to the message header struct. The function will set the following
header fields: \fISignature\fP, \fIRevision\fP, \fITxtOffset\fP, \fITxtLen\fP,
\fISubfieldLen\fP and \fIMsgNum\fP. Whatever you set these fields to will be
overwritten.
.TP
.I SubPack_PS
A subfield packet handler, containing all subfields for the message.
.TP
.I Text_PC
A pointer to the first byte of the message text.
.TP
.I TextLen_I
The length of the message text, excluding any zero termination characters.
.SH "RETURN VALUE"
.TP
.B 0
if successful
.TP
.B JAM_IO_ERROR
if an I/O error occured. See
.BR JAM_Errno (3)
.TP
.B JAM_NOT_LOCKED
if the message base is not locked
.SH EXAMPLES
.nf
s_JamSubPacket*   SubPacket_PS;
s_JamSubfield     Subfield_S;
s_JamMsgHeader    Header_S;
uchar             Text_AC[64];
uchar             Field_AC[64];

/*
**  Fix message header
*/

JAM_ClearMsgHeader(&Header_S);
Header_S.DateWritten = time(NULL);

/*
**  Create subfield packet
*/

SubPacket_PS = JAM_NewSubPacket();
if (!SubPacket_PS) {
    printf("JAM_NewSubPacket returned NULL.\\n");
    return;
}

/* set up subfield 1 */
strcpy(Field_AC, "This is field #1");
Subfield_S.LoID   = JAMSFLD_SENDERNAME;
Subfield_S.HiID   = 0;
Subfield_S.DatLen = strlen(Field_AC);
Subfield_S.Buffer = Field_AC;
JAM_PutSubfield(SubPacket_PS, &Subfield_S);

/* set up subfield 2 */
strcpy(Field_AC, "This is field #2");
Subfield_S.LoID   = JAMSFLD_RECVRNAME;
Subfield_S.HiID   = 0;
Subfield_S.DatLen = strlen(Field_AC);
Subfield_S.Buffer = Field_AC;
JAM_PutSubfield(SubPacket_PS, &Subfield_S);


/*
**  Add message
*/

strcpy(Text_AC, "Hello world!\\rThis is a test.");

/* [lock the message base] */

Result_I = JAM_AddMessage(Base_PS, &Header_S, SubPacket_PS,
                           Text_AC, strlen(Text_AC));
if (Result_I) {
  printf("JAM_AddMessage returned %d.\\n", Result_I);
  return;
}

/* [unlock the message base] */

JAM_DelSubPacket(SubPacket_PS);
.fi
.SH AUTHOR
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>.
.SH SEE ALSO
.BR jamlib (3),
.BR JAM_AddEmptyMessage (3),
.BR JAM_DeleteMessage (3),
.BR JAM_DelSubPacket (3),
.BR JAM_NewSubPacket (3),
.BR JAM_PutSubfield (3),
.BR JAM_LockMB (3),
.BR JAM_Errno (3)
.\" vim: ft=nroff