OS/2 Shareware BBS: 18 REXX/18-REXX.zip/rexvim.zip/REXXVIM.INF

OS/2 Help File | 1994-07-18 | 157KB | 7,577 lines

ΓòÉΓòÉΓòÉ 1. RexxVIM ΓòÉΓòÉΓòÉ

RexxVIM allows programs written in Rexx to communicate with Vendor Independent
Messaging (VIM) enabled mail systems.  This includes cc:Mail and Lotus Notes.
This toolkit provides the functionality of the Lotus VIM Developer'sToolkit to
Rexx applications.

The additional functions provided by this toolkit are usable with the base Rexx
support provided in Operating System/2 (OS/2). The toolkit extensions have also
been tested with Rexx extension products, such as VX-Rexx from Watcom,
VisPro/Rexx from Hockware, and GpfRexx from Gpf Systems.


ΓòÉΓòÉΓòÉ 2. License Agreement and Limited Product Warranty ΓòÉΓòÉΓòÉ

YOU SHOULD CAREFULLY READ THE FOLLOWING TERMS AND CONDITIONS. USING THIS
PROGRAM INDICATES YOUR ACCEPTANCE OF THEM.  IF YOU DO NOT AGREE WITH THEM,
PROMPTLY RETURN THE PACKAGE AND YOUR MONEY WILL BE REFUNDED.

Innovative Business Technologies, Inc. provides this Program and licenses its
use to you.  You are responsible for selecting the Program to achieve your
intended results and for the installation, use and results obtained form this
program.

THE PROGRAM, INCLUDING ITS STRUCTURE AND ORGANIZATION, AS WELL AS, ITS CODE, IS
A PROPRIETARY PRODUCT OF INNOVATIVE BUSINESS TECHNOLOGIES AND IS PROTECTED BY
COPYRIGHT LAWS.  TITLE TO THE PROGRAM, OR ANY COPY, MODIFICATION OR MERGED
PORTION OF THE PROGRAM, SHALL AT ALL TIMES REMAIN WITH INNOVATIVE BUSINESS
TECHNOLOGIES, INC.

LICENSE

You may:

Use the Program for development only on a single computer.  Even though two
copies of the program may be provided in this package, on diskettes of
different sizes, you may not use both sizes of diskettes simultaneously on
different computers.  This Program may not under any circumstances be used for
development on more than one computer system at a time.

Distribute without cost the RexxVIM.dll runtime program file to allow programs
created with the Program to operate on other computer systems.

Make one copy of the Program into any computer readable or printed form for
backup or modification purposes in support of your use of the Program for
development on a single computer.

Transfer the Program together with this License to another party, but only if
the other party agrees to accept the terms and condidtions of theis Agreement.
If you transfer the Program and License, you must at the same time either
transfer all copies, modifications or merged portions of the Program to the
same party or destroy those note transferred.  Any such transfer terminates
your License.

 You may not:

TRANSFER OR RENT THE PROGRAM OF USE, COPY MODIFY OR MERGE THE PROGRAM, IN WHOLE
OR IN PART, EXCEPT AS EXPRESSLY PERMITTED IN THIS LICENSE.

DECOMPILE, REVERSE ASSEMBLE OR OTHERWISE REVERSE ENGINEER THE PROGRAM.

REPRODUCE, DISTRIBUTE OR REVISE THE PROGRAM DOCUMENTATION.

IF YOU DO ANY OF THE FOREGOING, YOUR LICENSE AND THIS AGREEMENT ARE
AUTOMATICALLY TERMINATED.  SUCH TERMINATION SHALL BE IN ADDTION TO AND NOT IN
LIEU OF ANY CRIMIANL, CIVAL, OR OTHER REMEDIES AVAILABLE TO INNOVATIVE BUSINESS
TECHNOLOGIES.

TERM

You may terminate your License and this Agreement at any time by destroying the
Program and the Program documentation together with all copies in any form.
They will also terminate automatically if you fail to comply with any term or
condition of this Agreement, in which event you agree to destroy the Program
together with all copies in any form, and to provide us upon our request with
written certification of such destruction.

LIMITED PRODUCT WARRANTY

EXCEPT AS SPECIFICALLY STATED IN THIS AGREEMENT, THE PROGRAM IS PROVIDED AND
LICENSED "AS IS" WITHOUT WARRANTY OR ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE.

Innovative Business Technologies warrants that the Program will substantially
perform the functions or generally conforms to the Program's specifications
published by Innovative Business Technologies.

Innovative Business Technologies warrants that the diskettes on which the
Program is furnished will be free for defects in materials and workmanship
under normal use for a period of ninety days from the date of delivery to you.

Innovative Business Technologies DOES NOT WARRANT that the functions contained
in the Program will meet your requirements or that the operation of the Program
will be entirely error free or appear precisely as described in the Program
documentation.

LIMITATION OF REMIDIES AND LIABILITY

The remedies described below are accepted by you as your only remedies, and
shall be available to you only if you or your dealer returns the enclosed
registration card to Innovative Business Technologies within ten days after
delivery of the Program to you.  Innovative Business Technologies' entire
liability and your exclusive remedies shall be:

If the Program does not substantially perform the functions or generally
conform to the Program's specifications published by Innovative Business
Technologies, you may within siz months after delivery write to Innovative
Business Technologies to report a significant defect.  If Innovative Business
Technologies is unable to correct that defect within 90 days after receiving
your report, you may terminate your License and this Agreement by returning the
Program with your original receipts and your money will be refunded.

If the Program diskette is defective, you may return it with a copy of your
receipt, and Innovative Business Technologies with either replace it or, if a
replacement cannot soon be delivered, you may terminate your License and this
Agreement by returning the Program with your original receipts and your money
will be refunded.

IN NO EVENT WILL INNOVATIVE BUSINESS TECHNOLOGIES BE LIABLE TO YOU FOR ANY
DAMAGES, INCLUDING LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR
CONSEQUENTIAL DAMAGES, ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM,
EVEN IF INNOVATIVE BUSINESS TECHNOLOGIES OR DEALER HAS BEEN ADVISED OR THE
POSSIBILITY OF SUCH DAMAGES.

GENERAL

If any provision of this Agreement is held to be unenforceable, the
enforceability of the remianing provisions shall in no way be affected or
impaired thereby.

The prevailing party in any action or proceeding brought in connection with a
breach of this Agreement will be entitled to reimbursement by the other party
for costs and resonable attorney's fees.  This Agreement shall be governed by
the laws of the State of Ohio.

Any questions concerning this Agreement should be referred in writing to
Innovative Business Technologies, Inc. at 7137 Shady Nelms Drive, Suite #204,
Columbus, OH 43017.

YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, AND BY OPERATING THIS
PROGRAM INDICATE YOUR ACCEPTANCE OF ITS TERMS AND CONDITIONS.


ΓòÉΓòÉΓòÉ 3. Contacts and Order Form ΓòÉΓòÉΓòÉ

This section contains company contact and product ordering information.


ΓòÉΓòÉΓòÉ 3.1. Contact Information ΓòÉΓòÉΓòÉ

RexxVIM is copyrighted by Innovative Business Technologies, Inc.  Rights to use
this application will terminate upon the completion of the beta test program.
All copyrights and trademarks referenced in this material are the properties of
their respective corporations.

All future releases of this beta will be submitted to CompuServe.  If you have
any questions, problems, or bug reports, please send them to:

        Innovative Business Technologies, Inc.
        7137 Shady Nelms Drive
        Suite 204
        Columbus, OH 43017

        CompuServe:     74563,1530

or

        Voice/Fax:      [phone]


ΓòÉΓòÉΓòÉ 3.2. Product Ordering Information ΓòÉΓòÉΓòÉ

RexxVIM is available directly from Innovative Business Technologies, Inc.  The
software is licensed per developer, with unlimited rights to distribute the
runtime dll.  Each user developing RexxVIM applications will require a copy of
the development environment.  The development environment includes:

     RexxVIM.dll    -    Runtime dynamic link library
     RexxVIM.inf    -    Full online documentation

     RexxPack.exe   -    Program to compact a Rexx command file for
                         faster execution and limited change

     Example apps   -    Example applications that demonstrate the
                         use of all of the RexxVIM functions


ΓòÉΓòÉΓòÉ 3.3. Order Form ΓòÉΓòÉΓòÉ

INNOVATIVE BUSINESS TECHNOLOGIES, INC.    ++++++++++++++++++++++
7137 SHADY NELMS DRIVE, SUITE #204        | RexxVIM Order Form |
COLUMBUS, OH 43017                        ++++++++++++++++++++++
VOICE/FAX: [phone]

                                          Date:  _______________

Company Name:  _________________________________________________

Name:          _________________________________________________

Address:       _________________________________________________

City:          ________________________   State:    ____________

Zip Code:      ________________________   Country:  ____________

Telephone:     ________________________

Fax:           ________________________

================================================================
Version of ccMail or Lotus Notes currently in use: ____________

For electronic distribution, please list your e-mail address -

CompuServe        Internet         Prodigy        America Online

Address:       _________________________________________________

================================================================

  Quantity   Product Description           Cost           Total

  ________   RexxVIM for OS/2           $295.00      __________

     Shipping and Handling                                 4.00

     Ohio Residents add 5.75% Sales Tax              __________

  TOTAL ORDER
                                                     ==========

Please send your completed order form, including a check or
money order (U.S. Funds only) payable to: Innovative Business
Technologies, Inc.

================================================================
For faster service, fax us your order by including your credit
card information:

CREDIT CARD:   VISA      MASTERCARD     AMERICAN EXPRESS


CREDIT CARD NUMBER: ____________________________________________

EXPIRATION DATE:    ____________/_______________/_______________

SIGNATURE:          ____________________________________________
================================================================


ΓòÉΓòÉΓòÉ 4. What's New In this beta version ΓòÉΓòÉΓòÉ

This release of RexxVIM has the following changes from previous beta versions:

07/15/94
All of the functions that are part of the VIM specification
are now active.

RxVIMGetEntityName function has been changed.  It will now
return stem.type, stem.name, and stem.addressbook rather than
stem.1, stem.2, and stem.3.  This will make the stem variable
easier to understand.


07/08/94

The Message Container functions are now active.  These functions
allow message containers to be queried.  The results of the
query will allow actions to be taken on one or many messages.
A new example program is included to demonstrate the use of the
message container functions (MSGCONT.cmd).

The name of the product has been changed from "VIM Toolkit for Rexx"
to RexxVIM.  This change was made to prevent confusion between this
product and the "Lotus VIM Developer's Toolkit".


06/24/94

All calls now include support for pointers to allow multiple
sessions, messages, containers, and addressbooks.


ΓòÉΓòÉΓòÉ 5. Installation ΓòÉΓòÉΓòÉ

RexxVIM  files should be installed in a REXXVIM subdirectory.  If the files are
installed in another directory, the example applications in this material will
not be directly launchable.

The REXXVIM.dll must be placed in a directory that is referenced in the LIBPATH
statement in the config.sys file.  You may copy the file to the c:\os2\dll
directory, or add REXXVIM to the LIBPATH statement.

For the application to function correctly, the VIM.dll, MAILENG.dll, and the
other VIM dlls must be 9/93 or later versions.

The REXXVIM.zip file contains the following files:

      RexxVIM.dll          The dynamic link library that adds
                           VIM functions to Rexx

      RexxVIM.inf          The help file for the toolkit

      Demo.cmd             Rexx program to demonstrate the basic
                           RexxVIM functions

      VIMcap.cmd           Rexx program to demonstrate querying
                           the VIM subsystem for supported features

      Message.cmd          Rexx program to demonstrate sending
                           a message using RexxVIM

      MSGCont.cmd          Rexx program to demonstrate using the
                           message container.  Allows each message
                           in the Inbox to be deleted, stored in
                           a folder, or left in the Inbox.

      MSGActs.cmd          Rexx program to demonstrate the use
                           of the message access functions.

      AddrBook.cmd         Rexx program to demonstrate the use
                           of the address book functions for
                           opening, closing, and enumerating.

      ABEdemo.cmd          Rexx program to demonstrate the use
                           of the address book functions that
                           provide access to the address book
                           entries and group members.


ΓòÉΓòÉΓòÉ 6. Base Functions ΓòÉΓòÉΓòÉ

This section describes each of the functions available in the RexxVIM product
that address base RexxVIM features.


ΓòÉΓòÉΓòÉ 6.1. RxVIMLoadFuncs ΓòÉΓòÉΓòÉ

The RxVIMLoadFuncs function loads all of the VIM extensions using one call.


ΓòÉΓòÉΓòÉ 6.1.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMLoadFuncs is called with no parameters.

call RxVIMLoadFuncs

or

rc = RxVIMLoadFuncs()


ΓòÉΓòÉΓòÉ 6.1.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMLoadFuncs function returns the following values:

        0 - Successful load of all functions
        1 - Load of functions failed

        NOTE:  The load will fail if a previous program did
               not execute the RxVIMDropFuncs function.


ΓòÉΓòÉΓòÉ 6.1.3. Example ΓòÉΓòÉΓòÉ

/* Example to load all of the VIM extensions */

call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


ΓòÉΓòÉΓòÉ 6.2. RxVIMDropFuncs ΓòÉΓòÉΓòÉ

The RxVIMDropFuncs function unloads all of the VIM extensions using one call.


ΓòÉΓòÉΓòÉ 6.2.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMDropFuncs is called with no parameters.

call RxVIMDropFuncs

or

rc = RxVIMDropFuncs()


ΓòÉΓòÉΓòÉ 6.2.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMDropFuncs function returns the following values:

        0 - Successful unload of all functions
        1 - Unload of functions failed


ΓòÉΓòÉΓòÉ 6.2.3. Example ΓòÉΓòÉΓòÉ

/* Example to unload all of the VIM extensions */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7. Session Management Functions ΓòÉΓòÉΓòÉ

This section describes each of the functions available in the RexxVIM product
that address VIM session management.


ΓòÉΓòÉΓòÉ 7.1. RxVIMInitialize ΓòÉΓòÉΓòÉ

The RxVIMInitialize function establishes a connection to the underlying VIM
sub-system.  This function must be called prior to any of the other functions
that interact with the VIM system.  This function should only be called once
for any command file that interacts with a VIM system.


ΓòÉΓòÉΓòÉ 7.1.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMInitialize is called with no parameters.

call RxVIMInitialize

or

rc = RxVIMInitialize()


ΓòÉΓòÉΓòÉ 7.1.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMInitialize function returns the following values:

        0 - Successful initialization

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMInitialize:

        VIMSTS_SUCCESS          Successful Initialization
        VIMSTS_FAILURE          Initialization Failed


ΓòÉΓòÉΓòÉ 7.1.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMInitialize */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Show return code to user */
Say 'The return code from the Initialize was =' rc


/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7.2. RxVIMQueryCapability ΓòÉΓòÉΓòÉ

The RxVIMQueryCapability function allows the application to determine supported
features in the underlying VIM system.  This function should be used to
determine what features are supported in the particular VIM system be used,
prior to using the feature.


ΓòÉΓòÉΓòÉ 7.2.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMQueryCapability is called with two parameters. The first parameter is a
selector of the item to be queried, and the second is the Rexx variable to
contain the result.

call RxVIMQueryCapability 'Selector' , 'variable'

or

rc = RxVIMQueryCapability('Selector' , 'variable')

Listed below are the valid selectors to query, and the possible return values:

VIMSEL_VERSION                  Indicates the VIM version number

VIMSEL_IMPLEMENTATION           Indicates the product that is providing the database

VIMSEL_IMPLEMENTATION_VERSION   Indicates the version of the VIM implementation

VIMSEL_PRODUCT                  Indicates the name of the product

                                   ccMail will return CCMAIL
                                   Notes will return NOTES

VIMSEL_MAX_SUBJECT_LEN          This is the maximum limit for a subject line

VIMSEL_MAX_TYPE_LEN             This is the maximum limit for an item of type VIMSEL_TYPE

VIMSEL_MAX_TEXT_LEN             This is the maximum limit for a text item

VIMSEL_RTF                      Returns level of support for Rich Text Format

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_FAX                      Returns level of support for FAX

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_STYLED                   Returns level of support for Macintosh styled text

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_PICT                     Returns level of support for Macintosh PICT note parts

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_MOVIE                    Returns level of support for Quicktime movie parts

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_IMAG                     Returns level of support for Macintosh FAX note parts

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_UNWRAPPED_TEXT           Returns level of support for unwrapped text

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_ALL_NOTE_PARTS_SUPP      Returns TRUE if all notes part types are supported
                                without conversion

VIMSEL_ATTACH_TYPE_SUPP         Returns TRUE if types are supported for file attachment

VIMSEL_ATTACH_DIRS              Returns level of support for attaching directories

                                   VIMSEL_NOT_SUPPORTED - Not supported
                                   VIMSEL_SUPP_WITH_CONV - Support with conversion at source
                                   VIMSEL_SUPP_WITHOUT_CONV - Support without conversion at source

VIMSEL_ENCRYPT                  Returns TRUE if key-based encryption is supported

VIMSEL_ENCRYPT_WITH_KEY         Returns TRUE if explicit key-based encryption is
                                supported

VIMSEL_SIGN                     Returns TRUE if signatures are supported

VIMSEL_NSTD_DERIVED_REPLIES     Returns TRUE if replies are generated as nested
                                messages

VIMSEL_NSTD_DERIVED_FORWRDS     Returns TRUE if forwarded message are generated
                                as nested messages

VIMSEL_CP850                    Returns TRUE if the IBM 850 code page is supported

VIMSEL_CP1252                   Returns TRUE if the IBM 1252 code page is supported

VIMSEL_CP437                    Returns TRUE if the IBM 437 code page is supported

VIMSEL_LMBSC                    Returns TRUE if Lotus Multi-Byte Character Set is
                                supported

VIMSEL_ISTRING                  Returns TRUE if Apple International strings are
                                supported

VIMSEL_UNICODE                  Returns TRUE if Unicode multi-byte characters are
                                supported

VIMSEL_APPLESINGLE              Returns TRUE if AppleSingle file attachments are
                                supported

VIMSEL_PATH_REQUIRED            Returns TRUE if database path must be specified
                                during a RxVIMOpenSession

VIMSEL_NAME_REQUIRED            Returns TRUE if user name must be specified
                                during a RxVIMOpenSession

VIMSEL_PASS_REQUIRED            Returns TRUE if the password must be specified
                                during a RxVIMOpenSession


ΓòÉΓòÉΓòÉ 7.2.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMQueryCapability function returns the following values

        0 - Successful initialization

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMQueryCapability:

        VIMSTS_SUCCESS          Successful Initialization
        VIMSTS_FAILURE          Initialization Failed

        VIMSTS_BAD_PARAM        Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL    Results exceed size of return variable
        VIMSTS_INVALID_SELECTOR Selector is unknown


ΓòÉΓòÉΓòÉ 7.2.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMQueryCapability */

/* The RxLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxLoadFuncs', 'RexxVIM', 'RxLoadFuncs'
call RxLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()


/* Query the VIM system for product version level */
rc = RxVIMQueryCapability('VIMSEL_VERSION', 'Version')
Say 'VIM Version is' Version
Say
/* Query the VIM system for Max Subject Line Length */
rc = RxVIMQueryCapability('VIMSEL_MAX_SUBJECT_LEN', 'Subject_Length')
Say 'The maximum subject line length is' Subject_Length
Say


/* The RxDropFuncs function unloads all of the VIM extensions */
call RxDropFuncs


ΓòÉΓòÉΓòÉ 7.3. RxVIMDefaultSessionInfo ΓòÉΓòÉΓòÉ

The RxVIMDefaultSessionInfo function obtains the default user name and database
path name.  This information can then be passed to the VIM system during a
RxVIMOpenSession.


ΓòÉΓòÉΓòÉ 7.3.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMDefaultSessionInfo is called with two parameters. The first parameter is
the variable to return the default path, and the second is the variable to
return the default name.  This function will return a null value if no default
session information exists.

call RxVIMDefaultSessionInfo 'path_variable', 'name_variable'

or

rc = RxVIMDefaultSessionInfo('path_variable', 'name_variable')


ΓòÉΓòÉΓòÉ 7.3.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMDefaultSessionInfo function returns the following values:

        0 - Successful initialization

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMDefaultSessionInfo:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL            Results exceed size of return variable
        VIMSTS_INVALID_CONFIGURATION    Underlying configuration is incorrectly configured


ΓòÉΓòÉΓòÉ 7.3.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMDefaultSessionInfo */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7.4. RxVIMOpenSession ΓòÉΓòÉΓòÉ

The RxVIMOpenSession function establishes an active session with the VIM
system.


