Updated: 11 December 1998

OpenVMS Utility Routines Manual

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.

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

13.11 Input Item Codes

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

Table 13-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 since 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.

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

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

13.13 Using the MAIL Routines: Examples

This section provides examples of using the MAIL routines in various programming scenarios including the following:

• Example 13-1 is a C program that sends a Mail message to another user.
• Example 13-2 is a C program that displays a user's folders and returns how many messages are in each folder.
• Example 13-3 is a C program that displays fields in the user's Mail profile.

Example 13-1 Sending a File

/* send_message.c */ #include <stdio> #include <descrip> #include <ssdef> #include <maildef> #include <nam> typedef struct itmlst { short buffer_length; short item_code; long buffer_address; long return_length_address; } ITMLST; int send_context = 0 ; ITMLST nulllist[] = { {0,0,0,0} }; int getline(char *line, int max) { if (fgets(line, max, stdin) == NULL) return 0; else return strlen(line); } int main (int argc, char *argv[]) { char to_user[NAM$C_MAXRSS], subject_line[NAM$C_MAXRSS], file[NAM$C_MAXRSS], resultspec[NAM$C_MAXRSS] ; long resultspeclen; int status = SS$_NORMAL, file_len = 0, subject_line_len = 0, to_user_len = 0 ; ITMLST address_itmlst[] = { {sizeof(to_user), MAIL$_SEND_USERNAME, to_user, &to_user_len}, {0,0,0,0}}, bodypart_itmlst[] = { {sizeof(file), MAIL$_SEND_FILENAME, file, &file_len}, {0,0,0,0}}, out_bodypart_itmlst[] = { {sizeof(resultspec), MAIL$_SEND_RESULTSPEC, resultspec, &resultspeclen}, {0,0,0,0}}, attribute_itmlst[] = { {sizeof(to_user), MAIL$_SEND_TO_LINE, to_user, &to_user_len}, {sizeof(subject_line), MAIL$_SEND_SUBJECT, subject_line, &subject_line_len}, {0,0,0,0}} ; status = mail$send_begin(&send_context, &nulllist, &nulllist); if (status != SS$_NORMAL) exit(status); /* Get the destination and add it to the message */ printf("To: "); to_user[getline(to_user, NAM$C_MAXRSS) - 1] = '\0'; address_itmlst[0].buffer_length = strlen(to_user); address_itmlst[0].buffer_address = to_user; status = mail$send_add_address(&send_context, address_itmlst, &nulllist); if (status != SS$_NORMAL) return(status); /* Get the subject line and add it to the message header */ printf("Subject: "); subject_line[getline(subject_line, NAM$C_MAXRSS) - 1] = '\0'; /* Displayed TO: line */ attribute_itmlst[0].buffer_length = strlen(to_user); attribute_itmlst[0].buffer_address = to_user; /* Subject: line */ attribute_itmlst[1].buffer_length = strlen(subject_line); attribute_itmlst[1].buffer_address = subject_line; status = mail$send_add_attribute(&send_context, attribute_itmlst, &nulllist); if (status != SS$_NORMAL) return(status); /* Get the file to send and add it to the bodypart of the message */ printf("File: "); file[getline(file, NAM$C_MAXRSS) - 1] = '\0'; bodypart_itmlst[0].buffer_length = strlen(file); bodypart_itmlst[0].buffer_address = file; status = mail$send_add_bodypart(&send_context, bodypart_itmlst, out_bodypart_itmlst); if (status != SS$_NORMAL) return(status); resultspec[resultspeclen] = '\0'; printf("Full file spec actually sent: [%s]\n", resultspec); /* Send the message */ status = mail$send_message(&send_context, nulllist, nulllist); if (status != SS$_NORMAL) return(status); /* Done processing witht the SEND context */ status = mail$send_end(&send_context, nulllist, nulllist); if (status != SS$_NORMAL) return(status); return (status); }

Example 13-2 shows a C program that displays folders.

Example 13-2 Displaying Folders

