TS Network Basic with DataServerTM Installation Guide Version 8.7.1 285 Davidson Ave. • Ste. 302 • Somerset, NJ 08873 Telephone: 732-560-1377 • Outside NJ 800-524-0430 Fax: 732-560-1594 Internet address: http://www.tbred.com Published by: Thoroughbred Software International, Inc. 285 Davidson Ave., Suite 302 Somerset, New Jersey 08873 Copyright 2012 by Thoroughbred Software International, Inc. All rights reserved. No part of the contents of this document may be reproduced or transmitted in any form or by any means without the written permission of the publisher. Document Number: TNBDS8.7.1I101 The Thoroughbred logo, Swash logo, and Solution-IV Accounting logo, OPENWORKSHOP, THOROUGHBRED, VIP FOR DICTIONARY-IV, VIP, VIPImage, DICTIONARY-IV, and SOLUTION-IV are registered trademarks of Thoroughbred Software International, Inc. Thoroughbred Basic, TS Environment, T-WEB, Script-IV, Report-IV, Query-IV, Source-IV, TS Network DataServer, TS ODBC DataServer, TS ODBC R/W DataServer, TS ORACLE DataServer, TS DataServer, TS XML DataServer, GWW, Gateway for Windows™, TS ChartServer, TS ReportServer, TS WebServer, TbredComm, WorkStation Manager, Solution-IV Reprographics, Solution-IV ezRepro, TS/Xpress, and DataSafeGuard are trademarks of Thoroughbred Software International, Inc. Other names, products and services mentioned are the trademarks or registered trademarks of their respective vendors or organizations. . 2 Copyright 2012 Thoroughbred Software International, Inc. INTRODUCTION TS Network Basic is an integral part of the Thoroughbred Software network solution. Server data can be made available across platforms for use in Dictionary-IV file maintenance, Report-IV, Query-IV, ScriptIV, and Basic applications. With TS Network DataServer software: Applications can now be configured to access a Network DataServer. New or existing applications can access and share data across a network. When you access a file on another computer there is a large amount of network communication associated with accessing keys and locking records. This network traffic is in addition to the communication necessary to transfer the data. Current file sharing capabilities with NFS, Netware, and Microsoft Network provide low-level access to files on other systems. They do not, provide acceptable levels of performance or insure data integrity. TS Network DataServer allows much of the logic required for distributed file I/O to reside on the system that contains the data. This process minimizes network exchanges and provides improved performance. This guide first describes the Client side of TS Network DataServer, which is provided with every Thoroughbred Environment installation. It then provides specific information for Thoroughbred servers. BEFORE INSTALLING THIS PRODUCT: Please refer to the latest Release Notes found on the product CD. Package Contents Your CD is configured for a packaged bundle and operating system. Review the CD label to insure receipt of the correct packaged bundle and your target operating system. TS Network Basic with DataServer Thoroughbred OPENworkshop VIP Host VIP Client TS ReportServer TS ChartServer Gateway for Windows Requirements To run TS Network DataServer your system must meet the following requirements: Windows 2000/XP/2003/Vista/Windows7/2008. 1 Copyright 2012 Thoroughbred Software International, Inc. Once the installation is complete, server access is enabled by the addition of a number of configuration items. Refer to the sections that follow for instructions about creating or modifying the SERVER.MAP and IPLINPUT file, TERM.MAP file, and executing the Server Startup Program. TS Network Basic with DataServer Components The TS Network Basic with DataServer consists of three components: A Client enabled Thoroughbred Environment, A Startup Program (tsmgr), and A Server Process (tsserv) for each connection. Client Enabled Thoroughbred Environment The client side is enabled in a standard Thoroughbred Environment. When configured for data server access, it detects requests for data that reside on a server. When this event occurs, it sends the I/O request to the server for processing. The server responds with the resulting set and processing continues. Startup Program (tsmgr) The Startup Program (tsmgr) creates server processes for clients as needed. When the Startup Program detects a client attempting to connect, it tries to create a Server Process for the client. If a server process is created successfully, they can perform client/server communications. NOTE: A server system must have the Startup Program running before clients attempt to connect to it. Server Process (tsserv) The Server Process (tsserv) is triggered by requests from the client. Once a request is received, it is processed and the results returned to the client. System Architecture The following diagram describes the configuration of components for the Thoroughbred Client. Client on System A and Server on System B. System A System B Thoroughbred Client System running a Thoroughbred Environment Startup Program (tsmgr) that handles communication between the Client and Server 2 Server Process (tsserv) Copyright 2012 Thoroughbred Software International, Inc. INSTALLATION NOTE: All Thoroughbred Windows based products prior to Version 8.7.0 must first be uninstalled and then the 8.7.1 release installed. Only 8.7.0 can be upgraded to 8.7.1 and only 8.7.0 and 8.7.1 can co-exist on the same system. If you are upgrading a pre 8.7.0 release, BEFORE continuing with this installation, please see the Uninstalling TS Network Basic with DataServer section below to properly prepare your system for 8.7.1. Back Up Existing Program and Data File Before Installing Use site procedures to back up your application and data files. Use site procedures to back up the IPL, IPLINPUT, and TERMINAL files from the Thoroughbred Basic directory. From the IDL4 subdirectory, back up the TCONFIGW and TCONFIG8 files. Uninstalling TS Network Basic with DataServer These instructions assume you had previously installed using the default folder C:\Program Files\Tbsc. The folder names may vary slightly depending upon which products you have installed and where the products were originally installed. 1. Login using an Administrator account. 2. Backup your application data and programs. 3. From the Administrative tools select Services and stop the Thoroughbred Server Manager (tsmgr.exe). 4. Uninstall the Thoroughbred Server Manager by running srvcmgr.exe with the –d argument. From the Windows Start menu Select RUN. Click on the Browse button and point to the folder where you installed the Basic. Typically this is C:\Program Files\Tbsc. Highlight the file named srvcmgr.exe and press the Open button. Edit the Open option in the Run dialog appending the -d option. The run option is not quoted. For example: C:\Program Files\Tbsc\srvcmgr.exe –d From the Run dialog press OK. If the service is deleted a message box will display saying: Service 'tsmgr' successfully deleted! When the Thoroughbred Server Manager is uninstalled click the OK button and continue with the uninstall procedure. If the service could not be deleted, a message box will display saying: Unable to delete service 'tsmgr'!. If the delete fails do not continue with the uninstall procedure, contact Thoroughbred Support for assistance. 5. From the Control Panel select the applet to add and remove applications. Remove TS Network Basic with DataServer. 3 Copyright 2012 Thoroughbred Software International, Inc. 6. Files not installed by the setup or files that have changed since the setup was run are not removed. If you have already uninstalled other Thoroughbred products some the following files may no longer exist. Erase the following folders and files: C:\Program Files\Tbsc C:\Windows\Tsi.ini C:\Windows\tsiconst.ini C:\Windows\TBRED86.BAS 7. We recommend running a reliable registry cleaner at this point. 8. Reboot your system. The system is now ready for the 8.7.1 TS Network Basic with DataServer installation. When that is complete you can recover your application data and programs. If you are installing on Vista/2008 please be sure to review the Installed Directories and Files section of this manual before you recover your application files. Installed Directories and Files NOTE: Starting with 8.7.0 the location of some TS Network Basic with DataServer directories and files have changed. Unlike previous releases Thoroughbred files should not be moved as this will render various ini file entries and registry keys invalid. Windows Vista/Windows 7/Windows Server 2008 The installs follow Vista best practice rules. Some of the rules enforced by Vista are: all executables must be installed in Program Files, files that require read write access cannot be installed in Program Files or Window system folders. This required a new directory structure. All executables are located in \Program Files\Tbsc. Files and folders shared by all users requiring read and write access are located in the common data directory \ProgramData\Thoroughbred Software\Tbsc. This includes IPLINPUT.TXT, TERMINAL, TCONFIG files, and the IDL4, UTILS, and WORK folders. TSI.ini and Tsiconst.ini are now located in \ProgramData\Thoroughbred Software. Vista will mirror files in \ProgramData\Thoroughbred Software\Tbsc and Users\All Users\Thoroughbred Software. When referencing directories the Server ID must be included. To specify the IDL4 directory defined as DEV D0,1,,2,,,,S1:IDL4 use S1:IDL4. Windows Server 2000/Windows XP/Windows Server 2003 The default folder for all files including executables is C:\Program Files\Tbsc. 4 Copyright 2012 Thoroughbred Software International, Inc. Files previously written to C:\Windows are now written to the common data application folder. This folder varies depending upon the operating system. For XP the folder is \Documents and Settings\All Users\Application Data\Thoroughbred Software. Thoroughbred services previously installed in C:\Windows\System32 are now installed in the same folder as Basic; i.e. C:\Program Files\Tbsc. Installing the Host Files to Your Hard Drive All installations and activations must be run with Administrator privileges. Once fully installed and activated the products can be run using standard user accounts. If you are installing on Windows Server running Terminal Services in application mode switch to Install Mode prior to running setup.exe. To set Install Mode, from a command line enter chgusr /INSTALL. After completing the install, switch back to Execute Mode. From a command line enter chgusr /EXECUTE. At any time the current mode can be verified with chgusr /QUERY. The chgusr command is a Terminal Services tool. For more information regarding installing applications with Terminal Services please refer to Microsoft documentation. 1. Login using an Administrator account. 2. We recommend closing all unnecessary applications before running the install. Verify the operating system noted on the CD matches the target operating system. If the installation and the target operating system do not match, you will not be able to activate the product. Insert the 8.7.1 CD. Browse the CD and run setup.exe located in the Tsnetbas folder. 3. The InstallShield Wizard will start the installation process. You can exit this installation at anytime by selecting the Cancel button. User Information Enter your Name and Company. Thoroughbred Module Code Enter the Module Code located on the label. You must enter the correct module code for your product. If you make a mistake you will not be able to activate your system. Choose Destination Location The default is C:\Program Files\Tbsc. We strongly recommend installing into the default folder. 5 Copyright 2012 Thoroughbred Software International, Inc. NOTE: If you are installing on 2008 you must install into the Program Files folder. Select the Next button if this is where you want to install. Type the path or press the Browse button to select a different installation folder. Serial Number The installation procedure will display a dialog box to collect the serial number. Enter the Serial Number provided on the media label. If the operating system noted on the media does not match the target operating system, the serial number will not be validated. A serial number must be entered before TS Network Basic with DataServer can be run. The serial number can be entered at any time by manually executing CollectSSN.exe: Locate CollectSSN.exe in the <install-path>\directory. For example C:\Program Files\Tbsc Double click to execute it and enter the serial number from your CD label. If a serial number is not entered, then TS Network Basic with DataServer will not run and an "Unauthorized Installation" message will be displayed. Setup Complete Click Finish and then reboot the system. See the OPENworkshop and Dictionary-IV Installation guides located on your CD. Installing the Client Files to Your Hard Drive The Host installation creates an Install folder on the server containing the installation files required for the Client installation. The client is installed by sharing this folder, mapping a drive to it and then running the client setup. Share and Map the Client to the Host 2000/XP/2003 On the host, share the folder where the executables are installed, (for example C:\Program Files\Tbsc). On the client, create a mapped drive to the server connecting to the directory where TS Network Basic with DataServer is installed (for example, H:\Program Files\Tbsc). Install Client 2000/XP/2003 On the client, open the Install folder residing on the server (for example, H:\Program Files\Tbsc\Install). Double click on Setup.exe to start the installation for the client. 6 Copyright 2012 Thoroughbred Software International, Inc. InstallShield will display a dialog with the following input fields: Shortcut Name You will have the option to enter a shortcut name overriding the default name. Shortcut Target Value This is automatically set. It will contain the mapped drive where TS Network Basic with DataServer was installed. ShortCut Start in Value This is automatically set. For these operating systems the start in value and the target value are the same. Share and Map the Client to the Host Vista/2008 Host On the host, share the folder where the executables and dlls are installed (for example, C:\Program Files\Tbsc). On the host, share the common data folder where the OPENworkshop data environment is installed (for example, C:\ProgramData\Thoroughbred Software\Tbsc). Client On the client, create a mapped drive to the server connecting to the directory where Network Basic executables are installed (for example, H:\Program Files\Tbsc). On the client, create a mapped drive to the server connecting to the directory where the OPENworkshop data environment is installed (for example, V:\ProgramData\Thoroughbred Software\Tbsc). Install Client Vista/2008 On the client, open the mapped drive with the Network Basic with DataServer executables and browse for the Install folder, for example H:\Install. Open the Install folder and double click on Setup.exe to start the installation for the client. InstallShield will display a dialog with the following input fields: Shortcut Name You will have the option to enter a shortcut name overriding the default name. Shortcut Target Value This is automatically set for you. It will contain the mapped drive where the Network Basic executables have been installed (for example, H:\b.exe). ShortCut Start in Value Enter the mapped drive with the common data folder. If C:\ProgramData\Thoroughbred Software\Tbsc was shared and mapped to V, the Start In Value would be V:\. If C:\ProgramData was shared and mapped to Z the start in value would be Z:\Throughbred Software\Tbsc. 7 Copyright 2012 Thoroughbred Software International, Inc. CONFIGURING THE CLIENT ENVIRONMENT To setup TS Network DataServer software you must configure network communications and server access for the client. The following files must be created or modified: SERVER.MAP IPLINPUT TERM.MAP On Vista and 2008 these are located in the common data directory. For example, C:\ProgramData\Thoroughbred Software\Tbsc. SERVER.MAP The SERVER.MAP text file establishes a relationship between a 2-character Server ID used by Thoroughbred and the server system. Thoroughbred uses the Server ID to reference the server system. Enter a line in the file for each server. The syntax for an entry is: server-id:[host-name]::PARENT server-id is a 2-character alphanumeric string used within Basic to reference a particular server system. host-name is the host name for the server system. IPLINPUT Once you establish the server ID you can make the required entries for the IPLINPUT file. Each DEV line corresponds to a directory on the server. The syntax for a DEV line is: DEV device-name,1,,server-flag,,,,server-id:path device-name is device ID used to reference logical disk directories. Valid values range from D0 through DZ. server-flag informs Basic that the disk directory is located on a server and defines the type of server. The value for the Thoroughbred server is 2. 8 Copyright 2012 Thoroughbred Software International, Inc. server-id is the two-character alphanumeric code assigned to this server. The server ID on the DEV line must match an entry in the SERVER.MAP file. path is the directory (on the server) where the data resides. The path may or may not be a fully qualified path. If it is not a fully qualified path, it is interpreted as relative to the directory where the server executable resides. Example The following are example of valid DEV lines (using the SERVER.MAP entries defined previously): DEV D0,1,,2,,,,S1:IDL4 An IPLINPUT file may contain DEV lines that point to directories on the Client system and DEV lines that point to directories on the Server system. TERM.MAP The Thoroughbred Environment and the Server Process (tsserv) uses terminal IDs to enforce data integrity (record and file locking). Terminal IDs must be unique not only with other client Basics but also with each server connection. The client and server(s) negotiate at startup to establish a terminal ID that is unique for the client Basic and all servers connected. Therefore it is not recommended that client Basics be initiated as follows: ./b T5 Terminal table assignment is accomplished using TERM.MAP. See the Thoroughbred Basic Customization and Tuning Guide for information on creating and maintaining the TERM.MAP file. 9 Copyright 2012 Thoroughbred Software International, Inc. ACTIVATION OF THE TS DATASERVER To activate the TS DataServer: 1. Login as Administrator. 2. From the Start menu select All Programs-->Thoroughbred Software-->Server Activation. 3. The TS Network DataServer Security dialog will display: 4. Your Serial Number and Installation Code will be displayed. Enter your Activation Key and press Authorize to activate the TS DataServer. 10 Copyright 2012 Thoroughbred Software International, Inc. USING TS NETWORK DATASERVER The following describes how to access and manage server connections. Operating System Interface The Thoroughbred server makes any Thoroughbred native file accessible to a client. This includes Programs and Object Libraries. Your entire application may reside on the server. If your application does an operating system check, the results are based on the Client Basic. It is important to understand that instructions that are operating system specific may not generate expected results. Server Process Starting the Server Process The installation sets up the Thoroughbred server as an automatic service. The server process is initiated each time the system is started. You can manually start and stop the Server Process through Services in the Control Panel. Managing the Server Processes A server system that is running properly has one instance of the Startup Program (tsmgr) running and one instance of the Server Process (tsserv) running for every client that is connected. For a given client machine and server system, there is a one-to-one correspondence between the client and server processes. When a client connects to a server, a Server Process is created for that client by tsmgr. When the client quits, the associated Server Process (tsserv) also terminates. The Thoroughbred utility tbpview.exe can be used to produce a listing of processes that are currently running. This program can be found in the Thoroughbred folder (e.g. C:\Program Files\Tbsc). When tsmgr is not running, the (empty) output should be similar to the following dialog box: List of Processes Currently Running 11 Copyright 2012 Thoroughbred Software International, Inc. Client Connection Once the Server Process is up and running, clients can begin to connect. For each DEV line in the IPLINPUT file that specifies a connection to a server, an attempt is made to connect to that server. If an existing connection already exists, the existing virtual circuit will be used for communication. If no existing connection exists, a virtual circuit to the server will be created. If a connection cannot be made, an appropriate error message will be displayed. The device will be disabled. NOTE: If there are no servers defined in the IPLINPUT file or the client could not connect the defined servers, the client can still operate accessing local files. On Vista and 2008 Network Basic can only be run from a shortcut with a target value pointing to the Basic executables and a start in value pointing to the common data directory. For more information please see the Install Client Vista/2008 section of this manual. Managing the Number of Connections The server manages the number of connections. Each time a new connection is initialized, the user count will be incremented. When a user exits Basic (RELEASE), the user will be removed from the count. OPENing Data Files Thoroughbred client follows the same methodology as standard Basic when searching for files. The disk directories are searched in the order they are defined in the IPLINPUT file. If the client Basic attempts to OPEN /home/data/filename, the search starts with the first hierarchical disk defined in the IPLINPUT file. The client and each server may have a hierarchical disk directory defined in the IPLINPUT file. Adding a server ID to the above path S1:home/data/filename does not force access to the server. In this example the server ID S1 is ignored and the search is done as if the server ID did not exist. On Vista and 2008 when referencing a directory the Server ID must be included. To specify an IDL4 directory defined as DEV D0,1,,2,,,,S1:IDL4 you must use S1:IDL4. Data Security The server Process (tsserv) is installed with the set-UID bit set. Therefore, the client has the same permissions as the owner of the Server Process (tsserv) when accessing files on the server. 12 Copyright 2012 Thoroughbred Software International, Inc. ERROR MESSAGES The following describes startup and Client Error Messages. Startup Messages Unable to get host information for host name: Explanation: The host name in the SERVER.MAP file is not valid. Action: Verify that the SERVER.MAP file contains valid host name entries for all of the defined servers. Unable to get host information for host address: Explanation: The address in the SERVER.MAP file is not valid. Either the format is not correct or the address does not exist. Action: Verify that the SERVER.MAP file contains valid addresses for all of the defined servers. Invalid SERVER.MAP entry for Server: Explanation: The entry in the SERVER.MAP file is not valid. Action: Verify that the entries in the SERVER.MAP file are not missing any fields. Unable to connect to Server: Explanation: The client was unsuccessful in its attempt to connect to the server. Action: Verify that the Startup Program (tsmgr) is running on the server. Verify that the port number in the SERVER.MAP file is 5680. Verify that the network is up and functional. Try alternate methods of communicating with the Server (e.g., ping, telnet, rlogin, rcp, ftp) or notify your network administrator. Client Error Messages Error 103 Explanation: Operating system error. When running TS Network DataServer, there might be an error from a call made to the Socket API. The cause may be a broken or lost connection to the server. Action: The client must exit Basic and restart. 13 Copyright 2012 Thoroughbred Software International, Inc. TROUBLESHOOTING The following provides troubleshooting information for the Thoroughbred Server. Server Crash If the server crashes or the connection is lost, any attempt to access data on the server results in and Error 103. The client must exit Basic and restart. Performance Performance problems can be caused by network connection or by the hangs that occasionally occur in mixed operating system environments. Contact the network administrator to determine if network problems exist. To see if you are running into excessive “hang” conditions, type: DUMP IPLDEVS “STATS=YES” The listing shows the timeout errors for those servers to which the client is connected. The listing should look similar to: Listing of Timeout Errors *** IPL ENVIRONMENT INFORMATION *** TCP TIMEOUT INFORMATION Level Server 1 2 3 4 5 6 7 8 9 10 Total S1:Server1 1 0 0 0 0 0 0 0 0 0 1 S2:Server1 4 2 0 0 0 0 0 0 0 0 6 *** END OF DUMP2 Remember that a Level 1 error is a timeout after one second, a Level 2 error is a timeout after two seconds, a Level 3 error is a timeout after four seconds, etc. You should also contact the Server System Administrator to verify that the server is fully functional. 14 Copyright 2012 Thoroughbred Software International, Inc.