HP OpenVMS Systems Documentation
OpenVMS Utility Routines Manual
The LGI$ICB_PWDEXPIRED callback routine checks for password expiration.
Use this callback routine to determine whether the account password has expired. If the password is expired, the callback routine:
Condition Values Returned
The LGI$ICB_USERPARSE callback routine parses the user name input.
The site can use this callback routine to parse input for interactive logins on character-cell and DECwindows terminals.
Condition Values Returned1
True (1) if successful; otherwise, any condition code returned by CLI$PARSE.
The LGI$ICB_USERPROMPT callback routine prompts for the user name.
Use this callback routine to interactively prompt for the user name on a character-cell terminal. The callback routine reads the response to the prompt and does standard DCL parsing for the user name and any qualifiers provided. Upon completion of this routine, the user name is accessible at the LGI$A_USERNAME entry in the standard arguments vector.
Condition Values Returned
The LGI$ICB_VALIDATE callback routine validates the user name and passwords against the system authorization file.
LGI$ICB_VALIDATE username ,pwd1 ,pwd2
The site can use this callback routine to validate the user name and the user's primary and secondary passwords against the system authorization file (SYSUAF.DAT). The routine also:
Condition Values Returned1
Success, or an error indicating the reason for the failure.
From: MYNODE::USER "The Celestial Navigator" (1) To: NODE::J_DOE (2) CC: USER (3) Subj: Perseids ... (4) Get ready. Tuesday of this week (August 12th), one (5) of the most abundant meteor showers of the year will occur. The Perseids, also known as the St. Laurence's Tears, stream across earth's orbit at 319.3 degrees. Radiant 3h4m +58 degrees. Fine for photography with an average magnitude of 2.27. There will be some fireballs, fainter white or yellow meteors, and brighter green or orange or red ones. About one third of the meteors, including all the brightest, leave yellowish trains, which may be spectacular, up to 2 degrees wide and lasting up to 100 seconds. Brighter meteors often end in flares or bursts. (6)
The parts of a message are as follows:
where n...n is the external message identification number.
The Mail utility organizes messages by date and time received and, secondarily, by folder name. All messages are associated with a folder name---either default folders or user-specified folders. The Mail utility associates mail messages with one of three default mail folder names. Table 14-1 describes the three default mail folders.
|NEWMAIL||Newly received, unread messages|
|Messages that have been read and not deleted|
|WASTEBASKET||Messages designated for deletion|
You can also place messages in any user-defined mail folder and file.
14.3 Mail Files
In addition, you can select messages from mail files as well as copy or move messages to or from mail files.
The indexed mail file format offers two advantages: use of folders and
faster access time than sequential access. Indexed mail files use two
keys to locate messages---a primary key denoting the
date and time received and a secondary key using the
14.4 User Profile Database
The Mail utility maintains an indexed data file VMSMAIL_PROFILE.DATA that serves as a systemwide database of user profile entries. A user profile entry is a record that contains data describing a Mail user's default processing characteristics and whose primary key is the user name. Table 14-2 summarizes information contained in a user profile entry.
|Directory||Default MAIL subdirectory|
|Form||Default print form|
|Forwarding address||Forwarding address|
|Personal name string||User-specified character string included in the message header|
|Queue name||Default print queue name|
Copy self forward
Copy self reply
Copy self send
Purging of the wastebasket folder on exiting
Carbon copy prompt
Copy to self when forwarding a message
Copy to self when replying to a message
Copy to self when sending a message
|Signature file||Text file that is automatically appended to the end of the body of a mail message|
Both the callable interface and the user interface access the user
profile database to determine default processing characteristics.
14.5 Mail Utility Processing Contexts
The Mail utility defines four discrete levels of processing, or contexts for manipulating mail files, messages, folders, and the user profile database as shown in Table 14-3.
|Mail file||Mail files and folders|
|Message||Mail files, folders, and messages|
|User||User profile database|
Within each context, your application processes specific entities in certain ways using callable MAIL routines as described in the sections that follow.
When you begin processing in any context, the Mail utility performs the following functions:
Terminating a MAIL processing context deallocates virtual memory. You
must explicitly terminate processing in any context by calling a
14.5.1 Callable Mail Utility Routines
There are four types of callable Mail utility routines, each corresponding to the context within which they execute. A prefix identifies each functional group:
Table 14-4 lists Mail utility routines according to context.
Once you have successfully initiated MAIL processing in a context, you have created a thread. A thread is a series of calls to MAIL routines that uses the same context information. Applications can contain one or more threads.
For example, consider an application that begins mail file processing; opens, compresses, and closes a mail file; and ends mail file context processing. This application executes a single thread of procedures that reference the same context variable names and pass the same context information.
You can create up to 31 concurrent threads. Applications that contain more than one thread must maintain unique context variables for each thread in order to pass thread-specific context information.
The Mail utility returns the condition value MAIL$_NOMORECTX when your
process attempts to exceed the maximum number of allowable threads.
14.6 Programming Considerations
The calling sequence for all MAIL routines consists of a status variable, an entry point name, and an argument list. All arguments within the argument list are required. All callable MAIL routines use the same arguments in their calling sequences as described in the following example:
STATUS=MAIL$MAILFILE_BEGIN(CONTEXT, IN_ITEM_LIST, OUT_ITEM_LIST)
The variable status receives the condition value, and
the argument context receives the context information.
The arguments in_item_list and
out_item_list are input and output item lists that
contain one or more input or output item descriptors.
14.6.1 Condition Handling
At run time, a hardware- or software-related event can occur that determines whether or not the application executes successfully. The Mail utility processes such an event, or condition in the following ways:
You can establish your own condition handler or allow the program to signal the default condition handler.
You can disable signaling for any call by specifying the item code
MAIL$_NOSIGNAL as an item in the input item list.
14.6.2 Item Lists and Item Descriptors
Your application passes data to callable MAIL routines and receives
data from routines through data structures called item
lists defined in your program.
188.8.131.52 Structure of an Item Descriptor
An input or output item list is a data structure that consists of one or more input or output item descriptors.
The following table summarizes the characteristics of item lists:
|Input||Each descriptor points to a buffer or file from which Mail reads data.|
|Output||Each descriptor points to a buffer or file to which Mail writes data.|
An item descriptor is a data structure consisting of three longwords as described in Figure 14-2.
Figure 14-2 Item Descriptor
Item descriptor fields are described as follows:
|Item code||Specifies an action the routine is to perform.|
|Buffer length||Specifies the length in bytes of an input or output buffer.|
|Buffer address||Specifies the address of the input or output buffer.|
|Return length address||
Depends on the type of item code specified:
You can specify item descriptors in any order within an item list.
Boolean input and output item codes request an operation but do not pass data to the called routine. For example, the item code MAIL$_USER_SET_CC_PROMPT sets the CC prompt flag enabling use of CC: field text.