Ingres Database Reference
Document #: US-13231,EN
------------------------------------------------------------------------------
Major subject: data_mgmt Minor subjects: datatypes_be
Keywords: copyapp, tech_notes
Abstract:
Use of the COPYAPP Utility: What is it's purpose and what
objects in an application does this utility copy. Equivalent
to Release 6 Technical Note #9 or Release 5 note #44.
Expert note:
Use of the COPYAPP Utility
==========================
Overview
--------
Copyapp is an INGRES utility that can be used to copy an application
from one database to another. This document will discuss the uses
and function of the Copyapp utility.
o The Purpose of Copyapp
o Parts of an ABF Application
o Forms
o Reports
o Graphs
o ABF/4GL Source Code
o QBF Join Definitions
o Embedded Query Language Procedures
o Existing Object Code - ING_ABFDIR issues
o Copying Objects That Copyapp Does Not
o Copying Forms Referenced by EQL procedures
o Copying Non-Compiled Forms
o Copying Objects Referenced by the ABF/4GL 'CALL' Statement
o Planning use of COPYAPP in Application Development
o Summary
The Purpose of Copyapp
----------------------
Copyapp Out copies database objects associated with a specific applica-
tion from the database to a text file. These objects are entities such
as forms, reports, graphs, source code and join definitions. Copyapp In
copies these database objects into the desired database.
If you wish to simply run an application imaged in one database against
the data in another database, you may use the -d flag. You can see a
further explanation of the -d flag in the section entitled "Running a
Completed Application" in the "INGRES ABF User's Guide".
Parts of an ABF Application
---------------------------
ABF applications can consist of forms, reports, graphs, 4GL source
code and Report Writer source code, QBF Join Definitions, and embedded
query language (EQL) procedures.
Forms
-----
Forms can be created and edited by accessing VIFRED directly or by
choosing the FormEdit operation within ABF. In each case, the form
definition is stored in the appropriate system catalog tables. Forms
stored in the INGRES system catalogs are known as non-compiled forms.
You can also write out 'compiled forms' which are written to a C or
macro language file and compiled into object code. These compiled forms
can be linked into an application's executable for much faster activa-
tion at run time. Compiled forms can be used in EQL applications or ABF
applications. Compiled forms, since they are linked into program execut-
ables, are not stored in the system catalogs. The ABF Application
Defaults frame contains options that tell ABF whether to use the form
definition stored in the system catalog or to generate the compiled
version of the form when the image is built. A form can also be compiled
in VIFRED and linked into the executable using ING_ABFOPT1( a logical
name on VMS systems, or an environment variable on UNIX systems).
Since Copyapp looks to the system catalogs for both application informa-
tion and form definitions, it will copy:
1. All forms referenced in any 4GL, QBF, or REPORT frame.
It will NOT copy:
1. Any forms (compiled or non-compiled) used in EQL procedures.
2. Any form referenced in a 4GL 'CALL "QBF"' statement.
Reports
-------
Reports may be created or edited by using the INGRES Report Writer
language or by using RBF. Selecting the save menuitem in RBF writes the
report out to the INGRES system catalogs as does running the the
'default report'. Unlike forms, there is no concept of a compiled
report.
Reports, like forms, are saved in the system catalogs. Deleting a
report writer source code file does not remove the report from the data-
base. Copyapp (by default) will not copy report writer source since it
is not required to run the application.
Copyapp will copy:
1. All reports referenced in any report frame.
It will NOT copy:
1. Any reports referenced by the 'CALL "REPORT"' 4GL command.
2. Any reports referenced by the 'CALL "SREPORT"' 4GL command.
3. Any reports referenced by the 'CALL "RBF"' 4GL command.
Graphs
------
Graphs, like reports and forms, are saved in the INGRES system catalogs.
Graphs are the simplest of the three groups because there are neither
compiled graphs nor graph source code.
Following the rules for reports and forms, you can see that Copyapp will
copy:
1. All graphs referenced in any VIGRAPH frame.
It will NOT copy
1. Any graphs referenced by the 4GL 'CALL "GRAPH"' statement.
ABF/4GL Source Code
-------------------
By default, Copyapp does not copy 4GL source code to a new location. You
may use the Copyapp with a -s flag to copy source code to the new loca-
tion. In the new database, all frames and procedures will be recompiled
during the first run or while imaging of the application, so you must
have the 4GL source code when running or imaging the application. This
recompile may be time-consuming. A way of avoiding recompilation is
discussed on the section entitled ING_ABFDIR issues. If the application
is transferred to a different machine then the 4GL source code will also
need to be transferred. It will not be included in the Copyapp Out temp-
orary file.
Report writer source code, by default, is not copied by Copyapp. Using
the -s flag on the command line will cause Report Writer source code to
be copied. You will still be able to run and/or image the application
without Report Writer source code, since the report specifications will
be copied from the system catalogs for all reports associated with
report frames.
Copyapp with the -s flag specified will copy the report writer source
code for:
1. All reports referenced in report frames.
It will NOT copy,
1. Any reports referenced in a 4GL 'CALL "REPORT"', 'CALL "RBF"', or
'CALL "SREPORT"' statement.
QBF Join Definitions
--------------------
QBF Join Definitions (joindefs) are specifications and rules for joining
two or more tables in QBF. Since they are stored in the system catalogs
the specifications for all joindefs referenced in QBF frames will be
copied.
Copyapp will copy:
1. All joindefs mentioned in QBF frames.
Copyapp will NOT copy:
1. Any joindefs referenced in the 4GL command 'CALL "QBF"'.
Embedded Query Language Procedures
----------------------------------
You will need the source code for EQL procedures if you want to run or
image the application in the new database. EQL source code will be
copied if the -s flag is specified on the Copyapp In command line.
Existing Object Code - ING_ABFDIR issues
----------------------------------------
The above section has discussed all the different parts of an Applica-
tions-By-Forms application. It is important to consider whether or not
it is worthwhile to copy (using your Operating System's copy command)
all the object code associated with the application. Copyapp makes no
attempt to copy existing object code because all frames and procedures
may be recompiled in the new area. However, for large applications, it
can save time and avoid complete recompilation by copying the object
code to the new area.
All object code needed for the successful linking of an ABF application
is kept by ABF in an area denoted ING_ABFDIR, which is a logical name on
VMS, and an environment variable on UNIX. The object code for a an
application in a database is kept in a subdirectory named after the
application within a subdirectory named after the database.
To avoid complete recompilation of all frames, forms, and procedures you
can copy the entire contents of an application's object code directory
to the new location. Object code is not transferrable across operating
systems.
If both source code (using -s) and object code are being copied, copy
the object code LAST. This ensures that the date on the object code is
the more recent.
Copying Objects That Copyapp Does Not
-------------------------------------
The first part of this note discussed which objects Copyapp does and
does not copy. This section will discuss how to locate and copy objects
that Copyapp does not. The conclusion of this note will give a brief
list of some rules that will ensure that the majority of your
applications can be copied using the Copyapp utility.
Copying Forms Referenced by EQL procedures
------------------------------------------
Application developers generally use non-compiled forms while developing
their EQL procedures so that they do not have to relink an entire appli-
cation to have the latest changes to a form in VIFRED reflected in the
image. In EQL, you use the 'forminit' statement to bring in a non-
compiled form from the system catalogs.
But, once an application developer is satisfied with the appearance of a
form used in an EQL procedure within an ABF application, he or she may
decide to use the compile version of the form in the application. This is
done by including the full path to the form's object file in a link options
file which is pointed to by using ING_ABFOPT1.
If the forms can be used as is in an image of the application and never
need to be changed using VIFRED, then all that must be done is to copy
the object files for all the forms referenced by the link options file
pointed to by ING_ABFOPT1. Different developers linking different
applications should be sure to point ING_ABFOPT1 at the appropriate
files for their application. If, however, the forms in the application
must be edited, then use the copyform command to copy those forms from
the old database to the new one.
Copying Non-Compiled Forms
--------------------------
If the application developers are still in the early phases of develop-
ment when you wish to copy the application, there would be a good chance
that any EQL procedures used will use non-compiled forms. There will be
no list of form names in the file pointed to by ING_ABFOPT1. In this
case, the solution is to search all procedures used in the application
for the 'forminit' statement, and then use copyform to manually copy
those forms from the old database to the new one.
Copying Objects Referenced by the ABF/4GL 'CALL' Statement
----------------------------------------------------------
As mentioned earlier in this note, Copyapp does not have the capacity to
scan 4GL code looking for 4GL 'CALL SUBSYSTEM' statements and then copy
the objects named in the 'call' statement's parameter list. Therefore,
in order to copy these objects one must use the Operating System's
search facility to locate all such statements. One can then copy the
required objects individually using various copy utilities like copyrep
and copyform.
Planning use of COPYAPP in Application Development
--------------------------------------------------
As noted earlier, Copyapp does not generally copy the following kinds of
objects:
1. Forms referenced in EQL procedures.
2. Any object (such as Joindef, Report or Graph) referenced with a 4GL
'CALL {SUBSYSTEM}' statement.
Keeping this in mind can make the Copyapp process much simpler.
In general, the use of Copyapp is simpler when you use callframe state-
ments instead of the 4GL call statement (e.g. CALLFRAME REPORTFRAME as
opposed to CALL "REPORT" ( REPORT = "MYREP" ) ).
However, it is hard to avoid the use of forms in EQL procedures, so you
must devise a way to ensure that all forms referenced by the procedures
will find their way into the new database. This process can be simpli-
fied by using only compiled forms and establishing naming conventions
for the link options files. Then, during Copyapp, you simply move all
the forms referenced in the link options file to the new database using
the copyform command.
Briefly, the rules to follow to make Copyapp use easy, are:
1. Use only compiled forms.
2. Establish a naming convention for link options files so needed
forms can be located quickly.
3. D
------------------------------------------------------------------------------
Ingres Database Reference
To William's Home Page
© William Yuan 2000
Email William