OpenVMS Utility Routines Manual
15.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.
15.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.
15.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.
15.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
|
15.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.
15.9.3.1 Success Action Routines
A success action routine performs a task upon successful completion of
a send operation.
15.9.3.2 Error Handling Routines
An error action routine is a user-written error handler that signals
error conditions during a send operation.
15.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.
15.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 15-9 summarizes the user context routines.
Table 15-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.
15.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.
15.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.
15.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
|
15.11 Input Item Codes
Input item codes direct the called routine to read data from a buffer
or file and perform a task. Table 15-10 summarizes input item codes.
Table 15-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.
|
15.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 15-11 summarizes output item codes.
Table 15-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.
|
|
