═══ 1. Title Screen ═══ Code Assistant for OS/2(TM) Version 1.0.0 - Beta 3 ═══ 2. Copyright Information ═══ Code Assistant for OS/2(TM) Copyright (c) - 1995 by DB Technologies, Inc. All rights reserved. ═══ 3. Product Description ═══ The Code Assistant for OS/2(TM) is a programmer's tool. Its primary purpose is to assist the programmer while writing source code. Using the Code Assistant it is not necessary for the programmer to memorize APIs or to frequently reference documentation for function syntax and arguments. With the Code Assistant thats all just a mouse click away! The Code Assistant for OS/2 is an extensible database management system which provides for the storage and classification of items which can consist of blocks of ASCII text, VX-REXX GUI-based macros (VRM + VRW files), and executable programs (EXE files). The VX-REXX macros and executable files are classified as LAUNCHABLE MODULES. Code Assistant LAUNCHABLE MODULES are executable modules with a GUI designed for "Guided Completion". LAUNCHABLE MODULES guide or prompt the programmer for the necessary arguments to a specific function call, method, or procedure. After acquiring the neccessary information the LAUNCHABLE MODULE constructs the appropriate line or lines of code and inserts the resultant ASCII text into the current position in the editor. The best thing about the product is that you can design the database and maintain your own LAUNCHABLE MODULES. Programmers can design Code Assistant categories that cover specific APIs. Individual APIs can be imported and exported. If someone else has already designed a Code Assistant category for a specific API and exported it. You could import it into your existing database and have the new API instantly available for use. The Code Assistant for OS/2, and the Code Assistant Librarian programs were written using WATCOM International Corporation's VX-REXX product. The database management facilities are provided using the VIPER Database Engine for OS/2. ═══ 4. Supported Editors ═══ This Beta 3 release of the Code Assistant for OS/2 supports the following editors: VX-REXX Section Editor EPM editor LPEX (IBM Live Parsing editor) See the Installation section for specific installation requirements. The Code Assistant for OS/2 transfers information via the OS/2 clipboard and can actually be used with any editor that supports standard cut and paste clipboard operations. You can use the Code Assistant for OS/2 with the OS/2 System Editor. However, you will have to manually select the Code Assistant window (supported editors listed above have menu options to select the Code Assistant window) and then Paste the Code Assistant supplied source code into your editor (using the supported editors listed above the code is automatically inserted into the editor). ═══ 5. Installation ═══ NOTE: TO RUN THE CODE ASSISTANT FOR OS/2 YOU MUST HAVE REXX AVAILABLE ON YOUR SYSTEM! If you do not currently have a copy of the VROBJ.DLL file on your system you will need to copy the one provided with this package to your system before installation. You should copy the VROBJ.DLL file to your \OS2\DLL directory (or a directory included in your LIBPATH specification). The Code Assistant for OS/2 version 1.0.0 - Beta 3 release requires VROBJ.DLL (version 2.1 - Patch Level C) for proper operation. To install the Code Assistant for OS/2 run the INSTALL.EXE program. If you have WATCOMs VX-REXX installed on your machine, the install program will ask you if you want to use the VX-REXX Section Editor support. If you answer yes, the install program will modify your \VXREXX\MACROS\PROFILE.VRM file to integrate the Code Assistant package with the VX-REXX Section Editor. NOTE: YOU MUST NOT HAVE THE VX-REXX DESIGN ENVIRONMENT ACTIVE DURING INSTALLATION! The install program creates a file named PROFILE.ERX which provides the code necessary to automatically place the Code Assistant menu available for use in the EPM editor at start up. To activate this feature perform the following steps: If you do not have a current EPM profile: 1.) Copy the PROFILE.ERX file to your \OS2\APPS directory. 2.) Start up EPM. 3.) In the EPM Command Dialog (Ctrl+I) execute PROFILE ON. 4.) Then select Save options from the EPM Options menu selection. 5.) Shut down all instances of EPM and restart EPM. The Code Assistant menu should now be available in the EPM. If you already have an EPM PROFILE.ERX file: Add the lines in the PROFILE.ERX file in your Code Assistant directory to your current active profile. The Code Assistant for OS/2 - Beta 3 package now provides support for the LPEX editor. To use the Code Assistant from LPEX you must run the QUEUELX.VRM file from the LPEX editor. REXX support must be available to run the Code Assistant for OS/2. For example, to create a Code Assistant menu in LPEX perform the following: Select the Action -> Issue edit command (Shift+F9) from the LPEX main menu. In the prompt type: set actionbar.~Tools.~Code_Assistant macro C:\ASSIST\QUEUE.VRM This assumes that the QUEUELX.VRM macro file is in the C:\ASSIST directory. ═══ 6. How to use the Code Assistant ═══ For developers familiar with the VX-REXX "Insert Code" macro available in the VX-REXX Section Editor, the Code Assistant for OS/2 works very similar. The Code Assistant window always remains active however, so you remain at the last position within the tree on subsequent uses. You must initially start the Code Assiatant for OS/2 before you invoke it from an editor. The currrent release (Beta 3) transfers information via the OS/2 clipboard. You can use it from a non-supported editor just paste the result from the clipboard into the editor. Due to the current lack of documentation, this Beta 3 distribution is primarily for VX-REXX developers familiar with the Section Editor "Insert Code" macro. ═══ 7. How to use the Librarian ═══ The Code Assistant for OS/2 database is maintained and managed through the use of the Librarian application. You add categories and items (ASCII text blocks and Launchable Modules) to the database using the Librarian. The Code Assistant database contains two types of entries (Categories and Items). Categories form the container tree structure. Items are either the ASCII text blocks or Launchable Modules available in Categories. The following sections will describe the Code Assistant Categories and Items. ═══ 7.1. Categories ═══ Note that all category and item titles (container record captions) must be entered in a strict format. The format restriction is that the only capital (UPPER CASE) characters can exist in the first word of the title. All subsequent words must be completely LOWER CASE. Categories exist to provide the Code Assistant database with a tree-like structure. Categories can contain nested sub-categories to a varying limit. The limit of an individual nested category tree is typically about 3000-4000 sub-categories (more than adequate for reasonable usage). The exact limit is dependent upon the length of category names, the longer the names, the fewer nesting levels of sub-categories. You can create Root categories by selecting the Item -->Insert -->Category -->Root menu options. You can create a sub-category off of a root category or another sub-category by selecting the Item -->Insert -->Category -->Current position menu options. ═══ 7.2. Items ═══ Note that all category and item titles (container record captions) must be entered in a strict format. The format restriction is that the only capital (UPPER CASE) characters can exist in the first word of the title. All subsequent words must be completely LOWER CASE. Items can only be placed off of a category. The category may be a root category or a sub-category. Items may be Routines which are blocks of ASCII text or they may be Launchable Modules (currently supported Launchable Modules are GUI-based VX-REXX macros (VRM + VRW files), or executable programs (EXE files). ═══ 7.2.1. Routines ═══ Routines can be inserted into the database via the Item -->Insert -->Routine menu options. Once selected the Librarian will prompt you for the Item title. The Item title is the text caption displayed in the Code Assistant tree. Once an appropriate title is entered, you are presented with an MLE to accept the ASCII text for the Routine. When finished entering the text, selecting OK will store the new item in the Code Assistant database. The entire size of a block of code making up a single Routine may not exceed 30,000 bytes. ═══ 7.2.2. Launchable Modules ═══ Launchable Modules are inserted into the database via drag-drop. You select the appropriate VX-REXX macro file (VRM file must be dragged) or executable (EXE) from the Available files container and then drag and drop it on the appropriate category in the Code Assistant Database Structure container. You are then prompted for the Item title or caption. When an acceptable title is entered the module is stored in the database. When you design Launchable Modules you must abide by the following criteria: VX-REXX macros should return values from the Fini section as stated in the VX-REXX documentation. VX-REXX macros return values to the Code Assistant program (which is a VX-REXX executable) though the call to the macro. The Code Assistant program extracts the macro from the database and then calls it. The macro returns its value directly to the Code Assistant program which then transfers the value to the editor. Executable (EXE) files return values via the OS/2 clipboard. The Code Assistant program extracts the EXE file from the database and runs it. When the EXE terminates, the Code Assistant program regains control and looks for a return value (ASCII text) in the OS/2 clipboard. When you design EXE Launchable Modules you should pass any valid return text in the OS/2 clipboard. If you do not wish to pass back a value (as in the case of the user pressing a Cancel button) make sure that the clipboard is empty before terminating your EXE module. We prefer that all Launchable Modules be created as VX-REXX macros for several reasons. The VX-REXX macro approach is technically cleaner. The VX-REXX macros can be extracted out of the database individually and used elsewhere. The macros are modifiable by an end user. The macro approach will carry over in subsequent releases which will discourage use of the clipboard for data transfer. Currently the clipboard is used because we want to try to provide a very simple interface for designers of EXE Launchable modules. We do not want to demand a complicated interface for data transfer in EXE modules. We are currently designing a versatile API for EXE modules that does not use the OS/2 clipboard and that will appeal to numerous languages. All Launchable Modules must be under 30,000 bytes in size. VX-REXX GUI macros consist of two components (a .VRM and a .VRW file). Each of these two components must individually adhere to this size restriction. For example, it is acceptable to have a VX-REXX macro which consists of a VRM file 28,000 bytes in size and a VRW file which is 28,000 bytes in size. It is not legal to have a VRM file 32,000 bytes in size and a VRW file 3,000 bytes in size. ═══ 7.2.2.1. Sample Launchable Modules ═══ This Beta 3 distribution disk contains a directory (\LMODULES) which includes two sample Launchable Modules complete with source code (B2X and Random). These modules are located in their respective directories. Use these samples to see how Launchable Modules are designed. The RANDOM Launchable Module is of type EXE. The RANDOM.EXE file is the Launchable Module which can be inserted into the Code Assistant database. The B2X Launchable Module is a VX-REXX macro type. The B2X.VRM and the B2X.VRW files are inserted into the Code Assistant database using the Code Assistant Librarian (Note that when trying to insert a VX-REXX macro you must drag the .VRM file). The RANDOM and B2X Launchable Modules are already in the Code Assistant sample database shipped with the Beta 3 package. Using the Librarian you can delete these items and re-insert the Launchable Modules in the database using the samples provided in the \LMODULES directory. ═══ 8. Technical Support ═══ Technical support for the Beta program can be obtained via email. Send all requests for technical assistance to Code Assistant Beta Coordinator at: CompuServe ID: 72123,3661 Internet: dbtech@ibm.net You may also send requests by fax to (941) 377-7392.