Documentation file for HRxMail.dll functions.

30 January 1997

------------------------------------------------------------------------------
------------------------------------------------------------------------------

Function Name:  HStoreMail
Syntax:         HStoreMail( <username>, <mail directory>, <msg> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<msg> -- The message file to store in the user's mailbox.

This function accepts the arguments given and stores the message file
in the user's mailbox.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"3 Error. Cannot store mail."
"4 Error. Error closing mailbox."
"OK. Mail stored."

------------------------------------------------------------------------------

Function Name:  HNumMail
Syntax:         HNumMail( <username>, <mail directory> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.

This function returns the number of mail messages in the user's mailbox.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"OK. x messages."  (where x is the number of messages present.)

------------------------------------------------------------------------------

Function Name:  HRetrMailFile
Syntax:         HRetrMailFile( <username>, <mail directory>, <file>, <index>, <flag> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<file> -- A temporary file which will be overwritten by the mail message.
<index> -- The message number to retrieve.
<flag> -- If set to "delete", the message is removed. This variable
          is optional. If not present, the message is not removed.

This function retrieves the message file indicated by the index value.
The message file is copied to the filename indicated by msg overwriting 
any previous contents.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"5 Error. Message not present."
"6 Error. Message not deleted."
"OK. Mail retrieved."

------------------------------------------------------------------------------

Function Name:  HRetrMail
Syntax:         HRetrMail( <username>, <mail directory>, <var>, <index>, <flag> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<var> -- A stem variable holding the message. One line per component.
<index> -- The message number to retrieve.
<flag> -- If set to "delete", the message is removed. This variable
          is optional. If not present, the message is not removed.

This function retrieves the message file indicated by the index value.
The message file is copied to the stem variable.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"5 Error. Message not present."
"6 Error. Message not deleted."
"7 Error. Stem variable not present."
"8 Error. Error storing stem variable."
"OK. Mail retrieved."

------------------------------------------------------------------------------

Function Name:  HRetrHead
Syntax:         HRetrHead( <username>, <mail directory>, <var>, <index> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<var> -- A stem variable holding the message. One line per component.
<index> -- The message number to retrieve.

This function retrieves the headers of the message file indicated by 
the index value. The headers are copied to stem variable.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"5 Error. Message not present."
"7 Error. Stem variable not present."
"8 Error. Error storing stem variable."
"OK. Headers retrieved."

------------------------------------------------------------------------------

Function Name:  HRetrSize
Syntax:         size = HRetrSize( <username>, <mail directory>, <index> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<index> -- The message number to query.
<size> -- The returned size of the message in bytes.

This function returns the size of the indicated message. A size of -1 
indicates the message did not exist.

Return Values:

The message size in bytes or -1 if no message was found.

------------------------------------------------------------------------------

About the Uidl Functions:

The Uidl functions return message information based on a unique
identifier for each message within a mailbox. This unique identifier
is not repeated, but guaranteed unique across time and messages of
a particular mailbox. You can use the Uidl to guarantee access to
a particular message. The Uidl value should be treated as an opaque
string value. Nothing should be inferred from it's character sequence
or numeric value.

------------------------------------------------------------------------------

Function Name:  HUidlMail
Syntax:         HUidlMail( <username>, <mail directory>, <var> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<var>  --  A stem variable to hold the UIDL of each message.

This function returns the UIDL of each message in a user's mailbox. The ".0"
component of the stem variable holds the number of messages.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"7 Error. Stem variable not present."
"8 Error. Error storing stem variable."
"OK. x messages."  (where x is the number of messages present.)

------------------------------------------------------------------------------

Function Name:  HUidlRetrMailFile
Syntax:         HUidlRetrMailFile( <username>, <mail directory>, <file>, <uidl>, <flag> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<file> -- A temporary file which will be overwritten by the mail message.
<uidl> -- The uidl number to retrieve.
<flag> -- If set to "delete", the message is removed. This variable
          is optional. If not present, the message is not removed.

This function retrieves the message file indicated by the uidl value.
The message file is copied to the filename indicated by msg overwriting 
any previous contents.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"5 Error. Message not present."
"6 Error. Message not deleted."
"OK. Mail retrieved."

------------------------------------------------------------------------------

Function Name:  HUidlRetrMail
Syntax:         HUidlRetrMail( <username>, <mail directory>, <var>, <uidl>, <flag> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<var> -- A stem variable holding the message. One line per component.
<uidl> -- The uidl number to retrieve.
<flag> -- If set to "delete", the message is removed. This variable
          is optional. If not present, the message is not removed.

This function retrieves the message file indicated by the uidl value.
The message file is copied to the stem variable.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"5 Error. Message not present."
"6 Error. Message not deleted."
"7 Error. Stem variable not present."
"8 Error. Error storing stem variable."
"OK. Mail retrieved."

------------------------------------------------------------------------------

Function Name:  HUidlRetrHead
Syntax:         HUidlRetrHead( <username>, <mail directory>, <var>, <uidl> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<var> -- A stem variable holding the message. One line per component.
<uidl> -- The uidl number to retrieve.

This function retrieves the headers of the message file indicated by 
the uidl value. The headers are copied to stem variable.

Return Values:

"1 Error. Wrong Number of Arguments."
"2 Error. Cannot open mailbox."
"4 Error. Error closing mailbox."
"5 Error. Message not present."
"7 Error. Stem variable not present."
"8 Error. Error storing stem variable."
"OK. Headers retrieved."

------------------------------------------------------------------------------

Function Name:  HUidlRetrSize
Syntax:         size = HUidlRetrSize( <username>, <mail directory>, <uidl> )

Description:

<username>  -- The username of the user.
<mail directory> -- The full pathname of the user's mail directory.
<uidl> -- The uidl number to query.
<size> -- The returned size of the message in bytes.

This function returns the size of the indicated message. A size of -1 
indicates the message did not exist.

Return Values:

The message size in bytes or -1 if no message was found.

------------------------------------------------------------------------------

Function Name:  HMailLoadFuncs
Syntax:         HMailLoadFuncs()

Description:

This functions loads all functions.

Return Values:

"1 Error. Wrong Number of Arguments."
"OK. Functions loaded."

------------------------------------------------------------------------------

Function Name:  HMailDropFuncs
Syntax:         HMailDropFuncs()

Description:

This functions unloads all functions.

Return Values:

"1 Error. Wrong Number of Arguments."
"OK. Functions dropped."

------------------------------------------------------------------------------

