DBBUILD

DBBUILD adds one or more subsystems to a database, working from the AbaPerls SQL directory structure in version-control or on disk. When building from disk, the structure is often created by a previous invocation of DBBUILD with ‑noexec ‑get, as part of the two-step operation for installation at a customer site. You can also use DBBUILD to rebuild one or more subsystems already present in the database, by means of the ‑rebuild switch.

To get an overview of the process where DBBUILD fits in, see the page Life-cycle of a database.

Contents:
   Command-Line Syntax
   How DBBUILD Builds the Database
   Loading Stored Procedures
   Using the ‑rebuild and ‑restruct options
      Specifics for ‑rebuild
      Specifics for ‑restruct
   Loading BCP Files
   Output from DBBUILD
   Current Directory when Building
   abainstallinfo

Command-Line Syntax

dbbuild { -database db [-Server server] [-User user] [-Password pwd]
[-save file] [-tablesfirst]}
[-rebuild | -restruct] [-bcp [directory]] [-[no]insert]
[-revokeall]
| -noexec }
[-config config-file | -VC VC-path] [-subsystem subsys]
[-label version] [-get | -use_disk]
[-force] [-log file]
[-[no]crypt] [-site site-id:s] [-[no]quoterepl] [-Macro &macro=value [...]] [-undef &macro [...]]
[-environment DEV | TEST | PROD]

Thus, you must specify one of ‑database and ‑noexec, but you cannot specify both.

Database switches
‑database Name of the database to build. Prior to invoking DBBUILD, you must have created the database with CREATE DATABASE. The database may be empty or contain one or more subsystems since previous builds.
‑Server The server where the database resides. If you do not specify ‑Server, the local server is the default. The environment variable ABAPERLS_CTIMEOUT determines how log to wait for a connection. The default is 5 seconds.
   Note that if you specify the server instance by port number, you must enclose the server specification in quotes, for instance ‑S "127.0.0.1,2093".
‑User
‑Password
Which login and password to use with SQL authentication. If you leave out both username and password, AbaPerls uses Windows authentication. If you specify ‑password only, AbaPerls will log in as sa. It's illegal to specify a user without a password. If you have a blank password, you need to change this before you can use AbaPerls.
   No matter if you use SQL authentication or Windows authentication, the login you use must map to a database user with dbo as the default schema, or AbaPerls will not let you proceed. Obviously, the user needs permission to perform all actions implied by AbaPerls and the files you load.
‑save Use this option to save the generated SQL code to file in case you wish to review it. If you do not provide a file extension, DBBUILD adds .sql. By default, DBBUILD does not save any file.
   Do not use the saved SQL code to build another database, but always build your databases directly with DBBUILD. Two executions of DBBUILD typically generates different SQL code depending configuration options, whether other subsystems are present in the database, the version of SQL Server etc.
‑noexec Specifies that DBBUILD is to get the files and run them through Preppis to get all required include files and compile C# and VB files, but not proceed with further steps in the AbaPerls file-loading process. You typically use ‑noexec together with ‑get to create kits for installation at customer sites.
   When you specify ‑noexec, you cannot specify any of ‑database, ‑Server, ‑Password, ‑save, ‑rebuild, ‑restruct, ‑tablesfirst, ‑bcp, ‑insert or ‑noinsert.
Version-control Options
‑config

Instructs DBBUILD to build the database from the config-file you have specified. DBBUILD tacks on /sql on the directory specifications in the config-file and emits a warning for the entries in the config-file that do not have any SQL directory.
   If there is no subsystem in the database, DBBUILD will use the configuration options in the config-file both on database level and on subsystem level. If there already is a subsystem in the database, DBBUILD will obey the options saved in the database for the database level, and ignore the database-level options in the config-file. DBBUILD will apply the configuration options in the config-file for the subsystem(s) that it adds.
   If the config-file includes a subsystem which is already present in the database, DBBUILD skips this subsystem, unless you specify ‑rebuild.
   If there is a subsystem in the config-file that does not have an sql directory, DBBUILD skips this subsystem. On the other hand, if there is an sql directory, but no files in it, DBBUILD adds the subsystem as empty.
   If the database is a production database, as specified by the configuration option ‑environment, any explicit version specifications in the config-file must be labels on the standard AbaPerls Format.

