Document revision date: 19 July 1999 | |
Previous | Contents | Index |
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 |
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.
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. |
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.
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. |
This section provides examples of using the MAIL routines in various programming scenarios including the following:
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 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 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, ©_send, 0}, /* Copy reply flag */ {sizeof(copy_reply), MAIL$_USER_COPY_REPLY, ©_reply, 0}, /* Copy forward flag */ {sizeof(copy_forward), MAIL$_USER_COPY_FORWARD, ©_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); } |
Previous | Next | Contents | Index |
privacy and legal statement | ||
4493PRO_032.HTML |