Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Utility Routines Manual
Previous Contents Index

Chapter 13
Mail Utility (MAIL) Routines

The callable interface of the Mail utility (MAIL) lets you send messages to users on your system or on any other computer connected to your system with DECnet. This chapter describes how application programs using callable MAIL routines can perform the following functions:

For information about the DCL interface to the Mail utility, see the OpenVMS User's Manual.

13.1 Messages

Messages are files that contain information you want to send to other users. Messages having one or two blocks are part of a mail file, while messages having more than two blocks are external sequential files.

External files reside in the same directory as the mail file that points to them.

Structure of a Message

A message consists of header information and the bodypart. The message bodypart consists of text records that contain information you want to send to another user.

Figure 13-1 illustrates the format of a mail message.

Figure 13-1 Standard Message Format 


From:   MYNODE::USER  "The Celestial Navigator"    (1) 
To:     NODE::J_DOE         (2)
CC:     USER                (3)
Subj:   Perseids ...        (4)
 
Get ready. Tuesday of this week (August 12th), one    (5)
of the most abundant meteor showers of the year will occur.  
The Perseids, also known as the St. Laurence's Tears, stream 
across earth's orbit at 319.3 degrees. Radiant 3h4m +58 degrees. 
Fine for photography with an average magnitude of 2.27. 
There will be some fireballs, fainter white or yellow 
meteors, and brighter  green or orange or red ones. About one 
third of the meteors, including all the  brightest, leave 
yellowish trains, which may be spectacular, up to 2 
degrees wide and lasting up to 100 seconds. Brighter 
meteors often end in flares or bursts.            (6)

The parts of a message are as follows:

External Message Identification Number

In addition, the file name of an external message uses the following format: 


MAIL$nnnnnnnnnnnnnnnn.MAI

where n...n is the external message identification number.

13.2 Folders

The Mail utility organizes messages by date and time received and, secondarily, by folder name. All messages are associated with a folder name---either default folders or user-specified folders. The Mail utility associates mail messages with one of three default mail folder names. Table 13-1 describes the three default mail folders.

Table 13-1 Default Mail Folders
Folder Contents
NEWMAIL Newly received, unread messages
MAIL Messages that have been read and not deleted
WASTEBASKET Messages designated for deletion

You can also place messages in any user-defined mail folder and file.

13.3 Mail Files

A mail file is an indexed file that contains the following types of data:

In addition, you can select messages from mail files as well as copy or move messages to or from mail files.

Mail File Format

The indexed mail file format offers two advantages: use of folders and faster access time than sequential access. Indexed mail files use two keys to locate messages---a primary key denoting the date and time received and a secondary key using the folder name.

13.4 User Profile Database

The Mail utility maintains an indexed data file VMSMAIL_PROFILE.DATA that serves as a systemwide database of user profile entries. A user profile entry is a record that contains data describing a Mail user's default processing characteristics and whose primary key is the user name. Table 13-2 summarizes information contained in a user profile entry.

Table 13-2 User Profile Information
Field Function
Directory Default MAIL subdirectory
Form Default print form
Forwarding address Forwarding address
Personal name string User-specified character string included in the message header
Queue name Default print queue name
Flags
Automatic purge
CC: prompt
Copy self forward
Copy self reply
Copy self send
Purging of the wastebasket folder on exiting
Carbon copy prompt
Copy to self when forwarding a message
Copy to self when replying to a message
Copy to self when sending a message
Signature file Text file that is automatically appended to the end of the body of a mail message

Both the callable interface and the user interface access the user profile database to determine default processing characteristics.

13.5 Mail Utility Processing Contexts

The Mail utility defines four discrete levels of processing, or contexts for manipulating mail files, messages, folders, and the user profile database as shown in Table 13-3.

Table 13-3 Levels of Mail Utility Processing
Context Entity
Mail file Mail files and folders
Message Mail files, folders, and messages
Send Messages
User User profile database

Within each context, your application processes specific entities in certain ways using callable MAIL routines as described in the sections that follow.

Initiating a MAIL Context

You must explicitly begin and end each MAIL context. Each group of routines contains a pair of context-initiating and terminating routines.

When you begin processing in any context, the Mail utility performs the following functions:

  1. Allocates sufficient virtual memory to manage context information
  2. Initializes context variables and internal structures