‑VC

A VC-path to an AbaPerls SQL directory structure to build a single subsystem from. If the path does not end in /sql, DBBUILD will add it.
   If you do not specify any of ‑VC or ‑config, but DBBUILD is able to map your current Windows directory to a directory in TFS, this implicitly sets the ‑VC option.

‑subsystem When you build a single subsystem with ‑VC, ‑subsystem specifies the name of the subsystem. If you leave out ‑subsystem, AbaPerls attempts maps VC-path to a subsystem through the system-definition file to set the name. If no mapping exists, the subsystem name is NAMELESS. However, this name is only permitted when there are no other subsystems in the database.
  If you specify a subsystem that does not exist in the sysdef-file (if there is any), this is an error, except when you also specify the option ‑rebuild. (When you add a subsystem you are required to respect the sysdef-file, but an existing database may use a legacy name.)
   You can also use ‑subsystem with ‑config to restrict the build to this single subsystem.
‑label

Which version of the config-file or the VC-path that DBBUILD should read from. When you use ‑config, version specifies of the config-file to use and you can specify a date, label or an explicit version number of the config-file. AbaPerls then determines which version to use of each subsystem from the config-file as described on the config-file page.
   When you specify a single subsystem with ‑VC, ‑label specifies which version of VC-path to use. You can specify an explicit label or a date. If you leave out ‑label, DBBUILD will use the most recently checked-in version of all files in the subsystem. Note that if the database is a production or test database as defined by the configuration option ‑environment, you must specify a label on the standard AbaPerls format LetterMajor.Middle.Minor.
    Whether version interpreted as a date, label or a version number depends on the version-control system.

‑get With ‑get, DBBUILD creates a directory for each subsystem it builds. In each subsystem directory, DBBUILD gets the files and places them in an AbaPerls SQL directory structure. DBBUILD also creates the files SUBSYSTEMS.LIS and SS‑FILES.LIS with version-control information about the subsystems and the retrieved files.
   You typically use ‑get together with ‑noexec to create kits for installation at customer sites.
   You cannot use ‑get together with ‑use_disk. If you specify ‑get, you must also specify ‑config or ‑VC. When you use ‑get, DBBUILD does not permit that your current Windows directory maps to a TFS directory.
‑use_disk When you specify ‑VC or ‑config, DBBUILD reads only from version-control. You can override this with ‑use_disk to instruct DBBUILD to first look for files on disk according to the AbaPerls file-lookup order.  However, this does not apply to subsystems for which a label is specified explicitly or implicit from a config-file. That is, it only applies when you are building the latest version of a subsystem. If you specify ‑use_disk, but labels are present for all subsystems, you will get an error message.
   When you specify neither of ‑VC or ‑config, this implies ‑use_disk. You typically use this to build from a disk structure created with ‑get. In this case there is a file SUBSYSTEMS.LIS that DBBUILD uses to determine which files to load, as described on the page installation at a customer site.
Rebuild options
‑rebuild

Reloads all the objects in one more existing subsystem in a database, maintaining the current subsystem structure. See further the section Using the -rebuild and -restruct options below. You cannot combine ‑rebuild with ‑noexec, ‑restruct or ‑bcp.

‑restruct

Flushes all data in several of the AbaPerls system tables, and then builds the database as it if was a new database, thus permitting you implement a major change of your subsystem structure. See further the section Using the -rebuild and -restruct options below. You cannot combine ‑restruct with ‑noexec, ‑VC, ‑subsystem, ‑rebuild or ‑bcp. When you use ‑restruct, you must always use a config-file with all subsystems in the database.
    The ‑restruct option requires that the ABAPERLS subsystem is installed in the database and is at least at version L1.0.0270.

‑revokeall

This option can only be used together with one of ‑rebuild or ‑restruct. This option instructs DBBUILD to revoke all permissions granted to objects in abasysobjects. This includes any permissions granted outside AbaPerls, as AbaPerls does not track which permissions it has granted through grant.template. Note that AbaPerls only revokes permissions granted directly on the objects. Permissions granted on database or schema level will not be revoked, nor membership in roles like db_datareader.
   Use this option when you have made changes to one or more grant.template files to restrict permissions. When you specify ‑subsystem, AbaPerls only revokes permissions to objects in that subsystem.
    The ‑revokeall option requires that the ABAPERLS subsystem is installed in the database and is at least at version L1.0.0270.

