home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 18 REXX / 18-REXX.zip / dmrxwps1.zip / DMrxWPS.doc < prev   
Text File  |  1996-08-03  |  11KB  |  337 lines
  1. ===========================================================================
  2.  
  3. Title:      DMrxWPS
  4. Author:     David MacMahon (davidm@ccnet.com)
  5. Date:       August 3, 1996
  6. Copyright:  Copyright D. MacMahon, Inc. 1996.
  7.             All rights reserved.
  8.  
  9. ===========================================================================
  10.  
  11.  
  12. =================
  13. Table of Contents
  14. =================
  15.  
  16. (0) Terms and Conditions
  17. (1) Introduction
  18. (2) Functions
  19.       WpsLoadFuncs
  20.       WpsDropFuncs
  21.       WpsQueryObject
  22.       WpsQueryObjectPath
  23.       WpsSetObjectData
  24. (3) Sample - DelTmplt.cmd
  25. (4) Contacting D. MacMahon, Inc.
  26.  
  27.  
  28. ========================
  29. (0) Terms and Conditions
  30. ========================
  31. The copyright notice appearing at the top of this document applies to both
  32. this document ("Document") and the accompanying binary DMrxWPS library
  33. ("DLL") described herein.  Both Document and DLL (collectively referred to
  34. as "Product") may be freely used and distributed for any noncommercial
  35. purpose.  Neither Document nor DLL may be used or distributed in whole or
  36. in part for any commercial purpose without the prior written consent of D.
  37. MacMahon, Inc.
  38.  
  39. Consent for limited commercial distribution
  40. ------------------------------------------
  41. Consent is hereby granted for limited commercial distribution of Product
  42. provided the following conditions are met:
  43.  
  44. 1) Product is distributed unmodified and in its entirety including the
  45.    above copyright notice and this Terms and Conditions section.
  46.  
  47. 2) Product is being distributed as part of a collection of software that is
  48.    readily available on the Internet.
  49.  
  50. 3) Said collection of software is not distributed in conjunction with any
  51.    other commercial offering.
  52.  
  53. 4) No fee is charged for Product and only a nominal fee is charged for the
  54.    collection of software as a whole.
  55.  
  56. Disclaimer of Warranty
  57. ----------------------
  58. Product is provided "as is" without any warranties, express or implied,
  59. from D. MacMahon, Inc.  In no event will D. MacMahon, Inc. be liable for
  60. any damages whatsoever incurred through the use of Product.
  61.  
  62.  
  63. ================
  64. (1) Introduction
  65. ================
  66. DMrxWPS is a package that consists of three files: DMrxWPS.dll,
  67. DMrxWPS.doc (this file), and DelTmplt.cmd.
  68.  
  69. DMrxWPS.dll is a REXX library that provides a bridge between REXX scripts
  70. and some of the WPS related OS/2 API functions, referred to as "Win
  71. functions".  Its main purpose is to facilitate the installation and the
  72. reinstallation or updating of WPS classes.  The current version of
  73. DMrxWPS supports only three Win functions in addition to its own two
  74. "helper functions".  One of the Win functions, WinQueryObjectPath, is only
  75. available on Warp or above.  Calling its corresponding DMrxWPS function,
  76. WpsQueryObjectPath, will not work on version of OS/2 before Warp.
  77.  
  78. Many of the Win functions are available in the RexxUtil REXX library.
  79. DMrxWPS is intended to supplement RexxUtil, not replace it.  The three Win
  80. functions included in DMrxWPS are WpsQueryObject, WpsQueryObjectPath, and
  81. WpsSetObjectData.  The first two functions were chosen because they can be
  82. used together to obtain the path to a WPFileSystem derived template in the
  83. Templates folder without knowing the path of the Templates folder itself.
  84. This path can then be used to manipulate the template using functions
  85. from RexxUtil.  The sample script DelTmplt.cmd (included with DMrxWPS and
  86. described in section 3) shows how this can be done.
  87.  
  88. DMrxWPS.dll needs to be in one of the directories is specified in the
  89. LIBPATH statement of CONFIG.SYS.
  90.  
  91.  
  92. ============
  93. 2) Functions
  94. ============
  95. This section documents the functions provided in DMrxWPS.
  96.  
  97. -------------
  98. WpsLoadFuncs
  99. -------------
  100. Description:
  101. This function registers all the DMrxWPS functions, except itself, with
  102. REXX.  If the name of any previously registered function conflicts with the
  103. name of any function that this routine registers, the previously existing
  104. function is dropped.
  105.  
  106. Parameters:
  107. None.
  108.  
  109. Result:
  110. Copyright and version string
  111.  
  112. Example:
  113.            /* WpsLoadFuncs example */
  114.            rc = rxFuncAdd( 'WpsLoadFuncs', 'DMrxWPS', 'WpsLoadFuncs');
  115.            rc = WpsLoadFuncs(); say rc;
  116.            /* All DMrxWPS functions now available */
  117.            exit;
  118.  
  119. This script produces the following output:
  120.  
  121.    DMrxWPS - Version 1.0
  122.    Copyright D. MacMahon, Inc. 1996.  All rights reserved.
  123.  
  124.  
  125. ------------
  126. WpsDropFuncs
  127. ------------
  128. Description:
  129. This function deregisters all the DMrxWPS functions with REXX.  CAUTION:
  130. Deregistering the functions in any ONE session will make the functions
  131. unavailable in ALL sessions.
  132.  
  133. Parameters:
  134. None.
  135.  
  136. Result:
  137. Empty string
  138.  
  139. Example:
  140.            /* WpsDropFuncs example */
  141.            rc = rxFuncAdd( 'WpsLoadFuncs', 'DMrxWPS', 'WpsLoadFuncs');
  142.            rc = WpsLoadFuncs(); say rc;
  143.  
  144.            /* All DMrxWPS functions now available to all REXX sessions*/
  145.  
  146.            rc = WpsDropFuncs();
  147.  
  148.            /* All DMrxWPS functions now unavailable to all REXX sessions*/
  149.  
  150.            exit;
  151.  
  152. This script produces no output.
  153.  
  154.  
  155. --------------
  156. WpsQueryObject
  157. --------------
  158. Description:
  159. This function provides a REXX wrapper to the WinQueryObject function.
  160.  
  161. Parameter 1:
  162. Object ID of any type of object or the path of any WPFileSystem-derived
  163. object.
  164.  
  165. Result:
  166. Return value from WinQueryObject.  This is the object handle of the queried
  167. object as an eight digit hexadecimal number preceded by '0x'.  If
  168. '0x00000000' is returned, there was an error; probably the specified object
  169. does not exist or a path was used in an attempt to get the object ID of an
  170. abstract object.
  171.  
  172. Example:
  173.            /* WpsQueryObject example */
  174.            rc = rxFuncAdd( 'WpsLoadFuncs', 'DMrxWPS', 'WpsLoadFuncs');
  175.            rc = WpsLoadFuncs(); say rc;
  176.  
  177.            /* All DMrxWPS functions now available to all REXX sessions*/
  178.  
  179.            /* Get handle of <WP_DESKTOP> */
  180.            hDesktop = WpsQueryObject( '<WP_DESKTOP>');
  181.  
  182.            /* Print handle of <WP_DESKTOP> */
  183.            say '<WP_DESKTOP> is object' hDesktop;
  184.  
  185.            exit;
  186.  
  187. This script produces the following output:
  188.  
  189.    DMrxWPS - Version 1.0
  190.    Copyright D. MacMahon, Inc. 1996.  All rights reserved.
  191.  
  192.    <WP_DESKTOP> is object 0x00032AC5
  193.  
  194.  
  195. ------------------
  196. WpsQueryObjectPath
  197. ------------------
  198. Description:
  199. This function provides a REXX wrapper to the WinQueryObjectPath function.
  200. This function is only available on OS/2 version 3 (Warp) or above.
  201.  
  202. Parameter 1:
  203. Object handle of queried object
  204.  
  205. Parameter 2:
  206. REXX variable in which to store path
  207.  
  208. Result:
  209. Return value from WinQueryObjectPath. Nonzero indicates successful
  210. completion.  Zero indicates that an error occurred.
  211.  
  212. Example:
  213.            /* WpsQueryObjectPath example */
  214.            rc = rxFuncAdd( 'WpsLoadFuncs', 'DMrxWPS', 'WpsLoadFuncs');
  215.            rc = WpsLoadFuncs(); say rc;
  216.  
  217.            /* All DMrxWPS functions now available to all REXX sessions*/
  218.  
  219.            /* Get handle of <WP_DESKTOP> */
  220.            hDesktop = WpsQueryObject( '<WP_DESKTOP>');
  221.  
  222.            /* Check for error */
  223.            if hDesktop == '0x00000000' then
  224.              do
  225.                /* Uh, oh, display error message and bail out. */
  226.                say 'Error retrieving handle of <WP_DESKTOP>';
  227.                exit;
  228.              end;
  229.  
  230.            /* Get path to <WP_DESKTOP> */
  231.            rc = WinQueryObjectPath( hDesktop, DesktopPath);
  232.            /* Check for error */
  233.            if rc == 0 then
  234.              do
  235.                /* Uh, oh, display error message and bail out. */
  236.                say 'Error retrieving path to object' hDesktop;
  237.                exit;
  238.              end;
  239.            else /* no error */
  240.              do
  241.                /* Print path */
  242.                say 'Path to object' hDesktop 'is' DesktopPath;
  243.              end;
  244.            exit;
  245.  
  246. This script produces the following output:
  247.  
  248.    DMrxWPS - Version 1.0
  249.    Copyright D. MacMahon, Inc. 1996.  All rights reserved.
  250.  
  251.    Path to object 0x00032AC5 is D:\Desktop
  252.  
  253.  
  254. ----------------
  255. WpsSetObjectData
  256. ----------------
  257. Description:
  258. This function provides a REXX wrapper to the WinSetObjectData function.
  259. WpsSetObjectData is similar to, but more versatile than the
  260. SysSetObjectData function found in RexxUtil.  SysSetObjectData allows an
  261. object's "restriction options" (e.g. NOTVISIBLE, NOPRINT, etc.) to be
  262. turned on, but does not allow them to be turned off again without
  263. recreating the entire object.  WpsSetObjectData allows these restriction
  264. options to be turned both on and off.  The first parameter to
  265. WpsSetObjectData should be an object handle instead of an object ID or
  266. path (as SysSetObjectData expects).
  267.  
  268. Parameter 1:
  269. Object handle of object whose data is being set
  270.  
  271. Parameter 2:
  272. Setup string
  273.  
  274. Result:
  275. Return value from WinSetObjectData. Non-zero indicates successful
  276. completion.  Zero indicates that an error occurred.
  277.  
  278. Example:
  279.            /* WpsSetObjectData example */
  280.            rc = rxFuncAdd( 'WpsLoadFuncs', 'DMrxWPS', 'WpsLoadFuncs');
  281.            rc = WpsLoadFuncs(); say rc;
  282.  
  283.            /* All DMrxWPS functions now available to all REXX sessions*/
  284.  
  285.            /* Make "OS/2 System" folder invisible */
  286.            rc = WpsSetObjectData( '<WP_OS2SYS>', 'NOTVISIBLE=YES');
  287.            /* Check for error */
  288.            if rc == 0 then
  289.              do
  290.                /* Uh, oh, display error message and bail out. */
  291.                say 'Error making "OS/2 System" folder invisible';
  292.                exit;
  293.              end;
  294.  
  295.            /* "OS/2 System" folder is now invisible */
  296.  
  297.            /* Make "OS/2 System" folder visible again */
  298.            rc = WpsSetObjectData( '<WP_OS2SYS>', 'NOTVISIBLE=NO');
  299.            /* Check for error */
  300.            if rc == 0 then
  301.              do
  302.                /* Uh, oh, display error message and bail out. */
  303.                say 'Error making "OS/2 System" folder visible';
  304.                exit;
  305.              end;
  306.  
  307.            exit;
  308.  
  309. This script produces no textual output.
  310.  
  311.  
  312. =========================
  313. (3) Sample - DelTmplt.cmd
  314. =========================
  315. DelTmplt.cmd is a script file that is used to delete templates.  It takes a
  316. single template name as an argument and deletes it.  The script is well
  317. commented and should be self-documenting.  This script will only delete
  318. templates of classes that are derived (directly or indirectly) from
  319. WPFileSystem.  It will not delete templates of classes that are derived
  320. (directly or indirectly) from WPAbstract.  Furthermore, templates deleted
  321. from the Templates folder will be recreated automatically whenever the
  322. Templates folder is opened or refreshed.  To permanently delete a template
  323. from the Templates folder, deregister the template's class after deleting
  324. the template.  A WPS class DLL can be overwritten or deleted once the all
  325. the objects of all the DLL's classes have been deleted, including all
  326. templates of those classes, and the DLL's classes have been deregistered.
  327.  
  328.  
  329. ================================
  330. (4) Contacting D. MacMahon, Inc.
  331. ================================
  332. D. MacMahon, Inc. is a software development firm applying object-oriented,
  333. client/server technologies in heterogeneous environments.
  334.  
  335. D. MacMahon, Inc. may be reached by sending e-mail to its president,
  336. David MacMahon, at davidm@ccnet.com.
  337.