Terminating a MAIL Context

Terminating a MAIL processing context deallocates virtual memory. You must explicitly terminate processing in any context by calling a context-terminating routine.

13.5.1 Callable Mail Utility Routines

There are four types of callable Mail utility routines, each corresponding to the context within which they execute. A prefix identifies each functional group:

Table 13-4 lists Mail utility routines according to context.

Table 13-4 Callable Mail Utility Routines
Context Routine
Mail file MAIL$MAILFILE_BEGIN
MAIL$MAILFILE_CLOSE
MAIL$MAILFILE_COMPRESS
MAIL$MAILFILE_END
MAIL$MAILFILE_INFO_FILE
MAIL$MAILFILE_MODIFY
MAIL$MAILFILE_OPEN
MAIL$MAILFILE_PURGE_WASTE
Message MAIL$MESSAGE_BEGIN
MAIL$MESSAGE_COPY
MAIL$MESSAGE_DELETE
MAIL$MESSAGE_END
MAIL$MESSAGE_GET
MAIL$MESSAGE_INFO
MAIL$MESSAGE_MODIFY
MAIL$MESSAGE_SELECT
Send MAIL$SEND_ABORT
MAIL$SEND_ADD_ADDRESS
MAIL$SEND_ADD_ATTRIBUTE
MAIL$SEND_ADD_BODYPART
MAIL$SEND_BEGIN
MAIL$SEND_END
MAIL$SEND_MESSAGE
User MAIL$USER_BEGIN
MAIL$USER_DELETE_INFO
MAIL$USER_END
MAIL$USER_GET_INFO
MAIL$USER_SET_INFO

13.5.2 Single and Multiple Threads

Once you have successfully initiated MAIL processing in a context, you have created a thread. A thread is a series of calls to MAIL routines that uses the same context information. Applications can contain one or more threads.

Single Threads

For example, consider an application that begins mail file processing; opens, compresses, and closes a mail file; and ends mail file context processing. This application executes a single thread of procedures that reference the same context variable names and pass the same context information.

Multiple Threads

You can create up to 31 concurrent threads. Applications that contain more than one thread must maintain unique context variables for each thread in order to pass thread-specific context information.

The Mail utility returns the condition value MAIL$_NOMORECTX when your process attempts to exceed the maximum number of allowable threads.

13.6 Programming Considerations

The calling sequence for all MAIL routines consists of a status variable, an entry point name, and an argument list. All arguments within the argument list are required. All callable MAIL routines use the same arguments in their calling sequences as described in the following example: 


STATUS=MAIL$MAILFILE_BEGIN(CONTEXT, IN_ITEM_LIST, OUT_ITEM_LIST)

The variable status receives the condition value, and the argument context receives the context information. The arguments in_item_list and out_item_list are input and output item lists that contain one or more input or output item descriptors.

13.6.1 Condition Handling

At run time, a hardware- or software-related event can occur that determines whether or not the application executes successfully. The Mail utility processes such an event, or condition in the following ways:

You can establish your own condition handler or allow the program to signal the default condition handler.

Returning Condition Values

You can disable signaling for any call by specifying the item code MAIL$_NOSIGNAL as an item in the input item list.

13.6.2 Item Lists and Item Descriptors

Your application passes data to callable MAIL routines and receives data from routines through data structures called item lists defined in your program.

13.6.2.1 Structure of an Item Descriptor

An input or output item list is a data structure that consists of one or more input or output item descriptors.

The following table summarizes the characteristics of item lists:
Item Descriptor Characteristics
Input Each descriptor points to a buffer or file from which Mail reads data.
Output Each descriptor points to a buffer or file to which Mail writes data.

An item descriptor is a data structure consisting of three longwords as described in Figure 13-2.

Figure 13-2 Item Descriptor

Item descriptor fields are described as follows:
Field Function
Item code Specifies an action the routine is to perform.
Buffer length Specifies the length in bytes of an input or output buffer.
Buffer address Specifies the address of the input or output buffer.
Return length address Depends on the type of item code specified:
Item Code Use
Input Not used; specify 0.
Output Address of a longword that receives the length of the result.

Note
You can specify item descriptors in any order within an item list.

Item Codes

