HP OpenVMS Utility Routines Manual


Previous Contents Index

16.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.

16.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.

16.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.

16.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 16-5 summarizes the types of action routines and the contexts in which they are used.

Table 16-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.

16.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 16-6 summarizes each mail file routine and its function.

Table 16-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.

16.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.

16.7.1.1 Using the Default Specification for Mail Files

To open a mail file, Mail must first locate it using either a default or a user-specified mail file specification. A mail file specification consists of the following components: disk and directory, file name, and file type.

If you use the default file specification, the Mail utility locates and opens the default mail file using the following information:
Component Source
User's disk and directory Retrieved from the user authorization file (UAF)
MAIL subdirectory Retrieved from the user profile entry
Mail file name and type MAIL.MAI

16.7.1.2 Specifying an Alternate Mail File Specification

You can use the default specification for mail files or specify all or part of an alternate mail file specification.

When to Specify an Alternate Mail File Specification

The following mail file routines accept alternate mail file specifications when you use the item codes MAIL$_MAILFILE_DEFAULT_NAME or MAIL$_MAILFILE_NAME or both:

How the Mail Utility Creates an Alternate Mail File Specification

The Mail utility constructs an alternate mail file specification by using program-supplied mail file specifications to modify the default specification for mail files in the following order of importance:

  1. Program-supplied file specification (MAIL$_MAILFILE_NAME)
  2. Program-supplied default file specification (MAIL$_MAILFILE_DEFAULT_NAME)
  3. Default specification

If you are using MAIL$_MAILFILE_DEFAULT_NAME and you specify 0 as the buffer size and address, the Mail utility uses the current device and directory.

The default specification for mail files applies unless overridden by your program-supplied mail file specifications. Mail file specifications defined with MAIL$_MAILFILE_NAME override those defined with MAIL$_MAILFILE_DEFAULT_NAME.

For example, an application can override the default specification $DISK0:[USER]MAIL.MAIL by defining an alternate device type $DISK99: using MAIL$_MAILFILE_NAME. The result is $DISK99:[USER]MAIL.MAI. The application can further modify the specification by defining a different mail file MYMAILFILE.MAI using MAIL$_MAILFILE_DEFAULT_NAME. The new mail file specification is $DISK99:[USER]MYMAILFILE.MAI.

16.7.2 Displaying Folder Names

As the size of your mail files increases with messages and folders, you might want to display your folder names. A user-written folder action routine lets you do this.

In the mail file context, MAIL$MAILFILE_INFO_FILE can be used to invoke a folder action routine that displays folder names in a mail file. If you specify the item code MAIL$_MAILFILE_FOLDER_ROUTINE, MAIL$MAILFILE_INFO passes a descriptor of a folder name to the action routine repeatedly until it encounters no more folder names and passes a null descriptor.

16.7.3 Purging Mail Files Using the Wastebasket Folder

The Mail utility associates messages designated for deletion with a wastebasket folder. Purging mail files of messages in the wastebasket folder that are designated for deletion is one way to conserve disk space. You can also use the Mail utility to conserve disk space by reclaiming disk space and compressing mail files, as described in the sections that follow.

Note that purging the wastebasket folder removes the messages from the wastebasket folder but might not reclaim disk space.

16.7.3.1 Reclaiming Disk Space

Simply deleting the messages does not mean you will automatically reclaim the disk space. The Mail utility uses a system-defined threshold of bytes designated for deletion to determine when to reclaim disk space. When the total number of total bytes designated for deletion exceeds the threshold, the Mail utility performs a reclaim operation.

You can override the deleted bytes threshold and request a reclaim operation using MAIL$MAILFILE_PURGE_WASTE with the input item code MAIL$_MAILFILE_RECLAIM.

16.7.3.2 Compressing Mail Files

Compressing mail files is a way of conserving disk space. Mail file compression provides faster access to the folders and messages within the mail file. When you call MAIL$MAILFILE_COMPRESS, Mail removes unused space within the specified mail file.

16.8 Message Context

Message context processing involves manipulating existing messages as well as creating and deleting folders and mail files. Table 16-7 summarizes routines used in the message context.

Table 16-7 Message Routines
Routine Description
MAIL$MESSAGE_BEGIN Initiates message processing
MAIL$MESSAGE_COPY Copies messages
MAIL$MESSAGE_DELETE Deletes messages
MAIL$MESSAGE_END Terminates message processing
MAIL$MESSAGE_GET Retrieves a message
MAIL$MESSAGE_INFO Obtains information about a specified message
MAIL$MESSAGE_MODIFY Identifies a message as replied, new, or marked
MAIL$MESSAGE_SELECT Selects a message or messages from the currently open mail file

Initiating the Message Context

Message context processing can begin only after a mail file has been opened. Your application must explicitly call MAIL$MESSAGE_BEGIN in order to execute message context processing.

The Mail utility passes mail file context information to the message context when you call MAIL$MESSAGE_BEGIN with the input item code MAIL$_MESSAGE_FILE_CTX.

Terminating the Message Context

To terminate message-level processing for a specific thread, you must call MAIL$MESSAGE_END to deallocate memory.

16.8.1 Selecting Messages

