Client/Server Kiosk Manual


Overview

The Client/Server Kiosk system (henceforth called Kiosk) is a set of programs and protocols that work together to provide a real-time display of ADP systems status and online information.  The client is an Intel-based PC running Microsoft Windows and the server is a DEC Alpha 2100 server running VMS.  The client software was developed using Borland's Delphi Rapid Access Development tool.  The server software is written in FORTRAN and C.  Communications are provided by Multinet (on the server side) and Pathworks (on the client side).  The interface to the Pathworks Winsock was written and released to the public domain by Gary T. Desrosiers.  Although not tested with other Winsocks or VMS TCP/IP servers, there are no know dependencies.


Client Description

The client code is a Microsoft Windows program that runs continually.  Most of the information that is displayed is kept on the local machine to minimize network traffic.  Once every three minutes (by default), a network request is made to the server to get any updates to the system status.

The display consists of three areas.  The ADP system status at the top of the screen displays the status of major systems (whether they are up, down, coming up, etc.).  The lower, right portion of the screen displays a repeating set of text/ graphic images giving information about upcoming events.  The lower, left portion of the screen contains three buttons that are used to get additional information on staff and on the Kiosk itself.  These include, information about the ADP support staff, phone directories of the entire staff, and a description of how to use the Kiosk.  A fourth button updates the display immediately instead of waiting for the remainder of the 3 minutes.

During normal operations, the Kiosk updates its status display every 3 minutes by connecting to the server and requesting an update.  If no connection can be made, the network status display will show down and all others will show unknown.  If an error occurs during transmission, one or more of the displays may show the bad data icon.  This should be rare.  

The "Happening Events" portion of the screen consists of a text area and two bitmap areas.  When the Kiosk starts up it counts the number of text files in the data directory.  It then displays these files one at a time, updating the display every 30 seconds until the last file has been shown -- then the pointer goes back to the first file.  The files are standard text files.  They are recognized by name alone... being called HAP1.TXT, HAP2.TXT, etc.  Graphic images associated with the text files (if any) are called N.bmp and Na.bmp, where N is the number of the text file.  For example, if files 3.bmp and 3a.bmp exist, they will be displayed below HAP3.TXT.  If there is no 3a.bmp, then only 3.bmp will be displayed.

Starting at 5:00 PM, the kiosk goes into screen saver mode.  Unless the mouse is clicked, the screen remains blank until 7:00 AM, except on Saturday and Sunday when it remains blank all day.

To keep mischievous users from stopping the kiosk, none of the windows can be sized or moved and the main window can only be closed by entering the magic incantation.  As shipped, this is "STOPIT".


Site-specific Client Modifications

Because of the nature of the client code, it is necessary to update the code at each site.  This is best accomplished within Delphi.  The areas that are site-specific are: the number and names of the systems being monitored and information about the ADP support staff.  Additionally, each client must be given a unique name to allow the server monitoring to work.


Installing the Client

Your client PC must have MS Windows 3.1 and Pathworks 5.0 (it is possible that it will work with earlier versions of the IP Pathworks, but it has not been tested).

Create a directory for the program and a subdirectory for the data files.  The data files can not be stored in the same directory as the code, since an update command causes the data directory to be wiped.  As shipped, the directory for the program is C:\APPS\KIOSK and the data directory is C:\APPS\KIOSK\DATA.  The distribution contains all of the source files (which can be placed in the program directory).  Sample happening files and BMPs are included, these should be replaced.

If the PC is to be used solely for the Kiosk function, add the command WIN to the last line of the AUTOEXEC.BAT and create an icon in the STARTUP program group to automatically start KIOSK when the system is booted.  To create a startup icon, open the startup group and from the file menu, select NEW.  This will bring up a requester where you enter the command line for the program (i.e., C:\APPS\KIOSK\KIOSK).  The requester will show the default icon for the kiosk program.


Server Description

The kernel portion of the server software is written in C to make programming and interfacing with the MULTINET_SERVER process easier.  Because the author is not an expert C programmer, the bulk of the code is written in FORTRAN.  The code is then integrated into the MULTINET_SERVER process using the MULTINET CONFIGURE /SERVER command -- described below.  The server program is called GPSERVER (General-purpose Server) as it is used for several functions at the authors site (the code for which is not included in this package).

The server code is executed as a detached process when a connection is made to the port assigned to GPSERVER.  Because the function of the Kiosk doesn't provide any sensitive information, no security features have been implemented.  It would be easy, however, to use Multinet's accept/reject capability to limit access to authorized clients.  See chapter 3 of the Multinet Administrator's Guide for information.  When executed, GPSERVER looks at the first character of the inbound packet to determine what function to perform.  Most typically, this will be an 'S', which is a request for a status update.  GPSERVER responds by translating the system logical name KIOSK_STATUS and returning the string to the client.  The value of KIOSK_STATUS is maintained by the KSTATUS program on the server.  KIOSK_STATUS can also be modified by an automated tool that watches the network for events and system outages.  

An additional function provided by the server is the directory lookup.  When the server receives a packet beginning in 'D', it uses the remainder of the packet as a search string for a simple text file containing directory information.  This information is returned to the client for display.

