Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

##### 14.9.1.1.1 Constructing the Message Header

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.

##### 14.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.

#### 14.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.

User Name Types

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.

### 14.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

### 14.9.3 Send Action Routines

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.

#### 14.9.3.1 Success Action Routines

A success action routine performs a task upon successful completion of a send operation.

#### 14.9.3.2 Error Handling Routines

An error action routine is a user-written error handler that signals error conditions during a send operation.

#### 14.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.

## 14.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 14-9 summarizes the user context routines.

Table 14-9 User Profile 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

Initiating the User Context

You can invoke the user context directly.

Terminating the User Context

You must terminate the user context with MAIL$USER_END. Terminating the user context deallocates virtual memory.

### 14.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.

MAIL Subdirectory

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

Flags

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.

Form

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.

Forwarding Address

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.

Personal Name

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.

Queue Name

The queue name field defines the default print queue on your system where your print jobs are sent.

#### 14.10.1.1 Adding Entries to the User Profile Database

Ordinarily, the Mail utility creates a user profile entry for the calling process if one does not already exist. A system management application might create entries for other users. When you specify the item code MAIL$_USER_CREATE_IF using MAIL$USER_SET_INFO, the Mail utility creates a user profile entry if it does not already exist.

#### 14.10.1.2 Modifying or Deleting User Profile Entries

The calling process can modify, delete, or retrieve its own user profile entry without privileges.

The following table summarizes the privileges required to modify or delete user profile entries that do not belong to the calling process:

Procedure | Privilege | Function
--- | --- | ---
MAIL$USER_SET_INFO | SYSPRV | Modifies another user's profile entry
MAIL$USER_GET_INFO | SYSNAM or SYSPRV | Retrieves information about another user

## 14.11 Input Item Codes

Input item codes direct the called routine to read data from a buffer or file and perform a task. Table 14-10 summarizes input item codes.