Miscellaneous
‑bcp Instructs DBBUILD to load BCP files from the specified directory. If you specify ‑bcp without any directory, DBBUILD will read the BCP files from the current directory. See further the section Loading BCP files about the format of the BCP files etc.
   For the subsystem ABAPERLS, DBBUILD ignores ‑bcp, but always loads the INSERT-files for ABAPERLS.
   You cannot specify ‑bcp with ‑noexec or ‑rebuild.
‑[no]insert Whether DBBUILD should load INSERT-files or not. If you do not specify ‑insert, the default depends on the ‑bcp switch. If you specify neither ‑insert, nor ‑bcp, DBBUILD will load INSERT-files, and you need to specify ‑noinsert if you for some reason do not want to load such files. If you specify ‑bcp but not ‑insert, DBBUILD will not load INSERT-files. Thus, if you want to load both BCP files and INSERT-files, you must specify ‑insert. (The INSERT-files are loaded after the BCP files, see below.)
   For the subsystem ABAPERLS, DBBUILD ignores the setting of ‑insert, and always loads the INSERT-files for this subsystem.
‑log Name of log file for the build. If you do not specify ‑log, DBBUILD writes the log for the build to db.log. See below about the contents of the log file. Normally, DBBUILD overwrites an existing file, but if you prepend ++ to the file name, DBBUILD appends to an existing log. If you specify only ++, DBBUILD appends to db.log.
‑force Specifies that if there is a conflict between the configuration options in the config-file or those saved in the database, and the configuration options on the command-line, the command-line takes precedence. If you do not specify ‑force, and there is a conflict, DBBUILD will abort with an error message, and no file will be loaded.
   Only use ‑force when you really need to override the configuration saved in the database.
‑tablesfirst Instructs DBBUILD to use a build order, where all table and view definitions are loaded before any functions or stored procedures. This is useful if you find that you in practice refer to tables in higher subsystems in lower subsystems. (Something you probably should avoid.) For the exact details, see the section How DBBUILD builds the database below.
   You cannot specify ‑tablesfirst with ‑noexec.
Configuration options
‑crypt
‑environment
‑Macro
‑quoterepl
‑site
‑undef
These switches are configuration options. The setting of a configuration option is primarily taken from the config-file or the database according to the precedence rules for configuration options. If the config-file/database defines a setting for an option and you specify a different setting on the command-line, you must use ‑force to override.

How DBBUILD Builds the Database

DBBUILD first determines which subsystems to build:

For each subsystem, DBBUILD determines which files to load in one of these ways:

Having determined the list of files to load, DBBUILD proceeds to load the files in the order below. For all directories listed, the traversal includes subdirectories, save for BCP files.

  1. A START row is written to the table abainstallhistory, or if does not exist to abainstallinfo (created if needed).
  2. DBBUILD loads .sql files in the MESSAGE directory. (General SQL files for creating users, Service Broker queues etc.)
  3. DBBUILD loads .syno files in the MESSAGE directory. (Synonyms.)
  4. DBBUILD loads .assem files in the ASSEMBLIES directory. (CLR assemblies.)
  5. DBBUILD loads .xmlsc files in the TYPE directory. (XML Schema Collections)
  6. DBBUILD loads .mty files in the SERVICEBROKER directory. (Service Broker message types.)
  7. DBBUILD loads .sb files in the SERVICEBROKER directory for the first time, with CREATE QUEUE commands altered to leave out activation.
  8. DBBUILD loads .typ files in the TYPE directory. (User-defined types)
  9. DBBUILD loads .tbltyp files in the TYPE directory. (Table types)
  10. DBBUILD loads .tbl files in the TBL directory. (Table definitions.)
  11. DBBUILD loads .view files in the VIEW directory. (View definitions.)
  12. DBBUILD loads .sqlfun files in the FUNCTIONS directory. (User-defined functions of all kinds.)
  13. DBBUILD loads .sp files in SP directory. (Stored procedures.)
  14. DBBUILD loads .tri files the TBL directory. (Triggers on tables.)
  15. DBBUILD loads .vtri files in the VIEW. (Triggers on views.)
  16. DBBUILD loads .sb files in the SERVICEBROKER directory a second time, now without changing CREATE QUEUE commands.
  17. If you specified ‑bcp, DBBUILD loads BCP files as detailed under loading BCP files, below. (Not for ABAPERLS).
  18. If you specified ‑insert (which is the default unless you specified ‑bcp) or the subsystem is ABAPERLS, DBBUILD loads .ins files in the TBL directory. (INSERT-files.)
  19. DBBUILD loads .ix files in the TBL directory. (Indexes and statistics on tables.)
  20. DBBUILD loads .vix files in the VIEW directory. (Index and statistics on views.)
  21. DBBUILD loads .fkey files in the TBL directory. (Foreign-key definitions.)
  22. DBBULID loads .ddltri files in the MESSAGE directory. (DDL triggers.)
  23. DBBUILD loads .postsql files in the MESSAGE directory. (Final general SQL scripts.)
  24. DBBUILD saves configuration options on database level.
  25. DBBUILD saves configuration options for the subsystem.
  26. DBBUILD writes a STOP row to abainstallhistory or abainstallinfo.

