The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
VMS-Mail-0_04
River stage zero No dependents
++
/ VMS::Mail

NAME

VMS::Mail - VMS callable mail interface

SYNOPSIS

  use VMS::Mail;

Routine to initiate a new untyped object instance:

  $object = new VMS::Mail();

Routines to interact with mailfile contexts:

  $mailfile = new VMS::Mail();
  $href = $mailfile->mailfile_begin();
  $href = $mailfile->open();
  $href = $mailfile->close();
  $href = $mailfile->info_file();
  $href = $mailfile->compress();
  $href = $mailfile->purge_waste();
  $href = $mailfile->end();

Routines to interact with message contexts:

  $message = new VMS::Mail();
  $href = $message->message_begin();
  $href = $message->modify();
  $href = $message->info();
  $href = $message->get();
  $href = $message->select();
  $href = $message->delete();
  $href = $message->copy();
  $href = $message->end();

Routines to interact with send contexts:

  $send = new VMS::Mail();
  $href = $send->send_begin();
  $href = $send->abort();
  $href = $send->add_address();
  $href = $send->add_attribute();
  $href = $send->add_bodypart();
  $href = $send->message();
  $href = $send->end();

Routines to interact with user contexts:

  $user = new VMS::Mail();
  $href = $user->user_begin();
  $href = $user->delete_info();
  $href = $user->set_info();
  $href = $user->get_info();
  $href = $user->end();

One oddball routine that is here temporarily: $returned_string = VMS::Mail::smg_read($prompt [,$keydef_filename [,$default_keydef_filename]])

DESCRIPTION

This module supplies a complete interface to callable the VMSMail routines for client-side access.

This is the first CPAN release. This module is brand new and certainly has bugs. I will be testing it further and will release updates as I repair problems. The purpose of this release is to provide external access to it for peer review. I am very new to the module development process and would welcome any constructive criticism.

Functions

new

This function returns a new VMS::Mail object. The object is 'untyped'. Your next call should be to one of the context-type_begin methods to establish a type and a vms-level context within the object.

Object methods

mailfile_begin

mailfile_begin establishes an untyped object as a VMS MAILFILE context object. Methods for mailfile objects can now be used from the object. Output Items MAIL_DIRECTORY String, 255

message_begin

message_begin establishes an untyped object as a VMS MESSAGE context object. Methods for message objects can now be used from the object. Input items FILE_CTX Context - object returned from new, then MAILFILE_BEGIN Output Items SELECTED Integer

send_begin

send_begin establishes an untyped object as a VMS SEND context object. Methods for send objects can now be used from the object. Input items PERS_NAME String, 127 NO_PERS_NAME Presence flag SIGFILE String, 255 NO_SIGFILE Presence flag DEFAULT_TRANSPORT String, 255 NO_DEFAULT_TRANSPORT Presence flag Output Items COPY_FORWARD Integer COPY_SEND Integer COPY_REPLY Integer SEND_USER String, 255

user_begin

user_begin establishes an untyped object as a VMS USER context object. Methods for user objects can now be used from the object. Output Items AUTO_PURGE Integer CAPTIVE Integer CC_PROMPT Integer COPY_FORWARD Integer COPY_REPLY Integer COPY_SEND Integer FORWARDING String, 255 FORM String, 255 FULL_DIRECTORY String, 255 NEW_MESSAGES Integer PERSONAL_NAME String, 127 QUEUE String, 255 RETURN_USERNAME String, 255 RETURN_SIGFILE String, 255 RETURN_SUB_DIRECTORY String, 255 TRANSPORT String, 255 USER1 String, 255 USER2 String, 255 USER3 String, 255 USER3 String, 255

end

end completes a context-type_begin call and re-establishes the calling object as an untyped object.

open

open. Refer to the VMS Callable mail documentation. Applies to MAILFILE objects. Output Items WASTEBASKET String, 255

close close. Refer to the VMS Callable mail documentation. Applies to MAILFILE objects. Input items FULL_CLOSE Presence flag Output Items DATA_RECLAIM Integer DATA_SCAN Integer INDEX_RECLAIM Integer TOTAL_RECLAIM Integer MESSAGES_DELETED Integer
info_file

info_file. Refer to the VMS Callable mail documentation. Applies to MAILFILE objects. Input items DEFAULT_NAME String, 255 NAME String, 255 FOLDER_ROUTINE Callback - reference to a subroutine Output Items DELETED_BYTES Integer WASTEBASKET String, 255 RESULTSPEC String, 255

compress

compress. Refer to the VMS Callable mail documentation. Applies to MAILFILE objects. Input items FULL_CLOSE Presence flag DEFAULT_NAME String, 255 NAME String, 255 Output Items RESULTSPEC String, 255

