Using the Advanced Revelation Upgrade Procedure to Upgrade Developer Applications

Many developers like to upgrade their customers' applications at the same time they upgrade Advanced Revelation to a new version. In the past this has always involved two upgrade procedures for the customer: one from Revelation Technologies to upgrade the system and another from the developer to upgrade the application.

This Technical Bulletin describes how developers can piggyback their upgrade procedure onto the upgrade procedure used by Advanced Revelation. Using this procedure allows the user to enjoy a seamless upgrade procedure for both system and application.

The upgrade is controlled by an operating system file called LOG on disk 1 of the upgrade set. The LOG file contains information about what changes are to be made to the Advanced Revelation system.

Warning! The layout of the data in the LOG file is extremely sensitive. You should make a backup of this file before editing it.

Even though LOG is stored on disk as a DOS file, it is structured as an Advanced Revelation record. Only the first field of this record is of interest to you if you are modifying the upgrade procedure.

Field 1 contains a series of flags, separated by value marks, for the upgrade processor. Two of these flags can be used by a developer, one for a pre-upgrade procedure, and the other for a post-upgrade procedure:

• Value 9 is a list of codes and commands to execute prior to running the upgrade. You might use a pre-process here to check that the user has the correct disks or to check for security clearance to perform an upgrade.
• Value 10 is a list of codes and commands to execute after the upgrade has completed.

In both cases the code and command are separated with a text mark (@TM, ASCII 251), like this:

ExRUN DOS MY_UPGRADE

where x is the literal ascii 251

You can specify multiple codes and commands at each hook. To do so, separate each sequence of codes and commands with a subvalue mark (@SVM, ASCII 252). The codes and commands will be executed sequentially left-to-right. For example, a sequence to present a popup followed by a call to a subroutine might look like this:

PxDOS*UPGRD.OPTSyExRUN DOS MY_UPGRADE

where x is the literal ASCII 251 and y is the literal ASCII 252

In many cases it will be important for you to know what floppy drive is being used as the source of the upgrade. The name of that drive is available to you in the parameter %DRIVE%. You can embed this string of characters anywhere in your code and command sequence that you want to prompt for a drive. When the upgrade processor runs, it will replace this string with the drive name entered by the user (example: "A:").

The 1.x to 2.0 upgrade has a small amount of space available on the last disk. This allows you to keep at least a portion of your own upgrade code on the last of the Advanced Revelation disks. A good strategy is to write a small routine to prompt for the next disk. You can then have the user insert the first of your upgrade disks (you can also verify it), and in this way link your upgrade to the system's.

Your program should be at the DOS level and executed with an E code and command as a post installation process. All programs that are executed in this way should be executed in the RUN DOS %DRIVE% \ program_name format. It is dangerous to assume that a program has been cataloged in the target environment.

For example, this code and command sequence, placed in value 10 of field 1, will execute a program called CHNG on the drive entered by the user at the beginning of the upgrade:

ExRUN DOS %DRIVE%\CHNG

where x is the literal ASCII 251

The next disk and all subsequent disks are, of course, yours. Your upgrade programs will run under your control.

No special checking is done from the post installation processing. However, in pre-installation processing @PSEUDO can be used as an error flag. If @PSEUDO returns non-null after the pre-installation codes and commands have been processed, the upgrade process will be cancelled.

An Advanced Revelation subroutine that you might find helpful for your upgrade is MKDIR. This routine takes two parameters. The first is the name of the subdirectory to create. It must end with a CHAR(0). The second is a status flag. If all went well, this flag will be set to one, otherwise it will be zero. Figure 1 provides a simple example of calling MKDIR.

SUBDIR = ''

CALL MSG('ENTER SUBDIR','RC',SUBDIR,'')

CALL MKDIR(SUBDIR:CHAR(0),FLAG)
CALL MSG('FLAG = %1%','','',FLAG)