Within each group, the load order follows the sort order defined by the Windows regional settings on system level. (That is, if you as a user have Swedish regional settings, but the default setting on the machine is US-English, then DBBUILD will sort according to US-English. It's Perl that works this way, and AbaPerls can't but comply.) There are however a few deviations:

When you specify the switch ‑tablesfirst, DBBUILD traverses the subsystem in two rounds, and in the first round DBBUILD performs steps 1-11 and 24-26 only, and in the second round, DBBUILD performs only the steps 1, 12-26 only. (For the ABAPERLS subsystem, all steps are performed in the first round.)

Occasionally, you may find that you have dependencies that go against the load order. For instance, a function may call another function which comes later alphabetically. Or you may have a view that refers to a user-defined function. In this case, use $REQUIRE to force the referenced object to be loaded first. However, $REQUIRE is not always permitted. If you get the idea to use a scalar UDF in a CHECK constraint in a .tbl file, you will find that AbaPerls does not permit $REQUIRE in .tbl files. For a good reason: having UDF in constraints is rarely a good idea. If you are dead set on it, you can put your constraint in the .fkey file. But it may better to put the check in a trigger. For dependencies between stored procedures, see the next section.

Loading Stored Procedures

Because of the sheer volume, it would not really be practical if you had to use $REQUIRE to control the load order for stored procedures. AbaPerls therefore employs a special strategy for stored procedures. When loading the procedures in a subsystem, AbaPerls first looks through the list of files and buffer all names. (Recall that AbaPerls requires the file name to match the procedure name.) AbaPerls then loads the files in alphabetic order. If AbaPerls finds that a stored procedure (the caller) calls a procedure (the callee) buffered, but not loaded yet, AbaPerls requeues the caller and loads it a second time when all procedures have been loaded. This has two benefits:

Currently, a call to a non-existing stored procedure is never an error with DBBUILD, but a callee could be missing for more than one reason:

What is said above, applies also to calls to stored procedures from triggers.

Using the ‑rebuild and ‑restruct options

These two options are the same time both quite similar and quite different. Both reloads all objects in the database and replaces the current set of configuration options. There are several reasons why you may want to do this:

When you specify ‑rebuild or ‑restruct, DBBUILD takes all configuration options from the config-file and replaces those already present in the database. The options in the database are discarded.

If you specify ‑rebuild together with ‑subsystem to rebuild a single subsystem, DBBUILD retains the database-wide settings in the database and only discards the settings for the specified subsystem. Settings for other subsystems and database-wide settings are left untouched. When you use ‑restruct, you cannot specify ‑subsystem; ‑restruct always operates on the entire database.

To rebuild or restructure a database at a customer site, you should first run with ‑noexec ‑get at home, and then use ‑rebuild or ‑restruct at the customer site, possibly in combination with ‑revokeall.

Specifics for ‑rebuild