purge_waste

purge_waste. Refer to the VMS Callable mail documentation. Applies to MAILFILE objects. Input items RECLAIM Presence flag Output Items DATA_RECLAIM Integer DATA_SCAN Integer INDEX_RECLAIM Integer DELETED_BYTES Integer TOTAL_RECLAIM Integer MESSAGES_DELETED Integer

modify modify. Refer to the VMS Callable mail documentation. Applies to MAILFILE objects. Input items DEFAULT_NAME String, 255 NAME String, 255 WASTEBASKET_NAME String, 39 Output Items RESULTSPEC String, 255

Applies to MESSAGE objects. Input items BACK Integer FLAGS Bitvector - array reference ID Integer NEXT Integer UFLAGS Integer Output Items CURRENT_ID Integer

info

info. Refer to the VMS Callable mail documentation. Applies to MESSAGE objects. Input items BACK Integer ID Integer NEXT Integer Output Items BINARY_DATE String, VMS Date & Time CC String, 255 CURRENT_ID Integer DATE String, 255 EXTID String, 255 FROM String, 255 REPLY_PATH String, 255 RETURN_FLAGS Bitvector - array reference SENDER String, 255 SIZE Integer SUBJECT String, 255 TO String, 255 PARSE_QUOTES Integer RETURN_UFLAGS Integer

get

get. Refer to the VMS Callable mail documentation. Applies to MESSAGE objects. Input items AUTO_NEWMAIL Presence flag BACK Integer UFLAGS Integer CONTINUE Presence flag ID Integer NEXT Integer Output Items BINARY_DATE String, VMS Date & Time CC String, 255 CURRENT_ID Integer DATE String, 255 EXTID String, 255 FROM String, 255 RECORD String, 255 RECORD_TYPE String, enumerated value REPLY_PATH String, 255 RETURN_FLAGS Bitvector - array reference RETURN_UFLAGS Integer SENDER String, 255 SIZE Integer SUBJECT String, 255 TO String, 255 PARSE_QUOTES Integer

select

select. Refer to the VMS Callable mail documentation. Applies to MESSAGE objects. Input items BEFORE String, 32 CC_SUBSTRING String, 255 FLAGS Bitvector - array reference FLAGS_MBZ Bitvector - array reference FOLDER String, 255 FROM_SUBSTRING String, 255 SINCE String, 32 TO_SUBSTRING String, 255 SUBJ_SUBSTRING String, 255 UFLAGS Integer Output Items SELECTED Integer

delete

delete. Refer to the VMS Callable mail documentation. Applies to MESSAGE objects. Input items ID Integer

copy

copy. Refer to the VMS Callable mail documentation. Applies to MESSAGE objects. Input items BACK Presence flag DEFAULT_NAME String, 255 DELETE Presence flag ERASE Presence flag FILE_ACTION Callback - subroutine reference FILENAME String, 255 FOLDER String, 255 FOLDER_ACTION Callback - subroutine reference ID Integer NEXT Presence flag Output Items FILE_CREATED Integer FOLDER_CREATED Integer RESULTSPEC Integer

abort

abort. Refer to the VMS Callable mail documentation. Applies to SEND objects.

add_address

add_address. Refer to the VMS Callable mail documentation. Applies to SEND objects. Input items USERNAME String, 255 I_EN2("USERNAME_TYPE",MAIL$_SEND_USERNAME_TYPE, &c_username_type_enm) PARSE_QUOTES Presence flag

add_attribute

add_attribute. Refer to the VMS Callable mail documentation. Applies to SEND objects. Input items CC_LINE String, 255 FROM_LINE String, 255 SUBJECT String, 255 TO_LINE String, 255 UFLAGS Integer

add_bodypart

add_bodypart. Refer to the VMS Callable mail documentation. Applies to SEND objects. Input items DEFAULT_NAME String, 255 FILENAME String, 255 RECORD String, 255 Output Items SEND_RESULTSPEC String, 255

message

