Progress
Developer’s Toolkit
Upgrading with Updated .df and Encrypted Source
When you update a database structure in the development environment, you must then re-create these changes in the database that is already established at the deployment site. To accomplish this transfer, an incremental .df file is generated in the development environment. Copies of the original and updated databases are compared, and the differences between them are incorporated into an incremental .df file. For more information on creating an incremental 4GL data definitions file see the Progress Database Administration Guide and Reference for more information about deploying changes to database structures. The following general steps tell you how to prepare a .df file that includes new or modified data definitions:
- Obtain copies of the current user database and the new modified database.
- Connect the two databases.
- Compare the data definitions in the user database with the data definitions of your new updated database, creating a new incremental .df file that reflects the changes.
- Provide a utility for users that loads the incremental .df file into the existing database.
- Encrypt the procedures affected by changed data definitions.
In Windows, use the Data Administration Tool and follow these steps (for character interfaces, use the Data Dictionary):
- Connect the two databases by choosing Database
Connect.
- Select the database that includes the new, modified data definitions as your current database by choosing Database
Select Working Database.
- Create an incremental definition file by choosing Admin
Dump Data and Definitions
Create Incremental .df File.
This option compares the data definitions in the nonempty copy to the current database schema and creates a new data definition (.df) file. The new .df file contains a record for each difference between the two schemas. The differences include any added, renamed, changed, or deleted file, field, or index.
If a file, field, or index exists in the old database but not in the new schema, Progress asks you whether the object has been renamed. If you respond “no,” a record appears in the new .df file marking the object as deleted.
If the new schema includes a new unique active index, Progress asks you whether you want to deactivate it. If you do not deactivate the index, and there are duplicate keys in the old database, Progress aborts your attempt to load new definitions into the old database. If you deactivate the index, the load procedure defines the new index, but does not create the index file. You must build and activate the index after loading the new data definitions.
- Perform steps a through d below for testing purposes. Then prepare a tool for users that performs these steps on site. (The
upgrade
template provided with the Developer’s Toolkit outlines one way to do this. Before you can use this template, you probably need to modify it.)
- Select the copy of the old database as your working database.
- Load the updated data definitions by choosing Admin
Load Data and Definitions
Load Data Definitions (.df file).
- If you deactivated any indexes in Step 3, re-create data in the indexed fields as required to avoid duplicate keys. Then reactivate the indexes with PROUTIL IDXBUILD. For more information, see the Progress Database Administration Guide and Reference.
- Progress now updates the old database schema to match the modified schema. Compile and test all your procedures against the updated database.
- Test your procedures.
- Use the XCODE utility to encrypt procedures invalidated by the new data definitions.
Since the new .df file changes CRC check sums and time-stamps only on the database tables that are actually modified, you only have to encrypt and ship the source versions of those procedures that access the changed tables. (If you compile your procedures with the XREF option, you get a listing of the tables accessed by each procedure.)
Using the Upgrade Template
The
upgrade
template, all .p files it uses, and all .inp files it uses are only templates; you must check each file and modify it to suit your particular application. Following is a list of checks and modifications you must make before usingupgrade
; your application might require additional changes.The UNIX version of
upgrade
is found in/usr/dlctk/samples/unix
. The DOS version is located in the respective subdirectories ofsamples
. The files thatupgrade
uses can be found in/usr/dlctk/samples
.The
upgrade
template performs three basic actions to upgrade an application at the user’s site.Changes to the
upgrade
template for the data definition load stage (Step 1.):
- Modify
upgrade.p
(notupgrade
) and the files it uses:
- Set the system administrator id and password appropriately in
loginupg.p
(or prepare a tool your users can use to set them).- Modify
upgrade.inp
to name the new .df file.- Test
load_df.p
(a standard Progress Dictionary procedure). If you have created a new unique active index,load_df.p
asks whether you want to deactivate the index. You need to add a response (Y or N) toupgrade.inp
.- If you and your users do not freeze the database files, delete the call to
freeze.p
. (Leave the call tounfreeze.p
in case your users ever freeze the database files without your knowledge.) See the Progress Client Deployment Guide for more information about freezing and unfreezing files.- Modify
unfreeze.p
andfreeze.p
to include the correct filenames.- Check
upgrade.log
for any problems.Changes to the
upgrade
template for the rebuild deactivated indexes stage (Step 2.):
- If you and your users will not be deactivating indexes, remove the
_proutil
command line fromupgrade
.- If you have added a new unique active index, modify
rebuild.inp
to include the correct responses to prompts by_proutil $1 -C idxbuild
. That is, test_proutil idxbuild
on your database and add a line torebuild.inp
to answer each question appropriately.- Check
rebuild.log
for problems.- You might want to add a procedure to
upgrade
that checksrebuild.log
and, if necessary, fixes duplicate key data and rebuilds the index again. Alternatively, you might want to check the .log file and just stop before compilation proceeds.Changes to
upgrade
template for the compile encrypted procedures stage (Step 3.):
- Modify
compile.inp
to name the procedures to be compiled.- Modify the COMPILE statement in
compile.p
to use the encryption key you want.- Prepare to ship
compile.p
: either encryptcompile.p
, possibly with the default key, or compilecompile.p
, thereby hiding your encryption key in the .r file. If you shipcompile.r
, it must be compiled on the target machine type. It can be compiled against any database because it does not reference any database files.The
upgrade
template is relevant when you want to distribute only new data definitions and encrypted versions of affected application procedures. However, you might choose instead to ship a complete new version of the database and application, as described in the following section.
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |