RSU 1.5 Remote Software Update for Networks-Documentation Copyright (c) 1992-1995 Burkhard Daniel & Hans-Georg Michna Table of Contents Shareware Licensing and Registration 3 Support 5 Disclaimer 5 Introduction 5 How RSU Works 7 Installing RSU 7 RSU Server Preparation 7 Workstation Preparation 7 The RSU Development Cycle 8 Steps in the RSU Development Cycle 8 Prepare an RSU Test Workstation 8 Create and Test the New Module 9 Protect Users From Your Tests 9 Upload the New Module to the RSU Server 9 Adapt the RSU Program 9 Test the New RSU Program 10 Activate the New RSU Program 10 Programming RSU 10 General Rules 10 Sample RSU Program 11 Execution Sequence 12 Alphabetical List of Commands 12 General Command Syntax and Semantics 12 Sections 13 Environment Variables 13 DOS Commands 14 Echo 14 Goto 14 If 15 IniAddLine 17 IniChangeLine 17 IniCopyLine 17 IniCopySection 18 IniDeleteLine 18 IniDeleteSection 18 SynchronizeDir 18 SynchronizeDir (Old Syntax) 21 Brief Command Overview 23 RSU.DOC [64] 14-May-1995 Shareware Licensing and Registration RSU including its documentation files is Copyright (c) 1992-1995 Burkhard Daniel and Hans-Georg Michna. It is distributed under the Shareware concept. Its use on isolated PCs, for example to change settings in WIN.INI through batch files without the involvement of any network file server is free, even if the computer is connected to a network. As soon as RSU is used to copy files from a network file server to a user's local storage or to copy any parts of files of the Windows INI type from a network file server, however, its free use is restricted to a 30 day trial period. After that the shareware fee has to be paid, if the program is still used. Since the combinations of file servers and workstations can be rather involved, some specifications are in order. If RSU is used to manipulate shared files on other file servers (for example several slave servers being updated from one master server), then each target file server being updated counts only as one user, as long as no individual workstation files are modified on it. In other words, user workstations do not count if RSU is not used to alter their individual files like CONFIG.SYS, AUTOEXEC.BAT, WIN.INI, SYSTEM.INI, PROGMAN.INI, PROTOCOL.INI or NET.CFG. A special case is that each workstation has its individual files in a workstation specific directory on a file server and RSU is used to update the workstations' individual files on that file server (example: diskless workstations). In this case, each workstation should be counted as one user, since RSU is doing exactly the same amount of work as if the workstation specific files were on local workstation disks. The shareware fee for RSU 1.x is US $59.00 or DM 85.00 (German Mark) for each group of up to 100 users. In other words, if the program is used for 1 to 100 users, the fee is US $59.00 or DM 85.00. If it is used for 101 to 200 users, the fee is US $118.00 or DM 170.00, for 201 to 300 users US $177.00 or DM 255.00 and so on. Prices may change in future versions if the exchange rate changes considerably. Future enhanced versions of RSU may be more expensive. In Germany, add the legally prescribed Value Added Tax (currently 15%). The program contains no technical means to enforce payment other than noting the requirement on screen when an unregistered copy of RSU is started. To pay the fee through CompuServe log on to CompuServe and enter the command: GO SWREG. Search for the keyword RSU and register according to the choices you get on screen. Each single registration or license is good for up to 100 users. Alternatively, send a check and your e-mail address (or fax number) to one of the following addresses. USA: A.C.I. Micro, Mark Jordan, 45 Roland, Winchester, MO 63021 World: A.C.I. Micro, Hans-Georg Michna, Notingerweg 42, D- 85521 Ottobrunn In Europe use a Eurocheque for DM 85 or equivalent for each 100 users. In Germany add the legally prescribed Value Added Tax (currently 15%). If you require an invoice, please ask for it by e-mail or send a purchase order to A.C.I. Micro in Germany. But please keep bureaucracy to a minimum. If you can, please register directly through CompuServe's SWREG service, which is much more convenient and probably cheaper for you as well as for us. Within the European community please add your VAT ID. The VAT ID of ACI Micro is: DE 129 2759 98 This is a sample SWREG session in CompuServe: !go cis:swreg <---{User entry after exclamation mark} Shareware Registration SWREG 1 Instructions to Register Shareware 2 Register Shareware 3 Instructions to Submit Shareware 4 Submit Shareware (Authors) 5 Shareware Beta Forum + 6 ASP/Shareware Forum + 7 Provide Feedback 8 Frequently Asked Questions !2 <---{User entry after exclamation mark} ... Press to continue! <---{User entry (return key) after exclamation mark} Please select the geographic region for which you will be registering shareware. 1 United States 2 Canada/Mexico 3 Europe 4 Asia/Pacific Rim 5 Central/South America 6 Africa 7 Middle East 8 Australia/New Zealand Enter region number: 1 <---{User entry after colon} Register Shareware SEARCH BY: 1 Registration ID 2 Title 3 File Name 4 Author's User ID 5 Author's Name 6 Keywords (Categories) Enter choice!6 <---{User entry after exclamation mark} Register Shareware Enter Keyword (ex. - GAMES): rsu Reg ID: 552 Fee (US$): 59.00 Shipping/Handling (US$): 0.00 Title: RSU Version 1 File Name: RSUX.EXE Author: Hans-Georg Michna [74776,2361] Size: 69200 Compression: LHA Computer Type/Operating Systems: DOS, WINDOWS, OS/2 Support: CompuServe Mail to 74776,2361 Forum: GO NOVLIB Library: Shareware Library Number: 15 RSU V1.0 (Remote Software Update for DOS) is a program that can - determine whether a user has the latest update level, - copy, delete, add lines or whole sections from one INI file to another, - add multiple similar lines (like several device= lines in SYSTEM.INI), - insert environment variables, - synchronize directories, i.e. make them equal without unnecessary copying and more. Shareware $50 for 100 users. Upload by author. Would You Like to Register? (Y/N) y <---{User entry after "(Y/N)"} When you license RSU, you will receive information including hints on how to upgrade and a special key to turn RSU into a registered version, but you will not normally receive any paper mail. Neither will you receive the program itself, which is available only on CompuServe and on the Internet. You should retrieve updates from wherever you received the program in the first place. From time to time you may receive information on upgrades and related programs. The program may be freely distributed as long as the files stay together unaltered and packed in one file using an archiving program like PKZIP, LHA or similar. It is not allowed to add any other files other than minor additions that do not exceed the size of the original files. It is not allowed to distribute RSU as part of another program or package because we fear that this might look as if RSU may no longer require its shareware fee payment which it always does according to the rules outlined above. We have in the past sent information by e-mail when there were significant changes to RSU. But you have to download the new versions on your own. You don't have to pay anything again for any upgrades to RSU version 1.x. Should there be a significant technological change, like a new operating system, like a 32 bit OS, then there might be an entirely new version of RSU, which will be handled differently, probably as an entirely separate product. Support Support is available via e-mail from Hans-Georg Michna 74776,2361and from Burkhard Daniel 100342,2050. This support is free. In our experience, luckily, RSU needs very little support, because it doesn't seem to cause many problems. But if you need help, usually in the beginning, please feel free to send e-mail. The same holds for questions, remarks or proposals for future enhancements of RSU. You can also reach us through Internet mail: 74776.2361@compuserve.com and 100342.2050@compuserve.com (Please note the periods in the place of the commas). Disclaimer At the present state of software technology it is not possible to create error-free software. RSU may contain errors. Anybody using it should take precautions like creating safety backups in case a defect causes damage to any computer or data. The authors of RSU can under no circumstances be held responsible for any damage. Microsoftİ is a trademark of Microsoft, Inc. Introduction RSU (Remote Software Update) is a program that updates the software on many individual workstation1 PCs connected to a file server. The file server, when equipped with RSU, becomes an RSU server. The RSU program does not run on the RSU server, however. It runs only on the workstations. The RSU server consists only of subdirectories and files on the file server. Sample RSU installation The fundamental idea is that all workstation configurations are stored on the RSU server. RSU then copies the appropriate modules to each workstation while retaining individual settings or individual software on the workstations. The file server used for RSU does not have to be the same file server that is used for normal work. It is necessary, of course, that users log in to the RSU server from time to time to get the topical remote software update. Since the file server does not usually run DOS a separate RSU test workstation is needed to develop and test the configurations. If testing on different hardware is needed then one RSU test workstation is needed for each hardware setup. RSU test workstations can be used for other work when they are not being used for RSU development. Their RSU related configuration has to be totally reset, however, before it is used for testing. RSU can  copy predetermined files from the RSU server to the workstations,  change the contents of subdirectories, even whole subdirectory trees, on the workstation PCs such that they become equal to their parents on the RSU server, by adding, deleting or overwriting files on the target PC,  exclude certain subdirectories and files from directory replication,  report all changes when synchronizing directories,  add, change, copy or delete certain sections or certain lines in INI files like WIN.INI and SYSTEM.INI,  copy or delete sections in text files like AUTOEXEC.BAT and CONFIG.SYS,  find out whether each workstation is already up to date and skip the updating process,  detect BIOS signatures of certain hardware and, for example, automatically install the appropriate drivers. How RSU Works Since the file server or any program running on any workstation has normally no access to any local disks the main RSU program has to run on each workstation to work its magic. The most convenient way to achieve this is to run it each time any user logs in to the RSU server.2 This can be achieved in different ways on different operating systems. On a Novell network, for example, a command can be called up after the system login script finishes, by using the Novell EXIT "" syntax or by calling it in the middle of the login script with the # syntax. See the manual of your network for details. RSU can be called from a DOS batch file. It has one command line parameter which is the path of the RSU program file. Example: f:\rsu\rsu.exe f:\rsu\rsu.prg RSU.EXE will execute the RSU program file. Files are typically copied from the RSU server to the local disk or modified on the local disk. Instead of the local disk the individual user storage space may also be on a file server. In this case each user's private storage should be mapped to a drive like U:, such that each user sees his private storage area when he refers to U:. Installing RSU RSU Server Preparation Each file server can be a RSU server. The basic method is to keep a mirror image of a workstation in a RSU server directory, for example in F:\RSU\WSIMAGE. There can be several such directories for several different configurations. The configurations have to be created and tested on test workstations, then copied to the RSU server. In addition the RSU server needs one other directory with read-only access for RSU.EXE and the RSU program file (example: RSU.PRG, example of RSU read-only directory: F:\RSU). The management of more than one workstation configuration can easily achieved by creating small signal files on the different workstations which indicate the configuration type. The existence of any of these signal files can then be queried by a simple "If Exist" command. Another method is the BIOS scan, using RSU's BIOS function. Thus the BIOS version of the computer or, for example, of the display adapter can be determined automatically and the appropriate configuration installed without any manual intervention. Workstation Preparation Before installing RSU you have to make sure that all workstations connected to the RSU server have a valid minimal installation. The absolute minimum would be an installed DOS and the minimal network drivers to be able to connect to the server. It is recommended that you have an initial workstation setup procedure to erase all RSU related directories and files from a workstation and recreate the whole minimal setup from scratch. This could be done with a batch file like INSTALL.BAT on the RSU server. This will be very useful for users if they have somehow destroyed vital files on their workstation. They will then have a way to get up and running again if everything else fails and no service person is available. It is also conceivable to use RSU to such an extent that each and every file on the workstation is covered by RSU. This would have the advantage that every workstation would recover from any loss or mutilation of files automatically when logging on to the RSU server. But this will often not be practicable for performance or other reasons. RSU will run inside Windows and Windows NT. Note, however, that Windows or Windows NT may keep certain files open, such that these files themselves cannot be copied or updated. On Windows NT, RSU, like many other DOS programs, requires read and write access to the file CMOS.RAM in the SYSTEM32 directory. RSU, like any DOS or 16 bit Windows program, cannot use long file names, but it will use the automatic substitutes generated by Windows NT. The RSU Development Cycle Steps in the RSU Development Cycle The RSU development cycle is the process of developing a new configuration. Frequently this will just be a small change in an existing configuration, but it could also be an entirely new configuration for a new type of workstation, for example. Development proceeds in these steps: 1. Prepare a RSU test workstation by making it equivalent to the topical RSU update level. 2. Create and test a new configuration or modify the existing one on a test workstation. 3. Temporarily protect users from your RSU server changes. 4. Upload (copy) the new workstation configuration to the RSU server or modify the existing one on the RSU server. 5. If necessary, adapt the RSU program file (example: RSU.PRG). 6. Test the new RSU setup on a test workstation. 7. Activate the new setup, such that it gets installed on all target workstation PCs (undo step 3). In many cases this development cycle can be shortened by skipping certain actions if their effect is minimal or if the number of workstations is low enough such that some risk can be taken. The following sections describe these actions in detail. Prepare an RSU Test Workstation First you have to make sure that your RSU test workstation is equal to a topical workstation elsewhere in the network. If the test workstation has not been used for anything that might have altered the files and directories concerned then it can be used right away. If not, and whenever there are any doubts, the test workstation should be installed fresh from the RSU server. It is a good precaution to log in once after installation and obtain the latest changes from the RSU server to make sure they are included in the workstation image on the RSU server. The RSU update level information can be stored in any file for each workstation. You only have to edit this file or touch it such that the file date or time is changed to force an update. Start the RSU program, normally by logging in to the RSU server. The test workstation should automatically be updated to the topical update level. After the test workstation is up to the present standard you can now make the desired changes. Create and Test the New Module Now you can make the desired modification on the test machine only. Test thoroughly, since all your users who use that module will depend on your conscientiousness. Protect Users From Your Tests As soon as you touch the RSU server all users who happen to use the server will receive any modification. Therefore you have to make sure that this does not happen. There are several ways to protect users: 1. Deactivate the whole RSU server until you are done with all changes. One way is to rename the RSU program. Without it RSU will not be able to do anything. Another is to activate a jump over the RSU part of the controlling batch file. 2. Leave the RSU server running and create a second RSU server at least for the module you intend to work on. This is not quite so difficult as it sounds. It may be necessary for bigger changes that require some time to work out. 3. If you are making a very small change and you are absolutely sure that even a mistake can do no harm you may risk to work on the hot system. But be careful! Depending on the number of workstations and likelihood of a login you should be able to make the change within seconds. This might be viable if you just want to change a few files, for example. Again do not forget to change the date and time of the RSU update level file afterwards, so all users get a new update when they log in. Upload the New Module to the RSU Server After you have tested the new configuration thoroughly on your test machine you can now copy the modifications to the RSU server (for example to the F:\RSU\WSIMAGE directory and its subdirectories). It is useful to have a program that can detect the difference between files on two drives like the Norton CommanderT with its "Compare directories" command. In any case be sure to copy all changes from the test machine to the RSU server. Adapt the RSU Program Now change the RSU program (example: F:\RSU\RSU.PRG) if necessary. The modified RSU program should be able to copy all modifications from the RSU server area to any workstation PC. If you make changes to files by means of direct manipulation by the RSU program, for example with IniChangeLine, be sure to make those changes on the original files on the RSU server as well, such that users who do an install from scratch also get them immediately before they receive the next RSU update. Test the New RSU Program After the update is entirely in place but not yet activated you should test it before releasing it to all users. For this you either need a second test machine or you have to reset the first one to the previous configuration which is still standard for all other users. Then you have to make sure that the new update affects only the test machine but not yet all the other users. There are several ways to achieve this. The easiest is to modify the RSU program file such that only the testing user gets the update. Example: ... If %USER% <> SUPERVISOR Then Goto Not_yet End If rem Here enter the RSU commands to be tested. Not_yet: ... This sample batch file fragment presumes that the network user name was written into the environment variable USER, for example with the Novell Netware login script command: DOS SET USER="%USER_ID". Check whether the update is correct. You may have to test each configuration separately if there are several. Activate the New RSU Program Finally, after you have convinced yourself that the new update works correctly, you can release it to all users by removing any blocking commands you might have inserted. From that very moment all users who log on will receive the update. Programming RSU General Rules RSU is an interpreter for the RSU control language which strongly resembles BASIC and, to some extent, DOS batch files. The RSU program is the file which controls all RSU operations. It should reside on the RSU server, for example as F:\RSU\RSU.PRG. All users should have read-only access to it. RSU is started from DOS with either of the following commands: RSU RSU.EXE RSU /debug RSU.EXE /debug The /debug switch produces a display of all commands, as they are executed. As long as the program is unregistered, it always displays a shareware registration screen first. Apart from this, however, the program is fully functional and may be tested with all functions for 30 days. After that time the program must be registered for further legal use, although the program would technically still function properly. Sample RSU Program This is an example of an RSU.PRG file: rem RSU.PRG file rem First determine whether the user already has the latest version: If c:\rsu\version.txt Equal f:\rsu\version.txt Then echo Your workstation has the latest update level. Goto Finish End If rem Let user know what's going to happen to his computer: type f:\rsu\version.txt pause rem Modifications to WIN.INI: IniCopySection f:\rsu\wsimage\win31\win.ini c:\win31\win.ini [fonts] IniCopySection f:\rsu\wsimage\win31\win.ini c:\win31\win.ini [devices] IniDeleteSection c:\win31\win.ini [ObscureOldProgram] IniCopyLine f:\rsu\wsimage\win31\win.ini c:\win31\win.ini [windows] load IniDeleteLine c:\win31\win.ini [fonts] Swiss= IniChangeLine c:\win31\win.ini [mail] mailbox=%USER% rem Modifications to SYSTEM.INI: IniAddLine c:\win31\system.ini [display] svgamode=98 rem Synchronization of user files: SynchronizeDir From f:\rsu\wsimage\win31 To c:\win31Add End SynchronizeDir SynchronizeDir From f:\rsu\wsimage\util To c:\util Add Overwrite Delete Subdirectories End SynchronizeDir rem Users with HappyVGA adapters get a new driver and support rem utilities. This requires that such users have a signal file rem c:\rsu\happyvga.sig: If Exist c:\rsu\happyvga.sig Then SynchronizeDir From f:\rsu\wsimage\happyvga To c:\happyvga Add Overwrite Delete Subdirectories End SynchronizeDir End If rem Now install version text file to make sure that this rem user doesn't get the same update again: copy f:\rsu\version.txt c:\rsu Finish: rem End Of File Execution Sequence RSU is a pure and simple interpreter. This has consequences especially when using the Goto command in connection with If, Then, Else constructs. RSU takes these commands exactly in the sequence they are processed. This means that a Goto jump into an If structure can cause unexpected results if the programmer isn't aware of the actual processing sequence. Therefore it is not advisable to jump into an If command. Jumping out of an If command doesn't hurt. The If construct is simply never completed. But if it is done many times, for example in a loop, it will eventually cause a memory overflow. You should therefore try to use the Goto command sparingly and prudently. Ghastly mistakes can happen if the interpreter encounters, for example, an Else command after jumping out of an If construct, because the interpreter would assume that the Else belongs to the last encountered If command. Alphabetical List of Commands General Command Syntax and Semantics All control files are text files in which each line is followed by a carriage return/line feed pair (13dec and 10dec). Spaces and tab characters in the beginning of any line are totally ignored. In effect it is as if those characters were removed before executing the RSU.PRG program. Lines beginning with "REM " or ";" (a semicolon) are treated as comments and not otherwise executed. Upper and lower case are functionally equivalent. However, the case is retained when information is forwarded into another file. Command parameters are separated by spaces, with the exception of section headers (section name in brackets) and INI lines after a section header. If a parameter itself contains one or more spaces, it has to be enclosed in double quotes (character no. 34 in the ASCII/ANSI alphabet), so it is not mistaken for several separate parameters. If a quote character itself is to be included, two adjacent quote characters have to be written, but this is possible only within another pair of quotes. Examples: If Bios(C000-C080) = "ATI GRAPHICS" Then ... End If If %COMPUTER_TYPE% = "Label ""Taiwan""" Then ... End If The second example compares the environment variable COMPUTER_TYPE with the following text, including the two quotes: Label "Taiwan" If the first word in any line is a valid RSU command then it is executed. If not the line is deemed to be a DOS command and is forwarded to the DOS command processor. Note, however, that not every DOS command can be used. For example, the DOS command SET has no effect because it is running under a secondary command processor that has no access to the primary environment. In the syntax definitions below, a few special characters and words are used that have a special meaning. A word enclosed in angle brackets is a placeholder for a user defined, variable entry: < > The following placeholder stands for any valid RSU command: An ellipsis stands for "more of the same": ... Braces and vertical bars are used to define a user choice of one out of several units. Only one can and must be chosen: { | | } Sections Several commands work on sections in .INI files. A section is recognized by its header. It ends before the next section header. A section header consists of a section name in brackets. Examples: [windows] [HPPCL5A,LPT1:] [Microsoft Word] The section header must begin in cloumn 1, i.e. in the leftmost position of a line. Technically spoken, the opening bracket must immediately follow the carriage return, line feed pair that ends the previous line, or it must be the first byte of the whole file. All lines following the section header belong to this section until another section header follows. Note that section headers can contain spaces. RSU still recognizes the section header by the enclosing brackets. You don't need double quotes when referring to a section header in an RSU command. To facilitate manipulation of sections in files like AUTOEXEC.BAT or CONFIG.SYS, a second, alternative form of section header is also recognized, which consists of the abbreviation REM in upper, lower or mixed case, followed by exactly one space, followed by a section header as described above. The R in REM must be in the leftmost column. Examples: REM [drives] Rem [NETWORK DRIVERS] rem [User Specific Settings] Warning: Never use the alternative REM syntax inside an RSU command file. All RSU commands work without containing the word REM, even if the target files contain it. Hint: If you want to turn such REM lines into real comments rather than RSU section headers, insert at least a second space or any other characters between REM and [. Hint: While all RSU commands will recognize and accept this alternative syntax and work on it and in the sections thus designated, only the command IniCopySection can put such a section header into a file. Environment Variables Environment variables can be inserted in any command with the syntax: %% Example: IniChangeLine C:\WIN31\WIN.INI [mail] mailbox=%USER% This example will take the name from the USER= entry in the environment and substitute it for %USER% before executing the IniChangeLine command. For example, if the environment contains an entry reading: USER=DANIEL then the command above will be changed to: IniChangeLine C:\WIN31\WIN.INI [mail] mailbox=DANIEL which is useful for example to save users the separate logging in to Microsoftİ Mail. The substitution happens before any quote characters are processed, i.e. environment variables can be used inside quotes. To use a percent character (%) for other purposes, you have to write two adjacent percent characters (%%). However, RSU cannot use environment variable names that contain percent characters. You can use the double-percent feature only outside environment variable names. Environment variable names may contain spaces (example: %DEPT NAME%). It is not necessary to enclose them in quotes because of these spaces-RSU already recognizes the percent signs and processes them before spaces are considered. But superfluous quotes outside the variable name don't do any harm either. Hint: Novell Netware 3.11 can place essential system information entries into the environment with the SET ="" syntax of its login scripts. Example of a command in a Netware login script: SET USER="%USER_ID" DOS Commands Any command found in an RSU program file that is not a valid RSU command is deemed to be a DOS command. A secondary command processor (COMMAND.COM) is loaded and the command forwarded to it and executed. There is no error checking and no logging with DOS commands, so be careful to test and use them properly. Echo This command simply echoes some text on the screen. It works like the DOS command with the same name. It was incorporated only to increase speed and to avoid unnecessary empty lines on screen. Syntax: Echo Example: Echo RSU is now installing new video drivers... Goto This command continues execution of the RSU program file at the point after the label. The label can be anywhere else in the program file but has to be in its own line, i.e. no other command can follow in the line that contains the label. A label must be at least two characters long, not counting the colon. The reason for this is that c: means change to drive C:, rather than a label C. Labels may contain letters, digits and the underscore _. They may not contain spaces, umlauts or any other special characters. Syntax: Goto