message. Refer to the VMS Callable mail documentation. Applies to SEND objects. Input items I_CBK("ERROR_ENTRY", "USER_DATA", I_CBK("SUCCESS_ENTRY", "USER_DATA",

delete_info

delete_info. Refer to the VMS Callable mail documentation. Applies to USER objects. Input items USERNAME String, 31

set_info

set_info. Refer to the VMS Callable mail documentation. Applies to USER objects. Input items CREATE_IF Presence flag SET_AUTO_PURGE Presence flag SET_NO_AUTO_PURGE Presence flag SET_CC_PROMPT Presence flag SET_NO_CC_PROMPT Presence flag SET_COPY_FORWARD Presence flag SET_NO_COPY_FORWARD Presence flag SET_COPY_REPLY Presence flag SET_NO_COPY_REPLY Presence flag SET_COPY_SEND Presence flag SET_NO_COPY_SEND Presence flag SET_EDITOR String, 255 SET_NO_EDITOR Presence flag SET_FORM String, 255 SET_NO_FORM Presence flag SET_FORWARDING String, 255 SET_NO_FORWARDING Presence flag SET_NEW_MESSAGES Integer SET_QUEUE String, 255 SET_NO_QUEUE Presence flag SET_SIGFILE String, 255 SET_NO_SIGFILE Presence flag SET_SUB_DIRECTORY String, 255 SET_NO_SUB_DIRECTORY Presence flag SET_PERSONAL_NAME String, 127 SET_NO_PERSONAL_NAME Presence flag USERNAME String, 31 SET_USER1 String, 255 SET_NO_USER1 Presence flag SET_USER2 String, 255 SET_NO_USER2 Presence flag SET_USER3 String, 255 SET_NO_USER3 Presence flag SET_TRANSPORT String, 255 SET_NO_TRANSPORT Presence flag

get_info

get_info. Refer to the VMS Callable mail documentation. Applies to USER objects. Input items FIRST Presence flag NEXT Presence flag USERNAME String, 31 Output Items AUTO_PURGE Integer CC_PROMPT Integer COPY_FORWARD Integer COPY_REPLY Integer COPY_SEND Integer EDITOR String, 255 FORM String, 255 FORWARDING String, 255 FULL_DIRECTORY String, 255 PERSONAL_NAME String, 127 QUEUE String, 255 RETURN_USERNAME String, 255 SIGFILE String, 255 SUB_DIRECTORY String, 255 USERNAME String, 31 NEW_MESSAGES Integer TRANSPORT String, 255 USER1 String, 255 USER2 String, 255 USER3 String, 255 USER3 String, 255

BUGS

This is an initial external release. There are certainly many bugs, including, but not limited to: memory leakage, parameter mapping errors, and access violations. No such bugs are known at the time of this writing, but I am sure they are there....

EXAMPLES

An example to list information from your mail file

    #! perl -w
    use VMS::Mail;
    
    {
    $mailfile = new VMS::Mail();

    $ahref = $mailfile->mailfile_begin({},[MAIL_DIRECTORY]);
    if (defined($ahref)) {
      printf("  Mail directory is '%s'\n",$ahref->{MAIL_DIRECTORY});
    } else { die "Failure establishing mailfile context ($!)";

    $ahref = $mailfile->open({},[WASTEBASKET]);
    if (defined($ahref)) {
      printf("Mail file opened\n");
      printf("  Wastebasket folder is '%s'\n",$ahref->{WASTEBASKET});
    } else { die "Failure opening mail file ($!)";

    $rs = sub {
      my ($lstRef,$fldrname) = @_;
      defined($fldrname) && push @$lstRef,$fldrname;
      return(1); };
    $ahref = $mailfile->info_file({ FOLDER_ROUTINE => $rs,
                                    USER_DATA => $rfFlist=[]},
                   [WASTEBASKET,RESULTSPEC,
                    DELETED_BYTES]);
    if (defined($ahref)) {
      printf("  Folder list is (%s)",join(",",@$rfFlist));
      printf("  Wastebasket is '%s'\n",$ahref->{WASTEBASKET});
      printf("  Mail file is '%s'\n",$ahref->{RESULTSPEC});
      printf("  Mail file contains %d deleted bytes\n",$ahref->{DELETED_BYTES});
    } else { die "trying to get mailfile info ($!)";

    $ahref = $mailfile->close({FULL_CLOSE},
                              [TOTAL_RECLAIM,DATA_RECLAIM,DATA_SCAN,
                               INDEX_RECLAIM,MESSAGES_DELETED]);
    if (defined($ahref)) {
      printf("Closed mail file\n");
      printf("  Total reclaim was '%d'\n",$ahref->{TOTAL_RECLAIM});
      printf("  index reclaim was '%d'\n",$ahref->{INDEX_RECLAIM});
      printf("  data reclaim  was '%d'\n",$ahref->{DATA_RECLAIM});
      printf("  data scan     was '%d'\n",$ahref->{DATA_SCAN});
      printf("  messages deleted  '%d'\n",$ahref->{MESSAGES_DELETED});
    }
    $ahref = $mailfile->end({},[]);
    }

AUTHOR

David G. North, CCP <rold5@tditx.com>

SEE ALSO

perl(1).

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 100:

'=item' outside of any '=over'

Around line 106:

You forgot a '=back' before '=head2'

Around line 108:

'=item' outside of any '=over'

Around line 472:

You forgot a '=back' before '=head1'