========================================================================= G C O S - 8 C O B O L W O R K B E N C H v1.4.51 32bit RELEASE ========================================================================= OPEN-CLIENT-TOOLKIT =================== TABLE OF CONTENTS ================= INTRODUCTION Client DSA Client Interface EXAMPLES OTC Configuration TPCLI Command CCI Considerations INTRODUCTION ============ The Open Client Toolkit (OCT) for G8WB provides a mechanism for connecting - various Client applications - various Terminal Emulators to TP8 within G8WB. The principle of OTC is as follows: Client Application <-> Client or Emulator Interface <-> G8WB TP8 or DSA Client DSA provides a generic interface, which make G8WB 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 G8WB 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 G8WB 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, and must be installed first, unless you already use Host Links from G&R. G&R/Ggate - A DSA Gateway for GCOS 8 Only WIndows NT version can be used with G8WB 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 G8WB. Ggate is normally used to provide Glink/Gweb with outgoing DSA sessions used to connect to GCOS 8, but in this case it works in the reverse direction. It allows incoming DSA sessions to connect to G8WB TP8. G8WB 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 G8WB 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 Windows NT PC, where Ggate is installed, will act as a Gateway between the DSA session and G8WB 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 (where Ggate is running) and a remote DSA node p150_rfc. sc p150 rsc p150_rfc -scid p150 -ts p150_rfc ts p150_rfc -class 0 -ns localhost -tp rfc tp rfc -who gar W8GLAPI ------- Ggate provides a 'listen' mechanism, which can trigger launch of the W8GLAPI 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 g8wb -ext -lim 1 -cmd 'g8wb' is the mailbox to listen and handle connection for. The syntax is: W8GLAPI [args] publicname -ln -mn mailbox -li dsa [gline args] 'W8GLAPI' is the program launched when connection is detected. 'args', which is optional, has following options: [debug|debugall] [noetx|nodialog] 'debug', trigger creation of a debug file under \SERVERS\.gli\.log. 'debugall', trigger creation of a debug file under \SERVERS\.gli\..log. 'noetx' may be used to suppress ETX from TP8 messages. 'nodialog' may be used to suppres TP8 dialog and ETX from TP8 message (used by WEB8). 'publicname' must be the same as CC-PUBLICNAME: as configured under [REMOTE-DEFAULTS] in the G8WB.CFG file (case sensitive). 'mailbox' must be the same as specified in '-mn mailbox', ex. g8wb. '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 g8wb -ext -lim 1 -cmd w8glapi debug PRO150 -ln -mn g8wb -li dsa -t_ -s_ -d_ Here's an example of a connection through Glink: Communication interface = Windows Sockets IP address/Host = Ggate Server Host = G8WB Host mailbox = G8WB Host node = P150_RFC Mailbox ext = MAST (optional Lid) Terminal emulation is controlled by G8WB 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 g8wb -lim 1 -cmd 'g8wb' 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 (case sensitive). 'mailbox' specifies the name of the CPIC.CFG Node entry, it can be the same as specified in '-mn mailbox', ex. g8wb. 'lid' may optionally be specified. Here's a full example: listen -mn g8wb -lim 1 -cmd w8ldsa debug PRO150 g8wb MAST W8LDSA use CPIC interface, and mailbox details must be amended in the CPIC.CFG configuration as follows: * Define 'local' G8WB destinations node g8wb -li dsa -ln -mn g8wb -s_ -user -dbg on Here's an example of a connection through Glink: Communication interface = Windows Sockets IP address/Host = Ggate Server Host = G8WB Host mailbox = G8WB Host node = P150_RFC Terminal emulation is controlled by G8WB 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. 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 G8WB is TPLocG8WB and the default lid is MAST. Once the TPTTY process and G8WB 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 G8WB or you can use ESC-key in the G8WB 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 G8WB via OTC TPTTY is implemented as 'single session', meaning one TPTTY process may connect to one G8WB 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 G8WB 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 G8WB - Invoke TM001 transaction (part of G8WB Samples) - Supply the name 'Rice Warren' - terminate TM001 - Disconnect (shutdown) G8WB 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 G8WB in a Client- Server environment, where one client process execute a standard terminal emulation and one server process execute TP8. TPCLI use G8WB configuration (REMOTE-DEFAULTS). TPCLI command is started with: WB W8 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 MFWB or OSX 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 ------ If you have not installed Micro Focus Workbench with TCP/IP for CCI, you need to update your MFWB installation as follows: - Copy CCITC32.DLL into \cobol\exedll - Setup 'mfcobol' port for TCP/IP communication Execute CCISEDIT (under $g8wbgdir\site\client\cci) with CCISEDIT \winnt\system32\drivers\etc\services mfcobol 86/udp This will update your SERVICES file with the known mfcobol port (above is example for Windows NT). 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 Debug ----- CCI-debug (ref. configuration above) writes a trace to the file 'ccitrace.log' in current directory. ========================================================================= GCOS-8 COBOL Workbench is a trademark of B & C Solution Sarl. All other trademarks and trade names belong to their respective companies. ========================================================================= Copyright (C) 1991-1999 B & C Solution Sarl. All Rights Reserved.