ΓòÉΓòÉΓòÉ 7.4.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenSession is called with four parameters. The first parameter is the
location of the postoffice. The second is the name of the user opening the
session.  The third parameter is the password of the user opening the session.
If all of the parameters are not required, then a NULL string ('') is required
in its location.  The fourth parameter which will contain the Session handle is
required.  The session handle will be used in other calls to allow multiple
sessions to be opened concurrently.

call RxVIMOpenSession 'location', 'username', 'password', 'Session'

or

rc = RxVIMOpenSession('location', 'username', 'password', 'Session')


ΓòÉΓòÉΓòÉ 7.4.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMOpenSession function returns the following values:

        0 - Successful session established

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMOpenSession:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_ALL_PARAMS_REQUIRED      All values are required
        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory to open session
        VIMSTS_INVALID_CONFIGURATION    Underlying configuration is incorrectly configured
        VIMSTS_INVALID_PASSWORD         Password is incorrect
        VIMSTS_OPEN_FAILURE             Message system could not be opened
        VIMSTS_PASS_REQUIRED            A Password is required
        VIMSTS_UNSUP_VERSION            VIM version not supported


ΓòÉΓòÉΓòÉ 7.4.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenSession */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7.5. RxVIMOpenGatewaySession ΓòÉΓòÉΓòÉ

The RxVIMOpenGatewaySession function establishes an active session with the VIM
system with special gateway capabilities.

**THIS FUNCTION IS AN EXTENSION TO VIM, AND IS CURRENTLY NOT SUPPORTED**


ΓòÉΓòÉΓòÉ 7.6. RxVIMGetEntityName ΓòÉΓòÉΓòÉ

The RxVIMGetEntityName function obtains the current name associated with the
active session.  It also retrieves the type of entity, and the associated
addressbook.


ΓòÉΓòÉΓòÉ 7.6.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMGetEntityName is called with two parameters.  The first parameter is the
session handle returned from the RxVIMOpenSession function. The second
parameter is a Rexx variable that will be used as a stem variable for the three
portions of the return information. The type of the entity will be returned in
the stem_variable.Type location. The name of the entity will be returned in the
stem_variable.Name location. The addressbook of the entity will be returned in
the stem_variable.AddressBook location.

call RxVIMGetEntityName session, 'stem_variable'

or

rc = RxVIMGetEntityName(session, 'stem_variable'))


ΓòÉΓòÉΓòÉ 7.6.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMGetEntityName function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMGetEntityName:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_BUF_TOO_SMALL            Name or Address too large for buffer
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
        VIMSTS_INVALID_CONFIGURATION    VIM subsystem is incorrectly configured
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_NO_DEFAULT               NULL session is not supported


ΓòÉΓòÉΓòÉ 7.6.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMGetEntityName */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Display the type, name, and addressbook of active session */
rc = RXVIMGetEntityName(Sess, 'Entity.')
Say 'Active VIM Session'
Say
Say 'Type:        ' Entity.Type
Say 'Name:        ' Entity.Name
Say 'Addressbook: ' Entity.AddressBook

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession()

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7.7. RxVIMCloseSession ΓòÉΓòÉΓòÉ

The RxVIMCloseSession function closes the current session with the VIM system
and frees all resources.  This function should be called in any program that
issues an RxVIMOpenSession function.


ΓòÉΓòÉΓòÉ 7.7.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCloseSession is called with with the session handle of the session to
close.

call RxVIMCloseSession session

or

rc = RxVIMCloseSession(session)


ΓòÉΓòÉΓòÉ 7.7.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCloseSession function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCloseSession:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_INVALID_OBJECT           The session handle is bad


ΓòÉΓòÉΓòÉ 7.7.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCloseSession */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7.8. RxVIMTerminate ΓòÉΓòÉΓòÉ

The RxVIMTerminate function ends the connection to the VIM system.  This
function must be the last RexxVIM function called.


ΓòÉΓòÉΓòÉ 7.8.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMTerminate is called with no parameters.

call RxVIMTerminate

or

rc = RxVIMTerminate()


ΓòÉΓòÉΓòÉ 7.8.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMTerminate function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMTerminate:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed


ΓòÉΓòÉΓòÉ 7.8.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMTerminate */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* This will terminate the connection to the VIM system */
rc = RxVIMTerminate()

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 7.9. RxVIMStatusText ΓòÉΓòÉΓòÉ

The RxVIMStatusText function converts RexxVIM return values into the
corresponding text message.  The function allows the program to operate on the
VIM Status messages without decoding the actual return value.


ΓòÉΓòÉΓòÉ 7.9.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMStatusText is called with three parameters. The first parameter is the
session handle for the session to use for the function call. The second
parameter is the status code in which text information is desired.  The third
parameter is a Rexx variable that will be used as a stem variable for the two
portions of the return text.  The VIM status code will be returned in the
stem_variable.1 location.  The extended text will be returned in the
stem_variable.2 location.  Not all status code have both parts, in which case a
null will be returned for extended text.

call RxVIMStatusText session, 'Status', 'stem_variable'

or

rc = RxVIMStatusText(session, 'Status', 'stem_variable')


ΓòÉΓòÉΓòÉ 7.9.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMStatusText function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMStatusText:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_NOT_SUPPORTED            Error text strings are not supported


ΓòÉΓòÉΓòÉ 7.9.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMStatusText */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Display the type, name, and addressbook of active session */
Init = RXVIMGetEntityName(Sess, 'Entity.')

/* This will print the text associated with the return code */
/* from the above function call.  It will also print the    */
/* extended status if it exists.                            */

rc = RxVIMStatusText(Sess, Init, 'status')

Say 'Return Status:   ' status.1
if LENGTH(status.2) > 0 then do
   Say 'Extended Status: ' status.2
end

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8. Message Creation and Submission Functions ΓòÉΓòÉΓòÉ

This section describes each of the functions available in the RexxVIM product
that address message creation and submission features.


ΓòÉΓòÉΓòÉ 8.1. RxVIMCreateMessage ΓòÉΓòÉΓòÉ

The RxVIMCreateMessage function creates a new message area and prepares it for
composition.


ΓòÉΓòÉΓòÉ 8.1.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCreateMessage is called with three parameters.  The first parameter is the
session handle. The second parameter is the type of message being created.
VIM_MAIL will be used for all mail messages.  The third parameter is the
variable to contain the message handle.

call RxVIMCreateMessage session, 'VIM_MAIL', 'Message'

or

rc = RxVIMCreateMessage(session, 'VIM_MAIL', 'Message')


ΓòÉΓòÉΓòÉ 8.1.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCreateMessage function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCreateMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_UNSUP_TYPE               The type passed is not supported


ΓòÉΓòÉΓòÉ 8.1.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCreateMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Create a new message for composition */
rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')

/* NOTE:                                                   */
/* Message will be discarded, since the program is closing */
/* the session without processing the message              */

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession()

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8.2. RxVIMCreateDerivedMailMessage ΓòÉΓòÉΓòÉ

The RxVIMCreateDerivedMailMessage function uses the contents of an existing
message to create a new message.  This function can be used to create forwarded
messages, and replies that include the original message content.


ΓòÉΓòÉΓòÉ 8.2.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCreateDerivedMailMessage is called with four parameters.  The first
parameter is the handle of the original message to create the derived message.
The second parameter is the type of message being created. The third parameter
is a flag to indicate options for the message.  The fourth parameter is the
variable to contain the message handle of the derived message.

call RxVIMCreateDerivedMailMessage MsgPtr, 'type', 'flags', 'Message'

or

rc = RxVIMCreateDerivedMailMessage(session, 'type', 'flags', 'Message')

Listed below are the valid selectors to indicate the type of derived message:

VIMSEL_FORWARD                  Message will be directed to new recipients

VIMSEL_REPLY                    Message will be returned to sender

Listed below are the valid flags to indicate the style of derived message:

VIM_NO_FLAGS                    No flags specified

VIM_HISTORY                     Previous forwarding history to be maintained
                                (For VIMSEL_FORWARD)

VIM_INHERIT_CONTENTS            Previous contents will be maintained with new
                                message (For VIMSEL_REPLY)

VIM_ALL_RECIPIENTS              New message will be returned to all recipients,
                                not just the sender (For VIMSEL_REPLY)


ΓòÉΓòÉΓòÉ 8.2.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCreateDerivedMailMessage function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCreateDerivedMailMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_INVALID_SELECTOR         The type is bad


ΓòÉΓòÉΓòÉ 8.2.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCreateDerivedMailMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','OldMsg')



/* Create a forward message for composition */
rc = RxVIMCreateDerivedMailMessage(OldMsg, 'VIM_FORWARD', 'VIM_NO_FLAGS', 'Message')



/* NOTE:                                                   */
/* Message will be discarded, since the program is closing */
/* the session without processing the message              */

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession()

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8.3. RxVIMSetMessageHeader ΓòÉΓòÉΓòÉ

The RxVIMSetMessageHeader function sets the value of message attributes.  This
function is used to set attributes such as subject, priority, and return
receipt.


ΓòÉΓòÉΓòÉ 8.3.1. Syntax ΓòÉΓòÉΓòÉ

The RxVIMSetMessageHeader function is called with three parameters.  The first
parameter is the message handle from the RxVIMCreateMessage function call.  The
second parameter is the selector for the attribute to set, and the third is the
value for the attribute.

call RxVIMSetMessageHeader message, 'selector', 'value'

or

rc = RxVIMSetMessageHeader(message, 'selector', 'value')

Listed below are the valid selectors to use to set message header attributes:

VIMSEL_SUBJECT                  Sets the text for the subject up to
                                the maximum supported.  Use the
                                RxVIMQueryCapability to determine
                                maximum length.

VIMSEL_PRIORITY                 Sets the importance of the message.
                                Valid options are:

                                VIMSEL_LOW_PRIORITY
                                VIMSEL_NORMAL_PRIORITY  (default value)
                                VIMSEL_HIGH_PRIORITY

VIMSEL_DELIVERY_REPORT          If supported, this attribute will
                                report the delivery for each recipient
                                a successful delivery is made.  Valid
                                options to pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_NONDELIVERY_REPORT       If supported, this attribute will
                                report the delivery for each recipient
                                a unsuccessful delivery is made.  Valid
                                options to pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_NONDELIVERY_CONTENTS     If supported, this attribute will
                                report the delivery for each recipient
                                a unsuccessful delivery is made. The
                                report will include the contents of
                                the original message. Valid options to
                                pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_ENCRYPT                  If supported, this attribute will
                                cause the message to be encrypted with
                                an implicit key.  Valid options to
                                pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_ENCRYPT_WITH_KEY         If supported, this attribute will
                                cause the message to be encrypted with
                                an explicit key.  Valid options to
                                pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_SIGN                     If supported, this attribute will
                                cause the message to be signed.
                                Valid options to pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_CONVERSATION_ID          If supported, this attribute will
                                set the conversation id.

VIMSEL_SENSITIVITY              If supported, this attribute will
                                set the sensitivity of the message.
                                Valid options to pass are:

                                VIMSEL_NORMAL_SENS
                                VIMSEL_PRIVATE_SENS
                                VIMSEL_PERSONAL_SENS
                                VIMSEL_CO_CONFID_SENS

VIMSEL_IN_REPLY_TO              If supported, this attribute will
                                set id of the message that the current
                                message is in reply to.

VIMSEL_RESPOND_BY               If supported, this attribute will
                                set date the message must responded to.

VIMSEL_KEYWORD                  If supported, this attribute will
                                set a keyword for the current message.

VIMSEL_RETURN_RECEIPT           This attribute sets the request for
                                a return receipt on/off.  Valid
                                options to pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_SAVE                     This attribute sets the request for
                                a copy of the message to be saved
                                when it is sent. Valid options to
                                pass are:

                                VIM_TRUE
                                VIM_FALSE

VIMSEL_DRAFT                    This attribute sets the message to
                                a draft.  If the session is closed
                                without the message being sent, a
                                copy will be saved. Valid options to
                                pass are:

                                VIM_TRUE
                                VIM_FALSE


ΓòÉΓòÉΓòÉ 8.3.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSetMessageHeader function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSetMessageHeader:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_INVALID_SELECTOR         The selector passed is not valid
        VIMSTS_NOT_SUPPORTED            The selector passed is not supported


ΓòÉΓòÉΓòÉ 8.3.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSetMessageHeader */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Create a new message */
rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')

/* Set the subject of the message */
rc = RxVIMSetMessageHeader(Message, 'VIMSEL_SUBJECT', 'This will be the subject')

/* NOTE:                                                   */
/* Message will be discarded, since the program is closing */
/* the session without processing the message              */

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8.4. RxVIMSetMessageRecipient ΓòÉΓòÉΓòÉ

The RxVIMSetMessageRecipient function adds values to the list of addressees for
the active message.


ΓòÉΓòÉΓòÉ 8.4.1. Syntax ΓòÉΓòÉΓòÉ

The RxVIMSetMessageRecipient function is called with eight parameters.  The
first parameter is the message handle. The second parameter is the selector for
the class of the recipient of the message.  The third parameter is the type of
recipient.

The recipient of the message can be specified in one of two ways, either a name
entry or an addressbook entry.  If both are specified, the VIM system will use
the addressbook entry only.  The fourth, fifth and sixth parameters are used to
specify a name entry.  The seventh and eighth parameters are used to specify an
adressbook entry.

The fourth paramter is the type of entity, the fifth paramter is the
addressbook for the entity, and the sixth parameter is the value of the entity.

To specify the recipient as an addressbook entry, the seventh paramter is the
type of address, and the eighth is the value of the entry.

call RxVIMSetMessageRecipient message,'selector','entity_type','','',,
                              'user_name','',''

or

rc = RxVIMSetMessageRecipient(message,'selector','entity_type','','',,
                              'user_name','','')

Listed below are the valid selectors to use to set message class attributes:

VIMSEL_TO                       Sets the recipient as a primary
                                addressee for the message.

VIMSEL_CC                       Sets the recipient to receive a
                                copy of the message.

VIMSEL_BCC                      Sets the recipient to receive
                                a copy of the message, and not
                                appear as a listed recipient.

Listed below are the valid selectors to use to set recipient type:

VIMSEL_ENTITY                   Sets the type to a person entity

VIMSEL_GROUP                    Sets the type to a collection of
                                entities.

VIMSEL_UNKNOWN_RECIP_TYPE       Sets the type to unknown.


ΓòÉΓòÉΓòÉ 8.4.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSetMessageRecipient function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSetMessageRecipient:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_INVALID_SELECTOR         The selector passed is not valid
        VIMSTS_NAME_NOT_FOUND           The name passed was not found
        VIMSTS_WRITE_FAILURE            Could not write to the disk


ΓòÉΓòÉΓòÉ 8.4.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSetMessageRecipient */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Create a new message */
rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')

/* Set the message to send back to creator id */
rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
                              'Mark Stevens','','')

/* NOTE:                                                   */
/* Message will be discarded, since the program is closing */
/* the session without processing the message              */

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8.5. RxVIMSetMessageItem ΓòÉΓòÉΓòÉ

The RxVIMSetMessageItem function adds an item to the list of attachments for
the active message.  This function allows items such as text, file attachments,
etc. to be added to the content of the current message.


ΓòÉΓòÉΓòÉ 8.5.1. Syntax ΓòÉΓòÉΓòÉ

The RxVIMSetMessageItem function is called with seven parameters.  The first
parameter is the message handle. The second parameter is the selector for the
class of the item being added to the message.  The third parameter is the type
of the item being added to the message.  The fourth paramter is a selector
value to set flags for the message item if it is a file attachment.  The fifth
parameter is the name of the message item. For note parts, this will be the
title of the item.  For file attachments, this will be the name that is used to
specify the attachment.

An item being added to a message can be specified in one of two ways, either by
passing the contents of the item, or a filename.

To specify the item contents directly, the sixth parameter is used to pass the
contents.  If the item will be specified as a file, the sixth parameter should
be set to NULL.

To specify the item as a file, the seventh parameter is the name of the file.
If the item will be passed directly, this parameter should be set to NULL.

call RxVIMSetMessageItem message,'selector','item_type','flag','title',,
                              'content_buffer','filename'

or

call RxVIMSetMessageItem(message,'selector','item_type','flag','title',,
                              'content_buffer','filename')

Listed below are the valid selectors to use to set item class attributes:

VIMSEL_NOTE_PART                Sets the item as part of a text note

VIMSEL_ATTACH                   Sets the item as an attachment, item
                                type is ignored

VIMSEL_APP_DEFINED              Sets the item to be determined by
                                the application

Listed below are the valid selectors to use to set item type:

VIM_TEXT                        Sets the type to ASCII text

VIM_UNWRAPPED_TEXT              Sets the type to unwrapped text which
                                terminates each paragraph with CR/LF.

VIM_RTF                         Sets the type to Microsoft rich-text

VIM_STYLED                      Sets the type to Macintosh text

VIM_FAX                         Sets the type to PCX-format fax image

VIM_PICT                        Sets the type to Macintosh picture

VIM_MOVIE                       Sets the type to QuickTime sound/video

VIM_IMAGE                       Sets the type to Macintosh-fax-image

Listed below are the valid selectors to use to set item flag attributes:

VIMSEL_NATIVE                   Flag to indicate that file is in the
                                native format of the system

VIMSEL_APPLESINGLE              Flag to indicate that file is in the
                                Apple stream format


ΓòÉΓòÉΓòÉ 8.5.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSetMessageItem function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSetMessageItem:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_ATTACHMENT_NOT_FOUND     File attachment not avialable
        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_INVALID_SELECTOR         The selector passed is not valid
        VIMSTS_OPEN_FAILURE             Cannot open specified file
        VIMSTS_READ_FAILURE             Cannot read from the disk
        VIMSTS_UNSUP_TYPE               Type value unknown
        VIMSTS_WRITE_FAILURE            Could not write to the disk


ΓòÉΓòÉΓòÉ 8.5.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSetMessageItem */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Create a new message */
rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')

/* Add text to the message */
rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
         'Test Text','Hey!  This is text passed directly....', '')

/* NOTE:                                                   */
/* Message will be discarded, since the program is closing */
/* the session without processing the message              */

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8.6. RxVIMSendMessage ΓòÉΓòÉΓòÉ

The RxVIMSendMessage function submits the active message to the VIM system for
processing and closes the message.


ΓòÉΓòÉΓòÉ 8.6.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMSendMessage is called with the message handle to send.

call RxVIMSendMessage Message

or

rc = RxVIMSendMessage( Message )


ΓòÉΓòÉΓòÉ 8.6.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSendMessage function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSendMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Invalid parameter
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_NOT_SUPPORTED            Callbacks not supported
        VIMSTS_WRITE_FAILURE            Could not write to the disk


ΓòÉΓòÉΓòÉ 8.6.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSendMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')

/* Create a new message for composition */
rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')

/* Set the message to send back to creator id */
rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
                              'Mark Stevens','','')

/* Add text to the message */
rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
         'Test Text','Hey!  This is text passed directly....', '')

/* Send the message */
rc = RxVIMSendMessage( Message )

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 8.7. RxVIMCloseMessage ΓòÉΓòÉΓòÉ

The RxVIMCloseMessage function closes the active message and frees any
associated resources.  If the message type is not VIMSEL_DRAFT, the message is
discarded.  VIMSEL_DRAFT messages are saved for later retrieval as a draft
message.


ΓòÉΓòÉΓòÉ 8.7.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCloseMessage is called with the message handle to close.

call RxVIMCloseMessage Message

or

rc = RxVIMCloseMessage( Message )


ΓòÉΓòÉΓòÉ 8.7.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCloseMessage function returns the following values:

        0 - Successful session termination

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCloseMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_INVALID_OBJECT           The message handle is bad


ΓòÉΓòÉΓòÉ 8.7.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCloseMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', "Sess')

/* Create a new message for composition */
rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')

/* Set the message to send back to creator id */
rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
                              'Mark Stevens','','')

/* Add text to the message */
rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
         'Test Text','Hey!  This is text passed directly....','')

/* Close the message without sending .... message will be discarded */
rc = RxVIMCloseMessage( Message )

