Last modified: 10/05/07 Citrix/Terminal Services Support in IWPM Introduction ************ The 20041101 build of IWPM adds a new feature to ImagePlus Workstation Program V2.3 (IWPM with IP/390 host) that adds support for IWPM in a Citrix / Terminal Services environment. Windows Terminal Services runs on Windows servers, enabling a single copy of an application to be shared by multiple users. Citrix is a vendor who provides “thin client” products that run on top of Windows 2000 Terminal Servers. IWPM is the workstation application for two different products in the IBM Content Manager portfolio: ImagePlus/390 and Content Manager for iSeries with WAF support. IWPM communicates with IP/390 using TCP/IP and SNA (APPC) protocols, and runs on Microsoft Windows NT, 2000, and XP. However, IWPM was originally not designed to work under a Windows Terminal Services and Citrix environment. This enhancement will enable IWPM (with IP/390 and TCP/IP) to work under Citrix / Windows Terminal Services. Note that Windows Terminal Services support will not be offered for IWPM with WAF, or IP/390 with SNA/APPC as the host options. Windows Terminal Services Overview ********************************** Windows Terminal Services runs on Windows servers and allows a single copy of an application to be shared by multiple users. In a Windows Terminal Services environment, users run applications on the server through a Terminal Services Client that is installed on their workstation. This workstation can be any Windows PC, or even a dumb terminal. The workstation has no control over the tasks that are performed on the server, except for the execution of the Terminal Services Client. Each registered user on the Terminal Server is allocated an independent memory user area when they log on using the Terminal Services Client. Essentially, multiple users can run the same application within their user area. A product that is defined to work under Citrix / Terminal Services should adhere to policies that maintain workstation configuration information under a user-specific directory, rather than a central location. IWPM V2.3 Design Goals with Citrix ********************************** • Functions work under Windows Terminal Services. “Working” implies users should be able to perform operations, such as Display, Print, Working Set Operations, Store, and Annotate. • Documents can be imported and modified from the local machine. Storing markups will also be supported. Scanning (both batch scan and temp id scan) will NOT be supported and will be disabled under Windows Terminal Services. • Communication works with IP/390 through TCP/IP with no additional configuration information for Terminal Services support (standard IP/390 Configuration informa- tion is still required). • Users will be able to configure IWPM with information, like “User Specific Work Directory” location • Logging and printing operate normally, except that the log files and the printer profiles will be created in the user-specific location. • Currently, IWPM requires certain options to be configured: e.g., host informa- tion, printer profiles, menu options, and store options. Adding Windows Terminal Services support may require additional options to be configured, but the goal was to keep additional configuration settings minimal. Installation of this fixpack on a Windows 2000 Server ***************************************************** Installing IWPM on a Windows 2000 Server with Terminal Services installed is very similar to installing on a regular Windows workstation. Here are the instructions for the installation. 1. Installation should be performed by a Windows Administrator only. 2. Extract the IWP2KENU.ZIP installation zip file into a temporary directory. 3. Run Setup.exe and follow the instructions on the screen. IWPM with Citrix Installation and Configuration *********************************************** 1. Copy the EVN2CFG.DAT into the C:\EVN\BIN directory. 2. Run IWPM Configuration program through the Terminal Services Client. This will automatically copy EVN2CFG.DAT into the following directory: C:\Documents and Settings\\Application Data\IBM\EVN 3. The IWPM Configuration program will also create the IWPM_TS.INI file with the following values: [Settings] UserLocation=C:\Documents and Settings\Administrator\Application Data\IBM\EVN The UserLocation is where IWPM and IWPM Configuration Program create the files given below. Note that by default, IWPM creates the following files in the same directory where the IWPM_TS.INI file is present. Any user can change the location of these files, but not the location of IWPM_TS.INI. • IWPM configuration file • Printer Profiles • Trace and Error log files • IWPINIT files (contents of the INITC command) • EVN2.INI file Note that the "UserName" entry is not present here because the configuration program does not use a user name to perform any communications with the host. Mainframe Configuration *********************** Order and apply PTF UQ94247 for IP/390 (5655-A26). This fix should be installed on the MVS system in order to utilize the following new features in IWPM: a. IWPM with Terminal Services support b. IWPM on regular workstations with support for "dynamic workstation listener port" Make sure that the protocol field in the IDWKCFTB table is 1 (=IP-address) and not 3 (=DNS Name) for the Citrix client workstation rows. IWPM Startup ************ The ideal situation to run IWPM through Terminal Services client will be to use a "User ID" that matches the "Workstation Id" defined in the Workstation Configuration table in IODM. If these two user id's do not match, then edit the IWPM_TS.INI file manually using "Notepad" and the following entry under the [Settings] section: [Settings] UserName=WorkstationId Editing IWPM_TS.INI file is not required if the Windows user id matches the IODM WorkstationId. IWPM will automatically create this entry with the Windows user id, when launched through the Terminal Services client. When IWPM is started, it will perform the following: 1. Obtain the WorkstationId from the IWPM_TS.INI file. 2. Read the contents of the IWPM Configuration file (EVN2CFG.DAT) from the user location. If the file does not exist in that location, IWPM will automatically copy the file from IWPM Installation directory to the user location. This “automatic copying” process facilitates the replication of EVN2CFG.DAT file to all users in the Terminal Services environment. 3. Obtain the first available “Port” (between 1024 and 5000) on the machine and start listening on the port for requests from the host (in the Host Communications Thread). This port is where IWPM listens for incoming requests from the host. This port number is then logged in an INI file, called “IWPM_PORT.INI” under the “%APPDATA%\IBM\EVN” directory. The contents of this INI file look like this: [Communications] ListenerPort = port number The port number is logged as an “integer” entry. 4. For every TCP/IP host defined in the IWPM configuration file (EVN2CFG.DAT), execute the STAT command to the host, with the user ID (read from the IWPM_TS.INI file) and the Workstation listener port number as parameters. 5. When IWPM receives an INITC command, create the IWPINIT file corresponding to the host inside the user specific location. Notes: • A modification to ODM has been made in APAR PK51288 such that the altsendf flag is reset if the port number of the IWPM workstation changes mid-day. Changing the port number in IWPM causes an update to IODM's vector table by the STAT command but the altsendf flag had previously not been reset and this would cause IODM not to re-OINT the workstation unless the IP address also changed. If PTF UK29781 has not been applied to 5655A2601, you'll need to make sure to perform an OINT prior to doing DISPLAY's and STORE's. • Because IWPM uses a user-specific directory to store configuration files, and a unique workstation id to communicate with IODM, there can only be one instance of a "user id" logged on to the Windows server through the Terminal Services client. The process of allowing IWPM to decide on the workstation listener port and notifying the hosts about the same, as described in steps 3 and 4 above, are executed on regular Windows workstations if the following environment variable is defined, and is set to a value of “TRUE”. Set EVN_DYNAMIC_PORT = TRUE If the above environment variable is set to “TRUE” on regular Windows workstations, then “IWPM_PORT.INI” file is created in the IWPM Installation directory (e.g., C:\EVN\BIN). This environment variable indicates whether to use a fixed port number or to use a dynamically generated one on REGULAR workstations; it does not apply to Citrix or Terminal Services Clients. Running IWPM under regular Workstations but using the "dynamic workstation listener *********************************************************************************** port feature" ************* To enable IWPM running on standard workstations to use a dynamic workstation port, the following environment variables need to be defined: SET EVN_DYNAMIC_PORT=true SET EVN_WORKSTATION_ID=WorkstationId Additional Notes **************** The IWPM Configuration Program is used to configure the following: • Host-specific information • User-exits • Display menu options • Other preferences This program has been modified so that the configuration file is created in the user-specific location. The IWPM Configuration Program (EVNCONF.EXE), like IWPM, reads the user-specific location from the IWPM_TS.INI file, and if this file is not found, it will then create the same file with the default values. The IWPM main module (EVN.EXE), and Image Services Logger modules have been modified to create trace and error log files in a user-specific location, as specified in the IWPM_TS.INI file. The Image Services Printer module has been modified to read and create printer option profiles in a user- specific location, as specified in the IWPM_TS.INI file. Scanner support will not be supported, if IWPM is run under Citrix/Terminal Services. END