The item code defines an action that the routine is to perform. Input and output item codes are specified in input and output item descriptors, respectively.

Boolean input and output item codes request an operation but do not pass data to the called routine. For example, the item code MAIL$_USER_SET_CC_PROMPT sets the CC prompt flag enabling use of CC: field text.

For a complete list of input and output item codes, see Tables 13-10 and 13-11.

13.6.2.2 Null Item Lists

Both the input and output item list arguments in the MAIL routine calling sequence are required. However, there might be situations when you do not want to request an operation or no input or output item codes are listed for the routine. In such cases, you must pass the value 0 in the function call.

13.6.2.3 Declaring Item Lists and Item Descriptors

Depending on the programming language you are using, refer to the appropriate language reference manual for more information about declaring data structures and creating variables.

13.6.2.4 Terminating an Item List

Terminate an item list with a null item descriptor. Assign the value 0 to each field in the item descriptor.

13.6.3 Action Routines

Certain callable MAIL routines allow you to specify an action routine. An action routine transfers control to a user-written subroutine that performs specific tasks.

The mail file, message, and send contexts permit the use of action routines for specific reasons. Table 13-5 summarizes the types of action routines and the contexts in which they are used.

Table 13-5 Types of Action Routines
Context Routine Action Routine
Mail file MAIL$MAILFILE_INFO_FILE Provides information about folder and mail files.
Message MAIL$MESSAGE_COPY Copies messages between files and folders.
Send MAIL$SEND_MESSAGE Success and error results; sends a text file to an existing address list.

The preceding table summarizes typical uses of action routines. However, an action routine can perform any task you specify. See the Guide to Creating OpenVMS Modular Procedures for more information about action routines.

Mail File and Folder Action Routine Calling Sequence

The main portion of the application calls the action routine and passes values to it using parameters. The calling sequence of a mail file or folder action routine is as follows: 

entry-point-name(userdata,foldername)

The argument userdata is the address of a required longword that contains user-specified data, and the argument foldername is the address of a descriptor of the foldername.

Send Action Routine Calling Sequence

The calling sequence of a send action routine is as follows: 

entry-point-name(username,signal-array,userdata)

The argument username is the address of a descriptor of the user name to which the application successfully sent a message; signal-array is the address of a signal array containing the success message; userdata is the address of an optional longword that contains user-specified data.

13.7 Managing Mail Files

Using mail files involves opening and closing both default mail files and user-created mail files, displaying folder names, and purging and compressing mail files. Table 13-6 summarizes each mail file routine and its function.

Table 13-6 Mail File Routines
Routine Description
MAIL$MAILFILE_BEGIN Initiates mail file processing
MAIL$MAILFILE_CLOSE Closes a mail file
MAIL$MAILFILE_COMPRESS Compresses a mail file
MAIL$MAILFILE_END Terminates mail file processing
MAIL$MAILFILE_INFO_FILE Obtains information about the mail file
MAIL$MAILFILE_MODIFY Changes the wastebasket folder name and the default mail file name
MAIL$MAILFILE_OPEN Opens a mail file
MAIL$MAILFILE_PURGE_WASTE Purges a mail file

Mail file context processing involves accessing and manipulating one or more mail files.

Initiating the Mail File Context

Your application must call MAIL$MAILFILE_BEGIN to perform mail file context processing.

When you call MAIL$MAILFILE_BEGIN successfully and begin processing in the mail file context, you have created a thread. You must specify the same context variable name in routine calls within the same thread.

Terminating the Mail File Context

Terminate processing in the mail file context calling MAIL routines in the following order:

  1. Terminate message context processing (if applicable) using MAIL$MESSAGE_END.
  2. Close the currently open mail file using MAIL$MAILFILE_CLOSE.
  3. Terminate mail file context processing using MAIL$MAILFILE_END.
The following sections describe these actions in more detail.

13.7.1 Opening and Closing Mail Files

Before you perform any activities on existing messages, folders, and mail files, you must first open a mail file. Whenever you open a mail file, you must do so explicitly using MAIL$MAILFILE_OPEN. You can open only one mail file per mail file thread.

Note that each routine references the same context variable. An open mail file must be explicitly closed with a call to MAIL$MAILFILE_CLOSE.

Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4493PRO_030.HTML