Applications select messages using MAIL$MESSAGE_SELECT to copy and move messages between folders as well as to read, modify, or delete messages. You must select messages before you can use them. You must specify a folder name when you select messages.

You can select messages based on the following criteria: matching character strings, message arrival date and time, and message characteristics.

Matching Character Strings

You can select a message or set of messages from a mail file by specifying one or more character substrings that you want to match with a character substring in the header information of a message or group of messages. You must specify the specific bodypart in the message header where the substring is located.

The Mail utility searches the specified folder for message headers that contain the matching character substring. This method of selection is useful when you want to select and use messages from or to a particular user that are associated with many folder names.

When you specify more than one character substring, the Mail utility performs a logical AND operation to find the messages that contain the correct substring.

Message Arrival Date and Time

You can also select a message or group of messages based on their arrival time, that is, when you received them. Applications select messages according to two criteria as follows:

The Mail utility searches the mail file and selects messages whose primary key (date and time) matches the date and time specified in your application.

Message Characteristics

You can select messages based on Mail system flag values that indicate the following message characteristics:

For example, you can select unread messages in order to display them or to display a message you have marked.

16.8.2 Reading and Printing Messages

After a message is selected, an application iteratively retrieves the contents of the bodypart record by record. The message can be retrieved using MAIL$MESSAGE_GET and can then be stored in a buffer or file.

Displaying a Message

To display a message on the terminal screen, you should store the message in a buffer and use the host programming language command that directs data to the screen.

Printing a Message

To print a message on a print queue on your system, you should write the message to an external file and use the $SNDJBC system service to manage print jobs and define queue characteristics.

16.8.3 Modifying Messages

Message modification using MAIL$MESSAGE_MODIFY involves setting flags that identify a message or group of messages as having certain characteristics. The following table summarizes bit offsets that modify flag settings:
Symbol Meaning
MAIL$V_replied Flagged as answered
MAIL$V_marked Flagged for display purposes

16.8.4 Copying and Moving Messages

You can copy messages between folders within a mail file or between folders in different mail files using MAIL$MESSAGE_COPY. The Mail utility copies the message from the source folder to the destination folder leaving the original message intact.

Similarly, you can move messages between folders within a mail file or between folders in different mail files using MAIL$MESSAGE_COPY with the item code MAIL$_MESSAGE_DELETE. The Mail utility moves a message by copying the message from the source folder to the destination folder. You must specify a folder name.

When you move a message to another folder within the same mail file, you are changing the message's secondary key---its folder name.

16.8.4.1 Creating Folders

You can create a folder in a specified mail file whenever you attempt to copy or move a message to a nonexistent folder. When you create a folder, you are assigning a previously nonexistent folder name to a message as its secondary key.

Your application can include a user-written folder action routine that notifies you that the folder does not exist and accepts input to create the folder.

16.8.4.2 Deleting Folders

You can delete a folder by moving all of the messages within the source folder to another folder in the same mail file or to a folder in another mail file. In this case, the Mail utility associates messages that are moved with a new folder name.

You can also delete a folder by deleting all of the messages in a folder. The Mail utility associates messages designated for deletion with the wastebasket folder name.

In either case, the original folder name---the secondary key---no longer exists.

16.8.4.3 Creating Mail Files

Similarly, you can create a mail file whenever you attempt to copy or move a message to a nonexistent mail file.

Your application can include a user-written mail file action routine that notifies you that the mail file does not exist and accepts input to create the mail file.

Mail file creation involves creating the mail file and then copying or moving the message to the new mail file. If the message is shorter than 3 blocks, the Mail utility stores the message in the mail file. Otherwise, the Mail utility places a pointer to the message in the newly created mail file.

16.8.5 Deleting Messages

To delete a message, you need to know its message identification number. Applications can retrieve the message identification number by specifying the item code MAIL$_MESSAGE_ID when selecting a message or group of messages with MAIL$MESSAGE_SELECT.

When you delete all messages with the same secondary key (folder name) using MAIL$MESSAGE_DELETE and specifying the item code MAIL$_MESSAGE_ID, you have deleted the folder.

16.9 Send Context

Send context processing involves creating and sending new and existing messages. Table 16-8 summarizes send routines.

Table 16-8 Send Routines
Routine Description
MAIL$SEND_ABORT Aborts a send operation
MAIL$SEND_ADD_ADDRESS Adds an addressee to the address list
MAIL$SEND_ADD_ATTRIBUTE Constructs the message header
MAIL$SEND_ADD_BODYPART Constructs the body of the message
MAIL$SEND_BEGIN Initiates send processing
MAIL$SEND_END Terminates send processing
MAIL$SEND_MESSAGE Sends a message

Initiating the Send Context

You can invoke the send context directly if you are creating a new message. Otherwise, to access an existing message, you must open the mail file that contains the message, select the message, and retrieve it.

Terminating the Send Context

You must terminate the send context explicitly using MAIL$SEND_END.

16.9.1 Sending New Messages

You can send new or existing messages to yourself and other users.

16.9.1.1 Creating a Message

You create new messages using send context routines. If you want to create and send a new message, you do not need to initiate any other context. As mentioned earlier, a message consists of two parts---the message header and the message bodypart.

Constructing a message involves building each part of the message separately using the following routines:


Previous Next Contents Index