The "Happening Events" display on the client is provided on the client for efficiency, but is maintained on the server.  When files are added or deleted from the directory, GPSERVER appends a 'U' to the end of the next status response to each client, the client clears its directory and copies the new files using a standard Pathworks access.  

Finally, the server watches for each known client and reports to the ADP staff if a client fails to respond for a period of time.


Site-specific Server Modifications

In order to use Kiosk at your site, you may need to change some code.  Embedded in the code are some debugging features that send messages to the administrator.  The appropriate USERID can be inserted here, if this feature appears useful.  A makefile is included to rebuild the server code.  If MAKE is not available, the functioning of the makefile is fairly obvious.  Because it is executed frequently, the code should be built with the maximum efficiency possible; e.g., without traceback and with maximum optimization.

The source code contains an embedded list of client codes that represent each of the served clients.  This list must be modified on the server and the chosen code (node name) added to each client's code.  GPSERVER will notify the ADP staff if an unknown client access the GPSERVER port or if a known client isn't heard from for a while.

One of the functions provided by Kiosk is a directory lookup for the staff.  This is accomplished by searching the file STAFF.DAT.  This file has to be created for the local site; the file provided in this package is a sample only.  The format of this file isn't critical as it is simply searched line-by-line.


Installing the GPSERVER Program

This section is written to explain the installation of the GPSERVER program under Multinet.  You will have to adapt it if you are using a different TCP/IP server.  

The GPSERVER.EXE file should be copied to an appropriate directory which is protected from write access.  The executable should then be installed, for maximum efficiency; i.e.:

	INSTALL>  ADD SERV_DIR:GPSERVER/HEAD/OPEN

Finally, the MULTINET CONFIGURE command should be used to integrate the program to the MULTINET_SERVER process.

 	$ MULTINET CONFIGURE/SERVER
	SERVER-CONFIG> ADD GPSERVER
	Protocol: [TCP]  TCP
 	TCP Port Number:  2020
	Program to run:  SERV_DIR:GPSERVER.EXE
	SERVER-CONFIG>  

Note that the TCP Port Number isn't magic.  It must match the port number in the client code and can't duplicate a port that is already in use.  Additionally, port numbers below 1024 may have standardized definitions.


The SERVER Management Program (KSTATUS)

The KSTATUS program is used to maintain the logical name (KIOSK_STATUS) used to quickly update the status of the monitored resources without doing file I/O.  Additionally, it alerts GPSERVER when it is necessary to send the update command to the clients by setting the KIOSK_UPDATE logical to TRUE.  GPSERVER then sets that flag to FALSE and proceeds to notify all of the known clients to copy the new files which you have undoubtedly placed in the GPSERVER directory.  The KSTATUS program is very simple and self-explanatory.  It uses a menu system to change the status flags for each monitored system.  Only the status flags that are explicitly changed are affected; the remaining flags will hold their old values.  All flags are initialized to UP when the system first starts.

Happening files are maintained using a normal text editor.  Each file should be no more than 60 characters wide and 9 line long.  The names of the files must be HAP1.TXT, HAP2.TXT, etc.  The number must be continuous and can be more than one digit (i.e., more than 9 files can be used).  Graphic files, if any, are standard MS Windows BMP files.  They are associated with the relevant HAPn.TXT file by the number.  For example, the file 5.BMP will be displayed with HAP5.TXT.  A second file could be displayed at the same time as 5A.BMP.  BMP file should be no more than 200 pixels wide and 180 pixels high.


Communications Details

The client can make one of two requests to the server.  The first is to send update information and the second is to send staff directory information.

The update request is made by sending a packet consisting of the letter 'u' followed by the name of the client making the request.  The name is tracked by the server to notify the ADP staff if one of the servers goes off-line.  The server responds with a single packet which is either 8 or 9 bytes long.  The first 8 bytes of the packet are the status bytes for each of the systems being monitored in the order specified in the client and server code.  The 9th byte, if present, is a 'u' -- telling the client that the information files have been updated and need to be downloaded.

The directory request is made by sending a packet consisting of the letter 'd' followed by a text string containing the name or portion of name for the staff member of interest.  The response is a single packet containing up to 255 bytes of information to be displayed.  Formatting is provided by the server; i.e., carriage return/line feed pairs will be embedded in the packet.  If the search results in more than 255 bytes, the user probably put in a "too vague" request.

The final server/client communication is the downloading of the info files for display in the "Happening" area.  The downloading is done with a generic Pathworks copy command from drive letter "K".  The GPSERVER has nothing to do with this beyond the notification to the client that there are new files there.


Unfinished Business

- The communications code needs to be changed to leave the connection open (for performance reasons).  Currently, the connection is created for each update and then closed.

- Both the client and the server need to have better handling of the condition when the other goes away for some reason.  It is intended that the client should display the network as down and the remaining systems status as unknown, when this occurs.  It is intended for the server to watch for the client and, if it is not seen for some time, inform the systems staff via EMail.

- It is intended that the happening files, bitmaps, and explanation files reside on the server and be downloaded to the client only when they are updated.

- There will be an automated program on the server that checks for the status of each system (as best it can) and sets the status.  

- The system dependencies need to be placed into a single file that can be read at run-time so that the code can be distributed to sites without Delphi.
