========================================================================= 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 ========================================================================= OPEN-CLIENT-TOOLKIT =================== TABLE OF CONTENTS ================= INTRODUCTION Client DSA Client Interface EXAMPLES OTC Configuration TPCLI Command CCI Considerations DISCLAIMER INTRODUCTION ============ The Open Client Toolkit (OCT) for MFE8/NE8 provides a mechanism for connecting - various Client applications - various Terminal Emulators to TP8 within MFE8/NE8. The principle of OTC is as follows: Client Application <-> Client or Emulator Interface <-> MFE8 TP8 or DSA Client DSA provides a generic interface, which make MFE8 TP8 present itself as a DSA node. It is based on software components from G&R - provider of Glink, Host Links etc. G&R software is is available from BULL or local distributor. Client Interface provides a programmatic interface, which make MFE8 TP8 accessible from a Program written using either of two techniques: - Native Client-protocol using CCI - Simplified Client-protocol using DLL The TPCLI command, which is using Client Interface, provides the standard MFE8 terminal emulation in a separate Client. OCT is based on Common Communication Interface (CCI) from Micro Focus, a universal inter-process communication protocol. Client DSA ========== Client DSA is based on following software components from G&R, which must be installed first, unless you already use Host Links from G&R. G&R/Ggate - A DSA Gateway for GCOS8 Only WIndows NT version can be used with MFE8 A System license (number of sessions) or a Corporate license (number of users) exist. G&R/Gline API - Run-time library to support W8GLAPI run-time One license per session G&R/CPIC-C API - Run-time library to support W8LDSA run-time One license per session Note: You can choose either Gline API or CPIC-C API run-time depending on whether you use W8GLAPI or W8LDSA for interfacing with MFE8. 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 MFE8 TP8. MFE8 appears as a DSA node that can be accessed: - directly, ex. Glink, Gweb - indirectly via DNS, ex. VTD/X, UVTI OCT provides three gateway programs to connect a DSA session to MFE8 TP8, under $g8wbgdir\site\client\ldsa\: W8LDSA.EXE - Interface program using CPIC-API and CCI W8GLAPI.EXE - Interface program using GLAPI and CCI W8GLAPIE.EXE - Interface program using GLAPI and CCI (EBCDIC) Either of these interface programs must be installed and configured under Ggate. Note: The following Ggate releases are supported: 5.2.1 and 6.0.2. Note: The Windows PC/Server, where Ggate is installed, will act as a Gateway between the DSA session and MFE8 TP8. Ggate configuration ------------------- The DSA.CFG configuration must be amended with information on local and remote DSA nodes. Following example illustrate a local DSA node p150 and a remote DSA node p150_rfc specifying the IP address of the Ggate PC/Server. sc p150 rsc p150_rfc -scid p150 -ts p150_rfc ts p150_rfc -class 0 -ns localhost -tp rfc tp rfc -who gar To make a connection to the remote DSA node, which is actually a local node acting as gateway, you specify the IP address or name of the Ggate PC/server, the remote node and a mailbox. For Bull GTEA connections, you must amend the following special remote DSA node: rsc gtea -scid $tea -ts p150_rfc W8GLAPI ------- Ggate provides a 'listen' mechanism, which can trigger launch of the W8GLAPI program, whenever a connection is requested for a mailbox on the remote node. The CONFIG.DSA file must be amended to include a 'listen' entry as follows: listen -mn MFE8 -ext -lim 1 -cmd 'MFE8' is the mailbox to listen and handle connections for. The syntax is: W8GLAPI [options] publicname -ln -mn mailbox -li dsa [gline args] 'W8GLAPI' is the program launched when connection is detected. 'options' are optional, the following options are available: DEBUG|DEBUGALL - where debug trigger creation of a single debug file under \SERVERS\.gli\.log - where debugall trigger creation of a debug file per session. "tx" - may be used to trigger a logon transaction when a session is established, ex. "VLOGO" will run the tx = VLOGO. NODIALOG - may be used to suppress the connect/hello messages from TP. NOETX - may be used to suppress ETX, which is otherwise appended to messages sent to/from TP. 'debug', which is optional, trigger creation of a debug file under \SERVERS\.gli\.log. 'publicname' must be the same as CC-PUBLICNAME: as configured under [REMOTE-DEFAULTS] in the G8WB.CFG file. 'mailbox' must be the same as specified in '-mn mailbox', ex. MFE8. 'gline args' may optionally be specified, ex. -d_ will trigger Gline debug file creation. Here's a full example (all on one line): listen -mn MFE8 -ext -lim 1 -cmd c:\gar\bin32\w8glapi.exe debug PRO150 -ln -mn MFE8 -li dsa -t_ -s_ -d_ Note: A full path may be used to ensure the w8glapi.exe can be found, otherwise current PATH setting is used for retrieval. Here's an example of a connection through Glink: Communication interface = Windows Sockets IP address/Host = P150 (Ggate Server name or IP-adr) Host = MFE8 Host mailbox = MFE8 Host node = P150_RFC Mailbox ext = MAST (optional Lid) Terminal emulation is controlled by MFE8 configuration, so you must ensure you are using the same terminal emulation in the client. Note: For IBM3270 emulation, W8GLAPI will run in ASCII mode. If you need EBCDIC mode (depending on client), you must use the W8GLAPIE program instead. W8LDSA ------ Ggate provides a 'listen' mechanism, which can trigger launch of the W8LDSA program, whenever a connection is requested for a mailbox. The CONFIG.DSA file must be amended to include a 'listen' entry as follows: listen -mn MFE8 -lim 1 -cmd 'MFE8' is the mailbox to listen and handle connection for. The syntax is: W8LDSA [debug] publicname mailbox [lid] 'W8LDSA' is the program launched when connection is detected. 'debug', which is optional, trigger creation of a debug file under \SERVERS\.gli\.log. 'publicname' must be the same as CC-PUBLICNAME: as configured under [REMOTE-DEFAULTS] in the G8WB.CFG file. 'mailbox' specifies the name of the CPIC.CFG Node entry, it can be the same as specified in '-mn mailbox', ex. MFE8. 'lid' may optionally be specified. Here's a full example: listen -mn MFE8 -lim 1 -cmd w8ldsa debug PRO150 MFE8 MAST W8LDSA use CPIC interface, and mailbox details must be amended in the CPIC.CFG configuration as follows: * Define 'local' MFE8 destinations node MFE8 -li dsa -ln -mn MFE8 -s_ -user -dbg on Here's an example of a connection through Glink: Communication interface = Windows Sockets IP address/Host = P150 (Ggate Server name or IP-adr) Host = MFE8 Host mailbox = MFE8 Host node = P150_RFC Terminal emulation is controlled by MFE8 configuration, so you must ensure you are using the same terminal emulation in the client. Note: For IBM3270 emulation, W8LDSA will run in ASCII mode. If you need EBCDIC mode (depending on client), you must use the W8GLAPIE program instead. National Characters ------------------- Communication with TP as adapted in accordance with the CHARACTER-SET-ADJUST setting in G8WB.CFG, and national characters are thus communicated using GCOS8 standards, except for EBCDIC mode, where you should use DEF keyboard and international character set. Client Interface EXAMPLES ========================= A number of example Client Interface programs are provided under $g8wbgdir\site\client: \cobol - Examples written in MF-Cobol \cobol\TPTTY - Simple TTY interface using native protocl \cobol\TOCTDLL - Simple test using DLL interface \c - Examples written in C \c\TPTTY - Simple TTY interface using native protocl \c\TOCTDLL - Simple test using DLL interface \pb - Examples written in Powerbasic \pb\TOCTDLL - Simple test using DLL interface All examples are pre-generated into EXE files. TPTTY Example ------------- TPTTY implements a simple TTY interface to TP8. TPTTY connect to TP8 using a 'publicname' and a 'lid'. The default publicname for TPTTY and MFE8 is TPLocG8WB and the default lid is MAST. Once the TPTTY process and MFE8 process is connected, you can type commands to TP8 and responses from TP8 are logged back. Since TPTTY is using a TTY protocol, only line-oriented transaction will work correctly. Both TPTTY and TP8 are closed with $TERM command. Note: $ESC command may be used to trigger TP Escape within MFE8 or you can use ESC-key in the MFE8 window to trigger TP Escape. Following command line options may be given to TPTTY: -p publicname or /p publicname -l lid or /l lid -m cci-module or /m cci-module (CCIDDE or CCITCP) -t NNNN or /t NNNN (timeout-secs) -r NNNN or /r NNNN (timeout-retry) -d or /d (CCI-Debug enable) Only CCIDDE (local pipe) and CCITCP (networked TCP/IP) are implemented, however other protocols are available depending on the OS environment. A Client Interface program thus consist of two parts: 1) Own developed interface to Client application 2) Interfacing with MFE8 via OTC TPTTY is implemented as 'single session', meaning one TPTTY process may connect to one MFE8 process, however, a Client Interface Program may also be implemented as 'multi session', meaning multiple client applications can connect to Client Interface Program, which in turn route each session to one MFE8 process. For 'multi-session' you need to use ASYNCH instead of SYNCH technique towards CCI. TOCTDLL Example --------------- TOCTDLL implements a simple session as follows: - Connect to MFE8 - Invoke TM001 transaction (part of MFE8 Samples) - Supply the name 'Rice Warren' - terminate TM001 - Disconnect (shutdown) MFE8 The W8OCTDLL.DLL is shipped in $g8wbdir\exedll. You need to make sure the DLL can be found via PATH, if not executed from Micro Focus command prompt. COBOL Examples -------------- When you execute COBOL example programs, you must run from a Micro Focus command prompt, as these are linked for shared run-time. Use of standard copies are shown in the example programs. C Examples ---------- LIB files are provided for CCI and W8OCTDLL. PowerBasic Examples ------------------- Standard INC file is provided for W8OCTDLL interface. OTC Configuration ================= The TERMINAL-EMULATION configuration within Default Configuration (G8WB.CFG) is used to configure operation in 'Client' mode. This is done as follows: TERMINAL-EMULATION : DKU71XX REMOTE The 'REMOTE' argument will trigger TP8 operation to use OTC for communication with the Client. Additional new configuration entries may be placed under REMOTE- DEFAULTS in Default Configuration (G8WB.CFG). [REMOTE-DEFAULTS] CCI-MODULE : CCITCP ; CCIDDE(default) or CCITCP CCI-PUBLICNAME : PRO150 ; Public name of TP8, default TPlocG8WB CCI-DEBUG : ON ; OFF(default), ON CCI-TIMEOUT-SECS : 30 ; Default is 120 CCI-TIMEOUT-RETRY : 3 ; Default is 1 Note: You must use the same CCI protocol in Client Interface program as you have configured for 'REMOTE'. TPCLI Command ============= The TPCLI command may be used to execute standard MFE8 in a Client- Server environment, where one client process execute a standard terminal emulation and one server process execute TP8. TPCLI use MFE8 configuration (REMOTE-DEFAULTS). TPCLI command is started with: RUN WB TPCLI or RUN TPCLI CCI Considerations ================== Please refer to 'Micro Focus Object COBOL - Programmer's Guide to Communication' manual for details on CCI. TPTTY/TOCTDLL ------------- CCI run-time is using CCIDE32.DLL or CCITC32.DLL, and this/these must be installed unless Mainframe Express or Application Server is installed on the PC where TPTTY (or your own Client Interface Program) is executed. You find these DLL files under $g8wbgdir\site\client\cci. Copy the files to a directory included in your current PATH setting or include above directory in your PATH setting. TCP/IP ------ For TCP/IP, CCI requires a 'Registration Server' is running somewhere on your network (or your local PC). You find the 'Registration Server' program in $g8wbgdir\site\client\cci\CCITCP2.EXE. Only one server is required for a complete TCP/IP network. For Client's using CCITCP, the environment setting CCITCP2 designate where the 'Registration Server' is running, ex. CCITCP2=PRO150 If error occur during CCI operation, error messages are written to ccierr.log under current directory. CCI-debug (ref. configuration above) writes a trace to the file 'ccitrace.log' in current directory. TCP/IP FIXED PORTS ------------------ The CCI Registration Server utilizes port 86/UDP to service requests and additional ports (from 2000 and up) to map the various CCI servers. If this technique is undesirable for your network, you may configure fixed port assigments for the CCI servers, and run without any Registration server. For CCI servers, ex. TPLocG8WB, use an environment setting as follows: CCITCPS_TPLocG8WB = MFPORT:4001 For CCI clients, use an environment setting as follows: CCITCPT_TPLocG8WB = MFNODE:,MFPORT:4001 where mfnode designate the name or ip-adr where the CCI server is running. 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.