Readme File Last Updated: 05/01/2002 ========================================= Package: RPC Broker Current Version: 1.1 Original Release Date: October 1997 Dept. of Veterans Affairs VHA OI System Design & Development (SD&D) ========================================= This file contains any last minute changes, new instructions (not found in the documentation), and additional information to supplement the manuals. TABLE OF CONTENTS ================= * 05/01/02: BDK Supports Silent Login (Patch XWB*1.1*13), Delphi V. 6, & ESSO * 07/11/01: Removed all Delphi version conditions (Patch XWB*1.1*24) * 06/12/00: BDK No Longer Supports Delphi V. 2 and 3 * 05/25/00: Change "Required Package" for Packages Dependent on Broker * 05/25/00: Placement of XWB_Rxx.bpl File * 05/25/00: Resolution of dsgnintf Problem - Standard Edition Still Not Recommended * 12/09/99: Delphi V. 5 Standard Edition Not Recommended for BDK Development * 12/09/99: Recompile FMDC After Installing the New BDK * 12/09/99: RPC Broker DLL Not Updated * 08/23/99: Impact of Patch XWB*1.1*6 (Client Polling) on Developers * 08/23/99: New location on Inprise Web Site to Download Delphi V. 4 Help Updates * 08/23/99: Reduction of VMS Privileges on Broker Listener Process Advised * 06/01/99: Unpatched Broker Files Archived to Web Site * Original Readme: 1. Installation Notes A. Kernel Patch #59 (i.e., XU*8.0*59) B. Client Agent and Auto Startup C. MSM Must Disable Auto Signon D. Windows NT 3.51 & the Broker Client Agent 2. General Comments A. Response Time Monitor B. DHCPSERVER C. BrokerExample.EXE ------------------------------------------------------------------------------- 05/01/02: BDK Supports Silent Login (Patch XWB*1.1*13), Delphi V. 6, & ESSO ------------------------------------------------------------------------------- Updates: ------- Patch XWB*1.1*13 updated the Broker Development Kit (BDK). The BDK now includes the following functionality: * Silent Login Capability * Added a New Component, Classes, Types, and Properties Also, the BDK now supports Delphi V. 6 and is Enterprise Single Sign-On (ESSO) enabled. For a detailed list of updates available with Patch 13, please refer to the "What's New in the BDK" topic under the "Overview" topic in the BROKER.HLP file. Installation Notes: ------------------ Follow the installation steps as outlined in the Installation Guide (i.e., XWB1_1P13IG.DOC). The installation package integrates the BDK32 components (i.e., TRPCBroker and TXWBRichEdit) into Delphi V. 4.0, 5.0, and 6.0. The installation executable file for Patch 13 (i.e., XWB1_1P13PG.EXE) will automatically set up a directory structure similar to the following: VISTA | | BDK32 | | __________________________________|__________________________ | | | | | | | | | | | | | | D4 D5 D6 Help Samples Source D3 (if it existed before) | | _______________|_________________ | | | | | | BrokerEx SilentSignOn Vb5Egcho (NOTE: There is no option for installing a Delphi V. 3 of the Broker, however, any prior Delphi V. 3 installation is unaffected.) Context-sensitive Help: ---------------------- This installation also automatically installs the Broker components into Delphi and integrates the Broker's online help with Delphi's help. After dropping a component onto a form, give it focus, and press the F1 key to open the Broker's help file (i.e., BROKER.HLP). In the following $(DELPHI) is used to represent the base Delphi directory for a specified version (e.g., this might translate to C:\Program Files\Borland\Delphi4). For Delphi V. 4 -- The .bpl files are placed in the $(DELPHI)\Bin directory -- The .dcp files are placed in the $(DELPHI)\Lib directory -- Lines are added to the $(DELPHI)\Help\Delphi.cfg file, if they are not already present to add the Broker Help into Delphi Help. For Delphi V. 5 -- The .bpl files and .dcp files are placed in the $(DELPHI)\Projects\Bpl directory -- Lines are added to the $(DELPHI)\Help\Delphi.cnt file, if they are not already present to add the Broker Help into Delphi Help. For Delphi V. 6 -- The .bpl files and .dcp files are placed in the $(DELPHI)\Projects\Bpl directory -- Lines are added to the $(DELPHI)\Help\Delphi.cnt file, if they are not already present to add the Broker Help into Delphi Help. In the registry the following changes are made: HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help adds Broker.hlp and its directory path as the value adds Broker.cnt and its directory path as the value ------------------------------------------------------------------------------- 07/11/01: Removed all Delphi Version Conditions (Patch XWB*1.1*24) ------------------------------------------------------------------------------- Patch XWB*1.1*24 removes all Delphi version conditionals from the client code. For example, "$ifdef ver100". This caused a problem when recompiling under Delphi V. 5 -- user could not read/see the ServerList form the registry. ------------------------------------------------------------------------------- 06/12/00: BDK No Longer Supports Delphi V. 2 and 3 ------------------------------------------------------------------------------- As of 06/12/2000, the BDK is only supported in Delphi V 4 and 5. This statement defines the extent of support relative to use of Delphi. The Office of Information (OI) will support the Broker Development Kit (BDK) running in the currently offered version of Delphi and the immediately previous version of Delphi. This level of support became effective 06/12/2000. Sites may continue to use outdated versions of the RPC Broker Development Kit but do so with the understanding that support will not be available and that continued use of outdated versions will not afford features that may be essential to effective client/server operations in the VISTA environment. An archive of old (no longer supported) Broker Development Kits will be maintained at: http://vista.med.va.gov/broker/archives/index.html ------------------------------------------------------------------------------- 05/25/00: Change "Required Package" for Packages Dependent on Broker ------------------------------------------------------------------------------- Patch XWB*1.1*14 splits the Broker package into separate run- and design-time packages. If a package currently is defined with the VistaBroker.dpk as a Required package, you must delete that required package and add XWB_Dxx.dpk (where xx=30 for Delphi 3.0, =40 for Delphi 4.0, or =50 for Delphi 5.0) as a required package. ------------------------------------------------------------------------------- 05/25/00: Placement of XWB_Rxx.bpl File ------------------------------------------------------------------------------- The install of patch XWB*1.1*14 places the run-time bpl for the Broker package into the System32 directory. This is the proper location for the run-time bpl; so, if that file changes, the new version should be put into the System32 directory. ------------------------------------------------------------------------------- 05/25/00: Resolution of dsgnintf Problem - Standard Edition Still NOT Recommended ------------------------------------------------------------------------------- The Broker Component no longer has a dependency on the dsgnintf file. (This dependency is mentioned in a 12/09/99 entry in this Readme file.) So, you no longer need to have a copy of that file available in order to compile a Broker application. However, it is still recommended that you not use Delphi Standard edition with the Broker because you cannot properly install the help files with that edition. ------------------------------------------------------------------------------- 12/09/99: Delphi V. 5 Standard Edition NOT Recommended for BDK Development ------------------------------------------------------------------------------- Delphi V. 5 comes in three flavors: Standard, Professional and Enterprise. This version of the BDK requires the Professional or Enterprise Edition. Standard edition is targeted mainly at students,and as such leaves out many features. We do not recommend using the Standard edition of Delphi V. 5 for RPC Broker development at this time: 1. Delphi V. 5 Standard Edition does not ship with the OpenHelp help system, whose purpose is to allow easy integration of 3rd party component help with Delphi's own internal component help. 2. The RPC Broker component has a dependency on a VCL source code unit, 'dsgnintf.pas'. Delphi V. 5 Standard Edition does not ship the 'dsgnintf' file, in either .pas or .dcu form. VCL Source code units are available in Delphi 5 Professional and Enterprise Editions. When installing Delphi 5 Professional or Enterprise Edition, make sure you leave the VCL Source installation option selected. ------------------------------------------------------------------------------- 12/09/99: Recompile FMDC After Installing the New BDK ------------------------------------------------------------------------------- If you're using the FileMan Delphi Components (FMDC), please note that the FMDC source code includes references to RPC Broker Development Kit (BDK) code. When you install a new version of the BDK, you will need to recompile the FMDC. As of patch FMDC*1.0*1, source code for FMDC is provided, allowing you to recompile FMDC if necessary. For instructions on how to recompile FMDC, consult the new FMDC Installation Guide released with patch FMDC*1.0*2. ------------------------------------------------------------------------------- 12/09/99: RPC Broker DLL Not Updated ------------------------------------------------------------------------------- The original RPC Broker V. 1.1 BDK provided BDK functionality in the form of a dynamic link library (.DLL), as well as the more frequently used TRPCBroker Delphi Component. The DLL allows any development product that supports Windows DLLs to be used, rather than just Delphi. However, the DLL form of the BDK has not been updated since the original RPC Broker V. 1.1 release, and so does not contain new functionality added since that time, including client polling and multi-divisional support. A new version of the DLL may be provided in the future, but has not been at this time. ------------------------------------------------------------------------------- 08/23/99: Impact of Patch XWB*1.1*6 (Client Polling) on Developers ------------------------------------------------------------------------------- Broker patch XWB*1.1*6 initiates periodic 'polling' from the client application to the server. The polling requires no actions on the part of the developer and the developer cannot affect the polling. This polling is being done because the timeout on the server is being significantly shortened - from 10 hours to a site configurable time with a 3 minute default. Polling should keep this timeout from expiring if the client application is still running. However, mostly because of the possibility of significant network transmission delays, there may be situations where the server job times out and the client application is, in fact, still running. This is expected to be very rare. If it does happen, the next RPC from the client will cause a ConnectionLost error, raised by the Broker. This error gives the application the opportunity to take appropriate action -- which will usually be terminating the application. If the application is not ended, when the next RPC is sent, the user will be challenged to log back on (since no connection currently exists). This will often not be proper. In order to avoid this inappropriate situation, we suggest that all calls to the Broker from Delphi to execute an RPC (Call, lstCall, and strCall methods) be protected by a try ... except block with appropriate error handling code (e.g., Application.Terminate). There is nothing new in this recommendation: it is present in the help and tutorial files distributed with the Broker. The recommendation is being reiterated now because of the possibility that lost Broker connections will become slightly more frequent. ------------------------------------------------------------------------------- 08/23/99: New location on Inprise Web Site to Download Delphi V. 4 Help Updates ------------------------------------------------------------------------------- The Installation Guide suggests getting the DEL4HLP.ZIP file from Inprise's web site to fix the Delphi help that shipped with Delphi 4. The page location on the Inprise web site has changed, however: - The web page to go to download DEL4HLP.ZIP is: http://www.borland.com/techpubs/delphi/updated.html (DELPHI4.HLP link) - The direct ftp URL is: ftp://ftp.inprise.com/pub/delphi/techpubs/delphi4/del4hlp.zip ------------------------------------------------------------------------------- 08/23/99: Reduction of VMS Privileges on Broker Listener Process Advised ------------------------------------------------------------------------------- The Broker Listener process only needs TMPMBX and NETMBX OpenVMS privileges. The Broker Listener runs at the same priority as the user who started it. There have been a few reports of DSM sites crashing due to the Broker running at higher priority (7) than intended and the Broker listener having excessive privileges. We feel that this is ultimately an OpenVMS UCX problem, but following the guidelines in this section will prevent the problem from occurring. Please take particular notice of the privileges of the user who starts the Broker Listener. We do not recommend that the Broker listener be started with more than TMPMBX and NETMBX privileges. ------------------------------------------------------------------------------- 06/01/99: Unpatched Broker Files Archived to Web Site ------------------------------------------------------------------------------- Unpatched Broker distribution files have been archived from the National VISTA Support (NVS) anonymous directories to the RPC Broker home page, "archives" section. This means that the following two files are now available only from the RPC Broker home page, "archives" section: XWB1_1IG.PDF (original Installation Guide) XWB1_1PG.EXE (unpatched BDK, Delphi 2+3 support) The NVS anonymous directories will contain the most recent, patched distribution files. The archived files above are replaced (patch XWB*1.1*4) by: XWB1_1P4IG.PDF (new Installation Guide) XWB1_1P4PG.EXE (new patched BDK, Delphi 3+4 support) Note: RPC Broker support and maintenance for Delphi 2 has been discontinued, but you can still use the original unpatched BDK if you need to develop with Delphi 2. ------------------------------------------------------------------------------- Original V. 1.1 ReadMe: ------------------------------------------------------------------------------- ------------------------ 1. Installation Notes: ------------------------ During the installation, you must NOT be running the RPC Broker Client Agent or any application that uses the Broker. A. Patch #59 (i.e., XU*8.0*59) --------------------------- Install Patch #59, if you haven't already installed it, after you have installed the RPC Broker V. 1.1. The documentation on pages 6 and 34 of the Installation Guide did not make this clear. B. Client Agent and Auto Startup ----------------------------- During the installation process, you are given the option to "Always Start Client Agent?" when you start Windows. Answer Yes so the Broker Client Agent (i.e., CLAGENT.EXE) will automatically start up when Windows is started and so that single signon, if allowed, will be operational. However, if a particular workstation is not always connected to the network upon startup (e.g., a laptop), you may wish to prevent Client Agent from starting automatically by answering No to this prompt. You can always reset it to start automatically by re-installing the Broker client software and answering Yes to this prompt. Alternatively, you can manually start the Client Agent, double click on the Client Agent icon in the system tray, and check the "Start Client Agent with Windows" checkbox. C. MSM Must Disable Auto Signon ---------------------------- Single signon (a.k.a. Auto Signon) is not supported on MSM systems. --- All MSM sites must set the DEFAULT AUTO SIGN-ON field in the KERNEL SYSTEM PARAMETERS file (#8989.3) to Disabled. NOTE: For more information on single signon and setting the DEFAULT AUTO SIGN-ON field, please refer to the "Integrated Single Signon for Multiple User Sessions" topic in chapter 1 in the RPC Broker V. 1.1 Systems Manual. D. Windows NT 3.51 & the Broker Client Agent ----------------------------------------- If you are running Windows NT 3.51, in order to shut down the Client Agent, do the following: 1. If you answered Yes to automatically start the Client Agent when you did the installation, you must rerun the installation and answer No to this prompt and restart Windows. 2. If you answered No to automatically start the Client Agent when you did the installation, simply restart Windows. To date no additional changes have been made to the installation instructions. Thus, please follow the instructions in the Installation Guide when installing the RPC Broker. ------------------------ 2. General Comments: ------------------------ A. Response Time Monitor --------------------- **************************************************************** Please note the following: With the release of this version of the RPC Broker, Response Time Monitor (RTM) is turned on for the Broker only. The VISN CIO Council endorses monitoring the amount of resources consumed by client/server applications that use the Broker. The anticipated use of the RPC Broker for client/server applications is not expected to impact system performance. The data collected will be used to better gauge the performance of VISTA Broker-based client/server applications. If the Response Time Global is getting too large, IRM may purge this global using the Response Time Monitor utilities. In the future, once a baseline has been established, data collection will be turned off via a Broker patch. For more specific information on Response Time Monitoring and the Response Time Global, please refer to the Kernel Toolkit V. 7.3 User Manual. **************************************************************** B. DHCPSERVER ---------- When referring to the Broker Listener, the Broker V. 1.1 documentation refers to the BROKERSERVER. However, version 1.0 of the Broker made references to DHCPSERVER. You may want to create an ADDITIONAL entry for BROKERSERVER in your HOSTS file or DNS. However, DO NOT REMOVE the DHCPSERVER entry already present. The DHCPSERVER entry is still required for software that uses version 1.0 of the Broker. C. BrokerExample.EXE ----------------- Currently, the Broker demonstration program (i.e., BrokerExample.EXE, which is distributed in source code to be compiled by the end-users) can only be run by users with the XUPROGMODE security key. The option XWB Broker Example has no entry for the TYPE field in the OPTION file (i.e., entry should be Broker [client/server]). A user that does not have programmer access will get an error when trying to connect using the BrokerExample.EXE. This anomaly will be corrected in a future patch to allow all users, regardless if they have the programmer access, to successfully use this demonstration program.