/* Closing the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9. Message Container Functions ΓòÉΓòÉΓòÉ

This section describes each of the functions available in the RexxVIM product
that address message container features.


ΓòÉΓòÉΓòÉ 9.1. RxVIMOpenMessageContainer ΓòÉΓòÉΓòÉ

The RxVIMOpenMessageContainer function opens the specified message container
with the VIM system.


ΓòÉΓòÉΓòÉ 9.1.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenMessageContainer is called with three parameters. The first parameter
is the session to be used to open the message container. The second is the name
of the message container to open.  A null ('') for the name will cause the
system to open the default message container.  The third parameter is the
variable name for the call to return a pointer to the message container.

call RxVIMOpenMessageContainer Session, 'container', 'MsgPtr'

or

rc = RxVIMOpenMessageContainer(Session,'container','MsgPtr')


ΓòÉΓòÉΓòÉ 9.1.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMOpenMessageContainer function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMOpenMessageContainer:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory to open container
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_NOT_SUPPORTED            Null container name not supported
        VIMSTS_OPEN_FAILURE             Container could not be opened


ΓòÉΓòÉΓòÉ 9.1.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenMessageContainer */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.2. RxVIMEnumerateMessages ΓòÉΓòÉΓòÉ

The RxVIMEnumerateMessages function retrieves specified information regarding
one or many messages in the container.  This function is used to obtain
reference pointers to messages in the container.  Once a pointer has been
retrieved for a message, that message can be deleted, filed in a folder, or
operated on using the message access functions.


ΓòÉΓòÉΓòÉ 9.2.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMEnumerateMessages is called with nine parameters. The first parameter is
the pointer to the open message container, which was returned from the open of
the container.

The second is a variable containing the starting position within the message
container.  To start at the beginning, the value of the variable should be set
to null ('').  For subsequent calls, this value will contain the return value
from the previous call.  This entry MUST be a variable name, since the function
returns the value of the next starting position.

The third parameter is the number of entries to skip before or after the
starting position.  To start at the beginning,and move forward, this should be
set to a value of 1.  To start at the end, and move in reverse, this should be
set to a value of -1.

The fourth parameter is a stem variable name that contains the number of
attributes to retrieve at the root, and a Selector and Buffer entry for each
attribute.  The Selector entry contains the selector to retrieve, and the
Buffer entry contains the name of the variable to return the values.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 2
      attrDesc.1.Selector = 'VIMSEL_REF'
      attrDesc.1.Buffer   = 'MsgRefNo'
      attrDesc.2.Selector = 'VIMSEL_SUBJECT'
      attrDesc.2.Buffer   = 'Subject'

The fifth parameter is a variable that contains the number of messages to read
for the call.  Upon return, the variable contains the number of messages
actually read.  This entry MUST be a variable name, since the function returns
the number of messages actually read.

The sixth parameter is a selector indicating the type of filtering to be done
on the messages prior to being included in the return information.  Filtering
can allow messages to be filtered based on subject, category, type of message,
or other values.  To return all messages in the container without filtering,
specify 'VIMSEL_NO_FILTER'. The seventh parameter is the value to be used for
filtering, if specified. If no filtering is indicated, this parameter should be
null ('').

The eighth parameter is used to specify flags to be used as extended filter
values.  To return all messages in the container, specify 'VIM_NO_FLAGS' for
this parameter.

The ninth parameter is the name of a variable to return a boolean value
indicating if additional messages exist in the message container.  This value
can be used to indicate that another call to RxVIMEnumerateMessages is
necessary to process remaining messages in the container.

Pos     = ''
Skipcnt = 1
Mcount  = 1
attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_REF'
attrDesc.1.Buffer   = 'MsgRefNo'
filter  = 'VIMSEL_NO_FILTER'
fdata   = ''
flags   = 'VIM_NO_FLAGS'
more    = ''



call RxVIMEnumerateMessages MsgCont,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,flags,'more'

or

rc = RxVIMEnumerateMessages(MsgCont,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,flags,'more')

Listed below are the valid selectors to use to request specific attributes to
be returned for each message:

VIMSEL_REF                      Retrieves the message reference value

VIMSEL_TYPE                     Retrieves the message type

VIMSEL_FROM_NAME                Retrieves the name of the sender

VIMSEL_SUBJECT                  Retrieves the subject of the message

VIMSEL_PRIORITY                 Retrieves the priority of the message

VIMSEL_MSG_LEN                  Retrieves the size of the message in bytes

VIMSEL_UNREAD_MAIL              Returns 'True' if messge is unread, or
                                'False' if it has been read

VIMSEL_ENCRYPT_WITH_KEY         Returns 'True' if messge was encrypted
                                or  'False' if it was not

Listed below are the valid selectors to use to request filtering for each
message (parameter five):

VIMSEL_TYPE                     Filter on the message type

                                   Pass one of following in filter data:

                                   VIM_MAIL  -  normal mail messages
                                   VIM_RTRC  -  return receipts requested
                                   VIM_DLR   -  delivery reports
                                   VIM_NDLR  -  non-delivery reports

                                   Notes also supports user-defined types.



VIMSEL_CATEGORY                 Filter on the message category or folder

                                   Pass name of category in filter data



VIMSEL_FROM                     Filter on the name of the sender

                                   Pass name of sender in filter data



VIMSEL_SENT                     Retrive messages from message log (ccMail only)

                                   Pass null ('') in filter data



VIMSEL_SUBJECT                  Filter on the subject of the message

                                   Pass subject in filter data

Listed below are the valid values for the enumeration flags for this function
(parameter eight):

VIM_NO_FLAGS                    Retrieve all messages

VIM_UNREADONLY                  Retrieve only unread messages

The function will return the requested attribute values in the specified buffer
as stem values with the following format:

         'Subject' specified to receive message subject
         5 messages are retreived

         Subject.0 = 5
         Subject.1 = 'Subject from first  message'
         Subject.2 = 'Subject from second message'
         Subject.3 = 'Subject from third  message'
         Subject.4 = 'Subject from fourth message'
         Subject.5 = 'Subject from fifth  message'


ΓòÉΓòÉΓòÉ 9.2.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMEnumerateMessages function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMEnumerateMessages:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL            Return buffer is too small
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_INVALID_SELECTOR         The requested selector is bad
        VIMSTS_READ_FAILURE             Error reading from disk


ΓòÉΓòÉΓòÉ 9.2.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMEnumerateMessages */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one message */
filter  = 'VIMSEL_NO_FILTER'              /* No filtering       */
fdata   = ''                              /* No filter data     */
flags   = 'VIM_NO_FLAGS'                  /* No flags           */
more = ''                                 /* more messages?     */

attrDesc.0 = 2                            /* retrieve 2 attributes    */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference value          */
attrDesc.1.Buffer   = 'refno'             /* buffer to return refno   */
attrDesc.2.Selector = 'VIMSEL_SUBJECT'    /* message subject          */
attrDesc.2.Buffer   = 'Subject'           /* buffer to return subject */


rc = RxVIMEnumerateMessages(MsgCont,'pos',skipcnt,'attrDesc','mcount',filter,,
                            fdata,flags,'more')

Say 'The first message has the following values'
Say
Say 'Message No -' refno.1
Say 'Subject    -' Subject.1


/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.3. RxVIMSetMessageCategory ΓòÉΓòÉΓòÉ

The RxVIMSetMessageCategory function creates the association of the message
with the specified category.  If the message is the first for a category, the
new folder is created.


ΓòÉΓòÉΓòÉ 9.3.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMSetMessageCategory is called with three parameters. The first parameter is
the pointer to the open message container, which was returned from the open of
the container. The second is the pointer to the message to act upon, which can
be retrieve by using the RxVIMEnumerateMessage function..  The third parameter
is the name of the category to add the message.

call RxVIMSetMessageCategory MsgCont, MsgtoAdd, 'Category Name'

or

rc = RxVIMSetMessageCategory(MsgCont, MsgtoAdd, 'Category Name')


ΓòÉΓòÉΓòÉ 9.3.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSetMessageCategory function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSetMessageCategory:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to disk


ΓòÉΓòÉΓòÉ 9.3.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSetMessageCategory */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Assign the first message to the Temporary folder */
rc = RxVIMSetMessageCategory(MsgCont,refno.1,'Temporary')

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.4. RxVIMRemoveMessageCategory ΓòÉΓòÉΓòÉ

The RxVIMRemoveMessageCategory function deletes the association of the message
from the specified category.  When the message has been removed from all
categories, the message itself will be deleted. If the message is the last in
the category, the folder itself will be deleted.


ΓòÉΓòÉΓòÉ 9.4.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMRemoveMessageCategory is called with three parameters. The first parameter
is the pointer to the open message container, which was returned from the open
of the container. The second is the pointer to the message to act upon, which
can be retrieve by using the RxVIMEnumerateMessage function..  The third
parameter is the name of the category from which to remove the message.

call RxVIMRemoveMessageCategory MsgCont, MsgtoDel, 'Category Name'

or

rc = RxVIMRemoveMessageCategory(MsgCont, MsgtoDel, 'Category Name')


ΓòÉΓòÉΓòÉ 9.4.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMRemoveMessageCategory function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMRemoveMessageCategory:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to disk


ΓòÉΓòÉΓòÉ 9.4.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMRemoveMessageCategory */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_CATEGORY',,
                            'Temporary','VIM_NO_FLAGS','more')

/* Delete the first message from the Temporary folder */
rc = RxVIMRemoveMessageCategory(MsgCont,refno.1,'Temporary')

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.5. RxVIMRemoveMessage ΓòÉΓòÉΓòÉ

The RxVIMRemoveMessage function deletes the specified message from the message
container.


ΓòÉΓòÉΓòÉ 9.5.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMRemoveMessage is called with two parameters. The first parameter is the
pointer to the open message container, which was returned from the open of the
container. The second is the pointer to the message to delete, which can be
retrieve by using the RxVIMEnumerateMessage function..

call RxVIMRemoveMessage MsgCont, MsgtoDel

or

rc = RxVIMRemoveMessage(MsgCont, MsgtoDel)


ΓòÉΓòÉΓòÉ 9.5.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMRemoveMessage function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMRemoveMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to disk


ΓòÉΓòÉΓòÉ 9.5.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMRemoveMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Delete the first message */
rc = RxVIMRemoveMessage(MsgCont,refno.1)

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.6. RxVIMQueryNewMessages ΓòÉΓòÉΓòÉ

The RxVIMQueryNewMessages function returns a value of True or False to indicate
if new messages are in the container.


ΓòÉΓòÉΓòÉ 9.6.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMQueryNewMessages is called with two parameters. The first parameter is the
pointer to the open message container, which was returned from the open of the
container. The second is the name of the variable to return the a boolean value
to indicate if new messages are in the container.

call RxVIMQueryNewMessages MsgCont, 'NewMsgs'

or

rc = RxVIMQueryNewMessages(MsgCont, 'NewMsgs')


ΓòÉΓòÉΓòÉ 9.6.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMQueryNewMessages function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMQueryNewMessages:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_READ_FAILURE             Error reading from disk


ΓòÉΓòÉΓòÉ 9.6.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMQueryNewMessages */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')



/* Check for new messages in container */
rc = RxVIMQueryNewMessages( MsgCont, 'NewMsgs' )

if NewMsgs = 'True'
   Say 'Your Inbox has new messages'
else
   Say 'Your Inbox does not have new messages'


/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.7. RxVIMQueryUnreadMailCount ΓòÉΓòÉΓòÉ

The RxVIMQueryUnreadMailCount function returns the number of new messages in
the message container.


ΓòÉΓòÉΓòÉ 9.7.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMQueryUnreadMailCount is called with two parameters. The first parameter is
the pointer to the open message container, which was returned from the open of
the container. The second is the name of the variable to return the count
value.

call RxVIMQueryUnreadMailCount MsgCont, 'msgcount'

or

rc = RxVIMQueryUnreadMailCount(MsgCont, 'msgcount')


ΓòÉΓòÉΓòÉ 9.7.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMQueryUnreadMailCount function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMQueryUnreadMailCount:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_READ_FAILURE             Error reading from disk
        VIMSTS_NOT_SUPPORTED            This function is not supported


ΓòÉΓòÉΓòÉ 9.7.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMQueryUnreadMailCount */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')



/* Retrieve the number of new messages in container */
rc = RxVIMQueryUnreadMailCount( MsgCont, 'NewMsgs' )

Say 'Your Inbox has' NewMsgs 'new messages'



/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 9.8. RxVIMCloseMessageContainer ΓòÉΓòÉΓòÉ

The RxVIMCloseMessageContainer function closes the specified message container
with the VIM system.


ΓòÉΓòÉΓòÉ 9.8.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCloseMessageContainer is called with one parameter. The parameter is the
variable which contains a pointer to the message container to close.  The
pointer to the message container is returned from the call to
RxVIMOpenMessageContainer.

call RxVIMCloseMessageContainer MsgCont

or

rc = RxVIMCloseMessageContainer( MsgCont )


ΓòÉΓòÉΓòÉ 9.8.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCloseMessageContainer function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCloseMessageContainer:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_INVALID_OBJECT           The container handle is bad


ΓòÉΓòÉΓòÉ 9.8.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCloseMessageContainer */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10. Message Access and Attribute Functions ΓòÉΓòÉΓòÉ

This section describes each of the functions available in the RexxVIM product
that address message access and attribute features.


ΓòÉΓòÉΓòÉ 10.1. RxVIMOpenMessage ΓòÉΓòÉΓòÉ

The RxVIMOpenMessage function opens the specified message with the VIM system.
After the message has been opened, the other message functions can be used for
further message processing.


ΓòÉΓòÉΓòÉ 10.1.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenMessage is called with four parameter. The first parameter is the
variable which contains a pointer to the open message container.  The second
parameter is the reference number of the message to open, which can be
retrieved from the RxVIMEnumerateMessages function. The third parameter is the
explicit key to use if the message is encrypted or NULL ('') if it is not
encrypted.  The fourth parameter is the name of the variable to return the
pointer to the message.

call RxVIMOpenMessage MsgCont, MsgRef, '', 'MsgPtr'

or

rc = RxVIMOpenMessage( MsgCont, MsgRef, '', 'MsgPtr' )


ΓòÉΓòÉΓòÉ 10.1.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMOpenMessage function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMOpenMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message reference is bad
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_READ_FAILURE             Error reading from the disk


ΓòÉΓòÉΓòÉ 10.1.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')


/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')


/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.2. RxVIMMarkMessageAsRead ΓòÉΓòÉΓòÉ

The RxVIMMarkMessageAsRead function changes the status on the specified message
to read.


ΓòÉΓòÉΓòÉ 10.2.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMMarkMessageAsRead is called with two parameter. The first parameter is the
variable which contains a pointer to the open message container.  The second
parameter is the variable which contains a pointer to the open message.

call RxVIMMarkMessageAsRead MsgCont, MsgPtr

or

rc = RxVIMMarkMessageAsRead( MsgCont, MsgPtr )


ΓòÉΓòÉΓòÉ 10.2.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMMarkMessageAsRead function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMMarkMessageAsRead:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message reference is bad
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 10.2.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMMarkMessageAsRead */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')


/* Mark the first message as read */
rc = RxVIMMarkMessageAsRead(MsgCont,MsgPtr)


/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.3. RxVIMGetMessageHeader ΓòÉΓòÉΓòÉ

The RxVIMGetMessageHeader function retrieves one or more attributes from the
header of the specified message.


ΓòÉΓòÉΓòÉ 10.3.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMGetMessageHeader is called with two parameter. The first parameter is the
name of the variable that contains a pointer to the message.  The second is the
variable name of the stem variable of attributes to retrieve.

attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_TYPE'
attrDesc.1.Buffer   = 'MsgType'

call RxVIMGetMessageHeader MsgPtr, 'attrDesc'

or

rc = RxVIMGetMessageHeader( MsgPtr, 'attrDesc' )

Listed below are the valid selectors to use to request specific attributes to
be returned for each message:

VIMSEL_TYPE                     Retrieves the message type

VIMSEL_FROM_NAME                Retrieves the name of the sender

VIMSEL_SUBJECT                  Retrieves the subject of the message

VIMSEL_SUBJECT_LEN              Retrieves the length of the subject of the message

VIMSEL_PRIORITY                 Retrieves the priority of the message

VIMSEL_MSG_LEN                  Retrieves the size of the message in bytes

VIMSEL_RETURN_RECEIPT           Returns 'True' if messge was requested upon opening
                                or  'False' if it was not


ΓòÉΓòÉΓòÉ 10.3.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMGetMessageHeader function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMGetMessageHeader:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message reference is bad
        VIMSTS_BUF_TOO_SMALL            The return buffer is too small
        VIMSTS_INVALID_OBJECT           The container handle is bad
        VIMSTS_INVALID_SELECTOR         Unknown selector value
        VIMSTS_NOT_SUPPORTED            Selector is not supported


ΓòÉΓòÉΓòÉ 10.3.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMGetMessageHeader */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')


/* Retrieve two attributes of the message header */
attrHead.0 = 2
attrHead.1.Selector = 'VIMSEL_FROM_NAME'
attrHead.1.Buffer   = 'from'
attrHead.2.Selector = 'VIMSEL_MSG_LEN'
attrHead.2.Buffer   = 'MsgLength'

rc = RxVIMGetMessageHeader(MsgPtr,'attrHead')

Say 'The message from' from ' is' MsgLength 'bytes in size'



/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.4. RxVIMEnumerateMessageItem ΓòÉΓòÉΓòÉ

The RxVIMEnumerateMessageItems function retrieves specified information
regarding one or many items in a specific message.  This function is used to
obtain reference pointers to message items in the message.  Once a pointer has
been retrieved for a message item, that item can be accessed individually.


ΓòÉΓòÉΓòÉ 10.4.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMEnumerateMessageItems is called with eight parameters. The first parameter
is the pointer to the open message, which was returned from RxVIMOpenMessage.

The second is a variable containing the starting position within the message .
To start at the beginning, the value of the variable should be set to null
('').  For subsequent calls, this value will contain the return value from the
previous call.  This entry MUST be a variable name, since the function returns
the value of the next starting position.

The third parameter is the number of entries to skip before or after the
starting position.  To start at the beginning,and move forward, this should be
set to a value of 1.  To start at the end, and move in reverse, this should be
set to a value of -1.

The fourth parameter is a variable that contains the number of message items to
read for the call.  Upon return, the variable contains the number of messages
actually read.  This entry MUST be a variable name, since the function returns
the number of messages actually read.

The fifth parameter is a stem variable name that will contain the results of
the call.  Upon return, the stem variable will contain the class, type, title,
path, size, and reference number for each item retrieved. An example of a
return stem variable 'ItemDesc' for the first message item is:

     ItemDesc.1.CLASS         /* Contains the class of the item */
     ItemDesc.1.TYPE          /* Contains the type of the item  */
     ItemDesc.1.NAME          /* Contains the name of the item  */
     ItemDesc.1.SIZE          /* Contains size of item in bytes */
     ItemDesc.1.REF           /* Reference number of the item   */

The sixth parameter is a selector indicating the type of filtering to be done
on the messages prior to being included in the return information.  Filtering
can allow messages to be filtered based on subject, category, type of message,
or other values.  To return all messages in the container without filtering,
specify 'VIMSEL_NO_FILTER'. The seventh parameter is the value to be used for
filtering, if specified. If no filtering is indicated, this parameter should be
null ('').

The eighth parameter is the name of a variable to return a boolean value
indicating if additional messages exist in the message container.  This value
can be used to indicate that another call to RxVIMEnumerateMessageItems is
necessary to process remaining messages in the container.

Pos     = ''
Skipcnt = 1
Mcount  = 1
attrDesc = ''
filter  = 'VIMSEL_NO_FILTER'
fdata   = ''
more    = ''


call RxVIMEnumerateMessageItems MsgCont,'Pos',Skipcnt,'MCount','attrDesc',filter,fdata,'more'

or

rc = RxVIMEnumerateMessageItems(MsgCont,'Pos',Skipcnt,'MCount','attrDesc',filter,fdata,'more')

Listed below are the valid selectors to use to request filtering for each
message (parameter five):

VIMSEL_CLASS                    Filter on the message item class

                                   Pass one of following in filter data:

                                   VIMSEL_NOTE_PART  - text portion of message
                                   VIMSEL_ATTACH     - message attachments
                                   VIMSEL_NESTED_MSG - nested message items


ΓòÉΓòÉΓòÉ 10.4.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMEnumerateMessageItems function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMEnumerateMessageItems:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL            Return buffer is too small
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_NOT_SUPPORTED            The filter selector is not supported


ΓòÉΓòÉΓòÉ 10.4.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMEnumerateMessageItems */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one message */
filter  = 'VIMSEL_NO_FILTER'              /* No filtering       */
fdata   = ''                              /* No filter data     */
flags   = 'VIM_NO_FLAGS'                  /* No flags           */
more = ''                                 /* more messages?     */

attrDesc.0 = 2                            /* retrieve 2 attributes    */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference value          */
attrDesc.1.Buffer   = 'refno'             /* buffer to return refno   */
attrDesc.2.Selector = 'VIMSEL_SUBJECT'    /* message subject          */
attrDesc.2.Buffer   = 'Subject'           /* buffer to return subject */


