Installation at a Customer Site

When build or upgrade a database off home ground, at a customer site or elsewhere, you typically do not have access to your version-control system. The way to handle this in AbaPerls, is to perform the build/upgrade in two steps:
  1. First run at home with ‑noexec ‑get, extracting information from the version-control system to build a directory structure with all required files.
  2. Install at the remote site with ‑use_disk, so that AbaPerls reads the structure created in the first step. The final result is the same as if the files had been loaded directly from the version-control system.

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.

Contents:
   Getting Files with ‑noexec ‑get
      With DBBUILD
      With an update script generated by DBUPDGEN
      With ABASQL
      General Comment on ‑get
   Installation at the Remote Site
      With DBBUILD
      With an update script generated by DBUPDGEN
      With ABASQL
   Notes on Format of SS‑FILES.LIS and SUBSYSTEM.LIS
   If the remote site does not have AbaPerls?

Getting Files with ‑noexec ‑get

With DBBUILD

Here is an example command:

dbbuild -get -noexec -config TFSSRV/MyCollection/$/mycust/4.80/config.cfg -label 2562
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 coincides with the subsystem name. In each subsystem directory there is a 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 SUBSYSTEMS.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 ‑VC 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 version-control 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 (currently computed as an MD5 hash) for each file, so if someone would change the file while it is on disk, AbaPerls will disregard the version-control information, and it will appear as if the file had been loaded manually in abasysobjects. 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 version-control. In the same vein, DBBUILD overwrites any existing SUBSYSTEMS.LIS and SS‑FILES.LIS.

With an update script generated by 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:

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 -VC 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 replaces any existing 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 files through $INCLUDE or $REQUIRE, these files are extracted as well and information about them is included in 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 it), you can put it in the 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.

General Comment on ‑get

You should take care when you run ‑get that you current directory is outside any AbaPerls directory structure. That is, the path to your current directory should not include any components that are special to AbaPerls: SQL, Message, Type, Assemblies, Tbl, ServiceBroker, SP, Functions, Include, View or Scripts as this could lead to confusing results. If you use TFS and AbaPerls can map your current Windows directory to a directory in TFS, AbaPerls will not permit you to use ‑get.

The same applies when you install from a structure created with ‑noexec ‑get.

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. You make the files available at the remote site and open a command window in the top directory of the structure, that is the directory were SUBSYSTEMS.LIS and SS‑FILES.LIS reside. To build a new database, or add a new subsystem, you run DBBUILD without specifying ‑config or ‑VC. This implies ‑use_disk, which you can, but do not need to, specify. A sample command:

dbbuild -S server -P pwd -d db 

When you build a database, 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 SUBSYSTEMS.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 building a subsystem, DBBUILD scans the directories for that subsystem and loads all files it finds in each directory. It looks up the version-control information about each file in SS‑FILES.LIS and saves this information in abasysobjects. If a file is missing from SS‑FILES.LIS or its checksum does not agree with the checksum for the file on disk, you get a warning. The file is nevertheless loaded, but DBBUILD does not save any version-control information about the file in abasysobjects. Beware that DBBUILD does not check whether a file listed in SS‑FILES.LIS is missing from disk.

The final result of this two-step exercise is that the database looks just as if you had built it directly from version-control in a single step. That is, 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 -noVC
Since the update script has the version-control options built-in, you need to specify that they should not be used with ‑noVC. This option 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 version-control information to abasysobjects. If a file is missing from SS‑FILES.LIS or if there is a checksum mismatch, the script will issue a warning, but still load the file.

The update script changes the current directory for each subsystem, affecting the AbaPerls file-lookup order. Thus, if you for some reason want to override a file with some manual tweak, you must put it the appropriate directory for the subsystem. If you place it in the top-level directory, the update script will not see it.

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

ABASQL detects the presence of SS‑FILES.LIS and reads the information and adds the version-control information about the file to abasysobjects. When SS‑FILES.LIS is present, you must specify the subsystem with ‑subsystem.

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. The file must be in the structure below subsystem\SQL and not in the directory where you run ABASQL, since ABASQL changes the current directory to subsystem\SQL when SS‑FILES.LIS is present.

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 version control, and this may fail if the rules for production and test databases are violated.

Notes on Format of SS‑FILES.LIS and SUBSYSTEM.LIS

You may not always use the same version of AbaPerls to generate the files SS‑FILES.LIS and SUBSYSTEMS.LIS. When new features are added to AbaPerls, the format of these files may change. The header of these files includes a version number. When AbaPerls reads such a file, it verifies that the file is of a version that it is able to cope with. Typically, AbaPerls is able to read the current version of the format as well a couple of older versions of the format. However, a certain version of AbaPerls is not able to formats generated by  later version of AbaPerls. That is, if you have generated SS‑FILES.LIS and SUBSYSTEMS.LIS at home with a new version of AbaPerls, and the customer site has an older version, you need to install new version of the AbaPerls client at the customer site.

If the files does not match the format supported by the current version of AbaPerls, you will get an error message saying so. However, version before 1.0.0250 of AbaPerls did not perform any version checks of the files, and will read the newer formats, naïvely believing that it understands them. The new formats introduced in 1.0.0250 were designed so that at least the most recent versions of AbaPerls would interpret them correctly, but beware!

When you use ABASQL to append files to an existing SS‑FILES.LIS, the version of the format must match exactly.

The current version of the format for SS‑FILES.LIS is 1.1 and for SUBSYSTEM.LIS the version is 1.3. The versions 1.0 and 1.2 respectively are also supported.

If the remote site does not have AbaPerls?

Then you install it. And if Perl is not there, you install it too.

Sometimes, people get the idea to run a script at home with ‑save and use the generated SQL script. However, this option is intended for debugging purposes only, and any other usage of the generated files is entirely unsupported. The generated SQL depends on the configuration options and other settings in the database, why a file you generate at home may be different from the SQL AbaPerls would generate at the customer site.

Furthermore, AbaPerls includes a DDL trigger, which does not permit modification of objects loaded with AbaPerls through other tools than AbaPerls itself. Occasionally, however, you may need to fix a stored procedure directly in a live environment to resolve a critical problem on the spot, and you are logged to a machine where AbaPerls is not installed. In this case you will need to bypass the DDL trigger. The proper way to do this is as in this example:

BEGIN TRANSACTION

CREATE TABLE #abaperls(objname sysname)

INSERT #abaperls(objname) VALUES ('mqf_file_send_msg_to_file_sp')
go
ALTER PROCEDURE mqf_file_send_msg_to_file_sp AS 
   -- Procedure body goes here
go
DROP TABLE #abaperls

COMMIT TRANSACTION

That is, you start a transaction, create a temp table with the name #abaperls and with a column objname, and then you insert the name(s) of the object(s) you want to alter. Then you drop the temp table and commit the transaction. And, yes, the temp table must really be created inside the transaction. (The scheme is designed to permit a loophole, but which is cumbersome enough to discourage you to use it as a matter of routine.)

When you bypass the DDL trigger in this way, the action is logged in the table abaddltribypasslog. See the documentation for this table for further details.