When you use ‑rebuild, all subsystems you specify in the config-file or on the command-line with ‑subsystem must already exist in the database; you cannot add a subsystem with ‑rebuild. However, you are not required to rebuild all subsystems, but you can rebuild a subset of the subsystems in the database.

DBBUILD ‑rebuild is intended to refresh a database at its current version; it is not intended for version upgrades. That is, if the current label for subsystem ABC is L8.10.1040, you must rebuild ABC from label L8.10.1040. This is an occasion where it makes sense put explicit labels in your config-file. If there is a label listed for the subsystem in the table abasubsystems, DBBUILD will not accept attempts to rebuild the subsystem from a different label. If there is no label information in abasubsystems, DBBUILD will permit anything, and it is your responsibility to ensure that you rebuild from the correct version.

Why must the versions match? One reason is that DBBUILD ‑rebuild does not remove objects, so if you have version L8.10.1040 and move to L8.10.1500 you may be left with stored procedures that no longer should be there. (Which is bad in a development or a test database, if the production database reaches L8.10.1500 on a different path, and there are calls to these dropped procedures.) Another reason is objects that cannot be changed easily: types and tables. If you have at least version L1.0.0270 of the ABAPERLS system, AbaPerls will attempt to use ALTER TABLE when you load a .tbl file and the definition in the file does not match the database. However, there are many reasons why this will not work out, so it is precarious to count on it. The main reason for the check is to certify that the database agrees with version control.

Normally, DBBUILD ‑rebuild reloads all objects, but there is one exception: if the database is labelled as a production database, and the object in the database has a higher version number than the version number in version control, DBBUILD skips this file, since the later version could be a hotfix or similar. This does not apply to test or development databases, since for these databases you may want a database that aligns exactly with version control (and what you plan to ship to production).

If the ABAPERLS subsystem is not present in the database, or the version of the ABAPERLS subsystem is earlier than L1.0.0270, DBBUILD ‑rebuild skips the steps 5, 7, 8 and 9 in the list above, and thus does not load XML schema collections, user-defined types, table types or tables, since it is not possible to load these objects if the objects are in use. With L1.0.0270, AbaPerls added stored procedures to compare the new definition with the current, permitting you to verify that table and types agree with version control.

Specifics for ‑restruct

‑restruct is intended for all situations when you want to change the subsystem structure in the database. It could be that you have moved a large number of objects from one subsystem to another, or that you want delete one or more subsystems from the database (for instance because you take copy a test database targeted for one customer to be used for a different customer). A specific scenario which fits in here is when you move your source code from SourceSafe to TFS.

To use DBBUILD ‑restruct, version L1.0.0270 or later of the ABAPERLS subsystem must be present in the database.

‑restruct always operates on the entire database except for the ABAPERLS subsystem. You can't use the ‑VC or ‑subsystem options with ‑restruct, but you must use the ‑config option when you build from version-control. When you create a structure for installation at a remote site with ‑noexec ‑get, you must include all subsystems you intend to have in the new database. DBBUILD ‑restruct never touches the ABAPERLS subsystem. If the ABAPERLS subsystem is present in the config-file, DBBUILD silently ignores it.

DBBUILD ‑restruct adds a couple of preparatory and finalising steps to the build order above. These are the preparatory steps. (To keep it simple I say All although this really means All except the ABAPERLS subsystem.)

  1. If you specified ‑revokeall, DBBUILD removes all permissions as detailed above.
  2. All triggers, synonyms and Service Broker objects that are listed in abasysobjects are dropped from the database, and the deletion is logged in the same way as the file had been deleted in an update script.
  3. All signatures, certificates and users created from the $DBPERM and $SERVERPERM macros are removed and dropped. Note that certificates and logins in the master database are only dropped if you are logged as a member of sysadmin. See the topic Modules with Special Permissions for more details.
  4. DBBUILD writes a row to abahistsysobjects for all objects that remains in abasysobjects after the first step. In the scriptname column the value is DBBUILD ‑restruct (pre).
  5. DBBUILD writes a REMOVE row to abainstallhistory for all subsystems.
  6. DBBUILD deletes all rows in the tables abasysobjects, abaspecialperms, abasubsystems, abasslabels, and abaconfigsettings.

