HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

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

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

/* 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);
}

/* 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);
  }
}

/* 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);
}

This section describes the individual MAIL routines. Input and output item list arguments use item descriptor fields structured as shown in the following diagram:

Item Descriptor Fields

buffer length

For input item lists, this word specifies the length (in bytes) of the buffer that supplies the information needed by the routine to process the specified item code.

For output item lists, this word contains a user-supplied integer specifying the length (in bytes) of the buffer in which the routine is to write the information.

The required length of the buffer depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the routine truncates the data.

item code

For input item lists, a word containing a user-supplied symbolic code that specifies an option for the Mail utility operation. For output item lists, a word containing a user-supplied symbolic code specifying the item of information that the routine is to return. Each programming language provides an appropriate mechanism for defining this information.

buffer address

For input item lists, a longword containing the address of the buffer that supplies information to the routine. For output item lists, a longword containing the user-supplied address of the buffer in which the routine is to write the information.

return length address

This field is not used for input item lists. For output item lists, this field contains a longword specifying the user-supplied address of a longword in which the routine writes the actual length in bytes of the information it returns.

Initiates mail file processing.

Format

MAIL$MAILFILE_BEGIN context ,in_item_list ,out_item_list

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. All utility routines return a condition value in R0. Condition values that can be returned by this routine are listed under Condition Values Returned.

Arguments

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Mail file context information to be passed to other mail file routines. The context argument is the address of a longword that contains mail file context information.

You should specify the value of this argument as 0 in the first of a sequence of calls to mail file routines. In the following calls, you should specify the mail file context value returned by this routine.

in_item_list

OpenVMS usage:	itmlst_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Item list specifying options for the routine. The in_item_list argument is the address of a list of item descriptors, each of which specifies an option and provides the information needed to perform the operation.

The item list is terminated by a longword value of 0.

For this routine, there are no input item codes.

out_item_list

OpenVMS usage:	itmlst_3
type:	longword
access:	write only
mechanism:	by reference

Item list specifying the information you want the routine to return. The out_item_list argument is the address of a list of item descriptors, each of which describes an item of information. The list of item descriptors is terminated by longword value of 0.

The only output item code for this routine is the MAIL$_MAILFILE_MAIL_DIRECTORY item code. When you specify MAIL$_MAILFILE_MAIL_DIRECTORY, MAIL$MAILFILE_BEGIN returns the mail directory specification to the caller. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

MAIL$MAILFILE_BEGIN creates and initiates a mail file context for calls to other mail file routines.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
MAIL$_INVITMCOD	The specified item code is invalid.
MAIL$_INVITMLEN	The specified item length is invalid.
MAIL$_MISREQITEM	The required item is missing.
SS$_ACCVIO	Access violation.
Any condition value returned by LIB$GET_VM, $GETJPIW, and $GETSYI.

Closes the currently open mail file.

Format

MAIL$MAILFILE_CLOSE context ,in_item_list ,out_item_list

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. All utility routines return a condition value in R0. Condition values that can be returned by this routine are listed under Condition Values Returned.

Arguments

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Mail file context information to be passed to mail file routines. The context argument is the address of a longword that contains mail file context information returned by MAIL$MAILFILE_BEGIN.

in_item_list

OpenVMS usage:	itmlst_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Item list specifying options for the routine. The in_item_list argument is the address of a list of item descriptors, each of which specifies an option and provides the information needed to perform the operation.

The item list is terminated by longword value of 0.

Input Item Codes

MAIL$_MAILFILE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE specifies that MAIL$MAILFILE_CLOSE should purge the wastebasket folder when it closes the mail file. If the number of bytes deleted by the purge operation exceeds a system-defined threshold, the Mail utility reclaims the deleted space from the mail file.

Specify the value 0 in the buffer length and buffer address fields of the item descriptor.

The system-defined threshold is reserved by Compaq.

out_item_list

Output Item Codes

MAIL$_MAILFILE_DATA_RECLAIM

When you specify MAIL$_MAILFILE_DATA_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of data buckets reclaimed during the reclaim operation as a longword value.

MAIL$_MAILFILE_DATA_SCAN

When you specify MAIL$_MAILFILE_DATA_SCAN, MAIL$MAILFILE_CLOSE returns the number of data buckets scanned during the reclaim operation as a longword value.

MAIL$_MAILFILE_INDEX_RECLAIM

When you specify MAIL$_MAILFILE_INDEX_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of index buckets reclaimed during a reclaim operation as a longword value.

MAIL$_MAILFILE_MESSAGES_DELETED

When you specify MAIL$_MAILFILE_MESSAGES_DELETED, MAIL$MAILFILE_CLOSE returns the number of messages deleted as a longword value.

MAIL$_MAILFILE_TOTAL_RECLAIM

When you specify MAIL$_MAILFILE_TOTAL_RECLAIM, MAIL$MAILFILE_CLOSE returns the number of bytes reclaimed during a reclaim operation as a longword value.

Description

If you specify the input item code MAIL$_MAILFILE_FULL_CLOSE, this procedure purges the wastebasket folder automatically before it closes the file. If the number of bytes deleted by this procedure exceeds the deleted byte threshold, the system performs a convert/reclaim operation on the file.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
MAIL$_INVITMCOD	The specified item code is invalid.
MAIL$_INVITMLEN	The specified item length is invalid.
MAIL$_MISREQITEM	The required item is missing.
MAIL$_NOFILEOPEN	No mail file is open.
SS$_ACCVIO	Access violation.

Compresses a mail file.

Format

MAIL$MAILFILE_COMPRESS context ,in_item_list ,out_item_list

RETURNS

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

Longword condition value. All utility routines return a condition value in R0. Condition values that can be returned by this routine are listed under Condition Values Returned.

Arguments

context

OpenVMS usage:	context
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Mail file context information to be passed to various mail file routines. The context argument is the address of a longword that contains mail file context information returned by MAIL$MAILFILE_BEGIN.

in_item_list

OpenVMS usage:	itmlst_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

Item list specifying options for the routine. The in_item_list argument is the address of a list of item descriptors, each of which specifies an option and provides the information needed to perform the operation.

The item list is terminated by longword value of 0.

Input Item Codes

MAIL$_MAILFILE_DEFAULT_NAME

MAIL$_MAILFILE_DEFAULT_NAME specifies the default file specification the Mail utility should use when opening a mail file. The buffer address field points to a character string 0 to 255 characters long that defines the default file specification.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

If you specify the value 0 in buffer length field of the item descriptor, MAIL$MAILFILE_COMPRESS uses the current default directory as the default mail file specification.

If you do not specify MAIL$_MAILFILE_DEFAULT_NAME, MAIL$MAILFILE_COMPRESS creates the default mail file specification from the following sources:

• Disk and directory defined in the caller's user authorization file (UAF)
• Subdirectory defined in the Mail user profile
• Default file type of .MAI

MAIL$_MAILFILE_FULL_CLOSE

The Boolean item code MAIL$_MAILFILE_FULL_CLOSE requests that the wastebasket folder be purged and that convert and reclaim operations be performed, if necessary.

Specify the value 0 in the buffer length and buffer address fields of the item descriptor.

MAIL$_MAILFILE_NAME

MAIL$_MAILFILE_NAME specifies the name of a mail file to be opened. The buffer that the buffer address field points to contains a character string of 0 to 255 characters.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

If you do not specify MAIL$_MAILFILE_NAME, the default mail file name is MAIL.

out_item_list

Output Item Code

MAIL$_MAILFILE_RESULTSPEC

When you specify MAIL$_MAILFILE_RESULTSPEC, the Mail utility returns the resultant mail file specification. The buffer address field of the item descriptor points to a buffer that receives a character string 0 to 255 characters long.

Specify a value from 0 to 255 in the buffer length field of the item descriptor.

Description

If you do not specify an input file, the MAIL$MAILFILE_COMPRESS routine compresses the currently open Mail file. The MAIL$MAILFILE_COMPRESS routine signals informational messages concerning the phase of the compression.

Condition Values Returned

SS$_NORMAL	Normal successful completion.
MAIL$_INVITMCOD	The specified item code is invalid.
MAIL$_INVITMLEN	The specified item length is invalid.
MAIL$_MISREQITEM	The required item is missing.
MAIL$_NOTISAM	The message file is not an indexed file.
RMS$_FNF	The specified file cannot be found.
RMS$_SHR	The specified file is not shareable.
SS$_ACCVIO	Access violation.
SS$_IVDEVNAM	The specified device name is invalid.
Any condition value returned by LIB$FIND_IMAGE_SYMBOL, LIB$RENAME_FILE, $CREATE, $OPEN, $PARSE, and $SEARCH.