rc = RxVIMEnumerateMessages(MsgCont,'pos',skipcnt,'attrDesc','mcount',filter,,
                            fdata,flags,'more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')


/* Retrieve the first text message item from the first message */
ipos     = ''
iskip    = 1
icount   = 1
ifilter  = 'VIMSEL_CLASS'
ifdata   = 'VIMSEL_NOTE_PART'
imore    = ''
attrItem = ''

rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
                            ifdata,'imore')

Say 'The first text message item of the first message'
Say 'has the following details'
Say
Say '    Item Class  -' attrItem.1.CLASS
Say '    Item Type   -' attrItem.1.TYPE
Say '    Item Name   -' attrItem.1.NAME
Say '    Item Size   -' attrItem.1.SIZE
Say '    Item Ref No -' attrItem.1.REF



/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.5. RxVIMGetMessageItem ΓòÉΓòÉΓòÉ

The RxVIMGetMessageItem function reads a message item into a buffer or file.


ΓòÉΓòÉΓòÉ 10.5.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMGetMessageItem is called with five parameters. The first parameter is the
variable which contains a pointer to the open message.  The second parameter is
the reference number of the item to retrieve.  The third parameter is the
desired type for the message item.  The fourth parameter is a flag to control
output file formats.

The fifth parameter is a stem variable that contains the buffer name or the
filespec for the message to be stored.  The stem variable has three components,
the name of the buffer, the size of the buffer, and the name of the file.  If a
filename is specified, the buffer variable is ignored.  The size of the buffer
will control the amount of information returned from the item, up to a maximum
size of 4096.  Size will be updated on return to indicate the actual amount
read from the message item.

BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
BufDesc.Size      = 256                /* Size of return buffer */
BufDesc.FileName  = ''                 /* NULL for filename     */


call RxVIMGetMessageItem MsgPtr, MsgItemRef, 'Text Type', 'VIMSEL_NATIVE', 'BufDesc'

or

rc = RxVIMGetMessageItem( MsgPtr, MsgItemRef, 'Text Type', 'VIMSEL_NATIVE', 'BufDesc' )

Listed below are the valid types to use to request message conversion
(parameter three):

VIM_TEXT                    Convert the message to ASCII text (from VIM_RTF)

VIM_RTF                     Convert the message to Rich Text Format (from VIM_TEXT)

Listed below are the valid selectores to use to request specific file output
types (parameter four):

VIMSEL_NATIVE               The output file will be written in the Operating
                            System's format.  (Extended attributes will be
                            maintained.

VIMSEL_APPLESINGLE          The output file will be written in stream format.


ΓòÉΓòÉΓòÉ 10.5.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMGetMessageItem function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMGetMessageItem:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message pointer is bad
        VIMSTS_CONV_NOT_SUPPORTED       Specified conversion not valid
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_INVALID_SELECTOR         The flags value is not correct
        VIMSTS_READ_FAILURE             Error reading from the disk
        VIMSTS_UNSUP_TYPE               The flags type is not correct
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 10.5.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMGetMessageItem */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')

/* Retrieve the first text message item from the first message */
ipos     = ''
iskip    = 1
icount   = 1
ifilter  = 'VIMSEL_CLASS'
ifdata   = 'VIMSEL_NOTE_PART'
imore    = ''
attrItem = ''

rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
                            ifdata,'imore')


/* Store the message item in a Rexx variable */
BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
BufDesc.Size      = 2048               /* Size of return buffer */
BufDesc.FileName  = ''                 /* NULL for filename     */

rc = RxVIMGetMessageItem( MsgPtr, attrItem.1.REF, '', '', 'BufDesc')

/* Display first 60 characters of the message item */
Say 'First 60 characters of the message item'
Say SUBSTR(ItemText,1,60)


/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.6. RxVIMOpenMessageItem ΓòÉΓòÉΓòÉ

The RxVIMOpenMessageItem function opens a message item in preparation for other
actions.


ΓòÉΓòÉΓòÉ 10.6.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenMessageItem is called with five parameters. The first parameter is the
variable which contains a pointer to the open message.  The second parameter is
the reference number of the item to retrieve.  The third parameter is the
desired type for the message item.  The fourth parameter is a flag to control
output file formats. The fifth parameter is a variable which will contain a
pointer to the message item.

call RxVIMGetMessageItem MsgPtr, MsgItemRef, 'Text Type', 'VIMSEL_NATIVE', 'MsgItemPtr'

or

rc = RxVIMGetMessageItem( MsgPtr, MsgItemRef, 'Text Type', 'VIMSEL_NATIVE', 'MsgItemPtr' )

Listed below are the valid types to use to request message conversion
(parameter three):

VIM_TEXT                    Convert the message to ASCII text (from VIM_RTF)

VIM_RTF                     Convert the message to Rich Text Format (from VIM_TEXT)

Listed below are the valid selectores to use to request specific file output
types (parameter four):

VIMSEL_NATIVE               The output file will be written in the Operating
                            System's format.  (Extended attributes will be
                            maintained.

VIMSEL_APPLESINGLE          The output file will be written in stream format.


ΓòÉΓòÉΓòÉ 10.6.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMGetMessageItem function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMGetMessageItem:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message pointer is bad
        VIMSTS_CONV_NOT_SUPPORTED       Specified conversion not valid
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_INVALID_SELECTOR         The flags value is not correct
        VIMSTS_READ_FAILURE             Error reading from the disk
        VIMSTS_UNSUP_TYPE               The flags type is not correct
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 10.6.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenMessageItem */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')

/* Retrieve the first text message item from the first message */
ipos     = ''
iskip    = 1
icount   = 1
ifilter  = 'VIMSEL_CLASS'
ifdata   = 'VIMSEL_NOTE_PART'
imore    = ''
attrItem = ''

rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
                            ifdata,'imore')


/* Open the message item */
rc = RxVIMOpenMessageItem( MsgPtr, attrItem.1.REF, '', '', 'MsgItemPtr')



/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.7. RxVIMReadMessageItem ΓòÉΓòÉΓòÉ

The RxVIMReadMessageItem function reads a message item into a buffer in
sections.


ΓòÉΓòÉΓòÉ 10.7.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMReadMessageItem is called with two parameters. The first parameter is the
variable which contains a pointer to the open message item.

The second parameter is a stem variable that contains the buffer name for the
message to be stored.  The stem variable has three components, the name of the
buffer, the size of the buffer, and the offset. The size of the buffer will
control the amount of information returned from the item, up to a maximum size
of 4096.  Size will be updated on return to indicate the actual amount read
from the message item.  The offset is updated on return to indicate the
location within the message item.  When offset equals the size of the item, the
entire item has been read.

BufDesc.Buffer    = 'ItemText'         /* Return buffer name           */
BufDesc.Size      = 256                /* Size of return buffer        */
BufDesc.Offset    = 0                  /* Offset into the message item */

call RxVIMReadMessageItem MsgItemPtr, 'BufDesc'

or

rc = RxVIMReadMessageItem( MsgItemPtr, 'BufDesc' )


ΓòÉΓòÉΓòÉ 10.7.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMReadMessageItem function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMReadMessageItem:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message item pointer is bad
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message item handle is bad
        VIMSTS_READ_FAILURE             Error reading from the disk
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 10.7.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMReadMessageItem */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')

/* Retrieve the first text message item from the first message */
ipos     = ''
iskip    = 1
icount   = 1
ifilter  = 'VIMSEL_CLASS'
ifdata   = 'VIMSEL_NOTE_PART'
imore    = ''
attrItem = ''

rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
                            ifdata,'imore')


/* Open the message item */
rc = RxVIMOpenMessageItem( MsgPtr, attrItem.1.REF, '', '', 'MsgItemPtr')


/* Store the first 2K of message item in a Rexx variable */
BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
BufDesc.Size      = 2048               /* Size of return buffer */
BufDesc.Offset    = 0

rc = RxVIMReadMessageItem( MsgItemPtr, 'BufDesc')

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.8. RxVIMCloseMessageItem ΓòÉΓòÉΓòÉ

The RxVIMCloseMessageItem function closes a message item that has been opened
for action.


ΓòÉΓòÉΓòÉ 10.8.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCloseMessageItem is called with one parameter. The parameter is the
variable which contains a pointer to the open message item.

call RxVIMCloseMessageItem MsgItemPtr

or

rc = RxVIMCloseMessageItem( MsgItemPtr )


ΓòÉΓòÉΓòÉ 10.8.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCloseMessageItem function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCloseMessageItem:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_INVALID_OBJECT           The message item handle is bad


ΓòÉΓòÉΓòÉ 10.8.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCloseMessageItem */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')

/* Retrieve the first text message item from the first message */
ipos     = ''
iskip    = 1
icount   = 1
ifilter  = 'VIMSEL_CLASS'
ifdata   = 'VIMSEL_NOTE_PART'
imore    = ''
attrItem = ''

rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
                            ifdata,'imore')

/* Open the message item */
rc = RxVIMOpenMessageItem( MsgPtr, attrItem.1.REF, '', '', 'MsgItemPtr')



/* Close the message item */
rc = RxVIMCloseMessageItem( MsgItemPtr )


/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.9. RxVIMEnumerateMessageRecipients ΓòÉΓòÉΓòÉ

The RxVIMEnumerateMessageRecipients function retrieves one or more recipients
of the specified message.


ΓòÉΓòÉΓòÉ 10.9.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMEnumerateMessageRecipients is called with seven parameters. The first
parameter is the pointer to the open message, which was returned from the open
of the message.

The second parameter is a selector that indicates the type of recipients to
retrieve.

The third is a variable containing the starting position within the message
recipients.  To start at the beginning, the value of the variable should be set
to null ('').  For subsequent calls, this value will contain the return value
from the previous call.  This entry MUST be a variable name, since the function
returns the value of the next starting position.

The fourth parameter is the number of entries to skip before or after the
starting position.  To start at the beginning,and move forward, this should be
set to a value of 1.  To start at the end, and move in reverse, this should be
set to a value of -1.

The fifth parameter is a stem variable name that contains the number of
attributes to retrieve at the root, and a Selector and Buffer entry for each
attribute.  The Selector entry contains the selector to retrieve, and the
Buffer entry contains the name of the variable to return the values.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 1
      attrDesc.1.Selector = 'VIMSEL_NAME'
      attrDesc.1.Buffer   = 'Name'

The sixth parameter is a variable that contains the number of recipients to
read for the call.  Upon return, the variable contains the number of recipients
actually read.  This entry MUST be a variable name, since the function returns
the number of recipients actually read.

The seventh parameter is the name of a variable to return a boolean value
indicating if additional recipients exist for this message.  This value can be
used to indicate that another call to RxVIMEnumerateRecipients is necessary to
process remaining recipients for this message.

Pos     = ''
Skipcnt = 1
Mcount  = 1
Rtype   = 'VIMSEL_TO'
attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_NAME'
attrDesc.1.Buffer   = 'Name'
more    = ''



call RxVIMEnumerateMessageRecipients Message,Rtype,'Pos',Skipcnt,'attrDesc','MCount','more'

or

rc = RxVIMEnumerateMessageRecipients( Message,Rtype,'Pos',Skipcnt,'attrDesc','MCount','more' )

Listed below are the valid selectors to use to specify the type of recipients
to retrieve:

VIMSEL_TO                       Retrieves recipients on the TO list

VIMSEL_CC                       Retrieves recipients on the CC list

VIMSEL_BCC                      Retrieves recipients on the BCC list

Listed below are the valid selectors to use to specific information from the
call:

VIMSEL_NAME                     Return the name of the recipient

VIMSEL_FAILURE_REASON           Return the reason a delivery failed

VIMSEL_FAN                      Return the Foreign Alias Name for this
                                recipient, used in gateway applications

VIMSEL_RECIP_STATUS             Return True if message has been delivered
                                or False if it has not been delivered

The function will return the requested attribute values in the specified buffer
as stem values with the following format:

         'Name' specified to receive recipient name
         5 messages are retreived

         Name.0 = 5
         Name.1 = 'Name of the first  recipient'
         Name.2 = 'Name of the second recipient'
         Name.3 = 'Name of the third recipient'
         Name.4 = 'Name of the fourth recipient'
         Name.5 = 'Name of the fifth recipient'


ΓòÉΓòÉΓòÉ 10.9.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMEnumerateMessageRecipients function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMEnumerateMessageRecipients:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL            Return buffer is too small
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_INVALID_SELECTOR         The requested type is bad


ΓòÉΓòÉΓòÉ 10.9.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMEnumerateMessageRecipientss */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one message */
filter  = 'VIMSEL_NO_FILTER'              /* No filtering       */
fdata   = ''                              /* No filter data     */
flags   = 'VIM_NO_FLAGS'                  /* No flags           */
more = ''                                 /* more messages?     */

attrDesc.0 = 2                            /* retrieve 2 attributes    */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference value          */
attrDesc.1.Buffer   = 'refno'             /* buffer to return refno   */
attrDesc.2.Selector = 'VIMSEL_SUBJECT'    /* message subject          */
attrDesc.2.Buffer   = 'Subject'           /* buffer to return subject */

rc = RxVIMEnumerateMessages(MsgCont,'pos',skipcnt,'attrDesc','mcount',filter,,
                            fdata,flags,'more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','Message')



/* Retrieve the name of the first recipient on the TO list */

mpos = ''                                  /* Start at beginning   */
mskipcnt = 1                               /* Start at beginning   */
mcount  = 1                                /* Return one recipient */
more = ''                                  /* more recipients?     */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* recipient name           */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateMessageRecipients(Message,'VIMSEL_TO','mpos',mskipcnt,'attrDesc',,
                                     'mcount','more')

Say 'The name of the first recipient is' name.1




/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.10. RxVIMOpenNestedMessage ΓòÉΓòÉΓòÉ

The RxVIMOpenNestedMessage function opens the specified nested message with the
VIM system.  After the message has been opened, the other message functions can
be used for further message processing.  A nested message is one that has been
created with RxVIMCreateNestedMessage.  By opening the message as a nested
message, the history can be reviewed at that particular point.


ΓòÉΓòÉΓòÉ 10.10.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenNestedMessage is called with three parameter. The first parameter is
the variable which contains a pointer to the open message containing a nested
message.  The second parameter is the reference number of the nested message to
open.  The third parameter is the name of the variable to return the pointer to
the nested message.

call RxVIMOpenNestedMessage Message, MsgRef, 'NestMsgPtr'

or

rc = RxVIMOpenNestedMessage( Message, MsgRef, 'NestMsgPtr' )


ΓòÉΓòÉΓòÉ 10.10.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMOpenNestedMessage function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMOpenNestedMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The message reference is bad
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_NOT_SUPPORTED            This function is not supported


ΓòÉΓòÉΓòÉ 10.10.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenNestedMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')


/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')


/* Enumerate the nested message items */
ipos     = ''
iskip    = 1
icount   = 1
ifilter  = 'VIMSEL_CLASS'
ifdata   = 'VIMSEL_NESTED_MSG'
imore    = ''
attrItem = ''

rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
                            ifdata,'imore')

/* THIS EXAMPLE ASSUMES THAT THE FIRST MESSAGE IN THE INBOX CONTAINS */
/* NESTED MESSAGES.  THIS EXAMPLE WILL FAIL IF THE FIRST MESSAGE     */
/* DOES NOT CONTAIN NESTED MESSAGES                                  */



/* Open the first occurance of nesting in message */
rc = RxVIMOpenNestedMessage(MsgPtr,attrItem.1.REF,'NestMsgPtr')



/* Close the specified message */
rc = RxVIMCloseMessage( NestMsgPtr )

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.11. RxVIMExtractMessage ΓòÉΓòÉΓòÉ

The RxVIMExtractMessage function moves the message from the message container
into a file.


ΓòÉΓòÉΓòÉ 10.11.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMExtractMessage is called with three parameter. The first parameter is the
name of the variable that contains a pointer to the message.  The second
parameter are control flags for the extract. The third is the filespec of the
file into which the message will be extracted.

call RxVIMExtractMessage MsgPtr, 'flags', 'file_name'

or

rc = RxVIMExtractMessage( MsgPtr, 'flags', 'file_name' )

Listed below are the valid types to use to specify extraction options:

VIM_NO_FLAGS                    No extract options

VIM_EXTRACT_REF                 Extract only reference information,
                                not the actual message


ΓòÉΓòÉΓòÉ 10.11.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMExtractMessage function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMExtractMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                The filespec is bad
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The message handle is bad
        VIMSTS_NOT_SUPPORTED            Flag value is not supported
        VIMSTS_OPEN_FAILURE             The file could not be opened
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 10.11.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMExtractMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Open the default message container (Inbox) */
rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')

/* Retrieve the first message from the container pulling the */
/* message reference number only                             */
attrDesc.0 = 1
attrDesc.selector = 'VIMSEL_REF'
attrDesc.buffer   = 'refno'

rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
                            '','VIM_NO_FLAGS','more')

/* Open the first message */
rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')



/* Extract the message to a file */
path  = '\rexxvim\'
filename = 'message.dat'
filespec = path || filename

rc = RxVIMExtractMessage(MsgPtr,'VIM_NO_FLAGS',filespec)



/* Close the specified message */
rc = RxVIMCloseMessage( MsgPtr )

/* Close the specified message container */
rc = RxVIMCloseMessageContainer( MsgCont )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 10.12. RxVIMOpenExtractedMessage ΓòÉΓòÉΓòÉ

The RxVIMOpenExtractedMessage function opens the specified message which has
been previously extracted to a file. After the message has been opened, the
other message functions can be used for further message processing.


ΓòÉΓòÉΓòÉ 10.12.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenExtractedMessage is called with three parameter. The first parameter
is the variable which contains a pointer to the current VIM session.  The
second parameter is the filespec for the extracted message to open.  The third
parameter is the name of the variable to return the pointer to the message.

call RxVIMOpenExtractedMessage Session, 'file_name', 'MsgPtr'

or

rc = RxVIMOpenExtractedMessage( Session, 'file_name', 'MsgPtr' )


ΓòÉΓòÉΓòÉ 10.12.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMOpenExtractedMessage function returns the following values:

        0 - Successful function return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMOpenExtractedMessage:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                File name is bad
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_OPEN_FAILURE             File could not be opened
        VIMSTS_READ_FAILURE             Error reading from the disk


ΓòÉΓòÉΓòÉ 10.12.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenExtractedMessage */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs

/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')



/* Open an extracted message */
path  = '\rexxvim\'
filename = 'message.dat'
filespec = path || filename

rc = RxVIMOpenMessage(Sess,filespec,'MsgPtr')



/* Close the message */
rc = RxVIMCloseMessage( MsgPtr )

/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11. Address Book Functions ΓòÉΓòÉΓòÉ

This section describes each of the functions available in the RexxVIM product
that address address book RexxVIM features.


ΓòÉΓòÉΓòÉ 11.1. RxVIMEnumerateAddressBooks ΓòÉΓòÉΓòÉ

The RxVIMEnumerateAddressBooks function retrieves one or more attributes about
the address books available in the current session.


ΓòÉΓòÉΓòÉ 11.1.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMEnumerateAddressBooks is called with six parameters. The first parameter
is the pointer to the current session.

The second is a variable containing the starting position within the address
book list.  To start at the beginning, the value of the variable should be set
to null ('').  For subsequent calls, this value will contain the return value
from the previous call.  This entry MUST be a variable name, since the function
returns the value of the next starting position.

The third parameter is the number of entries to skip before or after the
starting position.  To start at the beginning,and move forward, this should be
set to a value of 1.  To start at the end, and move in reverse, this should be
set to a value of -1.

The fourth parameter is a stem variable name that contains the number of
attributes to retrieve at the root, and a Selector and Buffer entry for each
attribute.  The Selector entry contains the selector to retrieve, and the
Buffer entry contains the name of the variable to return the values.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 1
      attrDesc.1.Selector = 'VIMSEL_NAME'
      attrDesc.1.Buffer   = 'Name'

The fifth parameter is a variable that contains the number of address books to
read for the call.  Upon return, the variable contains the number of address
books actually read.  This entry MUST be a variable name, since the function
returns the number of address books actually read.

The sixth parameter is the name of a variable to return a boolean value
indicating if additional address books exist in this session.  This value can
be used to indicate that another call to RxVIMEnumerateAddressBooks is
necessary to process remaining address books.

Pos     = ''
Skipcnt = 1
Mcount  = 1
attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_NAME'
attrDesc.1.Buffer   = 'Name'
more    = ''


call RxVIMEnumerateAddressBooks Session,'Pos',Skipcnt,'attrDesc','MCount','more'

or

