home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / rxvim.zip / REXXVIM.INF (.txt) < prev    next >
OS/2 Help File  |  1995-01-08  |  162KB  |  7,705 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. RexxVIM ΓòÉΓòÉΓòÉ
  3.  
  4. RexxVIM allows programs written in Rexx to communicate with Vendor Independent 
  5. Messaging (VIM) enabled mail systems.  This includes cc:Mail and Lotus Notes. 
  6. This toolkit provides the functionality of the Lotus VIM Developer's Toolkit to 
  7. Rexx applications. 
  8.  
  9. The toolkit extends the ease-of-use of Rexx to provide the full function of a 
  10. VIM development environment.  The toolkit allows Rexx applications to create 
  11. messages, perform addressbook activities, provide in-box automation, and many 
  12. other services. 
  13.  
  14. Lotus cc:Mail is the world's best-selling LAN-based e-mail system.  cc:Mail 
  15. runs on Windows, Macintosh, OS/2, UNIX and MS-DOS platforms across all major 
  16. LANs, providing transparent connectivity to all major private and public 
  17. electronic mail systems and facsimile machines worldwide.  RexxVIM harnesses 
  18. the power of cc:Mail for use within Rexx applications, by providing access to 
  19. the full power of the VIM interface. 
  20.  
  21. RexxVIM allows the Rexx language included with OS/2 to be used as the 
  22. development environment for mail applications.  Several example applications 
  23. ship with the product.  The applications provide message creation with attached 
  24. text, addressbook manipulation, and in-box interaction.  Existing Rexx 
  25. applications, such as network monitoring, can easily be extended to utilize the 
  26. power of the e-mail system. 
  27.  
  28. The additional functions provided by this toolkit are usable with the base Rexx 
  29. support provided in Operating System/2 (OS/2).  The toolkit has also been 
  30. tested with Rexx extension products, such as VX-Rexx from Watcom, VisPro/Rexx 
  31. from Hockware, and GpfRexx from Gpf Systems. 
  32.  
  33.  
  34. ΓòÉΓòÉΓòÉ 2. License Agreement and Limited Product Warranty ΓòÉΓòÉΓòÉ
  35.  
  36. YOU SHOULD CAREFULLY READ THE FOLLOWING TERMS AND CONDITIONS. 
  37.  
  38. USING THIS PROGRAM INDICATES YOUR ACCEPTANCE OF THEM.  IF YOU DO NOT AGREE WITH 
  39. THEM, PROMPTLY RETURN THE PACKAGE AND YOUR MONEY WILL BE REFUNDED. 
  40.  
  41. Innovative Business Technologies, Inc. provides this Program and licenses its 
  42. use to you.  You are responsible for selecting the Program to achieve your 
  43. intended results and for the installation, use and results obtained form this 
  44. program. 
  45.  
  46. THE PROGRAM, INCLUDING ITS STRUCTURE AND ORGANIZATION, AS WELL AS, ITS CODE, IS 
  47. A PROPRIETARY PRODUCT OF INNOVATIVE BUSINESS TECHNOLOGIES 
  48.  
  49. AND IS PROTECTED BY COPYRIGHT LAWS.  TITLE TO THE PROGRAM, OR ANY COPY, 
  50. MODIFICATION OR MERGED PORTION OF THE PROGRAM, SHALL AT ALL TIMES REMAIN WITH 
  51. INNOVATIVE BUSINESS TECHNOLOGIES, INC. 
  52.  
  53. LICENSE 
  54.  
  55. You may: 
  56.  
  57. Use the Program for development only on a single computer.  Even though two 
  58. copies of the program may be provided in this package, on diskettes of 
  59. different sizes, you may not use both sizes of diskettes simultaneously on 
  60. different computers.  This Program may not under any circumstances be used for 
  61. development on more than one computer system at a time. 
  62.  
  63. Distribute without cost the RexxVIM.dll runtime program file to allow programs 
  64. created with the Program to operate on other computer systems. 
  65.  
  66. Make one copy of the Program into any computer readable or printed form for 
  67. backup or modification purposes in support of your use of the Program for 
  68. development on a single computer. 
  69.  
  70. Transfer the Program together with this License to another party, but only if 
  71. the other party agrees to accept the terms and conditions of this Agreement. 
  72. If you transfer the Program and License, you must at the same time either 
  73. transfer all copies, modifications or merged portions of the Program to the 
  74. same party or destroy those note transferred.  Any such transfer terminates 
  75. your License. 
  76.  
  77. You may not: 
  78.  
  79. TRANSFER OR RENT THE PROGRAM OF USE, COPY MODIFY OR MERGE THE PROGRAM, IN WHOLE 
  80. OR IN PART, EXCEPT AS EXPRESSLY PERMITTED IN THIS LICENSE. 
  81.  
  82. DECOMPILE, REVERSE ASSEMBLE OR OTHERWISE REVERSE ENGINEER THE PROGRAM. 
  83.  
  84. REPRODUCE, DISTRIBUTE OR REVISE THE PROGRAM DOCUMENTATION. 
  85.  
  86. IF YOU DO ANY OF THE FOREGOING, YOUR LICENSE AND THIS AGREEMENT ARE 
  87. AUTOMATICALLY TERMINATED.  SUCH TERMINATION SHALL BE IN ADDITION TO AND NOT IN 
  88. LIEU OF ANY CRIMINAL, CIVIL, OR OTHER REMEDIES AVAILABLE TO INNOVATIVE BUSINESS 
  89. TECHNOLOGIES. 
  90.  
  91. TERM 
  92.  
  93. You may terminate your License and this Agreement at any time by destroying the 
  94. Program and the Program documentation together with all copies in any form. 
  95. They will also terminate automatically if you fail to comply with any term or 
  96. condition of this Agreement, in which event you agree  to destroy the Program 
  97. together with all copies in any form, and to provide us upon our request with 
  98. written certification of such destruction. 
  99.  
  100. LIMITED PRODUCT WARRANTY 
  101.  
  102. EXCEPT AS SPECIFICALLY STATED IN THIS AGREEMENT, THE PROGRAM IS PROVIDED AND 
  103. LICENSED "AS IS" WITHOUT WARRANTY OR ANY KIND, EITHER EXPRESS OR IMPLIED, 
  104. INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND 
  105. FITNESS FOR A PARTICULAR PURPOSE. 
  106.  
  107. Innovative Business Technologies warrants that the Program will substantially 
  108. perform the functions or generally conforms to the Program's specifications 
  109. published by Innovative Business Technologies. 
  110.  
  111. Innovative Business Technologies warrants that the diskettes on which the 
  112. Program is furnished will be free for defects in materials and workmanship 
  113. under normal use for a period of ninety days from the date of delivery to you. 
  114.  
  115. Innovative Business Technologies DOES NOT WARRANT that the functions contained 
  116. in the Program will meet your requirements or that the operation of the Program 
  117. will be entirely error free or appear precisely as described in the Program 
  118. documentation. 
  119.  
  120. LIMITATION OF REMEDIES AND LIABILITY 
  121.  
  122. The remedies described below are accepted by you as your only remedies, and 
  123. shall be available to you only if you or your dealer returns the enclosed 
  124. registration card to Innovative Business Technologies within ten days after 
  125. delivery of the Program to you.  Innovative Business Technologies' entire 
  126. liability and your exclusive remedies shall be: 
  127.  
  128. If the Program does not substantially perform the functions or generally 
  129. conform to the Program's specifications published by Innovative Business 
  130. Technologies, you may within six months after delivery write to Innovative 
  131. Business Technologies to report a significant defect.  If Innovative 
  132.  
  133. Business Technologies is unable to correct that defect within 90 days after 
  134. receiving your report, you may terminate your License and this Agreement by 
  135. returning the Program with your original receipts and your money will be 
  136. refunded. 
  137.  
  138. If the Program diskette is defective, you may return it with a copy of your 
  139. receipt, and Innovative Business Technologies with either replace it or, if a 
  140. replacement cannot soon be delivered, you may terminate your License and this 
  141. Agreement by returning the Program with your original receipts and your money 
  142. will be refunded. 
  143.  
  144. IN NO EVENT WILL INNOVATIVE BUSINESS TECHNOLOGIES BE LIABLE TO YOU FOR ANY 
  145. DAMAGES, INCLUDING LOST PROFITS, LOST SAVINGS, OR OTHER INCIDENTAL OR 
  146. CONSEQUENTIAL DAMAGES, ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM, 
  147. EVEN IF INNOVATIVE BUSINESS TECHNOLOGIES OR DEALER HAS BEEN ADVISED OR THE 
  148. POSSIBILITY OF SUCH DAMAGES. 
  149.  
  150. GENERAL 
  151.  
  152. If any provision of this Agreement is held to be unenforceable, the 
  153. enforceability of the remaining provisions shall in no way be affected or 
  154. impaired thereby. 
  155.  
  156. The prevailing party in any action or proceeding brought in connection with a 
  157. breach of this Agreement will be entitled to reimbursement by the other party 
  158. for costs and reasonable attorney's fees.  This Agreement shall be governed by 
  159. the laws of the State of Ohio. 
  160.  
  161. Any questions concerning this Agreement should be referred in writing to 
  162. Innovative Business Technologies, Inc. at 7137 Shady Nelms Drive, Suite #204, 
  163. Columbus, OH 43017. 
  164.  
  165. YOU ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT, AND BY OPERATING THIS 
  166. PROGRAM INDICATE YOUR ACCEPTANCE OF ITS TERMS AND CONDITIONS. 
  167.  
  168.  
  169. ΓòÉΓòÉΓòÉ 3. Contacts and Order Form ΓòÉΓòÉΓòÉ
  170.  
  171. This section contains company contact and product ordering information. 
  172. Included in the product package is the order.txt file, which is an electronic 
  173. order form for additional copies of RexxVIM. 
  174.  
  175.  
  176. ΓòÉΓòÉΓòÉ 3.1. Contact Information ΓòÉΓòÉΓòÉ
  177.  
  178. RexxVIM is copyrighted by Innovative Business Technologies, Inc.  All other 
  179. copyrights and trademarks referenced in this material are the properties of 
  180. their respective corporations. 
  181.  
  182. If you have any questions, comments or suggestions, please contact us at: 
  183.  
  184. Innovative Business Technologies, Inc.
  185. 7137 Shady Nelms Drive
  186. Suite 204
  187. Columbus, OH 43017
  188.  
  189. _________________ or _____________________
  190.  
  191.  
  192. CompuServe:     74563,1530
  193.  
  194.  
  195. _________________ or _____________________
  196.  
  197.  
  198. OS/2 Vendor Forum A (OS2AVEND), Other vendors section
  199.  
  200.  
  201. _________________ or _____________________
  202.  
  203.  
  204. Voice/Fax:      614-791-9055
  205.  
  206.  
  207.  
  208. ΓòÉΓòÉΓòÉ 3.2. Product Ordering Information ΓòÉΓòÉΓòÉ
  209.  
  210. RexxVIM is available directly from Innovative Business Technologies, Inc.  The 
  211. software is licensed per developer, with unlimited rights to distribute the 
  212. runtime dll.  Each user developing RexxVIM applications will require a copy of 
  213. the development environment.  For multiple unit and site license pricing, 
  214. contact IBT. 
  215.  
  216. The development environment includes: 
  217.  
  218. RexxVIM.dll    -    Runtime dynamic link library
  219. RexxVIM.inf    -    Full on-line documentation
  220.  
  221. RexxPack.exe   -    Program to compact a Rexx command file for
  222.                     faster execution and limited change
  223.  
  224. Example apps   -    Example applications that demonstrate the
  225.                     use of all of the RexxVIM functions
  226.  
  227.  
  228.  
  229. ΓòÉΓòÉΓòÉ 3.3. Order Form ΓòÉΓòÉΓòÉ
  230.  
  231. To order additional copies of  RexxVIM print the included REXXVIM.ORD file and 
  232. mail or fax to IBT. 
  233.  
  234. For the fastest response, fax the form to IBT with your VISA or MasterCard 
  235. number.  IBT can send the product to you immediately via e-mail. 
  236.  
  237. Your order can be immediately sent via electronic mail using most major e-mail 
  238. systems.  Be sure to include your e-mail address for fastest response. 
  239.  
  240.  
  241. ΓòÉΓòÉΓòÉ 4. Installation ΓòÉΓòÉΓòÉ
  242.  
  243. The RexxVIM files should be installed into a RexxVIM directory.  The install 
  244. program will  place the product into a RexxVIM directory on the specified 
  245. drive. 
  246.  
  247. The directory where the RexxVIM files are copied must be added to the LIBPATH 
  248. statement in the config.sys.  The directory which contains the VIM.dll must 
  249. also be in the config.sys. 
  250.  
  251. NOTE:  Your VIM files must be dated 9/93 or later!  If the
  252.        VIM.dll is dated earlier than 9/93, contact Lotus
  253.        for the VIM OS/2 updates, or download the
  254.        updates from the LOTUSC forum on CompuServe.
  255.  
  256.  
  257. To install RexxVIM perform the following: 
  258.  
  259. 1.    Insert the RexxVIM Installation diskette into Drive A. 
  260.  
  261. 2.    Type A:INSTALL, and press enter. 
  262.  
  263. 3.    Follow the instructions on the screen. 
  264.  
  265. 4.    Remove the diskette from Drive A. 
  266.  
  267.  
  268. ΓòÉΓòÉΓòÉ 4.1. File Descriptions ΓòÉΓòÉΓòÉ
  269.  
  270. The RexxVIM package contains the following files: 
  271.  
  272. RexxVIM.dll    The dynamic link library that adds
  273.                VIM functions to Rexx
  274.  
  275. RexxVIM.inf    The help file for the toolkit
  276.  
  277. RexxPack.exe   Program to compact a Rexx command
  278.                file for faster execution and
  279.                   limited change
  280.  
  281. Demo.cmd       Rexx program to demonstrate the
  282.                    basic RexxVIM functions
  283.  
  284. VIMcap.cmd     Rexx program to demonstrate querying
  285.                   the VIM subsystem for supported features
  286.  
  287. Message.cmd    Rexx program to demonstrate sending
  288.                   a message using RexxVIM
  289.  
  290. MSGCont.cmd    Rexx program to demonstrate using the
  291.                message container.  Allows each message
  292.                in the Inbox to be deleted, stored in
  293.                a folder, or left in the Inbox.
  294.  
  295. MSGActs.cmd    Rexx program to demonstrate the use
  296.                of the message access functions.
  297.  
  298. AddrBook.cmd   Rexx program to demonstrate the use
  299.                of the address book functions for
  300.                opening, closing, and enumerating.
  301.  
  302. ABEdemo.cmd    Rexx program to demonstrate the use
  303.                of the address book functions that
  304.                provide access to the address book
  305.                entries and group members.
  306.  
  307.  
  308. ΓòÉΓòÉΓòÉ 5. Base Functions ΓòÉΓòÉΓòÉ
  309.  
  310. This section describes each of the functions available in the RexxVIM product 
  311. that address base RexxVIM features. 
  312.  
  313. Below are all of the base functions: 
  314.  
  315. RxVIMLoadFuncs 
  316.  
  317. RxVIMDropFuncs 
  318.  
  319. RxVIMVersion 
  320.  
  321. RxVIMStatus 
  322.  
  323.  
  324. ΓòÉΓòÉΓòÉ 5.1. RxVIMLoadFuncs ΓòÉΓòÉΓòÉ
  325.  
  326. The RxVIMLoadFuncs function loads all of the VIM extensions using one call. 
  327.  
  328.  
  329. ΓòÉΓòÉΓòÉ 5.1.1. Syntax ΓòÉΓòÉΓòÉ
  330.  
  331. RxVIMLoadFuncs is called with no parameters. 
  332.  
  333. call RxVIMLoadFuncs
  334.  
  335. or
  336.  
  337. rc = RxVIMLoadFuncs()
  338.  
  339.  
  340. ΓòÉΓòÉΓòÉ 5.1.2. Return Codes ΓòÉΓòÉΓòÉ
  341.  
  342. The RxVIMLoadFuncs function returns the following values: 
  343.  
  344. 0 - Successful load of all functions
  345. 1 - Load of functions failed
  346.  
  347.  
  348. NOTE:  The load will fail if a previous program did
  349.        not execute the RxVIMDropFuncs function.
  350.  
  351.  
  352. ΓòÉΓòÉΓòÉ 5.1.3. Example ΓòÉΓòÉΓòÉ
  353.  
  354. /* Example to load all of the VIM extensions */
  355.  
  356. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  357. call RxVIMLoadFuncs
  358.  
  359.  
  360. ΓòÉΓòÉΓòÉ 5.2. RxVIMDropFuncs ΓòÉΓòÉΓòÉ
  361.  
  362. The RxVIMDropFuncs function unloads all of the VIM extensions using one call. 
  363.  
  364.  
  365. ΓòÉΓòÉΓòÉ 5.2.1. Syntax ΓòÉΓòÉΓòÉ
  366.  
  367. RxVIMDropFuncs is called with no parameters. 
  368.  
  369. call RxVIMDropFuncs
  370.  
  371. or
  372.  
  373. rc = RxVIMDropFuncs()
  374.  
  375.  
  376. ΓòÉΓòÉΓòÉ 5.2.2. Return Codes ΓòÉΓòÉΓòÉ
  377.  
  378. The RxVIMDropFuncs function returns the following values: 
  379.  
  380. 0 - Successful unload of all functions
  381. 1 - Unload of functions failed
  382.  
  383.  
  384. ΓòÉΓòÉΓòÉ 5.2.3. Example ΓòÉΓòÉΓòÉ
  385.  
  386. /* Example to unload all of the VIM extensions */
  387.  
  388. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  389. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  390. call RxVIMLoadFuncs
  391.  
  392.  
  393. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  394. call RxVIMDropFuncs
  395.  
  396.  
  397. ΓòÉΓòÉΓòÉ 5.3. RxVIMVersion ΓòÉΓòÉΓòÉ
  398.  
  399. The RxVIMVersion function returns the version number of the RexxVIM currently 
  400. in use. 
  401.  
  402.  
  403. ΓòÉΓòÉΓòÉ 5.3.1. Syntax ΓòÉΓòÉΓòÉ
  404.  
  405. RxVIMVersion is called with no parameters. 
  406.  
  407. call RxVIMVersion
  408.  
  409. or
  410.  
  411. rc = RxVIMVersion()
  412.  
  413.  
  414. ΓòÉΓòÉΓòÉ 5.3.2. Return Codes ΓòÉΓòÉΓòÉ
  415.  
  416. The RxVIMVersion function returns the following: 
  417.  
  418. RexxVIM Version is 1.02   (01100002)
  419.  
  420.  
  421. ΓòÉΓòÉΓòÉ 5.3.3. Example ΓòÉΓòÉΓòÉ
  422.  
  423. /* Example of RxVIMVersion  */
  424.  
  425. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  426. call RxVIMLoadFuncs
  427.  
  428. Say RXVIMVersion()
  429.  
  430.  
  431.  
  432. ΓòÉΓòÉΓòÉ 5.4. RxVIMStatus ΓòÉΓòÉΓòÉ
  433.  
  434. The RxVIMStatus function returns the status text associated with a RexxVIM 
  435. return code value. 
  436.  
  437.  
  438. ΓòÉΓòÉΓòÉ 5.4.1. Syntax ΓòÉΓòÉΓòÉ
  439.  
  440. RxVIMStatus is called with one parameter, the return code value of interest. 
  441.  
  442.  
  443. status = RxVIMLoadFuncs( 'rc' )
  444.  
  445.  
  446. ΓòÉΓòÉΓòÉ 5.4.2. Return Codes ΓòÉΓòÉΓòÉ
  447.  
  448. The RxVIMLoadFuncs function returns the status text of the return code value 
  449. passed. 
  450.  
  451.  
  452. ΓòÉΓòÉΓòÉ 5.4.3. Example ΓòÉΓòÉΓòÉ
  453.  
  454. /* Example of VIMStatus */
  455.  
  456. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  457. call RxVIMLoadFuncs
  458.  
  459. rc = RxVIMInitialize()
  460. if rc <> 0 then do
  461.   status = RxVIMStatus( rc )
  462.   Say 'Initialize failed: Error:' status
  463. endif
  464.  
  465.  
  466. ΓòÉΓòÉΓòÉ 6. Session Management Functions ΓòÉΓòÉΓòÉ
  467.  
  468. This section describes each of the functions available in the RexxVIM product 
  469. that address VIM session management. 
  470.  
  471. Below are all of the Session Management Functions: 
  472.  
  473. RxVIMInitialize 
  474.  
  475. RxVIMQueryCapability 
  476.  
  477. RxVIMGetDefaultSessionInfo 
  478.  
  479. RxVIMOpenSession 
  480.  
  481. RxVIMGetSessionAttributes 
  482.  
  483. RxVIMSetSessionAttributes 
  484.  
  485. RxVIMGetEntityName 
  486.  
  487. RxVIMCloseSession 
  488.  
  489. RxVIMTerminate 
  490.  
  491. RxVIMStatusText 
  492.  
  493.  
  494. ΓòÉΓòÉΓòÉ 6.1. RxVIMInitialize ΓòÉΓòÉΓòÉ
  495.  
  496. The RxVIMInitialize function establishes a connection to the underlying VIM 
  497. sub-system.  This function must be called prior to any of the other functions 
  498. that interact with the VIM system.  This function should only be called once 
  499. for any command file that interacts with a VIM system. 
  500.  
  501.  
  502. ΓòÉΓòÉΓòÉ 6.1.1. Syntax ΓòÉΓòÉΓòÉ
  503.  
  504. RxVIMInitialize is called with no parameters. 
  505.  
  506. call RxVIMInitialize
  507.  
  508. or
  509.  
  510. rc = RxVIMInitialize()
  511.  
  512.  
  513. ΓòÉΓòÉΓòÉ 6.1.2. Return Codes ΓòÉΓòÉΓòÉ
  514.  
  515. The RxVIMInitialize function returns the following values: 
  516.  
  517. 0 - Successful initialization
  518.  
  519.  
  520.  
  521. The return values from all of the function calls return a zero for success, and 
  522. non-zero for failure.  To retrieve the actual failure reason, use the 
  523. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  524. value to the actual failure text.  Using RxVIMStatus, the following values may 
  525. be returned by RxVIMInitialize: 
  526.  
  527. VIMSTS_SUCCESS          Successful Initialization
  528. VIMSTS_FAILURE          Initialization Failed
  529.  
  530.  
  531. ΓòÉΓòÉΓòÉ 6.1.3. Example ΓòÉΓòÉΓòÉ
  532.  
  533. /* Example of using RxVIMInitialize */
  534.  
  535. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  536. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  537. call RxVIMLoadFuncs
  538.  
  539. /* This will establish a connection to the VIM system */
  540. rc = RxVIMInitialize()
  541.  
  542. /* Show return code to user */
  543. Say 'The return code from the Initialize was =' rc
  544.  
  545. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  546. call RxVIMDropFuncs
  547.  
  548.  
  549. ΓòÉΓòÉΓòÉ 6.2. RxVIMQueryCapability ΓòÉΓòÉΓòÉ
  550.  
  551. The RxVIMQueryCapability function allows the application to determine supported 
  552. features in the underlying VIM system.  This function should be used to 
  553. determine what features are supported in the particular VIM system be used, 
  554. prior to using the feature. 
  555.  
  556.  
  557. ΓòÉΓòÉΓòÉ 6.2.1. Syntax ΓòÉΓòÉΓòÉ
  558.  
  559. RxVIMQueryCapability is called with two parameters.  The first parameter is a 
  560. selector of the item to be queried, and the second is the Rexx variable to 
  561. contain the result. 
  562.  
  563. call RxVIMQueryCapability 'Selector' , 'variable'
  564.  
  565. or
  566.  
  567. rc = RxVIMQueryCapability('Selector' , 'variable')
  568.  
  569. Listed below are the valid selectors to query, and the possible return values: 
  570.  
  571. VIMSEL_VERSION                  Indicates the VIM version number
  572. VIMSEL_IMPLEMENTATION           Indicates the product that is providing the database
  573. VIMSEL_IMPLEMENTATION_VERSION   Indicates the version of the VIM implementation
  574. VIMSEL_PRODUCT                  Indicates the name of the product
  575.  
  576.                                 cc:Mail will return CCMAIL
  577.                                 Notes will return NOTES
  578.  
  579. VIMSEL_MAX_SUBJECT_LEN          This is the maximum limit for a subject line
  580. VIMSEL_MAX_TYPE_LEN             This is the maximum limit an item of type VIMSEL_TYPE
  581. VIMSEL_MAX_TEXT_LEN             This is the maximum limit for a text item
  582.  
  583.  
  584. VIMSEL_RTF                 Returns level of support for Rich Text Format
  585.  
  586.     VIMSEL_NOT_SUPPORTED     - Not supported
  587.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  588.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  589.  
  590. VIMSEL_FAX                      Returns level of support for
  591.  FAX VIMSEL_NOT_SUPPORTED - Not supported
  592.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  593.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  594.  
  595. VIMSEL_STYLED                   Returns level of support for Macintosh styled text
  596.  
  597.     VIMSEL_NOT_SUPPORTED     - Not supported
  598.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  599.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  600.  
  601. VIMSEL_PICT                     Returns level of support for Macintosh PICT note parts
  602.  
  603.     VIMSEL_NOT_SUPPORTED     - Not supported
  604.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  605.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  606.  
  607. VIMSEL_MOVIE                    Returns level of support for Quicktime movie parts
  608.  
  609.     VIMSEL_NOT_SUPPORTED     - Not supported
  610.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  611.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  612.  
  613. VIMSEL_IMAG                     Returns level of support for Macintosh FAX note parts
  614.  
  615.     VIMSEL_NOT_SUPPORTED     - Not supported
  616.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  617.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  618.  
  619. VIMSEL_UNWRAPPED_TEXT           Returns level of support for unwrapped text
  620.  
  621.     VIMSEL_NOT_SUPPORTED     - Not supported
  622.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  623.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  624.  
  625. VIMSEL_ALL_NOTE_PARTS_SUPP      Returns TRUE if all notes part types are supported
  626.  
  627. VIMSEL_ATTACH_TYPE_SUPP         Returns TRUE if types are supported for file attachment
  628.  
  629. VIMSEL_ATTACH_DIRS              Returns level of support for attaching directories
  630.  
  631.     VIMSEL_NOT_SUPPORTED     - Not supported
  632.     VIMSEL_SUPP_WITH_CONV    - Support w/conversion at source
  633.     VIMSEL_SUPP_WITHOUT_CONV - Support w/o conversion
  634.  
  635. VIMSEL_ENCRYPT                  Returns TRUE if key-based encryption is supported
  636.  
  637. VIMSEL_ENCRYPT_WITH_KEY         Returns TRUE if explicit key-based encryption is supported
  638.  
  639. VIMSEL_SIGN                     Returns TRUE if signatures are supported
  640.  
  641. VIMSEL_NSTD_DERIVED_REPLIES     Returns TRUE if replies are generated as nested messages
  642.  
  643. VIMSEL_NSTD_DERIVED_FORWRDS     Returns TRUE if forwarded message are generated
  644.                                 as nested messages
  645.  
  646. VIMSEL_CP850                    Returns TRUE if the IBM 850 code page is supported
  647.  
  648. VIMSEL_CP1252                   Returns TRUE if the IBM 1252 code page is supported
  649.  
  650. VIMSEL_CP437                    Returns TRUE if the IBM 437 code page is supported
  651.  
  652. VIMSEL_LMBSC                    Returns TRUE for Lotus Multi-Byte Character Set
  653.  
  654. VIMSEL_ISTRING                  Returns TRUE if Apple International strings are supported
  655.  
  656.  IMSEL_UNICODE                  Returns TRUE if Unicode multi-byte characters supported
  657.  
  658. VIMSEL_APPLESINGLE              Returns TRUE if AppleSingle file attachments are supported
  659.  
  660. VIMSEL_PATH_REQUIRED            Returns TRUE if database path must be specified
  661.  
  662. VIMSEL_NAME_REQUIRED            Returns TRUE if user name must be specified
  663.  
  664. VIMSEL_PASS_REQUIRED            Returns TRUE if the password must be specified
  665.  
  666.  
  667. ΓòÉΓòÉΓòÉ 6.2.2. Return Codes ΓòÉΓòÉΓòÉ
  668.  
  669. The RxVIMQueryCapability function returns the following values: 
  670.  
  671.         0 - Successful initialization
  672.  
  673.  
  674.  
  675. The return values from all of the function calls return a zero for success, and 
  676. non-zero for failure.  To retrieve the actual failure reason, use the 
  677. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  678. value to the actual failure text.  Using RxVIMStatus, the following values may 
  679. be returned by RxVIMQueryCapability: 
  680.  
  681.         VIMSTS_SUCCESS          Successful Initialization
  682.         VIMSTS_FAILURE          Initialization Failed
  683.  
  684.         VIMSTS_BAD_PARAM        Bad parameter passed to function
  685.         VIMSTS_BUF_TOO_SMALL    Results exceed size of return variable
  686.         VIMSTS_INVALID_SELECTOR Selector is unknown
  687.  
  688.  
  689. ΓòÉΓòÉΓòÉ 6.2.3. Example ΓòÉΓòÉΓòÉ
  690.  
  691. /* Example of using RxVIMQueryCapability */
  692.  
  693. /* The RxLoadFuncs function loads all of the VIM extensions */
  694. call RxFuncAdd 'RxLoadFuncs', 'RexxVIM', 'RxLoadFuncs'
  695. call RxLoadFuncs
  696.  
  697. /* This will establish a connection to the VIM system */
  698. rc = RxVIMInitialize()
  699.  
  700.  
  701. /* Query the VIM system for product version level */
  702. rc = RxVIMQueryCapability('VIMSEL_VERSION', 'Version')
  703. Say 'VIM Version is' Version
  704. Say
  705. /* Query the VIM system for Max Subject Line Length */
  706. rc = RxVIMQueryCapability('VIMSEL_MAX_SUBJECT_LEN', 'Subject_Length')
  707. Say 'The maximum subject line length is' Subject_Length
  708. Say
  709.  
  710.  
  711. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  712. call RxVIMDropFuncs
  713.  
  714.  
  715. ΓòÉΓòÉΓòÉ 6.3. RxVIMDefaultSessionInfo ΓòÉΓòÉΓòÉ
  716.  
  717. The RxVIMDefaultSessionInfo function obtains the default user name and database 
  718. path name.  This information can then be passed to the VIM system during a 
  719. RxVIMOpenSession. 
  720.  
  721.  
  722. ΓòÉΓòÉΓòÉ 6.3.1. Syntax ΓòÉΓòÉΓòÉ
  723.  
  724. RxVIMDefaultSessionInfo is called with two parameters.  The first parameter is 
  725. the variable to return the default path, and the second is the variable to 
  726. return the default name.  This function will return a null value if no default 
  727. session information exists. 
  728.  
  729. call RxVIMDefaultSessionInfo 'path_variable', 'name_variable'
  730.  
  731. or
  732.  
  733. rc = RxVIMDefaultSessionInfo('path_variable', 'name_variable')
  734.  
  735.  
  736. ΓòÉΓòÉΓòÉ 6.3.2. Return Codes ΓòÉΓòÉΓòÉ
  737.  
  738. The RxVIMDefaultSessionInfo function returns the following values: 
  739.  
  740.         0 - Successful initialization
  741.  
  742. The return values from all of the function calls return a zero for success, and 
  743. non-zero for failure.  To retrieve the actual failure reason, use the 
  744. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  745. value to the actual failure text.  Using RxVIMStatus, the following values may 
  746. be returned by RxVIMDefaultSessionInfo: 
  747.  
  748.         VIMSTS_SUCCESS                  Successful return
  749.         VIMSTS_FAILURE                  Function Failed
  750.  
  751.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  752.         VIMSTS_BUF_TOO_SMALL            Results exceed size of return variable
  753.         VIMSTS_INVALID_CONFIGURATION    Underlying configuration is incorrectly configured
  754.  
  755.  
  756. ΓòÉΓòÉΓòÉ 6.3.3. Example ΓòÉΓòÉΓòÉ
  757.  
  758. /* Example of using RxVIMDefaultSessionInfo */
  759.  
  760. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  761. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  762. call RxVIMLoadFuncs
  763.  
  764.  
  765. /* This will establish a connection to the VIM system */
  766. rc = RxVIMInitialize()
  767.  
  768. /* Obtain the default session information */
  769. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  770.  
  771. Say 'Default path:' db_path
  772. Say 'Default name:' user_name
  773.  
  774. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  775. call RxVIMDropFuncs
  776.  
  777.  
  778. ΓòÉΓòÉΓòÉ 6.4. RxVIMOpenSession ΓòÉΓòÉΓòÉ
  779.  
  780. The RxVIMOpenSession function establishes an active session with the VIM 
  781. system. 
  782.  
  783.  
  784. ΓòÉΓòÉΓòÉ 6.4.1. Syntax ΓòÉΓòÉΓòÉ
  785.  
  786. RxVIMOpenSession is called with four parameters.  The first parameter is the 
  787. location of the postoffice. The second is the name of the user opening the 
  788. session.  The third parameter is the password of the user opening the session. 
  789. If all of the parameters are not required, then a NULL string ('') is required 
  790. in its location.  The fourth parameter which will contain the Session handle is 
  791. required.  The session handle will be used in other calls to allow multiple 
  792. sessions to be opened concurrently. 
  793.  
  794. call RxVIMOpenSession 'location','userid','password','Session'
  795.  
  796. or
  797.  
  798. rc = RxVIMOpenSession('location','userid','password','Session')
  799.  
  800.  
  801. ΓòÉΓòÉΓòÉ 6.4.2. Return Codes ΓòÉΓòÉΓòÉ
  802.  
  803. The RxVIMOpenSession function returns the following values: 
  804.  
  805.         0 - Successful session established
  806.  
  807. The return values from all of the function calls return a zero for success, and 
  808. non-zero for failure.  To retrieve the actual failure reason, use the 
  809. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  810. value to the actual failure text.  Using RxVIMStatus, the following values may 
  811. be returned by RxVIMOpenSession: 
  812.  
  813.         VIMSTS_SUCCESS                  Successful return
  814.         VIMSTS_FAILURE                  Function Failed
  815.  
  816.         VIMSTS_ALL_PARAMS_REQUIRED      All values are required
  817.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  818.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory to open                                  VIMSTS_INVALID_CONFIGURATION    Underlying configuration is incorrectly configured
  819.         VIMSTS_INVALID_PASSWORD         Password is incorrect
  820.         VIMSTS_OPEN_FAILURE             Message system could not be opened
  821.         VIMSTS_PASS_REQUIRED            A Password is required
  822.         VIMSTS_UNSUP_VERSION            VIM version not supported
  823.  
  824.  
  825. ΓòÉΓòÉΓòÉ 6.4.3. Example ΓòÉΓòÉΓòÉ
  826.  
  827. /* Example of using RxVIMOpenSession */
  828.  
  829. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  830. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  831. call RxVIMLoadFuncs
  832.  
  833.  
  834. /* This will establish a connection to the VIM system */
  835. rc = RxVIMInitialize()
  836.  
  837. /* Obtain the default session information */
  838. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  839.  
  840. Say 'Default path:' db_path
  841. Say 'Default name:' user_name
  842.  
  843. /* Opening a session with the mail subsystem */
  844. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  845.  
  846. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  847. call RxVIMDropFuncs
  848.  
  849.  
  850. ΓòÉΓòÉΓòÉ 6.5. RxVIMGetEntityName ΓòÉΓòÉΓòÉ
  851.  
  852. The RxVIMGetEntityName function obtains the current name associated with the 
  853. active session.  It also retrieves the type of entity, and the associated 
  854. addressbook. 
  855.  
  856.  
  857. ΓòÉΓòÉΓòÉ 6.5.1. Syntax ΓòÉΓòÉΓòÉ
  858.  
  859. RxVIMGetEntityName is called with two parameters.  The first parameter is the 
  860. session handle returned from the RxVIMOpenSession function. The second 
  861. parameter is a Rexx variable that will be used as a stem variable for the three 
  862. portions of the return information.  The type of the entity will be returned in 
  863. the stem_variable.Type location.  The name of the entity will be returned in 
  864. the stem_variable.Name location.  The addressbook of the entity will be 
  865. returned in the stem_variable.AddressBook location. 
  866.  
  867. call RxVIMGetEntityName session, 'stem_variable'
  868.  
  869. or
  870.  
  871. rc = RxVIMGetEntityName(session, 'stem_variable'))
  872.  
  873.  
  874. ΓòÉΓòÉΓòÉ 6.5.2. Return Codes ΓòÉΓòÉΓòÉ
  875.  
  876. The RxVIMGetEntityName function returns the following values: 
  877.  
  878.         0 - Successful session termination
  879.  
  880. The return values from all of the function calls return a zero for success, and 
  881. non-zero for failure.  To retrieve the actual failure reason, use the 
  882. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  883. value to the actual failure text.  Using RxVIMStatus, the following values may 
  884. be returned by RxVIMGetEntityName: 
  885.  
  886.         VIMSTS_SUCCESS                  Successful return
  887.         VIMSTS_FAILURE                  Function Failed
  888.  
  889.         VIMSTS_BAD_PARAM                Invalid parameter
  890.         VIMSTS_BUF_TOO_SMALL            Name or Address too large for buffer
  891.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
  892.         VIMSTS_INVALID_CONFIGURATION    VIM subsystem is incorrectly configured
  893.         VIMSTS_INVALID_OBJECT           The session handle is bad
  894.         VIMSTS_NO_DEFAULT               NULL session is not supported
  895.  
  896.  
  897. ΓòÉΓòÉΓòÉ 6.5.3. Example ΓòÉΓòÉΓòÉ
  898.  
  899. /* Example of using RxVIMGetEntityName */
  900.  
  901. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  902. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  903. call RxVIMLoadFuncs
  904.  
  905.  
  906. /* This will establish a connection to the VIM system */
  907. rc = RxVIMInitialize()
  908.  
  909. /* Opening a session with the mail subsystem */
  910. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  911.  
  912. /* Display the type, name, and addressbook of active session */
  913. rc = RXVIMGetEntityName(Sess, 'Entity.')
  914. Say 'Active VIM Session'
  915. Say
  916. Say 'Type:        ' Entity.Type
  917. Say 'Name:        ' Entity.Name
  918. Say 'Addressbook: ' Entity.AddressBook
  919.  
  920. /* Closing the session with the mail subsystem */
  921. rc = RxVIMCloseSession()
  922.  
  923. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  924. call RxVIMDropFuncs
  925.  
  926.  
  927. ΓòÉΓòÉΓòÉ 6.6. RxVIMCloseSession ΓòÉΓòÉΓòÉ
  928.  
  929. The RxVIMCloseSession function closes the current session with the VIM system 
  930. and frees all resources.  This function should be called in any program that 
  931. issues an RxVIMOpenSession function. 
  932.  
  933.  
  934. ΓòÉΓòÉΓòÉ 6.6.1. Syntax ΓòÉΓòÉΓòÉ
  935.  
  936. RxVIMCloseSession is called with  the session handle of the session to close. 
  937.  
  938. call RxVIMCloseSession session
  939.  
  940. or
  941.  
  942. rc = RxVIMCloseSession(session)
  943.  
  944.  
  945. ΓòÉΓòÉΓòÉ 6.6.2. Return Codes ΓòÉΓòÉΓòÉ
  946.  
  947. The RxVIMCloseSession function returns the following values: 
  948.  
  949.         0 - Successful session termination
  950.  
  951. The return values from all of the function calls return a zero for success, and 
  952. non-zero for failure.  To retrieve the actual failure reason, use the 
  953. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  954. value to the actual failure text.  Using RxVIMStatus, the following values may 
  955. be returned by RxVIMCloseSession: 
  956.  
  957.         VIMSTS_SUCCESS                  Successful return
  958.         VIMSTS_FAILURE                  Function Failed
  959.  
  960.         VIMSTS_INVALID_OBJECT           The session handle is bad
  961.  
  962.  
  963. ΓòÉΓòÉΓòÉ 6.6.3. Example ΓòÉΓòÉΓòÉ
  964.  
  965. /* Example of using RxVIMCloseSession */
  966.  
  967. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  968. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  969. call RxVIMLoadFuncs
  970.  
  971.  
  972. /* This will establish a connection to the VIM system */
  973. rc = RxVIMInitialize()
  974.  
  975. /* Obtain the default session information */
  976. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  977.  
  978. Say 'Default path:' db_path
  979. Say 'Default name:' user_name
  980.  
  981. /* Opening a session with the mail subsystem */
  982. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  983.  
  984. /* Closing the session with the mail subsystem */
  985. rc = RxVIMCloseSession( Sess )
  986.  
  987. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  988. call RxVIMDropFuncs
  989.  
  990.  
  991. ΓòÉΓòÉΓòÉ 6.7. RxVIMTerminate ΓòÉΓòÉΓòÉ
  992.  
  993. The RxVIMTerminate function ends the connection to the VIM system.  This 
  994. function must be the last RexxVIM function called. 
  995.  
  996.  
  997. ΓòÉΓòÉΓòÉ 6.7.1. Syntax ΓòÉΓòÉΓòÉ
  998.  
  999. RxVIMTerminate is called with no parameters. 
  1000.  
  1001. call RxVIMTerminate
  1002.  
  1003. or
  1004.  
  1005. rc = RxVIMTerminate()
  1006.  
  1007.  
  1008. ΓòÉΓòÉΓòÉ 6.7.2. Return Codes ΓòÉΓòÉΓòÉ
  1009.  
  1010. The RxVIMTerminate function returns the following values: 
  1011.  
  1012. 0 - Successful session termination
  1013.  
  1014. The return values from all of the function calls return a zero for success, and 
  1015. non-zero for failure.  To retrieve the actual failure reason, use the 
  1016. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1017. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1018. be returned by RxVIMTerminate: 
  1019.  
  1020.         VIMSTS_SUCCESS                  Successful return
  1021.         VIMSTS_FAILURE                  Function Failed
  1022.  
  1023.  
  1024. ΓòÉΓòÉΓòÉ 6.7.3. Example ΓòÉΓòÉΓòÉ
  1025.  
  1026. /* Example of using RxVIMTerminate */
  1027.  
  1028. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1029. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1030. call RxVIMLoadFuncs
  1031.  
  1032. /* This will establish a connection to the VIM system */
  1033. rc = RxVIMInitialize()
  1034.  
  1035. /* This will terminate the connection to the VIM system */
  1036. rc = RxVIMTerminate()
  1037.  
  1038. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1039. call RxVIMDropFuncs
  1040.  
  1041.  
  1042. ΓòÉΓòÉΓòÉ 6.8. RxVIMStatusText ΓòÉΓòÉΓòÉ
  1043.  
  1044. The RxVIMStatusText function converts RexxVIM return values into the 
  1045. corresponding text message.  The function allows the program to operate on the 
  1046. VIM Status messages without decoding the actual return value. 
  1047.  
  1048.  
  1049. ΓòÉΓòÉΓòÉ 6.8.1. Syntax ΓòÉΓòÉΓòÉ
  1050.  
  1051. RxVIMStatusText is called with three parameters. The first parameter is the 
  1052. session handle for the session to use for the function call.  The second 
  1053. parameter is the status code in which text information is desired.  The third 
  1054. parameter is a Rexx variable that will be used as a stem variable for the two 
  1055. portions of the return text.  The VIM status code will be returned in the 
  1056. stem_variable.1 location.  The extended text will be returned in the 
  1057. stem_variable.2 location.  Not all status code have both parts, in which case a 
  1058. null will be returned for extended text. 
  1059.  
  1060. call RxVIMStatusText session, 'Status', 'stem_variable'
  1061.  
  1062. or
  1063.  
  1064. rc = RxVIMStatusText(session, 'Status', 'stem_variable')
  1065.  
  1066.  
  1067. ΓòÉΓòÉΓòÉ 6.8.2. Return Codes ΓòÉΓòÉΓòÉ
  1068.  
  1069. The RxVIMStatusText function returns the following values: 
  1070.  
  1071.         0 - Successful session termination
  1072.  
  1073. The return values from all of the function calls return a zero for success, and 
  1074. non-zero for failure.  To retrieve the actual failure reason, use the 
  1075. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1076. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1077. be returned by RxVIMStatusText: 
  1078.  
  1079.         VIMSTS_SUCCESS                  Successful return
  1080.         VIMSTS_FAILURE                  Function Failed
  1081.  
  1082.         VIMSTS_NOT_SUPPORTED            Error text strings are not supported
  1083.  
  1084.  
  1085. ΓòÉΓòÉΓòÉ 6.8.3. Example ΓòÉΓòÉΓòÉ
  1086.  
  1087. /* Example of using RxVIMStatusText */
  1088.  
  1089. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1090. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1091. call RxVIMLoadFuncs
  1092.  
  1093.  
  1094. /* This will establish a connection to the VIM system */
  1095. rc = RxVIMInitialize()
  1096.  
  1097. /* Opening a session with the mail subsystem */
  1098. Sess = ''
  1099. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  1100.  
  1101. /* Display the type, name, and addressbook of active session */
  1102. Init = RXVIMGetEntityName(Sess, 'Entity.')
  1103.  
  1104. /* This will print the text associated with the return code */
  1105. /* from the above function call.  It will also print the    */
  1106. /* extended status if it exists.                            */
  1107.  
  1108. rc = RxVIMStatusText(Sess, Init, 'status')
  1109.  
  1110. Say 'Return Status:   ' status.1
  1111. if LENGTH(status.2) > 0 then do
  1112.    Say 'Extended Status: ' status.2
  1113. end
  1114.  
  1115. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1116. call RxVIMDropFuncs
  1117.  
  1118.  
  1119. ΓòÉΓòÉΓòÉ 7. Message Creation and Submission Functions ΓòÉΓòÉΓòÉ
  1120.  
  1121. This section describes each of the functions available in the RexxVIM product 
  1122. that address message creation and submission features. 
  1123.  
  1124. Below are all of the Message Creation and Submission functions: 
  1125.  
  1126. RxVIMCreateMessage 
  1127.  
  1128. RxVIMCreateDerivedMailMessage 
  1129.  
  1130. RxVIMSetMessageHeader 
  1131.  
  1132. RxVIMSetMessageRecipient 
  1133.  
  1134. RxVIMSetMessageItem 
  1135.  
  1136. RxVIMSendMessage 
  1137.  
  1138. RxVIMCloseMessage 
  1139.  
  1140.  
  1141. ΓòÉΓòÉΓòÉ 7.1. RxVIMCreateMessage ΓòÉΓòÉΓòÉ
  1142.  
  1143. The RxVIMCreateMessage function creates a new message area and prepares it for 
  1144. composition. 
  1145.  
  1146.  
  1147. ΓòÉΓòÉΓòÉ 7.1.1. Syntax ΓòÉΓòÉΓòÉ
  1148.  
  1149. RxVIMCreateMessage is called with three parameters.  The first parameter is the 
  1150. session handle.  The second parameter is the type of message being created. 
  1151. VIM_MAIL will be used for all mail messages.  The third parameter is the 
  1152. variable to contain the message handle. 
  1153.  
  1154. call RxVIMCreateMessage session, 'VIM_MAIL', 'Message'
  1155.  
  1156. or
  1157.  
  1158. rc = RxVIMCreateMessage(session, 'VIM_MAIL', 'Message')
  1159.  
  1160.  
  1161. ΓòÉΓòÉΓòÉ 7.1.2. Return Codes ΓòÉΓòÉΓòÉ
  1162.  
  1163. The RxVIMCreateMessage function returns the following values: 
  1164.  
  1165.         0 - Successful session termination
  1166.  
  1167. The return values from all of the function calls return a zero for success, and 
  1168. non-zero for failure.  To retrieve the actual failure reason, use the 
  1169. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1170. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1171. be returned by RxVIMCreateMessage: 
  1172.  
  1173.         VIMSTS_SUCCESS                  Successful return
  1174.         VIMSTS_FAILURE                  Function Failed
  1175.  
  1176.         VIMSTS_BAD_PARAM                Invalid parameter
  1177.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
  1178.         VIMSTS_INVALID_OBJECT           The session handle is bad
  1179.         VIMSTS_UNSUP_TYPE               The type passed is not supported
  1180.  
  1181.  
  1182. ΓòÉΓòÉΓòÉ 7.1.3. Example ΓòÉΓòÉΓòÉ
  1183.  
  1184. /* Example of using RxVIMCreateMessage */
  1185.  
  1186. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1187. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1188. call RxVIMLoadFuncs
  1189.  
  1190.  
  1191. /* This will establish a connection to the VIM system */
  1192. rc = RxVIMInitialize()
  1193.  
  1194. /* Opening a session with the mail subsystem */
  1195. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  1196.  
  1197. /* Create a new message for composition */
  1198. rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')
  1199.  
  1200. /* NOTE:                                                   */
  1201. /* Message will be discarded, since the program is closing */
  1202. /* the session without processing the message              */
  1203.  
  1204. /* Closing the session with the mail subsystem */
  1205. rc = RxVIMCloseSession()
  1206.  
  1207. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1208. call RxVIMDropFuncs
  1209.  
  1210.  
  1211. ΓòÉΓòÉΓòÉ 7.2. RxVIMCreateDerivedMailMessage ΓòÉΓòÉΓòÉ
  1212.  
  1213. The RxVIMCreateDerivedMailMessage function uses the contents of an existing 
  1214. message to create a new message.  This function can be used to create forwarded 
  1215. messages, and replies that include the original message content. 
  1216.  
  1217.  
  1218. ΓòÉΓòÉΓòÉ 7.2.1. Syntax ΓòÉΓòÉΓòÉ
  1219.  
  1220. RxVIMCreateDerivedMailMessage is called with four parameters.  The first 
  1221. parameter is the handle of the original message to create the derived message. 
  1222. The second parameter is the type of message being created.  The third parameter 
  1223. is a flag to indicate options for the message.  The fourth parameter is the 
  1224. variable to contain the message handle of the derived message. 
  1225.  
  1226. call RxVIMCreateDerivedMailMessage MsgPtr, 'type', 'flags', 'Message'
  1227.  
  1228. or
  1229.  
  1230. rc = RxVIMCreateDerivedMailMessage(session, 'type', 'flags', 'Message')
  1231.  
  1232. Listed below are the valid selectors to indicate the type of derived message: 
  1233.  
  1234. VIMSEL_FORWARD                  Message will be directed to new recipients
  1235.  
  1236. VIMSEL_REPLY                    Message will be returned to sender
  1237.  
  1238. Listed below are the valid flags to indicate the style of derived message: 
  1239.  
  1240. VIM_NO_FLAGS                    No flags specified
  1241.  
  1242. VIM_HISTORY                     Previous forwarding history to be maintained
  1243.                                 (For VIMSEL_FORWARD)
  1244.  
  1245. VIM_INHERIT_CONTENTS            Previous contents will be maintained with new
  1246.                                 message (For VIMSEL_REPLY)
  1247.  
  1248. VIM_ALL_RECIPIENTS              New message will be returned to all recipients,
  1249.                                 not just the sender (For VIMSEL_REPLY)
  1250.  
  1251.  
  1252. ΓòÉΓòÉΓòÉ 7.2.2. Return Codes ΓòÉΓòÉΓòÉ
  1253.  
  1254. The RxVIMCreateDerivedMailMessage function returns the following values: 
  1255.  
  1256. 0 - Successful session termination
  1257.  
  1258. The return values from all of the function calls return a zero for success, and 
  1259. non-zero for failure.  To retrieve the actual failure reason, use the 
  1260. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1261. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1262. be returned by RxVIMCreateDerivedMailMessage: 
  1263.  
  1264.         VIMSTS_SUCCESS                  Successful return
  1265.         VIMSTS_FAILURE                  Function Failed
  1266.  
  1267.         VIMSTS_BAD_PARAM                Invalid parameter
  1268.         VIMSTS_INVALID_OBJECT           The message handle is bad
  1269.         VIMSTS_INVALID_SELECTOR         The type is bad
  1270.  
  1271.  
  1272. ΓòÉΓòÉΓòÉ 7.2.3. Example ΓòÉΓòÉΓòÉ
  1273.  
  1274. /* Example of using RxVIMCreateDerivedMailMessage */
  1275.  
  1276. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1277. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1278. call RxVIMLoadFuncs
  1279.  
  1280.  
  1281. /* This will establish a connection to the VIM system */
  1282. rc = RxVIMInitialize()
  1283.  
  1284. /* Opening a session with the mail subsystem */
  1285. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  1286.  
  1287. /* Open the default message container (Inbox) */
  1288. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  1289.  
  1290. /* Retrieve the first message from the container pulling the */
  1291. /* message reference number only                             */
  1292. attrDesc.0 = 1
  1293. attrDesc.selector = 'VIMSEL_REF'
  1294. attrDesc.buffer   = 'refno'
  1295.  
  1296. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  1297.                             '','VIM_NO_FLAGS','more')
  1298.  
  1299. /* Open the first message */
  1300. rc = RxVIMOpenMessage(MsgCont,refno.1,'','OldMsg')
  1301.  
  1302.  
  1303.  
  1304. /* Create a forward message for composition */
  1305. rc = RxVIMCreateDerivedMailMessage(OldMsg, 'VIM_FORWARD', 'VIM_NO_FLAGS', 'Message')
  1306.  
  1307.  
  1308.  
  1309. /* NOTE:                                                   */
  1310. /* Message will be discarded, since the program is closing */
  1311. /* the session without processing the message              */
  1312.  
  1313. /* Closing the session with the mail subsystem */
  1314. rc = RxVIMCloseSession()
  1315.  
  1316. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1317. call RxVIMDropFuncs
  1318.  
  1319.  
  1320. ΓòÉΓòÉΓòÉ 7.3. RxVIMSetMessageHeader ΓòÉΓòÉΓòÉ
  1321.  
  1322. The RxVIMSetMessageHeader function sets the value of message attributes.  This 
  1323. function is used to set attributes such as subject, priority, and return 
  1324. receipt. 
  1325.  
  1326.  
  1327. ΓòÉΓòÉΓòÉ 7.3.1. Syntax ΓòÉΓòÉΓòÉ
  1328.  
  1329. The RxVIMSetMessageHeader function is called with three parameters.  The first 
  1330. parameter is the message handle from the RxVIMCreateMessage function call.  The 
  1331. second parameter is the selector for the attribute to set, and the third is the 
  1332. value for the attribute. 
  1333.  
  1334. call RxVIMSetMessageHeader message, 'selector', 'value'
  1335.  
  1336. or
  1337.  
  1338. rc = RxVIMSetMessageHeader(message, 'selector', 'value')
  1339.  
  1340. Listed below are the valid selectors to use to set message header attributes: 
  1341.  
  1342. VIMSEL_SUBJECT                  Sets the text for the subject up to
  1343.                                 the maximum supported.  Use the
  1344.                                 RxVIMQueryCapability to determine
  1345.                                 maximum length.
  1346.  
  1347. VIMSEL_PRIORITY                 Sets the importance of the message.
  1348.                                 Valid options are:
  1349.  
  1350.                                 VIMSEL_LOW_PRIORITY
  1351.                                 VIMSEL_NORMAL_PRIORITY  (default value)
  1352.                                 VIMSEL_HIGH_PRIORITY
  1353.  
  1354. VIMSEL_DELIVERY_REPORT          If supported, this attribute will
  1355.                                 report the delivery for each recipient
  1356.                                 a successful delivery is made.  Valid
  1357.                                 options to pass are:
  1358.  
  1359.                                 VIM_TRUE
  1360.                                 VIM_FALSE
  1361.  
  1362. VIMSEL_NONDELIVERY_REPORT       If supported, this attribute will
  1363.                                 report the delivery for each recipient
  1364.                                 a unsuccessful delivery is made.  Valid
  1365.                                 options to pass are:
  1366.  
  1367.                                 VIM_TRUE
  1368.                                 VIM_FALSE
  1369.  
  1370. VIMSEL_NONDELIVERY_CONTENTS     If supported, this attribute will
  1371.                                 report the delivery for each recipient
  1372.                                 a unsuccessful delivery is made. The
  1373.                                 report will include the contents of
  1374.                                 the original message. Valid options to
  1375.                                 pass are:
  1376.  
  1377.                                 VIM_TRUE
  1378.                                 VIM_FALSE
  1379.  
  1380. VIMSEL_ENCRYPT                  If supported, this attribute will
  1381.                                 cause the message to be encrypted with
  1382.                                 an implicit key.  Valid options to
  1383.                                 pass are:
  1384.  
  1385.                                 VIM_TRUE
  1386.                                 VIM_FALSE
  1387.  
  1388. VIMSEL_ENCRYPT_WITH_KEY         If supported, this attribute will
  1389.                                 cause the message to be encrypted with
  1390.                                 an explicit key.  Valid options to
  1391.                                 pass are:
  1392.  
  1393.                                 VIM_TRUE
  1394.                                 VIM_FALSE
  1395.  
  1396. VIMSEL_SIGN                     If supported, this attribute will
  1397.                                 cause the message to be signed.
  1398.                                 Valid options to pass are:
  1399.  
  1400.                                 VIM_TRUE
  1401.                                 VIM_FALSE
  1402.  
  1403. VIMSEL_CONVERSATION_ID          If supported, this attribute will
  1404.                                 set the conversation id.
  1405.  
  1406. VIMSEL_SENSITIVITY              If supported, this attribute will
  1407.                                 set the sensitivity of the message.
  1408.                                 Valid options to pass are:
  1409.  
  1410.                                 VIMSEL_NORMAL_SENS
  1411.                                 VIMSEL_PRIVATE_SENS
  1412.                                 VIMSEL_PERSONAL_SENS
  1413.                                 VIMSEL_CO_CONFID_SENS
  1414.  
  1415. VIMSEL_IN_REPLY_TO              If supported, this attribute will
  1416.                                 set id of the message that the current
  1417.                                 message is in reply to.
  1418.  
  1419. VIMSEL_RESPOND_BY               If supported, this attribute will
  1420.                                 set date the message must responded to.
  1421.  
  1422. VIMSEL_KEYWORD                  If supported, this attribute will
  1423.                                 set a keyword for the current message.
  1424.  
  1425. VIMSEL_RETURN_RECEIPT           This attribute sets the request for
  1426.                                 a return receipt on/off.  Valid
  1427.                                 options to pass are:
  1428.  
  1429.                                 VIM_TRUE
  1430.                                 VIM_FALSE
  1431.  
  1432. VIMSEL_SAVE                     This attribute sets the request for
  1433.                                 a copy of the message to be saved
  1434.                                 when it is sent. Valid options to
  1435.                                 pass are:
  1436.  
  1437.                                 VIM_TRUE
  1438.                                 VIM_FALSE
  1439.  
  1440. VIMSEL_DRAFT                    This attribute sets the message to
  1441.                                 a draft.  If the session is closed
  1442.                                 without the message being sent, a
  1443.                                 copy will be saved. Valid options to
  1444.                                 pass are:
  1445.  
  1446.                                 VIM_TRUE
  1447.                                 VIM_FALSE
  1448.  
  1449.  
  1450. ΓòÉΓòÉΓòÉ 7.3.2. Return Codes ΓòÉΓòÉΓòÉ
  1451.  
  1452. The RxVIMSetMessageHeader function returns the following values: 
  1453.  
  1454.         0 - Successful return
  1455.  
  1456. The return values from all of the function calls return a zero for success, and 
  1457. non-zero for failure.  To retrieve the actual failure reason, use the 
  1458. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1459. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1460. be returned by RxVIMSetMessageHeader: 
  1461.  
  1462.         VIMSTS_SUCCESS                  Successful return
  1463.         VIMSTS_FAILURE                  Function Failed
  1464.  
  1465.         VIMSTS_BAD_PARAM                Invalid parameter
  1466.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
  1467.         VIMSTS_INVALID_OBJECT           The session handle is bad
  1468.         VIMSTS_INVALID_SELECTOR         The selector passed is not valid
  1469.         VIMSTS_NOT_SUPPORTED            The selector passed is not supported
  1470.  
  1471.  
  1472. ΓòÉΓòÉΓòÉ 7.3.3. Example ΓòÉΓòÉΓòÉ
  1473.  
  1474. /* Example of using RxVIMSetMessageHeader */
  1475.  
  1476. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1477. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1478. call RxVIMLoadFuncs
  1479.  
  1480.  
  1481. /* This will establish a connection to the VIM system */
  1482. rc = RxVIMInitialize()
  1483.  
  1484. /* Opening a session with the mail subsystem */
  1485. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  1486.  
  1487. /* Create a new message */
  1488. rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')
  1489.  
  1490. /* Set the subject of the message */
  1491. rc = RxVIMSetMessageHeader(Message, 'VIMSEL_SUBJECT', 'This will be the subject')
  1492.  
  1493. /* NOTE:                                                   */
  1494. /* Message will be discarded, since the program is closing */
  1495. /* the session without processing the message              */
  1496.  
  1497. /* Closing the session with the mail subsystem */
  1498. rc = RxVIMCloseSession( Sess )
  1499.  
  1500. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1501. call RxVIMDropFuncs
  1502.  
  1503.  
  1504. ΓòÉΓòÉΓòÉ 7.4. RxVIMSetMessageRecipient ΓòÉΓòÉΓòÉ
  1505.  
  1506. The RxVIMSetMessageRecipient function adds values to the list of addressees for 
  1507. the active message. 
  1508.  
  1509.  
  1510. ΓòÉΓòÉΓòÉ 7.4.1. Syntax ΓòÉΓòÉΓòÉ
  1511.  
  1512. The RxVIMSetMessageRecipient function is called with eight parameters.  The 
  1513. first parameter is the message handle.  The second parameter is the selector 
  1514. for the class of the recipient of the message.  The third parameter is the type 
  1515. of recipient. 
  1516.  
  1517. The recipient of the message can be specified in one of two ways, either a name 
  1518. entry or an addressbook entry.  If both are specified, the VIM system will use 
  1519. the addressbook entry only.  The fourth, fifth and sixth parameters are used to 
  1520. specify a name entry.  The seventh and eighth parameters are used to specify an 
  1521. adressbook entry. 
  1522.  
  1523. The fourth parameter is the type of entity, the fifth parameter is the 
  1524. addressbook for the entity, and the sixth parameter is the value of the entity. 
  1525.  
  1526. To specify the recipient as an addressbook entry, the seventh parameter is the 
  1527. type of address, and the eighth is the value of the entry. 
  1528.  
  1529. call RxVIMSetMessageRecipient message,'selector','entity_type','','',,
  1530.                               'user_name','',''
  1531.  
  1532. or
  1533.  
  1534. rc = RxVIMSetMessageRecipient(message,'selector','entity_type','','',,
  1535.                               'user_name','','')
  1536.  
  1537. Listed below are the valid selectors to use to set message class attributes: 
  1538.  
  1539. VIMSEL_TO                       Sets the recipient as a primary
  1540.                                 addressee for the message.
  1541.  
  1542. VIMSEL_CC                       Sets the recipient to receive a
  1543.                                 copy of the message.
  1544.  
  1545. VIMSEL_BCC                      Sets the recipient to receive
  1546.                                 a copy of the message, and not
  1547.                                 appear as a listed recipient.
  1548.  
  1549. Listed below are the valid selectors to use to set recipient type: 
  1550.  
  1551. VIMSEL_ENTITY                   Sets the type to a person entity
  1552.  
  1553. VIMSEL_GROUP                    Sets the type to a collection of
  1554.                                 entities.
  1555.  
  1556. VIMSEL_UNKNOWN_RECIP_TYPE       Sets the type to unknown.
  1557.  
  1558.  
  1559. ΓòÉΓòÉΓòÉ 7.4.2. Return Codes ΓòÉΓòÉΓòÉ
  1560.  
  1561. The RxVIMSetMessageRecipient function returns the following values: 
  1562.  
  1563.         0 - Successful return
  1564.  
  1565. The return values from all of the function calls return a zero for success, and 
  1566. non-zero for failure.  To retrieve the actual failure reason, use the 
  1567. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1568. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1569. be returned by RxVIMSetMessageRecipient: 
  1570.  
  1571.         VIMSTS_SUCCESS                  Successful return
  1572.         VIMSTS_FAILURE                  Function Failed
  1573.  
  1574.         VIMSTS_BAD_PARAM                Invalid parameter
  1575.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
  1576.         VIMSTS_INVALID_OBJECT           The session handle is bad
  1577.         VIMSTS_INVALID_SELECTOR         The selector passed is not valid
  1578.         VIMSTS_NAME_NOT_FOUND           The name passed was not found
  1579.         VIMSTS_WRITE_FAILURE            Could not write to the disk
  1580.  
  1581.  
  1582. ΓòÉΓòÉΓòÉ 7.4.3. Example ΓòÉΓòÉΓòÉ
  1583.  
  1584. /* Example of using RxVIMSetMessageRecipient */
  1585.  
  1586. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1587. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1588. call RxVIMLoadFuncs
  1589.  
  1590.  
  1591. /* This will establish a connection to the VIM system */
  1592. rc = RxVIMInitialize()
  1593.  
  1594. /* Opening a session with the mail subsystem */
  1595. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  1596.  
  1597. /* Create a new message */
  1598. rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')
  1599.  
  1600. /* Set the message to send back to creator id */
  1601. rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
  1602.                               'Mark Stevens','','')
  1603.  
  1604. /* NOTE:                                                   */
  1605. /* Message will be discarded, since the program is closing */
  1606. /* the session without processing the message              */
  1607.  
  1608. /* Closing the session with the mail subsystem */
  1609. rc = RxVIMCloseSession( Sess )
  1610.  
  1611. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1612. call RxVIMDropFuncs
  1613.  
  1614.  
  1615. ΓòÉΓòÉΓòÉ 7.4.4. RxVIMSetMessageItem ΓòÉΓòÉΓòÉ
  1616.  
  1617. The RxVIMSetMessageItem function adds an item to the list of attachments for 
  1618. the active message.  This function allows items such as text, file attachments, 
  1619. etc. to be added to the content of the current message. 
  1620.  
  1621.  
  1622. ΓòÉΓòÉΓòÉ 7.4.5. Syntax ΓòÉΓòÉΓòÉ
  1623.  
  1624. The RxVIMSetMessageItem function is called with seven parameters.  The first 
  1625. parameter is the message handle. 
  1626.  
  1627. The second parameter is the selector for the class of the item being added to 
  1628. the message.  The third parameter is the 
  1629.  
  1630. type of the item being added to the message.  The fourth parameter is a 
  1631. selector value to set flags for the message item if it is a file attachment. 
  1632. The fifth parameter is the name of the message item.  For note parts, this will 
  1633. be the title of the item.  For file attachments, this will be the name that is 
  1634. used to specify the attachment. 
  1635.  
  1636. An item being added to a message can be specified in one of two ways, either by 
  1637. passing the contents of the item, or a filename. 
  1638.  
  1639. To specify the item contents directly, the sixth parameter is used to pass the 
  1640. contents.  If the item will be specified as a file, the sixth parameter should 
  1641. be set to NULL. 
  1642.  
  1643. To specify the item as a file, the seventh parameter is the name of the file. 
  1644. If the item will be passed directly, this parameter should be set to NULL. 
  1645.  
  1646. call RxVIMSetMessageItem message,'selector','item_type','flag','title',,
  1647.                               'content_buffer','filename'
  1648.  
  1649. or
  1650.  
  1651. call RxVIMSetMessageItem(message,'selector','item_type','flag','title',,
  1652.                               'content_buffer','filename')
  1653.  
  1654. Listed below are the valid selectors to use to set item class attributes: 
  1655.  
  1656. VIMSEL_NOTE_PART                Sets the item as part of a text note
  1657.  
  1658. VIMSEL_ATTACH                   Sets the item as an attachment, item
  1659.                                 type is ignored
  1660.  
  1661. VIMSEL_APP_DEFINED              Sets the item to be determined by
  1662.                                 the application
  1663.  
  1664. Listed below are the valid selectors to use to set item type: 
  1665.  
  1666. VIM_TEXT                        Sets the type to ASCII text
  1667.  
  1668. VIM_UNWRAPPED_TEXT              Sets the type to unwrapped text which
  1669.                                 terminates each paragraph with CR/LF.
  1670.  
  1671. VIM_RTF                         Sets the type to Microsoft rich-text
  1672.  
  1673. VIM_STYLED                      Sets the type to Macintosh text
  1674.  
  1675. VIM_FAX                         Sets the type to PCX-format fax image
  1676.  
  1677. VIM_PICT                        Sets the type to Macintosh picture
  1678.  
  1679. VIM_MOVIE                       Sets the type to QuickTime sound/video
  1680.  
  1681. VIM_IMAGE                       Sets the type to Macintosh-fax-image
  1682.  
  1683. Listed below are the valid selectors to use to set item flag attributes: 
  1684.  
  1685. VIMSEL_NATIVE                   Flag to indicate that file is in the
  1686.                                 native format of the system
  1687.  
  1688. VIMSEL_APPLESINGLE              Flag to indicate that file is in the
  1689.                                 Apple stream format
  1690.  
  1691.  
  1692. ΓòÉΓòÉΓòÉ 7.4.6. Return Codes ΓòÉΓòÉΓòÉ
  1693.  
  1694. The RxVIMSetMessageItem function returns the following values: 
  1695.  
  1696.         0 - Successful return
  1697.  
  1698. The return values from all of the function calls return a zero for success, and 
  1699. non-zero for failure.  To retrieve the actual failure reason, use the 
  1700. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1701. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1702. be returned by RxVIMSetMessageItem: 
  1703.  
  1704.         VIMSTS_SUCCESS                  Successful return
  1705.         VIMSTS_FAILURE                  Function Failed
  1706.  
  1707.         VIMSTS_ATTACHMENT_NOT_FOUND     File attachment not available
  1708.         VIMSTS_BAD_PARAM                Invalid parameter
  1709.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
  1710.         VIMSTS_INVALID_OBJECT           The session handle is bad
  1711.         VIMSTS_INVALID_SELECTOR         The selector passed is not valid
  1712.         VIMSTS_OPEN_FAILURE             Cannot open specified file
  1713.         VIMSTS_READ_FAILURE             Cannot read from the disk
  1714.         VIMSTS_UNSUP_TYPE               Type value unknown
  1715.         VIMSTS_WRITE_FAILURE            Could not write to the disk
  1716.  
  1717.  
  1718. ΓòÉΓòÉΓòÉ 7.4.7. Example ΓòÉΓòÉΓòÉ
  1719.  
  1720. /* Example of using RxVIMSetMessageItem */
  1721.  
  1722. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1723. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1724. call RxVIMLoadFuncs
  1725.  
  1726.  
  1727. /* This will establish a connection to the VIM system */
  1728. rc = RxVIMInitialize()
  1729.  
  1730. /* Opening a session with the mail subsystem */
  1731. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  1732.  
  1733. /* Create a new message */
  1734. rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')
  1735.  
  1736. /* Add text to the message */
  1737. rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
  1738.          'Test Text','Hey!  This is text passed directly....', '')
  1739.  
  1740. /* NOTE:                                                   */
  1741. /* Message will be discarded, since the program is closing */
  1742. /* the session without processing the message              */
  1743.  
  1744. /* Closing the session with the mail subsystem */
  1745. rc = RxVIMCloseSession( Sess )
  1746.  
  1747. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1748. call RxVIMDropFuncs
  1749.  
  1750.  
  1751. ΓòÉΓòÉΓòÉ 7.5. RxVIMSendMessage ΓòÉΓòÉΓòÉ
  1752.  
  1753. The RxVIMSendMessage function submits the active message to the VIM system for 
  1754. processing and closes the message. 
  1755.  
  1756.  
  1757. ΓòÉΓòÉΓòÉ 7.5.1. Syntax ΓòÉΓòÉΓòÉ
  1758.  
  1759. RxVIMSendMessage is called with the message handle to send. 
  1760.  
  1761. call RxVIMSendMessage Message
  1762.  
  1763. or
  1764.  
  1765. rc = RxVIMSendMessage( Message )
  1766.  
  1767.  
  1768. ΓòÉΓòÉΓòÉ 7.5.2. Return Codes ΓòÉΓòÉΓòÉ
  1769.  
  1770. The RxVIMSendMessage function returns the following values: 
  1771.  
  1772.         0 - Successful session termination
  1773.  
  1774. The return values from all of the function calls return a zero for success, and 
  1775. non-zero for failure.  To retrieve the actual failure reason, use the 
  1776. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1777. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1778. be returned by RxVIMSendMessage: 
  1779.  
  1780.         VIMSTS_SUCCESS                  Successful return
  1781.         VIMSTS_FAILURE                  Function Failed
  1782.  
  1783.         VIMSTS_BAD_PARAM                Invalid parameter
  1784.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory for function
  1785.         VIMSTS_INVALID_OBJECT           The session handle is bad
  1786.         VIMSTS_NOT_SUPPORTED            Callbacks not supported
  1787.         VIMSTS_WRITE_FAILURE            Could not write to the disk
  1788.  
  1789.  
  1790. ΓòÉΓòÉΓòÉ 7.5.3. Example ΓòÉΓòÉΓòÉ
  1791.  
  1792. /* Example of using RxVIMSendMessage */
  1793.  
  1794. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1795. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1796. call RxVIMLoadFuncs
  1797.  
  1798.  
  1799. /* This will establish a connection to the VIM system */
  1800. rc = RxVIMInitialize()
  1801.  
  1802. /* Opening a session with the mail subsystem */
  1803. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', 'Sess')
  1804.  
  1805. /* Create a new message for composition */
  1806. rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')
  1807.  
  1808. /* Set the message to send back to creator id */
  1809. rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
  1810.                               'Mark Stevens','','')
  1811.  
  1812. /* Add text to the message */
  1813. rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
  1814.          'Test Text','Hey!  This is text passed directly....', '')
  1815.  
  1816. /* Send the message */
  1817. rc = RxVIMSendMessage( Message )
  1818.  
  1819. /* Closing the session with the mail subsystem */
  1820. rc = RxVIMCloseSession( Sess )
  1821.  
  1822. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1823. call RxVIMDropFuncs
  1824.  
  1825.  
  1826. ΓòÉΓòÉΓòÉ 7.6. RxVIMCloseMessage ΓòÉΓòÉΓòÉ
  1827.  
  1828. The RxVIMCloseMessage function closes the active message and frees any 
  1829. associated resources.  If the message type is not VIMSEL_DRAFT, the message is 
  1830. discarded.  VIMSEL_DRAFT messages are saved for later retrieval as a draft 
  1831. message. 
  1832.  
  1833.  
  1834. ΓòÉΓòÉΓòÉ 7.6.1. Syntax ΓòÉΓòÉΓòÉ
  1835.  
  1836. RxVIMCloseMessage is called with the message handle to close. 
  1837.  
  1838. call RxVIMCloseMessage Message
  1839.  
  1840. or
  1841.  
  1842. rc = RxVIMCloseMessage( Message )
  1843.  
  1844.  
  1845. ΓòÉΓòÉΓòÉ 7.6.2. Return Codes ΓòÉΓòÉΓòÉ
  1846.  
  1847. The RxVIMCloseMessage function returns the following values: 
  1848.  
  1849.         0 - Successful session termination
  1850.  
  1851. The return values from all of the function calls return a zero for success, and 
  1852. non-zero for failure.  To retrieve the actual failure reason, use the 
  1853. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1854. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1855. be returned by RxVIMCloseMessage: 
  1856.  
  1857.         VIMSTS_SUCCESS                  Successful return
  1858.         VIMSTS_FAILURE                  Function Failed
  1859.  
  1860.         VIMSTS_INVALID_OBJECT           The message handle is bad
  1861.  
  1862.  
  1863. ΓòÉΓòÉΓòÉ 7.6.3. Example ΓòÉΓòÉΓòÉ
  1864.  
  1865. /* Example of using RxVIMCloseMessage */
  1866.  
  1867. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1868. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1869. call RxVIMLoadFuncs
  1870.  
  1871.  
  1872. /* This will establish a connection to the VIM system */
  1873. rc = RxVIMInitialize()
  1874.  
  1875. /* Opening a session with the mail subsystem */
  1876. rc = RxVIMOpenSession('db_path', 'Mark Stevens', 'SNOOPY', "Sess')
  1877.  
  1878. /* Create a new message for composition */
  1879. rc = RxVIMCreateMessage(Sess, 'VIM_MAIL', 'Message')
  1880.  
  1881. /* Set the message to send back to creator id */
  1882. rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
  1883.                               'Mark Stevens','','')
  1884.  
  1885. /* Add text to the message */
  1886. rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
  1887.          'Test Text','Hey!  This is text passed directly....','')
  1888.  
  1889. /* Close the message without sending .... message will be discarded */
  1890. rc = RxVIMCloseMessage( Message )
  1891.  
  1892. /* Closing the session with the mail subsystem */
  1893. rc = RxVIMCloseSession( Sess )
  1894.  
  1895. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1896. call RxVIMDropFuncs
  1897.  
  1898.  
  1899. ΓòÉΓòÉΓòÉ 8. Message Container Functions ΓòÉΓòÉΓòÉ
  1900.  
  1901. This section describes each of the functions available in the RexxVIM product 
  1902. that address message container features. 
  1903.  
  1904. Below are all of the Message Container functions: 
  1905.  
  1906. RxVIMOpenMessageContainer 
  1907.  
  1908. RxVIMEnumerateMessages 
  1909.  
  1910. RxVIMSetMessageCategory 
  1911.  
  1912. RxVIMRemoveMessageCategory 
  1913.  
  1914. RxVIMQueryNewMessages 
  1915.  
  1916. RxVIMQueryUnreadMailCount 
  1917.  
  1918. RxVIMRemoveMessage 
  1919.  
  1920. RxVIMCloseMessageContainer 
  1921.  
  1922.  
  1923. ΓòÉΓòÉΓòÉ 8.1. RxVIMOpenMessageContainer ΓòÉΓòÉΓòÉ
  1924.  
  1925. The RxVIMOpenMessageContainer function opens the specified message container 
  1926. with the VIM system. 
  1927.  
  1928.  
  1929. ΓòÉΓòÉΓòÉ 8.1.1. Syntax ΓòÉΓòÉΓòÉ
  1930.  
  1931. RxVIMOpenMessageContainer is called with three parameters.  The first parameter 
  1932. is the session to be used to open the message container.  The second is the 
  1933. name of the message container to open.  A null ('') for the name will cause the 
  1934. system to open the default message container.  The third parameter is the 
  1935. variable name for the call to return a pointer to the message container. 
  1936.  
  1937. call RxVIMOpenMessageContainer Session, 'container', 'MsgPtr'
  1938.  
  1939. or
  1940.  
  1941. rc = RxVIMOpenMessageContainer(Session,'container','MsgPtr')
  1942.  
  1943.  
  1944. ΓòÉΓòÉΓòÉ 8.1.2. Return Codes ΓòÉΓòÉΓòÉ
  1945.  
  1946. The RxVIMOpenMessageContainer function returns the following values: 
  1947.  
  1948.         0 - Successful return
  1949.  
  1950. The return values from all of the function calls return a zero for success, and 
  1951. non-zero for failure.  To retrieve the actual failure reason, use the 
  1952. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  1953. value to the actual failure text.  Using RxVIMStatus, the following values may 
  1954. be returned by RxVIMOpenMessageContainer: 
  1955.  
  1956.         VIMSTS_SUCCESS                  Successful return
  1957.         VIMSTS_FAILURE                  Function Failed
  1958.  
  1959.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  1960.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory to open                                                container
  1961.         VIMSTS_INVALID_OBJECT           The container handle is bad
  1962.         VIMSTS_NOT_SUPPORTED            Null container name not                                                  supported
  1963.         VIMSTS_OPEN_FAILURE             Container could not be opened
  1964.  
  1965.  
  1966. ΓòÉΓòÉΓòÉ 8.1.3. Example ΓòÉΓòÉΓòÉ
  1967.  
  1968. /* Example of using RxVIMOpenMessageContainer */
  1969.  
  1970. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  1971. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  1972. call RxVIMLoadFuncs
  1973.  
  1974.  
  1975. /* This will establish a connection to the VIM system */
  1976. rc = RxVIMInitialize()
  1977.  
  1978. /* Obtain the default session information */
  1979. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  1980.  
  1981. Say 'Default path:' db_path
  1982. Say 'Default name:' user_name
  1983.  
  1984. /* Opening a session with the mail subsystem */
  1985. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  1986.  
  1987. /* Open the default message container (Inbox) */
  1988. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  1989.  
  1990. /* Close the session with the mail subsystem */
  1991. rc = RxVIMCloseSession( Sess )
  1992.  
  1993. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  1994. call RxVIMDropFuncs
  1995.  
  1996.  
  1997. ΓòÉΓòÉΓòÉ 8.2. RxVIMEnumerateMessages ΓòÉΓòÉΓòÉ
  1998.  
  1999. The RxVIMEnumerateMessages function retrieves specified information regarding 
  2000. one or many messages in the container.  This function is used to obtain 
  2001. reference pointers to messages in the container.  Once a pointer has been 
  2002. retrieved for a message, that message can be deleted, filed in a folder, or 
  2003. operated on using the message access functions. 
  2004.  
  2005.  
  2006. ΓòÉΓòÉΓòÉ 8.2.1. Syntax ΓòÉΓòÉΓòÉ
  2007.  
  2008. RxVIMEnumerateMessages is called with nine parameters.  The first parameter is 
  2009. the pointer to the open message container, which was returned from the open of 
  2010. the container. 
  2011.  
  2012. The second is a variable containing the starting position within the message 
  2013. container.  To start at the beginning, the value of the variable should be set 
  2014. to null ('').  For subsequent calls, this value will contain the return value 
  2015. from the previous call.  This entry MUST be a variable name, since the function 
  2016. returns the value of the next starting position. 
  2017.  
  2018. The third parameter is the number of entries to skip before or after the 
  2019. starting position.  To start at the beginning and move forward, this should be 
  2020. set to a value of 1.  To start at the end, and move in reverse, this should be 
  2021. set to a value of -1. 
  2022.  
  2023. The fourth parameter is a stem variable name that contains the number of 
  2024. attributes to retrieve at the root, and a Selector and Buffer entry for each 
  2025. attribute.  The Selector entry contains the selector to retrieve, and the 
  2026. Buffer entry contains the name of the variable to return the values. 
  2027.  
  2028. An example of a properly formatted attribute description buffer is shown below: 
  2029.  
  2030.       attrDesc.0 = 2
  2031.       attrDesc.1.Selector = 'VIMSEL_REF'
  2032.       attrDesc.1.Buffer   = 'MsgRefNo'
  2033.       attrDesc.2.Selector = 'VIMSEL_SUBJECT'
  2034.       attrDesc.2.Buffer   = 'Subject'
  2035.  
  2036. The fifth parameter is a variable that contains the number of messages to read 
  2037. for the call.  Upon return, the variable contains the number of messages 
  2038. actually read.  This entry MUST be a variable name, since the function returns 
  2039. the number of messages actually read. 
  2040.  
  2041. The sixth parameter is a selector indicating the type of filtering to be done 
  2042. on the messages prior to being included in the return information.  Filtering 
  2043. can allow messages to be filtered based on subject, category, type of message, 
  2044. or other values.  To return all messages in the container without filtering, 
  2045. specify 'VIMSEL_NO_FILTER'. 
  2046.  
  2047. The seventh parameter is the value to be used for filtering, if specified. If 
  2048. no filtering is indicated, this parameter should be null (''). 
  2049.  
  2050. The eighth parameter is used to specify flags to be used as extended filter 
  2051. values.  To return all messages in the container, specify 'VIM_NO_FLAGS' for 
  2052. this parameter. 
  2053.  
  2054. The ninth parameter is the name of a variable to return a Boolean value 
  2055. indicating if additional messages exist in the message container. This value 
  2056. can be used to indicate that another call to RxVIMEnumerateMessages is 
  2057. necessary to process remaining messages in the container. 
  2058.  
  2059. Pos     = ''
  2060. Skipcnt = 1
  2061. Mcount  = 1
  2062. attrDesc.0 = 1
  2063. attrDesc.1.Selector = 'VIMSEL_REF'
  2064. attrDesc.1.Buffer   = 'MsgRefNo'
  2065. filter  = 'VIMSEL_NO_FILTER'
  2066. fdata   = ''
  2067. flags   = 'VIM_NO_FLAGS'
  2068. more    = ''
  2069.  
  2070.  
  2071. call RxVIMEnumerateMessages MsgCont,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,flags,'more'
  2072.  
  2073. or
  2074.  
  2075. rc = RxVIMEnumerateMessages(MsgCont,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,flags,'more')
  2076.  
  2077. Listed below are the valid selectors to use to request specific attributes to 
  2078. be returned for each message: 
  2079.  
  2080. VIMSEL_REF                      Retrieves the message reference value
  2081.  
  2082. VIMSEL_TYPE                     Retrieves the message type
  2083.  
  2084. VIMSEL_FROM_NAME                Retrieves the name of the sender
  2085.  
  2086. VIMSEL_SUBJECT                  Retrieves the subject of the message
  2087.  
  2088. VIMSEL_PRIORITY                 Retrieves the priority of the message
  2089.  
  2090. VIMSEL_MSG_LEN                  Retrieves the size of the message in                                     bytes
  2091.  
  2092. VIMSEL_UNREAD_MAIL              Returns 'True' if message is unread, or
  2093.                                 'False' if it has been read
  2094.  
  2095. VIMSEL_ENCRYPT_WITH_KEY         Returns 'True' if message was encrypted
  2096.                                 or  'False' if it was not
  2097.  
  2098. Listed below are the valid selectors to use to request filtering for each 
  2099. message (parameter five): 
  2100.  
  2101. VIMSEL_TYPE                     Filter on the message type
  2102.  
  2103.                                    Pass one of following in filter data:
  2104.  
  2105.                                    VIM_MAIL  -  normal mail messages
  2106.                                    VIM_RTRC  -  return receipts requested
  2107.                                    VIM_DLR   -  delivery reports
  2108.                                    VIM_NDLR  -  non-delivery reports
  2109.  
  2110.                                    Notes also supports user-defined types.
  2111.  
  2112.  
  2113. VIMSEL_CATEGORY                 Filter on the message category or folder
  2114.                                 Pass name of category in filter data
  2115.  
  2116.  
  2117. VIMSEL_FROM                     Filter on the name of the sender
  2118.                                 Pass name of sender in filter data
  2119.  
  2120.  
  2121. VIMSEL_SENT                     Retrive messages from message log (ccMail only)
  2122.  
  2123.                                 Pass null ('') in filter data
  2124.  
  2125.  
  2126. VIMSEL_SUBJECT                  Filter on the subject of the message
  2127.                                 Pass subject in filter data
  2128.  
  2129.  
  2130.  
  2131. Listed below are the valid values for the enumeration flags for this function 
  2132. (parameter eight): 
  2133.  
  2134.  
  2135.  
  2136. VIM_NO_FLAGS                    Retrieve all messages
  2137.  
  2138. VIM_UNREADONLY                  Retrieve only unread messages
  2139.  
  2140. The function will return the requested attribute values in the specified buffer 
  2141. as stem values with the following 
  2142.  
  2143. format: 
  2144.  
  2145.          'Subject' specified to receive message subject
  2146.          5 messages are retreived
  2147.  
  2148.          Subject.0 = 5
  2149.          Subject.1 = 'Subject from first  message'
  2150.          Subject.2 = 'Subject from second message'
  2151.          Subject.3 = 'Subject from third  message'
  2152.          Subject.4 = 'Subject from fourth message'
  2153.          Subject.5 = 'Subject from fifth  message'
  2154.  
  2155.  
  2156. ΓòÉΓòÉΓòÉ 8.2.2. Return Codes ΓòÉΓòÉΓòÉ
  2157.  
  2158. The RxVIMEnumerateMessages function returns the following values: 
  2159.  
  2160.         0 - Successful return
  2161.  
  2162. The return values from all of the function calls return a zero for success, and 
  2163. non-zero for failure.  To retrieve the actual failure reason, use the 
  2164. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2165. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2166. be returned by RxVIMEnumerateMessages: 
  2167.  
  2168.         VIMSTS_SUCCESS                  Successful return
  2169.         VIMSTS_FAILURE                  Function Failed
  2170.  
  2171.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  2172.         VIMSTS_BUF_TOO_SMALL            Return buffer is too small
  2173.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  2174.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2175.         VIMSTS_INVALID_SELECTOR         The requested selector is bad
  2176.         VIMSTS_READ_FAILURE             Error reading from disk
  2177.  
  2178.  
  2179. ΓòÉΓòÉΓòÉ 8.2.3. Example ΓòÉΓòÉΓòÉ
  2180.  
  2181. /* Example of using RxVIMEnumerateMessages */
  2182.  
  2183. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2184. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2185. call RxVIMLoadFuncs
  2186.  
  2187. /* This will establish a connection to the VIM system */
  2188. rc = RxVIMInitialize()
  2189.  
  2190. /* Obtain the default session information */
  2191. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2192. Say 'Default path:' db_path
  2193. Say 'Default name:' user_name
  2194.  
  2195. /* Opening a session with the mail subsystem */
  2196. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2197.  
  2198. /* Open the default message container (Inbox) */
  2199. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2200.  
  2201. /* Retrieve the first message from the container pulling the */
  2202. /* message reference number only                             */
  2203. pos = ''                                  /* Start at beginning */
  2204. skipcnt = 1                               /* Start at beginning */
  2205. mcount  = 1                               /* Return one message */
  2206. filter  = 'VIMSEL_NO_FILTER'              /* No filtering       */
  2207. fdata   = ''                              /* No filter data     */
  2208. flags   = 'VIM_NO_FLAGS'                  /* No flags           */
  2209. more = ''                                 /* more messages?     */
  2210. attrDesc.0 = 2                            /* retrieve 2 attributes    */
  2211. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference value          */
  2212. attrDesc.1.Buffer   = 'refno'             /* buffer to return refno   */
  2213. attrDesc.2.Selector = 'VIMSEL_SUBJECT'    /* message subject          */
  2214. attrDesc.2.Buffer   = 'Subject'           /* buffer to return subject */
  2215.  
  2216. rc = RxVIMEnumerateMessages(MsgCont,'pos',skipcnt,'attrDesc','mcount',filter,,
  2217.                             fdata,flags,'more')
  2218.  
  2219. Say 'The first message has the following values'
  2220. Say
  2221. Say 'Message No -' refno.1
  2222. Say 'Subject    -' Subject.1
  2223.  
  2224. /* Close the specified message container */
  2225. rc = RxVIMCloseMessageContainer( MsgCont )
  2226.  
  2227. /* Close the session with the mail subsystem */
  2228. rc = RxVIMCloseSession( Sess )
  2229.  
  2230. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2231. call RxVIMDropFuncs
  2232.  
  2233.  
  2234. ΓòÉΓòÉΓòÉ 8.3. RxVIMSetMessageCategory ΓòÉΓòÉΓòÉ
  2235.  
  2236. The RxVIMSetMessageCategory function creates the association of the message 
  2237. with the specified category.  If the message is the first for a category, the 
  2238. new folder is created. 
  2239.  
  2240.  
  2241. ΓòÉΓòÉΓòÉ 8.3.1. Syntax ΓòÉΓòÉΓòÉ
  2242.  
  2243. RxVIMSetMessageCategory is called with three parameters.  The first parameter 
  2244. is the pointer to the open message container, which was returned from the open 
  2245. of the container.  The second is the pointer to the message to act upon, which 
  2246. can be retrieve by using the RxVIMEnumerateMessage function..  The third 
  2247. parameter is the name of the category to add the message. 
  2248.  
  2249. call RxVIMSetMessageCategory MsgCont, MsgtoAdd, 'Category Name'
  2250.  
  2251. or
  2252.  
  2253. rc = RxVIMSetMessageCategory(MsgCont, MsgtoAdd, 'Category Name')
  2254.  
  2255.  
  2256. ΓòÉΓòÉΓòÉ 8.3.2. Return Codes ΓòÉΓòÉΓòÉ
  2257.  
  2258. The RxVIMSetMessageCategory function returns the following values: 
  2259.  
  2260.         0 - Successful return
  2261.  
  2262. The return values from all of the function calls return a zero for success, and 
  2263. non-zero for failure.  To retrieve the actual failure reason, use the 
  2264. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2265. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2266. be returned by RxVIMSetMessageCategory: 
  2267.  
  2268.         VIMSTS_SUCCESS                  Successful return
  2269.         VIMSTS_FAILURE                  Function Failed
  2270.  
  2271.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  2272.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2273.         VIMSTS_WRITE_FAILURE            Error writing to disk
  2274.  
  2275.  
  2276. ΓòÉΓòÉΓòÉ 8.3.3. Example ΓòÉΓòÉΓòÉ
  2277.  
  2278. /* Example of using RxVIMSetMessageCategory */
  2279.  
  2280. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2281. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2282. call RxVIMLoadFuncs
  2283.  
  2284.  
  2285. /* This will establish a connection to the VIM system */
  2286. rc = RxVIMInitialize()
  2287.  
  2288. /* Obtain the default session information */
  2289. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2290.  
  2291. Say 'Default path:' db_path
  2292. Say 'Default name:' user_name
  2293.  
  2294. /* Opening a session with the mail subsystem */
  2295. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2296.  
  2297. /* Open the default message container (Inbox) */
  2298. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2299.  
  2300. /* Retrieve the first message from the container pulling the */
  2301. /* message reference number only                             */
  2302. attrDesc.0 = 1
  2303. attrDesc.selector = 'VIMSEL_REF'
  2304. attrDesc.buffer   = 'refno'
  2305.  
  2306. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  2307.                             '','VIM_NO_FLAGS','more')
  2308.  
  2309. /* Assign the first message to the Temporary folder */
  2310. rc = RxVIMSetMessageCategory(MsgCont,refno.1,'Temporary')
  2311.  
  2312. /* Close the specified message container */
  2313. rc = RxVIMCloseMessageContainer( MsgCont )
  2314.  
  2315. /* Close the session with the mail subsystem */
  2316. rc = RxVIMCloseSession( Sess )
  2317.  
  2318. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2319. call RxVIMDropFuncs
  2320.  
  2321.  
  2322. ΓòÉΓòÉΓòÉ 8.4. RxVIMRemoveMessageCategory ΓòÉΓòÉΓòÉ
  2323.  
  2324. The RxVIMRemoveMessageCategory function deletes the association of the message 
  2325. from the specified category.  When the message has been removed from all 
  2326. categories, the message itself will be deleted.  If the message is the last in 
  2327. the category, the folder itself will be deleted. 
  2328.  
  2329.  
  2330. ΓòÉΓòÉΓòÉ 8.4.1. Syntax ΓòÉΓòÉΓòÉ
  2331.  
  2332. RxVIMRemoveMessageCategory is called with three parameters.  The first 
  2333. parameter is the pointer to the open message container, which was returned from 
  2334. the open of the container.  The second is the pointer to the message to act 
  2335. upon, which can be retrieve by using the RxVIMEnumerateMessage function..  The 
  2336. third parameter is the name of the category from which to remove the message. 
  2337.  
  2338. call RxVIMRemoveMessageCategory MsgCont, MsgtoDel, 'Category Name'
  2339.  
  2340. or
  2341.  
  2342. rc = RxVIMRemoveMessageCategory(MsgCont, MsgtoDel, 'Category Name')
  2343.  
  2344.  
  2345. ΓòÉΓòÉΓòÉ 8.4.2. Return Codes ΓòÉΓòÉΓòÉ
  2346.  
  2347. The RxVIMRemoveMessageCategory function returns the following values: 
  2348.  
  2349.         0 - Successful return
  2350.  
  2351. The return values from all of the function calls return a zero for success, and 
  2352. non-zero for failure.  To retrieve the actual failure reason, use the 
  2353. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2354. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2355. be returned by RxVIMRemoveMessageCategory: 
  2356.  
  2357.         VIMSTS_SUCCESS                  Successful return
  2358.         VIMSTS_FAILURE                  Function Failed
  2359.  
  2360.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2361.         VIMSTS_WRITE_FAILURE            Error writing to disk
  2362.  
  2363.  
  2364. ΓòÉΓòÉΓòÉ 8.4.3. Example ΓòÉΓòÉΓòÉ
  2365.  
  2366. /* Example of using RxVIMRemoveMessageCategory */
  2367.  
  2368. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2369. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2370. call RxVIMLoadFuncs
  2371.  
  2372.  
  2373. /* This will establish a connection to the VIM system */
  2374. rc = RxVIMInitialize()
  2375.  
  2376. /* Obtain the default session information */
  2377. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2378.  
  2379. Say 'Default path:' db_path
  2380. Say 'Default name:' user_name
  2381.  
  2382. /* Opening a session with the mail subsystem */
  2383. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2384.  
  2385. /* Open the default message container (Inbox) */
  2386. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2387.  
  2388. /* Retrieve the first message from the container pulling the */
  2389. /* message reference number only                             */
  2390. attrDesc.0 = 1
  2391. attrDesc.selector = 'VIMSEL_REF'
  2392. attrDesc.buffer   = 'refno'
  2393.  
  2394. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_CATEGORY',,
  2395.                             'Temporary','VIM_NO_FLAGS','more')
  2396.  
  2397. /* Delete the first message from the Temporary folder */
  2398. rc = RxVIMRemoveMessageCategory(MsgCont,refno.1,'Temporary')
  2399.  
  2400. /* Close the specified message container */
  2401. rc = RxVIMCloseMessageContainer( MsgCont )
  2402.  
  2403. /* Close the session with the mail subsystem */
  2404. rc = RxVIMCloseSession( Sess )
  2405.  
  2406. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2407. call RxVIMDropFuncs
  2408.  
  2409.  
  2410. ΓòÉΓòÉΓòÉ 8.5. RxVIMRemoveMessage ΓòÉΓòÉΓòÉ
  2411.  
  2412. The RxVIMRemoveMessage function deletes the specified message from the message 
  2413. container. 
  2414.  
  2415.  
  2416. ΓòÉΓòÉΓòÉ 8.5.1. Syntax ΓòÉΓòÉΓòÉ
  2417.  
  2418. RxVIMRemoveMessage is called with two parameters.  The first parameter is the 
  2419. pointer to the open message container, which was returned from the open of the 
  2420. container.  The second is the pointer to the message to delete, which can be 
  2421. retrieve by using the RxVIMEnumerateMessage function. 
  2422.  
  2423. call RxVIMRemoveMessage MsgCont, MsgtoDel
  2424.  
  2425. or
  2426.  
  2427. rc = RxVIMRemoveMessage(MsgCont, MsgtoDel)
  2428.  
  2429.  
  2430. ΓòÉΓòÉΓòÉ 8.5.2. Return Codes ΓòÉΓòÉΓòÉ
  2431.  
  2432. The RxVIMRemoveMessage function returns the following values: 
  2433.  
  2434.         0 - Successful return
  2435.  
  2436. The return values from all of the function calls return a zero for success, and 
  2437. non-zero for failure.  To retrieve the actual failure reason, use the 
  2438. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2439. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2440. be returned by RxVIMRemoveMessage: 
  2441.  
  2442.         VIMSTS_SUCCESS                  Successful return
  2443.         VIMSTS_FAILURE                  Function Failed
  2444.  
  2445.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  2446.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  2447.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2448.         VIMSTS_WRITE_FAILURE            Error writing to disk
  2449.  
  2450.  
  2451. ΓòÉΓòÉΓòÉ 8.5.3. Example ΓòÉΓòÉΓòÉ
  2452.  
  2453. /* Example of using RxVIMRemoveMessage */
  2454.  
  2455. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2456. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2457. call RxVIMLoadFuncs
  2458.  
  2459.  
  2460. /* This will establish a connection to the VIM system */
  2461. rc = RxVIMInitialize()
  2462.  
  2463. /* Obtain the default session information */
  2464. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2465.  
  2466. Say 'Default path:' db_path
  2467. Say 'Default name:' user_name
  2468.  
  2469. /* Opening a session with the mail subsystem */
  2470. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2471.  
  2472. /* Open the default message container (Inbox) */
  2473. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2474.  
  2475. /* Retrieve the first message from the container pulling the */
  2476. /* message reference number only                             */
  2477. attrDesc.0 = 1
  2478. attrDesc.selector = 'VIMSEL_REF'
  2479. attrDesc.buffer   = 'refno'
  2480.  
  2481. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  2482.                             '','VIM_NO_FLAGS','more')
  2483.  
  2484. /* Delete the first message */
  2485. rc = RxVIMRemoveMessage(MsgCont,refno.1)
  2486.  
  2487. /* Close the specified message container */
  2488. rc = RxVIMCloseMessageContainer( MsgCont )
  2489.  
  2490. /* Close the session with the mail subsystem */
  2491. rc = RxVIMCloseSession( Sess )
  2492.  
  2493. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2494. call RxVIMDropFuncs
  2495.  
  2496.  
  2497. ΓòÉΓòÉΓòÉ 8.6. RxVIMQueryNewMessages ΓòÉΓòÉΓòÉ
  2498.  
  2499. The RxVIMQueryNewMessages function returns a value of True or False to indicate 
  2500. if new messages are in the container. 
  2501.  
  2502.  
  2503. ΓòÉΓòÉΓòÉ 8.6.1. Syntax ΓòÉΓòÉΓòÉ
  2504.  
  2505. RxVIMQueryNewMessages is called with two parameters.  The first parameter is 
  2506. the pointer to the open message container, which was returned from the open of 
  2507. the container.  The second is the name of the variable to return the a Boolean 
  2508. value to indicate if new messages are in the container. 
  2509.  
  2510. call RxVIMQueryNewMessages MsgCont, 'NewMsgs'
  2511.  
  2512. or
  2513.  
  2514. rc = RxVIMQueryNewMessages(MsgCont, 'NewMsgs')
  2515.  
  2516.  
  2517. ΓòÉΓòÉΓòÉ 8.6.2. Return Codes ΓòÉΓòÉΓòÉ
  2518.  
  2519. The RxVIMQueryNewMessages function returns the following values: 
  2520.  
  2521.         0 - Successful return
  2522.  
  2523. The return values from all of the function calls return a zero for success, and 
  2524. non-zero for failure.  To retrieve the actual failure reason, use the 
  2525. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2526. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2527. be returned by RxVIMQueryNewMessages: 
  2528.  
  2529.         VIMSTS_SUCCESS                  Successful return
  2530.         VIMSTS_FAILURE                  Function Failed
  2531.  
  2532.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  2533.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  2534.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2535.         VIMSTS_READ_FAILURE             Error reading from disk
  2536.  
  2537.  
  2538. ΓòÉΓòÉΓòÉ 8.6.3. Example ΓòÉΓòÉΓòÉ
  2539.  
  2540. /* Example of using RxVIMQueryNewMessages */
  2541.  
  2542. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2543. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2544. call RxVIMLoadFuncs
  2545.  
  2546.  
  2547. /* This will establish a connection to the VIM system */
  2548. rc = RxVIMInitialize()
  2549.  
  2550. /* Obtain the default session information */
  2551. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2552.  
  2553. Say 'Default path:' db_path
  2554. Say 'Default name:' user_name
  2555.  
  2556. /* Opening a session with the mail subsystem */
  2557. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2558.  
  2559. /* Open the default message container (Inbox) */
  2560. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2561.  
  2562.  
  2563.  
  2564. /* Check for new messages in container */
  2565. rc = RxVIMQueryNewMessages( MsgCont, 'NewMsgs' )
  2566.  
  2567. if NewMsgs = 'True'
  2568.    Say 'Your Inbox has new messages'
  2569. else
  2570.    Say 'Your Inbox does not have new messages'
  2571.  
  2572.  
  2573. /* Close the specified message container */
  2574. rc = RxVIMCloseMessageContainer( MsgCont )
  2575.  
  2576. /* Close the session with the mail subsystem */
  2577. rc = RxVIMCloseSession( Sess )
  2578.  
  2579. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2580. call RxVIMDropFuncs
  2581.  
  2582.  
  2583. ΓòÉΓòÉΓòÉ 8.7. RxVIMQueryUnreadMailCount ΓòÉΓòÉΓòÉ
  2584.  
  2585. The RxVIMQueryUnreadMailCount function returns the number of new messages in 
  2586. the message container. 
  2587.  
  2588.  
  2589. ΓòÉΓòÉΓòÉ 8.7.1. Syntax ΓòÉΓòÉΓòÉ
  2590.  
  2591. RxVIMQueryUnreadMailCount is called with two parameters.  The first parameter 
  2592. is the pointer to the open message container, which was returned from the open 
  2593. of the container.  The second is the name of the variable to return the count 
  2594. value. 
  2595.  
  2596. call RxVIMQueryUnreadMailCount MsgCont, 'msgcount'
  2597.  
  2598. or
  2599.  
  2600. rc = RxVIMQueryUnreadMailCount(MsgCont, 'msgcount')
  2601.  
  2602.  
  2603. ΓòÉΓòÉΓòÉ 8.7.2. Return Codes ΓòÉΓòÉΓòÉ
  2604.  
  2605. The RxVIMQueryUnreadMailCount function returns the following values: 
  2606.  
  2607.         0 - Successful return
  2608.  
  2609. The return values from all of the function calls return a zero for success, and 
  2610. non-zero for failure.  To retrieve the actual failure reason, use the 
  2611. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2612. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2613. be returned by RxVIMQueryUnreadMailCount: 
  2614.  
  2615.         VIMSTS_SUCCESS                  Successful return
  2616.         VIMSTS_FAILURE                  Function Failed
  2617.  
  2618.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  2619.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2620.         VIMSTS_READ_FAILURE             Error reading from disk
  2621.         VIMSTS_NOT_SUPPORTED            This function is not supported
  2622.  
  2623.  
  2624. ΓòÉΓòÉΓòÉ 8.7.3. Example ΓòÉΓòÉΓòÉ
  2625.  
  2626. /* Example of using RxVIMQueryUnreadMailCount */
  2627.  
  2628. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2629. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2630. call RxVIMLoadFuncs
  2631.  
  2632.  
  2633. /* This will establish a connection to the VIM system */
  2634. rc = RxVIMInitialize()
  2635.  
  2636. /* Obtain the default session information */
  2637. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2638.  
  2639. Say 'Default path:' db_path
  2640. Say 'Default name:' user_name
  2641.  
  2642. /* Opening a session with the mail subsystem */
  2643. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2644.  
  2645. /* Open the default message container (Inbox) */
  2646. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2647.  
  2648.  
  2649.  
  2650. /* Retrieve the number of new messages in container */
  2651. rc = RxVIMQueryUnreadMailCount( MsgCont, 'NewMsgs' )
  2652.  
  2653. Say 'Your Inbox has' NewMsgs 'new messages'
  2654.  
  2655.  
  2656.  
  2657. /* Close the specified message container */
  2658. rc = RxVIMCloseMessageContainer( MsgCont )
  2659.  
  2660. /* Close the session with the mail subsystem */
  2661. rc = RxVIMCloseSession( Sess )
  2662.  
  2663. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2664. call RxVIMDropFuncs
  2665.  
  2666.  
  2667. ΓòÉΓòÉΓòÉ 8.8. RxVIMCloseMessageContainer ΓòÉΓòÉΓòÉ
  2668.  
  2669. The RxVIMCloseMessageContainer function closes the specified message container 
  2670. with the VIM system. 
  2671.  
  2672.  
  2673. ΓòÉΓòÉΓòÉ 8.8.1. Syntax ΓòÉΓòÉΓòÉ
  2674.  
  2675. RxVIMCloseMessageContainer is called with one parameter.  The parameter is the 
  2676. variable which contains a pointer to the message container to close.  The 
  2677. pointer to the message container is returned from the call to 
  2678. RxVIMOpenMessageContainer. 
  2679.  
  2680. call RxVIMCloseMessageContainer MsgCont
  2681.  
  2682. or
  2683.  
  2684. rc = RxVIMCloseMessageContainer( MsgCont )
  2685.  
  2686.  
  2687. ΓòÉΓòÉΓòÉ 8.8.2. Return Codes ΓòÉΓòÉΓòÉ
  2688.  
  2689. The RxVIMCloseMessageContainer function returns the following values: 
  2690.  
  2691.         0 - Successful function return
  2692.  
  2693. The return values from all of the function calls return a zero for success, and 
  2694. non-zero for failure.  To retrieve the actual failure reason, use the 
  2695. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2696. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2697. be returned by RxVIMCloseMessageContainer: 
  2698.  
  2699.         VIMSTS_SUCCESS                  Successful return
  2700.         VIMSTS_FAILURE                  Function Failed
  2701.  
  2702.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2703.  
  2704.  
  2705. ΓòÉΓòÉΓòÉ 8.8.3. Example ΓòÉΓòÉΓòÉ
  2706.  
  2707. /* Example of using RxVIMCloseMessageContainer */
  2708.  
  2709. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2710. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2711. call RxVIMLoadFuncs
  2712.  
  2713. /* This will establish a connection to the VIM system */
  2714. rc = RxVIMInitialize()
  2715.  
  2716. /* Obtain the default session information */
  2717. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2718.  
  2719. Say 'Default path:' db_path
  2720. Say 'Default name:' user_name
  2721.  
  2722. /* Opening a session with the mail subsystem */
  2723. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2724.  
  2725. /* Open the default message container (Inbox) */
  2726. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2727.  
  2728. /* Close the specified message container */
  2729. rc = RxVIMCloseMessageContainer( MsgCont )
  2730.  
  2731. /* Close the session with the mail subsystem */
  2732. rc = RxVIMCloseSession( Sess )
  2733.  
  2734. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2735. call RxVIMDropFuncs
  2736.  
  2737.  
  2738. ΓòÉΓòÉΓòÉ 9. Message Access and Attribute Functions ΓòÉΓòÉΓòÉ
  2739.  
  2740. This section describes each of the functions available in the RexxVIM product 
  2741. that address message access and attribute features. 
  2742.  
  2743. Below are all of the Message Access and Attribute functions: 
  2744.  
  2745. RxVIMOpenMessage 
  2746.  
  2747. RxVIMMarkMessageAsRead 
  2748.  
  2749. RxVIMGetMessageHeader 
  2750.  
  2751. RxVIMEnumerateMessageItems 
  2752.  
  2753. RxVIMGetMessageItem 
  2754.  
  2755. RxVIMOpenMessageItem 
  2756.  
  2757. RxVIMReadMessageItem 
  2758.  
  2759. RxVIMCloseMessageItem 
  2760.  
  2761. RxVIMEnumerateMessageRecipients 
  2762.  
  2763. RxVIMOpenNestedMessage 
  2764.  
  2765. RxVIMExtractMessage 
  2766.  
  2767. RxVIMOpenExtractedMessage 
  2768.  
  2769.  
  2770. ΓòÉΓòÉΓòÉ 9.1. RxVIMOpenMessage ΓòÉΓòÉΓòÉ
  2771.  
  2772. The RxVIMOpenMessage function opens the specified message with the VIM system. 
  2773. After the message has been opened, the other message functions can be used for 
  2774. further message processing. 
  2775.  
  2776.  
  2777. ΓòÉΓòÉΓòÉ 9.1.1. Syntax ΓòÉΓòÉΓòÉ
  2778.  
  2779. RxVIMOpenMessage is called with four parameter.  The first parameter is the 
  2780. variable which contains a pointer to the open message container.  The second 
  2781. parameter is the reference number of the message to open, which can be 
  2782. retrieved from the RxVIMEnumerateMessages function.  The third parameter is the 
  2783. explicit key to use if the message is encrypted or NULL ('') if it is not 
  2784. encrypted.  The fourth parameter is the name of the variable to return the 
  2785. pointer to the message. 
  2786.  
  2787. call RxVIMOpenMessage MsgCont, MsgRef, '', 'MsgPtr'
  2788.  
  2789. or
  2790.  
  2791. rc = RxVIMOpenMessage( MsgCont, MsgRef, '', 'MsgPtr' )
  2792.  
  2793.  
  2794. ΓòÉΓòÉΓòÉ 9.1.2. Return Codes ΓòÉΓòÉΓòÉ
  2795.  
  2796. The RxVIMOpenMessage function returns the following values: 
  2797.  
  2798.         0 - Successful function return
  2799.  
  2800. The return values from all of the function calls return a zero for success, and 
  2801. non-zero for failure.  To retrieve the actual failure reason, use the 
  2802. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2803. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2804. be returned by RxVIMOpenMessage: 
  2805.  
  2806.         VIMSTS_SUCCESS                  Successful return
  2807.         VIMSTS_FAILURE                  Function Failed
  2808.  
  2809.         VIMSTS_BAD_PARAM                The message reference is bad
  2810.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  2811.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2812.         VIMSTS_READ_FAILURE             Error reading from the disk
  2813.  
  2814.  
  2815. ΓòÉΓòÉΓòÉ 9.1.3. Example ΓòÉΓòÉΓòÉ
  2816.  
  2817. /* Example of using RxVIMOpenMessage */
  2818.  
  2819. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2820. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2821. call RxVIMLoadFuncs
  2822.  
  2823. /* This will establish a connection to the VIM system */
  2824. rc = RxVIMInitialize()
  2825.  
  2826. /* Obtain the default session information */
  2827. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2828.  
  2829. Say 'Default path:' db_path
  2830. Say 'Default name:' user_name
  2831.  
  2832. /* Opening a session with the mail subsystem */
  2833. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2834.  
  2835. /* Open the default message container (Inbox) */
  2836. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2837.  
  2838. /* Retrieve the first message from the container pulling the */
  2839. /* message reference number only                             */
  2840. attrDesc.0 = 1
  2841. attrDesc.selector = 'VIMSEL_REF'
  2842. attrDesc.buffer   = 'refno'
  2843.  
  2844. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  2845.                             '','VIM_NO_FLAGS','more')
  2846.  
  2847.  
  2848. /* Open the first message */
  2849. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  2850.  
  2851.  
  2852. /* Close the specified message container */
  2853. rc = RxVIMCloseMessageContainer( MsgCont )
  2854.  
  2855. /* Close the session with the mail subsystem */
  2856. rc = RxVIMCloseSession( Sess )
  2857.  
  2858. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2859. call RxVIMDropFuncs
  2860.  
  2861.  
  2862. ΓòÉΓòÉΓòÉ 9.2. RxVIMMarkMessageAsRead ΓòÉΓòÉΓòÉ
  2863.  
  2864. The RxVIMMarkMessageAsRead function changes the status on the specified message 
  2865. to read. 
  2866.  
  2867.  
  2868. ΓòÉΓòÉΓòÉ 9.2.1. Syntax ΓòÉΓòÉΓòÉ
  2869.  
  2870. RxVIMMarkMessageAsRead is called with two parameter.  The first parameter is 
  2871. the variable which contains a pointer to the open message container.  The 
  2872. second parameter is the variable which contains a pointer to the open message. 
  2873.  
  2874. call RxVIMMarkMessageAsRead MsgCont, MsgPtr
  2875.  
  2876. or
  2877.  
  2878. rc = RxVIMMarkMessageAsRead( MsgCont, MsgPtr )
  2879.  
  2880.  
  2881. ΓòÉΓòÉΓòÉ 9.2.2. Return Codes ΓòÉΓòÉΓòÉ
  2882.  
  2883. The RxVIMMarkMessageAsRead function returns the following values: 
  2884.  
  2885.         0 - Successful function return
  2886.  
  2887. The return values from all of the function calls return a zero for success, and 
  2888. non-zero for failure.  To retrieve the actual failure reason, use the 
  2889. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  2890. value to the actual failure text.  Using RxVIMStatus, the following values may 
  2891. be returned by RxVIMMarkMessageAsRead: 
  2892.  
  2893.         VIMSTS_SUCCESS                  Successful return
  2894.         VIMSTS_FAILURE                  Function Failed
  2895.  
  2896.         VIMSTS_BAD_PARAM                The message reference is bad
  2897.         VIMSTS_INVALID_OBJECT           The container handle is bad
  2898.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  2899.  
  2900.  
  2901. ΓòÉΓòÉΓòÉ 9.2.3. Example ΓòÉΓòÉΓòÉ
  2902.  
  2903. /* Example of using RxVIMMarkMessageAsRead */
  2904.  
  2905. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  2906. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  2907. call RxVIMLoadFuncs
  2908.  
  2909. /* This will establish a connection to the VIM system */
  2910. rc = RxVIMInitialize()
  2911.  
  2912. /* Obtain the default session information */
  2913. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  2914.  
  2915. Say 'Default path:' db_path
  2916. Say 'Default name:' user_name
  2917.  
  2918. /* Opening a session with the mail subsystem */
  2919. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  2920.  
  2921. /* Open the default message container (Inbox) */
  2922. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  2923.  
  2924. /* Retrieve the first message from the container pulling the */
  2925. /* message reference number only                             */
  2926. attrDesc.0 = 1
  2927. attrDesc.selector = 'VIMSEL_REF'
  2928. attrDesc.buffer   = 'refno'
  2929.  
  2930. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  2931.                             '','VIM_NO_FLAGS','more')
  2932.  
  2933. /* Open the first message */
  2934. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  2935.  
  2936.  
  2937. /* Mark the first message as read */
  2938. rc = RxVIMMarkMessageAsRead(MsgCont,MsgPtr)
  2939.  
  2940.  
  2941. /* Close the specified message container */
  2942. rc = RxVIMCloseMessageContainer( MsgCont )
  2943.  
  2944. /* Close the session with the mail subsystem */
  2945. rc = RxVIMCloseSession( Sess )
  2946.  
  2947. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  2948. call RxVIMDropFuncs
  2949.  
  2950.  
  2951. ΓòÉΓòÉΓòÉ 9.3. RxVIMGetMessageHeader ΓòÉΓòÉΓòÉ
  2952.  
  2953. The RxVIMGetMessageHeader function retrieves one or more attributes from the 
  2954. header of the specified message. 
  2955.  
  2956.  
  2957. ΓòÉΓòÉΓòÉ 9.3.1. Syntax ΓòÉΓòÉΓòÉ
  2958.  
  2959. RxVIMGetMessageHeader is called with two parameter.  The first parameter is the 
  2960. name of the variable that contains a pointer to the message.  The second is the 
  2961. variable name of the stem variable of attributes to retrieve. 
  2962.  
  2963. attrDesc.0 = 1
  2964. attrDesc.1.Selector = 'VIMSEL_TYPE'
  2965. attrDesc.1.Buffer   = 'MsgType'
  2966.  
  2967. call RxVIMGetMessageHeader MsgPtr, 'attrDesc'
  2968.  
  2969. or
  2970.  
  2971. rc = RxVIMGetMessageHeader( MsgPtr, 'attrDesc' )
  2972.  
  2973. Listed below are the valid selectors to use to request specific attributes to 
  2974. be returned for each message: 
  2975.  
  2976. VIMSEL_TYPE                     Retrieves the message type
  2977.  
  2978. VIMSEL_FROM_NAME                Retrieves the name of the sender
  2979.  
  2980. VIMSEL_SUBJECT                  Retrieves the subject of the message
  2981.  
  2982. VIMSEL_SUBJECT_LEN              Retrieves the length of the subject of the message
  2983.  
  2984. VIMSEL_PRIORITY                 Retrieves the priority of the message
  2985.  
  2986. VIMSEL_MSG_LEN                  Retrieves the size of the message in bytes
  2987.  
  2988. VIMSEL_RETURN_RECEIPT           Returns 'True' if receipt was requested on open
  2989.  
  2990.  
  2991. ΓòÉΓòÉΓòÉ 9.3.2. Return Codes ΓòÉΓòÉΓòÉ
  2992.  
  2993. The RxVIMGetMessageHeader function returns the following values: 
  2994.  
  2995.         0 - Successful function return
  2996.  
  2997. The return values from all of the function calls return a zero for success, and 
  2998. non-zero for failure.  To retrieve the actual failure reason, use the 
  2999. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3000. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3001. be returned by RxVIMGetMessageHeader: 
  3002.  
  3003.         VIMSTS_SUCCESS                  Successful return
  3004.         VIMSTS_FAILURE                  Function Failed
  3005.  
  3006.         VIMSTS_BAD_PARAM                The message reference is bad
  3007.         VIMSTS_BUF_TOO_SMALL            The return buffer is too small
  3008.         VIMSTS_INVALID_OBJECT           The container handle is bad
  3009.         VIMSTS_INVALID_SELECTOR         Unknown selector value
  3010.         VIMSTS_NOT_SUPPORTED            Selector is not supported
  3011.  
  3012.  
  3013. ΓòÉΓòÉΓòÉ 9.3.3. Example ΓòÉΓòÉΓòÉ
  3014.  
  3015. /* Example of using RxVIMGetMessageHeader */
  3016.  
  3017. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3018. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3019. call RxVIMLoadFuncs
  3020.  
  3021. /* This will establish a connection to the VIM system */
  3022. rc = RxVIMInitialize()
  3023.  
  3024. /* Obtain the default session information */
  3025. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3026. Say 'Default path:' db_path
  3027. Say 'Default name:' user_name
  3028.  
  3029. /* Opening a session with the mail subsystem */
  3030. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3031.  
  3032. /* Open the default message container (Inbox) */
  3033. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3034.  
  3035. /* Retrieve the first message from the container pulling the */
  3036. /* message reference number only                             */
  3037. attrDesc.0 = 1
  3038. attrDesc.selector = 'VIMSEL_REF'
  3039. attrDesc.buffer   = 'refno'
  3040.  
  3041. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  3042.                             '','VIM_NO_FLAGS','more')
  3043.  
  3044. /* Open the first message */
  3045. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3046.  
  3047. /* Retrieve two attributes of the message header */
  3048. attrHead.0 = 2
  3049. attrHead.1.Selector = 'VIMSEL_FROM_NAME'
  3050. attrHead.1.Buffer   = 'from'
  3051. attrHead.2.Selector = 'VIMSEL_MSG_LEN'
  3052. attrHead.2.Buffer   = 'MsgLength'
  3053.  
  3054. rc = RxVIMGetMessageHeader(MsgPtr,'attrHead')
  3055.  
  3056. Say 'The message from' from ' is' MsgLength 'bytes in size'
  3057.  
  3058. /* Close the specified message container */
  3059. rc = RxVIMCloseMessageContainer( MsgCont )
  3060.  
  3061. /* Close the session with the mail subsystem */
  3062. rc = RxVIMCloseSession( Sess )
  3063.  
  3064. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3065. call RxVIMDropFuncs
  3066.  
  3067.  
  3068. ΓòÉΓòÉΓòÉ 9.4. RxVIMEnumerateMessageItem ΓòÉΓòÉΓòÉ
  3069.  
  3070. The RxVIMEnumerateMessageItems function retrieves specified information 
  3071. regarding one or many items in a specific message.  This function is used to 
  3072. obtain reference pointers to message items in the message.  Once a pointer has 
  3073. been retrieved for a message item, that item can be accessed individually. 
  3074.  
  3075.  
  3076. ΓòÉΓòÉΓòÉ 9.4.1. Syntax ΓòÉΓòÉΓòÉ
  3077.  
  3078. RxVIMEnumerateMessageItems is called with eight parameters.  The first 
  3079. parameter is the pointer to the open message, which was returned from 
  3080. RxVIMOpenMessage. 
  3081.  
  3082. The second is a variable containing the starting position within the message. 
  3083. To start at the beginning, the value of the variable should be set to null 
  3084. ('').  For subsequent calls, this value will contain the return value from the 
  3085. previous call.  This entry MUST be a variable name, since the function returns 
  3086. the value of the next starting position. 
  3087.  
  3088. The third parameter is the number of entries to skip before or after the 
  3089. starting position.  To start at the beginning and move forward, this should be 
  3090. set to a value of 1.  To start at the end, and move in reverse, this should be 
  3091. set to a value of -1. 
  3092.  
  3093. The fourth parameter is a variable that contains the number of message items to 
  3094. read for the call.  Upon return, the variable contains the number of messages 
  3095. actually read.  This entry MUST be a variable name, since the function returns 
  3096. the number of messages actually read. 
  3097.  
  3098. The fifth parameter is a stem variable name that will contain the results of 
  3099. the call.  Upon return, the stem variable will contain the class, type, title, 
  3100. path, size, and reference number for each item retrieved.  An example of a 
  3101. return stem variable 'ItemDesc' for the first message item is: 
  3102.  
  3103.      ItemDesc.1.CLASS         /* Contains the class of the item */
  3104.      ItemDesc.1.TYPE          /* Contains the type of the item  */
  3105.      ItemDesc.1.NAME          /* Contains the name of the item  */
  3106.      ItemDesc.1.SIZE          /* Contains size of item in bytes */
  3107.      ItemDesc.1.REF           /* Reference number of the item   */
  3108.  
  3109. The sixth parameter is a selector indicating the type of filtering to be done 
  3110. on the messages prior to being included in the return information.  Filtering 
  3111. can allow messages to be filtered based on subject, category, type of message, 
  3112. or other values.  To return all messages in the container without filtering, 
  3113. specify 'VIMSEL_NO_FILTER'. 
  3114.  
  3115. The seventh parameter is the value to be used for filtering, if specified.  If 
  3116. no filtering is indicated, this parameter should be null (''). 
  3117.  
  3118. The eighth parameter is the name of a variable to return a Boolean value 
  3119. indicating if additional messages exist in the message container. This value 
  3120. can be used to indicate that another call to RxVIMEnumerateMessageItems is 
  3121. necessary to process remaining messages in the container. 
  3122.  
  3123. Pos     = ''
  3124. Skipcnt = 1
  3125. Mcount  = 1
  3126. attrDesc = ''
  3127. filter  = 'VIMSEL_NO_FILTER'
  3128. fdata   = ''
  3129. more    = ''
  3130.  
  3131.  
  3132. call RxVIMEnumerateMessageItems MsgCont,'Pos',Skipcnt,'MCount','attrDesc',filter,fdata,'more'
  3133.  
  3134. or
  3135.  
  3136. rc = RxVIMEnumerateMessageItems(MsgCont,'Pos',Skipcnt,'MCount','attrDesc',filter,fdata,'more')
  3137.  
  3138. Listed below are the valid selectors to use to request filtering for each 
  3139. message (parameter five): 
  3140.  
  3141. VIMSEL_CLASS              Filter on the message item class
  3142.  
  3143.                           Pass one of following in filter data:
  3144.  
  3145.                           VIMSEL_NOTE_PART  - text portion of message
  3146.                           VIMSEL_ATTACH     - message attachments
  3147.                           VIMSEL_NESTED_MSG - nested message items
  3148.  
  3149.  
  3150. ΓòÉΓòÉΓòÉ 9.4.2. Return Codes ΓòÉΓòÉΓòÉ
  3151.  
  3152. The RxVIMEnumerateMessageItems function returns the following values: 
  3153.  
  3154.         0 - Successful return
  3155.  
  3156. The return values from all of the function calls return a zero for success, and 
  3157. non-zero for failure.  To retrieve the actual failure reason, use the 
  3158. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3159. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3160. be returned by RxVIMEnumerateMessageItems: 
  3161.  
  3162.         VIMSTS_SUCCESS                  Successful return
  3163.         VIMSTS_FAILURE                  Function Failed
  3164.  
  3165.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  3166.         VIMSTS_BUF_TOO_SMALL            Return buffer is too small
  3167.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  3168.         VIMSTS_INVALID_OBJECT           The message handle is bad
  3169.         VIMSTS_NOT_SUPPORTED            The filter selector is not supported
  3170.  
  3171.  
  3172. ΓòÉΓòÉΓòÉ 9.4.3. Example ΓòÉΓòÉΓòÉ
  3173.  
  3174. /* Example of using RxVIMEnumerateMessageItems */
  3175.  
  3176. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3177. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3178. call RxVIMLoadFuncs
  3179.  
  3180. /* This will establish a connection to the VIM system */
  3181. rc = RxVIMInitialize()
  3182. /* Obtain the default session information */
  3183. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3184. Say 'Default path:' db_path
  3185. Say 'Default name:' user_name
  3186. /* Opening a session with the mail subsystem */
  3187. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3188. /* Open the default message container (Inbox) */
  3189. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3190.  
  3191. /* Retrieve the first message from the container pulling the */
  3192. /* message reference number only                             */
  3193. pos = ''                                  /* Start at beginning */
  3194. skipcnt = 1                               /* Start at beginning */
  3195. mcount  = 1                               /* Return one message */
  3196. filter  = 'VIMSEL_NO_FILTER'              /* No filtering       */
  3197. fdata   = ''                              /* No filter data     */
  3198. flags   = 'VIM_NO_FLAGS'                  /* No flags           */
  3199. more = ''                                 /* more messages?     */
  3200. attrDesc.0 = 2                            /* retrieve 2 attributes    */
  3201. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference value          */
  3202. attrDesc.1.Buffer   = 'refno'             /* buffer to return refno   */
  3203. attrDesc.2.Selector = 'VIMSEL_SUBJECT'    /* message subject          */
  3204. attrDesc.2.Buffer   = 'Subject'           /* buffer to return subject */
  3205.  
  3206. rc = RxVIMEnumerateMessages(MsgCont,'pos',skipcnt,'attrDesc','mcount',filter,,
  3207.                             fdata,flags,'more')
  3208.  
  3209. /* Open the first message */
  3210. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3211.  
  3212. /* Retrieve the first text message item from the first message */
  3213. ipos     = ''
  3214. iskip    = 1
  3215. icount   = 1
  3216. ifilter  = 'VIMSEL_CLASS'
  3217. ifdata   = 'VIMSEL_NOTE_PART'
  3218. imore    = ''
  3219. attrItem = ''
  3220.  
  3221. rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
  3222.                             ifdata,'imore')
  3223.  
  3224. Say 'The first text message item of the first message'
  3225. Say 'has the following details'
  3226. Say
  3227. Say '    Item Class  -' attrItem.1.CLASS
  3228. Say '    Item Type   -' attrItem.1.TYPE
  3229. Say '    Item Name   -' attrItem.1.NAME
  3230. Say '    Item Size   -' attrItem.1.SIZE
  3231. Say '    Item Ref No -' attrItem.1.REF
  3232.  
  3233. /* Close the specified message container */
  3234. rc = RxVIMCloseMessageContainer( MsgCont )
  3235. /* Close the session with the mail subsystem */
  3236. rc = RxVIMCloseSession( Sess )
  3237. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3238. call RxVIMDropFuncs
  3239.  
  3240.  
  3241. ΓòÉΓòÉΓòÉ 9.5. RxVIMGetMessageItem ΓòÉΓòÉΓòÉ
  3242.  
  3243. The RxVIMGetMessageItem function reads a message item into a buffer or file. 
  3244.  
  3245.  
  3246. ΓòÉΓòÉΓòÉ 9.5.1. Syntax ΓòÉΓòÉΓòÉ
  3247.  
  3248. RxVIMGetMessageItem is called with five parameters.  The first parameter is the 
  3249. variable which contains a pointer to the open message.  The second parameter is 
  3250. the reference number of the item to retrieve.  The third parameter is the 
  3251. desired type for the message item.  The fourth parameter is a flag to control 
  3252. output file formats. 
  3253.  
  3254. The fifth parameter is a stem variable that contains the buffer name or the 
  3255. filespec for the message to be stored.  The stem variable has three components, 
  3256. the name of the buffer, the size of the buffer, and the name of the file.  If a 
  3257. filename is specified, the buffer variable is ignored.  The size of the buffer 
  3258. will control the amount of information returned from the item, up to a maximum 
  3259. size of 4096.  Size will be updated on return to indicate the actual amount 
  3260. read from the message item. 
  3261.  
  3262. BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
  3263. BufDesc.Size      = 256                /* Size of return buffer */
  3264. BufDesc.FileName  = ''                 /* NULL for filename     */
  3265.  
  3266.  
  3267. call RxVIMGetMessageItem MsgPtr, MsgItemRef, 'Text Type',, 'VIMSEL_NATIVE', 'BufDesc'
  3268.  
  3269. or
  3270.  
  3271. rc = RxVIMGetMessageItem( MsgPtr, MsgItemRef, 'Text Type',, 'VIMSEL_NATIVE', 'BufDesc' )
  3272.  
  3273. Listed below are the valid types to use to request message conversion 
  3274. (parameter three): 
  3275.  
  3276. VIM_TEXT                    Convert the message to ASCII text (from VIM_RTF)
  3277.  
  3278. VIM_RTF                     Convert the message to Rich Text Format (from VIM_TEXT)
  3279.  
  3280. Listed below are the valid selectors to use to request specific file output 
  3281. types (parameter four): 
  3282.  
  3283. VIMSEL_NATIVE               The output file will be written in the Operating System's                                  format.  (Extended attributes will be maintained)
  3284.  
  3285. VIMSEL_APPLESINGLE          The output file will be written in stream format.
  3286.  
  3287.  
  3288. ΓòÉΓòÉΓòÉ 9.5.2. Return Codes ΓòÉΓòÉΓòÉ
  3289.  
  3290. The RxVIMGetMessageItem function returns the following values: 
  3291.  
  3292.         0 - Successful function return
  3293.  
  3294. The return values from all of the function calls return a zero for success, and 
  3295. non-zero for failure.  To retrieve the actual failure reason, use the 
  3296. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3297. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3298. be returned by RxVIMGetMessageItem: 
  3299.  
  3300.         VIMSTS_SUCCESS                  Successful return
  3301.         VIMSTS_FAILURE                  Function Failed
  3302.  
  3303.         VIMSTS_BAD_PARAM                The message pointer is bad
  3304.         VIMSTS_CONV_NOT_SUPPORTED       Specified conversion not valid
  3305.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  3306.         VIMSTS_INVALID_OBJECT           The message handle is bad
  3307.         VIMSTS_INVALID_SELECTOR         The flags value is not correct
  3308.         VIMSTS_READ_FAILURE             Error reading from the disk
  3309.         VIMSTS_UNSUP_TYPE               The flags type is not correct
  3310.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  3311.  
  3312.  
  3313. ΓòÉΓòÉΓòÉ 9.5.3. Example ΓòÉΓòÉΓòÉ
  3314.  
  3315. /* Example of using RxVIMGetMessageItem */
  3316.  
  3317. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3318. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3319. call RxVIMLoadFuncs
  3320.  
  3321. /* This will establish a connection to the VIM system */
  3322. rc = RxVIMInitialize()
  3323.  
  3324. /* Obtain the default session information */
  3325. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3326. Say 'Default path:' db_path
  3327. Say 'Default name:' user_name
  3328.  
  3329. /* Opening a session with the mail subsystem */
  3330. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3331.  
  3332. /* Open the default message container (Inbox) */
  3333. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3334.  
  3335. /* Retrieve the first message from the container pulling the */
  3336. /* message reference number only                             */
  3337. attrDesc.0 = 1
  3338. attrDesc.selector = 'VIMSEL_REF'
  3339. attrDesc.buffer   = 'refno'
  3340.  
  3341. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  3342.                             '','VIM_NO_FLAGS','more')
  3343.  
  3344. /* Open the first message */
  3345. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3346.  
  3347. /* Retrieve the first text message item from the first message */
  3348. ipos     = ''
  3349. iskip    = 1
  3350. icount   = 1
  3351. ifilter  = 'VIMSEL_CLASS'
  3352. ifdata   = 'VIMSEL_NOTE_PART'
  3353. imore    = ''
  3354. attrItem = ''
  3355.  
  3356. rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
  3357.                             ifdata,'imore')
  3358.  
  3359.  
  3360. /* Store the message item in a Rexx variable */
  3361. BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
  3362. BufDesc.Size      = 2048               /* Size of return buffer */
  3363. BufDesc.FileName  = ''                 /* NULL for filename     */
  3364.  
  3365. rc = RxVIMGetMessageItem( MsgPtr, attrItem.1.REF, '', '', 'BufDesc')
  3366.  
  3367. /* Display first 60 characters of the message item */
  3368. Say 'First 60 characters of the message item'
  3369. Say SUBSTR(ItemText,1,60)
  3370.  
  3371.  
  3372. /* Close the specified message container */
  3373. rc = RxVIMCloseMessageContainer( MsgCont )
  3374.  
  3375. /* Close the session with the mail subsystem */
  3376. rc = RxVIMCloseSession( Sess )
  3377.  
  3378. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3379. call RxVIMDropFuncs
  3380.  
  3381.  
  3382. ΓòÉΓòÉΓòÉ 9.6. RxVIMOpenMessageItem ΓòÉΓòÉΓòÉ
  3383.  
  3384. The RxVIMOpenMessageItem function opens a message item in preparation for other 
  3385. actions. 
  3386.  
  3387.  
  3388. ΓòÉΓòÉΓòÉ 9.6.1. Syntax ΓòÉΓòÉΓòÉ
  3389.  
  3390. RxVIMOpenMessageItem is called with five parameters.  The first parameter is 
  3391. the variable which contains a pointer to the open message.  The second 
  3392. parameter is the reference number of the item to retrieve.  The third parameter 
  3393. is the desired type for the message item.  The fourth parameter is a flag to 
  3394. control output file formats. The fifth parameter is a variable which will 
  3395. contain a pointer to the message item. 
  3396.  
  3397. call RxVIMGetMessageItem MsgPtr, MsgItemRef, 'Text Type', 'VIMSEL_NATIVE', 'MsgItemPtr'
  3398.  
  3399. or
  3400.  
  3401. rc = RxVIMGetMessageItem( MsgPtr, MsgItemRef, 'Text Type', 'VIMSEL_NATIVE', 'MsgItemPtr' )
  3402.  
  3403. Listed below are the valid types to use to request message conversion 
  3404. (parameter three): 
  3405.  
  3406. VIM_TEXT                    Convert the message to ASCII text (from VIM_RTF)
  3407.  
  3408. VIM_RTF                     Convert the message to Rich Text Format (from VIM_TEXT)
  3409.  
  3410. Listed below are the valid selectors to use to request specific file output 
  3411. types (parameter four): 
  3412.  
  3413. VIMSEL_NATIVE               The output file will be written in the Operating System's                                  format.  (Extended attributes will be maintained)
  3414.  
  3415. VIMSEL_APPLESINGLE          The output file will be written in stream format.
  3416.  
  3417.  
  3418. ΓòÉΓòÉΓòÉ 9.6.2. Return Codes ΓòÉΓòÉΓòÉ
  3419.  
  3420. The RxVIMGetMessageItem function returns the following values: 
  3421.  
  3422.         0 - Successful function return
  3423.  
  3424. The return values from all of the function calls return a zero for success, and 
  3425. non-zero for failure.  To retrieve the actual failure reason, use the 
  3426. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3427. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3428. be returned by RxVIMGetMessageItem: 
  3429.  
  3430.         VIMSTS_SUCCESS                  Successful return
  3431.         VIMSTS_FAILURE                  Function Failed
  3432.  
  3433.         VIMSTS_BAD_PARAM                The message pointer is bad
  3434.         VIMSTS_CONV_NOT_SUPPORTED       Specified conversion not valid
  3435.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  3436.         VIMSTS_INVALID_OBJECT           The message handle is bad
  3437.         VIMSTS_INVALID_SELECTOR         The flags value is not correct
  3438.         VIMSTS_READ_FAILURE             Error reading from the disk
  3439.         VIMSTS_UNSUP_TYPE               The flags type is not correct
  3440.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  3441.  
  3442.  
  3443. ΓòÉΓòÉΓòÉ 9.6.3. Example ΓòÉΓòÉΓòÉ
  3444.  
  3445. /* Example of using RxVIMOpenMessageItem */
  3446. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3447. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3448. call RxVIMLoadFuncs
  3449.  
  3450. /* This will establish a connection to the VIM system */
  3451. rc = RxVIMInitialize()
  3452.  
  3453. /* Obtain the default session information */
  3454. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3455.  
  3456. Say 'Default path:' db_path
  3457. Say 'Default name:' user_name
  3458.  
  3459. /* Opening a session with the mail subsystem */
  3460. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3461.  
  3462. /* Open the default message container (Inbox) */
  3463. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3464.  
  3465. /* Retrieve the first message from the container pulling the */
  3466. /* message reference number only                             */
  3467. attrDesc.0 = 1
  3468. attrDesc.selector = 'VIMSEL_REF'
  3469. attrDesc.buffer   = 'refno'
  3470.  
  3471. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  3472.                             '','VIM_NO_FLAGS','more')
  3473.  
  3474. /* Open the first message */
  3475. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3476.  
  3477. /* Retrieve the first text message item from the first message */
  3478. ipos     = ''
  3479. iskip    = 1
  3480. icount   = 1
  3481. ifilter  = 'VIMSEL_CLASS'
  3482. ifdata   = 'VIMSEL_NOTE_PART'
  3483. imore    = ''
  3484. attrItem = ''
  3485.  
  3486. rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
  3487.                             ifdata,'imore')
  3488.  
  3489.  
  3490. /* Open the message item */
  3491. rc = RxVIMOpenMessageItem( MsgPtr, attrItem.1.REF, '', '', 'MsgItemPtr')
  3492.  
  3493. /* Close the specified message container */
  3494. rc = RxVIMCloseMessageContainer( MsgCont )
  3495. /* Close the session with the mail subsystem */
  3496. rc = RxVIMCloseSession( Sess )
  3497. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3498. call RxVIMDropFuncs
  3499.  
  3500.  
  3501. ΓòÉΓòÉΓòÉ 9.7. RxVIMReadMessageItem ΓòÉΓòÉΓòÉ
  3502.  
  3503. The RxVIMReadMessageItem function reads a message item into a buffer in 
  3504. sections. 
  3505.  
  3506.  
  3507. ΓòÉΓòÉΓòÉ 9.7.1. Syntax ΓòÉΓòÉΓòÉ
  3508.  
  3509. RxVIMReadMessageItem is called with two parameters.  The first parameter is the 
  3510. variable which contains a pointer to the open message item. 
  3511.  
  3512. The second parameter is a stem variable that contains the buffer name for the 
  3513. message to be stored.  The stem variable has three components, the name of the 
  3514. buffer, the size of the buffer, and the offset.  The size of the buffer will 
  3515. control the amount of information returned from the item, up to a maximum size 
  3516. of 4096.  Size will be updated on return to indicate the actual amount read 
  3517. from the message item.  The offset is updated on return to indicate the 
  3518. location within the message item.  When offset equals the size of the item, the 
  3519. entire item has been read. 
  3520.  
  3521. BufDesc.Buffer    = 'ItemText'         /* Return buffer name        */
  3522. BufDesc.Size      = 256                /* Size of return buffer     */
  3523. BufDesc.Offset    = 0                  /* Offset into  message item */
  3524.  
  3525. call RxVIMReadMessageItem MsgItemPtr, 'BufDesc'
  3526.  
  3527. or
  3528.  
  3529. rc = RxVIMReadMessageItem( MsgItemPtr, 'BufDesc' )
  3530.  
  3531.  
  3532. ΓòÉΓòÉΓòÉ 9.7.2. Return Codes ΓòÉΓòÉΓòÉ
  3533.  
  3534. The RxVIMReadMessageItem function returns the following values: 
  3535.  
  3536.         0 - Successful function return
  3537.  
  3538. The return values from all of the function calls return a zero for success, and 
  3539. non-zero for failure.  To retrieve the actual failure reason, use the 
  3540. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3541. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3542. be returned by RxVIMReadMessageItem: 
  3543.  
  3544.         VIMSTS_SUCCESS                  Successful return
  3545.         VIMSTS_FAILURE                  Function Failed
  3546.  
  3547.         VIMSTS_BAD_PARAM                The message item pointer is bad
  3548.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  3549.         VIMSTS_INVALID_OBJECT           The message item handle is bad
  3550.         VIMSTS_READ_FAILURE             Error reading from the disk
  3551.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  3552.  
  3553.  
  3554. ΓòÉΓòÉΓòÉ 9.7.3. Example ΓòÉΓòÉΓòÉ
  3555.  
  3556. /* Example of using RxVIMReadMessageItem */
  3557.  
  3558. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3559. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3560. call RxVIMLoadFuncs
  3561.  
  3562. /* This will establish a connection to the VIM system */
  3563. rc = RxVIMInitialize()
  3564.  
  3565. /* Obtain the default session information */
  3566. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3567.  
  3568. Say 'Default path:' db_path
  3569. Say 'Default name:' user_name
  3570.  
  3571. /* Opening a session with the mail subsystem */
  3572. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3573.  
  3574. /* Open the default message container (Inbox) */
  3575. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3576.  
  3577. /* Retrieve the first message from the container pulling the */
  3578. /* message reference number only                             */
  3579. attrDesc.0 = 1
  3580. attrDesc.selector = 'VIMSEL_REF'
  3581. attrDesc.buffer   = 'refno'
  3582.  
  3583. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  3584.                             '','VIM_NO_FLAGS','more')
  3585.  
  3586. /* Open the first message */
  3587. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3588.  
  3589. /* Retrieve the first text message item from the first message */
  3590. ipos     = ''
  3591. iskip    = 1
  3592. icount   = 1
  3593. ifilter  = 'VIMSEL_CLASS'
  3594. ifdata   = 'VIMSEL_NOTE_PART'
  3595. imore    = ''
  3596. attrItem = ''
  3597.  
  3598. rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
  3599.                             ifdata,'imore')
  3600.  
  3601.  
  3602. /* Open the message item */
  3603. rc = RxVIMOpenMessageItem( MsgPtr, attrItem.1.REF, '', '', 'MsgItemPtr')
  3604.  
  3605.  
  3606. /* Store the first 2K of message item in a Rexx variable */
  3607. BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
  3608. BufDesc.Size      = 2048               /* Size of return buffer */
  3609. BufDesc.Offset    = 0
  3610.  
  3611. rc = RxVIMReadMessageItem( MsgItemPtr, 'BufDesc')
  3612.  
  3613. /* Close the specified message container */
  3614. rc = RxVIMCloseMessageContainer( MsgCont )
  3615.  
  3616. /* Close the session with the mail subsystem */
  3617. rc = RxVIMCloseSession( Sess )
  3618.  
  3619. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3620. call RxVIMDropFuncs
  3621.  
  3622.  
  3623. ΓòÉΓòÉΓòÉ 9.8. RxVIMCloseMessageItem ΓòÉΓòÉΓòÉ
  3624.  
  3625. The RxVIMCloseMessageItem function closes a message item that has been opened 
  3626. for action. 
  3627.  
  3628.  
  3629. ΓòÉΓòÉΓòÉ 9.8.1. Syntax ΓòÉΓòÉΓòÉ
  3630.  
  3631. RxVIMCloseMessageItem is called with one parameter.  The parameter is the 
  3632. variable which contains a pointer to the open message item. 
  3633.  
  3634. call RxVIMCloseMessageItem MsgItemPtr
  3635.  
  3636. or
  3637.  
  3638. rc = RxVIMCloseMessageItem( MsgItemPtr )
  3639.  
  3640.  
  3641. ΓòÉΓòÉΓòÉ 9.8.2. Return Codes ΓòÉΓòÉΓòÉ
  3642.  
  3643. The RxVIMCloseMessageItem function returns the following values: 
  3644.  
  3645.         0 - Successful function return
  3646.  
  3647. The return values from all of the function calls return a zero for success, and 
  3648. non-zero for failure.  To retrieve the actual failure reason, use the 
  3649. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3650. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3651. be returned by RxVIMCloseMessageItem: 
  3652.  
  3653.         VIMSTS_SUCCESS                  Successful return
  3654.         VIMSTS_FAILURE                  Function Failed
  3655.  
  3656.         VIMSTS_INVALID_OBJECT           The message item handle is bad
  3657.  
  3658.  
  3659. ΓòÉΓòÉΓòÉ 9.8.3. Example ΓòÉΓòÉΓòÉ
  3660.  
  3661. /* Example of using RxVIMCloseMessageItem */
  3662.  
  3663. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3664. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3665. call RxVIMLoadFuncs
  3666.  
  3667. /* This will establish a connection to the VIM system */
  3668. rc = RxVIMInitialize()
  3669.  
  3670. /* Obtain the default session information */
  3671. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3672. Say 'Default path:' db_path
  3673. Say 'Default name:' user_name
  3674.  
  3675. /* Opening a session with the mail subsystem */
  3676. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3677.  
  3678. /* Open the default message container (Inbox) */
  3679. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3680.  
  3681. /* Retrieve the first message from the container pulling the */
  3682. /* message reference number only                             */
  3683. attrDesc.0 = 1
  3684. attrDesc.selector = 'VIMSEL_REF'
  3685. attrDesc.buffer   = 'refno'
  3686.  
  3687. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  3688.                             '','VIM_NO_FLAGS','more')
  3689.  
  3690. /* Open the first message */
  3691. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3692.  
  3693. /* Retrieve the first text message item from the first message */
  3694. ipos     = ''
  3695. iskip    = 1
  3696. icount   = 1
  3697. ifilter  = 'VIMSEL_CLASS'
  3698. ifdata   = 'VIMSEL_NOTE_PART'
  3699. imore    = ''
  3700. attrItem = ''
  3701.  
  3702. rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
  3703.                             ifdata,'imore')
  3704.  
  3705. /* Open the message item */
  3706. rc = RxVIMOpenMessageItem( MsgPtr, attrItem.1.REF, '', '', 'MsgItemPtr')
  3707.  
  3708.  
  3709. /* Close the message item */
  3710. rc = RxVIMCloseMessageItem( MsgItemPtr )
  3711.  
  3712.  
  3713. /* Close the specified message container */
  3714. rc = RxVIMCloseMessageContainer( MsgCont )
  3715.  
  3716. /* Close the session with the mail subsystem */
  3717. rc = RxVIMCloseSession( Sess )
  3718.  
  3719. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3720. call RxVIMDropFuncs
  3721.  
  3722.  
  3723. ΓòÉΓòÉΓòÉ 9.9. RxVIMEnumerateMessageRecipients ΓòÉΓòÉΓòÉ
  3724.  
  3725. The RxVIMEnumerateMessageRecipients function retrieves one or more recipients 
  3726. of the specified message. 
  3727.  
  3728.  
  3729. ΓòÉΓòÉΓòÉ 9.9.1. Syntax ΓòÉΓòÉΓòÉ
  3730.  
  3731. RxVIMEnumerateMessageRecipients is called with seven parameters.  The first 
  3732. parameter is the pointer to the open message, which was returned from the open 
  3733. of the message. 
  3734.  
  3735. The second parameter is a selector that indicates the type of recipients to 
  3736. retrieve. 
  3737.  
  3738. The third is a variable containing the starting position within the message 
  3739. recipients.  To start at the beginning, the value of the variable should be set 
  3740. to null ('').  For subsequent calls, this value will contain the return value 
  3741. from the previous call.  This entry MUST be a variable name, since the function 
  3742. returns the value of the next starting position. 
  3743.  
  3744. The fourth parameter is the number of entries to skip before or after the 
  3745. starting position.  To start at the beginning and move forward, this should be 
  3746. set to a value of 1.  To start at the end, and move in reverse, this should be 
  3747. set to a value of -1. 
  3748.  
  3749. The fifth parameter is a stem variable name that contains the number of 
  3750. attributes to retrieve at the root, and a Selector and Buffer entry for each 
  3751. attribute.  The Selector entry contains the selector to retrieve, and the 
  3752. Buffer entry contains the name of the variable to return the values. 
  3753.  
  3754. An example of a properly formatted attribute description buffer is shown below: 
  3755.  
  3756.       attrDesc.0 = 1
  3757.       attrDesc.1.Selector = 'VIMSEL_NAME'
  3758.       attrDesc.1.Buffer   = 'Name'
  3759.  
  3760. The sixth parameter is a variable that contains the number of recipients to 
  3761. read for the call.  Upon return, the variable contains the number of recipients 
  3762. actually read.  This entry MUST be a variable name, since the function returns 
  3763. the number of recipients actually read. 
  3764.  
  3765. The seventh parameter is the name of a variable to return a Boolean value 
  3766. indicating if additional recipients exist for this message.  This value can be 
  3767. used to indicate that another call to RxVIMEnumerateRecipients is necessary to 
  3768. process remaining recipients for this message. 
  3769.  
  3770. Pos     = ''
  3771. Skipcnt = 1
  3772. Mcount  = 1
  3773. Rtype   = 'VIMSEL_TO'
  3774. attrDesc.0 = 1
  3775. attrDesc.1.Selector = 'VIMSEL_NAME'
  3776. attrDesc.1.Buffer   = 'Name'
  3777. more    = ''
  3778.  
  3779.  
  3780.  
  3781. call RxVIMEnumerateMessageRecipients Message,Rtype,'Pos',Skipcnt,'attrDesc','MCount','more'
  3782.  
  3783. or
  3784.  
  3785. rc = RxVIMEnumerateMessageRecipients( Message,Rtype,'Pos',Skipcnt,'attrDesc','MCount','more' )
  3786.  
  3787. Listed below are the valid selectors to use to specify the type of recipients 
  3788. to retrieve: 
  3789.  
  3790. VIMSEL_TO                       Retrieves recipients on the TO list
  3791.  
  3792. VIMSEL_CC                       Retrieves recipients on the CC list
  3793.  
  3794. VIMSEL_BCC                      Retrieves recipients on the BCC list
  3795.  
  3796. Listed below are the valid selectors to use to specific information from the 
  3797. call: 
  3798.  
  3799. VIMSEL_NAME                     Return the name of the recipient
  3800.  
  3801. VIMSEL_FAILURE_REASON           Return the reason a delivery failed
  3802.  
  3803. VIMSEL_FAN                      Return the Foreign Alias Name for this
  3804.                                 recipient, used in gateway applications
  3805.  
  3806. VIMSEL_RECIP_STATUS             Return True if message has been                                          delivered
  3807.                                 or False if it has not been delivered
  3808.  
  3809. The function will return the requested attribute values in the specified buffer 
  3810. as stem values with the following 
  3811.  
  3812. format: 
  3813.  
  3814.          'Name' specified to receive recipient name
  3815.          5 messages are retrieved
  3816.  
  3817.          Name.0 = 5
  3818.          Name.1 = 'Name of the first  recipient'
  3819.          Name.2 = 'Name of the second recipient'
  3820.          Name.3 = 'Name of the third recipient'
  3821.          Name.4 = 'Name of the fourth recipient'
  3822.          Name.5 = 'Name of the fifth recipient'
  3823.  
  3824.  
  3825. ΓòÉΓòÉΓòÉ 9.9.2. Return Codes ΓòÉΓòÉΓòÉ
  3826.  
  3827. The RxVIMEnumerateMessageRecipients function returns the following values: 
  3828.  
  3829.         0 - Successful return
  3830.  
  3831. The return values from all of the function calls return a zero for success, and 
  3832. non-zero for failure.  To retrieve the actual failure reason, use the 
  3833. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3834. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3835. be returned by RxVIMEnumerateMessageRecipients: 
  3836.  
  3837.         VIMSTS_SUCCESS                  Successful return
  3838.         VIMSTS_FAILURE                  Function Failed
  3839.  
  3840.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  3841.         VIMSTS_BUF_TOO_SMALL            Return buffer is too small
  3842.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  3843.         VIMSTS_INVALID_OBJECT           The message handle is bad
  3844.         VIMSTS_INVALID_SELECTOR         The requested type is bad
  3845.  
  3846.  
  3847. ΓòÉΓòÉΓòÉ 9.9.3. Example ΓòÉΓòÉΓòÉ
  3848.  
  3849. /* Example of using RxVIMEnumerateMessageRecipientss */
  3850.  
  3851. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3852. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3853. call RxVIMLoadFuncs
  3854.  
  3855.  
  3856. /* This will establish a connection to the VIM system */
  3857. rc = RxVIMInitialize()
  3858. /* Obtain the default session information */
  3859. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3860. Say 'Default path:' db_path
  3861. Say 'Default name:' user_name
  3862. /* Opening a session with the mail subsystem */
  3863. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3864.  
  3865. /* Open the default message container (Inbox) */
  3866. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3867.  
  3868. /* Retrieve the first message from the container pulling the */
  3869. /* message reference number only                             */
  3870. pos = ''                                  /* Start at beginning */
  3871. skipcnt = 1                               /* Start at beginning */
  3872. mcount  = 1                               /* Return one message */
  3873. filter  = 'VIMSEL_NO_FILTER'              /* No filtering       */
  3874. fdata   = ''                              /* No filter data     */
  3875. flags   = 'VIM_NO_FLAGS'                  /* No flags           */
  3876. more = ''                                 /* more messages?     */
  3877.  
  3878. attrDesc.0 = 2                            /* retrieve 2 attributes    */
  3879. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference value          */
  3880. attrDesc.1.Buffer   = 'refno'             /* buffer to return refno   */
  3881. attrDesc.2.Selector = 'VIMSEL_SUBJECT'    /* message subject          */
  3882. attrDesc.2.Buffer   = 'Subject'           /* buffer to return subject */
  3883.  
  3884. rc = RxVIMEnumerateMessages(MsgCont,'pos',skipcnt,'attrDesc','mcount',filter,,
  3885.                             fdata,flags,'more')
  3886.  
  3887. /* Open the first message */
  3888. rc = RxVIMOpenMessage(MsgCont,refno.1,'','Message')
  3889.  
  3890.  
  3891. /* Retrieve the name of the first recipient on the TO list */
  3892.  
  3893. mpos = ''                                  /* Start at beginning   */
  3894. mskipcnt = 1                               /* Start at beginning   */
  3895. mcount  = 1                                /* Return one recipient */
  3896. more = ''                                  /* more recipients?     */
  3897.  
  3898. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  3899. attrDesc.1.Selector = 'VIMSEL_NAME'       /* recipient name           */
  3900. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  3901.  
  3902. rc = RxVIMEnumerateMessageRecipients(Message,'VIMSEL_TO','mpos',mskipcnt,'attrDesc',,
  3903.                                      'mcount','more')
  3904.  
  3905. Say 'The name of the first recipient is' name.1
  3906.  
  3907.  
  3908. /* Close the specified message container */
  3909. rc = RxVIMCloseMessageContainer( MsgCont )
  3910.  
  3911. /* Close the session with the mail subsystem */
  3912. rc = RxVIMCloseSession( Sess )
  3913.  
  3914. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  3915. call RxVIMDropFuncs
  3916.  
  3917.  
  3918. ΓòÉΓòÉΓòÉ 9.10. RxVIMOpenNestedMessage ΓòÉΓòÉΓòÉ
  3919.  
  3920. The RxVIMOpenNestedMessage function opens the specified nested message with the 
  3921. VIM system.  After the message has been opened, the other message functions can 
  3922. be used for further message processing.  A nested message is one that has been 
  3923. created with RxVIMCreateNestedMessage.  By opening the message as a nested 
  3924. message, the history can be reviewed at that particular point. 
  3925.  
  3926.  
  3927. ΓòÉΓòÉΓòÉ 9.10.1. Syntax ΓòÉΓòÉΓòÉ
  3928.  
  3929. RxVIMOpenNestedMessage is called with three parameter.  The first parameter is 
  3930. the variable which contains a pointer to the open message containing a nested 
  3931. message.  The second parameter is the reference number of the nested message to 
  3932. open.  The third parameter is the name of the variable to return the pointer to 
  3933. the nested message. 
  3934.  
  3935. call RxVIMOpenNestedMessage Message, MsgRef, 'NestMsgPtr'
  3936.  
  3937. or
  3938.  
  3939. rc = RxVIMOpenNestedMessage( Message, MsgRef, 'NestMsgPtr' )
  3940.  
  3941.  
  3942. ΓòÉΓòÉΓòÉ 9.10.2. Return Codes ΓòÉΓòÉΓòÉ
  3943.  
  3944. The RxVIMOpenNestedMessage function returns the following values: 
  3945.  
  3946.         0 - Successful function return
  3947.  
  3948. The return values from all of the function calls return a zero for success, and 
  3949. non-zero for failure.  To retrieve the actual failure reason, use the 
  3950. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  3951. value to the actual failure text.  Using RxVIMStatus, the following values may 
  3952. be returned by RxVIMOpenNestedMessage: 
  3953.  
  3954.         VIMSTS_SUCCESS                  Successful return
  3955.         VIMSTS_FAILURE                  Function Failed
  3956.  
  3957.         VIMSTS_BAD_PARAM                The message reference is bad
  3958.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  3959.         VIMSTS_INVALID_OBJECT           The message handle is bad
  3960.         VIMSTS_NOT_SUPPORTED            This function is not supported
  3961.  
  3962.  
  3963. ΓòÉΓòÉΓòÉ 9.10.3. Example ΓòÉΓòÉΓòÉ
  3964.  
  3965. /* Example of using RxVIMOpenNestedMessage */
  3966.  
  3967. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  3968. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  3969. call RxVIMLoadFuncs
  3970.  
  3971. /* This will establish a connection to the VIM system */
  3972. rc = RxVIMInitialize()
  3973.  
  3974. /* Obtain the default session information */
  3975. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  3976.  
  3977. Say 'Default path:' db_path
  3978. Say 'Default name:' user_name
  3979.  
  3980. /* Opening a session with the mail subsystem */
  3981. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  3982.  
  3983. /* Open the default message container (Inbox) */
  3984. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  3985.  
  3986. /* Retrieve the first message from the container pulling the */
  3987. /* message reference number only                             */
  3988. attrDesc.0 = 1
  3989. attrDesc.selector = 'VIMSEL_REF'
  3990. attrDesc.buffer   = 'refno'
  3991.  
  3992. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  3993.                             '','VIM_NO_FLAGS','more')
  3994.  
  3995.  
  3996. /* Open the first message */
  3997. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  3998.  
  3999.  
  4000. /* Enumerate the nested message items */
  4001. ipos     = ''
  4002. iskip    = 1
  4003. icount   = 1
  4004. ifilter  = 'VIMSEL_CLASS'
  4005. ifdata   = 'VIMSEL_NESTED_MSG'
  4006. imore    = ''
  4007. attrItem = ''
  4008.  
  4009. rc = RxVIMEnumerateMessageItems(MsgPtr,'ipos',iskip,'icount','attrItem',ifilter,,
  4010.                             ifdata,'imore')
  4011.  
  4012. /* THIS EXAMPLE ASSUMES THAT THE FIRST MESSAGE IN THE INBOX CONTAINS */
  4013. /* NESTED MESSAGES.  THIS EXAMPLE WILL FAIL IF THE FIRST MESSAGE     */
  4014. /* DOES NOT CONTAIN NESTED MESSAGES                                  */
  4015.  
  4016.  
  4017. /* Open the first occurrence of nesting in message */
  4018. rc = RxVIMOpenNestedMessage(MsgPtr,attrItem.1.REF,'NestMsgPtr')
  4019.  
  4020.  
  4021. /* Close the specified message */
  4022. rc = RxVIMCloseMessage( NestMsgPtr )
  4023.  
  4024. /* Close the specified message container */
  4025. rc = RxVIMCloseMessageContainer( MsgCont )
  4026.  
  4027. /* Close the session with the mail subsystem */
  4028. rc = RxVIMCloseSession( Sess )
  4029.  
  4030. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4031. call RxVIMDropFuncs
  4032.  
  4033.  
  4034. ΓòÉΓòÉΓòÉ 9.11. RxVIMExtractMessage ΓòÉΓòÉΓòÉ
  4035.  
  4036. The RxVIMExtractMessage function moves the message from the message container 
  4037. into a file. 
  4038.  
  4039.  
  4040. ΓòÉΓòÉΓòÉ 9.11.1. Syntax ΓòÉΓòÉΓòÉ
  4041.  
  4042. RxVIMExtractMessage is called with three parameter.  The first parameter is the 
  4043. name of the variable that contains a pointer to the message.  The second 
  4044. parameter are control flags for the extract.  The third is the filespec of the 
  4045. file into which the message will be extracted. 
  4046.  
  4047. call RxVIMExtractMessage MsgPtr, 'flags', 'file_name'
  4048.  
  4049. or
  4050.  
  4051. rc = RxVIMExtractMessage( MsgPtr, 'flags', 'file_name' )
  4052.  
  4053. Listed below are the valid types to use to specify extraction options: 
  4054.  
  4055. VIM_NO_FLAGS                    No extract options
  4056.  
  4057. VIM_EXTRACT_REF                 Extract only reference information,
  4058.                                 not the actual message
  4059.  
  4060.  
  4061. ΓòÉΓòÉΓòÉ 9.11.2. Return Codes ΓòÉΓòÉΓòÉ
  4062.  
  4063. The RxVIMExtractMessage function returns the following values: 
  4064.  
  4065.         0 - Successful function return
  4066.  
  4067. The return values from all of the function calls return a zero for success, and 
  4068. non-zero for failure.  To retrieve the actual failure reason, use the 
  4069. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4070. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4071. be returned by RxVIMExtractMessage: 
  4072.  
  4073.         VIMSTS_SUCCESS                  Successful return
  4074.         VIMSTS_FAILURE                  Function Failed
  4075.  
  4076.         VIMSTS_BAD_PARAM                The filespec is bad
  4077.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  4078.         VIMSTS_INVALID_OBJECT           The message handle is bad
  4079.         VIMSTS_NOT_SUPPORTED            Flag value is not supported
  4080.         VIMSTS_OPEN_FAILURE             The file could not be opened
  4081.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  4082.  
  4083.  
  4084. ΓòÉΓòÉΓòÉ 9.11.3. Example ΓòÉΓòÉΓòÉ
  4085.  
  4086. /* Example of using RxVIMExtractMessage */
  4087.  
  4088. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4089. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4090. call RxVIMLoadFuncs
  4091.  
  4092. /* This will establish a connection to the VIM system */
  4093. rc = RxVIMInitialize()
  4094.  
  4095. /* Obtain the default session information */
  4096. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4097.  
  4098. Say 'Default path:' db_path
  4099. Say 'Default name:' user_name
  4100.  
  4101. /* Opening a session with the mail subsystem */
  4102. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4103.  
  4104. /* Open the default message container (Inbox) */
  4105. rc = RxVIMOpenMessageContainer(Sess,'','MsgCont')
  4106.  
  4107. /* Retrieve the first message from the container pulling the */
  4108. /* message reference number only                             */
  4109. attrDesc.0 = 1
  4110. attrDesc.selector = 'VIMSEL_REF'
  4111. attrDesc.buffer   = 'refno'
  4112.  
  4113. rc = RxVIMEnumerateMessages(MsgCont,'',1,'attrDesc',1,'VIMSEL_NO_FILTER',,
  4114.                             '','VIM_NO_FLAGS','more')
  4115.  
  4116. /* Open the first message */
  4117. rc = RxVIMOpenMessage(MsgCont,refno.1,'','MsgPtr')
  4118.  
  4119.  
  4120. /* Extract the message to a file */
  4121. path  = '\RexxVIM\'
  4122. filename = 'message.dat'
  4123. filespec = path || filename
  4124.  
  4125. rc = RxVIMExtractMessage(MsgPtr,'VIM_NO_FLAGS',filespec)
  4126.  
  4127.  
  4128. /* Close the specified message */
  4129. rc = RxVIMCloseMessage( MsgPtr )
  4130.  
  4131. /* Close the specified message container */
  4132. rc = RxVIMCloseMessageContainer( MsgCont )
  4133.  
  4134. /* Close the session with the mail subsystem */
  4135. rc = RxVIMCloseSession( Sess )
  4136.  
  4137. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4138. call RxVIMDropFuncs
  4139.  
  4140.  
  4141. ΓòÉΓòÉΓòÉ 9.12. RxVIMOpenExtractedMessage ΓòÉΓòÉΓòÉ
  4142.  
  4143. The RxVIMOpenExtractedMessage function opens the specified message which has 
  4144. been previously extracted to a file.  After the message has been opened, the 
  4145. other message functions can be used for further message processing. 
  4146.  
  4147.  
  4148. ΓòÉΓòÉΓòÉ 9.12.1. Syntax ΓòÉΓòÉΓòÉ
  4149.  
  4150. RxVIMOpenExtractedMessage is called with three parameter.  The first parameter 
  4151. is the variable which contains a pointer to the current VIM session.  The 
  4152. second parameter is the filespec for the extracted message to open.  The third 
  4153. parameter is the name of the variable to return the pointer to the message. 
  4154.  
  4155. call RxVIMOpenExtractedMessage Session, 'file_name', 'MsgPtr'
  4156.  
  4157. or
  4158.  
  4159. rc = RxVIMOpenExtractedMessage( Session, 'file_name', 'MsgPtr' )
  4160.  
  4161.  
  4162. ΓòÉΓòÉΓòÉ 9.12.2. Return Codes ΓòÉΓòÉΓòÉ
  4163.  
  4164. The RxVIMOpenExtractedMessage function returns the following values: 
  4165.  
  4166.         0 - Successful function return
  4167.  
  4168. The return values from all of the function calls return a zero for success, and 
  4169. non-zero for failure.  To retrieve the actual failure reason, use the 
  4170. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4171. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4172. be returned by RxVIMOpenExtractedMessage: 
  4173.  
  4174.         VIMSTS_SUCCESS                  Successful return
  4175.         VIMSTS_FAILURE                  Function Failed
  4176.  
  4177.         VIMSTS_BAD_PARAM                File name is bad
  4178.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  4179.         VIMSTS_INVALID_OBJECT           The session handle is bad
  4180.         VIMSTS_OPEN_FAILURE             File could not be opened
  4181.         VIMSTS_READ_FAILURE             Error reading from the disk
  4182.  
  4183.  
  4184. ΓòÉΓòÉΓòÉ 9.12.3. Example ΓòÉΓòÉΓòÉ
  4185.  
  4186. /* Example of using RxVIMOpenExtractedMessage */
  4187.  
  4188. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4189. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4190. call RxVIMLoadFuncs
  4191.  
  4192. /* This will establish a connection to the VIM system */
  4193. rc = RxVIMInitialize()
  4194.  
  4195. /* Obtain the default session information */
  4196. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4197.  
  4198. Say 'Default path:' db_path
  4199. Say 'Default name:' user_name
  4200.  
  4201. /* Opening a session with the mail subsystem */
  4202. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4203.  
  4204.  
  4205.  
  4206. /* Open an extracted message */
  4207. path  = '\RexxVIM\'
  4208. filename = 'message.dat'
  4209. filespec = path || filename
  4210.  
  4211. rc = RxVIMOpenMessage(Sess,filespec,'MsgPtr')
  4212.  
  4213.  
  4214.  
  4215. /* Close the message */
  4216. rc = RxVIMCloseMessage( MsgPtr )
  4217.  
  4218. /* Close the session with the mail subsystem */
  4219. rc = RxVIMCloseSession( Sess )
  4220.  
  4221. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4222. call RxVIMDropFuncs
  4223.  
  4224.  
  4225. ΓòÉΓòÉΓòÉ 10. Address Book Functions ΓòÉΓòÉΓòÉ
  4226.  
  4227. This section describes each of the functions available in the RexxVIM product 
  4228. that support address book access and manipulation. 
  4229.  
  4230. Below are all of the Address Book functions: 
  4231.  
  4232. RxVIMEnumerateAddressBooks 
  4233.  
  4234. RxVIMOpenAddressBook 
  4235.  
  4236. RxVIMSetCurrentSubtree 
  4237.  
  4238. RxVIMGetCurrentSubtree 
  4239.  
  4240. RxVIMEnumerateAddressBookEntries 
  4241.  
  4242. RxVIMCreateAddressBookEntry 
  4243.  
  4244. RxVIMMatchAddressBookEntry 
  4245.  
  4246. RxVIMGetABEntryAttributes 
  4247.  
  4248. RxVIMSetABEntryAttributes 
  4249.  
  4250. RxVIMRemoveAddressBookEntry 
  4251.  
  4252. RxVIMAddGroupMember 
  4253.  
  4254. RxVIMRemoveGroupMember 
  4255.  
  4256. RxVIMEnumerateGroupMember 
  4257.  
  4258. RxVIMCloseAddressBook 
  4259.  
  4260.  
  4261. ΓòÉΓòÉΓòÉ 10.1. RxVIMEnumerateAddressBooks ΓòÉΓòÉΓòÉ
  4262.  
  4263. The RxVIMEnumerateAddressBooks function retrieves one or more attributes about 
  4264. the address books available in the current session. 
  4265.  
  4266.  
  4267. ΓòÉΓòÉΓòÉ 10.1.1. Syntax ΓòÉΓòÉΓòÉ
  4268.  
  4269. RxVIMEnumerateAddressBooks is called with six parameters.  The first parameter 
  4270. is the pointer to the current session. 
  4271.  
  4272. The second is a variable containing the starting position within the address 
  4273. book list.  To start at the beginning, the value of the variable should be set 
  4274. to null ('').  For subsequent calls, this value will contain the return value 
  4275. from the previous call.  This entry MUST be a variable name, since the function 
  4276. returns the value of the next starting position. 
  4277.  
  4278. The third parameter is the number of entries to skip before or after the 
  4279. starting position.  To start at the beginning and move forward, this should be 
  4280. set to a value of 1.  To start at the end, and move in reverse, 
  4281.  
  4282. this should be set to a value of -1. 
  4283.  
  4284. The fourth parameter is a stem variable name that contains the number of 
  4285. attributes to retrieve at the root, and a Selector and Buffer entry for each 
  4286. attribute.  The Selector entry contains the selector to retrieve, and the 
  4287. Buffer entry contains the name of the variable to return the values. 
  4288.  
  4289. An example of a properly formatted attribute description buffer is shown below: 
  4290.  
  4291.       attrDesc.0 = 1
  4292.       attrDesc.1.Selector = 'VIMSEL_NAME'
  4293.       attrDesc.1.Buffer   = 'Name'
  4294.  
  4295. The fifth parameter is a variable that contains the number of address books to 
  4296. read for the call.  Upon return, the variable contains the number of address 
  4297. books actually read.  This entry MUST be a variable name, since the function 
  4298. returns the number of address books actually read. 
  4299.  
  4300. The sixth parameter is the name of a variable to return a Boolean value 
  4301. indicating if additional address books exist in this session.  This value can 
  4302. be used to indicate that another call to RxVIMEnumerateAddressBooks is 
  4303. necessary to process remaining address books. 
  4304.  
  4305. Pos     = ''
  4306. Skipcnt = 1
  4307. Mcount  = 1
  4308. attrDesc.0 = 1
  4309. attrDesc.1.Selector = 'VIMSEL_NAME'
  4310. attrDesc.1.Buffer   = 'Name'
  4311. more    = ''
  4312.  
  4313.  
  4314. call RxVIMEnumerateAddressBooks Session,'Pos',Skipcnt,'attrDesc','MCount','more'
  4315.  
  4316. or
  4317.  
  4318. rc = RxVIMEnumerateAddressBooks( Session,'Pos',Skipcnt,'attrDesc','MCount','more' )
  4319.  
  4320. Listed below are the valid selectors to use to retrieve specific information 
  4321. from the call: 
  4322.  
  4323. VIMSEL_NAME                     Return the name of the address book
  4324.  
  4325. VIMSEL_TYPE                     Return the type of the address book
  4326.  
  4327.                                    Return values will be:
  4328.  
  4329.                                    VIMSEL_CCMAIL
  4330.                                    VIMSEL_MHS
  4331.                                    VIMSEL_MSGMGR
  4332.                                    VIMSEL_NOTES
  4333.                                    VIMSEL_OCE
  4334.                                    VIMSEL_X500
  4335.  
  4336. VIMSEL_DISPLAY_NAME             Return the name used to display the
  4337.                                 address book (same as VIMSEL_NAME
  4338.                                 for cc:Mail)
  4339.  
  4340. VIMSEL_ENTRY_NUMBER             Return the number for this entry
  4341.  
  4342. VIMSEL_TOTAL_ENTRIES            Return the total number of address books
  4343.  
  4344. The function will return the requested attribute values in the specified buffer 
  4345. as stem values with the following 
  4346.  
  4347. format: 
  4348.  
  4349.          'Name' specified to receive recipient name
  4350.          5 messages are retrieved
  4351.  
  4352.          Name.0 = 5
  4353.          Name.1 = 'Name of the first  address book'
  4354.          Name.2 = 'Name of the second address book'
  4355.          Name.3 = 'Name of the third address book'
  4356.          Name.4 = 'Name of the fourth address book'
  4357.          Name.5 = 'Name of the fifth address book'
  4358.  
  4359.  
  4360. ΓòÉΓòÉΓòÉ 10.1.2. Return Codes ΓòÉΓòÉΓòÉ
  4361.  
  4362. The RxVIMEnumerateAddressBooks function returns the following values: 
  4363.  
  4364.         0 - Successful return
  4365.  
  4366. The return values from all of the function calls return a zero for success, and 
  4367. non-zero for failure.  To retrieve the actual failure reason, use the 
  4368. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4369. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4370. be returned by RxVIMEnumerateAddressBooks: 
  4371.  
  4372.         VIMSTS_SUCCESS                  Successful return
  4373.         VIMSTS_FAILURE                  Function Failed
  4374.  
  4375.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  4376.         VIMSTS_BUF_TOO_SMALL            Return buffer is too small
  4377.         VIMSTS_INVALID_OBJECT           The session handle is bad
  4378.         VIMSTS_INVALID_SELECTOR         One of the request selectors is  bad
  4379.  
  4380.  
  4381. ΓòÉΓòÉΓòÉ 10.1.3. Example ΓòÉΓòÉΓòÉ
  4382.  
  4383. /* Example of using RxVIMEnumerateAddressBooks */
  4384.  
  4385. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4386. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4387. call RxVIMLoadFuncs
  4388.  
  4389.  
  4390. /* This will establish a connection to the VIM system */
  4391. rc = RxVIMInitialize()
  4392.  
  4393. /* Obtain the default session information */
  4394. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4395.  
  4396. Say 'Default path:' db_path
  4397. Say 'Default name:' user_name
  4398.  
  4399. /* Opening a session with the mail subsystem */
  4400. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4401.  
  4402.  
  4403. /* Retrieve the name of the first address book */
  4404. Pos = ''                                  /* Start at beginning */
  4405. skipcnt = 1                               /* Start at beginning */
  4406. mcount  = 1                               /* Return one entry   */
  4407. more = ''                                 /* more entries?      */
  4408.  
  4409. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  4410. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  4411. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  4412.  
  4413. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  4414.  
  4415. Say 'The name of the first address book is' name.1
  4416.  
  4417.  
  4418. /* Close the session with the mail subsystem */
  4419. rc = RxVIMCloseSession( Sess )
  4420.  
  4421. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4422. call RxVIMDropFuncs
  4423.  
  4424.  
  4425. ΓòÉΓòÉΓòÉ 10.2. RxVIMOpenAddressBook ΓòÉΓòÉΓòÉ
  4426.  
  4427. The RxVIMOpenAddressBook function opens the specified address book.  Once 
  4428. opened, entries from the address book can be accessed. 
  4429.  
  4430.  
  4431. ΓòÉΓòÉΓòÉ 10.2.1. Syntax ΓòÉΓòÉΓòÉ
  4432.  
  4433. RxVIMOpenAddressBook is called with three parameters.  The first parameter is 
  4434. the variable containing the pointer to the current session.  The second 
  4435. parameter is the name of the address book to open, which can be retrieved with 
  4436. a call to RxVIMEnumerateAddressBooks. The third is a variable which will 
  4437. contain a pointer to the address book after it has been opened. 
  4438.  
  4439. call RxVIMOpenAddressBook Session, 'Address Book", 'AddrBkPtr'
  4440.  
  4441. or
  4442.  
  4443. rc = RxVIMOpenAddressBook( Session, 'Address Book', 'AddrBkPtr' )
  4444.  
  4445.  
  4446. ΓòÉΓòÉΓòÉ 10.2.2. Return Codes ΓòÉΓòÉΓòÉ
  4447.  
  4448. The RxVIMOpenAddressBook function returns the following values: 
  4449.  
  4450.         0 - Successful return
  4451.  
  4452. The return values from all of the function calls return a zero for success, and 
  4453. non-zero for failure.  To retrieve the actual failure reason, use the 
  4454. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4455. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4456. be returned by RxVIMOpenAddressBook: 
  4457.  
  4458.         VIMSTS_SUCCESS                  Successful return
  4459.         VIMSTS_FAILURE                  Function Failed
  4460.  
  4461.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  4462.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  4463.         VIMSTS_INVALID_OBJECT           The session handle is bad
  4464.         VIMSTS_NAME_NOT_FOUND           The address book could not be located
  4465.  
  4466.  
  4467. ΓòÉΓòÉΓòÉ 10.2.3. Example ΓòÉΓòÉΓòÉ
  4468.  
  4469. /* Example of using RxVIMOpenAddressBook */
  4470.  
  4471. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4472. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4473. call RxVIMLoadFuncs
  4474.  
  4475.  
  4476. /* This will establish a connection to the VIM system */
  4477. rc = RxVIMInitialize()
  4478.  
  4479. /* Obtain the default session information */
  4480. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4481.  
  4482. Say 'Default path:' db_path
  4483. Say 'Default name:' user_name
  4484.  
  4485. /* Opening a session with the mail subsystem */
  4486. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4487.  
  4488. /* Retrieve the name of the first address book */
  4489. Pos = ''                                  /* Start at beginning */
  4490. skipcnt = 1                               /* Start at beginning */
  4491. mcount  = 1                               /* Return one entry   */
  4492. more = ''                                 /* more entries?      */
  4493.  
  4494. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  4495. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  4496. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  4497.  
  4498. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  4499.  
  4500.  
  4501.  
  4502. /* Open the first address book found */
  4503. rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')
  4504.  
  4505.  
  4506.  
  4507. /* Close the session with the mail subsystem */
  4508. rc = RxVIMCloseSession( Sess )
  4509.  
  4510. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4511. call RxVIMDropFuncs
  4512.  
  4513.  
  4514. ΓòÉΓòÉΓòÉ 10.3. RxVIMSetCurrentSubtree ΓòÉΓòÉΓòÉ
  4515.  
  4516. The RxVIMSetCurrentSubtree function sets the root of the tree for all future 
  4517. calls to the address book.  For flat address book models, such as cc:Mail and 
  4518. Lotus Notes, this call has no effect.  It is included here for compatibility to 
  4519. the VIM specification. 
  4520.  
  4521.  
  4522. ΓòÉΓòÉΓòÉ 10.3.1. Syntax ΓòÉΓòÉΓòÉ
  4523.  
  4524. RxVIMSetCurrentSubtree is called with three parameters.  The first parameter is 
  4525. the variable containing the pointer to the open address book.  The second 
  4526. parameter is a reference pointer to set the location of the subtree.  The third 
  4527. is the name of the subtree to set the root location. 
  4528.  
  4529. call RxVIMSetCurrentSubtree AddrBkPtr, 'Subtree_Ref', 'Subtree Name'
  4530.  
  4531. or
  4532.  
  4533. rc = RxVIMSetCurrentSubtree( AddrBkPtr, 'Subtree_Ref', 'Subtree Name' )
  4534.  
  4535. Shown below are the valid entries for the subtree reference pointer: 
  4536.  
  4537. VIM_ROOT_REF                  Set subtree to the root of the entry
  4538. VIM_PARENT_REF                Set subtree to the parent of the entry
  4539. NULL ('')                     Set the subtree to the beginning of the entry
  4540.  
  4541.  
  4542. ΓòÉΓòÉΓòÉ 10.3.2. Return Codes ΓòÉΓòÉΓòÉ
  4543.  
  4544. The RxVIMSetCurrentSubtree function returns the following values: 
  4545.  
  4546.         0 - Successful return
  4547.  
  4548. The return values from all of the function calls return a zero for success, and 
  4549. non-zero for failure.  To retrieve the actual failure reason, use the 
  4550. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4551. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4552. be returned by RxVIMSetCurrentSubtree: 
  4553.  
  4554.         VIMSTS_SUCCESS                  Successful return
  4555.         VIMSTS_FAILURE                  Function Failed
  4556.  
  4557.         VIMSTS_BAD_PARAM                Ref/name not a valid entry
  4558.  
  4559.  
  4560. ΓòÉΓòÉΓòÉ 10.3.3. Example ΓòÉΓòÉΓòÉ
  4561.  
  4562. /* Example of using RxVIMSetCurrentSubtree */
  4563.  
  4564. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4565. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4566. call RxVIMLoadFuncs
  4567.  
  4568.  
  4569. /* This will establish a connection to the VIM system */
  4570. rc = RxVIMInitialize()
  4571.  
  4572. /* Obtain the default session information */
  4573. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4574.  
  4575. Say 'Default path:' db_path
  4576. Say 'Default name:' user_name
  4577.  
  4578. /* Opening a session with the mail subsystem */
  4579. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4580.  
  4581. /* Retrieve the name of the first address book */
  4582. Pos = ''                                  /* Start at beginning */
  4583. skipcnt = 1                               /* Start at beginning */
  4584. mcount  = 1                               /* Return one entry   */
  4585. more = ''                                 /* more entries?      */
  4586.  
  4587. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  4588. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  4589. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  4590.  
  4591. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  4592.  
  4593. /* Open the first address book found */
  4594. rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')
  4595.  
  4596.  
  4597. /* NOTE: THIS CALL HAS NO EFFECT WHEN USED WITH CCMAIL OR LOTUS */
  4598. /*       NOTES.  IT IS INCLUDED FOR COMPATIBILITY WITH THE VIM  */
  4599. /*       SPECIFICATION ONLY.                                    */
  4600.  
  4601. /* Set the subtree to the beginning of the address book */
  4602. rc = RxVIMSetCurrentSubtree(AddrBkPtr, '', '')
  4603.  
  4604.  
  4605. /* Close the session with the mail subsystem */
  4606. rc = RxVIMCloseSession( Sess )
  4607.  
  4608. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4609. call RxVIMDropFuncs
  4610.  
  4611.  
  4612. ΓòÉΓòÉΓòÉ 10.4. RxVIMGetCurrentSubtree ΓòÉΓòÉΓòÉ
  4613.  
  4614. The RxVIMGetCurrentSubtree function returns the current subtree in the address 
  4615. book.  For flat address book models, such as cc:Mail and Lotus Notes, this call 
  4616. has no effect.  It is included here for compatibility to the VIM specification. 
  4617.  
  4618.  
  4619. ΓòÉΓòÉΓòÉ 10.4.1. Syntax ΓòÉΓòÉΓòÉ
  4620.  
  4621. RxVIMGetCurrentSubtree is called with three parameters.  The first parameter is 
  4622. the variable containing the pointer to the open address book.  The second 
  4623. parameter is a variable to get the reference pointer of the subtree.  The third 
  4624. is the name of the variable to get the name of the subtree. 
  4625.  
  4626. call RxVIMGetCurrentSubtree AddrBkPtr, 'Subtree_Ref', 'Subtree Name'
  4627.  
  4628. or
  4629.  
  4630. rc = RxVIMGetCurrentSubtree( AddrBkPtr, 'Subtree_Ref', 'Subtree Name' )
  4631.  
  4632.  
  4633. ΓòÉΓòÉΓòÉ 10.4.2. Return Codes ΓòÉΓòÉΓòÉ
  4634.  
  4635. The RxVIMGetCurrentSubtree function returns the following values: 
  4636.  
  4637.         0 - Successful return
  4638.  
  4639. The return values from all of the function calls return a zero for success, and 
  4640. non-zero for failure.  To retrieve the actual failure reason, use the 
  4641. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4642. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4643. be returned by RxVIMGetCurrentSubtree: 
  4644.  
  4645.         VIMSTS_SUCCESS                  Successful return
  4646.         VIMSTS_FAILURE                  Function Failed
  4647.  
  4648.         VIMSTS_BAD_PARAM                Ref/name not a valid entry
  4649.         VIMSTS_BUF_TOO_SMALL            Buffer variable is too small
  4650.  
  4651.  
  4652. ΓòÉΓòÉΓòÉ 10.4.3. Example ΓòÉΓòÉΓòÉ
  4653.  
  4654. /* Example of using RxVIMGetCurrentSubtree */
  4655.  
  4656. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4657. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4658. call RxVIMLoadFuncs
  4659.  
  4660. /* This will establish a connection to the VIM system */
  4661. rc = RxVIMInitialize()
  4662.  
  4663. /* Obtain the default session information */
  4664. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4665.  
  4666. Say 'Default path:' db_path
  4667. Say 'Default name:' user_name
  4668.  
  4669. /* Opening a session with the mail subsystem */
  4670. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4671.  
  4672. /* Retrieve the name of the first address book */
  4673. Pos = ''                                  /* Start at beginning */
  4674. skipcnt = 1                               /* Start at beginning */
  4675. mcount  = 1                               /* Return one entry   */
  4676. more = ''                                 /* more entries?      */
  4677.  
  4678. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  4679. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  4680. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  4681.  
  4682. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  4683.  
  4684. /* Open the first address book found */
  4685. rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')
  4686.  
  4687. /* NOTE: THIS CALL HAS NO EFFECT WHEN USED WITH CCMAIL OR LOTUS */
  4688. /*       NOTES.  IT IS INCLUDED FOR COMPATIBILITY WITH THE VIM  */
  4689. /*       SPECIFICATION ONLY.                                    */
  4690.  
  4691. /* Set the subtree to the beginning of the address book */
  4692. rc = RxVIMGetCurrentSubtree(AddrBkPtr, 'SubRef', 'SubName')
  4693.  
  4694. Say 'Subtree name is' SubName
  4695.  
  4696. /* Close the session with the mail subsystem */
  4697. rc = RxVIMCloseSession( Sess )
  4698.  
  4699. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4700. call RxVIMDropFuncs
  4701.  
  4702.  
  4703. ΓòÉΓòÉΓòÉ 10.5. RxVIMEnumerateAddressBookEntries ΓòÉΓòÉΓòÉ
  4704.  
  4705. The RxVIMEnumerateAddressBookEntries function retrieves one or more attributes 
  4706. about the entries in the current address book. 
  4707.  
  4708.  
  4709. ΓòÉΓòÉΓòÉ 10.5.1. Syntax ΓòÉΓòÉΓòÉ
  4710.  
  4711. RxVIMEnumerateAddressBookEntries is called with eight parameters.  The first 
  4712. parameter is a variable that contains the pointer to the current address book. 
  4713.  
  4714. The second is a variable containing the starting position within the address 
  4715. book entries.  To start at the beginning, the value of the variable should be 
  4716. set to null ('').  For subsequent calls, this value will contain the return 
  4717. value from the previous call.  This entry MUST be a variable name, since the 
  4718. function returns the value of the next starting position. 
  4719.  
  4720. The third parameter is the number of entries to skip before or after the 
  4721. starting position.  To start at the beginning and move forward, this should be 
  4722. set to a value of 1.  To start at the end, and move in reverse, this should be 
  4723. set to a value of -1. 
  4724.  
  4725. The fourth parameter is a stem variable name that contains the number of 
  4726. attributes to retrieve at the root, and a Selector and Buffer entry for each 
  4727. attribute.  The Selector entry contains the selector to retrieve, and the 
  4728. Buffer entry contains the name of the variable to return the values. 
  4729.  
  4730. An example of a properly formatted attribute description buffer is shown below: 
  4731.  
  4732.       attrDesc.0 = 2
  4733.       attrDesc.1.Selector = 'VIMSEL_NAME'
  4734.       attrDesc.1.Buffer   = 'Name'
  4735.       attrDesc.2.Selector = 'VIMSEL_REF'
  4736.       attrDesc.2.Buffer   = 'RefNo'
  4737.  
  4738. The fifth parameter is a variable that contains the number of address book 
  4739. entries to read for the call.  Upon return, the variable contains the number of 
  4740. address book entries actually read.  This entry MUST be a variable name, since 
  4741. the function returns the number of address book entries actually read. 
  4742.  
  4743. The sixth parameter is a selector indicating the type of filtering to be done 
  4744. on the messages prior to being included in the return information.  Filtering 
  4745. can allow messages to be filtered based on subject, category, type of message, 
  4746. or other values.  To return all messages in the container without filtering, 
  4747. specify 'VIMSEL_NO_FILTER'. 
  4748.  
  4749. The seventh parameter is the value to be used for filtering, if specified.  If 
  4750. no filtering is indicated, this parameter should be null (''). 
  4751.  
  4752. The eighth parameter is the name of a variable to return a Boolean value 
  4753. indicating if additional address books exist in this session.  This value can 
  4754. be used to indicate that another call to RxVIMEnumerateAddressBookEntries is 
  4755. necessary to process remaining address books. 
  4756.  
  4757. Pos     = ''
  4758. Skipcnt = 1
  4759. Mcount  = 1
  4760. filter  = 'VIMSEL_NO_FILTER'
  4761. fdata   = ''
  4762. attrDesc.0 = 1
  4763. attrDesc.1.Selector = 'VIMSEL_NAME'
  4764. attrDesc.1.Buffer   = 'Name'
  4765. more    = ''
  4766.  
  4767.  
  4768. call RxVIMEnumerateAddressBookEntries AddrBkPtr,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,'more'
  4769.  
  4770. or
  4771.  
  4772. rc = RxVIMEnumerateAddressBookEntries( AddrBkPtr,'Pos',Skipcnt,'attrDesc','MCount',filter,fdata,'more' )
  4773.  
  4774. Listed below are the valid selectors to use to request specific attributes to 
  4775. be returned for each entry: 
  4776.  
  4777. VIMSEL_REF                      Retrieves the entry reference value
  4778.  
  4779. VIMSEL_TYPE                     Retrieves the message type
  4780.  
  4781.                                    VIMSEL_ENTITY   -  Individual entry
  4782.                                    VIMSEL_GROUP    -  collection of                                                            entries
  4783.                                    VIMSEL_SUBTREE  -  subtree entry
  4784.  
  4785.  
  4786. VIMSEL_NAME                     Retrieves the full name of the entry
  4787.  
  4788. VIMSEL_ADDRESS                  Retrieves the address of the entry
  4789.  
  4790. VIMSEL_COMMENTS                 Retrieves the comments for this entry
  4791.  
  4792. VIMSEL_ENTRY_NUMBER             Retrieves the entry number for the entry
  4793.  
  4794. VIMSEL_TOTAL_ENTRIES            Retrieves the total entries in the                                       address book
  4795.  
  4796. VIMSEL_FAN                      Returns foreign alias name, which is                                     used in gateway applications
  4797.  
  4798. Listed below are the valid selectors to use to request filtering for each entry 
  4799. (parameter six ): 
  4800.  
  4801. VIMSEL_NO_FILTER                Return all entries
  4802.  
  4803. VIMSEL_ENTITY                   Return only individual entries
  4804.  
  4805. VIMSEL_GROUP                    Return only group entries (lists)
  4806.  
  4807. The function will return the requested attribute values in the specified buffer 
  4808. as stem values with the following 
  4809.  
  4810. format: 
  4811.  
  4812.          'Name' specified to receive address book entry name
  4813.          5 entries are retrieved
  4814.  
  4815.          Name.0 = 5
  4816.          Name.1 = 'Name of the first  address book entry'
  4817.          Name.2 = 'Name of the second address book entry'
  4818.          Name.3 = 'Name of the third address book entry'
  4819.          Name.4 = 'Name of the fourth address book entry'
  4820.          Name.5 = 'Name of the fifth address book entry'
  4821.  
  4822.  
  4823. ΓòÉΓòÉΓòÉ 10.5.2. Return Codes ΓòÉΓòÉΓòÉ
  4824.  
  4825. The RxVIMEnumerateAddressBookEntries function returns the following values: 
  4826.  
  4827.         0 - Successful return
  4828.  
  4829. The return values from all of the function calls return a zero for success, and 
  4830. non-zero for failure.  To retrieve the actual failure reason, use the 
  4831. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4832. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4833. be returned by RxVIMEnumerateAddressBookEntries: 
  4834.  
  4835.         VIMSTS_SUCCESS                  Successful return
  4836.         VIMSTS_FAILURE                  Function Failed
  4837.  
  4838.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  4839.         VIMSTS_BUF_TOO_SMALL            Return buffer is too small
  4840.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  4841.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  4842.         VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
  4843.  
  4844.  
  4845. ΓòÉΓòÉΓòÉ 10.5.3. Example ΓòÉΓòÉΓòÉ
  4846.  
  4847. /* Example of using RxVIMEnumerateAddressBookEntries */
  4848.  
  4849. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  4850. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  4851. call RxVIMLoadFuncs
  4852.  
  4853.  
  4854. /* This will establish a connection to the VIM system */
  4855. rc = RxVIMInitialize()
  4856.  
  4857. /* Obtain the default session information */
  4858. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  4859.  
  4860. Say 'Default path:' db_path
  4861. Say 'Default name:' user_name
  4862.  
  4863. /* Opening a session with the mail subsystem */
  4864. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  4865.  
  4866.  
  4867. /* Retrieve the name of the first address book */
  4868. Pos = ''                                  /* Start at beginning */
  4869. skipcnt = 1                               /* Start at beginning */
  4870. mcount  = 1                               /* Return one entry   */
  4871. more = ''                                 /* more entries?      */
  4872.  
  4873. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  4874. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  4875. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  4876.  
  4877. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  4878.  
  4879. /* Open the first addressbook */
  4880. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  4881.  
  4882.  
  4883.  
  4884. /* Retrieve the name of the first address book entry */
  4885. Pos = ''                                  /* Start at beginning */
  4886. skipcnt = 1                               /* Start at beginning */
  4887. mcount  = 1                               /* Return one entry   */
  4888. more = ''                                 /* more entries?      */
  4889. filter = 'VIMSEL_NO_FILTER'
  4890. fdata  = ''
  4891.  
  4892. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  4893. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  4894. attrDesc.1.Buffer   = 'Ename'             /* buffer to return name    */
  4895.  
  4896. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')
  4897.  
  4898. Say 'The full name of the first entry is' Ename.1
  4899.  
  4900.  
  4901. /* Close the session with the mail subsystem */
  4902. rc = RxVIMCloseSession( Sess )
  4903.  
  4904. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  4905. call RxVIMDropFuncs
  4906.  
  4907.  
  4908. ΓòÉΓòÉΓòÉ 10.6. RxVIMCreateAddressBookEntry ΓòÉΓòÉΓòÉ
  4909.  
  4910. The RxVIMCreateAddressBookEntry function adds a new entry to the current 
  4911. address book.  To add entries to the primary address book, the session must be 
  4912. connected with the postoffice name and password.  Standard users can only 
  4913. create entries in their private mailing lists. 
  4914.  
  4915. IMPORTANT NOTE:  If this function is called attempting to add an entry to the 
  4916. primary address book of a postoffice that is at the maximum number of local 
  4917. users, the function will generate an exception in OS/2.  This function should 
  4918. only be used with postoffices that have available users. 
  4919.  
  4920.  
  4921. ΓòÉΓòÉΓòÉ 10.6.1. Syntax ΓòÉΓòÉΓòÉ
  4922.  
  4923. RxVIMCreateAddressBookEntry is called with three parameters.  The first 
  4924. parameter is a variable that contains the pointer to the current address book. 
  4925.  
  4926. The second is a selector value of the type of entry to create.  For individual 
  4927. entries this will be VIMSEL_ENTITY, and for group entries (lists) this will be 
  4928. VIMSEL_GROUP. 
  4929.  
  4930. The third parameter is a stem variable name that contains the number of 
  4931. attributes to use for creation at the root, and a Selector and Value entry for 
  4932. each attribute.  The Selector entry contains the selector to use in the create, 
  4933. and the Value entry contains the information to use in the create. 
  4934.  
  4935. An example of a properly formatted attribute description buffer is shown below: 
  4936.  
  4937.       attrDesc.0 = 2
  4938.       attrDesc.1.Selector = 'VIMSEL_NAME'
  4939.       attrDesc.1.Value    = 'Mark Stevens'
  4940.       attrDesc.2.Selector = 'VIMSEL_COMMENTS'
  4941.       attrDesc.2.Value    = 'This entry created with RexxVIM'
  4942.  
  4943.  
  4944. attrDesc.0 = 1
  4945. attrDesc.1.Selector = 'VIMSEL_NAME'
  4946. attrDesc.1.Buffer   = 'Mark Stevens'
  4947.  
  4948.  
  4949. call RxVIMCreateAddressBookEntry AddrBkPtr,'VIMSEL_ENTITY','attrDesc'
  4950.  
  4951. or
  4952.  
  4953. rc = RxVIMCreateAddressBookEntry( AddrBkPtr,'VIMSEL_ENTITY','attrDesc' )
  4954.  
  4955. Listed below are the valid selectors to use to indicate specific attributes to 
  4956. be set for the entry: 
  4957.  
  4958. VIMSEL_NAME                     Provide the full name of the entry
  4959.  
  4960. VIMSEL_ADDRESS                  Provide the full address of the entry
  4961.  
  4962. VIMSEL_COMMENTS                 Provide free form comments for this entry
  4963.  
  4964. VIMSEL_PASSWORD                 Provide the password for the entry
  4965.  
  4966. VIMSEL_LOCATION                 Set the location using one of these selectors
  4967.  
  4968.  
  4969.                VIMSEL_LOCAL   - Add to the local postoffice (default)
  4970.  
  4971.                VIMSEL_DIALIN  - Will access the local postoffice
  4972.                                 using dialin only
  4973.  
  4974.                VIMSEL_REMOTE  - User local on another postoffice
  4975.  
  4976.                VIMSEL_ALIAS   - Entry is an alias for another local entry
  4977.  
  4978.     VIMSEL_DIRECT_POSTOFFICE  - Entry is a postoffice that will directly connect
  4979.  
  4980.     VIMSEL_INDIRECT_POSTOFFICE- Entry is a postoffice that will not direct connect
  4981.  
  4982.  
  4983. ΓòÉΓòÉΓòÉ 10.6.2. Return Codes ΓòÉΓòÉΓòÉ
  4984.  
  4985. The RxVIMCreateAddressBookEntry function returns the following values: 
  4986.  
  4987.         0 - Successful return
  4988.  
  4989. The return values from all of the function calls return a zero for success, and 
  4990. non-zero for failure.  To retrieve the actual failure reason, use the 
  4991. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  4992. value to the actual failure text.  Using RxVIMStatus, the following values may 
  4993. be returned by RxVIMCreateAddressBookEntry: 
  4994.  
  4995.         VIMSTS_SUCCESS                  Successful return
  4996.         VIMSTS_FAILURE                  Function Failed
  4997.  
  4998.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  4999.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  5000.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5001.         VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
  5002.         VIMSTS_NAME_EXISTS              Name already exists in addressbook
  5003.         VIMSTS_UNSUP_TYPE               Entry type is not valid
  5004.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  5005.         VIMSTS_NOT_SUPPORTED            Attribute not supported
  5006.  
  5007.  
  5008. ΓòÉΓòÉΓòÉ 10.6.3. Example ΓòÉΓòÉΓòÉ
  5009.  
  5010. /* Example of using RxVIMCreateAddressBookEntry */
  5011.  
  5012. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5013. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5014. call RxVIMLoadFuncs
  5015.  
  5016.  
  5017. /* This will establish a connection to the VIM system */
  5018. rc = RxVIMInitialize()
  5019.  
  5020. /* Obtain the default session information */
  5021. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5022.  
  5023. Say 'Default path:' db_path
  5024. Say 'Default name:' user_name
  5025.  
  5026. /* Opening a session with the mail subsystem */
  5027. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5028.  
  5029.  
  5030. /* Retrieve the name of the first address book */
  5031. Pos = ''                                  /* Start at beginning */
  5032. skipcnt = 1                               /* Start at beginning */
  5033. mcount  = 1                               /* Return one entry   */
  5034. more = ''                                 /* more entries?      */
  5035.  
  5036. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5037. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5038. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5039.  
  5040. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5041.  
  5042. /* Open the first addressbook */
  5043. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5044.  
  5045.  
  5046. /* Add a new name to the first address book entry */
  5047. attrDesc.0 = 1                            /* create with 1 attribute  */
  5048. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of entry to add     */
  5049. attrDesc.1.Value    = 'Mark Stevens'      /* value to use for add     */
  5050.  
  5051. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'VIMSEL_ENTITY',attrDesc')
  5052.  
  5053. Say attrDesc.1.Value 'has been added to the addressbook'
  5054.  
  5055.  
  5056. /* Close the session with the mail subsystem */
  5057. rc = RxVIMCloseSession( Sess )
  5058.  
  5059. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5060. call RxVIMDropFuncs
  5061.  
  5062.  
  5063. ΓòÉΓòÉΓòÉ 10.7. RxVIMMatchAddressBook ΓòÉΓòÉΓòÉ
  5064.  
  5065. The RxVIMMatchAddressBook function searches the specified address book for an 
  5066. entry that matches the specified attributes. 
  5067.  
  5068.  
  5069. ΓòÉΓòÉΓòÉ 10.7.1. Syntax ΓòÉΓòÉΓòÉ
  5070.  
  5071. RxVIMMatchAddressBook is called with six parameters.  The first parameter is a 
  5072. variable that contains the pointer to the current address book.  The second is 
  5073. a selector value to indicate what attribute on which to match.  The third 
  5074. parameter is the information with which to perform the match.  The fourth 
  5075. parameter a selector value to indicate the type of matching to use.  The fifth 
  5076. parameter is a variable that contains the position to start the match.  To 
  5077. begin the search at the beginning, the variable should be set to null (''). 
  5078. The sixth parameter is a variable that will receive the enumeration number of 
  5079. the entry being returned. 
  5080.  
  5081. Pos   = ''
  5082. Enum  = ''
  5083. Attr  = 'VIMSEL_NAME'
  5084. type  = 'VIMSEL_FULL'
  5085. srch  = 'Mark Stevens'
  5086.  
  5087. call RxVIMMatchAddressBook AddrBkPtr,Attr,srch,type,'Pos','Enum'
  5088.  
  5089. or
  5090.  
  5091. rc = RxVIMMatchAddressBook( AddrBkPtr,Attr,srch,type,'Pos','Enum' )
  5092.  
  5093. Listed below are the valid selectors to use to indicate on what element the 
  5094. match will occur: 
  5095.  
  5096. VIMSEL_NAME                     Performs the match on the entry name
  5097.  
  5098. VIMSEL_FAN                      Performs the match on the foreign alias
  5099.                                 name, which is used in gateway applications
  5100.  
  5101. Listed below are the valid selectors to use to indicate type of matching 
  5102. (parameter four ): 
  5103.  
  5104. VIMSEL_FULL                     Return only entries that fully match
  5105.  
  5106. VIMSEL_PARTIAL                  Return entries that match the partial string
  5107.  
  5108.  
  5109. ΓòÉΓòÉΓòÉ 10.7.2. Return Codes ΓòÉΓòÉΓòÉ
  5110.  
  5111. The RxVIMMatchAddressBook function returns the following values: 
  5112.  
  5113.         0 - Successful return
  5114.  
  5115. The return values from all of the function calls return a zero for success, and 
  5116. non-zero for failure.  To retrieve the actual failure reason, use the 
  5117. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5118. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5119. be returned by RxVIMMatchAddressBook: 
  5120.  
  5121.         VIMSTS_SUCCESS                  Successful return
  5122.         VIMSTS_FAILURE                  Function Failed
  5123.  
  5124.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  5125.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  5126.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5127.         VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
  5128.         VIMSTS_NO_MATCH                 No entries match the search
  5129.  
  5130.  
  5131. ΓòÉΓòÉΓòÉ 10.7.3. Example ΓòÉΓòÉΓòÉ
  5132.  
  5133. /* Example of using RxVIMMatchAddressBook */
  5134.  
  5135. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5136. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5137. call RxVIMLoadFuncs
  5138.  
  5139. /* This will establish a connection to the VIM system */
  5140. rc = RxVIMInitialize()
  5141.  
  5142. /* Obtain the default session information */
  5143. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5144.  
  5145. Say 'Default path:' db_path
  5146. Say 'Default name:' user_name
  5147.  
  5148. /* Opening a session with the mail subsystem */
  5149. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5150.  
  5151. /* Retrieve the name of the first address book */
  5152. Pos = ''                                  /* Start at beginning */
  5153. skipcnt = 1                               /* Start at beginning */
  5154. mcount  = 1                               /* Return one entry   */
  5155. more = ''                                 /* more entries?      */
  5156. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5157. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5158. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5159.  
  5160. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5161.  
  5162. /* Open the first addressbook */
  5163. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5164.  
  5165. /* Search for a name in the address book */
  5166. Pos   = ''
  5167. Enum  = ''
  5168. Attr  = 'VIMSEL_NAME'
  5169. type  = 'VIMSEL_FULL'
  5170. srch  = 'Mark Stevens'
  5171.  
  5172. rc = RxVIMMatchAddressBook( AddrBkPtr,Attr,srch,type,'Pos','Enum' )
  5173.  
  5174. if rc>0 then
  5175.   Say srch 'not found in addressbook'
  5176. else
  5177.   Say srch 'was found in addressbook at location' enum
  5178.  
  5179.  
  5180. /* Close the session with the mail subsystem */
  5181. rc = RxVIMCloseSession( Sess )
  5182.  
  5183. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5184. call RxVIMDropFuncs
  5185.  
  5186.  
  5187. ΓòÉΓòÉΓòÉ 10.8. RxVIMGetABEntryAttributes ΓòÉΓòÉΓòÉ
  5188.  
  5189. The RxVIMGetABEntryAttributes function retrieves one or more attributes about 
  5190. the specified address book entry. 
  5191.  
  5192.  
  5193. ΓòÉΓòÉΓòÉ 10.8.1. Syntax ΓòÉΓòÉΓòÉ
  5194.  
  5195. RxVIMGetABEntryAttributes is called with four parameters.  The first parameter 
  5196. is a variable that contains the pointer to the current address book. 
  5197.  
  5198. The second is a variable containing the reference number for the entry to 
  5199. obtain attribute information.  If this value is set to null (''), the third 
  5200. parameter is used to locate the entry. 
  5201.  
  5202. The third parameter is the name of the entry to obtain attribute information. 
  5203. This paramter is used if the Entry Reference number (parameter two) is null. 
  5204.  
  5205. The fourth parameter is a stem variable name that contains the number of 
  5206. attributes to retrieve at the root, and a Selector and Buffer entry for each 
  5207. attribute.  The Selector entry contains the selector to retrieve, and the 
  5208. Buffer entry contains the name of the variable to return the values. 
  5209.  
  5210. An example of a properly formatted attribute description buffer is shown below: 
  5211.  
  5212. attrDesc.0 = 2
  5213. attrDesc.1.Selector = 'VIMSEL_NAME'
  5214. attrDesc.1.Buffer   = 'Name'
  5215. attrDesc.2.Selector = 'VIMSEL_COMMENTS'
  5216. attrDesc.2.Buffer   = 'Comments'
  5217.  
  5218.  
  5219.  
  5220. The function would be called with the following syntax: 
  5221.  
  5222.  
  5223. attrDesc.0 = 1
  5224. attrDesc.1.Selector = 'VIMSEL_NAME'
  5225. attrDesc.1.Buffer   = 'Name'
  5226.  
  5227.  
  5228. call RxVIMGetABEntryAttributes AddrBkPtr,EntryRef,'','attrDesc'
  5229.  
  5230. or
  5231.  
  5232. rc = RxVIMGetABEntryAttributes( AddrBkPtr,EntryRef,'','attrDesc' )
  5233.  
  5234. Listed below are the valid selectors to use to request specific attributes to 
  5235. be returned for each entry: 
  5236.  
  5237. VIMSEL_NAME                     Retrieves the full name of the entry
  5238.  
  5239. VIMSEL_ADDRESS                  Retrieves the address of the entry
  5240.  
  5241. VIMSEL_COMMENTS                 Retrieves the comments for this entry
  5242.  
  5243. VIMSEL_TYPE                     Retrieves the message type
  5244.  
  5245.              VIMSEL_ENTITY   -  Individual entry
  5246.              VIMSEL_GROUP    -  collection of entries
  5247.              VIMSEL_SUBTREE  -  subtree entry
  5248.  
  5249.  
  5250. VIMSEL_LOCATION                 Retrieves location using one of these                                    selectors
  5251.  
  5252.                VIMSEL_LOCAL   - Add to the local postoffice (default)
  5253.                VIMSEL_DIALIN  - Will access the local postoffice
  5254.                                 using dialin only
  5255.                VIMSEL_REMOTE  - User local on another postoffice
  5256.                VIMSEL_ALIAS   - Entry is an alias for another
  5257.                                 local entry
  5258.     VIMSEL_DIRECT_POSTOFFICE  - Entry is a postoffice that
  5259.                                 will directly connect
  5260.     VIMSEL_INDIRECT_POSTOFFICE- Entry is a postoffice that
  5261.                                 will not direct connect
  5262.  
  5263. VIMSEL_FAN                      Returns foreign alias name, which is                                     used in gateway applications
  5264.  
  5265. The function will return the requested attribute values in the specified buffer 
  5266. variable directly with the following 
  5267.  
  5268. format: 
  5269.  
  5270.          'Name' specified to receive address book entry name
  5271.  
  5272.          Name  = 'Name of the address book entry'
  5273.  
  5274.  
  5275. ΓòÉΓòÉΓòÉ 10.8.2. Return Codes ΓòÉΓòÉΓòÉ
  5276.  
  5277. The RxVIMGetABEntryAttributes function returns the following values: 
  5278.  
  5279.         0 - Successful return
  5280.  
  5281. The return values from all of the function calls return a zero for success, and 
  5282. non-zero for failure.  To retrieve the actual failure reason, use the 
  5283. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5284. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5285. be returned by RxVIMGetABEntryAttributes: 
  5286.  
  5287.         VIMSTS_SUCCESS                  Successful return
  5288.         VIMSTS_FAILURE                  Function Failed
  5289.  
  5290.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  5291.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5292.         VIMSTS_INVALID_SELECTOR         One of the request selectors is bad
  5293.         VIMSTS_NOT_SUPPORTED            Attribute not supported
  5294.  
  5295.  
  5296. ΓòÉΓòÉΓòÉ 10.8.3. Example ΓòÉΓòÉΓòÉ
  5297.  
  5298. /* Example of using RxVIMGetABEntryAttributes */
  5299.  
  5300. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5301. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5302. call RxVIMLoadFuncs
  5303.  
  5304. /* This will establish a connection to the VIM system */
  5305. rc = RxVIMInitialize()
  5306.  
  5307. /* Obtain the default session information */
  5308. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5309.  
  5310. Say 'Default path:' db_path
  5311. Say 'Default name:' user_name
  5312.  
  5313. /* Opening a session with the mail subsystem */
  5314. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5315.  
  5316. /* Retrieve the name of the first address book */
  5317. Pos = ''                                  /* Start at beginning */
  5318. skipcnt = 1                               /* Start at beginning */
  5319. mcount  = 1                               /* Return one entry   */
  5320. more = ''                                 /* more entries?      */
  5321. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5322. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5323. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5324.  
  5325. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5326.  
  5327. /* Open the first addressbook */
  5328. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5329.  
  5330. /* Retrieve the name of the first address book entry */
  5331. Pos = ''                                  /* Start at beginning */
  5332. skipcnt = 1                               /* Start at beginning */
  5333. mcount  = 1                               /* Return one entry   */
  5334. more = ''                                 /* more entries?      */
  5335. filter = 'VIMSEL_NO_FILTER'
  5336. fdata  = ''
  5337.  
  5338. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5339. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
  5340. attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */
  5341.  
  5342. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')
  5343.  
  5344.  
  5345. /* Get the comment for the first address book entry */
  5346. ItemBuf.0 = 1
  5347. ItemBuf.1.Selector = 'VIMSEL_COMMENTS'
  5348. ItemBuf.1.Buffer   = 'comments'
  5349.  
  5350. rc = RxVIMGetABEntryAttributes(AddrBkPtr,RefNo.1,'','ItemBuf')
  5351.  
  5352. Say 'The comment for the first entry is' comments
  5353.  
  5354.  
  5355.  
  5356. /* Close the session with the mail subsystem */
  5357. rc = RxVIMCloseSession( Sess )
  5358.  
  5359. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5360. call RxVIMDropFuncs
  5361.  
  5362.  
  5363. ΓòÉΓòÉΓòÉ 10.9. RxVIMSetABEntryAttributes ΓòÉΓòÉΓòÉ
  5364.  
  5365. The RxVIMSetABEntryAttributes function changes one or more attributes of the 
  5366. specified address book entry. 
  5367.  
  5368.  
  5369. ΓòÉΓòÉΓòÉ 10.9.1. Syntax ΓòÉΓòÉΓòÉ
  5370.  
  5371. RxVIMSetABEntryAttributes is called with four parameters.  The first parameter 
  5372. is a variable that contains the pointer to the current address book. 
  5373.  
  5374. The second is a variable containing the reference number for the entry to 
  5375. obtain attribute information.  If this value is set to null (''), the third 
  5376. parameter is used to locate the entry. 
  5377.  
  5378. The third parameter is the name of the entry to obtain attribute information. 
  5379. This parameter is used if the Entry Reference number (parameter two) is null. 
  5380.  
  5381. The fourth parameter is a stem variable name that contains the number of 
  5382. attributes to change at the root, and a Selector and Value entry for each 
  5383. attribute.  The Selector entry contains the selector to retrieve, and the Value 
  5384. entry contains the information to use for the change. 
  5385.  
  5386. An example of a properly formatted attribute description buffer is shown below: 
  5387.  
  5388. attrDesc.0 = 2
  5389. attrDesc.1.Selector = 'VIMSEL_NAME'
  5390. attrDesc.1.Value    = 'Mark Stevens'
  5391. attrDesc.2.Selector = 'VIMSEL_COMMENTS'
  5392. attrDesc.2.Value    = 'This entry was changed using RexxVIM'
  5393.  
  5394.  
  5395. The function would be called with the following syntax: 
  5396.  
  5397.  
  5398. attrDesc.0 = 1
  5399. attrDesc.1.Selector = 'VIMSEL_NAME'
  5400. attrDesc.1.Value    = 'Mark Stevens'
  5401.  
  5402.  
  5403. call RxVIMSetABEntryAttributes AddrBkPtr,EntryRef,'','attrDesc'
  5404.  
  5405. or
  5406.  
  5407. rc = RxVIMSetABEntryAttributes( AddrBkPtr,EntryRef,'','attrDesc' )
  5408.  
  5409.  
  5410. Listed below are the valid selectors to use to request specific attributes to 
  5411. be changed for the entry: 
  5412.  
  5413. VIMSEL_NAME                     Changes the full name of the entry
  5414.  
  5415. VIMSEL_ADDRESS                  Changes the address of the entry
  5416.  
  5417. VIMSEL_COMMENTS                 Changes the comments for this entry
  5418.  
  5419. VIMSEL_COMMENTS                 Changes the password for this entry
  5420.  
  5421. VIMSEL_LOCATION                 Changes location using one of these selectors
  5422.  
  5423.                VIMSEL_LOCAL   - Add to the local postoffice (default)
  5424.  
  5425.                VIMSEL_DIALIN  - Will access the local postoffice
  5426.                                 using dialin only
  5427.  
  5428.                VIMSEL_REMOTE  - User local on another postoffice
  5429.  
  5430.                VIMSEL_ALIAS   - Entry is an alias for another local entry
  5431.  
  5432.     VIMSEL_DIRECT_POSTOFFICE  - Entry is a postoffice that will directly connect
  5433.  
  5434.     VIMSEL_INDIRECT_POSTOFFICE- Entry is a postoffice that will not direct connect
  5435.  
  5436.                   VIMSEL_FAN  - Changes foreign alias name, which is used in gateway
  5437.  
  5438.  
  5439. ΓòÉΓòÉΓòÉ 10.9.2. Return Codes ΓòÉΓòÉΓòÉ
  5440.  
  5441. The RxVIMSetABEntryAttributes function returns the following values: 
  5442.  
  5443.         0 - Successful return
  5444.  
  5445. The return values from all of the function calls return a zero for success, and 
  5446. non-zero for failure.  To retrieve the actual failure reason, use the 
  5447. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5448. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5449. be returned by RxVIMSetABEntryAttributes: 
  5450.  
  5451.         VIMSTS_SUCCESS                  Successful return
  5452.         VIMSTS_FAILURE                  Function Failed
  5453.  
  5454.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  5455.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5456.         VIMSTS_INVALID_SELECTOR         One of the request selectors is  bad
  5457.         VIMSTS_NOT_SUPPORTED            Attribute not supported
  5458.  
  5459.  
  5460. ΓòÉΓòÉΓòÉ 10.9.3. Example ΓòÉΓòÉΓòÉ
  5461.  
  5462. /* Example of using RxVIMSetABEntryAttributes */
  5463.  
  5464. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5465. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5466. call RxVIMLoadFuncs
  5467.  
  5468.  
  5469. /* This will establish a connection to the VIM system */
  5470. rc = RxVIMInitialize()
  5471.  
  5472. /* Obtain the default session information */
  5473. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5474.  
  5475. Say 'Default path:' db_path
  5476. Say 'Default name:' user_name
  5477.  
  5478. /* Opening a session with the mail subsystem */
  5479. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5480.  
  5481.  
  5482. /* Retrieve the name of the first address book */
  5483. Pos = ''                                  /* Start at beginning */
  5484. skipcnt = 1                               /* Start at beginning */
  5485. mcount  = 1                               /* Return one entry   */
  5486. more = ''                                 /* more entries?      */
  5487.  
  5488. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5489. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5490. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5491.  
  5492. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5493.  
  5494. /* Open the first addressbook */
  5495. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5496.  
  5497. /* Retrieve the name of the first address book entry */
  5498. Pos = ''                                  /* Start at beginning */
  5499. skipcnt = 1                               /* Start at beginning */
  5500. mcount  = 1                               /* Return one entry   */
  5501. more = ''                                 /* more entries?      */
  5502. filter = 'VIMSEL_NO_FILTER'
  5503. fdata  = ''
  5504.  
  5505. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5506. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
  5507. attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */
  5508.  
  5509. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')
  5510.  
  5511.  
  5512.  
  5513. /* Get the comment for the first address book entry */
  5514. ItemBuf.0 = 1
  5515. ItemBuf.1.Selector = 'VIMSEL_COMMENTS'
  5516. ItemBuf.1.Value    = 'This entry was updated using RexxVIM'
  5517.  
  5518. rc = RxVIMGetABEntryAttributes(AddrBkPtr,RefNo.1,'','ItemBuf')
  5519.  
  5520.  
  5521.  
  5522. /* Close the session with the mail subsystem */
  5523. rc = RxVIMCloseSession( Sess )
  5524.  
  5525. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5526. call RxVIMDropFuncs
  5527.  
  5528.  
  5529. ΓòÉΓòÉΓòÉ 10.10. RxVIMRemoveAddressBookEntry ΓòÉΓòÉΓòÉ
  5530.  
  5531. The RxVIMRemoveAddressBookEntry function deletes an address book entry from the 
  5532. specified address book. 
  5533.  
  5534.  
  5535. ΓòÉΓòÉΓòÉ 10.10.1. Syntax ΓòÉΓòÉΓòÉ
  5536.  
  5537. RxVIMRemoveAddressBookEntry is called with three parameters.  The first 
  5538. parameter is a variable that contains the pointer to the current address book. 
  5539.  
  5540. The second is a variable containing the reference number for the entry to 
  5541. delete.  If this value is set to null (''), the third parameter is used to 
  5542. locate the entry to delete. 
  5543.  
  5544. The third parameter is the name of the entry to delete.  This parameter is used 
  5545. if the Entry Reference number (parameter two) is null. 
  5546.  
  5547. call RxVIMRemoveAddressBookEntry AddrBkPtr,EntryRef,''
  5548.  
  5549. or
  5550.  
  5551. rc = RxVIMRemoveAddressBookEntry( AddrBkPtr,EntryRef,'' )
  5552.  
  5553.  
  5554. ΓòÉΓòÉΓòÉ 10.10.2. Return Codes ΓòÉΓòÉΓòÉ
  5555.  
  5556. The RxVIMRemoveAddressBookEntry function returns the following values: 
  5557.  
  5558.         0 - Successful return
  5559.  
  5560. The return values from all of the function calls return a zero for success, and 
  5561. non-zero for failure.  To retrieve the actual failure reason, use the 
  5562. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5563. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5564. be returned by RxVIMRemoveAddressBookEntry: 
  5565.  
  5566.         VIMSTS_SUCCESS                  Successful return
  5567.         VIMSTS_FAILURE                  Function Failed
  5568.  
  5569.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  5570.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  5571.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5572.         VIMSTS_WRITE_FAILURE            Error writing to disk
  5573.  
  5574.  
  5575. ΓòÉΓòÉΓòÉ 10.10.3. Example ΓòÉΓòÉΓòÉ
  5576.  
  5577. /* Example of using RxVIMRemoveAddressBookEntry */
  5578.  
  5579. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5580. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5581. call RxVIMLoadFuncs
  5582.  
  5583.  
  5584. /* This will establish a connection to the VIM system */
  5585. rc = RxVIMInitialize()
  5586.  
  5587. /* Obtain the default session information */
  5588. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5589.  
  5590. Say 'Default path:' db_path
  5591. Say 'Default name:' user_name
  5592.  
  5593. /* Opening a session with the mail subsystem */
  5594. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5595.  
  5596.  
  5597. /* Retrieve the name of the first address book */
  5598. Pos = ''                                  /* Start at beginning */
  5599. skipcnt = 1                               /* Start at beginning */
  5600. mcount  = 1                               /* Return one entry   */
  5601. more = ''                                 /* more entries?      */
  5602.  
  5603. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5604. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5605. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5606.  
  5607. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5608.  
  5609. /* Open the first addressbook */
  5610. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5611.  
  5612. /* Retrieve the name of the first address book entry */
  5613. Pos = ''                                  /* Start at beginning */
  5614. skipcnt = 1                               /* Start at beginning */
  5615. mcount  = 1                               /* Return one entry   */
  5616. more = ''                                 /* more entries?      */
  5617. filter = 'VIMSEL_NO_FILTER'
  5618. fdata  = ''
  5619.  
  5620. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5621. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
  5622. attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */
  5623.  
  5624. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')
  5625.  
  5626.  
  5627.  
  5628. /* Delete the first entry from the first address book */
  5629. rc = RxVIMRemoveAddressBookEntry(AddrBkPtr,RefNo.1,'')
  5630.  
  5631.  
  5632.  
  5633. /* Close the session with the mail subsystem */
  5634. rc = RxVIMCloseSession( Sess )
  5635.  
  5636. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5637. call RxVIMDropFuncs
  5638.  
  5639.  
  5640. ΓòÉΓòÉΓòÉ 10.11. RxVIMAddGroupMember ΓòÉΓòÉΓòÉ
  5641.  
  5642. The RxVIMAddGroupMember function adds a new entry to an existing group list. 
  5643. The group must have already been created, using the RxVIMCreateAddressBookEntry 
  5644. prior to adding entries. 
  5645.  
  5646.  
  5647. ΓòÉΓòÉΓòÉ 10.11.1. Syntax ΓòÉΓòÉΓòÉ
  5648.  
  5649. RxVIMAddGroupMember is called with four parameters.  The first parameter is a 
  5650. variable that contains the pointer to the current address book. 
  5651.  
  5652. The second is a variable containing the reference number for the group entry to 
  5653. add the new entry.  If this value is set to null (''), the third parameter is 
  5654. used to locate the entry. 
  5655.  
  5656. The third parameter is the name of the group entry to add the new entry.  This 
  5657. parameter is used if the Entry Reference number (parameter two) is null. 
  5658.  
  5659. The fourth parameter is a the name to add to the group.  This name must be an 
  5660. existing entry in the address book. 
  5661.  
  5662. call RxVIMAddGroupMember AddrBkPtr,EntryRef,'','Mark Stevens'
  5663.  
  5664. or
  5665.  
  5666. rc = RxVIMAddGroupMember( AddrBkPtr,EntryRef,'','Mark Stevens' )
  5667.  
  5668.  
  5669. ΓòÉΓòÉΓòÉ 10.11.2. Return Codes ΓòÉΓòÉΓòÉ
  5670.  
  5671. The RxVIMAddGroupMember function returns the following values: 
  5672.  
  5673.         0 - Successful return
  5674.  
  5675. The return values from all of the function calls return a zero for success, and 
  5676. non-zero for failure.  To retrieve the actual failure reason, use the 
  5677. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5678. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5679. be returned by RxVIMAddGroupMember: 
  5680.  
  5681.         VIMSTS_SUCCESS                  Successful return
  5682.         VIMSTS_FAILURE                  Function Failed
  5683.  
  5684.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  5685.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  5686.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5687.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  5688.  
  5689.  
  5690. ΓòÉΓòÉΓòÉ 10.11.3. Example ΓòÉΓòÉΓòÉ
  5691.  
  5692. /* Example of using RxVIMAddGroupMember */
  5693.  
  5694. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5695. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5696. call RxVIMLoadFuncs
  5697.  
  5698.  
  5699. /* This will establish a connection to the VIM system */
  5700. rc = RxVIMInitialize()
  5701.  
  5702. /* Obtain the default session information */
  5703. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5704.  
  5705. Say 'Default path:' db_path
  5706. Say 'Default name:' user_name
  5707.  
  5708. /* Opening a session with the mail subsystem */
  5709. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5710.  
  5711.  
  5712. /* Retrieve the name of the first address book */
  5713. Pos = ''                                  /* Start at beginning */
  5714. skipcnt = 1                               /* Start at beginning */
  5715. mcount  = 1                               /* Return one entry   */
  5716. more = ''                                 /* more entries?      */
  5717.  
  5718. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5719. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5720. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5721.  
  5722. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5723.  
  5724. /* Open the first addressbook */
  5725. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5726.  
  5727. /* Retrieve the name of the first group entry in the address book */
  5728. Pos = ''                                  /* Start at beginning */
  5729. skipcnt = 1                               /* Start at beginning */
  5730. mcount  = 1                               /* Return one entry   */
  5731. more = ''                                 /* more entries?      */
  5732. filter = 'VIMSEL_GROUP'                   /* return only group entries */
  5733. fdata  = ''
  5734.  
  5735. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5736. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
  5737. attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */
  5738.  
  5739. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')
  5740.  
  5741.  
  5742.  
  5743. /* Add a new member to the first group in the address book */
  5744. rc = RxVIMAddGroupMember(AddrBkPtr,RefNo.1,'','Mark Stevens')
  5745.  
  5746.  
  5747.  
  5748. /* Close the session with the mail subsystem */
  5749. rc = RxVIMCloseSession( Sess )
  5750.  
  5751. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5752. call RxVIMDropFuncs
  5753.  
  5754.  
  5755. ΓòÉΓòÉΓòÉ 10.12. RxVIMRemoveGroupMember ΓòÉΓòÉΓòÉ
  5756.  
  5757. The RxVIMRemoveGroupMember function deletes an  entry from an existing group 
  5758. list. 
  5759.  
  5760.  
  5761. ΓòÉΓòÉΓòÉ 10.12.1. Syntax ΓòÉΓòÉΓòÉ
  5762.  
  5763. RxVIMRemoveGroupMember is called with four parameters.  The first parameter is 
  5764. a variable that contains the pointer to the current address book. 
  5765.  
  5766. The second is a variable containing the reference number for the group entry to 
  5767. delete an entry.  If this value is set to null (''), the third parameter is 
  5768. used to locate the entry. 
  5769.  
  5770. The third parameter is the name of the group entry to delete the entry.  This 
  5771. parameter is used if the Entry Reference number (parameter two) is null. 
  5772.  
  5773. The fourth parameter is a the name to delete from the group. 
  5774.  
  5775. call RxVIMRemoveGroupMember AddrBkPtr,EntryRef,'','Mark Stevens'
  5776.  
  5777. or
  5778.  
  5779. rc = RxVIMRemoveGroupMember( AddrBkPtr,EntryRef,'','Mark Stevens' )
  5780.  
  5781.  
  5782. ΓòÉΓòÉΓòÉ 10.12.2. Return Codes ΓòÉΓòÉΓòÉ
  5783.  
  5784. The RxVIMRemoveGroupMember function returns the following values: 
  5785.  
  5786.         0 - Successful return
  5787.  
  5788. The return values from all of the function calls return a zero for success, and 
  5789. non-zero for failure.  To retrieve the actual failure reason, use the 
  5790. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5791. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5792. be returned by RxVIMRemoveGroupMember: 
  5793.  
  5794.         VIMSTS_SUCCESS                  Successful return
  5795.         VIMSTS_FAILURE                  Function Failed
  5796.  
  5797.         VIMSTS_BAD_PARAM                Bad parameter passed to function
  5798.         VIMSTS_INSUFFICIENT_MEMORY      Not enough memory
  5799.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5800.         VIMSTS_WRITE_FAILURE            Error writing to the disk
  5801.  
  5802.  
  5803. ΓòÉΓòÉΓòÉ 10.12.3. Example ΓòÉΓòÉΓòÉ
  5804.  
  5805. /* Example of using RxVIMRemoveGroupMember */
  5806.  
  5807. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5808. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5809. call RxVIMLoadFuncs
  5810.  
  5811.  
  5812. /* This will establish a connection to the VIM system */
  5813. rc = RxVIMInitialize()
  5814.  
  5815. /* Obtain the default session information */
  5816. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5817.  
  5818. Say 'Default path:' db_path
  5819. Say 'Default name:' user_name
  5820.  
  5821. /* Opening a session with the mail subsystem */
  5822. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5823.  
  5824.  
  5825. /* Retrieve the name of the first address book */
  5826. pos = ''                                  /* Start at beginning */
  5827. skipcnt = 1                               /* Start at beginning */
  5828. mcount  = 1                               /* Return one entry   */
  5829. more = ''                                 /* more entires?      */
  5830.  
  5831. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5832. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5833. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5834.  
  5835. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5836.  
  5837. /* Open the first addressbook */
  5838. rc = RxVIMOpenAddressBook(Sess, name.1, 'AddrBkPtr')
  5839.  
  5840. /* Retrieve the name of the first group entry in the address book */
  5841. pos = ''                                  /* Start at beginning */
  5842. skipcnt = 1                               /* Start at beginning */
  5843. mcount  = 1                               /* Return one entry   */
  5844. more = ''                                 /* more entires?      */
  5845. filter = 'VIMSEL_GROUP'                   /* return only group entries */
  5846. fdata  = ''
  5847.  
  5848. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5849. attrDesc.1.Selector = 'VIMSEL_REF'        /* reference number         */
  5850. attrDesc.1.Buffer   = 'RefNo'             /* buffer to return RefNo   */
  5851.  
  5852. rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'pos',skipcnt,'attrDesc','mcount',filter,fdata,'more')
  5853.  
  5854.  
  5855.  
  5856. /* Delete an entry from the first group in the address book */
  5857. rc = RxVIMRemoveGroupMember(AddrBkPtr,RefNo.1,'','Mark Stevens')
  5858.  
  5859.  
  5860.  
  5861. /* Close the session with the mail subsystem */
  5862. rc = RxVIMCloseSession( Sess )
  5863.  
  5864. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5865. call RxVIMDropFuncs
  5866.  
  5867.  
  5868. ΓòÉΓòÉΓòÉ 10.13. RxVIMCloseAddressBook ΓòÉΓòÉΓòÉ
  5869.  
  5870. The RxVIMCloseAddressBook function closes the session with the specified 
  5871. address book and frees any resources. 
  5872.  
  5873.  
  5874. ΓòÉΓòÉΓòÉ 10.13.1. Syntax ΓòÉΓòÉΓòÉ
  5875.  
  5876. RxVIMCloseAddressBook is called with one parameter.  The parameter is the 
  5877. variable containing the pointer to the address book to close. 
  5878.  
  5879. call RxVIMCloseAddressBook AddrBkPtr
  5880.  
  5881. or
  5882.  
  5883. rc = RxVIMCloseAddressBook( AddrBkPtr )
  5884.  
  5885.  
  5886. ΓòÉΓòÉΓòÉ 10.13.2. Return Codes ΓòÉΓòÉΓòÉ
  5887.  
  5888. The RxVIMCloseAddressBook function returns the following values: 
  5889.  
  5890.         0 - Successful return
  5891.  
  5892. The return values from all of the function calls return a zero for success, and 
  5893. non-zero for failure.  To retrieve the actual failure reason, use the 
  5894. RxVIMStatus function.  The RxVIMStatus function converts the numeric return 
  5895. value to the actual failure text.  Using RxVIMStatus, the following values may 
  5896. be returned by RxVIMCloseAddressBook: 
  5897.  
  5898.         VIMSTS_SUCCESS                  Successful return
  5899.         VIMSTS_FAILURE                  Function Failed
  5900.  
  5901.         VIMSTS_INVALID_OBJECT           The address book handle is bad
  5902.  
  5903.  
  5904. ΓòÉΓòÉΓòÉ 10.13.3. Example ΓòÉΓòÉΓòÉ
  5905.  
  5906. /* Example of using RxVIMCloseAddressBook */
  5907.  
  5908. /* The RxVIMLoadFuncs function loads all of the VIM extensions */
  5909. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  5910. call RxVIMLoadFuncs
  5911.  
  5912.  
  5913. /* This will establish a connection to the VIM system */
  5914. rc = RxVIMInitialize()
  5915.  
  5916. /* Obtain the default session information */
  5917. rc = RxVIMDefaultSessionInfo('db_path', 'user_name')
  5918.  
  5919. Say 'Default path:' db_path
  5920. Say 'Default name:' user_name
  5921.  
  5922. /* Opening a session with the mail subsystem */
  5923. rc = RxVIMOpenSession(db_path, user_name, 'SNOOPY', 'Sess')
  5924.  
  5925. /* Retrieve the name of the first address book */
  5926. pos = ''                                  /* Start at beginning */
  5927. skipcnt = 1                               /* Start at beginning */
  5928. mcount  = 1                               /* Return one entry   */
  5929. more = ''                                 /* more entires?      */
  5930.  
  5931. attrDesc.0 = 1                            /* retrieve 1 attribute     */
  5932. attrDesc.1.Selector = 'VIMSEL_NAME'       /* name of address book     */
  5933. attrDesc.1.Buffer   = 'name'              /* buffer to return name    */
  5934.  
  5935. rc = RxVIMEnumerateAddressBooks(Sess,'pos',skipcnt,'attrDesc','mcount','more')
  5936.  
  5937. /* Open the first address book found */
  5938. rc = RxVIMOpenAddressBook(Sess,name.1,'AddrBkPtr')
  5939.  
  5940.  
  5941.  
  5942. /* Close the address book */
  5943. rc = RxVIMCloseAddressBook( AddrBkPtr )
  5944.  
  5945.  
  5946.  
  5947. /* Close the session with the mail subsystem */
  5948. rc = RxVIMCloseSession( Sess )
  5949.  
  5950. /* The RxVIMDropFuncs function unloads all of the VIM extensions */
  5951. call RxVIMDropFuncs
  5952.  
  5953.  
  5954. ΓòÉΓòÉΓòÉ 11. RexxVIM Examples ΓòÉΓòÉΓòÉ
  5955.  
  5956. Several examples are shown for using the many functions of RexxVIM in actual 
  5957. Rexx programs.  These examples are included with the RexxVIM product.  The 
  5958. examples include a general demo, VIM capabilities demo, as well as, demos for 
  5959. messaging, in-box processing and addressbooks. 
  5960.  
  5961.  
  5962. ΓòÉΓòÉΓòÉ 11.1. General Demo ΓòÉΓòÉΓòÉ
  5963.  
  5964. The general demo (DEMO.CMD) shows the proper loading of the RexxVIM functions, 
  5965. connection to the VIM subsystem, querying session capabilities, opening a VIM 
  5966. session, and querying the active session.  The example also shows the proper 
  5967. unloading and shutdown of the VIM connections and sessions. 
  5968.  
  5969. The DEMO.CMD is located with the rest of the RexxVIM product files, or can be 
  5970. created from the listing section by copying it to a file.  If it is copied to a 
  5971. file, some modification may be required prior to executing the command file. 
  5972. Normally, one space must be removed from the first line of the command file to 
  5973. instruct OS/2 that the file is a valid Rexx program. 
  5974.  
  5975.  
  5976. ΓòÉΓòÉΓòÉ 11.1.1. DEMO.CMD Listing ΓòÉΓòÉΓòÉ
  5977.  
  5978. /** RexxDemo **/
  5979. /*----------------------------------------*/
  5980. /*                                        */
  5981. /* Command line syntax:                   */
  5982. /*                                        */
  5983. /* demo db_path user_password user_name   */
  5984. /*                                        */
  5985. /*                                        */
  5986. /*----------------------------------------*/
  5987. ARG db_path user_pw user_name
  5988. '@echo off'
  5989. '@cls'
  5990. Say 'RexxVIM General Demonstration Program'
  5991. Say
  5992.  
  5993. /* unload functions upon error */
  5994. SIGNAL ON ERROR NAME done
  5995.  
  5996. /* Prompt for the parameters if not passed on the */
  5997. /* command line                                   */
  5998. if LENGTH(STRIP(db_path)) = 0 then do
  5999.    Say 'Enter Postoffice Directory -'
  6000.    PARSE PULL db_path .
  6001.    Say
  6002.    Say 'Enter User Name -'
  6003.    PARSE PULL user_name
  6004.    Say 'Enter Password -'
  6005.    PARSE PULL user_pw
  6006. end  /* Do */
  6007.  
  6008.  
  6009. /* Load the RexxVIM extensions to Rexx */
  6010. rc = RxFuncAdd('RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs')
  6011. if rc <> 0 then do
  6012.    Say
  6013.    Say 'RexxVIM failed to load, return code' rc
  6014.    Say
  6015.    Say 'Functions have been released.  Retry program.'
  6016.    signal done
  6017. end  /* Do */
  6018. call RxVIMLoadFuncs
  6019. Say 'Functions are now loaded'
  6020. Say
  6021.  
  6022.  
  6023. /* Initialize the VIM subsystem */
  6024. rc = RxVIMInitialize()
  6025. Say
  6026. Say '|-Call To Routine ---------------RC--|'
  6027. Say '  RxVIMInitialize-              ' rc
  6028. if (rc > 0) then call vimerr
  6029.  
  6030.  
  6031. /* Retrieve the default session info if present */
  6032. rc = RxVIMGetDefaultSessionInfo('def_path', 'def_user')
  6033. Say '  RxVIMGetDefaultSessionInfo -  ' rc
  6034. if (rc > 0) then call vimerr
  6035. Say '      Default Path -' def_path
  6036. Say '      Default Name -' def_user
  6037. Say
  6038.  
  6039.  
  6040. /* Query the maximum subject line length and maximum */
  6041. /* text length                                       */
  6042. rc = RxVIMQueryCapability('VIMSEL_MAX_SUBJECT_LEN','Query')
  6043. Say '  RxVIMQueryCapability -        ' rc
  6044. if (rc > 0) then call vimerr
  6045. Say '      Max Subject Length -' query
  6046. rc = RxVIMQueryCapability('VIMSEL_MAX_TEXT_LEN','Query')
  6047. if (rc > 0) then call vimerr
  6048. Say '         Max Text Length -' query
  6049. Say
  6050.  
  6051.  
  6052. /* Open a session with the postoffice using the parameters */
  6053. /* provided by the user                                    */
  6054. rc = RxVIMOpenSession(db_path,user_name,user_pw,'Session')
  6055. Say '  RxVIMOpenSession -            ' rc
  6056. if (rc > 0) then call vimerr
  6057.  
  6058.  
  6059. /* Retieve the name and type of active session */
  6060. rc = RxVIMGetEntityName(Session,'Entity')
  6061. Say '  RxVIMGetEntityName            ' rc
  6062. if (rc > 0) then call vimerr
  6063. Say '      Type -' entity.Type
  6064. Say '      Name -' entity.Name
  6065. Say
  6066.  
  6067.  
  6068. /* Close the session with the postoffice */
  6069. rc = RxVIMCloseSession(Session)
  6070. Say '  RxVIMCloseSession -            ' rc
  6071. if (rc > 0) then call vimerr
  6072.  
  6073.  
  6074. /* Terminate the active VIM subsystem connection */
  6075. rc = RxVIMTerminate()
  6076. Say '  RxVIMTerminate -               ' rc
  6077. if (rc > 0) then call vimerr
  6078. signal done
  6079.  
  6080.  
  6081. /***** VIMErr *******/
  6082.  
  6083. /* If an error occurs, this function will return the text */
  6084. /* associated with the error.  Extended text may be       */
  6085. /* displayed if it exists for the specified error.        */
  6086.  
  6087. VIMERR:
  6088.  
  6089. rc = RxVIMStatusText(rc,'Status')
  6090. Say
  6091. Say '|-Error Information -----------------|'
  6092. Say '  Error Text -' status.1
  6093. Say
  6094. if LENGTH(STRIP(status.2)) > 0 then
  6095.    Say '  Ext Status -' status.2
  6096. rc = RxVIMTerminate()
  6097. signal done
  6098.  
  6099.  
  6100. /* The done section will unload the RexxVIM extensions */
  6101. /* and exit the program                                */
  6102. DONE:
  6103. /*** Drop all of the external functions ***/
  6104. call RxVIMDropFuncs
  6105. Say '|------------------------------------|'
  6106. Say 'Demo Complete.  All functions released'
  6107. 'pause'
  6108. exit
  6109.  
  6110.  
  6111. ΓòÉΓòÉΓòÉ 11.2. Query Capabilities Demo ΓòÉΓòÉΓòÉ
  6112.  
  6113. The Query Capabilities demo (VIMCAP.CMD) shows the use of the 
  6114. RxVIMQueryCapability function to determine support in the underlying VIM 
  6115. subsystem.  This demo can be used to query all selectors by using the command 
  6116. word ALL, or will support a query of a single selector.  Launching the demo 
  6117. below will query all selectors. 
  6118.  
  6119. The VIMCAP.CMD is located with the rest of the RexxVIM product files, or can be 
  6120. created from the listing section by copying it to a file.  If it is copied to a 
  6121. file, some modification may be required prior to executing the command file. 
  6122. Normally, one space must be removed from the first line of the command file to 
  6123. instruct OS/2 that the file is a valid Rexx program. 
  6124.  
  6125.  
  6126. ΓòÉΓòÉΓòÉ 11.2.1. VIMCAP.CMD Listing ΓòÉΓòÉΓòÉ
  6127.  
  6128. /** Rexx Program to Query VIM Capabilities **/
  6129.  
  6130. /* The program accepts either a selector to query or */
  6131. /* the command word ALL to query all selectors       */
  6132. ARG TYPE
  6133.  
  6134. '@echo off'
  6135. '@cls'
  6136.  
  6137. /* Unload functions upon error */
  6138. SIGNAL ON ERROR NAME done
  6139.  
  6140. if LENGTH(STRIP(type)) = 0 then do
  6141.    Say
  6142.    Say 'Incorrect Syntax!  Correct syntax is -'
  6143.    Say
  6144.    Say 'VIMCAP < Capability to query | ALL'
  6145.    Say
  6146.    Say 'VIMCAP ALL will query all VIM functions'
  6147.    Say
  6148.    return
  6149. end  /* Do */
  6150.  
  6151. TYPE = TRANSLATE(STRIP(TYPE))
  6152. if TYPE = 'ALL' then do
  6153.   call LoadVIMCap
  6154.   doall = TRUE
  6155. end  /* Do */
  6156. else
  6157.   doall = FALSE
  6158.  
  6159. call RxFuncAdd 'RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs'
  6160. call RxVIMLoadFuncs
  6161. rc = RxVIMInitialize()
  6162. Say
  6163. Say '|-Capability----------------------Value------------------------------------|'
  6164.  
  6165. if doall = TRUE then do
  6166.    do count=1 to vimcap.0
  6167.       TYPE = TRANSLATE(STRIP(vimcap.count))
  6168.       rc = RxVIMQueryCapability(TYPE,'Query')
  6169.    if rc>0 then signal VIMERR
  6170.       Say ' 'LEFT(TYPE||'-',30)'  ' SUBSTR(Query.1,1,30)
  6171.    end /* do */
  6172. end  /* Do */
  6173. else do
  6174.    rc = RxVIMQueryCapability(TYPE,'Query')
  6175.    if rc>0 then signal VIMERR
  6176.    Say ' 'LEFT(TYPE||'-',30)'  ' SUBSTR(Query.1,1,30)
  6177.    Say
  6178. end  /* Do */
  6179.  
  6180. rc = RxVIMTerminate()
  6181. /*** Drop all of the external functions ***/
  6182. call RxVIMDropFuncs
  6183. Say '|--------------------------------------------------------------------------|'
  6184. Say 'Demo Complete.  All functions released'
  6185. 'pause'
  6186. exit
  6187.  
  6188. /***** VIMErr *******/
  6189. VIMERR:
  6190.  
  6191. rc = RxVIMStatusText(rc,'Status')
  6192. Say
  6193. Say '|-Error Information -----------------|'
  6194. Say '  Error Text -' status.1
  6195. Say
  6196. if LENGTH(STRIP(status.2)) > 0 then
  6197.    Say '  Ext Status -' status.2
  6198. rc = RxVIMTerminate()
  6199.  
  6200. DONE:
  6201. /*** Drop all of the external functions ***/
  6202. call RxVIMDropFuncs
  6203. Say '|------------------------------------|'
  6204. Say 'Demo Complete.  All functions released'
  6205. 'pause'
  6206. exit
  6207.  
  6208. /****** Load all VIM Capabilities into stem variable *****/
  6209. LOADVIMCAP:
  6210.  
  6211. vimcap.0    =  32
  6212. vimcap.1    =  "VIMSEL_VERSION"
  6213. vimcap.2    =  "VIMSEL_IMPLEMENTATION"
  6214. vimcap.3    =  "VIMSEL_IMPLEMENTATION_VERSION"
  6215. vimcap.4    =  "VIMSEL_PRODUCT"
  6216. vimcap.5    =  "VIMSEL_MAX_SUBJECT_LEN"
  6217. vimcap.6    =  "VIMSEL_MAX_TYPE_LEN"
  6218. vimcap.7    =  "VIMSEL_MAX_TEXT_LEN"
  6219. vimcap.8    =  "VIMSEL_RTF"
  6220. vimcap.9    =  "VIMSEL_FAX"
  6221. vimcap.10   =  "VIMSEL_STYLED"
  6222. vimcap.11   =  "VIMSEL_PICT"
  6223. vimcap.12   =  "VIMSEL_MOVIE"
  6224. vimcap.13   =  "VIMSEL_IMAG"
  6225. vimcap.14   =  "VIMSEL_UNWRAPPED_TEXT"
  6226. vimcap.15   =  "VIMSEL_ALL_NOTE_PARTS_SUPP"
  6227. vimcap.16   =  "VIMSEL_ATTACH_TYPE_SUPP"
  6228. vimcap.17   =  "VIMSEL_ATTACH_DIRS"
  6229. vimcap.18   =  "VIMSEL_ENCRYPT"
  6230. vimcap.19   =  "VIMSEL_ENCRYPT_WITH_KEY"
  6231. vimcap.20   =  "VIMSEL_SIGN"
  6232. vimcap.21   =  "VIMSEL_NSTD_DERIVED_REPLIES"
  6233. vimcap.22   =  "VIMSEL_NSTD_DERIVED_FORWRDS"
  6234. vimcap.23   =  "VIMSEL_CP850"
  6235. vimcap.24   =  "VIMSEL_CP1252"
  6236. vimcap.25   =  "VIMSEL_CP437"
  6237. vimcap.26   =  "VIMSEL_LMBCS"
  6238. vimcap.27   =  "VIMSEL_ISTRING"
  6239. vimcap.28   =  "VIMSEL_UNICODE"
  6240. vimcap.29   =  "VIMSEL_APPLESINGLE"
  6241. vimcap.30   =  "VIMSEL_PATH_REQUIRED"
  6242. vimcap.31   =  "VIMSEL_NAME_REQUIRED"
  6243. vimcap.32   =  "VIMSEL_PASS_REQUIRED"
  6244. return
  6245.  
  6246.  
  6247. ΓòÉΓòÉΓòÉ 11.3. Send Message Demo ΓòÉΓòÉΓòÉ
  6248.  
  6249. The Send Message (MESSAGE.CMD) demo shows how RexxVIM can be used to create and 
  6250. send messages.  Launching the demo below will send a message back to the person 
  6251. that is logged into the postoffice.  The message will contain a text portion, 
  6252. and a file attachment. 
  6253.  
  6254. The MESSAGE.CMD is located with the rest of the RexxVIM product files, or can 
  6255. be created from the listing section by copying it to a file.  If it is copied 
  6256. to a file, some modification may be required prior to executing the command 
  6257. file.  Normally, one space must be removed from the first line of the command 
  6258. file to instruct OS/2 that the file is a valid Rexx program. 
  6259.  
  6260.  
  6261. ΓòÉΓòÉΓòÉ 11.3.1. MESSAGE.CMD Listing ΓòÉΓòÉΓòÉ
  6262.  
  6263. /** Message.cmd **/
  6264. /*-------------------------------------------*/
  6265. /*                                           */
  6266. /* Command line syntax:                      */
  6267. /*                                           */
  6268. /* message db_path user_password user_name   */
  6269. /*                                           */
  6270. /*                                           */
  6271. /*-------------------------------------------*/
  6272. ARG db_path user_pw user_name
  6273. '@echo off'
  6274. '@cls'
  6275. Say 'RexxVIM Message Demonstration Program'
  6276. Say
  6277.  
  6278. /* Unload functions upon error */
  6279. SIGNAL ON ERROR NAME done
  6280.  
  6281. /* Prompt for the parameters if not passed on the */
  6282. /* command line                                   */
  6283. if LENGTH(STRIP(db_path)) = 0 then do
  6284.    Say 'Enter Postoffice Directory -'
  6285.    PARSE PULL db_path .
  6286.    Say
  6287.    Say 'Enter User Name -'
  6288.    PARSE PULL user_name
  6289.    Say 'Enter Password -'
  6290.    PARSE PULL user_pw
  6291. end  /* Do */
  6292.  
  6293.  
  6294. /* Load the RexxVIM extensions to Rexx */
  6295. rc = RxFuncAdd('RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs')
  6296. if rc <> 0 then do
  6297.    Say
  6298.    Say 'RexxVIM failed to load, return code' rc
  6299.    Say
  6300.    Say 'Functions have been released.  Retry program.'
  6301.    signal done
  6302. end  /* Do */
  6303. call RxVIMLoadFuncs
  6304. Say 'Functions are now loaded'
  6305. Say
  6306.  
  6307.  
  6308. /* Initialize the VIM subsystem */
  6309. rc = RxVIMInitialize()
  6310. Say
  6311. Say '|-Call To Routine ---------------RC--|'
  6312. Say '  RxVIMInitialize -              ' rc
  6313. if (rc > 0) then call vimerr
  6314.  
  6315.  
  6316.  
  6317. /* Open a session with the postoffice using the parameters */
  6318. /* provided by the user                                    */
  6319. rc = RxVIMOpenSession(db_path,user_name,user_pw,'Session')
  6320. Say '  RxVIMOpenSession -             ' rc
  6321. if (rc > 0) then call vimerr
  6322.  
  6323.  
  6324. /* Create a new message of type VIM_MAIL */
  6325. rc = RxVIMCreateMessage(Session,'VIM_MAIL','Message')
  6326. Say '  RxVIMCreateMessage -           ' rc
  6327. if (rc > 0) then call vimerr
  6328.  
  6329.  
  6330. /* Set the header text */
  6331. hdrtext = user_name"'s config.sys file"
  6332. rc = RxVIMSetMessageHeader(Message,'VIMSEL_SUBJECT', hdrtext)
  6333. Say '  RxVIMSetMessageHeader -        ' rc
  6334. if (rc > 0) then call vimerr
  6335.  
  6336.  
  6337. /* Set the priority to high */
  6338. rc = RxVIMSetMessageHeader(Message,'VIMSEL_PRIORITY', 'VIM_HIGH_PRIORITY')
  6339. Say '  RxVIMSetMessageHeader -        ' rc
  6340. if (rc > 0) then call vimerr
  6341.  
  6342.  
  6343. /* Set the recipient to the user that is logged on */
  6344. /* This will send the message back to ourselves    */
  6345. rc = RxVIMSetMessageRecipient(Message,'VIMSEL_TO','VIMSEL_ENTITY','','',,
  6346.                 user_name,'','')
  6347. Say '  RxVIMSetMessageRecipient -     ' rc
  6348. if (rc > 0) then call vimerr
  6349.  
  6350.  
  6351. /* Add some text to the message */
  6352. itemtxt = 'This message was created using the RexxVIM !!'
  6353. rc = RxVIMSetMessageItem(Message,'VIMSEL_NOTE_PART','VIM_TEXT','VIMSEL_NATIVE',,
  6354.          'Message Demo',itemtxt,'')
  6355. Say '  RxVIMSetMessageItem -          ' rc
  6356. if (rc > 0) then call vimerr
  6357.  
  6358.  
  6359. /* Add the config.sys as a file attachment in the message */
  6360. drive = STRIP('c: ')
  6361. rc = RxVIMSetMessageItem(Message,'VIMSEL_ATTACH','VIM_TEXT','VIMSEL_NATIVE',,
  6362.          'config.sys','',drive'\config.sys')
  6363. Say '  RxVIMSetMessageItem -          ' rc
  6364. if (rc > 0) then call vimerr
  6365.  
  6366.  
  6367. /* Send the message */
  6368. rc = RxVIMSendMessage(Message)
  6369. Say '  RxVIMSendMessage -             ' rc
  6370. if (rc > 0) then call vimerr
  6371.  
  6372.  
  6373. /* Close the session with the postoffice */
  6374. rc = RxVIMCloseSession(Session)
  6375. Say '  RxVIMCloseSession -            ' rc
  6376. if (rc > 0) then call vimerr
  6377.  
  6378.  
  6379. /* Terminate the active VIM subsystem connection */
  6380. rc = RxVIMTerminate()
  6381. Say '  RxVIMTerminate -               ' rc
  6382. if (rc > 0) then call vimerr
  6383. signal done
  6384.  
  6385.  
  6386. /***** VIMErr *******/
  6387.  
  6388. /* If an error occurs, this function will return the text */
  6389. /* associated with the error.  Extended text may be       */
  6390. /* displayed if it exists for the specified error.        */
  6391.  
  6392. VIMERR:
  6393.  
  6394. rc = RxVIMStatusText(rc,'Status')
  6395. Say
  6396. Say '|-Error Information -----------------|'
  6397. Say '  Error Text -' status.1
  6398. Say
  6399. Say '  Ext Status -' status.2
  6400. rc = RxVIMTerminate()
  6401. signal done
  6402.  
  6403.  
  6404. /* The done section will unload the RexxVIM extensions */
  6405. /* and exit the program                                */
  6406. DONE:
  6407. /*** Drop all of the external functions ***/
  6408. call RxVIMDropFuncs
  6409. Say '|------------------------------------|'
  6410. Say 'Demo Complete.  All functions released'
  6411. 'pause'
  6412. exit
  6413.  
  6414.  
  6415. ΓòÉΓòÉΓòÉ 11.4. Message Container Demo ΓòÉΓòÉΓòÉ
  6416.  
  6417. The Message Container (MSGCONT.CMD) demo shows how RexxVIM can be used to open 
  6418. and read message containers, like the Inbox.  Launching the demo below will 
  6419. retrieve each message from the Inbox, and allow it to be deleted, stored in a 
  6420. folder, or left in the Inbox. 
  6421.  
  6422. The MSGCONT.CMD is located with the rest of the RexxVIM product files, or can 
  6423. be created from the listing section by copying it to a file.  If it is copied 
  6424. to a file, some modification may be required prior to executing the command 
  6425. file.  Normally, one space must be removed from the first line of the command 
  6426. file to instruct OS/2 that the file is a valid Rexx program. 
  6427.  
  6428.  
  6429. ΓòÉΓòÉΓòÉ 11.4.1. MSGCONT.CMD Listing ΓòÉΓòÉΓòÉ
  6430.  
  6431. /** Msgcont.cmd **/
  6432. /*-------------------------------------------*/
  6433. /*                                           */
  6434. /* Command line syntax:                      */
  6435. /*                                           */
  6436. /* msgcont db_path user_password user_name   */
  6437. /*                                           */
  6438. /*                                           */
  6439. /*-------------------------------------------*/
  6440. ARG db_path user_pw user_name
  6441. '@echo off'
  6442. '@cls'
  6443. Say 'RexxVIM Message Container Demonstration Program'
  6444. Say
  6445.  
  6446. /* Unload functions upon error */
  6447. SIGNAL ON ERROR NAME done
  6448.  
  6449. /* Prompt for the parameters if not passed on the */
  6450. /* command line                                   */
  6451. if LENGTH(STRIP(db_path)) = 0 then do
  6452.    Say 'Enter Postoffice Directory -'
  6453.    PARSE PULL db_path .
  6454.    Say
  6455.    Say 'Enter User Name -'
  6456.    PARSE PULL user_name
  6457.    Say 'Enter Password -'
  6458.    PARSE PULL user_pw
  6459. end  /* Do */
  6460.  
  6461.  
  6462. /* Load the RexxVIM extensions to Rexx */
  6463. rc = RxFuncAdd('RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs')
  6464. if rc <> 0 then do
  6465.    Say
  6466.    Say 'RexxVIM failed to load, return code' rc
  6467.    Say
  6468.    Say 'Functions have been released.  Retry program.'
  6469.    signal done
  6470. end  /* Do */
  6471. call RxVIMLoadFuncs
  6472. Say 'Functions are now loaded'
  6473. Say
  6474.  
  6475.  
  6476. /* Initialize the VIM subsystem */
  6477. rc = RxVIMInitialize()
  6478. if (rc > 0) then call vimerr
  6479.  
  6480. /* Open a session with the postoffice using the parameters */
  6481. /* provided by the user                                    */
  6482. rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
  6483. if (rc > 0) then call vimerr
  6484.  
  6485.  
  6486. /* Open the default message container -- Inbox */
  6487. rc = RxVIMOpenMessageContainer(Session,'','Inbox')
  6488. if (rc > 0) then call vimerr
  6489.  
  6490.  
  6491. /* Query the message container for new mail */
  6492. rc = RxVIMQueryNewMessages(Inbox,'New_Mail')
  6493. if (rc > 0) then call vimerr
  6494. Say '      New Mail Flag is' New_Mail
  6495.  
  6496.  
  6497. /* Query the number of new messages */
  6498. rc = RxVIMQueryUnreadMailCount(Inbox,'Unread_Count')
  6499. if (rc > 0) then call vimerr
  6500. Say '   Number of unread messages is' Unread_Count
  6501. Say
  6502.  
  6503.  
  6504. /* Display all mail in Inbox if unread messages exist */
  6505.  
  6506. if New_Mail = 'True' then do
  6507.  
  6508.      Say 'To review all mail in Inbox,'
  6509.      'pause'
  6510.  
  6511.      /* Enumerate messages in container -- Inbox */
  6512.      pos = ''                           /* Start at the beginning of the container */
  6513.      skipcnt = 1                        /* Move forward through the container one at a time */
  6514.      mcount  = 1                        /* Retrieve 1 message for each call */
  6515.      filter  = 'VIMSEL_NO_FILTER'       /* No filter, return all messages in inbox */
  6516.      fdata   = ''                       /* No filter data */
  6517.      flags   = 'VIM_NO_FLAGS'           /* No enumeration flags, return all messages in inbox */
  6518.      more    = ''                       /* Set the value of more to nul */
  6519.      action  = 'N'                      /* Set the value of repeat loop indicator to N */
  6520.  
  6521.      AttrDesc.0 = 2                          /* Retrieve 2 attributes for each message */
  6522.      AttrDesc.1.Selector = 'VIMSEL_REF'      /* 1st attribute is the message reference number */
  6523.      AttrDesc.1.Buffer   = 'MsgRefNo'        /* store results in this stem variable */
  6524.      AttrDesc.2.Selector = 'VIMSEL_SUBJECT'  /* 2nd attribute is the message subject */
  6525.      AttrDesc.2.Buffer   = 'Subject'         /* store results in this stem variable */
  6526.  
  6527.      do until TRANSLATE(SUBSTR(action,1,1)) = 'X'
  6528.  
  6529.           /* Continue retrieving message info until user enters N */
  6530.  
  6531.           rc = RxVIMEnumerateMessages(Inbox,'pos',skipcnt,'AttrDesc','mcount',filter,fdata,flags,'more')
  6532.           if (rc > 0) then call vimerr
  6533.  
  6534.           /* Display results */
  6535.          'cls'
  6536.           Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  6537.           Say
  6538.           Say 'Message Container Demo'
  6539.           Say
  6540.           Say '-----------------------------------------------------------'
  6541.           Say '    Message =' MsgRefNo.1
  6542.           Say '    Subject =' Subject.1
  6543.           Say '-----------------------------------------------------------'
  6544.           Say
  6545.           Say
  6546.           Say 'Select an action for this message'
  6547.           Say
  6548.           Say '   D - Delete message'
  6549.           Say '   F - File message in a folder'
  6550.           Say '   N - Go to next message, leave this one in the Inbox'
  6551.           Say '   X - Exit demo now'
  6552.           Say
  6553.           Say 'Enter your selection below -'
  6554.           PULL action
  6555.           if more = 'False' then do
  6556.              Say 'All messages have been retrieved'
  6557.              action = 'X'
  6558.           end  /* Do */
  6559.  
  6560.           /* Process the selection entered.  X will fall through the select statement */
  6561.           select
  6562.              when TRANSLATE(SUBSTR(action,1,1)) = 'D' then do
  6563.                 /* Delete message */
  6564.                 rc = RxVIMRemoveMessage(Inbox,MsgRefNo.1)
  6565.                 if (rc > 0) then call vimerr
  6566.            end  /* Do */
  6567.              when TRANSLATE(SUBSTR(action,1,1)) = 'F' then do
  6568.                 /* File message in folder */
  6569.                 Say 'Enter the name of the folder -'
  6570.                 PULL category
  6571.                  rc = RxVIMSetMessageCategory(Inbox,MsgRefNo.1,category)
  6572.                 if (rc > 0) then call vimerr
  6573.              end  /* Do */
  6574.              when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
  6575.                 /* Go to the next message */
  6576.                 /* Nothing to do.....loop will pull next message */
  6577.              end  /* Do */
  6578.           otherwise
  6579.           end  /* select */
  6580.      end /* do */
  6581. end  /* Do */
  6582.  
  6583.  
  6584. /* Close the message container -- Inbox */
  6585. rc = RxVIMCloseMessageContainer(Inbox)
  6586. if (rc > 0) then call vimerr
  6587.  
  6588.  
  6589. /* Close the session with the postoffice */
  6590. rc = RxVIMCloseSession(Session)
  6591. if (rc > 0) then call vimerr
  6592.  
  6593.  
  6594. /* Terminate the active VIM subsystem connection */
  6595. rc = RxVIMTerminate()
  6596. if (rc > 0) then call vimerr
  6597. signal done
  6598.  
  6599.  
  6600. /***** VIMErr *******/
  6601.  
  6602. /* If an error occurs, this function will return the text */
  6603. /* associated with the error.  Extended text may be       */
  6604. /* displayed if it exists for the specified error.        */
  6605.  
  6606. VIMERR:
  6607.  
  6608. erc = RxVIMStatusText(Session,rc,'Status')
  6609. Say
  6610. Say '|-Error Information -----------------|'
  6611. Say '  Error Text -' status.1
  6612. Say
  6613. Say '  Ext Status -' status.2
  6614. rc = RxVIMTerminate()
  6615. signal done
  6616.  
  6617.  
  6618. /* The done section will unload the RexxVIM extensions */
  6619. /* and exit the program                                */
  6620. DONE:
  6621. /*** Drop all of the external functions ***/
  6622. call RxVIMDropFuncs
  6623. Say '|------------------------------------|'
  6624. Say 'Demo Complete.  All functions released'
  6625. 'pause'
  6626. exit
  6627.  
  6628.  
  6629. ΓòÉΓòÉΓòÉ 11.5. Message Access Demo ΓòÉΓòÉΓòÉ
  6630.  
  6631. The Message Access (MSGACTS.CMD) demo shows how RexxVIM can be used to open and 
  6632. read messages.  Launching the demo below will actions to be performed on the 
  6633. messages in the Inbox. 
  6634.  
  6635. The MSGACTS.CMD is located with the rest of the RexxVIM product files, or can 
  6636. be created from the listing section by copying it to a file.  If it is copied 
  6637. to a file, some modification may be required prior to executing the command 
  6638. file.  Normally, one space must be removed from the first line of the command 
  6639. file to instruct OS/2 that the file is a valid Rexx program. 
  6640.  
  6641.  
  6642. ΓòÉΓòÉΓòÉ 11.5.1. MSGACTS.CMD Listing ΓòÉΓòÉΓòÉ
  6643.  
  6644. /** Msgacts.cmd **/
  6645. /*-------------------------------------------*/
  6646. /*                                           */
  6647. /* Command line syntax:                      */
  6648. /*                                           */
  6649. /* msgacts db_path user_password user_name   */
  6650. /*                                           */
  6651. /*                                           */
  6652. /*-------------------------------------------*/
  6653. ARG db_path user_pw user_name
  6654. '@echo off'
  6655. '@cls'
  6656. Say 'RexxVIM Message Access Demonstration Program'
  6657. Say
  6658.  
  6659. /* Unload the function upon error */
  6660. SIGNAL ON ERROR NAME done
  6661.  
  6662. /* Prompt for the parameters if not passed on the */
  6663. /* command line                                   */
  6664. if LENGTH(STRIP(db_path)) = 0 then do
  6665.    Say 'Enter Postoffice Directory -'
  6666.    PARSE PULL db_path .
  6667.    Say
  6668.    Say 'Enter User Name -'
  6669.    PARSE PULL user_name
  6670.    Say 'Enter Password -'
  6671.    PARSE PULL user_pw
  6672. end  /* Do */
  6673.  
  6674.  
  6675. /* Load the RexxVIM extensions to Rexx */
  6676. rc = RxFuncAdd('RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs')
  6677. if rc <> 0 then do
  6678.    Say
  6679.    Say 'RexxVIM failed to load, return code' rc
  6680.    Say
  6681.    Say 'Functions have been released.  Retry program.'
  6682.    signal done
  6683. end  /* Do */
  6684. call RxVIMLoadFuncs
  6685. Say 'Functions are now loaded'
  6686. Say
  6687.  
  6688.  
  6689. /* Initialize the VIM subsystem */
  6690. rc = RxVIMInitialize()
  6691. if (rc > 0) then call vimerr
  6692.  
  6693.  
  6694. /* Open a session with the postoffice using the parameters */
  6695. /* provided by the user                                    */
  6696. rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
  6697. if (rc > 0) then call vimerr
  6698.  
  6699.  
  6700. /* Open the default message container -- Inbox */
  6701. rc = RxVIMOpenMessageContainer(Session,'','Inbox')
  6702. if (rc > 0) then call vimerr
  6703.  
  6704.  
  6705. /* Display all messages in Inbox if they exist */
  6706.  
  6707.      /* Enumerate messages in container -- Inbox */
  6708.      pos = ''                           /* Start at the beginning of the container */
  6709.      skipcnt = 1               /* Move forward through the container one at a time */
  6710.      mcount  = 1                        /* Retrieve 1 message for each call */
  6711.      filter  = 'VIMSEL_NO_FILTER'       /* No filter, return all messages in inbox */
  6712.      fdata   = ''                       /* No filter data */
  6713.      flags   = 'VIM_NO_FLAGS'    /* No enumeration flags, return all messages in inbox */
  6714.      more    = ''                       /* Set the value of more to nul */
  6715.      action  = 'N'                      /* Set the value of repeat loop indicator to N */
  6716.  
  6717.      AttrDesc.0 = 3                     /* Retrieve 3 attributes for each message */
  6718.      AttrDesc.1.Selector = 'VIMSEL_REF' /* 1st attribute the message reference number */
  6719.      AttrDesc.1.Buffer   = 'MsgRefNo'   /* store results in this stem variable */
  6720.      AttrDesc.2.Selector = 'VIMSEL_SUBJECT'  /* 2nd attribute is the message subject */
  6721.      AttrDesc.2.Buffer   = 'Subject'         /* store results in this stem variable */
  6722.      AttrDesc.3.Selector = 'VIMSEL_UNREAD_MAIL'   /* 3rd attribute is if unread */
  6723.      AttrDesc.3.Buffer   = 'Unread'           /* store results in this stem variable */
  6724.  
  6725.      do until TRANSLATE(SUBSTR(action,1,1)) = 'X'
  6726.  
  6727.           /* Continue retrieving message info until user enters N */
  6728.  
  6729.           rc = RxVIMEnumerateMessages(Inbox,'pos',skipcnt,'AttrDesc','mcount',,
  6730.                                       filter,fdata,flags,'more')
  6731.           if (rc > 0) then call vimerr
  6732.  
  6733.           /* Display results */
  6734.          'cls'
  6735.           Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  6736.           Say
  6737.           Say 'Message Container Demo'
  6738.           Say
  6739.           Say '--------------------------------------------------------'
  6740.           Say '    Message =' MsgRefNo.1
  6741.           Say '    Subject =' Subject.1
  6742.           Say '    Unread  =' Unread.1
  6743.           Say '--------------------------------------------------------'
  6744.           Say
  6745.           Say 'Select an action for this message'
  6746.           Say
  6747.           Say '   D - Delete message'
  6748.           Say '   F - File message in a folder'
  6749.           Say '   N - Go to next message, leave this one in the Inbox'
  6750.           Say '   M - Mark message as read'
  6751.           Say '   H - Display message header info'
  6752.           Say '   I - Display message items'
  6753.           Say '   T - Display the first 60 characters of first message item'
  6754.           Say '   X - Exit demo now'
  6755.           Say
  6756.           Say 'Enter your selection below -'
  6757.           PULL action
  6758.  
  6759.           /* Process the selection entered.  X will fall through the select statement */
  6760.           select
  6761.              when TRANSLATE(SUBSTR(action,1,1)) = 'D' then do
  6762.                 /* Delete message */
  6763.                 rc = RxVIMRemoveMessage(Inbox,MsgRefNo.1)
  6764.                 if (rc > 0) then call vimerr
  6765.            end  /* Do */
  6766.              when TRANSLATE(SUBSTR(action,1,1)) = 'F' then do
  6767.                 /* File message in folder */
  6768.                 Say 'Enter the name of the folder-'
  6769.                 PULL category
  6770.                  rc = RxVIMSetMessageCategory(Inbox,MsgRefNo.1,category)
  6771.                 if (rc > 0) then call vimerr
  6772.              end  /* Do */
  6773.              when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
  6774.                 /* Go to the next message */
  6775.                 /* Nothing to do.....loop will pull next message */
  6776.              end  /* Do */
  6777.              when TRANSLATE(SUBSTR(action,1,1)) = 'M' then do
  6778.                 /* Open message */
  6779.                 rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
  6780.                 if (rc > 0) then call vimerr
  6781.  
  6782.                 /* Mark the message as read */
  6783.                 rc = RxVIMMarkMessageAsRead(Inbox,MsgRefNo.1)
  6784.                 if (rc > 0) then call vimerr
  6785.  
  6786.                 /* Close the message */
  6787.                 rc = RxVIMCloseMessage(MsgHandle)
  6788.                 if (rc > 0) then call vimerr
  6789.              end  /* Do */
  6790.              when TRANSLATE(SUBSTR(action,1,1)) = 'H' then do
  6791.                 /* Open message */
  6792.                 rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
  6793.                 if (rc > 0) then call vimerr
  6794.  
  6795.                 /* Get the message header info */
  6796.                 attrDesc.0 = 2
  6797.                 attrDesc.1.Selector = 'VIMSEL_FROM_NAME'
  6798.                 attrDesc.1.Buffer   = 'from'
  6799.                 attrDesc.2.Selector = 'VIMSEL_PRIORITY'
  6800.                 attrDesc.2.Buffer   = 'priority'
  6801.  
  6802.                 rc = RxVIMGetMessageHeader(MsgHandle,'attrDesc')
  6803.                 if (rc > 0) then call vimerr
  6804.                 Say '--------------------------------------------------------'
  6805.                 Say '    Message Sent by -' from
  6806.                 Say '    Message Priority-' priority
  6807.                 Say '--------------------------------------------------------'
  6808.                 'pause'
  6809.                 /* Close the message */
  6810.                 rc = RxVIMCloseMessage(MsgHandle)
  6811.                 if (rc > 0) then call vimerr
  6812.              end  /* Do */
  6813.              when TRANSLATE(SUBSTR(action,1,1)) = 'I' then do
  6814.                 /* Open message */
  6815.                 rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
  6816.                 if (rc > 0) then call vimerr
  6817.  
  6818.                 /* Retrieve all of the items for this message */
  6819.                 ipos      = ''
  6820.                 icount   = 20
  6821.                 imore    = ''
  6822.                 ItemDesc = ''
  6823.                 ifilter   = 'VIMSEL_NO_FILTER'
  6824.                 ifdata    = ''
  6825.  
  6826.                 rc = RxVIMEnumerateMessageItems(MsgHandle,'ipos',1,'icount','ItemDesc',,
  6827.                                                 ifilter,ifdata,'imore')
  6828.                 if (rc > 0) then call vimerr
  6829.  
  6830.                 'cls'
  6831.                 Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  6832.                 Say
  6833.                 Say ' Message Information with Item Detail'
  6834.                 Say '--------------------------------------------------------'
  6835.                 Say '    Message =' MsgRefNo.1
  6836.                 Say '    Subject =' Subject.1
  6837.                 Say '    Unread  =' Unread.1
  6838.                 Say '--------------------------------------------------------'
  6839.  
  6840.                 loopcnt = 1
  6841.                 do while (loopcnt <= icount)
  6842.                    /* Display each item descriptor entry */
  6843.                    Say '    Item Class  -' ItemDesc.loopcnt.CLASS
  6844.                    Say '    Item Type   -' ItemDesc.loopcnt.TYPE
  6845.                    Say '    Item Name   -' ItemDesc.loopcnt.NAME
  6846.                    Say '    Item Size   -' ItemDesc.loopcnt.SIZE
  6847.                    Say '    Item Ref No -' ItemDesc.loopcnt.REF
  6848.                    Say '--------------------------------------------------------'
  6849.  
  6850.                    loopcnt = loopcnt + 1
  6851.                 end /* do */
  6852.                 'pause'
  6853.                 /* Close the message */
  6854.                 rc = RxVIMCloseMessage(MsgHandle)
  6855.                 if (rc > 0) then call vimerr
  6856.              end  /* Do */
  6857.              when TRANSLATE(SUBSTR(action,1,1)) = 'T' then do
  6858.                 /* Open message */
  6859.                 rc = RxVIMOpenMessage(Inbox,MsgRefNo.1,'','MsgHandle')
  6860.                 if (rc > 0) then call vimerr
  6861.  
  6862.                 /* Retrieve all of the items for this message */
  6863.                 ipos      = ''
  6864.                 icount    = 20
  6865.                 imore     = ''
  6866.                 ItemDesc  = ''
  6867.                 ifilter   = 'VIMSEL_CLASS'        /* Filter on item class */
  6868.                 ifdata    = 'VIMSEL_NOTE_PART'    /* Retrieve only text items */
  6869.  
  6870.                 rc = RxVIMEnumerateMessageItems(MsgHandle,'ipos',1,'icount','ItemDesc',,
  6871.                                                 ifilter,ifdata,'imore')
  6872.                 if (rc > 0) then call vimerr
  6873.                 /* Retrieve the text for the first message item */
  6874.                 tconvert          = 'VIM_TEXT'         /* Use text conversion   */
  6875.                 tflags            = ''                 /* No conversion flags   */
  6876.                 BufDesc.Buffer    = 'ItemText'         /* Return buffer name    */
  6877.                 BufDesc.Size      = 256                /* Size of return buffer */
  6878.                 BufDesc.FileName  = ''
  6879.  
  6880.                 rc = RxVIMGetMessageItem(MsgHandle,ItemDesc.1.REF,tconvert,,
  6881.                                          tflags,'BufDesc')
  6882.                 if (rc > 0) then call vimerr
  6883.  
  6884.                 'cls'
  6885.                 Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  6886.                 Say
  6887.                 Say ' Message Information with Item Detail'
  6888.                 Say '--------------------------------------------------------'
  6889.                 Say '    Message =' MsgRefNo.1
  6890.                 Say '    Subject =' Subject.1
  6891.                 Say '    Unread  =' Unread.1
  6892.                 Say '--------------------------------------------------------'
  6893.  
  6894.                 /* Display each item descriptor entry */
  6895.                 Say '    Item Class  -' ItemDesc.1.CLASS
  6896.                 Say '    Item Type   -' ItemDesc.1.TYPE
  6897.                 Say '    Item Name   -' ItemDesc.1.NAME
  6898.                 Say '    Item Size   -' ItemDesc.1.SIZE
  6899.                 Say '    Item Ref No -' ItemDesc.1.REF
  6900.                 Say '--------------------------------------------------------'
  6901.                 Say ' Message Contents for first item (max 60 characters) -'
  6902.                 Say
  6903.                 Say SUBSTR(ItemText,1,60)
  6904.                 Say '--------------------------------------------------------'
  6905.                 'pause'
  6906.                 /* Close the message */
  6907.                 rc = RxVIMCloseMessage(MsgHandle)
  6908.                 if (rc > 0) then call vimerr
  6909.              end  /* Do */
  6910.           otherwise
  6911.           end  /* select */
  6912.  
  6913.           /* End the loop if no more messages to retrieve */
  6914.           if more = 'False' then do
  6915.              Say 'All messages have been retrieved'
  6916.              action = 'X'
  6917.           end  /* Do */
  6918.  
  6919.      end /* do */
  6920.  
  6921.  
  6922. /* Close the message container -- Inbox */
  6923. rc = RxVIMCloseMessageContainer(Inbox)
  6924. if (rc > 0) then call vimerr
  6925.  
  6926.  
  6927. /* Close the session with the postoffice */
  6928. rc = RxVIMCloseSession(Session)
  6929. if (rc > 0) then call vimerr
  6930.  
  6931.  
  6932. /* Terminate the active VIM subsystem connection */
  6933. rc = RxVIMTerminate()
  6934. if (rc > 0) then call vimerr
  6935. signal done
  6936.  
  6937.  
  6938. /***** VIMErr *******/
  6939.  
  6940. /* If an error occurs, this function will return the text */
  6941. /* associated with the error.  Extended text may be       */
  6942. /* displayed if it exists for the specified error.        */
  6943.  
  6944. VIMERR:
  6945.  
  6946. erc = RxVIMStatusText(Session,rc,'Status')
  6947. Say
  6948. Say '|-Error Information ------------------------------------|'
  6949. Say '  Error Text -' status.1
  6950. Say
  6951. Say '  Ext Status -' status.2
  6952. rc = RxVIMTerminate()
  6953. signal done
  6954.  
  6955.  
  6956. /* The done section will unload the RexxVIM extensions */
  6957. /* and exit the program                                */
  6958. DONE:
  6959. /*** Drop all of the external functions ***/
  6960. call RxVIMDropFuncs
  6961. Say '|-------------------------------------------------------|'
  6962. Say 'Demo Complete.  All functions released'
  6963. 'pause'
  6964. exit
  6965.  
  6966.  
  6967. ΓòÉΓòÉΓòÉ 11.6. Address Book Demo ΓòÉΓòÉΓòÉ
  6968.  
  6969. The Address Book (ADDRBOOK.CMD) demo shows how RexxVIM can be used to open and 
  6970. read address books, like the primary directory.  Launching the demo below will 
  6971. allow each address book to be accessed and displayed. 
  6972.  
  6973. The ADDRBOOK.CMD is located with the rest of the RexxVIM product files, or can 
  6974. be created from the listing section in the online documentation by copying it 
  6975. to a file.  If it is copied to a file, some modification may be required prior 
  6976. to executing the command file.  Normally, one space must be removed from the 
  6977. first line of the command file to instruct OS/2 that the file is a valid Rexx 
  6978. program. 
  6979.  
  6980.  
  6981. ΓòÉΓòÉΓòÉ 11.6.1. ADDRBOOK.CMD Listing ΓòÉΓòÉΓòÉ
  6982.  
  6983. /** AddrBook.cmd **/
  6984. /*--------------------------------------------*/
  6985. /*                                            */
  6986. /* Command line syntax:                       */
  6987. /*                                            */
  6988. /* AddrBook db_path user_password user_name   */
  6989. /*                                            */
  6990. /*                                            */
  6991. /*--------------------------------------------*/
  6992. ARG db_path user_pw user_name
  6993. '@echo off'
  6994. '@cls'
  6995. Say 'RexxVIM Address Book Demonstration Program'
  6996. Say
  6997.  
  6998. /* Unload the function upon error */
  6999. SIGNAL ON ERROR NAME done
  7000.  
  7001. /* Prompt for the parameters if not passed on the */
  7002. /* command line                                   */
  7003. if LENGTH(STRIP(db_path)) = 0 then do
  7004.    Say 'Enter Postoffice Directory -'
  7005.    PARSE PULL db_path .
  7006.    Say
  7007.    Say 'Enter User Name -'
  7008.    PARSE PULL user_name
  7009.    Say 'Enter Password -'
  7010.    PARSE PULL user_pw
  7011. end  /* Do */
  7012.  
  7013.  
  7014. /* Load the RexxVIM extensions to Rexx */
  7015. rc = RxFuncAdd('RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs')
  7016. if rc <> 0 then do
  7017.    Say
  7018.    Say 'RexxVIM failed to load, return code' rc
  7019.    Say
  7020.    Say 'Functions have been released.  Retry program.'
  7021.    signal done
  7022. end  /* Do */
  7023. call RxVIMLoadFuncs
  7024. Say 'Functions are now loaded'
  7025. Say
  7026.  
  7027.  
  7028. /* Initialize the VIM subsystem */
  7029. rc = RxVIMInitialize()
  7030. if (rc > 0) then call vimerr
  7031.  
  7032. /* Open a session with the postoffice using the parameters */
  7033. /* provided by the user                                    */
  7034. rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
  7035. if (rc > 0) then call vimerr
  7036.  
  7037.  
  7038.      /* Enumerate the addressbooks */
  7039.      pos = ''                           /* Start at the beginning */
  7040.      skipcnt = 1                        /* Move forward one at a time */
  7041.      acount  = 1                        /* Retrieve 1 addressbook for each call */
  7042.      more    = ''                       /* Set the value of more to nul */
  7043.      action  = 'N'                      /* Set the value of repeat loop indicator to N */
  7044.  
  7045.      AttrDesc.0 = 2                     /* Retrieve 2 attributes for each addressbook */
  7046.      AttrDesc.1.Selector = 'VIMSEL_NAME'     /* 1st attribute is the addressbook name */
  7047.      AttrDesc.1.Buffer   = 'AddrName'          /* store results in this stem variable */
  7048.      AttrDesc.2.Selector = 'VIMSEL_TOTAL_ENTRIES'   /* 2nd attribute is total entries */
  7049.      AttrDesc.2.Buffer   = 'AddrTotal'         /* store results in this stem variable */
  7050.  
  7051.      do until TRANSLATE(SUBSTR(action,1,1)) = 'X'
  7052.  
  7053.           /* Continue retrieving addressbook info until user enters N */
  7054.  
  7055.           rc = RxVIMEnumerateAddressBooks(Session,'pos',skipcnt,'AttrDesc',,
  7056.                                           'acount','more')
  7057.           if (rc > 0) then call vimerr
  7058.  
  7059.           /* Display results */
  7060.          'cls'
  7061.           Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  7062.           Say
  7063.           Say 'Address Book Demo'
  7064.           Say
  7065.           Say '--------------------------------------------------------'
  7066.           Say '    Address Book Name =' AddrName.1
  7067.           Say '    Total Entries     =' AddrTotal.1
  7068.           Say '--------------------------------------------------------'
  7069.           Say
  7070.           Say
  7071.           Say 'Select an action for this message'
  7072.           Say
  7073.           Say '   N - Go to next Address Book'
  7074.           Say '   D - Display each of the Address Book entries'
  7075.           Say '   G - Get the current subtree name'
  7076.           Say '   X - Exit demo now'
  7077.           Say
  7078.           Say 'Enter your selection below-'
  7079.           PULL action
  7080.  
  7081.           /* Process the selection entered.  X will fall through the select statement */
  7082.           select
  7083.              when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
  7084.                 /* Go to the next address book */
  7085.                 /* Nothing to do.....loop will pull next address book */
  7086.              end  /* Do */
  7087.              when TRANSLATE(SUBSTR(action,1,1)) = 'G' then do
  7088.  
  7089.                 /* Open the current address book */
  7090.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7091.                 if (rc > 0) then call vimerr
  7092.  
  7093.                 /* Get the subtree of the address book */
  7094.                 Subtree = ''
  7095.                 SubRefNo = ''
  7096.  
  7097.                 rc = RxVIMGetCurrentSubtree(AddrBkPtr,'SubRefNo','Subtree')
  7098.                 if (rc > 0) then call vimerr
  7099.  
  7100.                 /* Close the  address book */
  7101.                 rc = RxVIMCloseAddressBook(AddrBkPtr)
  7102.                 if (rc > 0) then call vimerr
  7103.  
  7104.                 Say '--------------------------------------------------------'
  7105.                 Say '    Current Subtree  =' Subtree
  7106.                 Say '--------------------------------------------------------'
  7107.                 'pause'
  7108.  
  7109.              end  /* Do */
  7110.              when TRANSLATE(SUBSTR(action,1,1)) = 'D' then do
  7111.  
  7112.                 /* Open the current address book */
  7113.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7114.                 if (rc > 0) then call vimerr
  7115.  
  7116.                 /* Enumerate the addressbook entries */
  7117.                 epos = ''                           /* Start at the beginning */
  7118.                 eskipcnt = 1                        /* Move forward one at a time */
  7119.                 eacount  = 1              /* Retrieve 1 addressbook for each call */
  7120.                 efilter  = 'VIMSEL_NO_FILTER'       /* no filtering */
  7121.                 efdata   = ''      /* no filter data */
  7122.                 emore    = ''      /* Set the value of more to nul */
  7123.                 eaction  = 'N'     /* Set the value of repeat loop indicator to N */
  7124.  
  7125.                 ItemDesc.0 = 3     /* Retrieve 3 attributes for each entry */
  7126.                 ItemDesc.1.Selector = 'VIMSEL_REF' /* 1st attribute  reference number */
  7127.                 ItemDesc.1.Buffer   = 'ABE_Ref'     /* store results in stem variable */
  7128.                 ItemDesc.2.Selector = 'VIMSEL_NAME'    /* 2nd attribute is entry name */
  7129.                 ItemDesc.2.Buffer   = 'ABE_Name'    /* store results in stem variable */
  7130.                 ItemDesc.3.Selector = 'VIMSEL_ADDRESS' /* 3rd attribute entry address */
  7131.                 ItemDesc.3.Buffer   = 'ABE_Address' /* store results in stem variable */
  7132.  
  7133.                 do until TRANSLATE(SUBSTR(eaction,1,1)) = 'X'
  7134.  
  7135.                      /* Continue retrieving addressbook info until user enters X */
  7136.  
  7137.                      rc = RxVIMEnumerateAddressBookEntries(AddrBkPtr,'epos',eskipcnt,,
  7138.                                            'ItemDesc','eacount',efilter,efdata,'emore')
  7139.                      if (rc > 0) then call vimerr
  7140.  
  7141.                      /* Display results */
  7142.                     'cls'
  7143.                      Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  7144.                      Say
  7145.                      Say 'Address Book Demo with entry information'
  7146.                      Say
  7147.                      Say '--------------------------------------------------------'
  7148.                      Say '    Address Book Name =' AddrName.1
  7149.                      Say '    Total Entries     =' AddrTotal.1
  7150.                      Say '--------------------------------------------------------'
  7151.                      Say '    Name =   ' ABE_Name.1
  7152.                      Say '    Address =' ABE_Address.1
  7153.                      Say '    Ref No  =' ABE_Ref.1
  7154.                      Say '--------------------------------------------------------'
  7155.                      Say
  7156.                      Say
  7157.                      Say 'Select an action for this message'
  7158.                      Say
  7159.                      Say '   N - Go to next Address Book entry'
  7160.                      Say '   X - Exit to the main screen'
  7161.                      Say
  7162.                      Say 'Enter your selection below-'
  7163.                      PULL eaction
  7164.  
  7165.                      select
  7166.                         when TRANSLATE(SUBSTR(eaction,1,1)) = 'N' then do
  7167.                            /* Go to the next address book entry */
  7168.                            /* Nothing to do.....will loop to the next entry */
  7169.                         end  /* Do */
  7170.                      otherwise
  7171.                      end  /* select */
  7172.  
  7173.                      /* End the loop if no more entries */
  7174.                      if emore = 'False' then do
  7175.                         Say 'All entries for this address book have been retrieved'
  7176.                         eaction = 'X'
  7177.                      end  /* Do */
  7178.  
  7179.                 end /* Do */
  7180.  
  7181.                 /* Close the  address book */
  7182.                 rc = RxVIMCloseAddressBook(AddrBkPtr)
  7183.                 if (rc > 0) then call vimerr
  7184.  
  7185.              end  /* Do */
  7186.           otherwise
  7187.           end  /* select */
  7188.  
  7189.           if more = 'False' then do
  7190.              Say 'All Address Books have been retrieved'
  7191.              action = 'X'
  7192.           end  /* Do */
  7193.  
  7194.      end /* do */
  7195.  
  7196. /* Close the session with the postoffice */
  7197. rc = RxVIMCloseSession(Session)
  7198. if (rc > 0) then call vimerr
  7199.  
  7200.  
  7201. /* Terminate the active VIM subsystem connection */
  7202. rc = RxVIMTerminate()
  7203. if (rc > 0) then call vimerr
  7204. signal done
  7205.  
  7206.  
  7207. /***** VIMErr *******/
  7208.  
  7209. /* If an error occurs, this function will return the text */
  7210. /* associated with the error.  Extended text may be       */
  7211. /* displayed if it exists for the specified error.        */
  7212.  
  7213. VIMERR:
  7214.  
  7215. erc = RxVIMStatusText(Session,rc,'Status')
  7216. Say
  7217. Say '|-Error Information ------------------------------------|'
  7218. Say '  Error Text -' status.1
  7219. Say
  7220. Say '  Ext Status -' status.2
  7221. rc = RxVIMTerminate()
  7222. signal done
  7223.  
  7224.  
  7225. /* The done section will unload the RexxVIM extensions */
  7226. /* and exit the program                                */
  7227. DONE:
  7228. /*** Drop all of the external functions ***/
  7229. call RxVIMDropFuncs
  7230. Say '|-------------------------------------------------------|'
  7231. Say 'Demo Complete.  All functions released'
  7232. 'pause'
  7233. exit
  7234.  
  7235.  
  7236. ΓòÉΓòÉΓòÉ 11.7. Address Book Entries Demo ΓòÉΓòÉΓòÉ
  7237.  
  7238. The Address Book Entries (ABEDEMO.CMD) demo shows how RexxVIM can be used to 
  7239. open and read addressbook entries.  Launching the demo below will allow 
  7240. individual entries in the address books to be reviewed, added, changed and 
  7241. removed. 
  7242.  
  7243. The ABEDEMO.CMD is located with the rest of the RexxVIM product files, or can 
  7244. be created from the listing section in the online documentation by copying it 
  7245. to a file.  If it is copied to a file, some modification may be required prior 
  7246. to executing the command file.  Normally, one space must be removed from the 
  7247. first line of the command file to instruct OS/2 that the file is a valid Rexx 
  7248. program. 
  7249.  
  7250.  
  7251. ΓòÉΓòÉΓòÉ 11.7.1. ABEDEMO.CMD Listing ΓòÉΓòÉΓòÉ
  7252.  
  7253. /** ABEDemo.cmd **/
  7254. /*--------------------------------------------*/
  7255. /*                                            */
  7256. /* Command line syntax:                       */
  7257. /*                                            */
  7258. /* ABEDemo  db_path user_password user_name   */
  7259. /*                                            */
  7260. /*                                            */
  7261. /*--------------------------------------------*/
  7262. ARG db_path user_pw user_name
  7263. '@echo off'
  7264. '@cls'
  7265. Say 'RexxVIM Address Book Entry Demonstration Program'
  7266. Say
  7267.  
  7268. /* Unload the function upon error */
  7269. SIGNAL ON ERROR NAME done
  7270.  
  7271. /* Prompt for the parameters if not passed on the */
  7272. /* command line                                   */
  7273. if LENGTH(STRIP(db_path)) = 0 then do
  7274.    Say 'Enter Postoffice Directory -'
  7275.    PARSE PULL db_path .
  7276.    Say
  7277.    Say 'Enter User Name -'
  7278.    PARSE PULL user_name
  7279.    Say 'Enter Password -'
  7280.    PARSE PULL user_pw
  7281. end  /* Do */
  7282.  
  7283.  
  7284. /* Load the RexxVIM extensions to Rexx */
  7285. rc = RxFuncAdd('RxVIMLoadFuncs', 'RexxVIM', 'RxVIMLoadFuncs')
  7286. if rc <> 0 then do
  7287.    Say
  7288.    Say 'RexxVIM failed to load, return code' rc
  7289.    Say
  7290.    Say 'Functions have been released.  Retry program.'
  7291.    signal done
  7292. end  /* Do */
  7293. call RxVIMLoadFuncs
  7294. Say 'Functions are now loaded'
  7295. Say
  7296.  
  7297.  
  7298. /* Initialize the VIM subsystem */
  7299. rc = RxVIMInitialize()
  7300. if (rc > 0) then call vimerr
  7301.  
  7302. /* Open a session with the postoffice using the parameters */
  7303. /* provided by the user                                    */
  7304. rc = RxVIMOpenSession(db_path,user_name,user_pw,Session)
  7305. if (rc > 0) then call vimerr
  7306.  
  7307.  
  7308.      /* Enumerate the addressbooks */
  7309.      pos = ''                           /* Start at the beginning */
  7310.      skipcnt = 1                        /* Move forward one at a time */
  7311.      acount  = 1                        /* Retrieve 1 addressbook for each call */
  7312.      more    = ''                       /* Set the value of more to nul */
  7313.      action  = 'N'                      /* Set the value of repeat loop indicator to N */
  7314.  
  7315.      AttrDesc.0 = 2                     /* Retrieve 2 attributes for each addressbook */
  7316.      AttrDesc.1.Selector = 'VIMSEL_NAME'     /* 1st attribute is the addressbook name */
  7317.      AttrDesc.1.Buffer   = 'AddrName'          /* store results in this stem variable */
  7318.      AttrDesc.2.Selector = 'VIMSEL_TOTAL_ENTRIES'   /* 2nd attribute is total entries */
  7319.      AttrDesc.2.Buffer   = 'AddrTotal'         /* store results in this stem variable */
  7320.  
  7321.      /* Continue retrieving addressbook info until user enters X */
  7322.  
  7323.      rc = RxVIMEnumerateAddressBooks(Session,'pos',skipcnt,'AttrDesc','acount','more')
  7324.      if (rc > 0) then call vimerr
  7325.  
  7326.      do until TRANSLATE(SUBSTR(action,1,1)) = 'X'
  7327.  
  7328.           /* Display results */
  7329.          'cls'
  7330.           Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  7331.           Say
  7332.           Say 'Address Book Demo'
  7333.           Say
  7334.           Say '--------------------------------------------------------'
  7335.           Say '    Address Book Name =' AddrName.1
  7336.           Say '    Total Entries     =' AddrTotal.1
  7337.           Say '--------------------------------------------------------'
  7338.           Say
  7339.           Say
  7340.           Say 'Select an action for this message'
  7341.           Say
  7342.           Say '   N - Go to next Address Book'
  7343.           Say '   C - Create a new entry'
  7344.           Say '   S - Search for an entry'
  7345.           Say '   L - Change the location of an entry'
  7346.           Say '   F - Create a new group'
  7347.           Say '   G - Display all members of a group'
  7348.           Say '   X - Exit demo now'
  7349.           Say
  7350.           Say 'Enter your selection below-'
  7351.           PULL action
  7352.  
  7353.           /* Process the selection entered.  X will fall through the select statement */
  7354.           select
  7355.              when TRANSLATE(SUBSTR(action,1,1)) = 'N' then do
  7356.                 /* Go to the next address book */
  7357.  
  7358.                 rc = RxVIMEnumerateAddressBooks(Session,'pos',skipcnt,'AttrDesc',,
  7359.                                                 'acount','more')
  7360.                 if (rc > 0) then call vimerr
  7361.  
  7362.              end  /* Do */
  7363.              when TRANSLATE(SUBSTR(action,1,1)) = 'C' then do
  7364.                 /* Create a new entry in this address book */
  7365.  
  7366.                 Say '--------------------------------------------------------'
  7367.                 Say 'Enter the name'
  7368.                 Pull ename
  7369.                 Say 'Enter a comment'
  7370.                 Pull ecomment
  7371.                 Say
  7372.                 Say 'Adding' ename 'to the addressbook'
  7373.                 Say '--------------------------------------------------------'
  7374.  
  7375.                 /* Open the addressbook */
  7376.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7377.                 if (rc > 0) then call vimerr
  7378.  
  7379.                 /* Create the description stem for the create */
  7380.                 attrItem.0 = 3
  7381.                 attrItem.1.Selector = 'VIMSEL_NAME'
  7382.                 attrItem.1.Value    = ename
  7383.                 attrItem.2.Selector = 'VIMSEL_COMMENTS'
  7384.                 attrItem.2.Value    = ecomment
  7385.                 attrItem.3.Selector = 'VIMSEL_LOCATION'
  7386.                 attrItem.3.Value    = 'VIMSEL_REMOTE'
  7387.  
  7388.                 /* Add the entry to the address book */
  7389.                 rc = RxVIMCreateAddressBookEntry(AddrBkPtr,'VIMSEL_ENTITY','attrItem')
  7390.                 if (rc > 0) then call vimerr
  7391.  
  7392.                 /* Close the address book */
  7393.                 rc = RxVIMCloseAddressBook(addrBkPtr)
  7394.                 if (rc > 0) then call vimerr
  7395.  
  7396.              end  /* Do */
  7397.              when TRANSLATE(SUBSTR(action,1,1)) = 'S' then do
  7398.                 /* Search for an entry in this address book */
  7399.  
  7400.                 Say '--------------------------------------------------------'
  7401.                 Say 'Enter the name for the search'
  7402.                 Pull ename
  7403.                 Say
  7404.                 Say 'Searching for' ename 'in the addressbook'
  7405.  
  7406.                 /* Open the addressbook */
  7407.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7408.                 if (rc > 0) then call vimerr
  7409.  
  7410.                 /* Create the description stem for the create */
  7411.                 searchon = 'VIMSEL_NAME'
  7412.                 epos     = ''
  7413.                 matchby  = 'VIMSEL_FULL'
  7414.                 enumb    = ''
  7415.  
  7416.                 /* Search for the entry in the address book */
  7417.                 rc = RxVIMMatchAddressBook(AddrBkPtr,searchon,ename,matchby,,
  7418.                                            'epos','enumb')
  7419.                 if (rc > 0) then do
  7420.                     /* Entry not found */
  7421.                     Say '--------------------------------------------------------'
  7422.                     Say '  Entry not found in the addressbook'
  7423.                     Say '--------------------------------------------------------'
  7424.                 end  /* Do */
  7425.                 else do
  7426.  
  7427.                     /* Get additional info about specific entry */
  7428.                     itemdesc.0 = 3
  7429.                     itemdesc.1.selector = 'VIMSEL_LOCATION'
  7430.                     itemdesc.1.buffer   = 'location'
  7431.                     itemdesc.2.selector = 'VIMSEL_ADDRESS'
  7432.                     itemdesc.2.buffer   = 'address'
  7433.                     itemdesc.3.selector = 'VIMSEL_TYPE'
  7434.                     itemdesc.3.buffer   = 'typebuf'
  7435.  
  7436.                     rc = RxVIMGetABEntryAttributes(addrBkPtr,epos,'','itemdesc')
  7437.                     if (rc > 0) then call vimerr
  7438.  
  7439.                     Say '--------------------------------------------------------'
  7440.                     Say '  Name     -' ename
  7441.                     Say '  Ref No   -' epos
  7442.                     Say
  7443.                     Say '  Address  -' address
  7444.                     Say '  Type     -' typebuf
  7445.                     Say '  Location -' location
  7446.                     Say '--------------------------------------------------------'
  7447.                 end  /* Do */
  7448.                 'pause'
  7449.  
  7450.                 /* Close the address book */
  7451.                 rc = RxVIMCloseAddressBook(addrBkPtr)
  7452.                 if (rc > 0) then call vimerr
  7453.  
  7454.              end  /* Do */
  7455.              when TRANSLATE(SUBSTR(action,1,1)) = 'G' then do
  7456.  
  7457.                 /* Retrieve the name of the group to display */
  7458.                 Say 'Enter the name of the group to display'
  7459.                 PULL gname
  7460.  
  7461.                 /* Open the current address book */
  7462.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7463.                 if (rc > 0) then call vimerr
  7464.  
  7465.                 /* Enumerate the group member entries */
  7466.                 epos = ''                /* Start at the beginning */
  7467.                 eskipcnt = 1             /* Move forward one at a time */
  7468.                 eacount  = 1             /* Retrieve 1 group member for each call */
  7469.                 emore    = ''            /* Set the value of more to nul */
  7470.                 eaction  = 'N'           /* Set the value of repeat loop indicator to N */
  7471.  
  7472.                 ItemDesc.0 = 3           /* Retrieve 3 attributes for each entry */
  7473.                 ItemDesc.1.Selector = 'VIMSEL_REF' /* 1st attribute  reference number */
  7474.                 ItemDesc.1.Buffer   = 'ABE_Ref'    /* store results in stem variable */
  7475.                 ItemDesc.2.Selector = 'VIMSEL_NAME' /* 2nd attribute is the entry name */
  7476.                 ItemDesc.2.Buffer   = 'ABE_Name'    /* store results in stem variable */
  7477.                 ItemDesc.3.Selector = 'VIMSEL_ADDRESS' /* 3rd attribute entry address */
  7478.                 ItemDesc.3.Buffer   = 'ABE_Address'    /* store results stem variable */
  7479.  
  7480.                 do until TRANSLATE(SUBSTR(eaction,1,1)) = 'X'
  7481.  
  7482.                      /* Continue retrieving group member info until user enters X */
  7483.  
  7484.                      rc = RxVIMEnumerateGroupMembers(AddrBkPtr,'',gname,'epos',eskipcnt,,
  7485.                                            'ItemDesc','eacount','emore')
  7486.                      if (rc > 0) then call vimerr
  7487.  
  7488.                      /* Display results */
  7489.                     'cls'
  7490.                      Say 'RexxVIM - (c) Innovative Business Technologies, Inc'
  7491.                      Say
  7492.                      Say 'Group Member Information'
  7493.                      Say
  7494.                      Say '--------------------------------------------------------'
  7495.                      Say '    Group Name =' gname
  7496.                      Say '--------------------------------------------------------'
  7497.                      Say '    Name =   ' ABE_Name.1
  7498.                      Say '    Address =' ABE_Address.1
  7499.                      Say '    Ref No  =' ABE_Ref.1
  7500.                      Say '--------------------------------------------------------'
  7501.                      Say
  7502.                      Say
  7503.                      Say 'Select an action for this message'
  7504.                      Say
  7505.                      Say '   N - Go to next Group Member entry'
  7506.                      Say '   A - Add a new entry to the group'
  7507.                      Say '   D - Delete this entry from the group'
  7508.                      Say '   X - Exit to the main screen'
  7509.                      Say
  7510.                      Say 'Enter your selection below-'
  7511.                      PULL eaction
  7512.  
  7513.                      select
  7514.                         when TRANSLATE(SUBSTR(eaction,1,1)) = 'N' then do
  7515.                            /* Go to the next group member entry */
  7516.                            /* Nothing to do.....will loop to the next entry */
  7517.                         end  /* Do */
  7518.                         when TRANSLATE(SUBSTR(eaction,1,1)) = 'D' then do
  7519.                            /* Delete the current entry from the group */
  7520.                            rc = RxVIMRemoveGroupMember(AddrBkPtr,'',gname,ABE_Name.1)
  7521.                            if (rc > 0) then call vimerr
  7522.                         end  /* Do */
  7523.                         when TRANSLATE(SUBSTR(eaction,1,1)) = 'A' then do
  7524.                            /* Add a new entry to the group */
  7525.                            Say 'Enter the new name to add'
  7526.                            PULL new_name
  7527.  
  7528.                            rc = RxVIMAddGroupMember(AddrBkPtr,'',gname,new_name)
  7529.                            if (rc > 0) then call vimerr
  7530.                         end  /* Do */
  7531.                      otherwise
  7532.                      end  /* select */
  7533.  
  7534.                      /* End the loop if no more entries */
  7535.                      if emore = 'False' then do
  7536.                         Say 'All entries for this group have been retrieved'
  7537.                         eaction = 'X'
  7538.                      end  /* Do */
  7539.  
  7540.                 end /* Do */
  7541.  
  7542.                 /* Close the  address book */
  7543.                 rc = RxVIMCloseAddressBook(AddrBkPtr)
  7544.                 if (rc > 0) then call vimerr
  7545.  
  7546.              end  /* Do */
  7547.              when TRANSLATE(SUBSTR(action,1,1)) = 'F' then do
  7548.                 /* Create a new group entry in this address book */
  7549.  
  7550.                 Say '--------------------------------------------------------'
  7551.                 Say 'Enter the group name'
  7552.                 Pull gname
  7553.                 Say
  7554.                 Say 'Adding' gname 'to the addressbook'
  7555.                 Say '--------------------------------------------------------'
  7556.  
  7557.                 /* Open the addressbook */
  7558.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7559.                 if (rc > 0) then call vimerr
  7560.  
  7561.                 /* Create the description stem for the create */
  7562.                 attrItem.0 = 1
  7563.                 attrItem.1.Selector = 'VIMSEL_NAME'
  7564.                 attrItem.1.Value    = gname
  7565.  
  7566.                 /* Add the entry to the address book */
  7567.                 rc = RxVIMCreateAddressBookEntry(AddrBkPtr,'VIMSEL_GROUP','attrItem')
  7568.                 if (rc > 0) then call vimerr
  7569.  
  7570.                 /* Close the address book */
  7571.                 rc = RxVIMCloseAddressBook(addrBkPtr)
  7572.                 if (rc > 0) then call vimerr
  7573.  
  7574.              end  /* Do */
  7575.              when TRANSLATE(SUBSTR(action,1,1)) = 'L' then do
  7576.                 /* Search for an entry in this address book */
  7577.  
  7578.                 Say '--------------------------------------------------------'
  7579.                 Say 'Enter the name to change location'
  7580.                 Pull ename
  7581.                 Say
  7582.                 Say 'Searching for' ename 'in the addressbook'
  7583.  
  7584.                 /* Open the addressbook */
  7585.                 rc = RxVIMOpenAddressBook(Session,AddrName.1,'AddrBkPtr')
  7586.                 if (rc > 0) then call vimerr
  7587.  
  7588.                 /* Create the description stem for the create */
  7589.                 searchon = 'VIMSEL_NAME'
  7590.                 epos     = ''
  7591.                 matchby  = 'VIMSEL_FULL'
  7592.                 enumb    = ''
  7593.  
  7594.                 /* Search for the entry in the address book */
  7595.                 rc = RxVIMMatchAddressBook(AddrBkPtr,searchon,ename,matchby,,
  7596.                                            'epos','enumb')
  7597.                 if (rc > 0) then do
  7598.                     /* Entry not found */
  7599.                     Say '--------------------------------------------------------'
  7600.                     Say '  Entry not found in the addressbook'
  7601.                     Say '--------------------------------------------------------'
  7602.                 end  /* Do */
  7603.                 else do
  7604.  
  7605.                     /* Get additional info about specific entry */
  7606.                     itemdesc.0 = 3
  7607.                     itemdesc.1.selector = 'VIMSEL_LOCATION'
  7608.                     itemdesc.1.buffer   = 'location'
  7609.                     itemdesc.2.selector = 'VIMSEL_ADDRESS'
  7610.                     itemdesc.2.buffer   = 'address'
  7611.                     itemdesc.3.selector = 'VIMSEL_TYPE'
  7612.                     itemdesc.3.buffer   = 'typebuf'
  7613.  
  7614.                     rc = RxVIMGetABEntryAttributes(addrBkPtr,epos,'','itemdesc')
  7615.                     if (rc > 0) then call vimerr
  7616.  
  7617.                     Say '--------------------------------------------------------'
  7618.                     Say '  Name     -' ename
  7619.                     Say '  Ref No   -' epos
  7620.                     Say
  7621.                     Say '  Address  -' address
  7622.                     Say '  Type     -' typebuf
  7623.                     Say '  Location -' location
  7624.                     Say '--------------------------------------------------------'
  7625.                 end  /* Do */
  7626.                 Say 'Enter new location - (L)ocal, (R)emote, (M)obile'
  7627.                 Say 'or enter for no change'
  7628.                 PULL nlocation
  7629.  
  7630.                 if LENGTH(STRIP(nlocation)) > 0 then do
  7631.  
  7632.                     itemdesc.0 = 1
  7633.                     itemdesc.1.selector = 'VIMSEL_LOCATION'
  7634.  
  7635.                     /* Set value of new location from input */
  7636.                     Select
  7637.                        when TRANSLATE(SUBSTR(nlocation,1,1)) = 'L' then
  7638.                          itemdesc.1.value = 'VIMSEL_LOCAL'
  7639.                        when TRANSLATE(SUBSTR(nlocation,1,1)) = 'R' then
  7640.                          itemdesc.1.value = 'VIMSEL_REMOTE'
  7641.                        when TRANSLATE(SUBSTR(nlocation,1,1)) = 'M' then
  7642.                          itemdesc.1.value = 'VIMSEL_DIALIN'
  7643.                     otherwise
  7644.                          itemdesc.1.value = location
  7645.                     end  /* select */
  7646.                     itemdesc.1.buffer   = 'location'
  7647.  
  7648.                     /* Call function to set location */
  7649.                     rc = RxVIMSetABEntryAttributes(addrBkPtr,epos,'','itemdesc')
  7650.                     if (rc > 0) then call vimerr
  7651.  
  7652.                 end  /* Do */
  7653.  
  7654.                 /* Close the address book */
  7655.                 rc = RxVIMCloseAddressBook(addrBkPtr)
  7656.                 if (rc > 0) then call vimerr
  7657.  
  7658.              end  /* Do */
  7659.           otherwise
  7660.           end  /* select */
  7661.  
  7662.           if more = 'False' then do
  7663.              Say 'All Address Books have been retrieved'
  7664.              action = 'X'
  7665.           end  /* Do */
  7666.  
  7667.      end /* do */
  7668.  
  7669. /* Close the session with the postoffice */
  7670. rc = RxVIMCloseSession(Session)
  7671. if (rc > 0) then call vimerr
  7672.  
  7673. /* Terminate the active VIM subsystem connection */
  7674. rc = RxVIMTerminate()
  7675. if (rc > 0) then call vimerr
  7676. signal done
  7677.  
  7678. /***** VIMErr *******/
  7679.  
  7680. /* If an error occurs, this function will return the text */
  7681. /* associated with the error.  Extended text may be       */
  7682. /* displayed if it exists for the specified error.        */
  7683.  
  7684. VIMERR:
  7685.  
  7686. erc = RxVIMStatusText(Session,rc,'Status')
  7687. Say
  7688. Say '|-Error Information ------------------------------------|'
  7689. Say '  Error Text -' status.1
  7690. Say
  7691. Say '  Ext Status -' status.2
  7692. rc = RxVIMTerminate()
  7693. signal done
  7694.  
  7695. /* The done section will unload the RexxVIM extensions */
  7696. /* and exit the program                                */
  7697. DONE:
  7698. /*** Drop all of the external functions ***/
  7699. call RxVIMDropFuncs
  7700. Say '|-------------------------------------------------------|'
  7701. Say 'Demo Complete.  All functions released'
  7702. 'pause'
  7703. exit
  7704.  
  7705.