Moving an Application in Advanced Revelation
Published By | Date | Version | Knowledge Level | Keywords |
---|---|---|---|---|
Revelation Technologies | 14 JAN 1990 | 2.X | INTERMEDIATE | ACCOUNTS, APPLICATION, DESIGN, INDEXING, LISTS, MACROS, QFILES, SYSTEM, VOC, VOLUMES |
Although Advanced Revelation is a powerful and complete environment, you are shielded from much of its complexity. For example, you rarely need to concern yourself with the relationship between Advanced Revelation and operating system files, with specifying path or drive designations when accessing data, or with explicitly attaching and using indexes.
There is at least one time, however, when you must understand how Advanced Revelation creates and accesses data files and commands: when transferring an application from one system to another. Because Advanced Revelation manages much of the process of the distributing data, it is not inherently simple to transfer an application from a development system to a client system.
This technical bulletin provides information on the creation of a portable application and on transferring all or part of an application. Because applications are not always designed for portability from their inception, two topics are presented: developing an application with transferability as a design consideration, and rearranging the data after the application is completed.
To begin with, though, background information on such concepts as volumes and accounts is provided. A general understanding of how Advanced Revelation views application and data storage design will help a great deal in designing an application for portability.
Data Storage in Advanced Revelation
Advanced Revelation stores information in files, as do all other applications. However, in Advanced Revelation, a file is located and identified using a volume and is associated with an account. This section is an introduction to these sometimes confusing concepts.
Volumes
The terms volume and subdirectory are often confused. Within the context of Advanced Revelation, a subdirectory has the same meaning as it does for other PC-based applications.
In addition, Advanced Revelation distinguishes a subdirectory from the more precisely-defined term volume. A volume defines the unique combination of a location (usually a subdirectory path) and a file type. File types currently available in Advanced Revelation include Linear Hash, ROS, and Revelation G files. Unless you specify differently, Advanced Revelation will use the default file type of Linear Hash.
By default, Advanced Revelation will create all new files on the default volume, called REVBOOT (in Advanced Revelation Version 2.0, new files will be created on a volume called DATAVOL). REVBOOT is always defined to be the path from which you logged into Advanced Revelation, and always uses the Linear Hash file type. To create files on any volume but REVBOOT, you must indicate a different volume name when entering the MAKEFILE command. And to create a new volume, you must define or set a volume pointer.
When a volume is defined, it points to the designated subdirectory, and lets Advanced Revelation know what kind of files it will find there. Each volume can only contain or refer to one type of file.
A volume definition is not strictly necessary. If you are dealing exclusively with Linear Hash files, you could refer to a volume using only the operating system path. A long operating system path can be cumbersome, though. Setting a volume pointer allows more flexibility in naming schemes.
To create a volume pointer, use the SETVOLUME command. For example, if you want to create the volume CLIENTS containing Linear Hash files on the DOS path C:\PURCHASING\CLIENTS, the command from TCL is:
SETVOLUME CLIENTS RTP57 C:\PURCHASING\CLIENTS
This example creates a record in the VOC file with CLIENTS as the key. Field 1 contains the word VOLUME, field 2 contains RTP57, and Field 3 contains the DOS path. RTP57 is the Linear Hash filing structure. By following the menus to the SetVolume window, choices for the filing structure can be obtained by pressing [F2] at the Filing System prompt.
All files used by Advanced Revelation must reside in an attached volume. The only volume containing datafiles that is attached at logon is REVBOOT. Any other volumes must be explicitly attached with an ATTACH command. For example, this command attaches the volume CLIENTS:
ATTACH CLIENTS
If you want to access only a subset of the files on the volume, these filenames can be appended after the volume name. For example:
ATTACH CLIENTS NAMES COMPANIES
Each file that is attached must have a unique name. When you attach files, any files with the same name that were already attached are detached. For instance, if a file NAMES were already attached, executing the example would automatically detach it and attach the file NAMES on the volume CLIENTS.
Accounts
An account is a collection of files that contain related information, such as payroll or inventory. Accounts can be used to segregate applications or to protect sensitive information. It is typical to isolate individual applications on the same copy of Advanced Revelation into separate accounts.
For example, you might create an account called PAYROLL to store the data and control information (window templates, popups, programs, etc.) used by that application. To access this account you would enter Advanced Revelation by logging in to the PAYROLL account instead of the default SYSPROG account.
When an account is created, all system files needed to develop and run applications are made available to it. However, the various application-specific files reside exclusively in the new account, and are not accessible from other accounts.
There are two exceptions global files and Qfiles. Files in the GLOBAL account are available to all accounts. Qfiles are synonym file names. These make it possible to access files in other accounts (a password is required if the target account is password protected). A Qfile also makes it possible to access a file that cannot be attached because one with a duplicate name is already attached.
Designing an Application for Portability
The instructions that follow present a series of suggestions for creating applications that can be ported easily between systems. The process described in this section builds the application with consolidated files, enabling an operating system copy command (for example, the DOS COPY, XCOPY, or BACKUP commands) to transfer the data from the source subdirectory to the target. Then, with minimal preparation, the data can be used by the new system.
- The basic process is simple:
- establish a new volume
- create a new account and new users
- move application-specific system files to the new volume
- create all new application files on the new volume
REVBOOT-bound Files
There is a slight complication in that certain system files must reside on REVBOOT (the default volume) so you can log into the application properly. These files are:
VOC
Commands to be executed when the user logs on to Advanced Revelation are stored in the VOC file as logon verbs. One of the most common uses of logon verbs is attaching volumes. For example, to create a logon verb to attach a CLIENTS volume and the UTILITY volume, follow these steps:
1.At TCL enter:
EDIT VOC LOGON.user.name
2.Enter the following in the first three lines:
TCL ATTACH CLIENTS ATTACH UTILITY
The VOC file must reside on REVBOOT because Advanced Revelation must read the logon verb from the VOC file to attach any other volumes.
MACROS
The default macro designated in the environment is read before the logon verb is executed. If this macro set cannot be found in REVBOOT, an error message will display during the logon process. Consequently, MACROS must also be stored in REVBOOT.
LISTS
As Advanced Revelation boots up, the TCL command stack is read from the REVBOOT LISTS file. As users log off, the stack is written to the currently attached LISTS file. Therefore, if the logon and logoff versions of the LISTS files are not the same file, each day's commands will be lost.
QFILES
Any permanent Qfiles (those created with the (W) option) that may be used in a session are read at logon. A QFILES file may subsequently be attached, but Advanced Revelation will not recognize any permanent Qfiles that were not initialized at logon.
Preparing the New Application
Follow these steps to prepare a new application that is easily portable.
- Create a subdirectory on the hard drive of your development system. All files specific to the application will be created and stored here. This will prevent needless file rearranging and re-indexing later.
- Create a new account on your development system. The account name must be the same on the development system and on the system the application will be run on. Again, this will prevent needless complexity when moving the application later.
- From the Tools-Files menu or from TCL set a volume pointer to the subdirectory created in step 1. This creates a logical name for the subdirectory.
- Define environments and video attributes for each user. This information is stored in the SYSTEM file. Make a temporary file on the new volume to contain this information. Note that this file will belong to the SYSPROG account, not to the application account. Use syntax like this from TCL:
MAKEFILE new.volume TEMP.SYSTEM
Using RECORDCOPY, transfer the environment and video records from the system file into the new file. In the SYSTEM file, all video and environment records have .VIDEO or .ENVIRONMENT endings, respectively.
Here is sample syntax for copying the video and environment records for a user:RECORDCOPY SYSTEM user.VIDEO user.ENVIRONMENT TO: (TEMP.SYSTEM
- Log to the newly-created account.
- Once again, set a volume pointer to the subdirectory created in step 1. Although you have done this step before, you must create a separate volume pointer in each account.
- Move all application-specific system files to the volume on which you will store your application files. This step is necessary because Advanced Revelation creates system files on the REVBOOT volume when making a new account.The following application-specific files are created by Advanced Revelation when an account is established:
CAPTURED FILTERS HELP IMPORT.EXPORT LABELS LISTS MACROS MENUS MERGES POPUPS QFILES QUERIES REPORTS TEMPLATES UPDATE VOC
Move all of these files with the FILECOPY command except VOC, MACROS, QFILES, and LISTS. These files must reside on the REVBOOT volume when you log into the new account. They are moved to the application volume in a later step.Use the delete option (D) when copying in order to remove the version of the file that exists on the REVBOOT volume. Be sure, however, that you delete only the data portion of the file, because the dictionary for these files is global.The CAPTURED, HELP, QFILES, and REPORTS files have no dictionaries, so the whole file can be copied. However, to avoid duplicate dictionary files, copy only the data portions of the other files. A sample command to move the POPUPS file looks like this:
FILECOPY DATA POPUPS (D) TO: ï new.volume new.account POPUPS
- Attach the new volume and begin development. All development should be done in the new account with the new volume attached. Be sure that all data and program files created during the development process are created on the volume to be transported.
- When application development is complete, use FILECOPY to copy the data portions of your VOC, MACROS, and QFILES files, and the entire LISTS file (which has no dictionary), to your application volume. When you copy these files, rename them to avoid confusion when copying them into the new system. Use this syntax as an example:
FILECOPY DATA VOC TO: new.volume ï new.account TEMP.VOC
- Update all indexes.
Transferring the Application
Follow these steps to move your application from the development system to the client system.
- On your development system, use DOS BACKUP (or equivalent) to move your application subdirectory to one or more floppy disks. On the target system, create a matching subdirectory on the hard drive. Using DOS RESTORE (or equivalent), copy the floppy disks to the new subdirectory. The goal is to transfer the subdirectory in its entirety from the source to the target system.
- On the target SYSPROG account, create a volume pointer to the new subdirectory.
- Make and Secure your new account and users.
- Attach the new volume from SYSPROG.
- Using RECORDCOPY, copy the SYSTEM records from the temporary SYSTEM file to the SYSTEM file on the target system. The command will look something like this:
RECORDCOPY TEMP.SYSTEM * TO: (SYSTEM (O)
- Log to the new account.
- On the new account, create a volume pointer to the new subdirectory.
- Attach the new volume using an ATTACH command.
- Using FILECOPY, copy the temporary VOC, MACROS, LISTS, and QFILES files from the new volume to their REVBOOT counterparts on the new account using the overwrite option. Use this syntax as an example:
FILECOPY TEMP.VOC TO: REVBOOT ï new.account VOC (O
- Log off. You are now ready to use the application. From the Advanced Revelation subdirectory, enter (for example):
AREV user.name
- If no logon verb exists to attach the new application volume, the user will need to attach the volume after logging in.
Moving an Existing Application
Existing applications can require a little more effort to move. It is easiest to move an application if its files are consolidated into a single subdirectory. However, unless you have isolated your application files from the start (as described above), they will all be in the REVBOOT volume.
The solution is to move these files onto one volume for transfer. The process is not difficult, but can be tedious. In addition, it is more complex if files to be moved have been indexed.
Indexing
When you index a file, Advanced Revelation automatically creates the appropriate index file and initializes it with control information about that index. An important component of this information is the location of the data to be indexed.
To identify index updates uniquely for all possible files in the system, Advanced Revelation uses the media name (the internal label for a volume). The media name stamped on all index updates is used later when it is flushed to the appropriate index file.
Because of this location stamp in an index file, you cannot move an index from one volume to another. As a result, all indexing must be removed from files before they are moved. The Advanced Revelation FILECOPY command strips indexes from a file as it copies it. If you use a different method to move a file, you should manually remove indexing before transferring the file.
Note: if you attempt to bypass this restriction on moving indexes from one volume to another, your index will not work properly on the target volume, and may also corrupt other indexes.
Steps to Move an Existing Application
Follow these steps if you wish to move an application that already exists on your system.
- Remove all indexing (see the topic Indexing above).
- Follow steps 1 to 7 under Preparing the New Application above.
- Using the SETFILE and RECORDCOPY commands, copy all records from the files in step 7 of Preparing the New Application to their respective new accounts and volumes. For example, if the original TEMPLATES file is in SYSPROG on REVBOOT and the password to SYSPROG is PASSWORD, then the following statement at TCL will set a pointer to the TEMPLATES file:
SETFILE REVBOOT SYSPROG,PASSWORD ï TEMPLATES
- Use FILECOPY to copy all data and program files to the new account and volume.
- Re-install and rebuild all indexes.
- All files necessary for the new application now reside on the new subdirectory. Proceed with steps 8, 9 and 10 from Preparing the New Application above.
- Install the new system as described under Transferring the Application above.
Closing Reminders
Bear the following in mind when moving an application from a development to a client system:
- Make a backup of the original system in case of errors.
- The name of the account you develop in or copy to must be the same as the target account.
- Flush all indexes before moving an application.