| Previous | Contents | Index |
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.
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 |
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.
| 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.
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.
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.
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 |
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.
| 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. |
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.
| 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 |