TUTORIAL.TXT -- eComet Internet Application Server Tutorial Installation ======================================================================== Last updated on January 24, 2002. Before attempting to install the eComet tutorial on your own machine, it would be very helpful for you to be somewhat familiar with it. The eComet online tutorial can be viewed from: http://www.signature.net/ecomet It is assumed that you have configured and tested the eComet Internet Application Server using the basic installation instructions provided in the file: eComet.ZIP For the latest information about the eComet tutorial, see the "What's New" section at the bottom of this file. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The tutorial files are contained in two ZIP files: 1. TUTORIAL.ZIP This ZIP file contains all of the HTML files and graphics in the eComet tutorial. Please note that this file contains 3 subdirectories: ECOMET\HTML the sample HTML files in the tutorial ECOMET\IMAGES the sample graphics in the tutorial ECOMET\TUTORIAL the tutorial files (in HTML format) Be sure to preserve the directory structure when unzipping this archive. We recommend using WinZip to unzip this file. 2. XGI0201.ZIP This ZIP file contains the Internet Basic source code for all of the sample programs in the eComet tutorial. It also contains some sample Comet data files that accompany the programs. This is a Comet directory (i.e., there's a QDIR file in the ZIP file) named XGI. ALL PROGRAMS MUST BE COMPILED BY THE INSTALLER. To facilitate program compilation, we have included an Internet Basic compiler command file in this ZIP file. The command file is named #BLDXAP. It compiles all of the source programs in the XGI directory to the XAP directory. Note: To use these programs, create and configure an XGI directory, and place the contents of this file in it. The compiled object code must be placed in XAP. For more information, see the eComet tutorial. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - How to implement this tutorial on your own Comet2000 system: a. Install and test the XAP gateway. For more information, please see: http://signature.net:8080/xap/tutorial?LESSON=install.htm The ZIP file eComet.zip contains all the basic files you will need. b. In addition to the COS & XAP directories, you must also configure an XGI directory, in which to put the tutorial program sources. Since the tutorial uses some advanced features, an additional NON-Comet folder must be created, in which COMMON context files are stored. The location and name of this folder is very specific. It must be called "TEMP" and must be located within the COS directory. The directory structure configured for the node running the XAP Gateway and tutorial must be the following: COS\ COS\TEMP\ XAP\ XGI\ d. Unzip the TUTORIAL.ZIP file to the C: drive. The file contains one main directory named ECOMET and 3 subdirectories (HTML, IMAGES, and TUTORIAL). These directory names are included in the zip file and must be preserved when you unzip the file (ie. WinZip). After unzipping, the directory structure will look like this: C:\ECOMET\ C:\ECOMET\HTML\ C:\ECOMET\IMAGES\ C:\ECOMET\TUTORIAL\ e. Unzip the XGI0201.ZIP file into the (newly created) XGI directory of your Comet2000 system. f. Run the Comet Editor program (CED). Open the XXAPCFM source program. Locate line 1400. Change the value of the maintenance password (Pwd$) and remember this value. g. Compile all of the programs in the XGI directory. All objects must be placed in the XAP directory of your Comet2000 system. The #BLDXAP command file is provided for this purpose. h. From the READY prompt in Comet2000, run the XAPMON program. This activates the eComet server (which should alread be configured). If you haven't modified the #XAP command file, the XAP gateway will start listening using port 80. i. From a web browser (such Netscape Navigator or Internet Explorer), run the XAPCFM program, as follows: http://127.0.0.1/xap/xapcfm or http://localhost/xap/xapcfm Notes: 1. The "127.0.0.1" address is the loopback IP address for your local machine. This is also referred to as "localhost". 2. The default port is 80, therefore there is no need to include it in the URL. j. The XAP Control File Maintenance program will now display a web page on your browser. Assuming you named the directories as recommended above, enter the following values in the table: Field name Value ------------------------------------------------- **CGIPATH** http://127.0.0.1/xap/ **SOURCEPATH** XGI **IMAGEPATH** file://c:/ecomet/images/ **HTMLPATH** c:\ecomet\html\ **HTMLLINK** file://c:/ecomet/html/ **TUTORIALPATH** c:\ecomet\tutorial\ **TUTORIALLINK** file://c:/ecomet/tutorial/ Disclaimer: If you use different directories than these, or Implement this tutorial on something other than a single system, it is up to you to determine the correct path names for all of the files. k. Enter the password (the one you chose in step f) and click the "Update #XAPCTRL file" button. This updates the XAP Control File. Note: The XAP Control File controls the parameters that are used in the eComet tutorial. For your own XAP applications, we suggest that you develop your own control file structure. l. You are now ready to run the eComet tutorial. Here's how to start. From your web browser, enter the following URL: http://127.0.0.1/xap/tutorial m. As you work your way through the tutorial, you will encounter many hyperlinks to compiled Internet Basic programs. YOU MUST COMPILE THESE PROGRAMS YOURSELF. We're releasing source code only. For example, in Lesson 1 you will see a link to the "HELLO" program. The source program is named XHELLO, XGI. Using Comet2000 (and not the web browser), compile this program and verify that the object program has been placed in the XAP directory on your system. Once the "HELLO" program has been compiled, the link in Lesson 1 will work. The same holds true for all of the other hyperlinks to the sample programs. n. Many of the sample programs rely on two Comet subprograms, so it's a good idea to compile these as soon as possible. Here are the program names: Source Object ------------- ------------ XHEADER , XGI HEADER, XAP XPAGETOP, XGI PAGETOP, XAP See Lesson 1 for more information about these programs. o. Another handy program is the DIRCAT utility. The source name is XDIRCAT, XGI and the object name is DIRCAT, XAP. Compile this program and run it as follows: http://127.0.0.1/xap/dircat The DIRCAT program displays the contents of any directory on your Comet2000 system. There are two "bonus" features in DIRCAT: 1. When DIRCAT displays the contents of the XAP directory, it automatically builds hyperlinks to all object programs in that directory. Thus, DIRCAT becomes a "launching pad" for all of your eComet programs. 2. When DIRCAT encounters a keyed file with a record size and 94 and a key size of 7 (in any directory), it assumes that this is a Comet Editor (CED) file and automatically builds a hyperlink to display the contents of this file on the web browser. The hyperlink is to an eComet program named CEDPRINT, XAP. The source program is named XCEDPRIN, XGI. To use this feature in DIRCAT, compile the XCEDPRIN program. Note: There are some places where this feature does not work. For example, if the source file name contains certain special characters (#, for example), the resulting hyperlink is ignored by the browser. Even though DIRCAT is a useful program, we don't recommend using it on a production eComet system. See the "Security" lesson for further information. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - What's New January 24, 2002 Renamed MTB to Internet Basic (in source programs and HTML documents). February 14, 2001 Updated XDEMO7G and XDEMO7J to include a warning note about the limitation of trying to pass too much data from a textarea field (on a form) to eComet. This is a limitation of METHOD=GET, not a limitation of eComet, and the warning message recommends using METHOD=POST for passing data from a web form to eComet. Also updated the above programs, along with XDEMO8G and XDEMO8J to use WRAP=HARD for the textarea fields. Updated lesson 8 (8.htm) and the information page about textarea fields (textarea.htm), and updated the main page for the tutorial (panel.htm) to include a version number and most recent copyright date. December 7,2000: Fixed a problem with the TUTORIAL.ZIP file. In the July 21 version of this file, four files were placed in the root directory rather than the \ecomet\tutorial\ subdirectory. The files are INDEX.HTM, INSTALL.HTM, PANEL.HTM, and 7.HTM. If you installed the tutorial from the July 21 release, it would not run because the tutorial engine was not able to find one of the main files used in every lesson of the tutorial (PANEL.HTM). July 21, 2000: Updated TUTORIAL.ZIP (added bubble text to PANEL.HTM for convenience, added XAP logo and link to PANEL.HTM, updated INDEX.HTM, added information to INSTALL.HTM about XAP and COS being configured in first 50 DABs, added information to 7.HTM about LUNs 1 and 2 being opened by eComet and correced information about the name of the CGI Interface File). Made XGI0004.ZIP (corrected CGI Interface File name code in the XCGIFILE program).