After these steps, the AbaPerls system tables looks just like they would after an initial DBBUILD has completed building the ABAPERLS subsystem, except that the history of the old structure is reflected in abainstallhistory and abahistsysobjects.

Note that if a .tbl fails to load during the rebuild, all child objects for the table – triggers, indexes, foreign keys and insert-files – will also fail to load. The table is still there in the database, but since the table is not present in abasysobjects, AbaPerls cannot add the children to abasysobjects, because of a foreign-key constraint. Stored procedures, functions and views that refer to the table will still load, as long as they are not dependent on the changes in the .tbl file. Keep in mind that as long as you have version 12 of the table in the database and DBBUILD ‑restruct loads version 12 of the file, the load should never fail. If you get an error in this case, this indicates that someone has tampered with table outside of AbaPerls.

When DBBUILD ‑restruct has completed building all subsystems, it retrieves all objects that exist in the database and do not appear in abasysobjects but exists in abahistsysobjects with the most recent row reading isdeletion = 1. That is, these are the objects removed from abasysobjects in steps 4 and 6 above but that were not reloaded by DBBUILD ‑restruct. DBBUILD drops these objects one by one (so that any errors can easily be identified with LISTERRS), and an extra deletion row is written to abahistsysobjects. On this row, the scriptname column will read DBBUILD ‑restruct (post) and the filename column will hold the DROP command. A couple of things to observe here:

DBBUILD ‑restruct performs no checks on labels, so in theory you could use DBBUILD ‑restruct to take your database from L4.20.0010 to L10.30.0450 – or in the reverse direction. However, the chances that you will able to do this successfully are slim. The sore points are types and tables. If a file fails to load during the build, it will not be recorded in abasysobjects, which means that AbaPerls will not have correct information about the objects. For an occasional stored procedure this may be OK, but things quickly get out of hand if you have a couple of types or tables that fail to load.

For this reason, you should plan your ‑restruct operation carefully and make sure that you run the build from labels that are in sync with the labels in the current structure. Particularly, you should make sure that there are no differences in type or table definitions. You should also be careful to take a backup of the database. When you run the restruct on a production database, you should first test the operation on a copy of the database so you know that it works out.

Even if you have all labels in sync, you may still run into errors with .sql, .postsql and .ins files if they are not written so that they can be run more than once. For instance, an .ins file may perform an INSERT without any preceding IF EXISTS. This applies to DBBUILD ‑rebuild as well, but when you use ‑rebuild you can discard the error; since the entry in abasysobjects is retained, there is no real harm.

Loading BCP Files

If you specify a directory as argument to ‑bcp, DBBUILD reads BCP files from the that directory. If you specify ‑bcp without an argument, DBBUILD reads all BCP files from the current directory. In neither case subdirectories are considered. That is, all BCP files should be in one place. This is advantageous when you want to rebuild and reload a database from scripts entirely, for instance because you want to change the collation or you need to migrate from a corrupted database. You can bulk out all data into one place with DOBCP and do not need to sort the files per subsystem.

Note that AbaPerls system tables are never loaded through BCP, but they will be repopulated with the objects and subsystems that are included in the build.

The files should be named table.bcp. DBBUILD attempts to load non-empty files named *.bcp that fits with the tables in the current subsystem. Empty BCP-files are merely noted in the build log.

DBBUILD determines the format of the BCP files in this way:

  1. If there is a tbl.fmt, DBUILD will use this file as a format file. (Typically this file would have been generated by DOBCP).
  2. If DBBUILD can find the string @!@ on the first line or the string <-> on the second line, DBBUILD will assume these command-line switches for BCP: ‑c ‑t@!@ ‑r"\n<->\n". (This is the character format used by DOBCP.)
  3. If neither applies, DBBUILD assumes native format, that is, the ‑n option to BCP.

Note that DBBUILD is not able to detect whether a BCP file was generated with the ‑unicode option with DOBCP, but you must always use format files in this case.

Overall, the use of format files is recommended. For instance, if you move data from one collation to another and use native format, you need to use format files to describe the BCP files correctly. (Note that sql_variant columns will retain their collation, since for them the collation is part of the data.)

DBBUILD runs BCP with a batch size of 1000, and uses the ‑E switch if required to maintain IDENTITY values.

