Lock Tools Administration Manual Steve Clarke May 1994 Lock Tools Administration Manual Page 2 INTRODUCTION The Lock suite of programs is provided to give network administrators the ability to control the number of copies that a peice of software may be run at any one time. The software has no network specific calls, and therefore should work an any network where file read/write sharing can be performed. There are three types of lock, DOS, Windows, and Windows Stub. DOS locks can be applied to any DOS application; Windows locks can be applied to any Windows 3.1 application. Windows Stub locks are special, and intended purely for the WIN.COM program. The programs have been tested on MS DOS 3.3, 5.0, 6.0 and 6.2, Windows 3.1, and Windows 3.11. The Windows lock program requires the use of TOOLHELP.DLL (which is distributed with Windows). 05/17/94 Lock Tools Administration Manual Page 3 INSTALLING The installation program uses four separate areas: o A program area. This area must be made read only by users, and must exist in the PATH. o An administration program area. This area is in a subdirectory under the program area, and is called ADMIN. It contains the lock management tools and documentation. This subdirectory should not be accessible to users (apart from the system manager). o A control directory. This directory holds information about how many applications of each type are allowed to be run. This directory should be made read only to users. o A Lock directory. This directory is where all of the locks are stored. It should be made read/write to users. When locks are taken out, the attributes are changed to read-only through DOS; this will cause the lockrm program to behave differently on different types of network. To install the program, put the installation disk into a disk drive (A:, say), then type A:INSTALL. (Note that it is possible to install from any drive or subdirectory). Once the install program has read in its configuration data, you will be asked which is the destination directory for the programs. Once entered, this directory will be created (if possible). If at any time, you wish to abort the install procedure, simply press the Escape key. You will then be prompted for the Control Directory. Enter the full path name for this directory. You will then be prompted for the Lock Directory. Enter the full path name for this directory. 05/17/94 Lock Tools Administration Manual Page 4 The installation procedure will continue, and all of the files will be copied into their respective directories. In addition, the installation procedure will create a LOCK.INI file in the program directory. IF YOU ARE UPGRADING FROM A PREVIOUS VERSION, THE LOCK.INI FILE WILL BE OVERWRITTEN. When the istallation procedure is complete, you will be left in the program directory. As the software is network independant, it is not possible to change any of the network file permissions. You should do this now, manually. 05/17/94 Lock Tools Administration Manual Page 5 CONFIGURING A MACHINE To enable a machine to identify which locked applications belong to it, each machine is given a host reference. This should be a one, or two letter identification string. To set the string, add a line to the machine's boot file (AUTOEXEC.BAT) as follows: set HOSTID=xx Where xx is a one or two character sequence which is unique. Note that 'AA' and 'aa' are treated as the same HOSTID by the lock tools. CONFIGURING A USER To enable the correct reporting of which user has taken out which application, each user should have an identification string. Ideally, this should be unique. To set the string, add a line to the user's login file (or to the system login file) as follows: set USR=uuuuuuu Where uuuuuuu is the username. Note that this username is used for outputting information only (up to 32 characters will be displayed), so there are only practical limits on its size and contents. 05/17/94 Lock Tools Administration Manual Page 6 THE LCONFIG UTILITY To create a blank LOCK.INI file in the current directory, lconfig may be used. Type the following: lconfig CreateIni path_to_lockdir path_to_controldir The LOCK.INI file should be edited manually to include user name and registration data. To take out locks on an application, the program lconfig should be used (with no parameters). Once started, you will be shown a screen with a menu bar, and an empty box. At any time when using this program (apart from when entering a string), pressing Escape (or x) will cause the program to end. To select an item off the menu bar, press the highlighted letter. 05/17/94 Lock Tools Administration Manual Page 7 LOCKING AN APPLICATION To lock an application, start up lconfig, and press 'I'. You will be asked for an application name. Enter the full pathname (and filename) of the application (including the extension). For example: Enter Application to Lock: L:\APPS\PROGRAM\BORLANDC\BIN\BC.EXE Note that if the application is already under lock, the locking stub will be updated. If this is a new lock, you will be asked for a one line description of the application. You will then be asked whether the application is (D)OS, (W)indows, or a Windows (S)tub. Select the appropriate response by pressing either D,W, or S. The lock for the application will then be created, and the application should be added to the top window. Locking an application involves the following process: Rename PROGNAME.EXE to PROGNAM_.SLP Copy Appropriate Locking Stub to PROGNAME.EXE Create a control file called PROGNAME.0 CHANGING NUMBER OF COPIED OF AN APPLICATION To change the nubmer of copies of an application which are available, simply use the arrow keys to move the cursor to the appropriate application, and type in a new number. Afer pressing Enter, you will be asked to confirm the change, then the change will be made. The change procedure involves the following: Rename Control file PROGNAME.xx to PROGNAME.yy (where xx = old number of copies, and yy = new number of copies) 05/17/94 Lock Tools Administration Manual Page 8 UNLOCKING AN APPLICATION To remove the lock from an application, use the arrow keys to move the cursror to the application which requires unlocking, and press 'D' (for lock delete). You will then be asked for the full pathname of the application (including the extension). This pathname is used to re-create the original file name, so be sure to get the .COM or .EXE extension correct. Once entered, the lock will be removed. Note that an extra layer of security has been added into the program with this release, to remove the possibility of file deletion. File contents are checked, and a file will only be removed if it is a valid lock stub. This means that locking stubs from previous versions of lock, and files that have been renamed without the use of lconfig may cause errors. If these errors arise, it is up to the administrator to ensure that the correct files are given the correct names. Unlocking an application involves the following procedure: Delete PROGNAME.EXE Rename PROGNAM_.SLP to PROGNAME.EXE Delete control file PROGNAME.yy GETTING INFORMATION To receive information about the user (registration), press 'I'. The user and registration inforation is stored in the LOCK.INI file. 05/17/94 Lock Tools Administration Manual Page 9 POTENTIAL HAZZARDS Problem: Because the lock program PROGNAME.EXE always looks for the original program (now named PROGNAM_.SLP), the lock program will be unable to lock two applications in the same directory with only the last character in the filename different. It will also be unable to lock a .EXE and a .COM file in the same directory. Example: PROGA.EXE Will all be renamed to PROG_.SLP PROGB.EXE PROGA.COM PROGB.COM Symptoms: LCONFIG will give an error saying that it cannot delete what it thinks should be a lock stub. Solution: Rename any potential problem files. so that no two programs in the same directory can cause this problem. Problem: Users crash an application, reboot the machine, then walk off. Depending on the network, this can be a problem. Some network configurations will insist on the original user running lockrm on the original machine, Some configurations will allow any user to run lockrm on the original machine. Symptoms: Lockrm refuses to remove locks on a machine. Solution: As there are may problems here, there is not one solution. One possible solution is for the network administrator to remove the locks manually (ie attrib, then delete *.%MACHID% and *._%MACHID% in the control directory) - this is only possible if the network administrator can attrib other user's files. (check AD0001.BAT in the ADMIN directory). A Second solution is for a job to run on the file server, searching for machines which are not turned on, and removing any files which belong to that machine. (check AD0002.SH in the ADMIN directory). 05/17/94 Lock Tools Administration Manual Page 10 ERROR MESSAGES The following error messages are due to an inconsistency in the system configuration, they are intended for the System Administrator. Unrecognised Machine Identification This means that the HOSTID environment variable has not been set. Set the environment variable. Unable to Find Overlay Application PROGNAME.EXE could not find PROGNAM_.SLP. This could be due to the file missing, or a network permissions problem. Restore this file (It is the original PROGNAME.EXE and retry). Unable to Create Application Lock The user does not have write permission to the lock directory. Unable to Remove Application Lock Either the user has been denied write access to the lock directory whilst running an application, or his lock has been removed before the application has finished. Unable to Execute Application - Invalid Program Path - Invalid or Corrupt Program - WinExec Error nn These error messages are reported by Windows, and intended to help give a better indication of as to why the child program cannot be run. 05/17/94 Lock Tools Administration Manual Page 11 Unable to Access INI Data The lock program cannot find the LOCK.INI file. This is either the INI file is not in the PATH, or the INI file does not have read permissions. INIFile Error: No CONTROLDIR Entry in LOCK.INI INIFile Error: No LOCKDIR Entry in LOCK.INI INIFile Error: EXEFLAGS option on LOCK.INI should be X or A A line in the LOCK.INI file is not syntactically correct (or is missing). Correct the line (or re- create the INI file with lconfig). This Application is Already Running on This Machine Either the application is running on the machine (another Windows application, a DOS application in a DOS Window, or a DOS application in an application DOS shell), or the machine has crashed when an application was running. Either use the running application, or use LOCKRM to remove the incorrect locks. Too Many Copies. Try Again Later You have attempted to book out one more copy of an application than has been allowed. Use LOCKINFO to find out who and where the applications are being used, and wait. 05/17/94