Installation at a Customer Site
When you are to build or upgrade a database off home ground, at a customer site or
elsewhere, you typically do not have access to SourceSafe. The way to handle
this in AbaPerls, is to perform the bulid/upgrade in two steps:
- First run at home with
-noexec -get, building a
directory structure with all
required files.
- Install at the remote disk with
-use_disk, so that AbaPerls reads the
structure created in the first step.
On this page, we look at this more in detail. For each step, I first cover
DBBUILD, then the update scripts generated by DBUPDGEN
and finally ABASQL.
Getting Files with -noexec -get
With DBBUILD
Here is an example command:
dbbuild -get -noexec -config customers/$/mycust/4.80/config.cfg -label 25
The working command-line switch here is -get, but you typically also specify
-noexec in this step, since you are not actually building any database.When you use -get, DBBUILD creates in two files in the current
directory,
SUBSYSTEMS.LIS and SS-FILES.LIS, together with one subdirectory
for each subsystem; the name of the directory coincide with the subsystem name. In
each subsystem directory there is an directory SQL which is the top directory of
an AbaPerls
SQL directory structure. DBBUILD
gets all files to their respective place in the SQL directory structure of the respective
subsystem.
SUBSYSTEMS.LIS includes the same information as the
config-file, but the format is different.
The format of SUBSYSEMS.LIS is internal for AbaPerls and may be changed in
future versions. The file includes the command-line switches you specified to
DBBUILD. Thus, if you say:
dbbuild -noexec -get -Macro &nisse=1289 -config ...
you do not need to repeat -Macro when you install at
the remote site.
If you specify -VSS to get files only for a single subsystem, you get a
SUBSYSTEMS.LIS in this case too. If you did not specify a name with -subsystem,
DBBUILD gets the files into an AbaPerls
SQL directory structure in
the directory NAMELESS.
SS-FILES.LIS holds SourceSafe information about the files that DBBUILD gets to disk.
AbaPerls uses this information when you install at the remote site to update the
table abasysobjects. In
SS-FILES.LIS there is also a checksum for each file, so if someone would change
the file while it is on disk, AbaPerls will disregard the SourceSafe
information, and in abasysobjects
it will appear as if the file had been loaded manually. Needless to say, the
format of SS-FILES.LIS is internal to AbaPerls, and may change in the future.
Note: DBBUILD does not delete any files or directories or files before it starts,
neither does it consider existing files. That is, if there
already are directories matching the subsystems, DBBUILD will write to these
directories, overwriting any files with the same name as those that are fetched
from SourceSafe. In the same vein,
DBBUILD overwrites any existing SUBSYSTEMS.LIS and SS-FILES.LIS.
With an update script generated dy DBUPDGEN
A sample command:
perl dbupdate-4.10.pl -get -noexec
When you run an update script with -get, you get the same
set of files and directories that you get with DBBUILD
with two differences:
- You only get SS-FILES.LIS.
- In each directory subsystem/SQL there is a directory OBSOLETE-FILES
which holds yet another AbaPerls SQL directory structure. This
one is for objects that are to be dropped from the database.
Just as DBBUILD, an update script will not delete any files before it starts,
nor save any. Thus files in subsystems directories will be retained and
overwritten, and any existing SS-FILES.LIS will be lost.
With ABASQL
A sample command (split on two lines for legibility)
abasql -noexec -get -VSS abasec/$/ababos/10.20/sql -label 3
-subsys ABABOS dsd_create_notes_sp.sp
ABASQL writes information about the
extracted files to SS-FILES.LIS. If the file already
exists, the information is appended to the file. (In difference to
DBBUILD and the update scripts that always
create a new file). This permits you to run multiple
ABASQL commands to extract several files,
possibly in different subsystems.
If the files you specify on the command line refers to other fles through
$INCLUDE or
$REQUIRE, they are extracted
too and informtion written SS-FILES.LIS.
The extracted files are put in an AbaPerls SQL
directory structure in the subdirectory subsystem/SQL.
If you want to include a file that is not checked in (because you need to
test), you can put it appropriate subdirectory to subsystem/SQL without
running ABASQL. You should not add it
to SS-FILES.LIS.
When you have extracted the files you need, you can zip the directory from
where you ran ABASQL and move this zip
archive to the customer site.
Installation
at the Remote Site
With DBBUILD
When you're off to the remote site, you bring the entire structure with you.
That is, SUBSYSTEMS.LIS, SS-FILES.LIS, and the directories for the
subsystems. A sample command:
dbbuild -S server -P pwd -d db
Once you have unpacked the files, you open a command window, and place
yourself in directory where you unpacked the structure. To build a new
database, or add a new subsystem, you run DBBUILD without specifying -config
or
-VSS. This implies -use_disk, which you can, but do not need to, specify.
When you build a database with DBBUILD, DBBUILD reads SUBSYSTEMS.LIS in the
current directory and builds the subsystems in the order they are listed and
with the configuration options
listed in the file. (You can choose to build only a single subsystem by specifying
-subsystem.) Recall that SUBSYSTEM.LIS also includes configurations options you
specified to DBBUILD when you ran with -noexec -get, so you do not need to
repeat them. (If you specify configuration options on the command line, you must
also specify -force if they conflict with the options in SUBSYSTEMS.LIS,
according to the precedence rules for configuration options.)
When DBBUILD retrieves a file to load into the database,
it gets information about the file from SS-FILES.LIS to save in
abasysobjects.
If a file is missing from
SS-FILES.LIS or its checksum does not agree with the file on
disk, you get a warning, but the file is nevertheless loaded, but DBBUILD will
not save the SourceSafe information about the file in
abasysobjects. If a file is listed in
SS-FILES.LIS, but is not on disk, DBBUILD will not even notice and even less
tell you. (Note however, this could be changed in a future version, so that
DBBUILD uses SS-FILES.LIS as its shopping list.)
When building a subsystem, DBBUILD changes the current directory to the top
directory for the AbaPerls SQL directory
structure for the subsystem, which thus is the current directory for the
AbaPerls file-lookup order during the build
of that subsystem.
The final result of this two-step exercise is that the database looks just as
if you had built it directly from SourceSafe in one step. That is, the you get
the same information in the AbaPerls system
tables in both cases.
With an update script generated by DBUPDGEN
Just like for DBBUILD, you bring the generated structure
of subsystem directories and
SS-FILES.LIS with you, and in the directory to which you unpacked the structure
you say something like:
perl dbupdate-4.10.pl -S server -P pwd -d db -noVSS
Since the update script has the SourceSafe options built-in, you need to specify
that they are not be used with -noVSS, and this also implies -use_disk.The
update script does not need SUBSYSTEMS.LIS, as which subsystems it updates is
contained within the script.
The script uses SS-FILES.LIS in the same manner as DBBUILD. That is, the
script uses the data to add SourceSafe information to
abasysobjects. If a file is
missing from SS-FILES.LIS, if there is a checksum mismatch, the script will
issue a warning, but still load the file.
Just like DBBUILD, the update scripts changes the current directory for each
subsystem, affecting the AbaPerls file-lookup
order.
With ABASQL
You run ABASQL in the directory
where you unpacked the files you extracted at home, including
SS-FILES.LIS. A typical command:
abasql -S server -P pwd -d db -subsys ABABOS dsd_create_notes_sp.sp
That is, you don't have to specify that you want ABASQL to
read from SS-FILES.LIS, since if
ABASQL finds this file, it will automatically
read it, and add the SourceSafe information about the file to
abasysobjects.
If the file you specify on the command line is not listed in
SS-FILES.LIS, this is the same as if you load a file directly
from disk at home, and ABASQL will load
the file if this complies with the rules
for production and test databases.Keep in mind that the file must be in the
structure below subsystem/SQL and not in the directory where you run
ABASQL.
If the file is listed in SS-FILES.LIS but there
is a checksum mismatch (because you tampered with the file after you extracted
it?), this will also count as a load from disk, and not a load from SourceSafe,
and this may fail if the rules for
production and test databases are violated.
If the remote site does not have AbaPerls?
Then you install it. And if Perl is not there, you install it too. Very old
versions of AbaPerls permitted you to create an SQL script at home to bring to
the remote site, but this feature has been removed. You can still get an SQL
script with -save, but this script will be specific for the database you run it
against, and is mainly intended as a debug aid. If you try to use such a script
at another database, you may cause a mess, because the databases are not equally
configured. In other words: such usage is unsupported and strongly deprecated.