========================================================================= G C O S 8 M A I N F R A M E E X P R E S S v2.5.04 G C O S 8 N E T E X P R E S S v4.0.04 Windows NT/2000/XP RELEASE ========================================================================= WEB8 SUPPORT NOTES ================== TABLE OF CONTENTS ================= INTRODUCTION MIGRATION REQUIREMENTS INSTALLATION $WEB8/HTTP COMMAND DOCS COMMAND HTTPECHO COMMAND WEB8 RUN-TIME WEB8-IDE HINTS & TIPS KNOWN LIMITATIONS/ERRORS DISCLAIMER INTRODUCTION ============ This document describes features specific to WEB8 Support. This information will later be included in the MFE8 documentation set. MIGRATION ========= n/a REQUIREMENTS ============ WEB8 Support in MFE8 can be used either with Browser connection through a Bull HTTP-DSA Gateway, GEAP or other compatible gateway, or with Browser connection through the embbeded CGI interface. Embedded CGI Interface ---------------------- The embedded CGI interface may be used to establish a Browser connection to MFE8 running TP8 emulation. The CGI program will establish an emulated DSA session with MFE8 using standard TCP/IP protocol. The embedded CGI interface is, however, not fully compatible with connection via standard gateways. The minimum requirements are: - Windows 95, 98, NT or 2000 - TCP/IP communication protocol - A Personal or Internet Web Server Note: GEAP operation mode may be emulated. Standard Gateway interface -------------------------- The standard gateway interface may be used to establish a Browser connection to MFE8 running TP8 emulation, through a DSA session. The DSA session is handled through Open-Client-Toolkit of MFE8, which utilize Ggate software from G&R. The minimum requirements are: - Windows 95, 98, NT or 2000 (for MFE8) - Ggate (and GlAPI run-time) software from G&R - Windows NT or 2000 (for Ggate) - TCP/IP communication protocol Note: If you currently use Ggate on Unix, or you currently don't use Ggate, you need to acquire a minimum license (5 user) for Windows NT or 2000. INSTALLATION ============ WEB8 Support is an optional part of MFE8 release V2.5.01. WEB8 Database ------------- The WEB8 Database (HTMLSchema) must be initialized. The command file $g8wbgdir\web8\support\syshtml.cf may be used to load the standard html documents as follows: DOCS_DEFAULT.HTM DOCUMENT_NOT_FOUND.HTM GCOS8.HTM HTTPFORM.HTM SETBASE.HTM CUSTOMER_DEFAULT_LOGON.HTM Example: RUN WB Q2UT htmlschema initial _a all RUN WB HTTP comm $g8wbgdir\web8\support\syshtml.cf TCP/IP Communication -------------------- MFE8 utilize Common-Communication-Interface (CCI), which is part of Micro Focus Workbench, to communicate either between the DSA session (Open-Client-Toolkit) or the CGI interface program. CCI in turn utilize TCP/IP communication protocol. You need to setup CCI in both ends, i.e. the PC Workstation where MFE8 us running and the PC Workstation/Server where Ggate or the CGI program is running. CCI communication use a 'Publicname' to find a correspondent, and a CCITCP Registration Server is used to map the publicname to an IP address. PC Workstation with MFE8: CCI is setup during MFWB installation. PC Workstation with Personal Web Server: If running alongside MFE8, no further configuration is required. PC Workstation/Server with Web Server: To enable use of CCI, the following setup steps are required. Services: Add the following entry to the SERVICES configuration file, ex. Windows NT C:\WINNT\SYSTEM32\DRIVERS\ETC\SERVICES. mfcobol 86/udp Startup: Create a shortcut to the CCITCP2 Registration Server and include the shortcut in the Startup Folder, so the server is automatically started, or start the server manually or as an NT service. The CCITCP2.EXE program is installed in your scripts or cgi-bin directory of your Web Server. Use 'CCITCP2 /?' to see how to install as an NT service. Environment: Add environment setting CCITPC2=. This setting designate where the CCITCP2 Registration Server is running, ex. SET CCITCP2=MYSERVER PC Workstation/Server with Ggate: Use same technique as Web Server, ref. above. Note: When running CCITCP2 Registration Server on other than the PC Workstation with MFE8, you should change your environment setting for MFE8 as follows: SET CCITCP2=MYSERVER Embedded CGI Interface ---------------------- The CGI interface program(s) must be installed on a Web/HTTP Server and you are thus required to use either a Personal or Intranet Web Server for WEB8 support through CGI interface. Example using Microsoft Personal Web Server: Server directorty = c:\InetPub Server root = c:\InetPub\wwwroot Server scripts = c:\InetPub\scripts (can hold CGI also) You need to install MFE8 CGI programs as follows: copy $g8wbgdir\WEB8\CGI\*.* c:\InetPub\scripts Example using Microsoft IIS 4.0 Internet Server: Server directorty = c:\InetPub Server root = c:\InetPub\wwwroot Server scripts = c:\InetPub\wwwroot\cgi-bin You need to install MFE8 CGI programs as follows: copy $g8wbgdir\WEB8\CGI\*.* c:\InetPub\wwwroot\cgi-bin The standard format for a GCOS8 URL http://gateway/node.mbx/0// cannot be used, instead the field must specify the location of the CGI interface program, ex. http://myserver/scripts/cgig8wb.exe/node.mbx/0// ---------------------------- To use CGI interface you need at least one HTML page on the Personal Server to launch the initial WEB8 transaction. Alternatively you can enter the adapted URL to launch the WEB8 transaction. This represent ONLY a minor problem, provided you use 'relative' URL and 'BASE' technique as recommended with WEB8. The information is not directly used by CGI interface, whereas information is used as the CCI-PUBLICNAME to connect to MFE8. If your Web Server support virtual directories, you can minimize the differences in the URL by defining a virtual directory with the name , and redirect this to the CGI interface program, ex. Create virtual directory = dpst.testtp and change properties as follows: Set 'A redirection to a URL' Set 'The exact URL entered above' Set 'Redirect to' = 'http://myserver/scripts/cgig8wb.exe/$V' this would allow you to use the following URL instead: http://myserver/dpst.testtp/0/docs/gcos8.htm -------------------- When the URL is launched, the CGI interface will attempt to connect to MFE8 using the as public name, ex. testtp, and your MFE8 configuration should thus specify: [WEB8-DEFAULTS] CCI-PUBLICNAME : testtp ; Name is case sensitive If the connection fails, i.e. MFE8 is not started, an error message is send to your browser, ex. CGI-Gateway failure Function: DSA-CONNECT Publicname: testtp CCI-INITCLIENT failed-A CCITCP call has timed out Standard Gateway interface -------------------------- When connecting through HTTP-DSA Gateway, GEAP or other compatible gateways, the gateway will establish a DSA session towards GCOS8, ex. GEAP will establish such session through GTEA. MFE8 use Ggate to capture such connection requests and route the DSA session towards MFE8 instead of GCOS8. Ggate is normally used to provide Glink/Gweb with outgoing DSA sessions used to connect to GCOS8, but in this case it works in the reverse direction. It allows incoming DSA sessions to connect to TP8 within MFE8, ref. $g8wbgdir\site\client\otc.txt for further details. Ggate configuration: The DSA.CFG configuration is used to define DSA nodes - a local node and one or more remote nodes. Following example illustrate a local DSA node p150 (where Ggate is running), a remote DSA node p150_rfc and and a special entry required by GTEA. sc p150 rsc p150_rfc -scid p150 -ts p150_rfc ts p150_rfc -class 0 -ns localhost -tp rfc tp rfc -who gar rsc gtea -scid $tea -ts p150_rfc A URL to connect through GEAP specifies the DSA Node, ex. http://mygeap:8080/p150.testtp/0/docs... and Ggate will accept the DSA session requested for the p150 node. Listen configuration: The CONFIG.DSA configuration is used to define the mailboxes within the DSA node and the action to be taken when a connection request is received. Following illustrate mailboxes used for connection to WEB8 within MFE8: listen -mn testtp -ext -lim 5 -cmd w8glapi nodialog testtp -ln -mn testtp -li dsa -t_ -s_ listen -mn mytp1 -ext -lim 5 -cmd w8glapi nodialog mytp1 -ln -mn testtp -li dsa -t_ -s_ listen -mn mytp2 -ext -lim 5 -cmd w8glapi nodialog mytp2 -ln -mn testtp -li dsa -t_ -s_ The 'w8glapi' program is provided with MFE8 and should be copied with CCI programs, ref. above, to the Ggate PC Workstation/Server. The files are located under $g8wbgdir\site\client\ldsa. A connection to either testtp, mytp1 or mytp2 will thus launch the w8glapi program and route all communication for the DSA session through this. W8glapi program will in turn establish a session towards MFE8 using the 'publicname' specified after nodialog, ex. testtp (normally the same name as the mailbox). Since multiple MFE8 developers may be utilizing the same Ggate, mailboxes and publicnames should be configured to allow multiple TP8 test systems concurrently. The '-lim n' arguments defines the maximum number of concurrent sessions for the mailbox, and this should be higher than 1 since GEAP can/will establish more than one session towards TP8. You need to increase this number if sessions are left open by the application, otherwise new connections are refused until existing connections are timed-out by GEAP. Note: 'nodialog' argument is required for WEB8 connections to avoid connection dialog and ETX for the DSA session. $WEB8/HTTP COMMAND ================== The functionality of $WEB8 command on GCOS8, has implemented as Forms within MFE8 (not a TP8 command). When Forms is launched, MFE8 provides the $WEB8 functionalities - Import, List, Refresh, Delete and Command through a new utility. The $WEB8 functionality is also available from command files through the HTTP command, ex. RUN WB HTTP The $WEB8 functionality is also partially available through a browser via 'docs/httpform.htm'. The WEB8 database is non-shared (local database), like other application databases, and you use MFE8 Forms or other technqiues to maintain documents (HTML or images). The database may be backed up to a global backup-set, and thus restored by other MFE8 developers as required. Import ------ When importing documents (HTML, images etc.) you specify the URL of the file, ex. //localhost/myumc/myhtml/demo1.html //myserver/demo1.html //myserver/images/logo.gif - Localhost files are accessed through VMPS configuration, which map GCOS8 catfile-string syntax to actual placement of the file on a PC Workstation or Server. - Localhost files are limited to 'text/html' type. Optionally you may specify the document name (Save as name). By default the last name of the URL is used as the document name. - The document name is stored in upper-case in the WEB8 database. Optionally you may specify a proxy server, if access to URL requires going though a proxy server, ex. MYPROXY, MYPROXY:8080. The HTML syntax is scanned for actiontag = WEB8. The HTML syntax is scanned for 'include' syntax. Note: For MFE8 only, you can specify a instead of a URL, ex. $g8wbgdir\web8\support\gcos8.htm. List ---- You may list the content of the WEB8 database either by specifying a document name, a masked document, a URL or a masked URL. The wildcard character * may be used to mask either document name or URL. Refresh ------- You may refresh the content of the WEB8 database either by specifying a document name, a masked document, a URL or a masked URL. The wildcard character * may be used to mask either document name or URL. Refresh will re-import the document (HTML, image etc.) if the source URL has changed (Last-modified) since import. Note: Changes to 'includes' are not detected by refresh. Delete ------ You may delete documents from WEB8 database either by specifying a document name, a masked document, a URL or a masked URL. The wildcard character * may be used to mask either document name or URL. Command ------- You may execute a series of command by specifying a URL for a text file containing Import, List, Refresh and Delete commands. Note: Command files cannot be nested. Note: For MFE8 only, you can specify a instead of a URL, ex. $g8wbgdir\web8\support\syshtml.cf. Command line ------------ Forms may be launched from command file BAT as follows: RUN WB HTTP Forms may be launched from command file CBT as follows: HTTP The command syntax is as follows: IMPO[rt] url [-SA documentname] [-P proxyname[:port]] LIST [documentname|url] - wildcard * allowed - default * REFR[esh] documentname|url [-P proxyname[:port]] - wildcard * allowed DELE[te] documentname|url - wildcard * allowed COMM[and] url Browser ------- You may use a URL '.../docs/httpform.htm' for maintenance of WEB8 database through a browser. DOCS COMMAND ============ The DOCS command has been implemented as a TP8 command like on GCOS8. HTTPECHO ======== HTTPECHO may be used to document a browser request, either by specifying HTTPECHO as the command in the request, or changing TP8 configuration so HTTPECHO is made the first TPR for a command. The information is logged on the TP Journal. WEB8 RUN-TIME ============= MFE8 use dynamic linking, meaning you only need to check a TPR to be able to execute or animate it, whereas on GCOS8 you would link your WEB8 TPR with a run-time wrapper (WEBLIB), to enable WEB8 run-time support before execution of your TPR logic. For MFE8, the "FORMS-SOFTWARE : W" setting will trigger load of WEB8 run-time support, and your TPR will dynamically link to the various run-time services as required. During TP8 startup, MFE8 will also verify you have "TERMINAL-EMULATION : WEB8" setting. TP8 Execution ------------- When you start TP8 - animate or run in GUI or non-GUI mode, the TP8 status window will show execution steps and it may also be used to request the escape menu. Once TP8 is operational, the following menu is shown: Waiting for HTTP-DSA Session connection ... Use Escape to get Escape-menu By pressing the Escape key you can request the TP8 Escape menu, like in a terminal emulation window. The Escape menu may be used to terminate TP8, abort a transaction in conversation, view TP Journal etc. When a Browser request arrive, the following message is given. -> Connect HTTP-DSA session=0001361824 Accepting Session input ... While executing the transaction, status messages may be shown, ex. Executing ... When the transaction completes - conversation or end of transaction, the following message is given. Waiting for HTTP-DSA Session connection ... Use Escape to get Escape-menu -> Disconnect HTTP-DSA session=0001361824 If the Web page has image references, and these are stored in the WEB8 database, then one or more interactions follow as the browser request download these images. When connecting through GEAP, multiple sessions may be connected concurrently, either because these are left open by the application or GEAP is requesting download of documents (HTML or images) through the $GEAP command. Note: MFE8 will treat all input as coming from the same Lid, so care must be taken when using conversational transactions. Emulated GEAP ------------- If your are not connecting through GEAP, but would like WEB8 to behave as if you were connected through GEAP, you can enable GEAP emulation through configuration, ex. [WEB8-DEFAULTS] GEAP-EMULATION : ON With GEAP emulation enabled, HTTP_CONTENT_TYPE will behave as if a GEAP connection was active and setup GEAP request headers. MFE8 will parse the HTTP header during send operations and detect remote form requests, and will trigger a send of HTML after any sends from the application (read and send named page from WEB8 database). WEB8 Database ------------- During TP8 execution the WEB8 Database is used ONLY to retrieve documents (HTML or images). If WEB8 database maintenance is restricted to an administrator(s), you can use a shared WEB8 database instead. Example of configuration: ; Number Location Location [Perm Concurrent Protect] ; (1-99) Schema files [R/W OFF/ON/FS2 OFF/ON/FULL] [SCHEMA-SECTION] HTMLSchema : 18 CURRENT $G8WBDDIR\DBMS R OFF OFF ; WEB8 BIBO Recording/Playback ----------------------- The BIBO Recording and Playback feature may be used during execution of WEB8 transactions. When attaching a BIBO output file, MFE8 will record both input and output messages for WEB8 transactions, until detached or TP8 is terminated. When running a BIBO input file, MFE8 will re-execute the WEB8 transactions from the recorded input messages. Such messages may be edited (ref. format above) to produce new/changed test cases, going through the Browser. The output messages to the Browser are ignored, however they will be recorded if a BIBO output file is attached during re-execution, and will be trace in TP8 Journal also. WEB8-IDE ======== The WEB8-IDE, and Windows application integration various tools and synchronization features for GCOS8, can be used ASIS with MFE8, however, the GCOS8 synchronization feature is less relevant, if you plan to test your Web8 application within MFE8. WEB8-IDE maintains both a PC and Host directory of components - TPRs, Copies, HTML, Images and Applets, and you can use the PC structure as the basis for your MFE8 environment. A new Host emulation utility (IDE8) is now provided with MFE8, and this may be used to obtain a better integration of MFE8 and WEB8-IDE. You are no longer required to be connected to GCOS8, and publish operations are performed locally in the MFE8 environment. Note: WEB8-IDE is using GTEA for host connection, and the new IDE8 utility is working much like 'Standard Gateway interface' described above. To use WEB8-IDE in a Host emulated environment, WEB8-IDE must be configured differently. FTP Connection -------------- An FTP-Server - local on PC or shared via LAN, is used instead of the GCOS8 FTP-Server, and is thus used for storage of the GCOS8 component structure. IP addr: name or IP address of the FTP-Server, ex. localhost UserID : anonymous (or explicit userid and password) TSS Connection -------------- Ip addr: name or IP address of Ggate, ex. localhost Mailbox: name of mailbox (within Ggate), ex. TssWks Dest SC: name of host node (within Ggate), ex. p150 Resp1 : TSS (used as indication of TSS connection) Note: System Security Manager is optional, if set it is ignored. WKS Connection -------------- Ip addr: name or IP address of Ggate, ex. localhost Mailbox: name of mailbox (within Ggate), ex. TssWks LID : name of lid (within Ggate), ex. mast Dest SC: name of host node (within Ggate), ex. p150 Resp1 : WKS (used as indication of Workstation connection) Note: System Security Manager is optional, if set it is ignored. Ggate Listen ------------ Add a listen entry in CONFIG.DSA configuration, ref. details above. listen -mn TssWks -ext -lim 5 -cmd w8glapi noetx TssWks -ln -mn TssWks -li dsa -t_ -s_ Ex. TssWks, used to establish both TSS and WKS connection from WEB8-IDE to IDE8 Host emulation utility. IDE8 Utility ------------ The IDE8 Host emulation utility must be started either on your local PC (non-shared) or PC Server (shared), and it is used to accept both TSS and WKS connections. In above configuration examples, both TSS and WKS specify 'TssWks' as the mailbox name. The IDE8 utility is started with the command: RUN WB IDE8 |* [DB [backup-set]] [TPR] Publicname = mailbox name, ex. TssWks * = TSS DB = request processing of $WEB commands against WEB8 Database, i.e. LIST, IMPORT, DELETE Default = ignore all commands Backup-set = request backup of Web8 Database after each update to the given backup-set name Default = no backup May be used to maintain a common Web8 Database, and allow developers to restore 'current' database from the given backup-set name TPR = request compilation (Check) of published TPR(s) Default = no compilation TPRs are compiled from the Host directory The IDE8 utility will show a trace of activities (connections and operations performed) on screen and in the file $g8wbldir\ W8IDE8.LOG. Use ESCape in the command window to terminate. When either DB or TPR option is used, you need to update your VMPS configuration within MFE8, so the Host structure is mapped correctly, ex. [FMS-CONFIG] DEFAULT-PATH : \\localhost\ftproot ; local FTP-Server or WEB8 : \\localhost\ftproot\web8 ; UMC specific mapping MYUMC : F:\myumc ; UMC specific mapping HINTS & TIPS ============ o Special rounded is required, both in TPR and HTML/Javascript, for COMP-11 and COMP-12 (floating point) fields, ref. Bull Web8 documentation for details. o The installation procedure for CGI program as described above, says you need copy all files from $g8wbgdir\WEB8\CGI into your CGI directory under the Web Server. As an alternative implementation technique, you need only copy CGIG8WB.EXE into your CGI directory and have the registry setting point to $g8wbgdir\web8\cgi, so other CGI programs are executed from this directory. Ex. where G8WBGDIR = M:\MFE8G HKEY_LOCAL_MACHINE\SOFTWARE\cgig8wb\AppPath value = m:\MFE8G\web8\cgi\ o CGI Debugging: CGIG8WB will create a temporary input and output file with the message content being passed to/from the Web Server. These files - named GTWxx.TMP and placed in 'temp' directory, are deleted when the request has been processed. For debugging you can disable delete, so you are able to browse the content of these files. Disable is triggered by the presence of a string in the registry as follows: HKEY_LOCAL_MACHINE\SOFTWARE\cgig8wb\TraceApp value= o DSA Debugging: If connection through DSA fails, Ggate provides various trace files, which may be consulted to determine the cause of failure. The W8GLAPI program does NOT send any error messages, however, you may request debug information to be logged, and consult this information to determine the cause of failure. Change the CONFIG.DSA entry as follows: listen -mn testtp -ext -lim 5 -cmd w8glapi debug nodialog ... or listen -mn testtp -ext -lim 5 -cmd w8glapi debugall nodialog ... The 'debug' argument will make W8GLAPI write a debug file under \Servers\.gli\.log. The 'debugall' argument will make W8GLAPI write a debug file under \Servers\.gli\..log. The debug file is a text file with information on DSA session activity (and eny error messages). KNOWN LIMITATIONS/ERRORS ======================== o For HTTP_GET_STRUCT and HTTP_SEND_STRUCT it is assumed that map fields are in ascending data-offset sequence (default for WEB8-IDE), as data-offsets are recalculated due to differences in alignment of COMP-6, COMP-7, COMP-11 and COMP-12 fields (MFE8 use byte alignment for all field types). o Please refer also to limitations described in text above. DISCLAIMER ========== THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. B & C SOLUTION DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL B & C SOLUTION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF B & C SOLUTION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. ========================================================================= GCOS8 Mainframe Express and GCOS Net Express are a trademarks of B & C Solution. All other trademarks and trade names are the property of their respective owners. ========================================================================= Copyright (C) 1998-2003 B & C Solution. All Rights Reserved.