Document revision date: 30 March 2001

## OpenVMS Utility Routines Manual

Previous | Contents | Index

## 14.13 Using the MAIL Routines: Examples

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

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

Example 14-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 14-2 shows a C program that displays folders.

Example 14-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 14-3 shows a C program that displays user profile information.

Example 14-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);
    }

## 14.14 MAIL Routines

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.

## MAIL$MAILFILE_BEGIN

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

## MAIL$MAILFILE_CLOSE

> 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

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.

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

## MAIL$MAILFILE_COMPRESS

> 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

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.

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

Previous | Next | Contents | Index

| privacy and legal statement |
4493PRO_038.HTML