═══ 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: 614-791-9055 ═══ 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: (614) 791-9055 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