PicLan-IP Email Subroutines

PicLan-IP version 2.0.0 (build 129)

January 22, 1999

The PicLan-IP email sub-system includes a number of subroutines that are uses to query and update the email database files. These functions are documented here.

Overview

The EMAIL,HDR file has cross-references stored in the EMAIL,HDR$ index file. You should use these subroutines to manipulate email items.

Subroutines

All of these functions are implemented as mv/BASIC subroutines and are CALLed from within your mv/BASIC application code. The subroutines are defined and cataloged in the PICLAN-IP account. In order to use these subroutines from your application you must follow these proceedures:

Compile your mv/BASIC code with PRECISION 4
Catalog all program files in PLIP.BP
Have access to the following account files:

PLIP.BP
PLIP.CTRL
EMAIL
WWW.CTRL

These subroutines are designed to not use any mv/BASIC common and should be compatible with most application programs without difficulty.

The "2" Subroutines

Many of these subroutines have two different version. The version whose name ends in "2" are only useable from within applications that are called by the PicLan-IP thread processes. These routines assume that PicLan-IP data files are already open and control variables are already setup in BASIC COMMON variables. If you use these routines from other applications, they will not function properly and you may corrupt email indexes. These "2" subroutines are considerably faster than the generic entry points because they do not need to open files and read configuration records on every call.

Mail Utility Subroutines

These functions are general purpose functions that help to manage PicLan-IP mail functions.

Message Generation Routines

PLM.BUILD.MSG
PLM.SEND

Email Database Update Routines

PLM.UPDATE
PLM.MAT.UPDATE

Email Mailbox Query Routines

PLM.MAILBOX.INFO

PLM.BUILD.MSG(PARMS,MAT CONTENTS,MSG,FR.ADDR,TO.ADDR,R.ERR)

Build a mail message from parameters

PARMS A dynamic array containing message parameters

MAT CONTENTS A dimensioned array containing sub-part contents.

MSG The resulting message text.

FR.ADDR The resulting "from address"

TO.ADDR The resulting "to address" array

R.ERR An error string if an error is encountered building the message

This is a generic subroutine used to build messages. Additional documentation can be found in the source code of the function which is included in the PLIP.BP file.

PLM.SEND(FR.ADDR,TO.ADDR,MSG,ID,R.ERR)
PLM.SEND2(FR.ADDR,TO.ADDR,MSG,ID,R.ERR)

Schedule a mail message for transmission

FR.ADDR The "from address" that is sending the message

TO.ADDR The "to address" array that is where the message is to be sent.

MSG The message text as a dynamic array.

ID The resulting message ID.

R.ERR An error string if an error is encountered building the message

This is the subroutine used to schedule a message for transmission.

PLM.UPDATE(CMD,ID,DTA)
PLM.UDPATE2(CMD,ID,DTA)

Update the EMAIL,HDR data file including indexes

CMD 'WRITE' to write item or 'DELETE' to delete item.

ID The mail item-id to manipulate.

DTA The dynamic array to WRITE.

This subroutine will perform WRITE and DELETE type statements maintaining email index integrity. You should always use this subroutine whenever you update the EMAIL,HDR file.

PLM.MAT.UPDATE(CMD,ID,MAT DTA)
PLM.MAT.UPDATE2(CMD,ID,MAT DTA)

Update the EMAIL,HDR data file using dimensioned arrays

CMD 'WRITE' to write item or 'DELETE' to delete item.

ID The mail item-id to manipulate.

MAT DTA The dimensioned array to MATWRITE. Dimension at 51 elements.

This subroutine will perform MATWRITE and DELETE type statements maintaining email index integrity. You should always use this subroutine whenever you update the EMAIL,HDR file.

PLM.MAILBOX.INFO(ID,MSG.LST,MSG.SIZES,TOT.SIZE)
PLM.MAILBOX.INFO2(ID,MSG.LST,MSG.SIZES,TOT.SIZE)

Query the contents of a POP3 mailbox

ID The name of the mailbox to query.

MSG.LST A array of attributes of the message ids that are currently in the mailbox.

MSG.SIZES An array of attributes of the message sizes in bytes.

TOT.SIZE The total size in bytes of all messages in the mailbox.

This subroutine is used to get lists of the messages that are in a POP3 mailbox. Because mailboxes are indexed with BTREE data structures, you must use this functions to query these indexes.