rc = RxVIMEnumerateAddressBooks( Session,'Pos',Skipcnt,'attrDesc','MCount','more' )

Listed below are the valid selectors to use to retrieve specific information
from the call:

VIMSEL_NAME                     Return the name of the address book

VIMSEL_TYPE                     Return the type of the address book

                                   Return values will be:

                                   VIMSEL_CCMAIL
                                   VIMSEL_MHS
                                   VIMSEL_MSGMGR
                                   VIMSEL_NOTES
                                   VIMSEL_OCE
                                   VIMSEL_X500

VIMSEL_DISPLAY_NAME             Return the name used to display the
                                address book (same as VIMSEL_NAME
                                for ccMail)

VIMSEL_ENTRY_NUMBER             Return the number for this entry

VIMSEL_TOTAL_ENTRIES            Return the total number of address books

The function will return the requested attribute values in the specified buffer
as stem values with the following format:

         'Name' specified to receive recipient name
         5 messages are retreived

         Name.0 = 5
         Name.1 = 'Name of the first  address book'
         Name.2 = 'Name of the second address book'
         Name.3 = 'Name of the third address book'
         Name.4 = 'Name of the fourth address book'
         Name.5 = 'Name of the fifth address book'


ΓòÉΓòÉΓòÉ 11.1.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMEnumerateAddressBooks function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMEnumerateAddressBooks:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL            Return buffer is too small
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_INVALID_SELECTOR         One of the request selectors is bad


ΓòÉΓòÉΓòÉ 11.1.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMEnumerateAddressBooks */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

Say 'The name of the first address book is' name.1


/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.2. RxVIMOpenAddressBook ΓòÉΓòÉΓòÉ

The RxVIMOpenAddressBook function opens the specified address book.  Once
opened, entries from the address book can be accessed.


ΓòÉΓòÉΓòÉ 11.2.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMOpenAddressBook is called with three parameters. The first parameter is
the variable containing the pointer to the current session. The second
parameter is the name of the address book to open, which can be retrieved with
a call to RxVIMEnumerateAddressBooks.  The third is a variable which will
contain a pointer to the address book after it has been opened.

call RxVIMOpenAddressBook Session, 'Address Book", 'AddrBkPtr'

or

rc = RxVIMOpenAddressBook( Session, 'Address Book', 'AddrBkPtr' )


ΓòÉΓòÉΓòÉ 11.2.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMOpenAddressBook function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMOpenAddressBook:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The session handle is bad
        VIMSTS_NAME_NOT_FOUND           The address book could not be located


ΓòÉΓòÉΓòÉ 11.2.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMOpenAddressBook */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')



/* Open the first address book found */
rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.3. RxVIMSetCurrentSubtree ΓòÉΓòÉΓòÉ

The RxVIMSetCurrentSubtree function sets the root of the tree for all future
calls to the address book.  For flat address book models, such as cc:Mail and
Lotus Notes, this call has no effect.  It is included here for compatibility to
the VIM specification.


ΓòÉΓòÉΓòÉ 11.3.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMSetCurrentSubtree is called with three parameters. The first parameter is
the variable containing the pointer to the open address book. The second
parameter is a reference pointer to set the location of the subtree. The third
is the name of the subtree to set the root location.

call RxVIMSetCurrentSubtree AddrBkPtr, 'Subtree_Ref', 'Subtree Name'

or

rc = RxVIMSetCurrentSubtree( AddrBkPtr, 'Subtree_Ref', 'Subtree Name' )

Shown below are the valid entries for the subtree reference pointer:

VIM_ROOT_REF                  Set subtree to the root of the entry

VIM_PARENT_REF                Set subtree to the parent of the entry

NULL ('')                     Set the subtree to the beginning of the entry


ΓòÉΓòÉΓòÉ 11.3.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSetCurrentSubtree function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSetCurrentSubtree:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Ref/name not a valid entry


ΓòÉΓòÉΓòÉ 11.3.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSetCurrentSubtree */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first address book found */
rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')


/* NOTE: THIS CALL HAS NO EFFECT WHEN USED WITH CCMAIL OR LOTUS */
/*       NOTES.  IT IS INCLUDED FOR COMPATIBILITY WITH THE VIM  */
/*       SPECIFICATION ONLY.                                    */

/* Set the subtree to the beginning of the address book */
rc = RxVIMSetCurrentSubtree(AddrBkPtr, '', '')


/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.4. RxVIMGetCurrentSubtree ΓòÉΓòÉΓòÉ

The RxVIMGetCurrentSubtree function returns the current subtree in the address
book.  For flat address book models, such as cc:Mail and Lotus Notes, this call
has no effect.  It is included here for compatibility to the VIM specification.


ΓòÉΓòÉΓòÉ 11.4.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMGetCurrentSubtree is called with three parameters. The first parameter is
the variable containing the pointer to the open address book. The second
parameter is a variable to get the reference pointer of the subtree. The third
is the name of the variable to get the name of the subtree.

call RxVIMGetCurrentSubtree AddrBkPtr, 'Subtree_Ref', 'Subtree Name'

or

rc = RxVIMGetCurrentSubtree( AddrBkPtr, 'Subtree_Ref', 'Subtree Name' )

Shown below are the valid entries for the subtree reference pointer:


ΓòÉΓòÉΓòÉ 11.4.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMGetCurrentSubtree function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMGetCurrentSubtree:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Ref/name not a valid entry
        VIMSTS_BUF_TOO_SMALL            Buffer variable is too small


ΓòÉΓòÉΓòÉ 11.4.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMGetCurrentSubtree */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first address book found */
rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')



/* NOTE: THIS CALL HAS NO EFFECT WHEN USED WITH CCMAIL OR LOTUS */
/*       NOTES.  IT IS INCLUDED FOR COMPATIBILITY WITH THE VIM  */
/*       SPECIFICATION ONLY.                                    */

/* Set the subtree to the beginning of the address book */
rc = RxVIMGetCurrentSubtree(AddrBkPtr, 'SubRef', 'SubName')

Say 'Subtree name is' SubName



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.5. RxVIMEnumerateAddressBookEntries ΓòÉΓòÉΓòÉ

The RxVIMEnumerateAddressBookEntries function retrieves one or more attributes
about the entries in the current address book.


ΓòÉΓòÉΓòÉ 11.5.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMEnumerateAddressBookEntries is called with eight parameters. The first
parameter is a variable that contains the pointer to the current address book.

The second is a variable containing the starting position within the address
book entries.  To start at the beginning, the value of the variable should be
set to null ('').  For subsequent calls, this value will contain the return
value from the previous call.  This entry MUST be a variable name, since the
function returns the value of the next starting position.

The third parameter is the number of entries to skip before or after the
starting position.  To start at the beginning,and move forward, this should be
set to a value of 1.  To start at the end, and move in reverse, this should be
set to a value of -1.

The fourth parameter is a stem variable name that contains the number of
attributes to retrieve at the root, and a Selector and Buffer entry for each
attribute.  The Selector entry contains the selector to retrieve, and the
Buffer entry contains the name of the variable to return the values.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 2
      attrDesc.1.Selector = 'VIMSEL_NAME'
      attrDesc.1.Buffer   = 'Name'
      attrDesc.2.Selector = 'VIMSEL_REF'
      attrDesc.2.Buffer   = 'RefNo'

The fifth parameter is a variable that contains the number of address book
entries to read for the call.  Upon return, the variable contains the number of
address book entries actually read.  This entry MUST be a variable name, since
the function returns the number of address book entries actually read.

The sixth parameter is a selector indicating the type of filtering to be done
on the messages prior to being included in the return information.  Filtering
can allow messages to be filtered based on subject, category, type of message,
or other values.  To return all messages in the container without filtering,
specify 'VIMSEL_NO_FILTER'. The seventh parameter is the value to be used for
filtering, if specified. If no filtering is indicated, this parameter should be
null ('').

The eighth parameter is the name of a variable to return a boolean value
indicating if additional address books exist in this session.  This value can
be used to indicate that another call to RxVIMEnumerateAddressBookEntries is
necessary to process remaining address books.

Pos     = ''
Skipcnt = 1
Mcount  = 1
filter  = 'VIMSEL_NO_FILTER'
fdata   = ''
attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_NAME'
attrDesc.1.Buffer   = 'Name'
more    = ''


call RxVIMEnumerateAddressBookEntries AddrBkPtr,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,'more'

or

rc = RxVIMEnumerateAddressBookEntries( AddrBkPtr,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,'more' )

Listed below are the valid selectors to use to request specific attributes to
be returned for each entry:

VIMSEL_REF                      Retrieves the entry reference value

VIMSEL_TYPE                     Retrieves the message type

                                   VIMSEL_ENTITY   -  Individual entry
                                   VIMSEL_GROUP    -  collection of entries
                                   VIMSEL_SUBTREE  -  subtree entry


VIMSEL_NAME                     Retrieves the full name of the entry

VIMSEL_ADDRESS                  Retrieves the address of the entry

VIMSEL_COMMENTS                 Retrieves the comments for this entry

VIMSEL_ENTRY_NUMBER             Retrieves the entry number for the entry

VIMSEL_TOTAL_ENTRIES            Retrieves the total entries in the address book

VIMSEL_FAN                      Returns foreign alias name, which is used
                                in gateway applications

Listed below are the valid selectors to use to request filtering for each entry
(parameter six ):

VIMSEL_NO_FILTER                Return all entries

VIMSEL_ENTITY                   Return only individual entries

VIMSEL_GROUP                    Return only group entries (lists)

The function will return the requested attribute values in the specified buffer
as stem values with the following format:

         'Name' specified to receive address book entry name
         5 entries are retreived

         Name.0 = 5
         Name.1 = 'Name of the first  address book entry'
         Name.2 = 'Name of the second address book entry'
         Name.3 = 'Name of the third address book entry'
         Name.4 = 'Name of the fourth address book entry'
         Name.5 = 'Name of the fifth address book entry'


ΓòÉΓòÉΓòÉ 11.5.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMEnumerateAddressBookEntries function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMEnumerateAddressBookEntries:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_BUF_TOO_SMALL            Return buffer is too small
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_INVALID_SELECTOR         One of the request selectors is bad


ΓòÉΓòÉΓòÉ 11.5.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMEnumerateAddressBookEntries */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')



/* Retrieve the name of the first address book entry */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */
filter = 'VIMSEL_NO_FILTER'
fdata  = ''

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'Ename'             /* buffer to return name    */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')

Say 'The full name of the first entry is' Ename.1


/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.6. RxVIMCreateAddressBookEntry ΓòÉΓòÉΓòÉ

The RxVIMCreateAddressBookEntry function adds a new entry to the current
address book.  To add entries to the primary address book, the session must be
connected with the postoffice name and password.  Standard users can only
create entries in their private mailing lists.

IMPORTANT NOTE:  If this function is called attempting to add an entry to the
primary address book of a postoffice that is at the maximum number of local
users, the function will generate an exception in OS/2.  This function should
only be used with postoffices that have available users.


ΓòÉΓòÉΓòÉ 11.6.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCreateAddressBookEntry is called with three parameters. The first
parameter is a variable that contains the pointer to the current address book.

The second is a selector value of the type of entry to create.  For individual
entries this will be VIMSEL_ENTITY, and for group entries (lists) this will be
VIMSEL_GROUP.

The third parameter is a stem variable name that contains the number of
attributes to use for creation at the root, and a Selector and Value entry for
each attribute.  The Selector entry contains the selector to use in the create,
and the Value entry contains the information to use in the create.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 2
      attrDesc.1.Selector = 'VIMSEL_NAME'
      attrDesc.1.Value    = 'Mark Stevens'
      attrDesc.2.Selector = 'VIMSEL_COMMENTS'
      attrDesc.2.Value    = 'This entry created with RexxVIM'

attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_NAME'
attrDesc.1.Buffer   = 'Mark Stevens'


call RxVIMCreateAddressBookEntry AddrBkPtr,'VIMSEL_ENTITY','attrDesc'

or

rc = RxVIMCreateAddressBookEntry( AddrBkPtr,'VIMSEL_ENTITY','attrDesc' )

Listed below are the valid selectors to use to indicate specific attributes to
be set for the entry:

VIMSEL_NAME                     Provide the full name of the entry

VIMSEL_ADDRESS                  Provide the full address of the entry

VIMSEL_COMMENTS                 Provide free form comments for this entry

VIMSEL_PASSWORD                 Provide the password for the entry

VIMSEL_LOCATION                 Set the location using one of these selectors

                                   VIMSEL_LOCAL   - Add to the local postoffice (default)

                                   VIMSEL_DIALIN  - Will access the local postoffice
                                                    using dialin only

                                   VIMSEL_REMOTE  - User local on another postoffice

                                   VIMSEL_ALIAS   - Entry is an alias for another
                                                    local entry

                                   VIMSEL_DIRECT_POSTOFFICE  - Entry is a postoffice that
                                                               will directly connect

                                   VIMSEL_INDIRECT_POSTOFFICE- Entry is a postoffice that
                                                               will not direct connect


ΓòÉΓòÉΓòÉ 11.6.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCreateAddressBookEntry function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCreateAddressBookEntry:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
        VIMSTS_NAME_EXISTS              Name already exists in address book
        VIMSTS_UNSUP_TYPE               Entry type is not valid
        VIMSTS_WRITE_FAILURE            Error writing to the disk
        VIMSTS_NOT_SUPPORTED            Attribute not supported


ΓòÉΓòÉΓòÉ 11.6.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCreateAddressBookEntry */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')



/* Add a new name to the first address book entry */
attrDesc.0 = 1                            /* create with 1 attribute  */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of entry to add     */
attrDesc.1.Value    = 'Mark Stevens'      /* value to use for add     */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'VIMSEL_ENTITY',attrDesc')

Say attrDesc.1.Value 'has been added to the addressbook'



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.7. RxVIMMatchAddressBook ΓòÉΓòÉΓòÉ

The RxVIMMatchAddressBook function searches the specified address book for an
entry that matches the specified attributes.


ΓòÉΓòÉΓòÉ 11.7.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMMatchAddressBook is called with six parameters. The first parameter is a
variable that contains the pointer to the current address book. The second is a
selector value to indicate what attribute on which to match. The third
parameter is the information with which to perform the match. The fourth
parameter a selector value to indicate the type of matching to use. The fifth
parameter is a variable that contains the position to start the match.  To
begin the search at the beginning, the variable should be set to null (''). The
sixth parameter is a variable that will receive the enumeration number of the
entry being returned.

Pos   = ''
Enum  = ''
Attr  = 'VIMSEL_NAME'
type  = 'VIMSEL_FULL'
srch  = 'Mark Stevens'

call RxVIMMatchAddressBook AddrBkPtr,Attr,srch,type,'Pos','Enum'

or

rc = RxVIMMatchAddressBook( AddrBkPtr,Attr,srch,type,'Pos','Enum' )

Listed below are the valid selectors to use to indicate on what element the
match will occur:

VIMSEL_NAME                     Performs the match on the entry name

VIMSEL_FAN                      Performs the match on the foreign alias
                                name, which is used in gateway applications

Listed below are the valid selectors to use to indicate type of matching
(parameter four ):

VIMSEL_FULL                     Return only entries that fully match

VIMSEL_PARTIAL                  Return entries that match the partial string


ΓòÉΓòÉΓòÉ 11.7.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMMatchAddressBook function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMMatchAddressBook:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
        VIMSTS_NO_MATCH                 No entries match the search


ΓòÉΓòÉΓòÉ 11.7.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMMatchAddressBook */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')



/* Search for a name in the address book */
Pos   = ''
Enum  = ''
Attr  = 'VIMSEL_NAME'
type  = 'VIMSEL_FULL'
srch  = 'Mark Stevens'

rc = RxVIMMatchAddressBook( AddrBkPtr,Attr,srch,type,'Pos','Enum' )

if rc>0 then
  Say srch 'not found in addressbook'
else
  Say srch 'was found in addressbook at location' enum



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.8. RxVIMGetABEntryAttributes ΓòÉΓòÉΓòÉ

The RxVIMGetABEntryAttributes function retrieves one or more attributes about
the specified address book entry.


ΓòÉΓòÉΓòÉ 11.8.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMGetABEntryAttributes is called with four parameters. The first parameter
is a variable that contains the pointer to the current address book.

The second is a variable containing the reference number for the entry to
obtain attribute information.  If this value is set to null (''), the third
parameter is used to locate the entry.

The third parameter is the name of the entry to obtain attribute information.
This paramter is used if the Entry Reference number (parameter two) is null.

The fourth parameter is a stem variable name that contains the number of
attributes to retrieve at the root, and a Selector and Buffer entry for each
attribute.  The Selector entry contains the selector to retrieve, and the
Buffer entry contains the name of the variable to return the values.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 2
      attrDesc.1.Selector = 'VIMSEL_NAME'
      attrDesc.1.Buffer   = 'Name'
      attrDesc.2.Selector = 'VIMSEL_COMMENTS'
      attrDesc.2.Buffer   = 'Comments'

attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_NAME'
attrDesc.1.Buffer   = 'Name'


call RxVIMGetABEntryAttributes AddrBkPtr,EntryRef,'','attrDesc'

or

rc = RxVIMGetABEntryAttributes( AddrBkPtr,EntryRef,'','attrDesc' )

Listed below are the valid selectors to use to request specific attributes to
be returned for each entry:

VIMSEL_NAME                     Retrieves the full name of the entry

VIMSEL_ADDRESS                  Retrieves the address of the entry

VIMSEL_COMMENTS                 Retrieves the comments for this entry

VIMSEL_TYPE                     Retrieves the message type

                                   VIMSEL_ENTITY   -  Individual entry
                                   VIMSEL_GROUP    -  collection of entries
                                   VIMSEL_SUBTREE  -  subtree entry


VIMSEL_LOCATION                 Retrieves location using one of these selectors

                                   VIMSEL_LOCAL   - Add to the local postoffice (default)

                                   VIMSEL_DIALIN  - Will access the local postoffice
                                                    using dialin only

                                   VIMSEL_REMOTE  - User local on another postoffice

                                   VIMSEL_ALIAS   - Entry is an alias for another
                                                    local entry

                                   VIMSEL_DIRECT_POSTOFFICE  - Entry is a postoffice that
                                                               will directly connect

                                   VIMSEL_INDIRECT_POSTOFFICE- Entry is a postoffice that
                                                               will not direct connect

VIMSEL_FAN                      Returns foreign alias name, which is used
                                in gateway applications

The function will return the requested attribute values in the specified buffer
variable directly with the following format:

         'Name' specified to receive address book entry name

         Name  = 'Name of the address book entry'


ΓòÉΓòÉΓòÉ 11.8.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMGetABEntryAttributes function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMGetABEntryAttributes:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
        VIMSTS_NOT_SUPPORTED            Attribute not supported


ΓòÉΓòÉΓòÉ 11.8.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMGetABEntryAttributes */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')

/* Retrieve the name of the first address book entry */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */
filter = 'VIMSEL_NO_FILTER'
fdata  = ''

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')



/* Get the comment for the first address book entry */
ItemBuf.0 = 1
ItemBuf.1.Selector = 'VIMSEL_COMMENTS'
ItemBuf.1.Buffer   = 'comments'

rc = RxVIMGetABEntryAttributes(AddrBkPtr,RefNo.1,'','ItemBuf')

Say 'The comment for the first entry is' comments



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.9. RxVIMSetABEntryAttributes ΓòÉΓòÉΓòÉ

The RxVIMSetABEntryAttributes function changes one or more attributes of the
specified address book entry.


ΓòÉΓòÉΓòÉ 11.9.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMSetABEntryAttributes is called with four parameters. The first parameter
is a variable that contains the pointer to the current address book.

The second is a variable containing the reference number for the entry to
obtain attribute information.  If this value is set to null (''), the third
parameter is used to locate the entry.

The third parameter is the name of the entry to obtain attribute information.
This paramter is used if the Entry Reference number (parameter two) is null.

The fourth parameter is a stem variable name that contains the number of
attributes to change at the root, and a Selector and Value entry for each
attribute.  The Selector entry contains the selector to retrieve, and the Value
entry contains the information to use for the change.

An example of a properly formated attribute description buffer is shown below:

      attrDesc.0 = 2
      attrDesc.1.Selector = 'VIMSEL_NAME'
      attrDesc.1.Value    = 'Mark Stevens'
      attrDesc.2.Selector = 'VIMSEL_COMMENTS'
      attrDesc.2.Value    = 'This entry was changed using RexxVIM'

attrDesc.0 = 1
attrDesc.1.Selector = 'VIMSEL_NAME'
attrDesc.1.Value    = 'Mark Stevens'


call RxVIMSetABEntryAttributes AddrBkPtr,EntryRef,'','attrDesc'