Table 14-10 Input Item Codes
Item Code | Function
--- | ---
Mail File Context
MAIL$_MAILFILE_DEFAULT_NAME | Specifies the location (disk and directory) of the default mail file MAIL.MAI.
MAIL$_MAILFILE_FOLDER_ROUTINE | Displays folder names within a specified mail file.
MAIL$_MAILFILE_FULL_CLOSE | Requests that the wastebasket folder be purged and that a convert/reclaim operation be performed, if necessary.
MAIL$_MAILFILE_NAME | Specifies the name of a mail file to be opened.
MAIL$_MAILFILE_RECLAIM | Overrides the deleted bytes threshold and requests a reclaim operation.
MAIL$_MAILFILE_USER_DATA | Passes a longword of user context data to an action routine.
MAIL$_MAILFILE_WASTEBASKET_NAME | Specifies a new name for the wastebasket in a specified mail file.
Message Context
MAIL$_MESSAGE_AUTO_NEWMAIL | Places newly read messages in the Mail folder automatically.
MAIL$_MESSAGE_BACK | Returns the first record of the preceding message.
MAIL$_MESSAGE_BEFORE | Selects a message before a specified date.
MAIL$_MESSAGE_CC_SUBSTRING | Specifies a character string that must match a node or user name substring in the CC: field of the specified message.
MAIL$_MESSAGE_CONTINUE | Returns the next text record of the current message.
MAIL$_MESSAGE_DEFAULT_NAME | Specifies the default mail file specification.
MAIL$_MESSAGE_DELETE | Deletes a message in the current folder after the message has been copied to a new folder.
MAIL$_MESSAGE_FILE_ACTION | Specifies a user-written routine that is called if a mail file is to be created.
MAIL$_MESSAGE_FILE_CTX | Specifies mail file context received from MAIL$MAILFILE_BEGIN.
MAIL$_MESSAGE_FILENAME | Specifies the name of a mail file to which the message is to be moved.
MAIL$_MESSAGE_FOLDER_ACTION | Specifies a user-written routine that is called if a folder is to be created.
MAIL$_MESSAGE_FLAGS | Specifies MAIL system flags to use when selecting messages.
MAIL$_MESSAGE_FLAGS_MBZ | Specifies MAIL system flags that must be zero.
MAIL$_MESSAGE_FOLDER | Specifies the name of the target folder for moving messages.
MAIL$_MESSAGE_FROM_SUBSTRING | Specifies a character string that must match a node or user name substring in the From: field of the specified message.
MAIL$_MESSAGE_ID | Specifies the message identification number of the message on which an operation is to be performed.
MAIL$_MESSAGE_NEXT | Returns the first record of the message following the current message.
MAIL$_MESSAGE_SINCE | Selects a message received on or after a specified date.
MAIL$_MESSAGE_SUBJ_SUBSTRING | Specifies a character string that must match a node or user name substring in the Subject: field of the specified message.
MAIL$_MESSAGE_TO_SUBSTRING | Specifies a character string that must match a substring in the To: field of the specified message.
MAIL$_MESSAGE_USER_DATA | Specifies a longword to be passed to the folder and mail file action routines.
Send Context
MAIL$_SEND_CC_LINE | Specifies the CC: field text.
MAIL$_SEND_DEFAULT_NAME | Specifies the default file specification of a text file to be opened.
MAIL$_SEND_ERROR_ENTRY | Specifies a user-written routine to process errors that occur during a send operation.
MAIL$_SEND_FID | Specifies the file identifier.
MAIL$_SEND_FILENAME | Specifies the input file specification of a text file to be opened.
MAIL$_SEND_FROM_LINE | Specifies the From: field text.
MAIL$_SEND_PERS_NAME MAIL$_SEND_NO_PERS_NAME | Specifies the personal name string. Specifies that no personal string be used.
MAIL$_SEND_RECORD | Specifies the descriptor of a text record to be added to the body of a message.
MAIL$_SEND_SIGFILE | Specifies a full OpenVMS file specification of the signature file to be used in the message.
MAIL$_SEND_NO_SIGFILE | Specifies that no signature file be used.
MAIL$_SEND_SUBJECT | Specifies the Subject: field text.
MAIL$_SEND_SUCCESS_ENTRY | Specifies a user-written routine to process successfully completed events during a send operation.
MAIL$_SEND_TO_LINE | Specifies the To: field text.
MAIL$_SEND_USER_DATA | Specifies a longword passed to the send action routines.
MAIL$_SEND_USERNAME | Adds a specified user name to the address list.
MAIL$_SEND_USERNAME_TYPE | Specifies the type of user name added to the address list.
User Context
MAIL$_USER_CREATE_IF | Creates a user profile entry.
MAIL$_USER_FIRST | Returns information about the first user in the user profile database.
MAIL$_USER_NEXT | Returns information about the next user in the user profile database.
MAIL$_USER_SET_AUTO_PURGE MAIL$_USER_SET_NO_AUTO_PURGE | Sets the automatic purge flag. Clears the automatic purge flag.
MAIL$_USER_SET_CC_PROMPT MAIL$_USER_SET_NO_CC_PROMPT | Sets the CC prompt flag. Clears the CC prompt flag.
MAIL$_USER_SET_COPY_FORWARD MAIL$_USER_SET_NO_COPY_FORWARD | Sets the copy self forward flag. Clears the copy self forward flag.
MAIL$_USER_SET_COPY_REPLY MAIL$_USER_SET_NO_COPY_REPLY | Sets the copy self reply flag. Clears the copy self reply flag.
MAIL$_USER_SET_COPY_SEND MAIL$_USER_SET_NO_COPY_SEND | Sets the copy self send flag. Clears the copy self send flag.
MAIL$_USER_SET_EDITOR MAIL$_USER_SET_NO_EDITOR | Specifies the default editor. Clears the default editor field.
MAIL$_USER_SET_FORM MAIL$_USER_SET_NO_FORM | Specifies the default print form string. Clears the default print form field.
MAIL$_USER_SET_FORWARDING MAIL$_USER_SET_NO_FORWARDING | Specifies the forwarding address string. Clears the forwarding address field.
MAIL$_USER_SET_NEW_MESSAGES | Specifies the new messages count.
MAIL$_USER_SET_PERSONAL_NAME MAIL$_USER_SET_NO_PERSONAL_NAME | Specifies the personal name string. Clears the personal name field.
MAIL$_USER_SET_QUEUE MAIL$_USER_SET_NO_QUEUE | Specifies the default print queue name string. Clears the default print queue name field.
MAIL$_USER_SET_SIGFILE | Specifies a signature file specification for the specified user.
MAIL$_USER_SET_NO_SIGFILE | Clears a signature file field for the specified user.
MAIL$_USER_SET_SUB_DIRECTORY MAIL$_USER_SET_NO_SUB_DIRECTORY | Specifies a MAIL subdirectory. Clears the MAIL subdirectory field.
MAIL$_USER_USERNAME | Points to the user name string to specify the user profile entry to be modified.

## 14.12 Output Item Codes

