home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / ca100b3.zip / CA100.INF (.txt) < prev    next >
OS/2 Help File  |  1995-09-29  |  34KB  |  286 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Title Screen ΓòÉΓòÉΓòÉ
  3.  
  4.                            Code Assistant for OS/2(TM)
  5.  
  6.                              Version 1.0.0 - Beta 3
  7.  
  8.  
  9. ΓòÉΓòÉΓòÉ 2. Copyright Information ΓòÉΓòÉΓòÉ
  10.  
  11. Code Assistant for OS/2(TM) 
  12.  
  13. Copyright (c) - 1995 by DB Technologies, Inc. All rights reserved. 
  14.  
  15.  
  16. ΓòÉΓòÉΓòÉ 3. Product Description ΓòÉΓòÉΓòÉ
  17.  
  18. The Code Assistant for OS/2(TM) is a programmer's tool. Its primary purpose is 
  19. to assist the programmer while writing source code. Using the Code Assistant it 
  20. is not necessary for the programmer to memorize APIs or to frequently reference 
  21. documentation for function syntax and arguments. With the Code Assistant thats 
  22. all just a mouse click away! 
  23.  
  24. The Code Assistant for OS/2 is an extensible database management system which 
  25. provides for the storage and classification of items which can consist of 
  26. blocks of ASCII text, VX-REXX GUI-based macros (VRM + VRW files), and 
  27. executable programs (EXE files). The VX-REXX macros and executable files are 
  28. classified as LAUNCHABLE MODULES. Code Assistant LAUNCHABLE MODULES are 
  29. executable modules with a GUI designed for "Guided Completion". LAUNCHABLE 
  30. MODULES guide or prompt the programmer for the necessary arguments to a 
  31. specific function call, method, or procedure. After acquiring the neccessary 
  32. information the LAUNCHABLE MODULE constructs the appropriate line or lines of 
  33. code and inserts the resultant ASCII text into the current position in the 
  34. editor. 
  35.  
  36. The best thing about the product is that you can design the database and 
  37. maintain your own LAUNCHABLE MODULES. Programmers can design Code Assistant 
  38. categories that cover specific APIs. Individual APIs can be imported and 
  39. exported. If someone else has already designed a Code Assistant category for a 
  40. specific API and exported it. You could import it into your existing database 
  41. and have the new API instantly available for use. 
  42.  
  43. The Code Assistant for OS/2, and the Code Assistant Librarian programs were 
  44. written using WATCOM International Corporation's VX-REXX product. The database 
  45. management facilities are provided using the VIPER Database Engine for OS/2. 
  46.  
  47.  
  48. ΓòÉΓòÉΓòÉ 4. Supported Editors ΓòÉΓòÉΓòÉ
  49.  
  50. This Beta 3 release of the Code Assistant for OS/2 supports the following 
  51. editors: 
  52.  
  53. VX-REXX Section Editor 
  54.  
  55. EPM editor 
  56.  
  57. LPEX (IBM Live Parsing editor) 
  58.  
  59. See the Installation section for specific installation requirements. 
  60.  
  61. The Code Assistant for OS/2 transfers information via the OS/2 clipboard and 
  62. can actually be used with any editor that supports standard cut and paste 
  63. clipboard operations. You can use the Code Assistant for OS/2 with the OS/2 
  64. System Editor. However, you will have to manually select the Code Assistant 
  65. window (supported editors listed above have menu options to select the Code 
  66. Assistant window) and then Paste the Code Assistant supplied source code into 
  67. your editor (using the supported editors listed above the code is automatically 
  68. inserted into the editor). 
  69.  
  70.  
  71. ΓòÉΓòÉΓòÉ 5. Installation ΓòÉΓòÉΓòÉ
  72.  
  73. NOTE: TO RUN THE CODE ASSISTANT FOR OS/2 YOU MUST HAVE REXX AVAILABLE ON YOUR 
  74. SYSTEM! 
  75.  
  76. If you do not currently have a copy of the VROBJ.DLL file on your system you 
  77. will need to copy the one provided with this package to your system before 
  78. installation. You should copy the VROBJ.DLL file to your \OS2\DLL directory (or 
  79. a directory included in your LIBPATH specification). The Code Assistant for 
  80. OS/2 version 1.0.0 - Beta 3 release requires VROBJ.DLL (version 2.1 - Patch 
  81. Level C) for proper operation. 
  82.  
  83. To install the Code Assistant for OS/2 run the INSTALL.EXE program. If you have 
  84. WATCOMs VX-REXX installed on your machine, the install program will ask you if 
  85. you want to use the VX-REXX Section Editor support. If you answer yes, the 
  86. install program will modify your \VXREXX\MACROS\PROFILE.VRM file to integrate 
  87. the Code Assistant package with the VX-REXX Section Editor. 
  88.  
  89. NOTE: YOU MUST NOT HAVE THE VX-REXX DESIGN ENVIRONMENT ACTIVE DURING 
  90. INSTALLATION! 
  91.  
  92. The install program creates a file named PROFILE.ERX which provides the code 
  93. necessary to automatically place the Code Assistant menu available for use in 
  94. the EPM editor at start up. To activate this feature perform the following 
  95. steps: 
  96.  
  97. If you do not have a current EPM profile: 
  98.  
  99. 1.) Copy the PROFILE.ERX file to your \OS2\APPS directory. 
  100.  
  101. 2.) Start up EPM. 
  102.  
  103. 3.) In the EPM Command Dialog (Ctrl+I) execute PROFILE ON. 
  104.  
  105. 4.) Then select Save options from the EPM Options menu selection. 
  106.  
  107. 5.) Shut down all instances of EPM and restart EPM. The Code Assistant menu 
  108. should now be available in the EPM. 
  109.  
  110. If you already have an EPM PROFILE.ERX file: 
  111.  
  112. Add the lines in the PROFILE.ERX file in your Code Assistant directory to your 
  113. current active profile. 
  114.  
  115. The Code Assistant for OS/2 - Beta 3 package now provides support for the LPEX 
  116. editor. To use the Code Assistant from LPEX you must run the QUEUELX.VRM file 
  117. from the LPEX editor. REXX support must be available to run the Code Assistant 
  118. for OS/2. 
  119.  
  120. For example, to create a Code Assistant menu in LPEX perform the following: 
  121.  
  122. Select the Action -> Issue edit command (Shift+F9) from the LPEX main menu. 
  123.  
  124. In the prompt type: 
  125.  
  126. set actionbar.~Tools.~Code_Assistant macro C:\ASSIST\QUEUE.VRM 
  127.  
  128. This assumes that the QUEUELX.VRM macro file is in the C:\ASSIST directory. 
  129.  
  130.  
  131. ΓòÉΓòÉΓòÉ 6. How to use the Code Assistant ΓòÉΓòÉΓòÉ
  132.  
  133. For developers familiar with the VX-REXX "Insert Code" macro available in the 
  134. VX-REXX Section Editor, the Code Assistant for OS/2 works very similar. The 
  135. Code Assistant window always remains active however, so you remain at the last 
  136. position within the tree on subsequent uses. You must initially start the Code 
  137. Assiatant for OS/2 before you invoke it from an editor. 
  138.  
  139. The currrent release (Beta 3) transfers information via the OS/2 clipboard. You 
  140. can use it from a non-supported editor just paste the result from the clipboard 
  141. into the editor. 
  142.  
  143. Due to the current lack of documentation, this Beta 3 distribution is primarily 
  144. for VX-REXX developers familiar with the Section Editor "Insert Code" macro. 
  145.  
  146.  
  147. ΓòÉΓòÉΓòÉ 7. How to use the Librarian ΓòÉΓòÉΓòÉ
  148.  
  149. The Code Assistant for OS/2 database is maintained and managed through the use 
  150. of the Librarian application. You add categories and items (ASCII text blocks 
  151. and Launchable Modules) to the database using the Librarian. 
  152.  
  153. The Code Assistant database contains two types of entries (Categories and 
  154. Items). Categories form the container tree structure. Items are either the 
  155. ASCII text blocks or Launchable Modules available in Categories. 
  156.  
  157. The following sections will describe the Code Assistant Categories and Items. 
  158.  
  159.  
  160. ΓòÉΓòÉΓòÉ 7.1. Categories ΓòÉΓòÉΓòÉ
  161.  
  162. Note that all category and item titles (container record captions) must be 
  163. entered in a strict format. The format restriction is that the only capital 
  164. (UPPER CASE) characters can exist in the first word of the title. All 
  165. subsequent words must be completely LOWER CASE. 
  166.  
  167. Categories exist to provide the Code Assistant database with a tree-like 
  168. structure. Categories can contain nested sub-categories to a varying limit. The 
  169. limit of an individual nested category tree is typically about 3000-4000 
  170. sub-categories (more than adequate for reasonable usage). 
  171.  
  172. The exact limit is dependent upon the length of category names, the longer the 
  173. names, the fewer nesting levels of sub-categories. 
  174.  
  175. You can create Root categories by selecting the Item -->Insert -->Category 
  176. -->Root menu options. 
  177.  
  178. You can create a sub-category off of a root category or another sub-category by 
  179. selecting the Item -->Insert -->Category -->Current position menu options. 
  180.  
  181.  
  182. ΓòÉΓòÉΓòÉ 7.2. Items ΓòÉΓòÉΓòÉ
  183.  
  184. Note that all category and item titles (container record captions) must be 
  185. entered in a strict format. The format restriction is that the only capital 
  186. (UPPER CASE) characters can exist in the first word of the title. All 
  187. subsequent words must be completely LOWER CASE. 
  188.  
  189. Items can only be placed off of a category. The category may be a root category 
  190. or a sub-category. Items may be Routines which are blocks of ASCII text or they 
  191. may be Launchable Modules (currently supported Launchable Modules are GUI-based 
  192. VX-REXX macros (VRM + VRW files), or executable programs (EXE files). 
  193.  
  194.  
  195. ΓòÉΓòÉΓòÉ 7.2.1. Routines ΓòÉΓòÉΓòÉ
  196.  
  197. Routines can be inserted into the database via the Item -->Insert -->Routine 
  198. menu options. Once selected the Librarian will prompt you for the Item title. 
  199. The Item title is the text caption displayed in the Code Assistant tree. Once 
  200. an appropriate title is entered, you are presented with an MLE to accept the 
  201. ASCII text for the Routine. When finished entering the text, selecting OK will 
  202. store the new item in the Code Assistant database. 
  203.  
  204. The entire size of a block of code making up a single Routine may not exceed 
  205. 30,000 bytes. 
  206.  
  207.  
  208. ΓòÉΓòÉΓòÉ 7.2.2. Launchable Modules ΓòÉΓòÉΓòÉ
  209.  
  210. Launchable Modules are inserted into the database via drag-drop. You select the 
  211. appropriate VX-REXX macro file (VRM file must be dragged) or executable (EXE) 
  212. from the Available files container and then drag and drop it on the appropriate 
  213. category in the Code Assistant Database Structure container. You are then 
  214. prompted for the Item title or caption. When an acceptable title is entered the 
  215. module is stored in the database. 
  216.  
  217. When you design Launchable Modules you must abide by the following criteria: 
  218.  
  219. VX-REXX macros should return values from the Fini section as stated in the 
  220. VX-REXX documentation. VX-REXX macros return values to the Code Assistant 
  221. program (which is a VX-REXX executable) though the call to the macro. The Code 
  222. Assistant program extracts the macro from the database and then calls it. The 
  223. macro returns its value directly to the Code Assistant program which then 
  224. transfers the value to the editor. 
  225.  
  226. Executable (EXE) files return values via the OS/2 clipboard. The Code Assistant 
  227. program extracts the EXE file from the database and runs it. When the EXE 
  228. terminates, the Code Assistant program regains control and looks for a return 
  229. value (ASCII text) in the OS/2 clipboard. When you design EXE Launchable 
  230. Modules you should pass any valid return text in the OS/2 clipboard. If you do 
  231. not wish to pass back a value (as in the case of the user pressing a Cancel 
  232. button) make sure that the clipboard is empty before terminating your EXE 
  233. module. 
  234.  
  235. We prefer that all Launchable Modules be created as VX-REXX macros for several 
  236. reasons. The VX-REXX macro approach is technically cleaner. The VX-REXX macros 
  237. can be extracted out of the database individually and used elsewhere. The 
  238. macros are modifiable by an end user. The macro approach will carry over in 
  239. subsequent releases which will discourage use of the clipboard for data 
  240. transfer. 
  241.  
  242. Currently the clipboard is used because we want to try to provide a very simple 
  243. interface for designers of EXE Launchable modules. We do not want to demand a 
  244. complicated interface for data transfer in EXE modules. We are currently 
  245. designing a versatile API for EXE modules that does not use the OS/2 clipboard 
  246. and that will appeal to numerous languages. 
  247.  
  248.  All Launchable Modules must be under 30,000 bytes in size. VX-REXX GUI macros 
  249. consist of two components (a .VRM and a .VRW file). Each of these two 
  250. components must individually adhere to this size restriction. For example, it 
  251. is acceptable to have a VX-REXX macro which consists of a VRM file 28,000 bytes 
  252. in size and a VRW file which is 28,000 bytes in size. It is not legal to have a 
  253. VRM file 32,000 bytes in size and a VRW file 3,000 bytes in size. 
  254.  
  255.  
  256. ΓòÉΓòÉΓòÉ 7.2.2.1. Sample Launchable Modules ΓòÉΓòÉΓòÉ
  257.  
  258. This Beta 3 distribution disk contains a directory (\LMODULES) which includes 
  259. two sample Launchable Modules complete with source code (B2X and Random). These 
  260. modules are located in their respective directories. Use these samples to see 
  261. how Launchable Modules are designed. 
  262.  
  263. The RANDOM Launchable Module is of type EXE. The RANDOM.EXE file is the 
  264. Launchable Module which can be inserted into the Code Assistant database. 
  265.  
  266. The B2X Launchable Module is a VX-REXX macro type. The B2X.VRM and the B2X.VRW 
  267. files are inserted into the Code Assistant database using the Code Assistant 
  268. Librarian (Note that when trying to insert a VX-REXX macro you must drag the 
  269. .VRM file). 
  270.  
  271. The RANDOM and B2X Launchable Modules are already in the Code Assistant sample 
  272. database shipped with the Beta 3 package. Using the Librarian you can delete 
  273. these items and re-insert the Launchable Modules in the database using the 
  274. samples provided in the \LMODULES directory. 
  275.  
  276.  
  277. ΓòÉΓòÉΓòÉ 8. Technical Support ΓòÉΓòÉΓòÉ
  278.  
  279. Technical support for the Beta program can be obtained via email. Send all 
  280. requests for technical assistance to Code Assistant Beta Coordinator at: 
  281.  
  282. CompuServe ID: 72123,3661 
  283.  
  284. Internet: dbtech@ibm.net 
  285.  
  286. You may also send requests by fax to (941) 377-7392.