/* show_folders.c */ #include <stdio> #include <descrip> #include <ctype> #include <ssdef> #include <maildef> typedef struct itmlst { short buffer_length; short item_code; long buffer_address; long return_length_address; } ITMLST; struct node { struct node *next; /* Next folder name node */ char *folder_name; /* Zero terminated folder name */ }; int folder_routine(struct node *list, struct dsc$descriptor *name) { if (name->dsc$w_length) { while (list->next) list = list->next; list->next = malloc(sizeof(struct node)); list = list->next; list->next = 0; list->folder_name = malloc(name->dsc$w_length + 1); strncpy(list->folder_name,name->dsc$a_pointer,name->dsc$w_length); list->folder_name[name->dsc$w_length] = '\0'; } return(SS$_NORMAL); } main (int argc, char *argv[]) { struct node list = {0,0}; int message_context = 0, file_context = 0, messages_selected = 0, total_folders = 0, total_messages = 0 ; ITMLST nulllist[] = {{0,0,0,0}}, message_in_itmlst[] = { {sizeof(file_context),MAIL$_MESSAGE_FILE_CTX,&file_context,0}, {0,0,0,0}}, mailfile_info_itmlst[] = { {4,MAIL$_MAILFILE_FOLDER_ROUTINE,folder_routine,0}, {4,MAIL$_MAILFILE_USER_DATA,&list,0}, {0,0,0,0}}, message_select_in_itmlst[] = { {0,MAIL$_MESSAGE_FOLDER,0,0}, {0,0,0,0}}, message_select_out_itmlst[] = { {sizeof(messages_selected),MAIL$_MESSAGE_SELECTED,&messages_selected,0}, {0,0,0,0}}; if (mail$mailfile_begin(&file_context, nulllist, nulllist) == SS$_NORMAL) { if (mail$mailfile_open(&file_context, nulllist, nulllist) == SS$_NORMAL) { if (mail$mailfile_info_file(&file_context, mailfile_info_itmlst, nulllist) == SS$_NORMAL) { if (mail$message_begin(&message_context, message_in_itmlst, nulllist) == SS$_NORMAL) { struct node *tmp = &list; while(tmp->next) { tmp = tmp->next; message_select_in_itmlst[0].buffer_address = tmp->folder_name; message_select_in_itmlst[0].buffer_length = strlen(tmp->folder_name); if (mail$message_select(&message_context, message_select_in_itmlst, message_select_out_itmlst) == SS$_NORMAL) { printf("Folder %s has %d messages\n", tmp->folder_name, messages_selected); total_messages += messages_selected; total_folders++; } } printf("Total of %d messages in %d folders\n",total_messages, total_folders); } mail$message_end(&message_context, nulllist, nulllist); } mail$mailfile_close(&file_context, nulllist, nulllist); } mail$mailfile_end(&file_context, nulllist, nulllist); } }

Example 13-3 shows a C program that displays user profile information.

Example 13-3 Displaying User Profile Information