Output item codes direct the called routine to return data to a buffer or file which is then available for use by the application. Table 14-11 summarizes output item codes.

Table 14-11 Output Item Codes
Item Code | Function
--- | ---
Mail File Context
MAIL$_MAILFILE_INDEXED | Determines whether the mail file format is indexed.
MAIL$_MAILFILE_DIRECTORY | Returns the mail file subdirectory specification to the caller.
MAIL$_MAILFILE_RESULTSPEC | Returns the result mail file specification.
MAIL$_MAILFILE_WASTEBASKET | Returns the wastebasket folder name for the specified file.
MAIL$_MAILFILE_DELETED_BYTES | Returns the number of deleted bytes in a specified mail file.
MAIL$_MAILFILE_MESSAGES_DELETED | Returns the number of deleted messages.
MAIL$_MAILFILE_DATA_RECLAIM | Returns the number of data buckets reclaimed.
MAIL$_MAILFILE_DATA_SCAN | Returns the number of data buckets scanned.
MAIL$_MAILFILE_INDEX_RECLAIM | Returns the number of index buckets reclaimed.
MAIL$_MAILFILE_TOTAL_RECLAIM | Returns the total number of bytes reclaimed.
Message Context
MAIL$_MESSAGE_BINARY_DATE | Returns the date and time received as a binary value.
MAIL$_MESSAGE_CC | Returns the text in the CC: field of the current message.
MAIL$_MESSAGE_CURRENT_ID | Returns the message identification number of the current message.
MAIL$_MESSAGE_DATE | Returns the message creation date string.
MAIL$_MESSAGE_EXTID | Returns the external message identification number of the current message.
MAIL$_MESSAGE_FILE_CREATED | Returns the value of the mail file created flag.
MAIL$_MESSAGE_FOLDER_CREATED | Returns the value of the folder created flag.
MAIL$_MESSAGE_FROM | Returns the text in the From: field of the current messsage.
MAIL$_MESSAGE_RECORD | Returns a record from the current message.
MAIL$_MESSAGE_RECORD_TYPE | Returns the record type.
MAIL$_MESSAGE_REPLY_PATH | Returns the reply path.
MAIL$_MESSAGE_RESULTSPEC | Returns the resultant mail file specification.
MAIL$_MESSAGE_RETURN_FLAGS | Returns the MAIL system flag value of the current message.
MAIL$_MESSAGE_SELECTED | Returns the number of selected messages.
MAIL$_MESSAGE_SENDER | Returns the name of the sender of the current message.
MAIL$_MESSAGE_SIZE | Returns the size in records of the current message.
MAIL$_MESSAGE_SUBJECT | Returns the text in the Subject: field of the specified message.
MAIL$_MESSAGE_TO | Returns the text in the To: field of the specified message.
Send Context
MAIL$_SEND_COPY_FORWARD | Returns the value of the caller's copy forward flag.
MAIL$_SEND_COPY_REPLY | Returns the value of the caller's copy reply flag.
MAIL$_SEND_COPY_SEND | Returns the value of the caller's copy send flag.
MAIL$_SEND_RESULTSPEC | Returns the resultant file specification of the file to be sent.
MAIL$_SEND_USER | Returns the process owner's user name.
User Context
MAIL$_USER_AUTO_PURGE | Returns the value of the automatic purge mail flag.
MAIL$_USER_CAPTIVE | Returns the value of the UAF captive flag.
MAIL$_USER_CC_PROMPT | Returns the value of the CC prompt flag.
MAIL$_USER_COPY_FORWARD | Returns the value of the copy self forward flag.
MAIL$_USER_COPY_REPLY | Returns the value of the copy self reply flag.
MAIL$_USER_COPY_SEND | Returns the value of the copy self send flag.
MAIL$_USER_EDITOR | Returns the name of the default editor.
MAIL$_USER_FORM | Returns the default print form string.
MAIL$_USER_FORWARDING | Returns the forwarding address string.
MAIL$_USER_FULL_DIRECTORY | Returns the complete directory path of the mail file subdirectory.
MAIL$_USER_NEW_MESSAGES | Returns the new message count.
MAIL$_USER_PERSONAL_NAME | Returns the personal name string.
MAIL$_USER_QUEUE | Returns the default queue name string.
MAIL$_USER_RETURN_USERNAME | Returns the user name string.
MAIL$_USER_SIGFILE | Returns the default signature file specification.
MAIL$_USER_SUB_DIRECTORY | Returns the subdirectory specification.

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_037.HTML