or

rc = RxVIMSetABEntryAttributes( AddrBkPtr,EntryRef,'','attrDesc' )

Listed below are the valid selectors to use to request specific attributes to
be changed for the entry:

VIMSEL_NAME                     Changes the full name of the entry

VIMSEL_ADDRESS                  Changes the address of the entry

VIMSEL_COMMENTS                 Changes the comments for this entry

VIMSEL_COMMENTS                 Changes the password for this entry

VIMSEL_LOCATION                 Changes location using one of these selectors

                                   VIMSEL_LOCAL   - Add to the local postoffice (default)

                                   VIMSEL_DIALIN  - Will access the local postoffice
                                                    using dialin only

                                   VIMSEL_REMOTE  - User local on another postoffice

                                   VIMSEL_ALIAS   - Entry is an alias for another
                                                    local entry

                                   VIMSEL_DIRECT_POSTOFFICE  - Entry is a postoffice that
                                                               will directly connect

                                   VIMSEL_INDIRECT_POSTOFFICE- Entry is a postoffice that
                                                               will not direct connect

VIMSEL_FAN                      Changes foreign alias name, which is used
                                in gateway applications


ΓòÉΓòÉΓòÉ 11.9.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMSetABEntryAttributes function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMSetABEntryAttributes:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
        VIMSTS_NOT_SUPPORTED            Attribute not supported


ΓòÉΓòÉΓòÉ 11.9.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMSetABEntryAttributes */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')

/* Retrieve the name of the first address book entry */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */
filter = 'VIMSEL_NO_FILTER'
fdata  = ''

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')



/* Get the comment for the first address book entry */
ItemBuf.0 = 1
ItemBuf.1.Selector = 'VIMSEL_COMMENTS'
ItemBuf.1.Value    = 'This entry was updated using RexxVIM'

rc = RxVIMGetABEntryAttributes(AddrBkPtr,RefNo.1,'','ItemBuf')



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.10. RxVIMRemoveAddressBookEntry ΓòÉΓòÉΓòÉ

The RxVIMRemoveAddressBookEntry function deletes an address book entry from the
specified address book.


ΓòÉΓòÉΓòÉ 11.10.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMRemoveAddressBookEntry is called with three parameters. The first
parameter is a variable that contains the pointer to the current address book.

The second is a variable containing the reference number for the entry to
delete. If this value is set to null (''), the third parameter is used to
locate the entry to delete.

The third parameter is the name of the entry to delete. This paramter is used
if the Entry Reference number (parameter two) is null.

call RxVIMRemoveAddressBookEntry AddrBkPtr,EntryRef,''

or

rc = RxVIMRemoveAddressBookEntry( AddrBkPtr,EntryRef,'' )


ΓòÉΓòÉΓòÉ 11.10.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMRemoveAddressBookEntry function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMRemoveAddressBookEntry:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to disk


ΓòÉΓòÉΓòÉ 11.10.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMRemoveAddressBookEntry */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')

/* Retrieve the name of the first address book entry */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */
filter = 'VIMSEL_NO_FILTER'
fdata  = ''

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')



/* Delete the first entry from the first address book */
rc = RxVIMRemoveAddressBookEntry(AddrBkPtr,RefNo.1,'')



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.11. RxVIMAddGroupMember ΓòÉΓòÉΓòÉ

The RxVIMAddGroupMember function adds a new entry to an existing group list.
The group must have already been created, using the RxVIMCreateAddressBookEntry
prior to adding entries.


ΓòÉΓòÉΓòÉ 11.11.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMAddGroupMember is called with four parameters. The first parameter is a
variable that contains the pointer to the current address book.

The second is a variable containing the reference number for the group entry to
add the new entry.  If this value is set to null (''), the third parameter is
used to locate the entry.

The third parameter is the name of the group entry to add the new entry. This
paramter is used if the Entry Reference number (parameter two) is null.

The fourth parameter is a the name to add to the group.  This name must be an
existing entry in the address book.

call RxVIMAddGroupMember AddrBkPtr,EntryRef,'','Mark Stevens'

or

rc = RxVIMAddGroupMember( AddrBkPtr,EntryRef,'','Mark Stevens' )


ΓòÉΓòÉΓòÉ 11.11.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMAddGroupMember function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMAddGroupMember:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 11.11.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMAddGroupMember */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')

/* Retrieve the name of the first group entry in the address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */
filter = 'VIMSEL_GROUP'                   /* return only group entries */
fdata  = ''

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')



/* Add a new member to the first group in the address book */
rc = RxVIMAddGroupMember(AddrBkPtr,RefNo.1,'','Mark Stevens')



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.12. RxVIMRemoveGroupMember ΓòÉΓòÉΓòÉ

The RxVIMRemoveGroupMember function deletes an  entry from an existing group
list.


ΓòÉΓòÉΓòÉ 11.12.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMRemoveGroupMember is called with four parameters. The first parameter is a
variable that contains the pointer to the current address book.

The second is a variable containing the reference number for the group entry to
delete an entry.  If this value is set to null (''), the third parameter is
used to locate the entry.

The third parameter is the name of the group entry to delete the entry. This
paramter is used if the Entry Reference number (parameter two) is null.

The fourth parameter is a the name to delete from the group.

call RxVIMRemoveGroupMember AddrBkPtr,EntryRef,'','Mark Stevens'

or

rc = RxVIMRemoveGroupMember( AddrBkPtr,EntryRef,'','Mark Stevens' )


ΓòÉΓòÉΓòÉ 11.12.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMRemoveGroupMember function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMRemoveGroupMember:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_BAD_PARAM                Bad parameter passed to function
        VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
        VIMSTS_INVALID_OBJECT           The address book handle is bad
        VIMSTS_WRITE_FAILURE            Error writing to the disk


ΓòÉΓòÉΓòÉ 11.12.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMRemoveGroupMember */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')


/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first addressbook */
rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')

/* Retrieve the name of the first group entry in the address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */
filter = 'VIMSEL_GROUP'                   /* return only group entries */
fdata  = ''

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */

rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')



/* Delete an entry from the first group in the address book */
rc = RxVIMRemoveGroupMember(AddrBkPtr,RefNo.1,'','Mark Stevens')



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 11.13. RxVIMCloseAddressBook ΓòÉΓòÉΓòÉ

The RxVIMCloseAddressBook function closes the session with the specified
address book and frees any resources.


ΓòÉΓòÉΓòÉ 11.13.1. Syntax ΓòÉΓòÉΓòÉ

RxVIMCloseAddressBook is called with one parameter. The parameter is the
variable containing the pointer to the address book to close.

call RxVIMCloseAddressBook AddrBkPtr

or

rc = RxVIMCloseAddressBook( AddrBkPtr )


ΓòÉΓòÉΓòÉ 11.13.2. Return Codes ΓòÉΓòÉΓòÉ

The RxVIMCloseAddressBook function returns the following values:

        0 - Successful return

The return values from all of the function calls return a zero for success, and
non-zero for failure.  To retrieve the actual failure reason, use the
RxVIMStatus function.  The RxVIMStatus function converts the numeric return
value to the actual failure text.  Using RxVIMStatus, the following values may
be returned by RxVIMCloseAddressBook:

        VIMSTS_SUCCESS                  Successful return
        VIMSTS_FAILURE                  Function Failed

        VIMSTS_INVALID_OBJECT           The address book handle is bad


ΓòÉΓòÉΓòÉ 11.13.3. Example ΓòÉΓòÉΓòÉ

/* Example of using RxVIMCloseAddressBook */

/* The RxVIMLoadFuncs function loads all of the VIM extensions */
call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs


/* This will establish a connection to the VIM system */
rc = RxVIMInitialize()

/* Obtain the default session information */
rc = RxVIMDefaultSessionInfo('db_path', 'user_name')

Say 'Default path:' db_path
Say 'Default name:' user_name

/* Opening a session with the mail subsystem */
rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')

/* Retrieve the name of the first address book */
pos = ''                                  /* Start at beginning */
skipcnt = 1                               /* Start at beginning */
mcount  = 1                               /* Return one entry   */
more = ''                                 /* more entires?      */

attrDesc.0 = 1                            /* retrieve 1 attribute     */
attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
attrDesc.1.Buffer   = 'name'              /* buffer to return name    */

rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')

/* Open the first address book found */
rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')



/* Close the address book */
rc = RxVIMCloseAddressBook( AddrBkPtr )



/* Close the session with the mail subsystem */
rc = RxVIMCloseSession( Sess )

/* The RxVIMDropFuncs function unloads all of the VIM extensions */
call RxVIMDropFuncs


ΓòÉΓòÉΓòÉ 12. RexxVIM Examples ΓòÉΓòÉΓòÉ

Several examples are shown for using the many functions of RexxVIM in actual
Rexx programs.


ΓòÉΓòÉΓòÉ 12.1. General Demo ΓòÉΓòÉΓòÉ

 The general demo (DEMO.CMD) shows the proper loading of the RexxVIM functions,
connection to the VIM subsystem, querying session capabilities, opening a VIM
session, and querying the active session.  The example also shows the proper
unloading and shutdown of the VIM connections and sessions.

    Run DEMO.CMD


ΓòÉΓòÉΓòÉ 12.1.1. DEMO.CMD Listing ΓòÉΓòÉΓòÉ

/** RexxDemo **/
/******************************************/
/*                                        */
/* Command line syntax:                   */
/*                                        */
/* demo db_path user_password user_name   */
/*                                        */
/*                                        */
/******************************************/
ARG db_path user_pw user_name
'@echo off'
'@cls'
Say 'RexxVIM General Demonstration Program'
Say

/* unload functions upon error */
SIGNAL ON ERROR NAME done

/* Prompt for the parameters if not passed on the */
/* command line                                   */
if LENGTH(STRIP(db_path)) = 0 then do
   Say 'Enter Postoffice Directory -'
   PARSE PULL db_path .
   Say
   Say 'Enter User Name -'
   PARSE PULL user_name
   Say 'Enter Password -'
   PARSE PULL user_pw
end  /* Do */


/* Load the RexxVIM extensions to Rexx */
rc = RxFuncAdd('RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs')
if rc <> 0 then do
   Say
   Say 'RexxVIM failed to load, return code' rc
   Say
   Say 'Functions have been released.  Retry program.'
   signal done
end  /* Do */
call RxVIMLoadFuncs
Say 'Functions are now loaded'
Say


/* Initialize the VIM subsystem */
rc = RxVIMInitialize()
Say
Say '|-Call To Routine ---------------RC--|'
Say '  RxVIMInitialize-              ' rc
if (rc > 0) then call vimerr


/* Retrieve the default session info if present */
rc = RxVIMGetDefaultSessionInfo('def_path', 'def_user')
Say '  RxVIMGetDefaultSessionInfo -  ' rc
if (rc > 0) then call vimerr
Say '      Default Path -' def_path
Say '      Default Name -' def_user
Say


/* Query the maximum subject line length and maximum */
/* text length                                       */
rc = RxVIMQueryCapability('VIMSEL_MAX_SUBJECT_LEN','Query')
Say '  RxVIMQueryCapability -        ' rc
if (rc > 0) then call vimerr
Say '      Max Subject Length -' query
rc = RxVIMQueryCapability('VIMSEL_MAX_TEXT_LEN','Query')
if (rc > 0) then call vimerr
Say '         Max Text Length -' query
Say


/* Open a session with the postoffice using the parameters */
/* provided by the user                                    */
rc = RxVIMOpenSession(db_path,user_name,user_pw,'Session')
Say '  RxVIMOpenSession -            ' rc
if (rc > 0) then call vimerr


/* Retieve the name and type of active session */
rc = RxVIMGetEntityName(Session,'Entity')
Say '  RxVIMGetEntityName            ' rc
if (rc > 0) then call vimerr
Say '      Type -' entity.Type
Say '      Name -' entity.Name
Say


/* Close the session with the postoffice */
rc = RxVIMCloseSession(Session)
Say '  RxVIMCloseSession -            ' rc
if (rc > 0) then call vimerr


/* Terminate the active VIM subsystem connection */
rc = RxVIMTerminate()
Say '  RxVIMTerminate -               ' rc
if (rc > 0) then call vimerr
signal done


/***** VIMErr *******/

/* If an error occurs, this function will return the text */
/* associated with the error.  Extended text may be       */
/* displayed if it exists for the specified error.        */

VIMERR:

rc = RxVIMStatusText(rc,'Status')
Say
Say '|-Error Information -----------------|'
Say '  Error Text -' status.1
Say
if LENGTH(STRIP(status.2)) > 0 then
   Say '  Ext Status -' status.2
rc = RxVIMTerminate()
signal done


/* The done section will unload the RexxVIM extensions */
/* and exit the program                                */
DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit


ΓòÉΓòÉΓòÉ 12.2. Query Capabilities Demo ΓòÉΓòÉΓòÉ

 The Query Capabilities demo (VIMCAP.CMD) shows the use of the
RxVIMQueryCapability function to determine support in the underlying VIM
subsystem.  This demo can be used to query all selectors by using the command
word ALL, or will support a query of a single selector.  Launching the demo
below will query all selectors.

    Run VIMCAP.CMD


ΓòÉΓòÉΓòÉ 12.2.1. VIMCAP.CMD Listing ΓòÉΓòÉΓòÉ

/** Rexx Program to Query VIM Capabilities **/

/* The program accepts either a selector to query or */
/* the command word ALL to query all selectors       */
ARG TYPE

'@echo off'
'@cls'

/* Unload functions upon error */
SIGNAL ON ERROR NAME done

if LENGTH(STRIP(type)) = 0 then do
   Say
   Say 'Incorrect Syntax!  Correct syntax is -'
   Say
   Say 'VIMCAP < Capability to query | ALL'
   Say
   Say 'VIMCAP ALL will query all VIM functions'
   Say
   return
end  /* Do */

TYPE = TRANSLATE(STRIP(TYPE))
if TYPE = 'ALL' then do
  call LoadVIMCap
  doall = TRUE
end  /* Do */
else
  doall = FALSE

call RxFuncAdd 'RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs'
call RxVIMLoadFuncs
rc = RxVIMInitialize()
Say
Say '|-Capability----------------------Value------------------------------------|'

if doall = TRUE then do
   do count=1 to vimcap.0
      TYPE = TRANSLATE(STRIP(vimcap.count))
      rc = RxVIMQueryCapability(TYPE,'Query')
   if rc>0 then signal VIMERR
      Say ' 'LEFT(TYPE||'-',30)'  ' SUBSTR(Query.1,1,30)
   end /* do */
end  /* Do */
else do
   rc = RxVIMQueryCapability(TYPE,'Query')
   if rc>0 then signal VIMERR
   Say ' 'LEFT(TYPE||'-',30)'  ' SUBSTR(Query.1,1,30)
   Say
end  /* Do */

rc = RxVIMTerminate()
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|--------------------------------------------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit

/***** VIMErr *******/
VIMERR:

rc = RxVIMStatusText(rc,'Status')
Say
Say '|-Error Information -----------------|'
Say '  Error Text -' status.1
Say
if LENGTH(STRIP(status.2)) > 0 then
   Say '  Ext Status -' status.2
rc = RxVIMTerminate()

DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit

/****** Load all VIM Capabilities into stem variable *****/
LOADVIMCAP:

vimcap.0    =  32
vimcap.1    =  "VIMSEL_VERSION"
vimcap.2    =  "VIMSEL_IMPLEMENTATION"
vimcap.3    =  "VIMSEL_IMPLEMENTATION_VERSION"
vimcap.4    =  "VIMSEL_PRODUCT"
vimcap.5    =  "VIMSEL_MAX_SUBJECT_LEN"
vimcap.6    =  "VIMSEL_MAX_TYPE_LEN"
vimcap.7    =  "VIMSEL_MAX_TEXT_LEN"
vimcap.8    =  "VIMSEL_RTF"
vimcap.9    =  "VIMSEL_FAX"
vimcap.10   =  "VIMSEL_STYLED"
vimcap.11   =  "VIMSEL_PICT"
vimcap.12   =  "VIMSEL_MOVIE"
vimcap.13   =  "VIMSEL_IMAG"
vimcap.14   =  "VIMSEL_UNWRAPPED_TEXT"
vimcap.15   =  "VIMSEL_ALL_NOTE_PARTS_SUPP"
vimcap.16   =  "VIMSEL_ATTACH_TYPE_SUPP"
vimcap.17   =  "VIMSEL_ATTACH_DIRS"
vimcap.18   =  "VIMSEL_ENCRYPT"
vimcap.19   =  "VIMSEL_ENCRYPT_WITH_KEY"
vimcap.20   =  "VIMSEL_SIGN"
vimcap.21   =  "VIMSEL_NSTD_DERIVED_REPLIES"
vimcap.22   =  "VIMSEL_NSTD_DERIVED_FORWRDS"
vimcap.23   =  "VIMSEL_CP850"
vimcap.24   =  "VIMSEL_CP1252"
vimcap.25   =  "VIMSEL_CP437"
vimcap.26   =  "VIMSEL_LMBCS"
vimcap.27   =  "VIMSEL_ISTRING"
vimcap.28   =  "VIMSEL_UNICODE"
vimcap.29   =  "VIMSEL_APPLESINGLE"
vimcap.30   =  "VIMSEL_PATH_REQUIRED"
vimcap.31   =  "VIMSEL_NAME_REQUIRED"
vimcap.32   =  "VIMSEL_PASS_REQUIRED"
return


ΓòÉΓòÉΓòÉ 12.3. Send Message Demo ΓòÉΓòÉΓòÉ

 The Send Message (MESSAGE.CMD) demo shows how RexxVIM can be used to create
and send messages.  Launching the demo below will send a message back to the
person that is logged into the postoffice.  The message will contain a text
portion, and a file attachment.

    Run MESSAGE.CMD


ΓòÉΓòÉΓòÉ 12.3.1. MESSAGE.CMD Listing ΓòÉΓòÉΓòÉ

/** Message.cmd **/
/*********************************************/
/*                                           */
/* Command line syntax:                      */
/*                                           */
/* message db_path user_password user_name   */
/*                                           */
/*                                           */
/*********************************************/
ARG db_path user_pw user_name
'@echo off'
'@cls'
Say 'RexxVIM Message Demonstration Program'
Say

/* Unload functions upon error */
SIGNAL ON ERROR NAME done

/* Prompt for the parameters if not passed on the */
/* command line                                   */
if LENGTH(STRIP(db_path)) = 0 then do
   Say 'Enter Postoffice Directory -'
   PARSE PULL db_path .
   Say
   Say 'Enter User Name -'
   PARSE PULL user_name
   Say 'Enter Password -'
   PARSE PULL user_pw
end  /* Do */


/* Load the RexxVIM extensions to Rexx */
rc = RxFuncAdd('RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs')
if rc <> 0 then do
   Say
   Say 'RexxVIM failed to load, return code' rc
   Say
   Say 'Functions have been released.  Retry program.'
   signal done
end  /* Do */
call RxVIMLoadFuncs
Say 'Functions are now loaded'
Say


/* Initialize the VIM subsystem */
rc = RxVIMInitialize()
Say
Say '|-Call To Routine ---------------RC--|'
Say '  RxVIMInitialize -              ' rc
if (rc > 0) then call vimerr



/* Open a session with the postoffice using the parameters */
/* provided by the user                                    */
rc = RxVIMOpenSession(db_path,user_name,user_pw,'Session')
Say '  RxVIMOpenSession -             ' rc
if (rc > 0) then call vimerr


/* Create a new message of type VIM_MAIL */
rc = RxVIMCreateMessage(Session,'VIM_MAIL','Message')
Say '  RxVIMCreateMessage -           ' rc
if (rc > 0) then call vimerr


/* Set the header text */
hdrtext = user_name"'s config.sys file"
rc = RxVIMSetMessageHeader(Message,'VIMSEL_SUBJECT', hdrtext)
Say '  RxVIMSetMessageHeader -        ' rc
if (rc > 0) then call vimerr


/* Set the priority to high */
rc = RxVIMSetMessageHeader(Message,'VIMSEL_PRIORITY', 'VIM_HIGH_PRIORITY')
Say '  RxVIMSetMessageHeader -        ' rc
if (rc > 0) then call vimerr


/* Set the recipient to the user that is logged on */
/* This will send the message back to ourselves    */
rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
                user_name,'','')
Say '  RxVIMSetMessageRecipient -     ' rc
if (rc > 0) then call vimerr


/* Add some text to the message */
itemtxt = 'This message was created using the RexxVIM !!'
rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
         'Message Demo',itemtxt,'')
Say '  RxVIMSetMessageItem -          ' rc
if (rc > 0) then call vimerr


