Who Locked It Rev 2.4 Copyright 1994 by Threshold, Inc., Auburn, Alabama All rights reserved. Printed in the U.S.A. Threshold, Inc. 118 N. Ross Street Auburn, Alabama 36830 (334) 821-0075 voice (334) 821-0122 fax LIMITED WARRANTY Threshold warrants that (a) the software will perform substantially in accordance with the accompanying written materials for a period of ninety (90) days from the date of receipt; and (b) any hardware accompanying the software will be free from defects in materials and construction under normal use and service for a period of one (1) year from the date of receipt. Any implied warranties on the software and hardware are limited t o n i n e t y (90) days and one (1) year respectively. Some states/jurisdictions do not allow limitations on duration of an implied warranty, so the above limitation may not apply to you. Threshold's entire liability and your exclusive remedy shall be, at Threshold's option, either (a) return the license fee or (b) repair or replacement of the software or hardware that does not meet the above Limited Warranty and which is returned to the original vendor with a copy of the receipt. This Limited Warranty is void if failure of the software or hardware has resulted from accident, abuse, or misapplication. To the maximum extent permitted by applicable law, Threshold and its supplier disclaim all other warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with regard to this software, the accompanying written materials, and any accompanying hardware. This limited warranty gives you specific legal rights. You may have others which vary from state/jurisdiction to state/jurisdiction. To the maximum extent permitted by applicable law, in no event shall Threshold or its suppliers be liable for any damages whatsoever (including without limitation, damages for loss of business profits, business interruption, loss of business information, or any other pecuniary loss) arising out of the use of or inability to use this Threshold product, even if Threshold has been advised of the possibility of such damages. Because some states/jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages, the above may not apply to you. i U.S. Government Restricted Rights Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 or subparagraphs (c)(1) and (2) of the Commercial Computer Software - Restricted Rights at 48 CFR 52.227-19, as applicable. Manufacturer is Threshold, Inc. / 118 North Ross St. / Auburn, AL 36830. If you acquired this product in the United States, this agreement is governed by the laws of the State of Alabama. Notice These routines contain the valuable properties and trade secrets of Threshold, Inc. embodying substantial creative efforts and confidential information, ideas and expressions, no part of which may be reproduced or transmitted in any form or by any means except under the terms and conditions of the Threshold, Inc. Software License, or by written permission from Threshold, Inc. Copyright 1994, Threshold, Inc., Auburn, Alabama. All rights reserved. Who Locked It is a trademark of Threshold, Inc., Auburn, Alabama. ACUCOBOL, ACUCOBOL-85, and Vision are trademarks of Acucobol, Inc. Any other products mentioned are the trademarks of their respective companies. Document revision date: February 1995 ii Table of Contents TABLE OF CONTENTS I. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 A. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 B. Documentation Conventions . . . . . . . . . . . . . . . . . . . 2 II. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 A. Software Installation . . . . . . . . . . . . . . . . . . . . . 3 B. Threshold Utility Daemon (thud) . . . . . . . . . . . . . . . . 3 C. The COBOL Runtime . . . . . . . . . . . . . . . . . . . . . . . 4 III. Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 A. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 B. Notification Parameters . . . . . . . . . . . . . . . . . . . . 5 C. Persistence Parameters . . . . . . . . . . . . . . . . . . . . . 5 D. Assistance Parameters . . . . . . . . . . . . . . . . . . . . . 6 E. Insistence Parameters . . . . . . . . . . . . . . . . . . . . . 7 F. Other Parameters . . . . . . . . . . . . . . . . . . . . . . . . 8 IV. External Configuration . . . . . . . . . . . . . . . . . . . . . . 10 A. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 B. Using Environment Variables . . . . . . . . . . . . . . . . . 10 C. Using The Acucobol Configuration File . . . . . . . . . . . . 10 D. Using the thud Configuration File . . . . . . . . . . . . . . 11 V. Programmer's Interface . . . . . . . . . . . . . . . . . . . . . . 12 A. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 B. Setting Configuration Variables . . . . . . . . . . . . . . . 12 C. Retrieving Configuration Variable Values . . . . . . . . . . . 12 D. Accessing Who Locked It Information . . . . . . . . . . . . . 13 iii Who Locked It User's Manual APPENDICES APPENDIX A. Who Locked It Registration and thud Startup . . . . . . . A-1 APPENDIX B. Rebuilding the Runtime . . . . . . . . . . . . . . . . . . B-1 APPENDIX C. Pseudo Code Illustrations of WLI Logic . . . . . . . . . . C-1 APPENDIX D. National Language Support (NLS) . . . . . . . . . . . . . D-1 iv Introduction I. Introduction A. Overview Who Locked It (WLI) is an enhancement product for the Acucobol runtime which greatly improves your program's ability to handle locked records. Normally, when a program attempts to read a record which has been locked by another program, the runtime returns an error code. The program knows the record is locked but is limited in what it can do to resolve the situation. The program cannot tell the user anything about who has the record locked. Who Locked It solves this problem. Who Locked It operates in four modes: Notification, providing information about the holder of the locked record; Persistence, allowing the program to automatically retry the read; Assistance, providing an automatic attempt to free the locked record; and, Insistence, a method by which the program can force the record to become available. Notification There are two ways for a program to provide record locking information to the user. The program can call the WLI subroutine which will return the username, station id, and process id of the holder of the locked record. This information can then be formatted and displayed by the program. The runtime can also be configured to automatically display this information whenever a locked record is encountered. Persistence The persistence configuration option instructs the runtime to automatically retry the read. Options are provided to control how long the runtime will persist in its attempt to read the record, and how often during this period the runtime should attempt the read. If the record becomes available during the persistence period, the record is returned to the program just as if the first attempt to read the record had succeeded. If, on the other hand, the runtime is unable to read the record during this time, the record-locked file status code is returned to the program. In other words, the program works the same as it always did. Now, it just has a better chance of successfully reading the record. Assistance Optionally, the runtime can send a message to the holder of the locked record. Up to two such requests can be made. Meanwhile, the runtime continues to retry the read. The message sent to the other runtime pops up in a window on that user's screen. The user is, of course, free to ignore the message and continue to hold the lock. Insistence If insistence mode is turned on and all attempts to read the record fail, the other runtime will be terminated in order to gain access to the record. The termination is done in such a way as to allow the runtime to perform an 1 Who Locked It User's Manual orderly shutdown, closing any open files and returning the terminal to a normal state. Configuration The parameters which control the operation of Who Locked It can be tailored to your particular needs. B. Documentation Conventions This documentation will often need to identify the parties involved in a lock collision. The user who holds the lock will be referred to as the locker and the one who has attempted to access the locked resource will be referred to as the reader. Who Locked It will report information about attempts to open locked files and well as attempts to read locked records. To avoid the awkwardness of constantly referring to "file or record" and "open or read", this document will generally refer to attempts to "read" locked "records". Bear in mind that when this document uses the term "read" it includes attempts to open files. Likewise the term "record" will be used where the situation would also include a file. 2 Installation II. Installation A. Software Installation Who Locked It is distributed on several different types of media. The software should be loaded using the command printed on the release media label (usually tar), using the appropriate device specification for this media on your system. In some cases this label will refer you to other loading instructions. If you already have other Threshold utilities for Acucobol, load Who Locked It in the same directory. If this is your first Threshold product, create a new directory to contain Who Locked It. cd /usr [or other directory] mkdir thutil [or similar] cd thutil (command-from-release-media) Please save your release media for future reference. Your release media may also contain a copy of the Threshold Utility Daemon (thud). A number of products offered by Threshold and other vendors use thud so it may already be installed on your system. B. Threshold Utility Daemon (thud) The Threshold Utility Daemon (thud) must be running before you execute runtimes containing Who Locked It. In addition to providing certain services required for Who Locked It, thud also serves as the license control mechanism for this and other products. The thud registration file may limit your use of Who Locked it to a certain number of simultaneous users or provide for an expiration date beyond which Who Locked It will no longer function. Quick Start Tip: If you just loaded your copy of Who Locked It, you probably have a thud registration file containing temporary registration data. You may start thud as follows: (login as root) cd /usr/thutil [or directory containing thud and thud.ini] ./thud -s -n -f To determine whether or not thud is running and to verify that Who Locked It has been properly registered, please type following command: thud -p This command will display some general information about thud along with a list of currently registered products. If you do not see Who Locked It listed, you will need to update the thud configuration file. Please refer to the Who Locked It Registration section of this document for instructions (Appendix A). If you see the message: 3 Who Locked It User's Manual thud server not running you will need to start thud before proceeding. If you have not installed thud, please refer to the Who Locked It Registration section of this document for instructions (Appendix A). C. The COBOL Runtime Who Locked It works by adding certain routines to the COBOL runtime. This means that a runtime must be built containing these special routines. In some cases, your release media will include a pre-configured runtime with these routines already installed. If the directory where you installed WLI contains a file with the name wliruncbl, this is an Acucobol runtime with Who Locked It capabilities. If desired, you may rename this file or move it to a different directory on your system. If you do not find a pre- configured runtime or if you need to include other special routines, you will need to rebuild the runtime. Please refer to Appendix B, Rebuilding the Runtime. 4 Configuration III. Configuration A. Overview The operation of Who Locked It can be controlled in a variety of ways. T h i s chapter describes the individual parameters that affect WLI operations. After reading these descriptions, you may find it helpful to review Appendix C, D which further describes the logical relationship of these parameters. Chapter IV, External Configuration, describes various ways of setting these parameters without modifying your existing programs. Chapter V describes the programmer's interface which provides a means of controlling the operation of WLI from within a COBOL program. Appendix D, National Language Support (NLS), describes how NLS can be used when running Who Locked It in a non-English or multilingual environment. As you read the descriptions of the following parameters, keep in mind that there are usually two parties to a Who Locked It event - the locker and the reader. Some parameters are meaningful to the locker and other to the reader. The locker and the reader may have completely different setting these parameters. For example, the message that the reader sends to the locker to request the release of record or file locks is determined by the value of the reader's parameters (i.e. the value of WLI_REQUEST1_MESG). How long this message remains on the locker's screen is determined by the locker's setting of WLI_MESG_STAY. In this example, the setting of WLI_MESG_STAY by the reader will have no effect on how long the message stays on the locker's screen. B. Notification Parameters WLI_AUTO = n Controls whether or not the WLI window should pop-up automatically when a locked record is encountered. If this is not set, or if it is set to 0, the window does not appear. WLI_AUTO_STAY = n If WLI_AUTO is set, the controls how long the window will stay on the screen. If not set, or set to 0, the window will remain on the screen until the user hits a key. Even if set, the user can remove the window by pressing a key anytime during the pause. WLI_SHOWPID = n If set to anything other than 0, the pop-up window will include the pid of the record locker. C. Persistence Parameters WLI_PERSISTENCE = n Turns on the WLI persistent read routines. The value of this environment variable limits the total time WLI will retry the read before returning a record locked status. 5 Who Locked It User's Manual WLI_DELAY = n The value of this parameter determines how many seconds WLI will delay between read retries during the persistence period. The default for this parameter is five seconds. WLI_SILENT = n This parameter will cause WLI to 'silently' retry the read for the specified number of seconds before reporting the lock information to the reader. Use of this parameter can have the effect of hiding most lock collisions from the user since WLI only display a report of locks that are held for longer than this interval. WLI_SILENT_DELAY = n If the WLI_SILENT parameter has been set, WLI_SILENT_DELAY can be used to specify a delay between reads during the silent period. The default for this parameter is the 1 second. Assume that the following parameter settings are in effect at the time a lock is encountered: WLI_PERSISTENCE = 60 WLI_DELAY = 5 WLI_SILENT = 10 WLI_SILENT_DELAY = 1 Who Locked It will automatically retry the read for up to 60 seconds. For the first 10 seconds, WLI will pause 1 second between attempts and will not display any WLI notification. After 10 seconds, WLI will start pausing 5 seconds between each attempt and each time a lock is encountered, WLI will display the identity of the locker. D. Assistance Parameters WLI_REQUEST1 = n If a read persists for at least n seconds, WLI will send a message, defined by WLI_REQUEST1_MESG, to the holder of the lock requesting the release of the record. WLI_REQUEST2 = n If a read persists for at least n seconds, WLI will send a message, defined by WLI_REQUEST2_MESG, to the holder of the lock requesting the release of the record. If WLI_REQUEST2 is defined, it must be greater than WLI_REQUEST1, if it is defined. WLI_REQUEST1_MESG = "Message Text" or @filename The contents of this variable will be displayed on the screen of the holder of the locked record upon the expiration of WLI_REQUEST1. If the variable begins with a @ character, the message text will be read from the indicated filename. If WLI_REQUEST1 is defined and WLI_REQUEST1_MESG is not defined, the message text will be "Please release your locked record". A vertical bar character (|) imbedded in the message will cause a newline in the message when it is displayed. If the first character of Message Text is an equal sign (=) the 6 Configuration message displayed on the other user s screen will be whatever that user has defined as his WLI_REQUEST1_MESG. This can be used in conjunction with the NLS service described in Appendix D to configure Who Locked in a multilingual environment. WLI_REQUEST1_FILE_MESG = "Message Text" or @filename The contents of this variable will be displayed on the screen of the holder of the locked file upon the expiration of WLI_REQUEST1. If the variable begins with a @ character, the message text will be read from t h e i n d icated filename. If WLI_REQUEST1 is defined and WLI_REQUEST1_FILE_MESG is not defined, the message text will be "Please release your locked file". A vertical bar character (|) imbedded in the message will cause a newline in the message when it is displayed. If the first character of Message Text is a plus sign (+) the message displayed on the other user s screen will be whatever that user has defined as his WLI_REQUEST1_FILE_MESG. This can be used in conjunction with the NLS service described in Appendix D to configure Who Locked in a multilingual environment. WLI_REQUEST2_MESG = "Message Text" or @filename The contents of this variable will be displayed on the screen of the holder of the locked record upon the expiration of WLI_REQUEST2. If the variable begins with a @ character, the message text will be read from the indicated filename. If WLI_REQUEST2 is defined and WLI_REQUEST2_MESG is not defined, the message text will be "Please release your locked record or your session will be terminated". If the message text begins with an equal sign (=), the remote user s WLI_REQUEST2_MESG text is displayed. WLI_REQUEST2_FILE_MESG = "Message Text" or @filename The contents of this variable will be displayed on the screen of the holder of the locked file upon the expiration of WLI_REQUEST2. If the variable begins with a @ character, the message text will be read from the indicated filename. If WLI_REQUEST2 is defined and WLI_REQUEST2_FILE_MESG is not defined, the message text will be "Please release your locked file or your session will be terminated". If the message text begins with a plus sign (+), the remote user s WLI_REQUEST2_FILE_MESG text is displayed. E. Insistence Parameters WLI_KILL = n If the record is still locked after this many seconds, terminate the locker's runtime. This value must be greater than both WLI_REQUEST1 and WLI_REQUEST2. WLI_KILL_MESG = "Message text" or @filename The contents of this variable will be displayed on the screen of the holder of the locked record just prior to termination. If the variable begins with a @ character, the message text will be read from the indicated filename. If WLI_KILL_MESG is not defined, the message 7 Who Locked It User's Manual text will be "Your session was terminated to release a locked record". If the first character of Message Text is an equal sign (=) the message displayed on the other user s screen will be whatever that user has defined as his WLI_KILL_MESG. This can be used in conjunction with the NLS service described in Appendix D to configure Who Locked in a multilingual environment. WLI_KILL_FILE_MESG = "Message text" or @filename The contents of this variable will be displayed on the screen of the holder of the locked file just prior to termination. If the variable begins with a @ character, the message text will be read from the indicated filename. If WLI_KILL_FILE_MESG is not defined, the message text will be "Your session was terminated to release a locked file". If the first character of Message Text is a plus sign (+) the message displayed on the other user s screen will be whatever that user has defined as his WLI_KILL_FILE_MESG. This can be used in conjunction with the NLS service described in Appendix D to configure Who Locked in a multilingual environment. F. Other Parameters WLI_MESG_STAY = n This variable controls how long the an incoming message will stay on the recipient's screen before it is automatically removed. The recipient can remove the message at any time by pressing a key. Remember, this variable must be set in the recipient's environment. WLI_NOMESG = n If set to any value other than 0, this runtime will not display WLI messages sent by other runtimes. That is, when another runtime sends a message to request the release of a locked record or file, the message is simply discarded. WLI_NOKILL = n If set to any value other than 0, this runtime will not comply with a termination request sent by another WLI runtime. That is, if this runtime has WLI_NOKILL set and locks a record, other runtimes will not be able to use WLI to free that record by terminating this runtime. Setting both WLI_NOMESG and WLI_NOKILL makes a runtime immune from Who Locked It interference by other runtimes. WLI_REQUEST1_GRACE=n WLI_REQUEST2_GRACE=n If multiple users try to read the same locked record, each might send messages to the locker requesting that the record be released. If these grace period parameters are set, all messages of the same type will be ignored (not displayed) for the specified number of seconds after the display of the first request of that type. 8 Configuration WLI_LOGOFF_CALL = cobol_program_name When a WLI runtime receives a termination request, the named program will be called prior to terminating the runtime. WLI_ENABLE = n If set to 0, all WLI operation will be disabled. That is, the runtime will operate as a standard runtime would when it encounters a locked record. WLI_BOX_LABEL=label Sets the text displayed in the top border of the message box. The default is Who_Locked_It. 9 Who Locked It User's Manual IV. External Configuration A. Overview When a WLI runtime is first executed, it establishes starting values for all of the configuration parameters listed above. Initially, the parameters have default values as described in Chapter III. B. Using Environment Variables First the WLI initialization routine will look at the user's environment variables for WLI parameters. Settings in the environment will override the built-in defaults, the setting in the thud configuration file, and the setting in the Acucobol configuration file. This makes the environment a convenient place to put parameters that will differ from one user to another. The following unix commands demonstrate the use of environment variables to set WLI parameters. WLI_PERSISTENCE=120 export WLI_PERSISTENCE WLI_REQUEST1=45 export WLI_REQUEST1 WLI_REQUEST2=90 export WLI_REQUEST2 WLI_KILL=110 export WLI_KILL WLI_REQUEST1_MESG=@req1_mesg export WLI_REQUEST1_MESG WLI_REQUEST2_MESG="Unlock your records NOW!" export WLI_REQUEST2_MESG C. Using The Acucobol Configuration File If the parameter is not found in the user's environment, the initialization routine looks for WLI parameters in the user's Acucobol configuration file. This is the same file that contains your Acucobol configuration entries. The following is an example of what a portion of an Acucobol configuration file might look like: # This is a sample configuration file # You should edit it to match your needs (see the ACUCOBOL User's Guide). WLI_PERSISTENCE 120 WLI_REQUEST1 45 WLI_REQUEST2 90 WLI_KILL 110 WLI_REQUEST1_MESG @req1_mesg WLI_REQUEST2_MESG Unlock your records NOW! # Uncomment the following line if you want to print a form-feed each # time a print file is closed # PAGE-EJECT-ON-CLOSE 1 10 External Configuration D. Using the thud Configuration File Finally, if the parameter has not been set in the user's environment or in the Acucobol configuration file, the initialization routine will look in the thud configuration file for any Who Locked It parameter entries it may find there. You might think of the thud configuration file as a way of changing the default value for WLI parameters since each WLI runtime will read the same thud configuration file at startup. The following is an example of what the Who Locked It section of the thud configuration file (thud.ini) might look like: [Who_Locked_It] *usercount = 64 *revision = 2.0 WLI_PERSISTENCE = 120 WLI_DELAY = 10 WLI_REQUEST1_MESG = "**** PLEASE **** release your locked records" *validation = ZQS QWZ TCP DCO EFSX Be careful when modifying the thud configuration file. The thud configuration file contains much more than WLI parameters. This file also contains entries to control the registration of Who Locked It and, possibly, other products as well. In particular, you should not modify any line that begins with an asterisk (*). These lines can not be altered without a proper validation code. While changes made to a line that does not begin with an asterisk will not affect product registration, such changes might alter the behavior other products listed in the configuration file. To be safe, always make a backup of thud.ini before making any changes. Thoroughly test all products that use thud before discarding the backup file. Changes to the thud configuration file will not take effect until you issue the following command: thud -i full_path_name_of_thud.ini COBOL runtimes that are started after this command is issued will retrieve the modified parameters. Please refer to the thud user's manual for more information about reloading the thud configuration file. 11 Who Locked It User's Manual V. Programmer's Interface A. Overview Who Locked It configuration variables can be manipulated and lock information can be accessed from within an Acucobol program. By using programmatic modification of configuration variables your programs can turn the automatic display of WLI information on or off, change the time intervals for persistence, or change the text of messages sent by Who Locked It. The WLI callable routine can be used instead of the automatic display to access the details of who has a record or file locked. By using this method, you can include the information in reports, log the information to disk, or create your own WLI display screen. B. Setting Configuration Variables Program control of WLI configuration variables is accomplished using a call to a subroutine with the name T$SETPARAM. For example: CALL "T$SETPARAM" USING "WLI_PERSISTENCE", 120 CALL "T$SETPARAM" USING "WLI_REQUEST1", WLI-REQUEST1-TIME CALL "T$SETPARAM" USING "WLI_REQUEST2", "90" CALL "T$SETPARAM" USING "WLI_KILL", 110 CALL "T$SETPARAM" USING "WLI_REQUEST1_MESG", "@req1_mesg" CALL "T$SETPARAM" USING "WLI_REQUEST2_MESG", "Unlock your records NOW!" The first argument to the T$SETPARAM call must be the name of the configuration variable to be set. The second argument specifies the new value. Value arguments may be specified as numeric values, quoted literals, or working-storage data names. If a working-storage item is used, it must be an alphanumeric or numeric (USAGE DISPLAY) item. Do not attempt to pass COMPUTATIONAL data to T$SETPARAM. These changes take effect immediately. Parameters set using the T$SETPARAM call effect only the user making the call and survive as long as the current runtime is active. C. Retrieving Configuration Variable Values Your program can retrieve the current value of any configuration variable by using the T$GETPARAM subroutine. For example: CALL "T$GETPARAM" USING "WLI_PERSISTENCE", WLI-PERSIST-VALUE CALL "T$GETPARAM" USING "WLI_REQUEST1", WLI-REQUEST1-TIME The working-storage data field passed as the second argument should be an alphanumeric (PIC X) field large enough to hold the expected return value. Numeric values are returned zero suppressed, left justified, and space filled to the right (i.e. "1 "). While this format may not be particularly convenient for numeric manipulation it is acceptable for 12 Programmer's Interface subsequent use as the value argument passed to T$SETPARAM. For example, suppose you wanted to insure that while a particular operation was taking place, your program would not be bothered by messages or termination requests from other runtimes. The following code would retrieve the current values for WLI_NOKILL and WLI_NOMESG, set both to 1, perform your special routine, then restore the WLI_NOKILL and WLI_NOMESG to their original settings. CALL "T$GETPARAM" USING "WLI_NOKILL", WLI-NOKILL-VALUE CALL "T$GETPARAM" USING "WLI_NOMESG", WLI-NOMESG-VALUE CALL "T$SETPARAM" USING "WLI_NOKILL", 1 CALL "T$SETPARAM" USING "WLI_NOMESG", 1 PERFORM SPECIAL-OPERATION CALL "T$SETPARAM" USING "WLI_NOKILL", WLI-NOKILL-VALUE CALL "T$SETPARAM" USING "WLI_NOMESG", WLI-NOMESG-VALUE D. Accessing Who Locked It Information The following example shows how a program can access Who Locked It information. CALL "T$SETPARAM" USING "WLI_PERSISTENCE", 0. CALL "T$SETPARAM" USING "WLI_AUTO", 0. CALL "WLI" USING PID, USERNAME, TTYNAME ON EXCEPTION MOVE "NO WLI" TO PID, USERNAME, TTYNAME. DISPLAY "Record Locked By: ", USERNAME, " PID: ", PID, " on ", TTYNAME The calls to T$SETPARAM insure that no automatic screen displays will appear and may not be needed in your application. 13 Who Locked It Registration and thud Startup APPENDICES APPENDIX A. Who Locked It Registration and thud Startup A.1 Introduction Before Who Locked It can be used on your system, the Threshold Utility Daemon (thud) must be started. Thud provides Who Locked It with information about users on other terminals, delivers messages to other users and controls access to Who Locked It and other products. This appendix offers basic instructions for starting and stopping thud. These instructions assume that thud will use its built in defaults for most options. A.2 Installing Thud To start thud, you must have two files: thud, the executable program, and thud.ini, the thud configuration file. These files can be found in the directory where Who Locked It was loaded. There is no requirement that these files remain in the Who Locked It directory. If you already have or later acquire other products which use thud, you will probably want to establish a common location for all thud related files and programs. A.3 Registration and Configuration The following is a sample thud configuration file. Your file will be somewhat different depending of what products you are running and how they are licensed. You must contact Threshold or your dealer before making any changes to lines which begin with an asterisk (*). Changing one of these lines without a corresponding change to the validation code entry will invalidate the configuration file. Applications which use thud will not operate without a valid configuration file. Typically, the Who Locked It distribution media will include a configuration file containing temporary registration information. ;Sample thud.ini file [thud] *serialnumber= 0022138 *expires = 1-may-94 licensee = "ABC Company" deviceport = /dev/tty00,9600,8,n *validation = JSG FVV SJS VCI HJGN [Who_Locked_It] *revision = 2 *usercount = 99999 key = WEM SNS RWL EVN XTG FWW FGXA *validation = JTS DEC WVH BVF CNSM ;* lines cannot be altered without authorization - included in validation code If you already have a working thud.ini file (used with other products), you will need to add a valid [Who_Locked_It] section to the file. A-1 Who Locked It User's Manual A.4 Installing the Hardware Protection Device Note: If you are using a configuration file with temporary registration data or you have a system which can provide a hardware serial number, you do not need to install a thud hardware protection device. You may proceed directly to the next section: Starting Thud. Thud validates your configuration file and then expects to find a special software protection device attached to one of your serial ports. This following description of the required port characteristics is provided to assist you in selecting an appropriate port for installation of the protection device or in selecting any adapter cables necessary for correct operation of the device. The device must be installed on an asynchronous DTE port with an RS-232 25- pin male connector. Pins 4 (RTS) and 20 (DTR) are required to supply the protection device with positive voltage; both pins are required for the protection device to wok. These pins must be asserted (held positive with respect to pin 7) at all times. The serial protection device is transparent to all character traffic unless it sees a particular sequence transmitted by the computer. This wake-up sequence should never present a problem for other devices attached to the line. Notes: 1. A DTE connection transmits on pin 2 and signals its willingness to communicate on pins 4 (RTS) and 20 (DTR). A DCE connection transmits on pin 3 and signals its willingness to communicate on pins 5 (CTS), 6 (DSR), and 8 (DCD). 2. If an RS-232 Tester, Diagnostic Indicator, or Breakout Box with status LED's is available, it can be used to determine the type of connection a port provides. These RS-232 Testers generally have Green and/or Red LED's/LCD's to indicate power. If pin 2 (TxD) has power then the port provides a DTE connection. If pin 3 (RxD) has power the port provides a DCE connection. For the serial protection device to work on a DTE port, pins 4 (RTS) and 20 (DTR) must also have power. For the serial p r otection device to work on a DCE port using a "Reverser" configuration, pins 5 (CTS), 6 (DSR), and/or 8 (DCD) must also have power. If your computer does not provide an asynchronous port with an RS-232 25- pin connector, you must provide an adapter that does. If the computer provides a DTE connection with power on pins 4 (RTS) and 20 (DTR) and is a male connector, then insert the serial protection device as shown in Figure 1 making sure that the female end of the protection device points toward the computer. A-2 Who Locked It Registration and thud Startup 컴커 旼컴컴컴컴컴컴컴컴컴� 旼컴 旼� � protection � 읕� O P 읕� 旼� device 읕� 旼� P E C � 쿑 � 쿑 T R O M� 쿐 M � 쿐 I I M D A� 쿘 A � 쿘 O P P C L� 쿌 L � 쿌 N H T E E� 쿗 CPU E � 쿗 A R E � 쿐 <-- � 쿐 L R R 旼� 읕� 旼� 읕� A 읕� � � 旼� L 컴켸 읕컴컴컴컴컴컴컴컴컴� 읕컴 Figure 1. Standard Serial Protection Device Connection A.5 Thud Startup Before you start thud, please check to make sure that the following directory exists on your system: /usr/spool/locks If this directory does not exist, please create it. Once you have a proper thud configuration file and a /usr/spool/locks directory, start thud with the following commands: (login as root) cd /usr/thutil [or directory containing thud.ini] ./thud -s -n If you have not yet connected your hardware protection device or if your device has been damaged, add a -f switch to the thud command line shown above. This switch causes thud to run in failsafe mode, bypassing the hardware protection key check. .thud -s -n -f In a production environment, thud should be started when the system moves from single user or maintenance mode to multi-user mode by whatever method is appropriate. Usually this can be done by placing a script in the /etc/rc file or directory. If thud is started in the rc script and a serial protection device is being used, make sure that the particular serial device driver on which the protection device is located has been initialized by the operating system. This is especially important for serial lines that reside on cluster controllers or other smart serial A-3 Who Locked It User's Manual boards in which code must be downloaded and executed on the serial board/controller before the lines are active. A.6 Stopping Thud To stop thud, type the following command line (logged in a root): thud -k A-4 Rebuilding the Runtime APPENDIX B. Rebuilding the Runtime Acucobol provides the components required to re-create the runtime executable, runcbl. This is done by compiling certain Acucobol provided, user modifiable, 'C' source files and then linking the resulting object modules with the file runcbl.a. Who Locked It is installed in runcbl.a so that anytime a runtime is rebuilt, Who Locked It will automatically be included. Creating a new runtime from a runcbl.a does require a 'C' compiler and linker. Some Unix systems (SCO Unix, for example) provide these programs as part of a separate package, usually referred to as a 'Development System'. If you do not have these programs on your system, you will need to contact Threshold or your dealer to obtain a pre- configured Who Locked It runtime. B.1 Modifying the Acucobol Library In the Who Locked It directory (where the Who Locked It media was loaded), run the Threshold installation script by typing the following command: thinstall If the script asks for the location of the thud files, answer by entering the full pathname of the Who Locked It directory or by entering a period followed by the enter key. If the script asks for an unmodified copy of runcbl.a, enter the full pathname of your copy of runcbl.a. The script will make a copy of this file. All modifications will be made to this copy. Ex: Please enter the full pathname to a copy of runcbl.a Pathname or enter q to exit []: /usr/acu231/runcbl.a The script will then install the Who Locked It routines in runcbl.a. You should only need to run this macro one time. If you later make changes to sub.c, sub85.c or another user-defined module and re-link the runtime, that new runtime will contain Who Locked It as long as you link with the modified runcbl.a. You should now move the modified runcbl.a into the directory where you normally build your Acucobol runtime. PLEASE: Make a copy of your original runcbl.a and runcbl files before moving in the modified runcbl.a. B-1 Who Locked It User's Manual B.2 Building the Runtime Use the unix make command to rebuild the Acucobol runtime (runcbl). At the unix prompt, type: make This will compile the necessary source files and create a new runtime. You can verify that the new runtime contains the Who Locked It routines by typing: runcbl -v This will display the Acucobol and Who Locked It revision numbers. B-2 Pseudo Code Illustrations of WLI Logic APPENDIX C. Pseudo Code Illustrations of WLI Logic C.1 Program Encounters a Locked Record or File. When a program encounters a locked record (or file), WLI steps in and performs the following logic. This illustration is not intended as a complete description of all WLI options. It is primarily intended to demonstrate the relationship of the various WLI configuration variables, especially those relating to persistent reads/opens (automatic retries). if WLI_PERSISTENCE > 0 start persist_timer loop until persist_time > WLI_PERSISTENCE if persist_timer > WLI_SILENT display wli_notification_window if persist_timer > WLI_KILL and WLI_NOKILL(in remote runtime) not > 0 display "termination request sent" send termination message and termination request else if persist_timer > WLI_REQUEST2 and WLI_NOMESG(in remote runtime) not > 0 display "request2 sent" send request2 message else if persist_timer > WLI_REQUEST1 and WLI_NOMESG(in remote runtime) not > 0 display "request1 sent" send request1 message pause for WLI_DELAY (or WLI_SILENT_DELAY) seconds retry the read (or open) if record (or file) now available set file status code to indicate valid read (or open) if record (or file) locked by different user restart the persist_timer end loop set file status code to indicate record (or file) locked else if WLI_AUTO > 0 display wli_notification_window wait for WLI_STAY seconds or until user presses a key set file status code to indicate record (or file) locked else set file status code to indicate record (or file) locked C-1 Who Locked It User's Manual C.2 Termination Request Received When a runtime receives a termination request from another WLI runtime, the following procedure is followed: display the termination message in a pop-up window if WLI_LOGOFF_CALL is set CALL "value_of_WLI_LOGOFF_CALL" display "terminated by Who Locked It" on line 24 exit runtime The exit procedure used causes the runtime to close all open files and resets the display to the proper state. C-2 National Language Support (NLS) APPENDIX D. National Language Support (NLS) Many implementations of the Unix operating system provide a service known as National Language Support which allows programs to retrieve data from a language dependent message catalog. Who Locked It will check to see if an NLS catalog file has been defined for the user s language. If so, all display information is taken from this file. Otherwise the English language defaults are used. Although the specifics of NLS configuration vary from system to system, setting up NLS usually involves defining the NLSPATH and LANG environment variables. Please refer to your Unix system documentation for details on setting up NLS. D.1 Modify the Message File Your copy of Who Locked It should have included a file with the name wli.msg. This is the text version of the message catalog file. Make a copy of this file and edit the copy to include any desired modifications or translations. Each message includes a comment intended to aid in the translation of the message to another language. Be sure to observe the remarks regarding any %s or %d parameters in the messages. D.2 Rebuild the Catalog Once the new message text file has been created, it must be converted to the binary format used by NLS. This is usually done with a command line similar to the following: gencat wli.cat wli_french.msg where wli_french.msg is the name of the modified text file and wli.cat is the output file to be produced. The binary catalog file must be named wli.cat. D.3 Move the Binary Catalog Once the new binary version has been created, the file must be moved to the appropriate directory along the NLS path. D-1