DBBUILD runs BCP with the option ‑h "CHECK_CONSTRAINTS", meaning that all constraints for the table are checked when the data is loaded. Typically foreign keys will not be present when BCP runs, as DBBUILD loads them later. On the other hand, CHECK constraints are present if they appear in the .tbl file (which is the normal thing). If DBBUILD would load the files without constraint checks, SQL Server would mark the constraints as "not trusted", and the optimiser would not ignore the constraints when building query plans, which in some cases can lead to less efficient plans.

There is one exception to this: if there are types with the name ending in _upduser, DBBUILD assumes that for each such type there is a rule bound to it that requires the value to be equal to SYSTEM_USER or similar. DBBUILD unbinds these rules prior to bulk-loading, assuming that then name of the rules is the type name with _rule tacked on to it. When DBBUILD has finished bulk-loading the subsystem, it rebinds the rules. If you use some other mechanism, for instance a constraint to enforce the value of an auditing column, I'm afraid that it's not going to work with DBBUILD.

Note: while AbaPerls generally supports the full use of Unicode in file names, this does not apply to BCP files, since AbaPerls invokes Windows Command Line which is not Unicode-aware.

Output from DBBUILD

DBBUILD produces two forms of output: it prints to the command-line window, and it produces a log file.

The output to the command-line window only serves the purpose of giving progress information. There is no need to monitor this output.

On the other hand, it is essential that you check the log file, because if a file produces errors when DBBUILD loads it, the errors are written to the log only. The log file includes a full list of files that DBBUILD has loaded.

First in the log file you find a header which reports the user that ran DBBUILD, when he did it and with which command-line options. For each subsystem, there is a header with the configuration options that DBBUILD used for that subsystem. DBBUILD reports only the configuration options that somehow were set explicitly. That is, they were specified in the config-file or on the command-line or read from the database. DBBUILD does not report options set to their default values.

For a database with a reasonable number of tables, the log becomes huge and tedious to read directly. To this end there is the command LISTERRS that extracts the interesting messages from the log as well as the header information.

Note: Messages from Perl itself will be printed to the command-line window only. Ideally such messages should not occur, and if they do, it could be construed to be a bug in AbaPerls (or Perl itself). Some warnings like wide character in output are fairly innocent and can be ignored..

Current Directory when Building

You can build a database from files on disk, from version-control or a combination both. Essentially there are four scenarios:

  1. From version-control only.
  2. From version-control, but letting local disk files override with ‑use_disk.
  3. From disk only.
  4. From disk from a structure previously created with ‑noexec ‑get.

When you build from version-control only, your current directory does not matter. (Save for BCP files if you did not specify an argument to ‑bcp.)

When you want to override version-control with local disk files (because you are making some tests), you need to ensure that DBBUILD will find the files with through the AbaPerls file-lookup order. The simplest way is to check out these files, and DBBUILD will find the disk files through the version-control system. You can also gather the files in the same AbaPerls SQL directory structure, and run DBBUILD from the Scripts directory of that structure. Note that when you build from version-control, DBBUILD retrieves the list of files from the version-control system, and thus DBBUILD will not pick up new files that have not yet been checked in (including files that have an Add pending in TFS.)

When you build from disk with no version-control whatsoever – maybe because you are toying out a new database, or you want to test with files you have not checked in – you can only build one subsystem at a time. As in the previous scenario, your current directory can either be in the AbaPerls SQL directory structure for the subsystem, or in a directory which has one directory per subsystem. In the latter case, you don't have to change directory if you build several subsystems.

In the last scenario, you always run DBBUILD from the directory where you have SUBSYSTEMS.LIS and SS‑FILES.LIS, and you have one directory per subsystem.

For more information and examples, see AbaPerls file-lookup order and Installation at a Customer Site.

abainstallinfo

Even if you opt to not install the subsystem ABAPERLS in your database, DBBUILD creates one help table: abainstallinfo.

Abainstallinfo gives an installation history for the database, akin to the one in abainstallhistory, and is also maintained by the update scripts generated by DBUPDGEN. If you later opt to add the ABAPERLS subsystem to your database, abainstallinfo will be converted to abainstallhistory.