/* Add the config.sys as a file attachment in the message */
drive = STRIP('c: ')
rc = RxVIMSetMessageItem(Message,'VIMSEL_ATTACH','VIM_TEXT','VIMSEL_NATIVE',,
         'config.sys','',drive'\config.sys')
Say '  RxVIMSetMessageItem -          ' rc
if (rc > 0) then call vimerr


/* Send the message */
rc = RxVIMSendMessage(Message)
Say '  RxVIMSendMessage -             ' rc
if (rc > 0) then call vimerr


/* Close the session with the postoffice */
rc = RxVIMCloseSession(Session)
Say '  RxVIMCloseSession -            ' rc
if (rc > 0) then call vimerr


/* Terminate the active VIM subsystem connection */
rc = RxVIMTerminate()
Say '  RxVIMTerminate -               ' rc
if (rc > 0) then call vimerr
signal done


/***** VIMErr *******/

/* If an error occurs, this function will return the text */
/* associated with the error.  Extended text may be       */
/* displayed if it exists for the specified error.        */

VIMERR:

rc = RxVIMStatusText(rc,'Status')
Say
Say '|-Error Information -----------------|'
Say '  Error Text -' status.1
Say
Say '  Ext Status -' status.2
rc = RxVIMTerminate()
signal done


/* The done section will unload the RexxVIM extensions */
/* and exit the program                                */
DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit


ΓòÉΓòÉΓòÉ 12.4. Message Container Demo ΓòÉΓòÉΓòÉ

 The Message Container (MSGCONT.CMD) demo shows how RexxVIM can be used to open
and read message containers, like the Inbox.  Launching the demo below will
retrieve each message from the Inbox, and allow it to be deleted, stored in a
folder, or left in the Inbox.

    Run MSGCONT.CMD


ΓòÉΓòÉΓòÉ 12.4.1. MESSAGE.CMD Listing ΓòÉΓòÉΓòÉ

/** Msgcont.cmd **/
/*********************************************/
/*                                           */
/* Command line syntax:                      */
/*                                           */
/* msgcont db_path user_password user_name   */
/*                                           */
/*                                           */
/*********************************************/
ARG db_path user_pw user_name
'@echo off'
'@cls'
Say 'RexxVIM Message Container Demonstration Program'
Say

/* Unload functions upon error */
SIGNAL ON ERROR NAME done

/* Prompt for the parameters if not passed on the */
/* command line                                   */
if LENGTH(STRIP(db_path)) = 0 then do
   Say 'Enter Postoffice Directory -'
   PARSE PULL db_path .
   Say
   Say 'Enter User Name -'
   PARSE PULL user_name
   Say 'Enter Password -'
   PARSE PULL user_pw
end  /* Do */


/* Load the RexxVIM extensions to Rexx */
rc = RxFuncAdd('RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs')
if rc <> 0 then do
   Say
   Say 'RexxVIM failed to load, return code' rc
   Say
   Say 'Functions have been released.  Retry program.'
   signal done
end  /* Do */
call RxVIMLoadFuncs
Say 'Functions are now loaded'
Say


/* Initialize the VIM subsystem */
rc = RxVIMInitialize()
if (rc > 0) then call vimerr

/* Open a session with the postoffice using the parameters */
/* provided by the user                                    */
rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
if (rc > 0) then call vimerr


/* Open the default message container -- Inbox */
rc = RxVIMOpenMessageContainer(Session,'','Inbox')
if (rc > 0) then call vimerr


/* Query the message container for new mail */
rc = RxVIMQueryNewMessages(Inbox,'New_Mail')
if (rc > 0) then call vimerr
Say '      New Mail Flag is' New_Mail


/* Query the number of new messages */
rc = RxVIMQueryUnreadMailCount(Inbox,'Unread_Count')
if (rc > 0) then call vimerr
Say '   Number of unread messages is' Unread_Count
Say


/* Display all mail in Inbox if unread messages exist */

if New_Mail = 'True' then do

     Say 'To review all mail in Inbox,'
     'pause'

     /* Enumerate messages in container -- Inbox */
     pos = ''                           /* Start at the beginning of the container */
     skipcnt = 1                        /* Move forward through the container one at a time */
     mcount  = 1                        /* Retrieve 1 message for each call */
     filter  = 'VIMSEL_NO_FILTER'       /* No filter, return all messages in inbox */
     fdata   = ''                       /* No filter data */
     flags   = 'VIM_NO_FLAGS'           /* No enumeration flags, return all messages in inbox */
     more    = ''                       /* Set the value of more to nul */
     action  = 'N'                      /* Set the value of repeat loop indicator to N */

     AttrDesc.0 = 2                          /* Retrieve 2 attributes for each message */
     AttrDesc.1.Selector = 'VIMSEL_REF'      /* 1st attribute is the message reference number */
     AttrDesc.1.Buffer   = 'MsgRefNo'        /* store results in this stem variable */
     AttrDesc.2.Selector = 'VIMSEL_SUBJECT'  /* 2nd attribute is the message subject */
     AttrDesc.2.Buffer   = 'Subject'         /* store results in this stem variable */

     do until TRANSLATE(SUBSTR(action,1,1)) = 'X'

          /* Continue retrieving message info until user enters N */

          rc = RxVIMEnumerateMessages(Inbox,'pos',skipcnt,'AttrDesc','mcount',filter,fdata,flags,'more')
          if (rc > 0) then call vimerr

          /* Display results */
         'cls'
          Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
          Say
          Say 'Message Container Demo'
          Say
          Say '-----------------------------------------------------------'
          Say '    Message =' MsgRefNo.1
          Say '    Subject =' Subject.1
          Say '-----------------------------------------------------------'
          Say
          Say
          Say 'Select an action for this message'
          Say
          Say '   D - Delete message'
          Say '   F - File message in a folder'
          Say '   N - Go to next message, leave this one in the Inbox'
          Say '   X - Exit demo now'
          Say
          Say 'Enter your selection below -'
          PULL action
          if more = 'False' then do
             Say 'All messages have been retrieved'
             action = 'X'
          end  /* Do */

          /* Process the selection entered.  X will fall through the select statement */
          select
             when TRANSLATE(SUBSTR(action,1,1)) = 'D' then do
                /* Delete message */
                rc = RxVIMRemoveMessage(Inbox,MsgRefNo.1)
                if (rc > 0) then call vimerr
           end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'F' then do
                /* File message in folder */
                Say 'Enter the name of the folder -'
                PULL category
                 rc = RxVIMSetMessageCategory(Inbox,MsgRefNo.1,category)
                if (rc > 0) then call vimerr
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
                /* Go to the next message */
                /* Nothing to do.....loop will pull next message */
             end  /* Do */
          otherwise
          end  /* select */
     end /* do */
end  /* Do */


/* Close the message container -- Inbox */
rc = RxVIMCloseMessageContainer(Inbox)
if (rc > 0) then call vimerr


/* Close the session with the postoffice */
rc = RxVIMCloseSession(Session)
if (rc > 0) then call vimerr


/* Terminate the active VIM subsystem connection */
rc = RxVIMTerminate()
if (rc > 0) then call vimerr
signal done


/***** VIMErr *******/

/* If an error occurs, this function will return the text */
/* associated with the error.  Extended text may be       */
/* displayed if it exists for the specified error.        */

VIMERR:

erc = RxVIMStatusText(Session,rc,'Status')
Say
Say '|-Error Information -----------------|'
Say '  Error Text -' status.1
Say
Say '  Ext Status -' status.2
rc = RxVIMTerminate()
signal done


/* The done section will unload the RexxVIM extensions */
/* and exit the program                                */
DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit


ΓòÉΓòÉΓòÉ 12.5. Message Access Demo ΓòÉΓòÉΓòÉ

 The Message Access (MSGACTS.CMD) demo shows how RexxVIM can be used to open
and read messages.  Launching the demo below will actions to be performed on
the messages in the Inbox.

    Run MSGACTS.CMD


ΓòÉΓòÉΓòÉ 12.5.1. MSGACTS.CMD Listing ΓòÉΓòÉΓòÉ

/** Msgacts.cmd **/
/*********************************************/
/*                                           */
/* Command line syntax:                      */
/*                                           */
/* msgacts db_path user_password user_name   */
/*                                           */
/*                                           */
/*********************************************/
ARG db_path user_pw user_name
'@echo off'
'@cls'
Say 'RexxVIM Message Access Demonstration Program'
Say

/* Unload the function upon error */
SIGNAL ON ERROR NAME done

/* Prompt for the parameters if not passed on the */
/* command line                                   */
if LENGTH(STRIP(db_path)) = 0 then do
   Say 'Enter Postoffice Directory -'
   PARSE PULL db_path .
   Say
   Say 'Enter User Name -'
   PARSE PULL user_name
   Say 'Enter Password -'
   PARSE PULL user_pw
end  /* Do */


/* Load the RexxVIM extensions to Rexx */
rc = RxFuncAdd('RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs')
if rc <> 0 then do
   Say
   Say 'RexxVIM failed to load, return code' rc
   Say
   Say 'Functions have been released.  Retry program.'
   signal done
end  /* Do */
call RxVIMLoadFuncs
Say 'Functions are now loaded'
Say


/* Initialize the VIM subsystem */
rc = RxVIMInitialize()
if (rc > 0) then call vimerr


/* Open a session with the postoffice using the parameters */
/* provided by the user                                    */
rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
if (rc > 0) then call vimerr


/* Open the default message container -- Inbox */
rc = RxVIMOpenMessageContainer(Session,'','Inbox')
if (rc > 0) then call vimerr


/* Display all messages in Inbox if they exist */

     /* Enumerate messages in container -- Inbox */
     pos = ''                           /* Start at the beginning of the container */
     skipcnt = 1                        /* Move forward through the container one at a time */
     mcount  = 1                        /* Retrieve 1 message for each call */
     filter  = 'VIMSEL_NO_FILTER'       /* No filter, return all messages in inbox */
     fdata   = ''                       /* No filter data */
     flags   = 'VIM_NO_FLAGS'           /* No enumeration flags, return all messages in inbox */
     more    = ''                       /* Set the value of more to nul */
     action  = 'N'                      /* Set the value of repeat loop indicator to N */

     AttrDesc.0 = 3                               /* Retrieve 3 attributes for each message */
     AttrDesc.1.Selector = 'VIMSEL_REF'           /* 1st attribute is the message reference number */
     AttrDesc.1.Buffer   = 'MsgRefNo'             /* store results in this stem variable */
     AttrDesc.2.Selector = 'VIMSEL_SUBJECT'       /* 2nd attribute is the message subject */
     AttrDesc.2.Buffer   = 'Subject'              /* store results in this stem variable */
     AttrDesc.3.Selector = 'VIMSEL_UNREAD_MAIL'   /* 3rd attribute is if unread */
     AttrDesc.3.Buffer   = 'Unread'               /* store results in this stem variable */

     do until TRANSLATE(SUBSTR(action,1,1)) = 'X'

          /* Continue retrieving message info until user enters N */

          rc = RxVIMEnumerateMessages(Inbox,'pos',skipcnt,'AttrDesc','mcount',filter,fdata,flags,'more')
          if (rc > 0) then call vimerr

          /* Display results */
         'cls'
          Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
          Say
          Say 'Message Container Demo'
          Say
          Say '--------------------------------------------------------'
          Say '    Message =' MsgRefNo.1
          Say '    Subject =' Subject.1
          Say '    Unread  =' Unread.1
          Say '--------------------------------------------------------'
          Say
          Say 'Select an action for this message'
          Say
          Say '   D - Delete message'
          Say '   F - File message in a folder'
          Say '   N - Go to next message, leave this one in the Inbox'
          Say '   M - Mark message as read'
          Say '   H - Display message header info'
          Say '   I - Display message items'
          Say '   T - Display the first 60 characters of first message item'
          Say '   X - Exit demo now'
          Say
          Say 'Enter your selection below -'
          PULL action

          /* Process the selection entered.  X will fall through the select statement */
          select
             when TRANSLATE(SUBSTR(action,1,1)) = 'D' then do
                /* Delete message */
                rc = RxVIMRemoveMessage(Inbox,MsgRefNo.1)
                if (rc > 0) then call vimerr
           end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'F' then do
                /* File message in folder */
                Say 'Enter the name of the folder-'
                PULL category
                 rc = RxVIMSetMessageCategory(Inbox,MsgRefNo.1,category)
                if (rc > 0) then call vimerr
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
                /* Go to the next message */
                /* Nothing to do.....loop will pull next message */
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'M' then do
                /* Open message */
                rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
                if (rc > 0) then call vimerr

                /* Mark the message as read */
                rc = RxVIMMarkMessageAsRead(Inbox,MsgRefNo.1)
                if (rc > 0) then call vimerr

                /* Close the message */
                rc = RxVIMCloseMessage(MsgHandle)
                if (rc > 0) then call vimerr
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'H' then do
                /* Open message */
                rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
                if (rc > 0) then call vimerr

                /* Get the message header info */
                attrDesc.0 = 2
                attrDesc.1.Selector = 'VIMSEL_FROM_NAME'
                attrDesc.1.Buffer   = 'from'
                attrDesc.2.Selector = 'VIMSEL_PRIORITY'
                attrDesc.2.Buffer   = 'priority'

                rc = RxVIMGetMessageHeader(MsgHandle,'attrDesc')
                if (rc > 0) then call vimerr
                Say '--------------------------------------------------------'
                Say '    Message Sent by -' from
                Say '    Message Priority-' priority
                Say '--------------------------------------------------------'
                'pause'
                /* Close the message */
                rc = RxVIMCloseMessage(MsgHandle)
                if (rc > 0) then call vimerr
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'I' then do
                /* Open message */
                rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
                if (rc > 0) then call vimerr

                /* Retrieve all of the items for this message */
                ipos      = ''
                icount   = 20
                imore    = ''
                ItemDesc = ''
                ifilter   = 'VIMSEL_NO_FILTER'
                ifdata    = ''

                rc = RxVIMEnumerateMessageItems(MsgHandle,'ipos',1,'icount','ItemDesc',,
                                                ifilter,ifdata,'imore')
                if (rc > 0) then call vimerr

                'cls'
                Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
                Say
                Say ' Message Information with Item Detail'
                Say '--------------------------------------------------------'
                Say '    Message =' MsgRefNo.1
                Say '    Subject =' Subject.1
                Say '    Unread  =' Unread.1
                Say '--------------------------------------------------------'

                loopcnt = 1
                do while (loopcnt <= icount)
                   /* Display each item descriptor entry */
                   Say '    Item Class  -' ItemDesc.loopcnt.CLASS
                   Say '    Item Type   -' ItemDesc.loopcnt.TYPE
                   Say '    Item Name   -' ItemDesc.loopcnt.NAME
                   Say '    Item Size   -' ItemDesc.loopcnt.SIZE
                   Say '    Item Ref No -' ItemDesc.loopcnt.REF
                   Say '--------------------------------------------------------'

                   loopcnt = loopcnt + 1
                end /* do */
                'pause'
                /* Close the message */
                rc = RxVIMCloseMessage(MsgHandle)
                if (rc > 0) then call vimerr
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'T' then do
                /* Open message */
                rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
                if (rc > 0) then call vimerr

                /* Retrieve all of the items for this message */
                ipos      = ''
                icount    = 20
                imore     = ''
                ItemDesc  = ''
                ifilter   = 'VIMSEL_CLASS'        /* Filter on item class */
                ifdata    = 'VIMSEL_NOTE_PART'    /* Retrieve only text items */

                rc = RxVIMEnumerateMessageItems(MsgHandle,'ipos',1,'icount','ItemDesc',,
                                                ifilter,ifdata,'imore')
                if (rc > 0) then call vimerr
                /* Retrieve the text for the first message item */
                tconvert          = 'VIM_TEXT'         /* Use text conversion   */
                tflags            = ''                 /* No conversion flags   */
                BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
                BufDesc.Size      = 256                /* Size of return buffer */
                BufDesc.FileName  = ''

                rc = RxVIMGetMessageItem(MsgHandle,ItemDesc.1.REF,tconvert,tflags,'BufDesc')
                if (rc > 0) then call vimerr

                'cls'
                Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
                Say
                Say ' Message Information with Item Detail'
                Say '--------------------------------------------------------'
                Say '    Message =' MsgRefNo.1
                Say '    Subject =' Subject.1
                Say '    Unread  =' Unread.1
                Say '--------------------------------------------------------'

                /* Display each item descriptor entry */
                Say '    Item Class  -' ItemDesc.1.CLASS
                Say '    Item Type   -' ItemDesc.1.TYPE
                Say '    Item Name   -' ItemDesc.1.NAME
                Say '    Item Size   -' ItemDesc.1.SIZE
                Say '    Item Ref No -' ItemDesc.1.REF
                Say '--------------------------------------------------------'
                Say ' Message Contents for first item (max 60 characters) -'
                Say
                Say SUBSTR(ItemText,1,60)
                Say '--------------------------------------------------------'
                'pause'
                /* Close the message */
                rc = RxVIMCloseMessage(MsgHandle)
                if (rc > 0) then call vimerr
             end  /* Do */
          otherwise
          end  /* select */

          /* End the loop if no more messages to retrieve */
          if more = 'False' then do
             Say 'All messages have been retrieved'
             action = 'X'
          end  /* Do */

     end /* do */


/* Close the message container -- Inbox */
rc = RxVIMCloseMessageContainer(Inbox)
if (rc > 0) then call vimerr


/* Close the session with the postoffice */
rc = RxVIMCloseSession(Session)
if (rc > 0) then call vimerr


/* Terminate the active VIM subsystem connection */
rc = RxVIMTerminate()
if (rc > 0) then call vimerr
signal done


/***** VIMErr *******/

/* If an error occurs, this function will return the text */
/* associated with the error.  Extended text may be       */
/* displayed if it exists for the specified error.        */

VIMERR:

erc = RxVIMStatusText(Session,rc,'Status')
Say
Say '|-Error Information ------------------------------------|'
Say '  Error Text -' status.1
Say
Say '  Ext Status -' status.2
rc = RxVIMTerminate()
signal done


/* The done section will unload the RexxVIM extensions */
/* and exit the program                                */
DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|-------------------------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit


ΓòÉΓòÉΓòÉ 12.6. Address Book Demo ΓòÉΓòÉΓòÉ

 The Address Book (ADDRBOOK.CMD) demo shows how RexxVIM can be used to open and
read address books, like the primary directory.  Launching the demo below will
allow each address book to be accessed and displayed.

    Run ADDRBOOK.CMD


ΓòÉΓòÉΓòÉ 12.6.1. ADDRBOOK.CMD Listing ΓòÉΓòÉΓòÉ

/** AddrBook.cmd **/
/**********************************************/
/*                                            */
/* Command line syntax:                       */
/*                                            */
/* AddrBook db_path user_password user_name   */
/*                                            */
/*                                            */
/**********************************************/
ARG db_path user_pw user_name
'@echo off'
'@cls'
Say 'RexxVIM Address Book Demonstration Program'
Say

/* Unload the function upon error */
SIGNAL ON ERROR NAME done

/* Prompt for the parameters if not passed on the */
/* command line                                   */
if LENGTH(STRIP(db_path)) = 0 then do
   Say 'Enter Postoffice Directory -'
   PARSE PULL db_path .
   Say
   Say 'Enter User Name -'
   PARSE PULL user_name
   Say 'Enter Password -'
   PARSE PULL user_pw
end  /* Do */


/* Load the RexxVIM extensions to Rexx */
rc = RxFuncAdd('RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs')
if rc <> 0 then do
   Say
   Say 'RexxVIM failed to load, return code' rc
   Say
   Say 'Functions have been released.  Retry program.'
   signal done
end  /* Do */
call RxVIMLoadFuncs
Say 'Functions are now loaded'
Say


/* Initialize the VIM subsystem */
rc = RxVIMInitialize()
if (rc > 0) then call vimerr

