========================================================================= G C O S 8 R E H O S T I N G E X P R E S S v4.0.05 Windows NT/2000/XP RELEASE ========================================================================= RELEASE NOTES ============= TABLE OF CONTENTS ================= INTRODUCTION REQUIREMENTS INSTALLATION INTEGRATION TP8 SERVER TUXEDO/TP8 TXSERIES/TP8 BATCH COMMANDS DATABASE REHOSTING INFORMIX ORACLE IBM DB2 MICROSOFT SQL SERVER DIMS8 ERRORS FIXED & IMPROVEMENTS IN THIS RELEASE TIPS & HINTS KNOWN ERRORS KNOWN LIMITATIONS MANUAL INSTALLATION PROBLEM REPORTING INTRODUCTION ============ This version of GCOS8 Rehosting Express (RHE8) is the Initial Release supporting the Micro Focus Application Server. It is issued on CD-ROM (diskettes available upon request), with limited new documentation. RHE8 includes Micro Focus Application (a run-time version of Mainframe Express, named AS) and a run-time version of the GCOS8 Mainframe Express (MFE8), which may be used to execute GCOS8 applications prepared with MFE8. Most of the features of RHE8 are documented in MFE8, MFE and AS documentation set, however the RHE8 Release Notes and Update Notes provides details on RHE8 specific features and differences from the MFE8 environment. REQUIREMENTS ============ RHE8 use a standard Relational Database System to host the IDS-II database emulation. Following RDBMS software is supported: INFORMIX IDS.2000 Version 9.2 ORACLE 8/8i/9i IBM DB2 UDB Version 7/8 Microsoft SQL Server 7.0/2000 RHE8 may use either the embedded TP8 Server, or a standard Transaction Monitor System ofr TP8 emulation. Following TPMS software is supported: TUXEDO 8.1 TXSERIES 5.1 The embedded TP8 Server is based on Micro Focus Common Communication Protocol (CCI) and will support up to 500 concurrent TP users. INSTALLATION ============ Like MFE8, the installation procedure is separated into a Server and a Workstation installation. o The Server installation is used to setup shared directories and a database Server, to support a number of Workstation users. o The Workstation installation is used to setup a single Workstation for testing of GCOS8 Batch or TP applications. Note: Although the shared directories G8RBGDIR, G8RBDDIR, G8RBFDIR and G8RBDIR are similar to MFE8, they CANNOT be installed into the same directories as MFE8. CD-ROM ------ The RHE8 CD-ROM is structured as follows: RHE8NOTE.TXT - release notes (this document) RHE8\DISK1\SETUP.EXE - start installation of RHE8 RHE8UPD.TXT - update notes RHE8UP\DISK1\SETUP.EXE - start installation of RHE8 update WEBSYNC - Service-, Add- and Fix-packs for Application Server SERVER Installation ------------------- The Server installation must be made first, and is normally only done once. The installation involves the following steps: - install Application Server software - update AS with websync packs (optional) - install G8RE software (includes latest update) The Server installation should be performed on a LAN Server or a PC Workstation dedicated as Server for the RHE8 environment. Application Server Installation ------------------------------- The Application Server installation procedure is quite simple. o Directory: When prompted select a directory for installation of software, ex. \Program Files\Micro Focus\Application Server. o License info: When prompted for license information, you should enter a serial number provided on the software package. Next you may optionally update Application Server with Websync service and fix packs as provided on this CD-ROM. Application Server rely on registry settings setup during installation. RHE8 Installation ----------------- The RHE8 installation procedure is quite simple and similar to installation procedure for MFE8. o Installation type: Select 'Server Installation'. o Global Directory: Target directory for Global files, ex. D:\RHE8G. o Program Directory: Target directory for Program files, ex. D:\RHE8P. o Forms Directory: Target directory for Forms files, ex. D:\RHE8F. o Database Directory: Target directory for Database files, ex. D:\RHE8D. o Select Components: 'Basic' includes support for TPFF. Select other components as required. o Select RDBMS: Select the RDBMS for rehosting of IDS-II. o Folders: Icons are grouped under a default folder 'GCOS8 Rehosting Express'. The default folder name can be changed as required. Following entries area created under the default folder: 'Books' will contain: Getting Started (Help file) 'Notes' will contain: Release Notes (Notepad) Update Notes (Notepad) Open-Client-Toolkit (Notepad) The RHE8 software will now be installed into the specified target directories. Note: Before proceeding with Workstation installation, make sure the G8RB Global, Program, Forms and Database directories can be accessed (shared) from PC Workstations. WORKSTATION Installation ------------------------ The Workstation installation must be made next. This installation must be done on a LAN server or a PC Workstation dedicated as Server for the RHE8 environment. This installation may also be repeated for each PC Workstation, where you want to be able to execute RHE8. The very first Workstation Installation will perform some additional setup of the Server directories. The installation involves the following steps: For separate PC Workstation only: - install Application Server software - update AS with websync packs (optional) For Server or separate PC Workstation: - install RHE8 software (includes latest update) - customize/integrate RHE8 with Application Server Application Server Installation ------------------------------- Ref. above. RHE8 Installation ----------------- The RHE8 installation procedure is quite simple and similar to installation procedure for RHE8. o Installation type: Select 'Workstation Installation'. o License info: When prompted for license information, you should enter a serial number indicated on the CD-ROM, ex. RHE8/BTDM/0201. Your name and company is setup with Windows defaults. o Local Directory: Target directory for local non-shared files, ex. C:\RHE8L. o Global Directory: Reference directory for Global files, ex. F:\RHE8G (network share = F:\ = D:\ on Server PC). o Program Directory: Reference directory for Program files, ex. F:\RHE8P. o Forms Directory: Reference directory for Forms files, ex. F:\RHE8F. o Database Directory: Reference directory for Database files, ex. F:\RHE8D. o Select Components: 'Basic' includes support for TPFF. Select other components as required. o Folders: Icons are grouped under a default folder 'GCOS8 Rehosting Express'. The default folder name can be changed as required. Following entries area created under the default folder: 'Books' will contain: Getting Started (Help file) 'Notes' will contain: Release Notes (Notepad) Update Notes (Notepad) Open-Client-Toolkit (Notepad) 'DB Administration Tools' will contain: IIDS Database Utility Load Database Utility Others icons are: Configuration GCOS8 Customization RHE8 Command Prompt Run TP8 Server Run TP8 Monitor The RHE8 software will now be installed into the specified target directory, and references setup for the shared directories. Upon completion of installation, you are adviced to run two setup steps: Launch CCI Configuration: This is used to setup and configure the CCI communication software. You are prompted for the name of the CCITCP2 Registration Server location (usually the name of the server). Launch GCOS8 Customization: This is used to customize, setup and integrate RHE8 with Application Server. =========== INTEGRATION =========== The RHE8 environment is now fully operational, however, none of your GCOS8 applications components are available within the environment. Your next step is thus to integrate your GCOS8 application components and parts of your configuration from the MFE8 environment. Database integration -------------------- Before integration from MFE8 environment, make sure you have installed MFE8 with RHE-RDBMS option, and that schemas and subschemas have been validated for the RHE environment. The $g8rbddir\DBMS.CFG file must be amended with information from your MFE8 environment. This step must be done manually, i.e. copying from $g8wbddir\DBMS.CFG and pasting into $g8rbddir\DBMS.CFG. The Schema and Subschema file can either be used directly from your MFE8 environment, or copied into $g8rbddir. MFE8 has a Move Schema and Move Subschema function to facilitate this. Note: Existing databases MUST be unloaded with nnHDBU, either from GCOS8 or MFE8 environment. Schema ------ Refer to details under RDBMS. Subschema --------- The Subschema configuration is similar for RHE8 and MFE8. ; Short Location Auto ; name Subschema generated [SUBSCHEMA-SECTION] CLASS : CLASS CURRENT ; example SS-CLASS : 26SCHS CURRENT -AUTO ; example Defaults -------- The Defaults configuration may be slightly different for MFE8, due to the use of a RDBMS database Server. [DEFAULT-SECTION] TP-WAIT-TIME : 30 ; Concurrency wait time in secs This setting specify the time-out before a transaction is aborted (similar to deadlock). Note: TP transactions can be restarted (see TP8.CFG). BATCH-WAIT-TIME : 180 ; Concurrency wait time in secs This setting specify the time-out before a batch program is aborted (similar to deadlock). Note: Concurrency control is done at record level and reservation is exclusive for both read and write. Batch programs should take frequent checkpoints, if executed concurrently with TP. DYNAMIC-DEBUG : OFF ; Dynamic Debug Mode ON/OFF (Drop-in) The Dynamic Debugger (IIDS drop-in) should be OFF, so DB exceptions are passed directly to the application. TP8 Integration --------------- The $g8rbgdir\TP8.CFG file must be amended with information from your MFE8 environment. This step must be done manually, i.e. copying from $g8wbgdir\TP8.CFG and pasting into $g8rbgdir\TP8.CFG. The TP8 configuration is similar for RHE8 and MFE8, except you may want to use some of the optimization features. [CREATE_TP8_EXTENSION] TPR_POOL : 5 RANDOM ; # TPRs (0-25) [FIFO|RANDOM] May be used to cache TPRs and obtain RANDOM use/reuse of TPRs (similar to real TP8 execution). MAXIMUM_STACK : 100 ; Maximum modules within TPR Whenever a TPR is cancelled from memory (fresh copy), MFE8 has to cancel all modules called by the TPR also to obtain similar behavior as TP8 (RHE8 use dynamic linking). RHE8 will keep track of modules called directly or indirectly through a stack. The maximum setting must be sufficient to cope with the maximum number of modules called from an application TPR (application modules only). PROGRAM_CACHE : 25 ; 0-100 program entries May be used to optimize execution, by caching the most used TPRs and or modules in memory. STATISTICS : 500 ; TPR/Module usage entries RHE8 will collect statistics for TPR and module use. The maximum setting must be sufficient to cope with the maximum number of TPR and modules within your application. If overflow occur, this is indicated in the Journal and additional statistics are lost. MAXIMUM_RESTART : 3 ; Maximum deadlock restarts May be used to control how many times a transaction will be restarted in case of concurrency deadlock. A restart will be indicated in a status message on the TP8 screen. [CREATE_TPR] ;TPR or pathname Loaded as resident TPRA MODULEA May be used to load high use TPRs and/or modules resident in memory. The $RDY command will trigger execution of your ready TPRs. For RHE8 (and MFE8) use of ready TPRs are optional. For RHE8 it is not recommended to use ready TPRs (leave out $RDY), since this would force all IDS-II databases to be opened during TP startup. Without ready TPRs, database are only opened when required, i.e. first time a schema is used by the application. RHE8 includes a TP8 Server, which is quite similar to GCOS8 TP8. The TP8 Server (W8TPS) acts as a TP8 Workstation, accepting client connections, either via TP8 Client (W8TPC) or via DSA-Gateway. The TP8 Monitor (W8TP) acts as a TP8 Process, which connect automatically to TP8 Server, and is used to execute the individual transactions. TP8 Monitor(s) may either be launched manually or automatically from TP8 Server. RHE8 use an additional environment setting G8RBSDIR for storage of TP8 swap-files. By default G8RBSDIR = G8RBGDIR setting. Defaults integration -------------------- The $g8rbgdir\G8WB.CFG file must be amended with information from your G8WB environment. This step must be done manually, i.e. copying from $g8wbgdir\G8WB.CFG and pasting into $g8rbgdir\G8WB.CFG. The Defaults configuration is similar for RHE8 and MFE8. Some options may be changed to suit a run-time environment, and mixture of Global and Local configuration may be changed also. Note: Local Defaults configuration file is $g8wbldir\G8WB.CFG. [G8WB-DEFAULTS] ; Defaults configuration SYSTEM-DATE : CURRENT ; CURRENT or YYMMDD SYSTEM-DAY : CURRENT ; CURRENT or YYDDD SYSTEM-TIME : CURRENT ; CURRENT or HHMMSSHS May be used to 'fix' specific data/time for testing. MESSAGE-ID : LAZY ; Default Message-id/Command for TP May used to automatically execute a specific transaction whenever an empty transmit is given. HELLO-MESSAGE : "THIS IS MY OWN TP HELLO" May be used to change TP HELLO message. SPAWN-AUTO-RUN : ON ; Process Spawn automatically OFF/ON May be used to automatically execute spawned transaction(s), when the current transaction terminate. When OFF, spawned transactions must be executed manually via TP-Escape menu. [G8WB-TRACE] ; Trace configuration TP-TX-SEQUENCE : OFF ; Trace TX/TPR state Normally OFF to limit the amount of information in the TP Journal. TP-EXEC-CALL : OFF ; Trace TP Interface/procedure calls Normally OFF to limit the amount of information in the TP Journal. TP-COMM-DETAIL : OFF ; Trace SEND/RECEIVE details Normally OFF to limit the amount of information in the TP Journal. TP-TPR-EXECUTE : ON ; OFF(default)/ON Normally ON, so user can see 'progress' in a status message on the TP8 screen. TP-RESPONSE-TIME : PROFILE ; OFF(default)/ON/PROFILE May be used to obtain response-time (and other statistics) in the TP Journal. OFF - No response time statistics given TPR/Module use and IDS-II statistics given at termination ON - Response time summary statistics given at termination TPR/Module use and IDS-II statistics given at termination PROFILE - Like ON, however Response time, TPR/Module use and IDS-II statistics are given both after each TX or Phase, and summary at termination Note: Response time statistics are naturally not comparable to real TP8 response times, however it does give you an idea of performance variances within or between transactions. Note: IDS-II statistics are comparable to GCOS8 for Logical (DML) operations, whereas Physical statistics are not comparable to GCOS8. However it does give you an idea of I/O performance variances within or between transactions. TP-GLOBAL-JOURNAL : ON ; OFF(default)/ON May be used to consolidated all TP Journals. When ON, each TP Journal will be appended to a Global Journal file $g8rbgdir\JOURNAL.ddd, where ddd = day number. BATCH-EXEC-CALL : OFF ; Trace Interface/procedure calls Normally OFF to limit the amount of information in the TP Journal. BATCH-GLOBAL-LOG : ON ; OFF(default)/ON May be used to consolidated all Batch Logs. When ON, each Batch Log will be appended to a Global Log file $g8rbgdir\BATCH.ddd, where ddd = day number. Note: RHE8 Utilities like DB Backup etc. will by default produce output on $g8rbldir\BATCH.LOG (like batch application programs). Environment integration ----------------------- The $g8rbgdir\ENV.CFG file must be amended with information from your MFE8 environment. This step must be done manually, i.e. copying from $g8wbgdir\ENV.CFG and pasting into $g8rbgdir\ENV.CFG. Note: If you have made no changes to ENV.CFG, no integration is required. Forms Integration ----------------- RHE8 will only install an empty Forms directory structure, and since Forms directory is only used by some Forms software, you may not be required to do any integration. TPFF ---- Forms are embedded in TPR and Forms directory not used during execution. FORMAT ------ Forms are embedded in TPR and Forms directory not used during execution. SOLD ---- Forms are embedded in TPR and Forms directory not used during execution. PILSPRAAK --------- Forms are embedded in TPR and Forms directory not used during execution. DIMS8 ----- Forms are loaded from Forms directory during execution. Either copy the entire $g8wbfdir\FORMS structure to $g8rbfdir\FORMS, or change G8RBFDIR setting to point to G8WBFDIR (during installation of RHE8 Workstation). TSM8 ---- Forms are loaded from Forms directory during execution. Either copy the entire $g8wbfdir\FORMS structure to $g8rbfdir\FORMS, or change G8RBFDIR setting to point to G8WBFDIR (during installation of RHE8 Workstation). SOLD+ ----- Forms are loaded from Forms directory during execution. Either copy the entire $g8wbfdir\FORMS structure to $g8rbfdir\FORMS, or change G8RBFDIR setting to point to G8WBFDIR (during installation of RHE8 Workstation). Application integration ----------------------- The application programs checked and compiled in MFE8 environment must be made available within the RHE8 environment, so you are able to execute the entire application system, as if it was running on GCOS8. COBDIR ------ Like MFE8, RHE8 use COBDIR setting to dynamically search through multiple directories for application programs. Such programs may be either INT or GNT format, however GNT (compiled) is recommended for best performance. COBDIR settings may be placed in the RHE8ENV.CFG file, which is processed during startup of any RHE8 operation. The RHE8ENV.CFG is located using following technique: $rhe8env\rhe8env.cfg (if RHE8ENV setting is present) \rhe8env.cfg $g8rbldir\rhe8env.cfg $g8rbgdir\rhe8env.cfg no rhe8env.cfg used The RHE8ENV.CFG is a simple text file with one or more environment settings, ex. AP1=F:\APP1 AP1=F:\APP2 SUB=F:\SUB DBPROC=F:\DBPROC COBDIR=%SUB%;%DBPROC%;%COBDIR% COBDIR=%AP1%;%AP2%;%COBDIR% Note: SET is not specified. Existing environment variables must be expanded using %symbol% technique. Libraries --------- An alternative technique is to use application libraries, and allocate these libraries through Environment configuration ($g8rbgdir\ENV.CFG). Although library technique is faster than directory searching through COBDIR, we do not recommend use of libraries because libraries cannot be updated if they are busy, i.e. some RHE8 user is executing somewhere. TP8 SERVER ========== Principles ---------- ---------* ----------* *--------* I *--------* *---------* I *-------* I I I I I I I I I I I Client I I<---->I Server I<---->I Monitor I I<---->I RDBMS I I I I I I I I I *--------* *--------* *---------* *-------* Terminal Pending Application IDS-II Emulator Request TPRs ESQL Browser Queue TX/PHASE Spawn TX Queue Client: Users establish session via TPCLI or DSA-Gateway. Server: Messages are queued for processing (PRQ) in Monitor. Output messages are relayed to Client, and Client is given turn when TX completes or goes into conver- sation. Monitor: Executes message from Server - TX or conversational reply. TP8 Server ---------- TP8 Server is launched with the RUN TP8S command or icon, and quickly becomes operational, awaiting connections from either clients or monitors. Following configuration entries in Defaults Configuration (G8WB.CFG) may be used to control TP8 Server: [TP-MONITOR-DEFAULTS] CCI-MODULE : CCITCP ; CCIDDE(default) or CCITCP CCI-PUBLICNAME : TPMonG8RB ; Public name of TP8, default TPMonG8RB ;CCI-TIMEOUT-SECS : 30 ; Default is 120 TP8 server communicates with TP8 Monitor(s) via TCP/IP using the name TPMonG8RB. [TP-CLIENT-DEFAULTS] CCI-MODULE : CCITCP ; CCITCP(default) or CCIDDE CCI-PUBLICNAME : TPCliG8RB ; Public name of TP8, default TPCliG8RB ;CCI-TIMEOUT-SECS : 30 ; Default is 120 TP8 server communicates with Client(s) via TCP/IP using the name TPCliG8RB. Note: If you need to setup multiple RHE8 enviroments, you need to configure unique publicnames for Monitor and Client. [TP-SERVER-STARTUP] ;Tpident Command ; INITIAL and FINAL used to start a process only, all others ; will start process continously (start and restart ; at 30 second interval) ; Note: Tpident must match W8TP ident ;INITIAL : 'start only once during startup' ;FINAL : 'start only once during shutdown' TP1 : 'start \bin\RUN TP8M "TP1" /F:\g8rbl1' TP2 : 'start \bin\RUN TP8M "TP2" /F:\g8rbl2' TP8 Server may be configured to launch one or more Monitors at startup. Should a Monitor stop (RHE8 or uncontrolled application abort), a new Monitor instance is automatically re-launched. [G8WB-TRACE] ; Trace configuration TP-SERVER-DEBUG : OFF ; Trace TP Server TP-GLOBAL-JOURNAL : ON ; OFF(default)/ON TP8 Server writes statistics to $g8rbsdir\SERVER.LOG. TP-SERVER-DEBUG:ON cause a substantial amount of debug/trace information to be added to this log. TP-GLOBAL-JOURNAL:ON cause the SERVER.LOG to be appended to $g8rbsdir\SERVER.nnn file, where nnn = current day number. Following limits are fixed for TP8 Server: Max. number of Clients = 500 Max. number of Monitors = 10 Min. number of Buffers = 3 Max. number of Buffers = 100 (allocated as needed) TP8 Server Operation -------------------- TP8 Server provides status information in the execution window, and accepts one character commands, as indicated: -> TP Server is in the air -> Enter Q or S to shutdown TP Server, L for LID Statistics M for Monitor Statistics, D for Disconnect Lid Z for restart processes, any other for Quick Status Quick Status, which is both shown and written to SERVER.LOG, gives a summary of activity and resource use. Counters are given for Interval (period since last quick status) and Total (period since startup). -> Quick status for TP Server at hh.mm.ss TX-Serial# nnnnnnnn Counter Interval /sec Total /sec ----------------------------------------- Client Imsg# nnnnnnnn nn.n nnnnnnnn nn.n Client Omsg# nnnnnnnn nn.n nnnnnnnn nn.n Monitor Imsg# nnnnnnnn nn.n nnnnnnnn nn.n Monitor Omsg# nnnnnnnn nn.n nnnnnnnn nn.n Total I/Omsg# nnnnnnnn nn.n nnnnnnnn nn.n Client Lost# nnnnnnnn nnnnnnnn Client Prq# nnnnnnnn nnnnnnnn Client Max# nnnnnnnn nnnnnnnn Resource Current Maximum ------------------------------- Clients nnn nnn -active nnn -send nnn -pending nnn -idle nnn -spawn nnn -sleep nnn Monitors nn nn -active nn -idle nn Buffers nnn nnn -free nnn Shutdown of TP8 Server may be requested with S or Q command, however, to prevent accidental shutdown, the request has to be confirmed, ex. Shutdown has been requested Execution is suspended until you reply! CONFIRM SHUTDOWN (N/Y)? If shutdown is not confirmed with Y (upper-case), the shutdown request is ignored and server.log is copied to server.001 (for viewing). A shutdown will stop all monitors and disconnect all clients. Note: If you do not have access to the TP8 Server window, you shutdown from a client using the $SHUTDOWN command. Shutdown of all idle monitors may be requested with Z command. This feature maybe used to reload application programs/libraries without shutting down TP. Disconnect of a single client may be requested with D command. Current LID statistics is shown, and the LID index is used to designate a specific LID to be disconnected, ex. To prevent accidental shutdown, the request has to be confirmed, ex. -> LID Statistics for TP Server at hh.mm.ss LID Index Queue Input# Output# Min. Max. Avg. /sec ---------------------------------------------------- xxxx nnn qqqq nnnnnnn nnnnnnn nn.n nn.n nn.n Disconnect of Lid has been requested Execution is suspended until you reply! Enter LID Index or just Return If no LID index or an invalid index is given, the disconnect request is ignored. LID Statistics (L command), which is both shown and written to SERVER.LOG, gives a summary of client activity and current status. Only currently connected clients are shown. -> LID Statistics for TP Server at hh.mm.ss LID Index Queue Input# Output# Min. Max. Avg. /sec Lost# ---------------------------------------------------------- xxxx nnn qqqq nnnnnnn nnnnnnn nn.n nn.n nn.n nnn -> Idle, Busy, Send, PRQ, Disc, Spawn, Sleep Note: If unique LIDs are used, then a re-connected client will continue to use the same index (entry), without resetting the counters. Monitor Statistics (M command), which is both shown and written to SERVER.LOG, gives a summary of Monitor activity and current status. Only currently connected monitors are shown. -> Monitor Statistics for TP Server at hh.mm.ss Proc Ident Queue LID Input# Output# Min. Max. Avg./sec Start --------------------------------------------------------------------- nn xxxxxxxx qqqq nnn-xxxx nnnnnnn nnnnnnn nn.n nn.n nn.n nnn -> Idle, Busy TP8 Monitor ----------- TP8 Monitor is launched with the RUN TP8M command or icon. Alternatively one or more monitors can be launched by TP8 Server automatically. The command line is used to uniquely identify each monitor. Each monitor must be assigned a non-shared G8RBLDIR. This can be done via command line. RUN TP8M ["TP-Ident"] [/ldirpath|/.] TP-ident: Although optional, a unique identification must be assigned to each monitor, if launched by TP8 Server. G8RBLDIR: May be used to set G8RBLDIR for monitor instance. Following configuration entries in Defaults Configuration (G8WB.CFG) may be used to control TP8 Server: [G8WB-DEFAULTS] ; Defaults configuration TERMINAL-EMULATION : DKU71XX SERVER ; ; Emulator [Interface] ; VIP77XX ; VIP78XX ; DKU71XX ; IBM327X ; SERVER ; SERVER TNVIP ; SERVER TN3270 The Terminal-emulation setting defines the default terminal emulation for a Client, and SERVER, which instruct the Monitor to run in RHE8 mode. The TNVIP|TN3270 setting defines the default communication mode for the Client interface (TPCLI). Note: Terminal-emulation can be overriden via Local configuration, however you cannot mix different terminal emulations within the same TP8 server. [TP-MONITOR-DEFAULTS] CCI-MODULE : CCITCP ; CCIDDE(default) or CCITCP CCI-PUBLICNAME : TPMonG8RB ; Public name of TP8, default TPMonG8RB ;CCI-TIMEOUT-SECS : 30 ; Default is 120 TP8 Monitor communicates with TP8 Server via TCP/IP using the name TPMonG8RB. [G8WB-TRACE] ; Trace configuration TP-TX-SEQUENCE : OFF ; Trace TX/TPR state TP-EXEC-CALL : OFF ; Trace TP Interface/procedure calls TP-COMM-DETAIL : OFF ; Trace SEND/RECEIVE details TP-TPR-EXECUTE : OFF ; OFF(default)/ON TP-RESPONSE-TIME : ON ; OFF(default)/ON/PROFILE TP-GLOBAL-JOURNAL : ON ; OFF(default)/ON TP-RESPONSE-TIME:ON cause a one line trace to be written to $g8rbldir\ JOURNAL.LOG for each TX/PHASE. TP-GLOBAL-JOURNAL:ON cause the JOURNAL.LOG to be appended to $g8rbgdir\JOURNAL.nnn file, where nnn = current day number. TP-TPR-EXECUTE should be left OFF, otherwise a message is sent to the client, whenever a TPR is executed. This message will, however, not be shown at the client. TP-TX-SEQUENCE, TP-EXEC-CALL, TP-COMM-DETAIL:ON cause a substantial amount of debug/trace information to be written to JOURNAL.LOG. Note: Monitor(s) will continue to run until TP8 Server is closed down, or a time-out occur while waiting for TP8 Server to respond. TP8 Client ---------- TP8 Clients may be connected either through TP8 Client utility (TPCLI) or through a DSA-Gateway. TP8 Client Utility ------------------ TP8 Client is launched with the RUN TPCLI command or icon. The optional command line may be used to control client execution mode and override default configuration. Following modes are possible: - Run a single TX - Run a series of TX's from a file - Start a terminal dialog using embedded emulators - Start a terminal dialog via an external terminal emulator The syntax of command line is as folllows: RUN TPCLI [BIBOTX "command"|BIBOFILE bibo-file [think-secs]] [lid] [terminal-emulation] [/ldirpath|/.] BIBOTX - may be used to execute a single TP8 message - given in "command", and then terminate. BIBOFILE - may be used to execute a series of TP8 messages from bibo-file. Messages in the file can either be plain text or in BIBO format (see MFE8 documentation for details). The optional think-secs may be used to slow down execution of messages. If neither BIBOTX nor BIBOFILE is specified, a terminal dialog is started. Lid - may be used to set a lid for the session, and thus override default configuration. Terminal-emulation - may be used to set terminal emulation and interface for the session, and thus override default configuration. VIP77XX|VIP78XX|DKU71XX|IBM327X|TTY SERVER [TNVIP|TN3270] Note: SERVER must be specified for RHE8. TNVIP or TN3270 trigger client utility to acts as an interface to terminal- emulation software. G8RBLDIR: The setting for G8RBLDIR may be changed on-the-fly, ex. /c:\temp (specific path) /. (current path) Note: G8RBLDIR is ONLY used for optional local configuration, no files, except for Hard-copy, are written. Following configuration entries in Defaults Configuration (G8WB.CFG) may be used to control TPCLI: [TP-CLIENT-DEFAULTS] CCI-MODULE : CCITCP ; CCITCP(default) or CCIDDE CCI-PUBLICNAME : TPCliG8RB ; Public name of TP8, default TPCliG8RB ;CCI-TIMEOUT-SECS : 30 ; Default is 120 TP8 Client communicates with TP8 Server via TCP/IP using the name TPCliG8RB. [G8WB-DEFAULTS] ; Defaults configuration LOGICAL-ID : MAST ; Default LID for TP Log-on Note: It is recommended to use unique LIDs for TP8 Clients, as this makes it possible to identify a user and collect useful statistics. TP8 Client DSA-Gateway ---------------------- The DSA-Gateway is based on Ggate from G&R, and you need both Ggate and GlAPI run-time licenses in order to use DSA-Gateway. With DSA-Gateway you are able to connect Glink to TP8 Server, as if TP8 Server was a GCOS8 node. The setup, configuration and use of DSA-Gateway is docu- mented in G8RB, ref. Open-Client-Toolkit. For RHE8 the 'Listener' configuration of Ggate is slightly different and only ONE entry is required. listen -mn rhetp8 -ext -lim nn -cmd 'rhetp8' is the mailbox to listen and handle connection for, and nn designate the maximum number of connections. The syntax is: W8GLAPI [options] publicname -ln -mn mailbox -li dsa [gline args] 'W8GLAPI' is the program launched when connection is detected. 'publicname' must be the same as CC-PUBLICNAME: as configured under [TP-CLIENT-DEFAULTS]. 'options' can be VIP77XX|VIP78XX|DKU71XX|IBM327X|TTY|BROWSER, and designates the terminal-emulation for the session. The default is defined in Default Configuration (G8WB.CFG). Note: For IBM327X emulation you MUST use W8GLAPIE program, which implies IBM327X emulation. 'options' can be DEBUG|DEBUGALL, where DEBUG may be used to create a debug file under the 'servers' directory of Ggate. DEBUGALL may be used create a new debug file for each session. 'options' can be "tx", may be used to trigger a logon transaction when a session is established, ex. "VLOGO" will run the tx = VLOGO without any further input. 'options' can be NODIALOG, may be used to suppress the connect/hello messages from TP8. 'options' can be NOETX, may be used to suppress ETX, which is otherwise appended to messages sent to/from TP8. 'mailbox' must be the same as specified in '-mn mailbox', ex. rhetp8. '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 rhetp8 -ext -lim 50 -cmd w8glapi TPCliG8RB dku71xx -ln -mn rhbtp8 -li dsa -t_ -s_ Here's an example of a connection through Glink: Communication interface = Windows Sockets IP address/Host = Ggate Server Protocol = G&R DSA Gateway Host = myggate or ip Host mailbox = RHETP8 Host node = GGATE_RFC Mailbox ext = LID1 (optional Lid, but recommended) Note: Terminal emulation setting in Glink MUST match the terminal emulation used for the session. TUXEDO/TP8 ========== Principles ---------- ---------* ----------* *--------* I *--------* *---------* I *-------* I I I I I I I I I I I Client I I<---->I Tuxedo I<---->I Process I I<---->I RDBMS I I I I I I I I I *--------* *--------* *---------* *-------* Terminal Pending Application IDS-II Emulator Request TPRs ESQL Browser Queue TX/PHASE Spawn TX Queue Client: Users establish session via TPCLI or DSA-Gateway, which includes interface to Tuxedo Workstation. Tuxedo: Messages are queued for processing in Tuxedo. Output messages are relayed to Client, and Client is given turn when TX completes or goes into conver- sation. Process: Executes message from Tuxedo - TX or conversational reply. Tuxedo Workstation ------------------ TP8 handling must be defined in the Tuxedo configuration file, you may select either of three Tuxedo servers to execute TP8 commands, as follows: TUXTP8 - May be used to execute TP8 messages (conversational or non-conversational). Database commit/rollback is controlled by RDBMS software. TUXTP8TX - Like TUXTP8, except TP8 messages are executed under Tuxedo transaction control. Should be used if application is spawning transaction(s), and you wish to ensure rollback of spawn operations, if TX fails. TUXTP8XA - Like TUXTPTX, except database commit/rollback are coordinated with Tuxedo using the XA protocol. Should be used if application is amended to start of sub-transactions, which require coordinated commit/ rollback. The $g8rbgdir\tuxedo\rhe8.cfg and rhe8w.cfg provides examples of Tuxedo configuration files, and you can either use these to create a new Tuxedo workstation or amend an existing one. Example (simple): *GROUPS GROUP2 LMID=simple GRPNO=2 OPENINFO=NONE *SERVERS DEFAULT: CLOPT="-A" TUXTP8 SRVGRP=GROUP2 SRVID=1 MIN=1 MAX=2 TUXTP8TX SRVGRP=GROUP2 SRVID=5001 MIN=1 MAX=2 *SERVICES TUXTP8 TUXTP8TX Above defines the two servers TUXTP8 and TUXTP8TX, and associates the with groups, which trigger spawn of processes to handle TP8 messages. When Tuxedo is launched with 'tmboot' command, the 'min' numbers of processed are launched for each server, ready for processing of TP8 messages. Additional processes are launched as required up to the 'max' number specified. Tuxedo is stopped with 'tmshutdown' command. Example (/WS): If Tuxedo client are not executed on the same server as Tuxedo workstation, you also need to configure a /WS listener (rhe8w.cfg). *MACHINES MYSERVER LMID=simple MAXWSCLIENTS=100 *GROUPS GROUP1 LMID=simple GRPNO=1 OPENINFO=NONE *SERVERS WSL SRVGRP=GROUP1 SRVID=1 CLOPT=" -- -n //myserver:25000" RQPERM=0660 REPLYQ=Y RPPERM=0660 MIN=1 MAX=1 CONV=N SYSTEM_ACCESS=FASTPATH MAXGEN=5 GRACE=86400 RESTART=Y Example (Spawn): If the TP8 application is spawning transaction (other than SWTM to originator), or send to ROP lids, you also need to configure one or more queues. *GROUPS GROUP4 LMID=simple GRPNO=4 TMSNAME=TMS_QM TMSCOUNT=2 OPENINFO="TUXEDO/QM:\QUE;QSPACE" *SERVERS TMQUEUE SRVGRP=GROUP4 SRVID=1 GRACE=0 RESTART=Y CONV=N MAXGEN=10 CLOPT="-s QSPACE:TMQUEUE" Above creates a minimum queue mechanism for handling of TX spawn and/or ROP messages. Before starting Tuxedo, you must use the 'qmadmin' command as follows: Use 'crdl' directive to create the device Use 'qspacecreate' to create a qspace for storage Use 'qcreate' to create on or more queues within qspace For TX spawn you must create a queue with the name "TP8" for each 'spawn-lid' defined in your TP8 Workstation configuration. For ROP messages you must create ONE queue with the name 'TP8ROP'. Please refer to Tuxedo /Q for details on queue administration. Example (XA): If TP8 application is to be executed as part of a distributed transaction, i.e. TX is launching sub-transaction(s) which required coordinated commit/rollback, you need to configure the TUXTP8XA server and an associated resource manager. *GROUPS UDB_GRP LMID=simple GRPNO=3 TMSNAME=TMS_UDB TMSCOUNT=2 OPENINFO="UDB_XA:db=MYDB,uid=db2admin,pwd=xxx,tpm=TUXEDO" *SERVERS TUXTP8XA SRVGRP=UDB_GRP SRVID=10001 MIN=1 MAX=2 *SERVICES TUXTP8XA Above example demonstrates database access through DB2 UDB. During startup of TUXTP8, TUXTP8TX and TUXTP8XA processes, the TP8 Workstation is configured through G8WB.CFG and TP8.CFG configuration files, however this configuration takes place ONLY for the first process, all others processes will share the same configuration, until Tuxedo is shutdown and re-booted. Although Tuxedo treat all TP8 messages as non-conversational, the RHE8 emulation of TP8 will keep track of the session state, and handle checkpoint, conversations and abort like TP8. The state information (TP-Storage, TX-Storage, Constant-Storage and Lid- Storage) is swapped as required during TP8 execution. RHE8 use an additional environment setting G8RBSDIR for storage of TP8 swap-files. By default G8RBSDIR = G8RBGDIR setting. TP8 Configuration ----------------- RHE8 will log a few information messages, and any fatal exception messages to the standard Tuxedo log. In addition a TP8 Journal is used to provide further details of events and exception occuring during TP8 execution. The TP8 Journal is placed under $G8RBLDIR\journal..log where pid = process-id of the Tuxedo process Following configuration entries in Defaults Configuration (G8WB.CFG) may be used to TP8 journal content: [G8WB-TRACE] ; Trace configuration TP-TX-SEQUENCE : OFF ; Trace TX/TPR state TP-EXEC-CALL : OFF ; Trace TP Interface/procedure calls TP-COMM-DETAIL : OFF ; Trace SEND/RECEIVE details TP-TPR-EXECUTE : OFF ; OFF(default)/ON TP-RESPONSE-TIME : ON ; OFF(default)/ON/PROFILE TP-GLOBAL-JOURNAL : ON ; OFF(default)/ON TP-RESPONSE-TIME:ON cause a one line trace to be written to journal for each TX/PHASE. TP-TPR-EXECUTE should be left OFF, otherwise a message is sent to the client, whenever a TPR is executed. This message will, however, not be shown at the client. TP-TX-SEQUENCE, TP-EXEC-CALL, TP-COMM-DETAIL:ON cause a substantial amount of debug/trace information to be written to journal. TP-GLOBAL-JOURNAL:ON cause the journal to be appended to $g8rbgdir\JOURNAL.nnn file, where nnn = current day number, upon completion of process. Following configuration entries in TP8 Configuration (TP8.CFG) may be used to control Tuxedo behavior: [create_monitor_extension] ROP : IGNORE ; IGNORE(default)|QUEUE SLAVE : LOG ; LOG(default)|IGNORE|QUEUE SPAWN : IGNORE ; IGNORE(default)|QUEUE QUEUE_SPACE_NAME : QSPACE ; QSPACE(default)| ROP, QUEUE will cause messages to ROP lids to be queued in Tuxedo for further processing, otherwise such messages are ignored. SPAWN, QUEUE will cause messages to SPAWN lids to be queued in Tuxedo for further processing, otherwise such messages are ignored. SLAVE, QUEUE will cause messages to SLAVE lid to be queued in Tuxedo for further processing (the queue name is TP8SLAVE). LOG willl cause messages to SLAVE lid to be written to the Tuxedo Log, otherwise such messages are ignored. QUEUE_SPACE_NAME setting may be used to change the default QSPACE name for the Tuxedo Queue Space. TP8 Client ---------- TP8 Clients may be connected either through Tuxedo/TP8 Client utility (TP8TUX) or through a DSA-Gateway. Tuxedo/TP8 Client Utility ------------------------- Tuxedo/TP8 Client is launched with the TP8TUX or TP8TUXW command or icon(s). TP8TUX can be used when executed on the same server as the Tuxedo Workstation. The environment variable TUXCONFIG must point to the configuration file for Tuxedo Workstation, ex. c:/mytux/tuxconfig. TP8TUXW must be used when executed elsewhere (connect through /WS). The environment variable WSNADDR must point to the listening address of the Tuxedo Workstation, ex. //myserver:25000. The optional command line may be used to control client execution mode. Following modes are possible: - Run a single TX - Run a series of TX's from a file - Start a terminal dialog using embedded emulators - Start a terminal dialog via an external terminal emulator The syntax of command line is as folllows: TP8TUX[W] [BIBOTX "command"|BIBOFILE bibo-file [think-secs]] [TUXTP8|TUXTP8TX|TUXTP8XA] [/[username:[clientname:]]password] [lid] [terminal-emulation] BIBOTX - may be used to execute a single TP8 message - given in "command", and then terminate. BIBOFILE - may be used to execute a series of TP8 messages from bibo-file. Messages in the file can either be plain text or in BIBO format (see MFE8 documentation for details). The optional think-secs may be used to slow down execution of messages. If neither BIBOTX nor BIBOFILE is specified, a terminal dialog is started. TUXTP8|TUXTP8TX|TUXTP8XA - may be used to specify the Tuxedo service. The default is TUXTP8. Lid - may be used to set a specific lid for the session. /... - may be used to provide authentication information for Tuxedo, if configured. For SYSAUTH only password is required. If authentication is configured and no information is given, you are prompted for information. Terminal-emulation - may be used to set terminal emulation and interface for the session, and thus override default configuration. VIP77XX|VIP78XX|DKU71XX|IBM327X|TTY [TNVIP|TN3270] Note: TNVIP or TN3270 trigger client utility to acts as an interface to terminal-emulation software, ex. Glink. Note: It is recommended to use unique LIDs for TP8 Clients, as this makes it possible to identify a user and collect useful statistics. Tuxedo/TP8 Client DSA-Gateway ----------------------------- The DSA-Gateway is based on Ggate from G&R, and you need both Ggate and GlAPI run-time licenses in order to use DSA-Gateway. With DSA-Gateway you are able to connect Glink to Tuxedo/TP8, as if Tuxedo/TP8 was a GCOS8 node. The setup, configuration and use of DSA-Gateway is docu- mented in G8RB, ref. Open-Client-Toolkit. For RHE8 the 'Listener' configuration of Ggate is slightly different and only ONE entry (per Tuxedo service) is required. listen -mn tuxtp8 -ext -lim nn -cmd 'tuxtp8' is the mailbox to listen and handle connection for, and nn designate the maximum number of connections. The syntax is: TUXGLAPI[W] [options] -ln -mn mailbox -li dsa [gline args] 'TUXGLAPI' is the program launched when connection is detected and can be used when Ggate is executed on the same server as the TuxedoWorkstation. The environment variable TUXCONFIG must pointto the configuration file for Tuxedo Workstation, ex. c:/mytux/tuxconfig. 'TUXGLAPIW' is the program launched when connection is detected and must be used when Ggate is executed elsewhere (connect through /WS). The environment variable WSNADDR must point to the listening address of the Tuxedo Workstation, ex. //myserver:25000. 'options' can be TUXTP8|TUXTP8TX|TUXTP8XA, and this designates the Tuxedo service to use for the session. The default is TUXTP8. 'options' can be VIP77XX|VIP78XX|DKU71XX|IBM327X|TTY|BROWSER, and designates the terminal-emulation for the session. The default is defined in Default Configuration (G8WB.CFG). Note: For IBM327X emulation you MUST use TUXGLAPIE or TUXGLAPIEW program, which implies IBM327X emulation. 'options' can be DEBUG|DEBUGALL, where DEBUG may be used to create a debug file under the 'servers' directory of Ggate. DEBUGALL may be used create a new debug file for each session. 'options' can be "tx", may be used to trigger a logon transaction when a session is established, ex. "VLOGO" will run the tx = VLOGO without any further input. 'options' can be NODIALOG, may be used to suppress the connect/hello messages from TP8. 'options' can be NOETX, may be used to suppress ETX, which is otherwise appended to messages sent to/from TP8. 'mailbox' must be the same as specified in '-mn mailbox', ex. tuxtp8. '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 tuxtp8 -ext -lim 50 -cmd tuxglapiw tuxtp8 dku71xx -ln -mn tuxtp8 -li dsa -t_ -s_ Here's an example of a connection through Glink: Communication interface = Windows Sockets IP address/Host = Ggate Server Protocol = G&R DSA Gateway Host = myggate or ip Host mailbox = TUXTP8 Host node = GGATE_RFC Mailbox ext = LID1 (optional Lid, but recommended) Note: Terminal emulation setting in Glink MUST match the terminal emulation used for the session. If Tuxedo is configured for authentication - SYSAUTH or APPAUTH, you must setup Glink to provide following information (fixed or prompted): password - minimum for SYSAUTH userid - used as username for Tuxedo billing - used as clientname for Tuxedo Tuxedo Queue Utility -------------------- If messages are queued from Tuxedo/TP8 - spawn, ROP or SLAVE, you must start one or more Tuxedo Queue utilities to process the queued messages. Tuxedo Queue Utility is launched with the QUETUX or QUETUXW command or icon(s). QUETUX can be used when executed on the same server as the Tuxedo Workstation. The environment variable TUXCONFIG must point to the configuration file for Tuxedo Workstation, ex. c:/mytux/tuxconfig. QUETUXW must be used when executed elsewhere (connect through /WS). The environment variable WSNADDR must point to the listening address of the Tuxedo Workstation, ex. //myserver:25000. The optional command line may be used to control queue execution mode. The syntax of command line is as folllows: QUETUX[W] [SLAVE programname] [ROP programname] [SPAWN [[lid|group]...]] Default is SPAWN (all lids) SLAVE - send SLAVE messages to the specified programname ROP - send ROP messages to the specified programname SPAWN - execute spawned messages for the specified lid(s) and or group(s). Default is all lids. Note: Timed messages are handled by /Q. In the command window you are able to stop QUETUX using Q or S key. BATCH ===== Batch application are launched with the RUN PRG command or icon. The command line format is as follows: RUN PRG ["title"] programname [normal|exclusive|nolog| auto|query|nodb] [cbl85|cbl74] [=outfilename] [/ldirpath|/.]" Title: When specified, the title is applied to the execution window. Must be first argument and a quoted value. Programname: The programname or filename of the application program. Databasemode: May be used to control access to the database, if applicable. The default is normal. Nodb = database not used by program Exclusive = lock database and perform auto-commit Nolog = access database without logging (exclusive) Auto = access database with auto-commit Query = access database with query Note: All schema and subschema domains configured are pre-loaded before the application is launched. Environment: The execution environment for COBOL-85 or COBOL-74 is now preloaded. The default is cbl85. Redirect: The log may be redirected to a file. The default is $g8rbldir\BATCH.LOG. G8RBLDIR: The setting for G8RBLDIR may be changed on-the-fly, ex. /c:\temp (specific path) /. (current path) Following configuration entries in Defaults Configuration (G8WB.CFG) may be used to control Batch: [G8WB-TRACE] ; Trace configuration BATCH-EXEC-CALL : OFF ; Trace Interface/procedure calls BATCH-GLOBAL-LOG : ON ; OFF(default)/ON BATCH-GLOBAL-LOG:ON cause the BATCH.LOG to be appended to $g8rbgdir\BATCH.nnn file, where nnn = current day number. BATCH-EXEC-CALL:ON cause debug/trace information to be written to BATCH.LOG. ======== COMMANDS ======== The graphical IDE used in the MFE8 environment is not available within RHE8 environment. Likewise only a subset of the functions are available. RHE8 functions are either launched from icons 'GCOS8 Rehosting Expres' folder (and sub-folders), or launched as commands from the 'RHE8 Command Prompt' or within BAT files. RHE8 commands may be launched using the RUN command from 'GCOS8 Rehosting Command Prompt', ex. RUN command [arguments] To launch RHE8 commands from OS Command Prompt, or an OS Command file, you need to prefix the RUN command with the RHE8 path, unless this has been included in the PATH seetings, ex. c:\rhe8\p\bin\RUN command [arguments] The following RHE8 commands are available: Syntax: TP8S Start TP8 Server. Syntax: TP8M Start TP8 Monitor. Syntax: TPCLI arguments Start TP8 Client. Syntax: PRG programname Start Batch program. Syntax: IIDS subschema FILE filename [=output-file] Execute IIDS Utility with DML script. Syntax: PRCEXP print-file[.ext] [report-file] Expand Report-code or Report-writer print-file into separate report files. Default extension for print-file is DAT. Report-file extension is forced to Dnn, where nn = report-code. Syntax: PSWS nn+|- [...] where nn = 00-35 or 99(all) + = set switch ON - = set switch OFF Set or reset PSW switch or switches. Syntax: PSWT nn where nn = 00-35 Test status of PSW switch and set ErrorLevel 1 = ON. Syntax: PSM psm-file [_List-source] Execute PSM sort. Syntax: G8WFL profile[.g8p] [inputfile[.g8f] outputfile[.dat]] Convert GCOS8 file. Syntax: DBLOAD schemaname load-file[.dat] [_Update [Only]] [_Force] [_Trace] [_1|_2|_3] Load whole or parts of a database. Syntax: LOG some message Write message to consolidated Batch Log. Syntax: BATCH command-file[.cbt] Execute a RHE8 command-file. Default extension is CBT. Some RHE8 commands may also be launched in interactive mode: Syntax: IIDSI Execute IIDS Utility interactively. Syntax: DBLOADI Execute DBLOAD Utility interactively. Syntax: G8WFLI Execute G8WFL Utility interactively. Syntax: PRCEXPI Execute PRCEXP Utility interactively. Syntax: PSWI Execute PSW Utility interactively. Syntax: CONFIG Launch Configuration Utility. Syntax: BCFI Execute BCF Utility interactively. The TUXTP8 and TUXTP8W commands are launched without RUN prefix. File mapping ------------ Like MFE8, RHE utilize External mapping for conventional files. By default the GCOS8 file-code is used as 'logical name', except for I* and P* which use SYSIN and SYSOUT respectively as 'logical name'. PSM files are mapped slightly different, ex. PSM-file is named TEST.PSM TESTSA is input file TESTSZ is output file Default ------- Files are by default accessed through their 'logical name' under the current directory. Ex. GCOS8 $ prmfl I1,R,S,UMC/myfile $ sysout P* Ex. RHE8 read I1 under current directory write SYSOUT under current directory Setting ------- 'Logical name' may be mapped to a physical file through environment settings. ex. SET I1=C:\g8rbl\myfile.dat SET I1=$App1\files\Myfile.dat Mapping file ------------ 'Logical name' may be mapped to a physical file through a mapping file. This file is name 'MFEXTMAP.DAT'. ex. program mapping I1 $app1\files\Myfile.dat O1 $app1\files\Myfile.dat SYSOUT $g8rbldir\SYSOUT. RHE8 will search for MFEXTMAP.DAT under current directory and if not found under all directories specified in COBDIR (left-to-right). RHE8 can be directed to a specific MFEXTMAP.DAT file through the following setting: SET MFEXTMAP=$app1\files Note: RHE8 can ONLY use one 'MFEXTMAP.DAT', and will stop searching as soon as a MFEXTMAP.DAT file is found. Search for MFEXTMAP.DAT can be disabled through the following setting: SET MFEXTMAP=NO Mapping Rules ------------- File mapping rules are applied in the following priority order: o Environment: Use if setting is found. o Mapping-file: Use if mapping is found within MFEXTMAP.DAT file. o Logical-name: Use default access through 'logical name' under current directory. Command Files ------------- GCOS8 JCL and job streams are not supported by RHE8, however, you can use RHE8 commands to build command files (BAT) with similar functionality. When using Environment setting for file mapping, remember mapping must be done before execution of batch program. Ex. rem My example batch stream SET SYSIN=$app1\files\par1.txt SET LS=$app1\files\output.dat rem Execute P1 RUN PRG p1 rem Expand report-file and print it RUN PRCEXP $app1\files\output wrk PRINT wrk.D10 DELE wrk.D10 Conditional JCL using Program-Switch-Word can be tested as follows. Ex. rem My example batch stream rem Reset all switches RUN PSWS -99 rem Execute P1 RUN p1 rem Test switch 21 RUN PSWT 21 if errorlevel 1 goto label2 :label1 rem Execute P2 RUN PRG p2 :label2 DATABASE REHOSTING ================== RHE8 use a standard Relational Database System to host the IDS-II database emulation. Following RDBMS software is supported: INFORMIX IDS.2000 Version 9.2 ORACLE 8/8i/9i IBM DB2 Version 7/8 Microsoft SQL Server 7.0/2000 Each of these RDBMS emulation are described below, however although IDS-II database access will be functionally equivalent for your applicarion programs, the following general preparations must be considered. Dbkey allocation ---------------- Dbkey allocation for GCOS is defined for an area and the dbkey allocation and optional reserve reflect the number of records that can be stored in an area. As records are deleted, dbkeys are reused. Dbkey allocation for RHE8 is defined for a record and the dbkey allocation reflect the number of records (of this type) that can be stored during the life-cycle of the database. As records are deleted, dbkeys are NOT reused. To prevent running out of dbkeys, you must consider the dbkey allocation carefully before loading your production database for use in a rehosted environment. Note: It is possible re-gain lost dbkeys using an own developed SQL script, however you must keep in mind set relations, which are using the dbkey. Hidden fields ------------- CHAR fields in an IDS-II schema can contain 'hidden' fields, and such fields MUST always be converted during unload/load if the are in packed or binary formats, otherwise data will be incorrect and for some RDBMS software considered illegal. NULL characters (low-values) are not allowed in CHAR fields for some RDBMS software. Where applicable you can use the NULL-FIX settings to force null characters to spaces (works both for load and application programs). Some RDBMS software will not allow packed or binary data in CHAR, and you then need to change the format to DISPLAY. This may affect the size of the CHAR field in schema/subschema. The PDATA-TRACE setting may be used to document presence of packed or binary data in CHAR fields (works both for load and application programs). Phantom pointers ---------------- RHE8 will automatically adapt dbkeys for records and sets, however it cannot adapt phantom pointers (data field with dbkey pointer) automatically. If phantom pointers are used, you need to amend the schema configuration rules before you generate unload/load programs, ex. ; ; ---------------------------------------------- ; Phantom pointer Configuration (Rehosting only) ; ---------------------------------------------- ; ; During rehosting to RDBMS database, the GCOS8 dbkey is changed ; and set pointers are adjusted. When phantom pointers are used ; you need to configure these, otherwise these will NOT be ; adjusted and thus be invalid. When this configuration is ; present, the load program will perform a Phase 3, where ; such pointers are adjusted. ; ; Note: The records referenced in phantom pointers MUST be ; loaded with the records where the phantom pointers are ; define (in same load run), or the referenced record ; must have been loaded in a previous load run. ; Alternatively you must split the load run into ; phases _1, _2 and _3, to ensure the referenced ; records are loaded, before the phantom pointers ; are adjusted. ; ;[PHANTOM,field,record] [PHANTOM,TRANSLINK,TRANSPOST] [PHANTOM,TRANSLINKX,TRANSPOSTX] Area use -------- For GCOS you could store records in multiple areas through area selection, using a DB parameter of DB procedure. For RHE8 areas are considered logical and an attribute of a table, however functionally area selection is performed equivalent to GCOS. You an however suppress all area selection via the AREA-SELECT setting. If supressed, all records are stored in the first realm (from WITHIN clause), no area attribute is associated with the table and DB parameters or procedures are ignored. Note: Access to other areas (non-first) are still possible, however these are all empty. Space allocation ---------------- For GCOS the physical space allocation was controlled via schema DMCL and the database could (or had to) be spread amongst multiple physical files. For RHE8 all IDS-II databases (all schemas) are rehosted in one instance of the target RDBMS software, and the physical space allocation can be left entirely to the target RDBMS software or partially controlled by you. The Location database setting for a schema controls space allocation as follows: CURRENT = use default tablespace for all tables SCHEMA = create and use a schema specific tablespace AREA = create and use an area specific tablespace INFORMIX RDBMS ============== Technqiues ---------- All records have a unique dbkey field, which is used as primary key. The dbkey field is implemented as a SERIAL datatype with a min/max range as configured for the schema. During load of database the GCOS dbkey value is remapped to the new dbkey value assigned during load. This remapping apply to set and phantom pointers. When accessing records through Calc or Index keys or sets, RHE8 will use a hint for the appropriate key, and thus force Informix optimizer to use the correct index for access. Sets are implemented as foreign keys in the member record(s), and the dbkey of the owner is use to enforce a constraint for the set relationship. For manually sorted sets - insertion first/last/next/ prior, an additional order field is maintained. RHE8 Configuration ------------------ Following configuration entries in Database Configuration (DBMS.CFG) may be used enable and configure IDS-II via RDBMS: [SQL-SECTION] ; Enable/Disable RHE SQL-IMPLEMENTATION : INFORMIX ; INFORMIX ; ; OFF (ISAM) SERVER : ol_instance ; Name of server DATABASE : inf_ids2 ; Name of database USERID : informix ; Name of user PASSWORD : informix ; Password of user NULL-FIX : ON ; Fix null in char OFF(default)/ON NULL-TRACE : OFF ; Trace null fix OFF(default)/ON DEBUG : OFF ; SQL Debug-log OFF(default)/ON EXPLAIN : OFF ; SQL explain OFF(default)/ON WAIT-LOCK : ON ; SQL wait lock ON(default)/OFF ISOLATION : HIGH ; Isolation HIGH(default)/LOW/OFF .LOCK-SUPPORT : ON ; .LOCK ON(default)/OFF AREA-SELECT : ON ; ON(default)/OFF DECIMAL-POINT-COMMA : OFF ; OFF(default)/ON MAX-LOAD-UNIT : 10000 ; commit every n (default 500) ESQL-C : ON ; ON(default)/OFF ORDER-PROGRAM : ON ; Enforce non-sorted set ordering On(default)/OFF CASCADE-DELETE : ON ; Use constaint rules ON(Default)/OFF CHECKSUM-CHECK : OFF ; Debug OFF(default)/ON/ALWAYS SQL-IMPLEMENTATION:INFORMIX setting enables IDS-II database emulation through Informix IDS 2000. SERVER setting designate the name of the Informix IDS server instance. Default naming is ol_xxxxx. The name cannot exceed 9 characters. DATABASE setting designate the name of the Informix IDS database. It is recommended to use the default name = inf_ids2. USERID and PASSWORD setting designate which indentification to use when establishing sessions with Informix. Use the default Informix userid with appropriate password. NULL-FIX:ON setting may be used force NULL characters in CHAR type fields to SPACE. Note: NULL characters, i.e. low-values, are not allowed in CHAR type fields. NULL-TRACE:ON may be used to log information on NULL-FIX activity on the execution log (batch or TP8). Statistics show the field-name and a corresponding count for null-fix operations. DEBUG:ON may be used to log a substantial amount of information about ESQL activity on the $g8rbldir\DBESQL.LOG file. EXPLAIN:ON may be used to set explain mode for all SELECT operations performed by RHE8. The explain information is logged within RDBMS environment, ref. Informix documentation for details. WAIT-LOCK:ON is default, i.e. application will not abort until a lock-wait time-out occur. The time-out period is controlled via settings in DEFAULT-SECTION as follows: BATCH-WAIT-TIME : 180 ; Wait time in seconds, default 180 TP-WAIT-TIME : 30 ; Wait time in seconds, default 30 ISOLATION:HIGH is default, however, following this is dynamically changes as follows: For TP: The setting, i.e. HIGH, is always used For Batch: If HIGH, it is changed to LOW, except when QUERY access mode is used, then it is changed to OFF The equivalence for Informix is as follows: HIGH = REPEATABLE READ LOW = COMMITTED READ OFF = DIRTY READ .LOCK-SUPPORT:ON is default, and a .LOCK service call will cause the current record to be 'locked for update'. Alternatively .LOCK service calls can be ignored (OFF). AREA-SELECT: ON is default, OFF may be used to ignore area selection. Note: When OFF, any area selection procedures are ignored and records are always stored/retrieved from the first realm. All others realms are treated as empty. DECIMAL-POINT-COMMA: OFF is default, ON must be specified if Informix is configured to treat comma as decimal point. MAX-LOAD-UNIT: 500 is default, may be used to control how often commits are taken during load of database. ESQL-C: ON is default, and the only option for Informix. ORDER-PROGRAM: ON is default and use to ensure non-sorted sets are maintained in the appropriate FIRST/LAST/NEXT/PRIOR order. OFF may be used enable a simpler and more efficient emulation (dbkey order), which however is not compatible with GCOS. CASCADE-DELETE: ON is default and will use SQL constaint rules to enforce owner/membership relations, which is effective both for IDS-II and direct SQL database access. OFF may be used suppress use of constraint rules and emulation of ERASE ALL MEMBERS. CHECKSUM-CHECK:OFF is default, however, following settings can be used to recover from some times of memory leaks: ON - cause schema and subschema tables to be checksummed and re- loaded if corrupted, after any DB related abort ALWAYS - cause schema and subschema tables to be checksummed and reloaded if corrupted, during every DML operation Note: ALWAYS gives extensive processor overhead and should be used with care. [SCHEMA-SECTION] ; Number Location Location Dbkey ; (1-99) Schema database allocation per table ; CURRENT DEFAULT (2100000 dbkeys) ; SCHEMA nnnnnnnnn ; AREA CONFIG (separate tag) DIMS : 23 CURRENT CURRENT DEFAULT ; DIMS8 TELEX8 : 24 CURRENT CURRENT DEFAULT ; DIMS8 Schema configuration is different for RHE8, however, the schema number and location is the same as for MFE8/G8RB, likewise, the schema number should NEVER be changed. Location database may be used to control placement of the database for the schema. CURRENT (Default) will place the database within the default SBSPACE of the inf_ids2 database. SCHEMA will place the database within an SBSPACE with the same name as the schema. AREA will place the database within multiple SBSPACEs, where each SBSPACE is given the same name as an area within the schema. Note: A record can ONLY be placed in one SBSPACE, and the the first area, i.e. WITHIN clause, is always used. Area- selection is not affected by this. Note: For a production environment you should consider use of SCHEMA or AREA location, or a combination of these. DBkey allocation may be used to control the DBkey ranges within a schema. The default is 2100000, and each record within the schema is thus assigned a dbkey range of 2.1 million. CONFIG: May be used to control DBkey allocation at record level. A separate tag is used to specify DBkey allocation details, this tag must be name -INTERVAL, ex. [DIMS-INTERVAL] DEFAULT : 2100000 ; Default allocation COURSE : 40000000 ; Specific allocation SCEHDULE : 80000000 ; Sepcific allocation Note: DBkeys are NOT reused, so the range must be sufficient to support STORE/DELETE over an extended period of time, otherwise the dbkey range will be exhausted eventually. Whenever a schema (a table) is dropped and re-created, the dbkey range is reset. Note: RHE8 can ONLY work with one RDBMS Server instance. As such, all schemas and databases are loaded into the same RDBMS Server instance. Additional RHE8 environments may be setup to support multiple environments, i.e. Test and Production. Database setup & load --------------------- For RHE8, all schemas and subschemas must be re-validated. The validation environment is recorded and verified at run-time. If validation and execution environment does not match, the application will be aborted. The SQL definition of a schema must be generated through GENSQL command or function within MFE8, alternatively generation is done automatically if schema is translated and validated. The SQL definition files are placed under $g8rbddir\schema as follows: nnMTABL.SQL - create all tables and primary index nnMINDX.SQL - create all indexes (Calc, Index key) nnMCONS.SQL - create set indexes and constrains nnDTABL.SQL - create all tables and primary index nnDINDX.SQL - create all indexes (Calc, Index key) nnDCONS.SQL - create set indexes and constrains where nn = schema number Creation of an empty database can be done with the DBACCESS utility, when executed from the ol instance command prompt, ex. dbaccess inf_ids2 \schema\23MTABL.SQL dbaccess inf_ids2 \schema\23MINDX.SQL dbaccess inf_ids2 \schema\23MCONS.SQL When Database location = SCHEMA, GENSQL will generate two additional command files (BAT) as follows: nnCSPACE.BAT - Create SBSPACE for schema nnDSPACE.BAT - Drop SBSPACE for schema When Database location = AREA, GENSQL will generate similar command files (BAT) as follows: nnCSPACE.BAT - Create SBSPACE for all areas within schema nnDSPACE.BAT - Drop SBSPACE for all areas within schema Note: You need to change information and space allocation for each DBSPACE, before you execute the command file. RHE8 utilize almost the same technique for GCOS database unload, as MFE8. First you need to generate unload and load programs for each schema. This is done with DBWFL command or Generate Unload function. The GCOS8 host unload program hhHDBU.CBL and the subschema nnSCHCS.SSD is placed under your current directory. The RHE8 load program is placed within $g8rbddir\schema and automatically compiled. Transfer the nnHDBU.CBL to GCOS8, and optionally the subschema (may already be present on the host). Next compile and execute the nnHDBU program to unload the whole or parts of the host database. Next transfer the unload file(s) to RHE8 environment (UFT/FTP ascii file). Before loading the database, you need to prepare the Informix database as follows: 1) Modify the nnCSPACE.BAT and execute this to create the DBSPACE(s) for the schema. This does not apply for Database location = CURRENT. 2) Set database in 'no-logging' mode using ONDBLOG utility, ex. ONDBLOG nolog inf_ids2 3) Create tables for the schema using DBACCESS utility, ex. DBACCESS inf_ids2 \schema\23MTABL.SQL 4) Load the database using DBLOAD utility, ex. DBLOAD dims dumpdims. _nolog Repeat this step for each unload file, if multiple files were used for GCOS8 unload. 5) Create indexes and constrains for the schema using DBACCESS utility, ex. DBACCESS inf_ids2 \\schema\23MINDX.SQL DBACCESS inf_ids2 \\schema\23MCONS.SQL 6) Set database in 'logging' mode using ONDBLOG utility, ex. ONDBLOG unbuf inf_ids2 The request does not become effective until a level-0 backup is performed for the database. 7) Do a complete (level-0) backup of the database using the ONBAR utility, ex. ONBAR -b -L 0 The DBLOAD utility will execute in two phases if the unload file contains both record and set information (default). In Phase 1, only records are processed and each record is inserted in the database. A serial number (new dbkey) is assigned to each record, and GCOS8 db-key is mapped to the serial number (new dbkey) using a table snn_dbk_map. In Phase 2, only sets are processed and each set membership causes the corresponding record to be updated with the serial number (new dbkey) of the owner. If you need to re-run the DBLOAD utility, it is recommended to drop all tables or the tables involved, and re-create these, before running DBLOAD. This way serial number ranges are reset. The DBLOAD utility may be directed to perform only a single phase, ex. DBLOAD dims dumpdims. _1 DBLOAD dims dumpdims. _2 _u Logging, Backup & Restore ------------------------- Logging ------- For on-line TP8 operation, the database must be protected with logging enabled. By default, logging files are backed up automa- tically (ALARMPROGRAM setting). Should a disaster occur, the database can be fully recovered to a consistently state near the time of disaster. For batch operation, the database may or may not be protected with logging enabled, depending on operation mode and the application. Batch concurrent with on-line: Logging MUST be enabled, and the application must either take frequent checkpoints, or use the 'auto' database mode. Warning: Should the batch program apply incorrect changes to the database, you are NOT able to restore the database without poten- tial loss of changes made through on-line applications. Batch stand-alone: Logging may be enabled, however, the application must either take frequent checkpoints, or use the 'auto' database mode, otherwise the LOCKS resource may be exhausted. Batch stand-alone/heavy: Logging may be disabled, however, be aware the database MUST be backed up (level-0) whenever the logging mode is changed. The application MUST use the 'nolog' database mode, otherwise it will be aborted. For batch, use 'exclusive' database mode, if you want to prevent others (batch or TP8) from accessing the database. For batch, use 'query' database mode, if the application is only reading from the database. When running concurrent with TP8, the batch application will neither reserve locks or respect locks on records. This mode is quite similar to QUERY allocation mode on GCOS8. Backup ------ Informix IDS Server provides following levels of backup: Level-0 - A full backup of the database Level-1 - An incremental backup of changed pages (since level-0) Level-2 - An incremental backup of changed pages (since level-1) Logical Logs - A backup of all changes since last backup A level-0 backup should be performed - after initial load of database - after changing logging mode - at frequent intervals, i.e. once a week, to limit the size of level-1/2 backup and logical logs A level-1/2 backup should be performed - after completion of on-line operation day - after completion of large batch operations Note: If level-2 is requested and no level-1 exist since last level-0 backup, the backup is treated as level-1. Backup operations are requested with the ONBAR utility, ex. ONBAR -b -L 0 ONBAR -b -L 2 Note: Logical logs are backed up automatically, either when filled or when a level-n backup is requested. Restore ------- Informix IDS Server perform automatic recovery should the instance or the server machine fail. For hardware failures, please refer to Informix documentation on how to restore and recover the database to a consistent clean-point, just before the failure occurred. The need for an operational restore may arrise, if an application has logical errors and incorrect updating of the database has occurred, or you need to re-run a batch application, which have partially committed database updates (checkpoint or auto) or was run with logging disabled. By default, a restore request will perform restore and recovery to the most recent consistent clean-point. To restore to a specific operational point, i.e. just before running a batch application, a restore request must be specified with a data/time stamp equivalent to the specific operational point. Note: To ensure proper documentation of operational point and associated date/time stamp, we recommend using BATLOG command to log a meaningful message in the consolidated batch.log (ref. Batch above). Ex. BATLOG Ready to run XXXX program - backup clean-point Restore operations are requested the ONBAR utility, ex. ONBAR -r ONBAR -r -t "yyyy-mm-dd hh:mm:ss" Backup - Wrapper ---------------- A Backup Wrapper utility (DBBCK) may be used to launch database backups and record information about associated time stamps. DBBCK backup-set-name [0|1|2|W] backup-set-name = a meaningful text to identify the backup 0 = Full backup (level-0) 1 = incremental backup (changes since level-0) 2 = incremental backup (changes since level-1) W = Complete backup (level-0) Default is 2 The backup information is recorded in $g8rbddir\BACKUP.CFG. Restore - Wrapper ----------------- A Restore Wrapper utility (DBRES) may be used to launch database restores without knowledge of actual time stamps. DBRES backup-set-name|L|Last-good-backup backup-set-name = the identification used during backup L = the last-good-backup complete The associated time stamp is used to launch a restore to the point right after the backup was completed Note: All restores are cold (Informix shutdown and restarted) and the database is left in Quecient mode after the restore completes. ORACLE ====== Installation ------------ The Oracle 8/8i/9i Database may be installed either on the same NT/ 2000 as RHE8, or on any other server, including Linux and Unix platforms. When installed on another server, you must install the Oracle Client on the RHE8 server and setup appropriate connect string(s) for RHE8. Configuration ------------- Use standard Oracle tuning techniques to achieve the required performance. During load of database you should disable archive logging. Technqiues ---------- All records have a unique dbkey field, which is used as primary key. The dbkey field is implemented as a SERIAL datatype with a min/max range as configured for the schema. During load of database the GCOS dbkey value is remapped to the new dbkey value assigned during load. This remapping apply to set and phantom pointers. When accessing records through Calc or Index keys or sets, RHE8 will use a hint for the appropriate key, and thus force Oracle optimizer to use the correct index for access. Sets are implemented as foreign keys in the member record(s), and the dbkey of the owner is use to enforce a constraint for the set relationship. For manually sorted sets - insertion first/last/next/ prior, an additional order field is maintained. RHE8 always use OPTIMIZER_MODE = FIRST_ROWS. RHE8 Configuration ------------------ Following configuration entries in Database Configuration (DBMS.CFG) may be used enable and configure IDS-II via RDBMS: [SQL-SECTION] ; Enable/Disable RHE SQL-IMPLEMENTATION : ORACLE ; Oracle 8/8i/9i ; ; OFF (ISAM) DATABASE : ora_ids2 ; Database name (TNS name) USERID : scott ; Name of user PASSWORD : tiger ; Password of user NULL-FIX : ON ; Fix null in char OFF(default)/ON NULL-TRACE : OFF ; Trace null fix OFF(default)/ON DEBUG : OFF ; SQL Debug-log OFF(default)/ON ISOLATION : HIGH ; Isolation HIGH(default)/LOW .LOCK-SUPPORT : ON ; .LOCK ON(default)/OFF AREA-SELECT : ON ; ON(default)/OFF DECIMAL-POINT-COMMA : OFF ; OFF(default)/ON MAX-LOAD-UNIT : 10000 ; commit every n (default 500) EXPLAIN : OFF ; OFF(required) WAIT-LOCK : ON ; ON(required) ESQL-C : OFF ; OFF(required) ORDER-PROGRAM : ON ; Enforce non-sorted set ordering On(default)/OFF CASCADE-DELETE : ON ; Use constaint rules ON(Default)/OFF CHECKSUM-CHECK : OFF ; Debug OFF(default)/ON/ALWAYS SQL-IMPLEMENTATION:ORACLE setting enables IDS-II database emulation through Oracle 8/8i/9i. DATABASE setting designate the name of the Oracle database (TNS name). USERID and PASSWORD setting designate which indentification to use when establishing sessions with Oracle. Use the default Scott userid with appropriate password, or any other userid. NULL-FIX:ON setting may be used force NULL characters in CHAR type fields to SPACE. Note: NULL characters, i.e. low-values, are not allowed in CHAR type fields. NULL-TRACE:ON may be used to log information on NULL-FIX activity on the execution log (batch or TP8). Statistics show the field-name and a corresponding count for null-fix operations. DEBUG:ON may be used to log a substantial amount of information about ESQL activity on the $g8rbldir\DBESQL.LOG file. ISOLATION:LOW is default, however, this may changed to HIGH as required. The equivalence for Oracle is as follows: HIGH = SERIALIZABLE LOW = COMMITTED READ Note: Oracle does not support query/nolog mode of operation and will use the isolation level low/high as configured. .LOCK-SUPPORT:ON is default, and a .LOCK service call will cause the current record to be 'locked for update'. Alternatively .LOCK service calls can be ignored (OFF). AREA-SELECT: ON is default, OFF may be used to ignore area selection. Note: When OFF, any area selection procedures are ignored and records are always stored/retrieved from the first realm. All others realms are treated as empty. DECIMAL-POINT-COMMA: OFF is default, ON must be specified if Oracle is configured to treat comma as decimal point. MAX-LOAD-UNIT: 500 is default, may be used to control how often commits are taken during load of database. ESQL-C: OFF is default, and the only option for Oracle. ORDER-PROGRAM: ON is default and use to ensure non-sorted sets are maintained in the appropriate FIRST/LAST/NEXT/PRIOR order. OFF may be used enable a simpler and more efficient emulation (dbkey order), which however is not compatible with GCOS. CASCADE-DELETE: ON is default and will use SQL constaint rules to enforce owner/membership relations, which is effective both for IDS-II and direct SQL database access. OFF may be used suppress use of constraint rules and emulation of ERASE ALL MEMBERS. CHECKSUM-CHECK:OFF is default, however, following settings can be used to recover from some times of memory leaks: ON - cause schema and subschema tables to be checksummed and re- loaded if corrupted, after any DB related abort ALWAYS - cause schema and subschema tables to be checksummed and reloaded if corrupted, during every DML operation Note: ALWAYS gives extensive processor overhead and should be used with care. [SCHEMA-SECTION] ; Number Location Location Dbkey ; (1-99) Schema database allocation per table ; CURRENT DEFAULT (2100000 dbkeys) ; SCHEMA nnnnnnnnn ; AREA CONFIG (separate tag) DIMS : 23 CURRENT CURRENT DEFAULT ; DIMS8 TELEX8 : 24 CURRENT CURRENT DEFAULT ; DIMS8 Schema configuration is different for RHE8, however, the schema number and location is the same as for MFE8/G8RB, likewise, the schema number should NEVER be changed. Location database may be used to control placement of the database for the schema. CURRENT (Default) will place the database within the default SBSPACE of the inf_ids2 database. SCHEMA will place the database within an TABLESPACE with the same name as the schema. AREA will place the database within multiple TABLESPACEs, where each TABLESPACE is given the same name as an area within the schema. Note: A record can ONLY be placed in one TABLESPACE, and the the first area, i.e. WITHIN clause, is always used. Area- selection is not affected by this. Note: For a production environment you should consider use of SCHEMA or AREA location, or a combination of these. DBkey allocation may be used to control the DBkey ranges within a schema. The default is 2100000, and each record within the schema is thus assigned a dbkey range of 2.1 million. CONFIG: May be used to control DBkey allocation at record level. A separate tag is used to specify DBkey allocation details, this tag must be name -INTERVAL, ex. [DIMS-INTERVAL] DEFAULT : 2100000 ; Default allocation COURSE : 40000000 ; Specific allocation SCEHDULE : 80000000 ; Sepcific allocation Note: DBkeys are NOT reused, so the range must be sufficient to support STORE/DELETE over an extended period of time, otherwise the dbkey range will be exhausted eventually. Whenever a schema (a table) is dropped and re-created, the dbkey range is reset. Note: RHE8 can ONLY work with one RDBMS Server instance. As such, all schemas and databases are loaded into the same RDBMS Server instance. Additional RHE8 environments may be setup to support multiple environments, i.e. Test and Production. Database setup & load --------------------- For RHE8, all schemas and subschemas must be re-validated. The validation environment is recorded and verified at run-time. If validation and execution environment does not match, the application will be aborted. The SQL definition of a schema must be generated through GENSQL command or function within MFE8, alternatively generation is done automatically if schema is translated and validated. The SQL definition files are placed under $g8rbddir\schema as follows: nnMTABL.SQL - create all tables and primary index nnMINDX.SQL - create all indexes (Calc, Index key) nnMCONS.SQL - create set indexes and constrains nnDTABL.SQL - create all tables and primary index nnDINDX.SQL - create all indexes (Calc, Index key) nnDCONS.SQL - create set indexes and constrains where nn = schema number Creation of an empty database can be done with the SQL*Plus utility, ex. (first connect to appropriate database> start \schema\23MTABL.SQL start \schema\23MINDX.SQL start \schema\23MCONS.SQL When Database location = SCHEMA, GENSQL will generate two additional SQL definition files as follows: nnMSPACE.SQL - Create TABLESPACE for schema nnDSPACE.SQL - Drop TABLESPACE for schema When Database location = AREA, GENSQL will generate similar SQL definition files as follows: nnMSPACE.SQL - Create TABLESPACE for all areas within schema nnDSPACE.SQL - Drop TABLESPACE for all areas within schema Note: You need to change datafile information and space allocation for each TABLESPACE, before you execute the definition files. RHE8 utilize almost the same technique for GCOS database unload, as MFE8. First you need to generate unload and load programs for each schema. This is done with DBWFL command or Generate Unload function. The GCOS8 host unload program hhHDBU.CBL and the subschema nnSCHCS.SSD is placed under your current directory. The RHE8 load program is placed within $g8rbddir\schema and automatically compiled. Transfer the nnHDBU.CBL to GCOS8, and optionally the subschema (may already be present on the host). Next compile and execute the nnHDBU program to unload the whole or parts of the host database. Next transfer the unload file(s) to RHE8 environment (UFT/FTP ascii file). Before loading the database, you need to prepare the Oracle database as follows: 1) Modify the nnMSPACE.SQL and execute this to create the TABLESPACE(s) for the schema. This does not apply for Database location = CURRENT. 2) Set ARCHIVE LOGGING off using Oracle Console or command. 3) Create tables for the schema using SQL*Plus utility, ex. START \schema\23MTABL.SQL 4) Load the database using DBLOAD utility, ex. DBLOAD dims dumpdims. Repeat this step for each unload file, if multiple files were used for GCOS8 unload, however remember to use _update for all but the first load file, ex. DBLOAD dims dumpdims1. DBLOAD dims dumpdims2. _u DBLOAD dims dumpdims3. _u 5) Create indexes and constrains for the schema using SQL*Plus utility, ex. START \schema\23MINDX.SQL START \schema\23MCONS.SQL 6) Set ARCHIVE LOGGING on using Oracle Console or command. 7) Do a complete backup of the database using Oracle Console or command. The DBLOAD utility will execute in two phases if the unload file contains both record and set information (default). In Phase 1, only records are processed and each record is inserted in the database. A serial number (new dbkey) is assigned to each record, and GCOS8 db-key is mapped to the serial number (new dbkey) using a table snn_dbk_map. In Phase 2, only sets are processed and each set membership causes the corresponding record to be updated with the serial number (new dbkey) of the owner. An optional Phase 3 is triggered if phantom pointers are defined and involved records are detected in Phase 1 (record processing). If you need to re-run the DBLOAD utility, it is recommended to drop all tables or the tables involved, and re-create these, before running DBLOAD. This way serial number ranges are reset. The DBLOAD utility may be directed to perform only a single phase, ex. DBLOAD dims dumpdims. _1 DBLOAD dims dumpdims. _2 _u DBLOAD dims dumpdims. _3 _u (only phantom pointers) Logging ------- For on-line TP8 operation, the database must be protected with archive logging enabled. By default, logging files are backed up automatically. Should a disaster occur, the database can be fully recovered to a consistently state near the time of disaster. Batch concurrent with on-line: The application must either take frequent checkpoints, or use the 'auto' database mode to prevent TP from waiting for resources held by batch application. Batch stand-alone: The application must either take frequent checkpoints, or use the 'auto' database mode, otherwise the LOCKS resource may be exhausted. IBM DB2 ======= Installation ------------ The DB2 UDB 7/8 Database may be installed either on the same NT/ 2000 as RHE8, or on any other server, including Linux and Unix platforms. When installed on another server, you must install the DB2 Client on the RHE8 server and configure the database(s) for DB2. Configuration ------------- Use standard DB2 tuning techniques to achieve the required performance. During load of database you should use circular logging (set 'Retain log files' to NO). Techniques ---------- All records have a unique dbkey field, which is used as primary key. The dbkey field is implemented as a SERIAL datatype with a min/max range as configured for the schema. During load of database the GCOS dbkey value is remapped to the new dbkey value assigned during load. This remapping apply to set and phantom pointers. When accessing records through Calc or Index keys or sets, RHE8 will use a hint for the appropriate key, and thus force DB2 optimizer to use the correct index for access. Sets are implemented as foreign keys in the member record(s), and the dbkey of the owner is use to enforce a constraint for the set relationship. For manually sorted sets - insertion first/last/next/ prior, an additional order field is maintained. RHE8 always use QUERY OPTIMIZATION = 0. RHE8 Configuration ------------------ Following configuration entries in Database Configuration (DBMS.CFG) may be used enable and configure IDS-II via RDBMS: [SQL-SECTION] ; Enable/Disable RHE SQL-IMPLEMENTATION : DB2 ; IBM DB2 UDB 7/8 ; ; OFF (ISAM) DATABASE : db2_ids2 ; Database name USERID : db2admin ; Name of user PASSWORD : db2admin ; Password of user NULL-FIX : OFF ; Change null to space in char OFF(default)/ON ; Null IS allowed in CHAR fields NULL-TRACE : OFF ; Trace null fix OFF(default)/ON PDATA-TRACE : OFF ; Trace 'packed' data in char OFF(default)/ON DEBUG : OFF ; SQL Debug-log OFF(default)/ON EXPLAIN : OFF ; SQL explain OFF(default)/ON ; ON = EXPLAIN MODE YES ; DB2 explain tables MUST be created first ISOLATION : HIGH ; HIGH = READ COMMITTED (not configurable) .LOCK-SUPPORT : ON ; .LOCK ON(default)/OFF AREA-SELECT : ON ; ON(default)/OFF DECIMAL-POINT-COMMA : OFF ; OFF(default)/ON MAX-LOAD-UNIT : 10000 ; commit every n (default 500) WAIT-LOCK : ON ; ON(required) ESQL-C : OFF ; OFF(required) ORDER-PROGRAM : ON ; Enforce non-sorted set ordering On(default)/OFF CASCADE-DELETE : ON ; Use constaint rules ON(Default)/OFF CHECKSUM-CHECK : OFF ; Debug OFF(default)/ON/ALWAYS SQL-IMPLEMENTATION:ORACLE setting enables IDS-II database emulation through DB2 UDB 7/8. DATABASE setting designate the name of the Oracle database (TNS name). USERID and PASSWORD setting designate which indentification to use when establishing sessions with DB2. Use the default db2admin userid with appropriate password, or any other userid. NULL-FIX:ON setting may be used force NULL characters in CHAR type fields to SPACE. Note: NULL characters, i.e. low-values, are allowed in CHAR type fields. NULL-TRACE:ON may be used to log information on NULL detections on the execution log (batch or TP8). Statistics show the field-name and a corresponding count for NULL detections. PDATA-TRACE:ON may be used to log information on 'packed' data detections on the execution log (batch or TP8). Statistics show the field-name and a corresponding count for 'packed' data detections. DEBUG:ON may be used to log a substantial amount of information about ESQL activity on the $g8rbldir\DBESQL.LOG file. EXPLAIN:ON may be used to set explain mode for dynamic SQL operations performed by RHE8. The explain information is logged in the DB2 explain tables. Note: The DB2 explain tables MUST be created before you enable this feature. Refer to DB2 documentatuion for further details. ISOLATION:HIGH is default, and equivalent to READ COMMITTED. This is not configurable. Note: DB2 does not support query/nolog mode of operation and will always use the isolation level high. .LOCK-SUPPORT:ON is default, and a .LOCK service call will cause the current record to be 'locked for update'. Alternatively .LOCK service calls can be ignored (OFF). AREA-SELECT: ON is default, OFF may be used to ignore area selection. Note: When OFF, any area selection procedures are ignored and records are always stored/retrieved from the first realm. All others realms are treated as empty. MAX-LOAD-UNIT: 500 is default, may be used to control how often commits are taken during load of database. ESQL-C: OFF is default, and the only option for Oracle. ORDER-PROGRAM: ON is default and use to ensure non-sorted sets are maintained in the appropriate FIRST/LAST/NEXT/PRIOR order. OFF may be used enable a simpler and more efficient emulation (dbkey order), which however is not compatible with GCOS. CASCADE-DELETE: ON is default and will use SQL constaint rules to enforce owner/membership relations, which is effective both for IDS-II and direct SQL database access. OFF may be used suppress use of constraint rules and emulation of ERASE ALL MEMBERS. CHECKSUM-CHECK:OFF is default, however, following settings can be used to recover from some times of memory leaks: ON - cause schema and subschema tables to be checksummed and re- loaded if corrupted, after any DB related abort ALWAYS - cause schema and subschema tables to be checksummed and reloaded if corrupted, during every DML operation Note: ALWAYS gives extensive processor overhead and should be used with care. [SCHEMA-SECTION] ; Number Location Location Dbkey ; (1-99) Schema database allocation per table ; CURRENT DEFAULT (2100000 dbkeys) ; SCHEMA nnnnnnnnn ; AREA CONFIG (separate tag) DIMS : 23 CURRENT CURRENT DEFAULT ; DIMS8 TELEX8 : 24 CURRENT CURRENT DEFAULT ; DIMS8 Schema configuration is different for RHE8, however, the schema number and location is the same as for MFE8/G8RB, likewise, the schema number should NEVER be changed. Location database may be used to control placement of the database for the schema. CURRENT (Default) will place the database within the default SBSPACE of the inf_ids2 database. SCHEMA will place the database within an TABLESPACE with the same name as the schema. AREA will place the database within multiple TABLESPACEs, where each TABLESPACE is given the same name as an area within the schema. Note: A record can ONLY be placed in one TABLESPACE, and the the first area, i.e. WITHIN clause, is always used. Area- selection is not affected by this. Note: For a production environment you should consider use of SCHEMA or AREA location, or a combination of these. DBkey allocation may be used to control the DBkey ranges within a schema. The default is 2100000, and each record within the schema is thus assigned a dbkey range of 2.1 million. CONFIG: May be used to control DBkey allocation at record level. A separate tag is used to specify DBkey allocation details, this tag must be name -INTERVAL, ex. [DIMS-INTERVAL] DEFAULT : 2100000 ; Default allocation COURSE : 40000000 ; Specific allocation SCEHDULE : 80000000 ; Sepcific allocation Note: DBkeys are NOT reused, so the range must be sufficient to support STORE/DELETE over an extended period of time, otherwise the dbkey range will be exhausted eventually. Whenever a schema (a table) is dropped and re-created, the dbkey range is reset. Note: RHE8 can ONLY work with one RDBMS Server instance. As such, all schemas and databases are loaded into the same RDBMS Server instance. Additional RHE8 environments may be setup to support multiple environments, i.e. Test and Production. Database setup & load --------------------- For RHE8, all schemas and subschemas must be re-validated. The validation environment is recorded and verified at run-time. If validation and execution environment does not match, the application will be aborted. The SQL definition of a schema must be generated through GENSQL command or function within MFE8, alternatively generation is done automatically if schema is translated and validated. The SQL definition files are placed under $g8rbddir\schema as follows: nnMTABL.SQL - create all tables and primary index nnMINDX.SQL - create all indexes (Calc, Index key) nnMCONS.SQL - create set indexes and constrains nnDTABL.SQL - create all tables and primary index nnDINDX.SQL - create all indexes (Calc, Index key) nnDCONS.SQL - create set indexes and constrains where nn = schema number A corresponding set of command files (BAT) are generated, which may be launched from a DB2 command window. Each command file contains a CONNECT, execution of SQL file and a DISCONNECT. Creation of an empty database can be done from a DB2 command window, ex. \schema\23MTABL.BAT \schema\23MINDX.BAT \schema\23MCONS.BAT When Database location = SCHEMA, GENSQL will generate two additional SQL definition files as follows: nnMSPACE.SQL - Create TABLESPACE for schema nnDSPACE.SQL - Drop TABLESPACE for schema When Database location = AREA, GENSQL will generate similar SQL definition files as follows: nnMSPACE.SQL - Create TABLESPACE for all areas within schema nnDSPACE.SQL - Drop TABLESPACE for all areas within schema Note: You need to change datafile information and space allocation for each TABLESPACE, before you execute the definition files. RHE8 utilize almost the same technique for GCOS database unload, as MFE8. First you need to generate unload and load programs for each schema. This is done with DBWFL command or Generate Unload function. The GCOS8 host unload program hhHDBU.CBL and the subschema nnSCHCS.SSD is placed under your current directory. The RHE8 load program is placed within $g8rbddir\schema and automatically compiled. Transfer the nnHDBU.CBL to GCOS8, and optionally the subschema (may already be present on the host). Next compile and execute the nnHDBU program to unload the whole or parts of the host database. Next transfer the unload file(s) to RHE8 environment (UFT/FTP ascii file). Before loading the database, you need to prepare the DB2 database as follows: 1) First bind the RHE8 interface to the DB2 database using the command: RUN INITBND 2) Modify the nnMSPACE.SQL and execute this to create the TABLESPACE(s) for the schema. This does not apply for Database location = CURRENT. 3) Set 'Retain log files' to NO using DB2 Control Center or DB2 command. 4) Create tables for the schema using DB2 Command window, ex. \schema\23MTABL.BAT 5) Load the database using DBLOAD utility, ex. DBLOAD dims dumpdims. Repeat this step for each unload file, if multiple files were used for GCOS8 unload, however, remember to use _update for all but the first load file, ex. DBLOAD dims dumpdims1. DBLOAD dims dumpdims2. _u DBLOAD dims dumpdims3. _u 6) Create indexes and constrains for the schema using DB2 Command window, ex. \schema\23MINDX.BAT \schema\23MCONS.BAT 7) Set 'Retain log files' to RECOVERY or CAPTURE using DB2 Control Center or DB2 command. 8) Do a complete backup of the database using DB2 Control Center or DB2 command. The DBLOAD utility will execute in two phases if the unload file contains both record and set information (default). In Phase 1, only records are processed and each record is inserted in the database. A serial number (new dbkey) is assigned to each record, and GCOS8 db-key is mapped to the serial number (new dbkey) using a table snn_dbk_map. In Phase 2, only sets are processed and each set membership causes the corresponding record to be updated with the serial number (new dbkey) of the owner. An optional Phase 3 is triggered if phantom pointers are defined and involved records are detected in Phase 1 (record processing). If you need to re-run the DBLOAD utility, it is recommended to drop all tables or the tables involved, and re-create these, before running DBLOAD. This way serial number ranges are reset. The DBLOAD utility may be directed to perform only a single phase, ex. DBLOAD dims dumpdims. _1 DBLOAD dims dumpdims. _2 _u DBLOAD dims dumpdims. _3 _u (only phantom pointers) Logging ------- For on-line TP8 operation, the database should be protected with proper 'Retain log files' setting. Should a disaster occur, the database can be fully recovered to a consistently state near the time of disaster. Batch concurrent with on-line: The application must either take frequent checkpoints, or use the 'auto' database mode to prevent TP from waiting for resources held by batch application. Batch stand-alone: The application must either take frequent checkpoints, or use the 'auto' database mode, otherwise the LOCKS resource may be exhausted. MICROSOFT SQL SERVER ==================== Currently not documented. DIMS8 ===== DIMS8 - a Forms Management System, utilize additional run-time files as follows: LID Swap file PAGE Swap File For RHE8, these files are implemented as separate files for each user, identified by Lid index from TP8 Server. The files are placed under G8RBSDIR. ERRORS FIXED & IMPROVEMENTS IN RELEASE ====================================== o DATE/TIME: Configuration of Date, Day and Time has been made more flexible. The Default configuration has been changed as follows: SYSTEM-DATE : CURRENT|DYNAMIC|yymmdd ; default current SYSTEM-TIME : CURRENT|DYNAMIC|hhmm[ss[hs]] ; default current Note: SYSTEM-DAY setting no longer exist, instead julian date is derived from system date. For Batch, the DYNAMIC setting will trigger read of the environment variables: GCOS-SYSTEM-DATE GCOS-SYSTEM-TIME the value setting is similar to default configuration. For TP8, the DYNAMIC or an explicit setting will allow date and/or time to be changed through service transaction as follows: $DATE yymmdd $TIME hhmm[ss[hs]] may be used to change the date and/or time during a TP8 session. o TP8: Tuxedo and TX Series Encina is now supported for TP8. o DBSP: RHE8B now support DBSP and thus allows you to develop and execute DBSP programs within RHE8. See $g8rbgdir\dbsp.txt for details. o WEB8: Support has been updated to v2.0 and support of browser connection via HTTP-DSA Gateway and GEAP. o TP: The default entry for CREATE_COMMAND, which is used to start a transaction without a create_command entry, may now specify a first-tpr and profile, ex. ******** : SLDINP SOLDDBK ; Default is SOLD+ TX o TP Bibo: The TPCLI command now support a command line to enable execution of a single BIBO transaction or a BIBO transaction file. o Terminal Emulation: When using terminal emulation software, ex. Glink, VTD/Amaril, with TELNET or TNVIP interface, the national character-set configuration may now be identical for GCOS and G8WB (adapted to/from PC standard by the interface, whenever CHARACTER-SET-ADJUST is active). o WEB8: The 'Referer:' header field is now emulated, so a TPR can retrieve the information through HTTP_GETHDR. The format is GCOS compatible, ex. http://gateway:8080/node.mbx/TPLocG8WB/Command/Options ---------------------------- I I-> constant o TP/TNVIP: The command $BYE is treated as $TERM when connection to TP is done trough terminal emulation software, ex. GLINK. o WEB8: Graphic files are now supported. o WEB8: Forms import now provide a more flexible configuration of //localhost. o WEB8: Forms import now provide additional default file extensions for the index function. o Open-Client-Toolkit: A new and simpler interface is provided for interfacing TP8 client application with MFE8. Refer to $g8rbgdir\site\client\otc.txt for details. ============ TIPS & HINTS ============ n/a ============ KNOWN ERRORS ============ o MFEXTMAP: If the MFEXTMAP.DAT file contains an entry with only one word on the line, the file is not processed correctly (mapping does not work) and the MFEXTMAP.DAT file will be left in a 'busy' state (unable to update). This error can typically occur if comment lines are placed in MFEXTMAP.DAT, ex. * * Above line will trigger problem * Line below will not trigger problem * * * My test files sysin in1.dat o CONFIG: If you forget the ":" (separate keyword from arguments) in a config-file entry, you do not always get an error message. ================= KNOWN LIMITATIONS ================= o SYSOUT: The SYSOUT file will be closed if a program is cancelled. If generic or default mapping is used, then some SYSOUT may be lost if a program writing to SYSOUT (DISPLAY verb) is cancelled. o MFEXTMAP: The number of entries in MFEXTMAP.DAT is limited by Environment Space under Windows 95 and 98, as all entries in MFEXTMAP.DAT file is placed into environment during startup of a Workbench function. The maximum size of environment space may be controlled via a 'SHELL=... /E:nnnn' entry in config.sys. If no size is specified, the maximum is 32768 bytes. Note: If environment space is insufficient, the MFEXTMAP.DAT file is not processed correctly (mapping does not work) and the MFEXTMAP.DAT file will be left in a 'busy' state (unable to update). o MFEXTMAP.DAT: General performance is very sensitive to the placement and size of the MFEXTMAP.DAT. Placing an MFEXTMAP.DAT with more than a few (10-20) mapping entries on a network drive, can result in degraded performance, depending on network setup. As a temporary solution, you should either only work with a local MFEXTMAP.DAT or copy your global (on a network drive) MFEXTMAP.DAT file into a local drive during startup of RHE8, if you experience such degraded performance. =================== MANUAL INSTALLATION =================== Manual installation is not possible with RHE8 and Application Server. ================= PROBLEM REPORTING ================= Please use the enclosed Software Problem Reporting (SPR) forms for problem reporting. Describe your problem in as much detail as possible, providing example(s) and/or other supporting material if possible, and send this to B & C Solution P.O. Box 54 Ole Piisvej 4 DK-3100 Hornbaek Denmark or fax to +45 49.70.47.80 or send through email to support@bc-solution.com If you have any questions, suggestions for changes and/or improvements, please do not hesitate to let us know. More recent updates are available through INTERNET for download or verification of update content. Connect to our web-site 'http://www.bc-solution.com', go to the Support section and select 'GCOS8 Rehosting Express V4.0 Update' under Download Software Update. 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 Rehosting Express and GCOS8 Mainframe Express are trademarks of B & C Solution. All other trademarks and trade names are the property of their respective owners. ========================================================================= Copyright (C) 1998-2004 B & C Solution. All Rights Reserved.