HP OpenVMS Utility Routines Manual


Previous Contents Index

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

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

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

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

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

16.9.3.1 Success Action Routines

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

16.9.3.2 Error Handling Routines

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

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

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

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

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

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

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

16.11 Input Item Codes

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

Table 16-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.
MAIL$_SEND_RECIP_FOLDER Specifies the descriptor of a recipients folder name.
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.

16.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 16-11 summarizes output item codes.

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