/* Open a session with the postoffice using the parameters */
/* provided by the user                                    */
rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
if (rc > 0) then call vimerr


     /* Enumerate the addressbooks */
     pos = ''                           /* Start at the beginning */
     skipcnt = 1                        /* Move forward one at a time */
     acount  = 1                        /* Retrieve 1 addressbook for each call */
     more    = ''                       /* Set the value of more to nul */
     action  = 'N'                      /* Set the value of repeat loop indicator to N */

     AttrDesc.0 = 2                               /* Retrieve 2 attributes for each addressbook */
     AttrDesc.1.Selector = 'VIMSEL_NAME'          /* 1st attribute is the addressbook name */
     AttrDesc.1.Buffer   = 'AddrName'             /* store results in this stem variable */
     AttrDesc.2.Selector = 'VIMSEL_TOTAL_ENTRIES' /* 2nd attribute is total entries */
     AttrDesc.2.Buffer   = 'AddrTotal'            /* store results in this stem variable */

     do until TRANSLATE(SUBSTR(action,1,1)) = 'X'

          /* Continue retrieving addressbook info until user enters N */

          rc = RxVIMEnumerateAddressBooks(Session,'pos',skipcnt,'AttrDesc','acount','more')
          if (rc > 0) then call vimerr

          /* Display results */
         'cls'
          Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
          Say
          Say 'Address Book Demo'
          Say
          Say '--------------------------------------------------------'
          Say '    Address Book Name =' AddrName.1
          Say '    Total Entries     =' AddrTotal.1
          Say '--------------------------------------------------------'
          Say
          Say
          Say 'Select an action for this message'
          Say
          Say '   N - Go to next Address Book'
          Say '   D - Display each of the Address Book entries'
          Say '   G - Get the current subtree name'
          Say '   X - Exit demo now'
          Say
          Say 'Enter your selection below-'
          PULL action

          /* Process the selection entered.  X will fall through the select statement */
          select
             when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
                /* Go to the next address book */
                /* Nothing to do.....loop will pull next address book */
             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'G' then do

                /* Open the current address book */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Get the subtree of the address book */
                Subtree = ''
                SubRefNo = ''

                rc = RxVIMGetCurrentSubtree(AddrBkPtr,'SubRefNo','Subtree')
                if (rc > 0) then call vimerr

                /* Close the  address book */
                rc = RxVIMCloseAddressBook(AddrBkPtr)
                if (rc > 0) then call vimerr

                Say '--------------------------------------------------------'
                Say '    Current Subtree  =' Subtree
                Say '--------------------------------------------------------'
                'pause'

             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'D' then do

                /* Open the current address book */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Enumerate the addressbook entries */
                epos = ''                           /* Start at the beginning */
                eskipcnt = 1                        /* Move forward one at a time */
                eacount  = 1                        /* Retrieve 1 addressbook for each call */
                efilter  = 'VIMSEL_NO_FILTER'       /* no filtering */
                efdata   = ''                       /* no filter data */
                emore    = ''                       /* Set the value of more to nul */
                eaction  = 'N'                      /* Set the value of repeat loop indicator to N */

                ItemDesc.0 = 3                               /* Retrieve 3 attributes for each entry */
                ItemDesc.1.Selector = 'VIMSEL_REF'           /* 1st attribute is the reference number */
                ItemDesc.1.Buffer   = 'ABE_Ref'              /* store results in this stem variable */
                ItemDesc.2.Selector = 'VIMSEL_NAME'          /* 2nd attribute is entry name */
                ItemDesc.2.Buffer   = 'ABE_Name'             /* store results in this stem variable */
                ItemDesc.3.Selector = 'VIMSEL_ADDRESS'       /* 3rd attribute is entry address */
                ItemDesc.3.Buffer   = 'ABE_Address'          /* store results in this stem variable */

                do until TRANSLATE(SUBSTR(eaction,1,1)) = 'X'

                     /* Continue retrieving addressbook info until user enters X */

                     rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'epos',eskipcnt,,
                                           'ItemDesc','eacount',efilter,efdata,'emore')
                     if (rc > 0) then call vimerr

                     /* Display results */
                    'cls'
                     Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
                     Say
                     Say 'Address Book Demo with entry information'
                     Say
                     Say '--------------------------------------------------------'
                     Say '    Address Book Name =' AddrName.1
                     Say '    Total Entries     =' AddrTotal.1
                     Say '--------------------------------------------------------'
                     Say '    Name =   ' ABE_Name.1
                     Say '    Address =' ABE_Address.1
                     Say '    Ref No  =' ABE_Ref.1
                     Say '--------------------------------------------------------'
                     Say
                     Say
                     Say 'Select an action for this message'
                     Say
                     Say '   N - Go to next Address Book entry'
                     Say '   X - Exit to the main screen'
                     Say
                     Say 'Enter your selection below-'
                     PULL eaction

                     select
                        when TRANSLATE(SUBSTR(eaction,1,1)) = 'N' then do
                           /* Go to the next address book entry */
                           /* Nothing to do.....will loop to the next entry */
                        end  /* Do */
                     otherwise
                     end  /* select */

                     /* End the loop if no more entries */
                     if emore = 'False' then do
                        Say 'All entries for this address book have been retrieved'
                        eaction = 'X'
                     end  /* Do */

                end /* Do */

                /* Close the  address book */
                rc = RxVIMCloseAddressBook(AddrBkPtr)
                if (rc > 0) then call vimerr

             end  /* Do */
          otherwise
          end  /* select */

          if more = 'False' then do
             Say 'All Address Books have been retrieved'
             action = 'X'
          end  /* Do */

     end /* do */

/* Close the session with the postoffice */
rc = RxVIMCloseSession(Session)
if (rc > 0) then call vimerr


/* Terminate the active VIM subsystem connection */
rc = RxVIMTerminate()
if (rc > 0) then call vimerr
signal done


/***** VIMErr *******/

/* If an error occurs, this function will return the text */
/* associated with the error.  Extended text may be       */
/* displayed if it exists for the specified error.        */

VIMERR:

erc = RxVIMStatusText(Session,rc,'Status')
Say
Say '|-Error Information ------------------------------------|'
Say '  Error Text -' status.1
Say
Say '  Ext Status -' status.2
rc = RxVIMTerminate()
signal done


/* The done section will unload the RexxVIM extensions */
/* and exit the program                                */
DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|-------------------------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit


ΓòÉΓòÉΓòÉ 12.7. Address Book Entries Demo ΓòÉΓòÉΓòÉ

 The Address Book Entries (ABEDEMO.CMD) demo shows how RexxVIM can be used to
open and read addressbook entries.  Launching the demo below will allow
individual entries in the address books to be reviewed, added, changed and
removed.

    Run ABEDEMO.CMD


ΓòÉΓòÉΓòÉ 12.7.1. ABEDEMO.CMD Listing ΓòÉΓòÉΓòÉ

/** ABEDemo.cmd **/
/**********************************************/
/*                                            */
/* Command line syntax:                       */
/*                                            */
/* ABEDemo  db_path user_password user_name   */
/*                                            */
/*                                            */
/**********************************************/
ARG db_path user_pw user_name
'@echo off'
'@cls'
Say 'RexxVIM Address Book Entry Demonstration Program'
Say

/* Unload the function upon error */
SIGNAL ON ERROR NAME done

/* Prompt for the parameters if not passed on the */
/* command line                                   */
if LENGTH(STRIP(db_path)) = 0 then do
   Say 'Enter Postoffice Directory -'
   PARSE PULL db_path .
   Say
   Say 'Enter User Name -'
   PARSE PULL user_name
   Say 'Enter Password -'
   PARSE PULL user_pw
end  /* Do */


/* Load the RexxVIM extensions to Rexx */
rc = RxFuncAdd('RxVIMLoadFuncs', 'REXXVIM', 'RxVIMLoadFuncs')
if rc <> 0 then do
   Say
   Say 'RexxVIM failed to load, return code' rc
   Say
   Say 'Functions have been released.  Retry program.'
   signal done
end  /* Do */
call RxVIMLoadFuncs
Say 'Functions are now loaded'
Say


/* Initialize the VIM subsystem */
rc = RxVIMInitialize()
if (rc > 0) then call vimerr

/* Open a session with the postoffice using the parameters */
/* provided by the user                                    */
rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
if (rc > 0) then call vimerr


     /* Enumerate the addressbooks */
     pos = ''                           /* Start at the beginning */
     skipcnt = 1                        /* Move forward one at a time */
     acount  = 1                        /* Retrieve 1 addressbook for each call */
     more    = ''                       /* Set the value of more to nul */
     action  = 'N'                      /* Set the value of repeat loop indicator to N */

     AttrDesc.0 = 2                               /* Retrieve 2 attributes for each addressbook */
     AttrDesc.1.Selector = 'VIMSEL_NAME'          /* 1st attribute is the addressbook name */
     AttrDesc.1.Buffer   = 'AddrName'             /* store results in this stem variable */
     AttrDesc.2.Selector = 'VIMSEL_TOTAL_ENTRIES' /* 2nd attribute is total entries */
     AttrDesc.2.Buffer   = 'AddrTotal'            /* store results in this stem variable */

     /* Continue retrieving addressbook info until user enters X */

     rc = RxVIMEnumerateAddressBooks(Session,'pos',skipcnt,'AttrDesc','acount','more')
     if (rc > 0) then call vimerr

     do until TRANSLATE(SUBSTR(action,1,1)) = 'X'

          /* Display results */
         'cls'
          Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
          Say
          Say 'Address Book Demo'
          Say
          Say '--------------------------------------------------------'
          Say '    Address Book Name =' AddrName.1
          Say '    Total Entries     =' AddrTotal.1
          Say '--------------------------------------------------------'
          Say
          Say
          Say 'Select an action for this message'
          Say
          Say '   N - Go to next Address Book'
          Say '   C - Create a new entry'
          Say '   S - Search for an entry'
          Say '   L - Change the location of an entry'
          Say '   F - Create a new group'
          Say '   G - Display all members of a group'
          Say '   X - Exit demo now'
          Say
          Say 'Enter your selection below-'
          PULL action

          /* Process the selection entered.  X will fall through the select statement */
          select
             when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
                /* Go to the next address book */

                rc = RxVIMEnumerateAddressBooks(Session,'pos',skipcnt,'AttrDesc','acount','more')
                if (rc > 0) then call vimerr

             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'C' then do
                /* Create a new entry in this address book */

                Say '--------------------------------------------------------'
                Say 'Enter the name'
                Pull ename
                Say 'Enter a comment'
                Pull ecomment
                Say
                Say 'Adding' ename 'to the addressbook'
                Say '--------------------------------------------------------'

                /* Open the addressbook */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Create the description stem for the create */
                attrItem.0 = 3
                attrItem.1.Selector = 'VIMSEL_NAME'
                attrItem.1.Value    = ename
                attrItem.2.Selector = 'VIMSEL_COMMENTS'
                attrItem.2.Value    = ecomment
                attrItem.3.Selector = 'VIMSEL_LOCATION'
                attrItem.3.Value    = 'VIMSEL_REMOTE'

                /* Add the entry to the address book */
                rc = RxVIMCreateAddressBookEntry(AddrBkPtr,'VIMSEL_ENTITY','attrItem')
                if (rc > 0) then call vimerr

                /* Close the address book */
                rc = RxVIMCloseAddressBook(addrBkPtr)
                if (rc > 0) then call vimerr

             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'S' then do
                /* Search for an entry in this address book */

                Say '--------------------------------------------------------'
                Say 'Enter the name for the search'
                Pull ename
                Say
                Say 'Searching for' ename 'in the addressbook'

                /* Open the addressbook */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Create the description stem for the create */
                searchon = 'VIMSEL_NAME'
                epos     = ''
                matchby  = 'VIMSEL_FULL'
                enumb    = ''

                /* Search for the entry in the address book */
                rc = RxVIMMatchAddressBook(AddrBkPtr,searchon,ename,matchby,'epos','enumb')
                if (rc > 0) then do
                    /* Entry not found */
                    Say '--------------------------------------------------------'
                    Say '  Entry not found in the addressbook'
                    Say '--------------------------------------------------------'
                end  /* Do */
                else do

                    /* Get additional info about specific entry */
                    itemdesc.0 = 3
                    itemdesc.1.selector = 'VIMSEL_LOCATION'
                    itemdesc.1.buffer   = 'location'
                    itemdesc.2.selector = 'VIMSEL_ADDRESS'
                    itemdesc.2.buffer   = 'address'
                    itemdesc.3.selector = 'VIMSEL_TYPE'
                    itemdesc.3.buffer   = 'typebuf'

                    rc = RxVIMGetABEntryAttributes(addrBkPtr,epos,'','itemdesc')
                    if (rc > 0) then call vimerr

                    Say '--------------------------------------------------------'
                    Say '  Name     -' ename
                    Say '  Ref No   -' epos
                    Say
                    Say '  Address  -' address
                    Say '  Type     -' typebuf
                    Say '  Location -' location
                    Say '--------------------------------------------------------'
                end  /* Do */
                'pause'

                /* Close the address book */
                rc = RxVIMCloseAddressBook(addrBkPtr)
                if (rc > 0) then call vimerr

             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'G' then do

                /* Retrieve the name of the group to display */
                Say 'Enter the name of the group to display'
                PULL gname

                /* Open the current address book */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Enumerate the group member entries */
                epos = ''                           /* Start at the beginning */
                eskipcnt = 1                        /* Move forward one at a time */
                eacount  = 1                        /* Retrieve 1 group member for each call */
                emore    = ''                       /* Set the value of more to nul */
                eaction  = 'N'                      /* Set the value of repeat loop indicator to N */

                ItemDesc.0 = 3                               /* Retrieve 3 attributes for each entry */
                ItemDesc.1.Selector = 'VIMSEL_REF'           /* 1st attribute is the reference number */
                ItemDesc.1.Buffer   = 'ABE_Ref'              /* store results in this stem variable */
                ItemDesc.2.Selector = 'VIMSEL_NAME'          /* 2nd attribute is the entry name */
                ItemDesc.2.Buffer   = 'ABE_Name'             /* store results in this stem variable */
                ItemDesc.3.Selector = 'VIMSEL_ADDRESS'       /* 3rd attribute is entry address */
                ItemDesc.3.Buffer   = 'ABE_Address'          /* store results in this stem variable */

                do until TRANSLATE(SUBSTR(eaction,1,1)) = 'X'

                     /* Continue retrieving group member info until user enters X */

                     rc = RxVIMEnumerateGroupMembers(AddrBkPtr,'',gname,'epos',eskipcnt,,
                                           'ItemDesc','eacount','emore')
                     if (rc > 0) then call vimerr

                     /* Display results */
                    'cls'
                     Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
                     Say
                     Say 'Group Member Information'
                     Say
                     Say '--------------------------------------------------------'
                     Say '    Group Name =' gname
                     Say '--------------------------------------------------------'
                     Say '    Name =   ' ABE_Name.1
                     Say '    Address =' ABE_Address.1
                     Say '    Ref No  =' ABE_Ref.1
                     Say '--------------------------------------------------------'
                     Say
                     Say
                     Say 'Select an action for this message'
                     Say
                     Say '   N - Go to next Group Member entry'
                     Say '   A - Add a new entry to the group'
                     Say '   D - Delete this entry from the group'
                     Say '   X - Exit to the main screen'
                     Say
                     Say 'Enter your selection below-'
                     PULL eaction

                     select
                        when TRANSLATE(SUBSTR(eaction,1,1)) = 'N' then do
                           /* Go to the next group member entry */
                           /* Nothing to do.....will loop to the next entry */
                        end  /* Do */
                        when TRANSLATE(SUBSTR(eaction,1,1)) = 'D' then do
                           /* Delete the current entry from the group */
                           rc = RxVIMRemoveGroupMember(AddrBkPtr,'',gname,ABE_Name.1)
                           if (rc > 0) then call vimerr
                        end  /* Do */
                        when TRANSLATE(SUBSTR(eaction,1,1)) = 'A' then do
                           /* Add a new entry to the group */
                           Say 'Enter the new name to add'
                           PULL new_name

                           rc = RxVIMAddGroupMember(AddrBkPtr,'',gname,new_name)
                           if (rc > 0) then call vimerr
                        end  /* Do */
                     otherwise
                     end  /* select */

                     /* End the loop if no more entries */
                     if emore = 'False' then do
                        Say 'All entries for this group have been retrieved'
                        eaction = 'X'
                     end  /* Do */

                end /* Do */

                /* Close the  address book */
                rc = RxVIMCloseAddressBook(AddrBkPtr)
                if (rc > 0) then call vimerr

             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'F' then do
                /* Create a new group entry in this address book */

                Say '--------------------------------------------------------'
                Say 'Enter the group name'
                Pull gname
                Say
                Say 'Adding' gname 'to the addressbook'
                Say '--------------------------------------------------------'

                /* Open the addressbook */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Create the description stem for the create */
                attrItem.0 = 1
                attrItem.1.Selector = 'VIMSEL_NAME'
                attrItem.1.Value    = gname

                /* Add the entry to the address book */
                rc = RxVIMCreateAddressBookEntry(AddrBkPtr,'VIMSEL_GROUP','attrItem')
                if (rc > 0) then call vimerr

                /* Close the address book */
                rc = RxVIMCloseAddressBook(addrBkPtr)
                if (rc > 0) then call vimerr

             end  /* Do */
             when TRANSLATE(SUBSTR(action,1,1)) = 'L' then do
                /* Search for an entry in this address book */

                Say '--------------------------------------------------------'
                Say 'Enter the name to change location'
                Pull ename
                Say
                Say 'Searching for' ename 'in the addressbook'

                /* Open the addressbook */
                rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
                if (rc > 0) then call vimerr

                /* Create the description stem for the create */
                searchon = 'VIMSEL_NAME'
                epos     = ''
                matchby  = 'VIMSEL_FULL'
                enumb    = ''

                /* Search for the entry in the address book */
                rc = RxVIMMatchAddressBook(AddrBkPtr,searchon,ename,matchby,'epos','enumb')
                if (rc > 0) then do
                    /* Entry not found */
                    Say '--------------------------------------------------------'
                    Say '  Entry not found in the addressbook'
                    Say '--------------------------------------------------------'
                end  /* Do */
                else do

                    /* Get additional info about specific entry */
                    itemdesc.0 = 3
                    itemdesc.1.selector = 'VIMSEL_LOCATION'
                    itemdesc.1.buffer   = 'location'
                    itemdesc.2.selector = 'VIMSEL_ADDRESS'
                    itemdesc.2.buffer   = 'address'
                    itemdesc.3.selector = 'VIMSEL_TYPE'
                    itemdesc.3.buffer   = 'typebuf'

                    rc = RxVIMGetABEntryAttributes(addrBkPtr,epos,'','itemdesc')
                    if (rc > 0) then call vimerr

                    Say '--------------------------------------------------------'
                    Say '  Name     -' ename
                    Say '  Ref No   -' epos
                    Say
                    Say '  Address  -' address
                    Say '  Type     -' typebuf
                    Say '  Location -' location
                    Say '--------------------------------------------------------'
                end  /* Do */
                Say 'Enter new location - (L)ocal, (R)emote, (M)obile or enter for no change'
                PULL nlocation

                if LENGTH(STRIP(nlocation)) > 0 then do

                    itemdesc.0 = 1
                    itemdesc.1.selector = 'VIMSEL_LOCATION'

                    /* Set value of new location from input */
                    Select
                       when TRANSLATE(SUBSTR(nlocation,1,1)) = 'L' then
                         itemdesc.1.value = 'VIMSEL_LOCAL'
                       when TRANSLATE(SUBSTR(nlocation,1,1)) = 'R' then
                         itemdesc.1.value = 'VIMSEL_REMOTE'
                       when TRANSLATE(SUBSTR(nlocation,1,1)) = 'M' then
                         itemdesc.1.value = 'VIMSEL_DIALIN'
                    otherwise
                         itemdesc.1.value = location
                    end  /* select */
                    itemdesc.1.buffer   = 'location'

                    /* Call function to set location */
                    rc = RxVIMSetABEntryAttributes(addrBkPtr,epos,'','itemdesc')
                    if (rc > 0) then call vimerr

                end  /* Do */

                /* Close the address book */
                rc = RxVIMCloseAddressBook(addrBkPtr)
                if (rc > 0) then call vimerr

             end  /* Do */
          otherwise
          end  /* select */

          if more = 'False' then do
             Say 'All Address Books have been retrieved'
             action = 'X'
          end  /* Do */

     end /* do */

/* Close the session with the postoffice */
rc = RxVIMCloseSession(Session)
if (rc > 0) then call vimerr


/* Terminate the active VIM subsystem connection */
rc = RxVIMTerminate()
if (rc > 0) then call vimerr
signal done


/***** VIMErr *******/

/* If an error occurs, this function will return the text */
/* associated with the error.  Extended text may be       */
/* displayed if it exists for the specified error.        */

VIMERR:

erc = RxVIMStatusText(Session,rc,'Status')
Say
Say '|-Error Information ------------------------------------|'
Say '  Error Text -' status.1
Say
Say '  Ext Status -' status.2
rc = RxVIMTerminate()
signal done


/* The done section will unload the RexxVIM extensions */
/* and exit the program                                */
DONE:
/*** Drop all of the external functions ***/
call RxVIMDropFuncs
Say '|-------------------------------------------------------|'
Say 'Demo Complete.  All functions released'
'pause'
exit