![[OpenVMS documentation]](../../images/openvms_doc_banner_top.gif)
|
![[Site home]](../../images/buttons/bn_site_home_off.gif)
![[Send comments]](../../images/buttons/bn_comments_off.gif)
![[Help with this site]](../../images/buttons/bn_site_help_off.gif)
![[How to order documentation]](../../images/buttons/bn_order_docs_off.gif)
![[OpenVMS site]](../../images/buttons/bn_openvms_off.gif)
![[Compaq site]](../../images/buttons/bn_compaq_off.gif)
|
| Updated: 11 December 1998 |
|
|
|
|
| Updated: 11 December 1998 |
OpenVMS Utility Routines Manual
| Previous | Contents | Index |
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 |
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:
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.
13.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.
13.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.
13.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.
13.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.
13.8 Message Context
Message context processing involves manipulating existing messages as well as creating and deleting folders and mail files. Table 13-7 summarizes routines used in the message context.
| 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.
13.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.
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.
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.
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.
13.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.
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.
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.
13.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 |
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.
13.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.
13.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.
13.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.
13.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.
13.9 Send Context
Send context processing involves creating and sending new and existing messages. Table 13-8 summarizes 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 |
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.
You must terminate the send context explicitly using MAIL$SEND_END.
13.9.1 Sending New Messages
You can send new or existing messages to yourself and other users.
13.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:
Each field of the message header is a message attribute. You can specify one or more attributes for inclusion in the message header using MAIL$SEND_ADD_ATTRIBUTE. During successive calls to MAIL$SEND_ADD_ATTRIBUTE, an application specifies the specific message attribute to be constructed.
If you do not specify the From: or To: fields, the
Mail utility provides this information from the address list.
13.9.1.1.2 Constructing the Body of the Message
To construct a message, an application must specify a series of calls to MAIL$SEND_ADD_BODYPART to build a message from successive text records contained in a buffer or file.
If the body of the message is located in a file, you can build the
bodypart with one call to MAIL$SEND_ADD_BODYPART by specifying its file
name.
13.9.1.2 Creating an Address List
You must create an address list in order to send a message. The address list is a file or buffer of addressees to whom you want to send the message. Each entry in the address list is a valid user name on your system or on another system connected to your system by DECnet.
Adding User Names to the Address List
User names are added one at a time to the address list using one or more calls to MAIL$SEND_ADD_ADDRESS.
There are two types of user names---direct and
carbon copy addressees. Direct and carbon copy
addressees correspond to user names in the To: and
CC: fields of the message header.
13.9.2 Sending Existing Messages
Sending an existing message involves many tasks as well as initiating the mail file context and message context. The following table summarizes the tasks and routines involved in sending an existing message:
| Task | Routine |
|---|---|
| Open a mail file. | MAIL$MAILFILE_OPEN |
| Select the message. | MAIL$MESSAGE_SELECT |
| Retrieve the message. | MAIL$MESSAGE_GET |
|
Construct the message.
Construct the message header. Construct the message bodypart. |
MAIL$SEND_ADD_ATTRIBUTE MAIL$SEND_ADD_BODYPART |
| Create an address list. | MAIL$SEND_ADD_ADDRESS |
| Send the message. | MAIL$SEND_MESSAGE |
Once you have created an address list and constructed a message, you can send the message using MAIL$SEND_MESSAGE. Optional success and error action routines handle signaled success and error events in a synchronous manner.
For example, If DECnet returns messages indicating that it might not be
possible to complete a send operation to some users in your address
list, a user-specified send action routine might prompt the sender for
permission to continue the send operation.
13.9.3.1 Success Action Routines
A success action routine performs a task upon successful completion of
a send operation.
13.9.3.2 Error Handling Routines
An error action routine is a user-written error handler that signals
error conditions during a send operation.
13.9.3.3 Aborting a Send Operation
Under certain circumstances, you might want to terminate a send
operation in progress using MAIL$SEND_ABORT. In this instance, you can
use an asynchronous system trap (AST) routine that contains a call to
MAIL$SEND_ABORT to abort the send operation whenever the user presses
Ctrl/C.
13.10 User Profile Context
The user profile processing context functions as a system management tool for customizing the programming and interactive mail environments. It lets individual users modify their default processing characteristics.
The user profile database VMSMAIL_PROFILE.DATA contains information that application programs and the Mail utility use for processing in any context.
Table 13-9 summarizes the user context routines.
| Routine | Description |
|---|---|
| MAIL$USER_BEGIN | Initiates user profile context |
| MAIL$USER_DELETE_INFO | Deletes a user profile entry |
| MAIL$USER_END | Terminates user profile context |
| MAIL$USER_GET_INFO | Retrieves information about a user from the user profile |
| MAIL$USER_SET_INFO | Adds or modifies a user profile entry |
You can invoke the user context directly.
You must terminate the user context with MAIL$USER_END. Terminating the
user context deallocates virtual memory.
13.10.1 User Profile Entries
A user profile entry is a dynamic record. The Mail utility creates a user profile entry automatically for the calling process if it does not exist. The callable and user interfaces of the Mail utility use the data contained in the user profile entry. The user profile consists of fields as described in the sections that follow.
A MAIL subdirectory is the location---that is, the disk and directory specification---of your mail files. When you define a MAIL subdirectory, you are creating a subdirectory in which the specified mail file and associated external messages are to reside. For example:
$DISK5:[MAILUSER.COMMON.MAIL] |
The subdirectory [.common.mail] represents the MAIL subdirectory specification defined in the user profile entry. This subdirectory contains the mail file (for example, MAIL.MAI) and any external messages associated with the mail file. The disk and directory specification $DISK5:[MAILUSER] is defined in the user authorization file (UAF).
User profile flags can be set to enable or disable automatic purging of deleted mail, automatic self-copy when forwarding, replying, or sending messages, and use of the CC prompt.
The form field of the user profile entry defines the default print form to be used by print batch jobs. The string you specify as the default form must match a valid print form in use on your system.
A forwarding address lets you receive messages to your account on another system or to have your messages sent to another user either on your system or another system. You must specify valid node names and user names.
A personal name is a user-specified character string. For example, a personal name might include your entire name and phone number. Any phrase beginning with alphabetic characters up to a maximum of 127 alphanumeric characters is valid. However, consecutive embedded spaces should not be used.
The queue name field defines the default print queue on your system where your print jobs are sent.
| Previous | Next | Contents | Index |
|
|
![[OpenVMS documentation]](../../images/openvms_doc_banner_bottom.gif) |
|
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4493PRO_031.HTML
|