Microsoft Host Data Replicator Release Notes 9/29/97 This README file contains important late-breaking information about installing and using Host Data Replicator. Use this file in conjunction with the installation instructions contained in your printed Host Data Replicator CD insert. If you are installing an evaluation version of Host Data Replicator that you obtained via the World Wide Web or from the Microsoft Select CD, use this README file in conjunction with the SETUP.WRI file included with the Host Data Replicator product. Contents ------------ System Requirements Upgrading from Previous Product Versions Addition to Installation and Configuration Instructions Configuring the Replicator Service to Log On As a User Account Using HDR with Extended Characters Limiting the Number of Database Connections Used by HDR Managing the Size of the History Log Changes to Replicator Manager Data Truncation Warning SQL Server Devices, Databases, and HDR Configuration Transferring Control Database Information to Text Files Frequently Asked Questions System Requirements ----------------------------- Host Data Replicator runs in the Windows NT Server environment. It communicates with Microsoft SQL Server and IBM DB2 database management systems. For proper installation and operation of Host Data Replicator, make sure your systems meet the following requirements: 1. Any DB2 system that will provide data to or receive data from Host Data Replicator must use one of the following versions of IBM DB2: DB2 for AIX/6000 V2.R1 and later DB2 for MVS V2.R3, V3.R1, and V4.R1 and later DB2 for OS/2 V2.R1 and later DB2 for OS/400 V2.R2, V2.R3, V3.R0.M5, and V3.R1 and later DB2 for VM and VSE V3.R1 and later DB2 for Windows NT V2.R1 and later 2. The computer that will run Host Data Replicator must run one of the following versions of Windows NT Server software: Windows NT Server version 4.0 with service pack 3 Windows NT Server version 3.51 with service pack 5 3. The computer that will run Host Data Replicator must also run one of the following versions of Microsoft SNA Client or Server: Microsoft SNA Server version 3.0, service pack 2 or later Microsoft SNA Server version 2.11, service pack 2 or later Be sure that you include the ODBC/DRDA driver (also known as StarSQL) in your SNA Server installation, unless you already have a later version of StarSQL installed. When the ODBC driver is properly included in the initial SNA Server installation, applying SNA Server 3.0 service pack 2 will install StarSQL 2.4.0, and applying SNA Server 2.11 service pack 2 will install StarSQL 2.2.5. These are the minimum required versions for correct communication between Host Data Replicator and DB2 systems. 4. The computer that will run Host Data Replicator must run Microsoft SQL Server version 6.5, with service pack 3 or later (version 6.50.258 or later), along with ODBC version 2.5 or later. Either install SQL Server to run as a Windows NT service under a user account or create a Windows NT user account and assign it to SQL Server, as described in the SQL Server Administrator’s Companion. Be sure you include support for Named Pipes in your installation, as it is required for proper connectivity to Host Data Replicator. If you choose a non-standard value for the Named Pipes network support setting, make a note of the value for use in a future step. You may also want to increase the size of the SQL Server msdb database, as Host Data Replicator will use it for task scheduling and history information. For additional setup information, see the SQL Server Setup manual. Upgrading from Previous Product Versions --------------------------------------------------------- If your Windows NT Server system contains a beta or release candidate version of Host Data Replicator, you must remove the previous version of the product before installing the current version. To remove the previous version from your system, use the instructions below. For information about using the SQL Server bulk copy feature to dump and reload control database information, see the "Transferring Control Database Information to Text Files" section of this readme file. 1. Remove all old Host Data Replicator subscriptions from the SQL Server Scheduled Tasks list. You can use either of the following methods to remove the tasks: - Run Replicator Manager, connect to the Replicator Service, and delete all subscriptions, or - Run Enterprise Manager, highlight the SQL Server for Host Data Replicator, and select Scheduled Tasks from the Server menu. When the Manage Scheduled Tasks dialog box appears, delete all HDR tasks. 2. Run your old version of the Host Data Replicator SETUP.EXE program, which is normally located in the C:\MSHDR\Setup directory. Select the "Remove All" option to remove the obsolete Host Data Replicator Software. 3. Use Enterprise Manager to drop any previous versions of the Host Data Replicator control database. NOTE THAT DROPPING THE CONTROL DATABASE WILL REMOVE ANY EXISTING INFORMATION ABOUT HDR SOURCES, DESTINATIONS, AND SUBSCRIPTIONS. Addition to Installation and Configuration Instructions ------------------------------------------------------------------------- Use the following procedure to complete the process of configuring Host Data Replicator, before you first run Host Data Replicator Manager: 1. Open the ODBC Administrator from the Windows NT Control Panel. 2. In the Data Sources dialog box, click the System DSN button. 3. In the System Data Sources dialog box, select LocalServer (SQL Server) and click the Setup button. 4. In the ODBC SQL Server Setup dialog box, click the Options button. 5. If the Login frame in the expanded dialog box contains a "Use ANSI Quoted Identifiers" check box, make sure that the check box is selected. 6. Click the OK button to return to the System Data Sources dialog box, click Close to return to the Data Sources dialog box, and click Close to exit from the ODBC Administrator. Then close the Windows NT Control Panel. Configuring the Replicator Service to Log On As a User Account -------------------------------------------------------------- The Host Data Replicator Configuration utility (HDRCONF.EXE) ordinarily lets you specify whether the Replicator Service will log on to Windows NT as the System Account or a User Account. By default, User Account names refer to domain accounts. You can enter other accounts by using the form DOMAIN\ACCOUNT for the selected user account. However, under certain security configurations, HDRCONF may report an error if you enter an account name in this form. For example, if you are running HDRCONF on a computer MEMSVR that is a Windows NT Member Server in Domain TESTDOMAIN, and if you attempt to enter the local user account MEMSVR\TESTUSER, HDRCONF displays an error message such as "The domain controller for this domain could not be found." If you cannot successfully enter the user account of your choice in HDRCONF, select System Account and complete the process of running HDRCONF. When HDRCONF has run successfully, use the Windows NT Control Panel for Services to modify the Log On As setting for the Host Data Replicator Service. Then restart the service. Note that if you configure the Host Data Replicator Service to log on as a user account, the user account you specify must have access to your SNA Server, or you will not be able to establish necessary replication connections with DB2 sources or destinations. Using HDR with Extended Characters -------------------------------------------------- Extended characters are letters, numbers, or symbols that are listed among the last 128 characters of a character set, including characters with diacritical marks. Microsoft recommends that you avoid using extended characters in Host Data Replicator subscription names. However, if you choose to use extended characters in subscription names, you must carry out the following procedure before you create the first such subscription. 1. On the computer that runs the Host Data Replicator Service, start the SQL Client Configuration Utility. 2. On the DBLibrary property sheet, deselect (clear) the Automatic ANSI to OEM check box, then click Done. 3. Use the Windows NT Control Panel for Services or SQL Service Manager to stop and restart SQL Executive. Limiting the Number of Database Connections Used by HDR ------------------------------------------------------------- By default, HDR allows 100 simultaneous sessions per Replicator Service, regardless of the number of subscriptions you configure. To change the number of simultaneous connections allowed, run Host Data Replicator Manager and change the Maximum Number of Connections setting in the Service Properties dialog box. Note that if this setting has a value below the number of simultanteous connections needed, some subscription runs may fail with error messages such as "Could not add connection to list." If a subscription fails in this manner, Host Data Replicator attempts to re-run the subscription at its next scheduled replication time. To prevent replication failures of this type, either increase the Maximum Number of Connections to a higher value, or change the replication schedule to reduce the number of simultaneously active subscriptions. Managing the Size of the History Log ---------------------------------------------- HDR maintains history information for past replication events. The amount of information saved for each Replicator Service depends on the value of the Replication History Log Limit setting in the Service Options dialog box. The default value is 500, allowing information to be saved for the most recent 500 replication events. If you configure more than 500 subscriptions, or have another need to view history for more than 500 replication events, Microsoft recommends that you keep the value of the Replication History Log Limit setting as low as your needs allow. If the number of history log entries per subscription approaches hundreds or thousands, you may experience slow response from Host Data Replicator Manager as it attempts to display the subscription status. Changes to Replicator Manager ------------------------------------------ The following changes were made to the Replicator Manager application after the online Help was complete: - When you define a new Host Data Replicator source in the Source Properties dialog box, the "Select the Source DSN" list displays only data sources that use SQL Server or StarSQL 32 ODBC drivers. When you view properties for an existing source, the list shows only data sources that use the same type of ODBC driver as the currently selected DSN. - When you define a new Host Data Replicator destination in the Destination Properties dialog box, the "Select the Destination DSN" list displays only data sources that use SQL Server or StarSQL 32 ODBC drivers. When you view properties for an existing destination, the list shows only data sources that use the same type of ODBC driver as the currently selected DSN. Data Truncation Warning ---------------------------------- The following destination column types truncate replicated data if the source data is too large to fit in the destination column: - char - binary - varchar - varbinary - longvarchar - longvarbinary SQL Server Devices, Databases, and HDR Configuration ------------------------------------------------------- The Host Data Replicator Configuration Utility performs many actions during the process of setting up your Host Data Replicator control database and Host Data Replicator Service. Some of these actions may complete successfully, even if you encounter a configuration failure at a later stage, and this fact may complicate subsequent configuration attempts. Depending on when such a failure occurs, you may need to adjust your configuration choices. For example, if you use the Host Data Replicator Configuration Utility to create a new SQL Server database device, the device may be created even if the configuration fails at a later stage. If this occurs, do not attempt to re-create the device on the next configuration attempt. Instead, choose a configuration option that uses an existing device, and specify the previously created device when you are prompted for a device name. Similarly, if you use the Host Data Replicator Configuration Utility to create a new SQL Server database, either on a new device or on an existing device, the database may be created even if the configuration fails at a later stage. If this occurs, do not attempt to re-create the database on the next configuration attempt. Instead, choose a configuration option that uses an existing database, and specify the previously created database when you are prompted for a database name. Transferring Control Database Information to Text Files -------------------------------------------------------------------------- This version of Host Data Replicator includes the WRITEHDR.CMD utility, which uses the SQL Server bulk copy (bcp) feature to copy the contents of Host Data Replicator control database tables to text files. If you encounter problems when using Host Data Replicator, Microsoft Technical Support may ask you to run WRITEHDR as part of troubleshooting efforts. The output files created by WRITEHDR can also be useful if you need to create a replacement or duplicate of your control database. For information about using bcp to load information from text files into database tables, see the Administrator's Companion manual in your SQL Server documentation set. Note that WRITEHDR uses character format when creating output files. CAUTION: Files created by WRITEHDR contain SQL Server and host passwords in clear text. If the security of these passwords is a concern, be sure that you take appropriate measures to restrict access to any WRITEHDR output files. All output files are created in a directory you specify, as described in the following procedure. To Place Control Table Data in Text Files Using WRITEHDR: 1. Make sure your MSSQLServer service is running. 2. Use SQL Enterprise Manager as needed to gather the following information, which you will need for the next step: - Name of your Host Data Replicator control database (such as ControlDB) - Owner of your Host Data Replicator control database tables (such as hdruser) - A target directory of your choice for WRITEHDR output files (such as \temp). Use an existing directory and standard pathname syntax. - A SQL Server login ID that has access to the Host Data Replicator control database (such as hdruser) - The password for the above SQL Server login ID. 3. Open a Command Prompt window. Change to the directory where you installed Host Data Replicator, using a command such as "CD \MSHDR" (omit the quotes). Then type the following command, substituting the information you gathered in the previous step of this procedure: WRITEHDR controlDB_name controlTable_owner target_directory login_ID password For example, the command might read: WRITEHDR ControlDB hdruser C:\temp hdruser hdru_pwd On a successful run, the WRITEHDR utility creates the following files in the target directory: - writehdr.log Records progress of the most recent WRITEHDR run attempt - COLUMNS.HDR Information from the HDR columns table - SUBSCRIPTION.HDR Information from the HDR subscription table - STATS.HDR Information from the HDR stats (statistics) table - SRCDEST.HDR Information from the HDR srcdest (sources and destinations) table Be sure to examine the log file to confirm that the operation was successful for all four control tables. If the operation does not complete successfully, some of the files listed above may not be created. If two runs use the same target directory, the second run will overwrite some or all of the files from the first run. Frequently Asked Questions --------------------------------------- Q: How can I fix a subscription that fails and displays the following message when I run SQL Enterprise Manager, select Scheduled Tasks from the Server menu, and click the Task History button? "[Microsoft][ODBC SQL Server Driver][SQL Server]Can't allocate space for object 'Syslogs' in database 'alldata' because the 'logsegment' segment is full. If you ran out of space in Syslogs, dump the transaction log." A: You can use either of the following methods to address this problem : - Increase the Transaction Log Size for the destination database. To do this, run SQL Enterprise Manager, place the cursor over the destination database listing, click the right mouse button, and choose Edit. Then click the Expand button and increase the space allocated for the Transaction Log. - Set the Database Option to delete the transaction log on checkpoint. To do this, run SQL Server Enterprise Manager, place the cursor over the destination database listing, click the right mouse button, and choose Edit. Then click the Options tab. Select the "Truncate Log on Checkpoint" check box. Then click the Database tab. Click the Truncate button in the Transaction Log frame. Q: How can I fix a subscription that includes a DATETIME column and fails with the following message: "[SQL Server]The conversion of char to datetime resulted in a value out of range." A: DB2 and SQL Server have different ranges for their respective TIMESTAMP and DATETIME fields. You cannot replicate a DB2 TIMESTAMP column to a SQL Server DATETIME column if the source column contains year values earlier than 1753, or if it contains time values of 24:00:00.000. This time is equivalent to 00:00:00.000 but the allowable time range on SQL Server is 00:00:00.000 to 23:59:59.999. If your DB2 source table contains values that SQL Server does not accept in a DATETIME column, you may want to consider using a SQL Server column type of CHAR instead of DATETIME. Q: How can I establish a connection between Replicator Manager and the Replicator Service? I currently receive the following error message when I try to connect: "[Microsoft][ODBC ODS Gateway Driver]SQ_SRV_CONVERT_FAILURE: ::srv_convert() returned FAIL" A: Upgrade your SQL Server to version 6.50.258 (6.5 SP3). Q: Can I change the SQL Server password that Host Data Replicator uses to access its control database? A: Yes, but you must re-run the Host Data Replicator Configuration utility to update the password in the Windows NT registry. You can run the configuration utility from the Host Data Replicator program group or from your Host Data Replicator directory, where it appears as HDRCONF.EXE. The default directory for Host Data Replicator is C:\MSHDR.