/* show_profile.c */ #include <stdio> #include <ssdef> #include <jpidef> #include <maildef> #include <stsdef> #include <ctype> #include <nam> struct itmlst { short buffer_length; short item_code; long buffer_address; long return_length_address; }; int user_context = 0 ; struct itmlst nulllist[] = { {0,0,0,0} }; int main (int argc, char *argv[]) { int userlen = 0, /* return length of strings */ editor_len = 0, form_len = 0, forwarding_len = 0, full_directory_len = 0, personal_name_len = 0, queue_len = 0, /* Flags */ auto_purge = 0, cc_prompt = 0, copy_forward = 0, copy_reply = 0, copy_send = 0 ; char user[13], editor[NAM$C_MAXRSS], form[NAM$C_MAXRSS], forwarding[NAM$C_MAXRSS], full_directory[NAM$C_MAXRSS], personal_name[NAM$C_MAXRSS], queue[NAM$C_MAXRSS] ; short new_messages = 0 ; struct itmlst jpi_list[] = { {sizeof(user) - 1, JPI$_USERNAME, user, &userlen}, {0,0,0,0}}, user_itmlst[] = { {0, MAIL$_USER_USERNAME, 0, 0}, {0,0,0,0}}, out_itmlst[] = { /* Full directory spec */ {sizeof(full_directory),MAIL$_USER_FULL_DIRECTORY,full_directory,&full_directory_len}, /* New message count */ {sizeof(new_messages), MAIL$_USER_NEW_MESSAGES, &new_messages, 0}, /* Forwarding field */ {sizeof(forwarding), MAIL$_USER_FORWARDING, forwarding, &forwarding_len}, /* Personal name field */ {sizeof(personal_name), MAIL$_USER_PERSONAL_NAME, personal_name, &personal_name_len}, /* Editor field */ {sizeof(editor), MAIL$_USER_EDITOR, editor, &editor_len}, /* CC prompting flag */ {sizeof(cc_prompt), MAIL$_USER_CC_PROMPT, &cc_prompt, 0}, /* Copy send flag */ {sizeof(copy_send), MAIL$_USER_COPY_SEND, &copy_send, 0}, /* Copy reply flag */ {sizeof(copy_reply), MAIL$_USER_COPY_REPLY, &copy_reply, 0}, /* Copy forward flag */ {sizeof(copy_forward), MAIL$_USER_COPY_FORWARD, &copy_forward, 0}, /* Auto purge flag */ {sizeof(auto_purge), MAIL$_USER_AUTO_PURGE, &auto_purge, 0}, /* Queue field */ {sizeof(queue), MAIL$_USER_QUEUE, queue, &queue_len}, /* Form field */ {sizeof(form), MAIL$_USER_FORM, form, &form_len}, {0,0,0,0}}; int status = SS$_NORMAL ; /* Get a mail user context */ status = MAIL$USER_BEGIN(&user_context, &nulllist, &nulllist); if (status != SS$_NORMAL) return(status); if (argc > 1) { strcpy(user,argv[1]); } else { sys$getjpiw(0,0,0,jpi_list,0,0,0); user[userlen] = '\0'; }; while(isspace(user[--userlen])) user[userlen] = '\0'; user_itmlst[0].buffer_length = strlen(user); user_itmlst[0].buffer_address = user; status = MAIL$USER_GET_INFO(&user_context, user_itmlst, out_itmlst); if (status != SS$_NORMAL) return (status); /* Release the mail USER context */ status = MAIL$USER_END(&user_context, &nulllist, &nulllist); if (status != SS$_NORMAL) return(status); /* display the information just gathered */ full_directory[full_directory_len] = '\0'; printf("Your mail file directory is %s.\n", full_directory); printf("You have %d new messages.\n", new_messages); forwarding[forwarding_len] = '\0'; if (strlen(forwarding) == 0) printf("You have not set a forwarding address.\n"); else printf("Your mail is being forwarded to %s.\n", forwarding); personal_name[personal_name_len] = '\0'; printf("Your personal name is \"%s\"\n", personal_name); editor[editor_len] = '\0'; if (strlen(editor) == 0) printf("You have not specified an editor.\n"); else printf("Your editor is %s\n", editor); printf("CC prompting is %s.\n", (cc_prompt == TRUE) ? "disabled" : "enabled"); printf("Automatic copy to yourself on"); if (copy_send == TRUE) printf(" SEND"); if (copy_reply == TRUE) { if (copy_send == TRUE) printf(","); printf(" REPLY"); } if (copy_forward == TRUE) { if ((copy_reply == TRUE) || (copy_send == TRUE)) printf(","); printf(" FORWARD"); } if ((copy_reply == FALSE) && (copy_send == FALSE) && (copy_forward == FALSE)) printf(" Nothing"); printf("\n"); printf("Automatic deleted message purge is %s.\n", (auto_purge == TRUE) ? "disabled" : "enabled"); queue[queue_len] = '\0'; if (strlen(queue) == 0) printf("You have not specified a default queue.\n"); else printf("Your default print queue is %s.\n", queue); form[form_len] = '\0'; if (strlen(form) == 0) printf("You have not specified a default print form.\n"); else printf("Your default print form is %s.\n", form); }

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4493PRO_032.HTML