This page describes the grammar and semantics of config-files and what they are good for.
Contents:
Introduction
Syntax for a Config-File
The Subsystem Entry
Config-File Examples
Configurations files, or config-files for short, is an important concept in AbaPerls. The config-files are used as input to several of the AbaPerls tools. The main usages are:
A config-file lists one or more subsystems, the
SS-path and, optionally,
the version for each subsystem. It
also lists configuration options that DBBUILD
uses when building a database; configuration options can be specified both on
global level for the database or for a single subsystem. The configuration
options are saved in the database, and ABASQL
and the update scripts generated by DBUPDGEN
reads them when operating on the database. One example of such a configuration
option is
A config-file may reside in SourceSafe or on disk. When in SourceSafe, you refer to it through its SS-path, for instance ABABOS32/$/ABABOS/4.40/ABASEC.CFG. If you specify a project, AbaPerls looks for CONFIG.CFG in that project.
Depending in the usage of the config-file, the contents and the maintenance of the file may vary. A config-file for DBBUILD is typically site-specific, and lists the subsystem installed in the databases at a certain site, whereas a config-file for DBUPDGEN may be all-inclusive and include all subsystems that could be installed in the main system that lives in the database. In both cases the config-file should be rigorously maintained and be stored in SourceSafe. Also, in both cases, the config-files covers only the SQL part of the subsystems. Config-files for SSGREP and SSREPLACE might be more ad hoc in nature, and are also likely to cover non-SQL parts of the subsystem, such as Visual Basic code etc.
There is a command, LISTCONFIG, that reads a config-file and lists the contents of it. This is a useful debug tool.
The grammar for a config-file is as follows:
[option [option...] | . option] [comment]
[...]
subsys-entry [comment]
[subsys-entry] [comment]
[...]
Where:
subsys-entry ::= subsys-name SS-Path [version-desig] [option [option...]]
[option [option...] | . option]
[...]
subsys-name ::= A-Z[-_A-Z0-9...]
SS-path ::= "[database/]$/proj-path"
version-desig ::= date | label | LATEST | NULL
option ::= -[no]Adefauls | -[no]Anulls | -[no]Apadding | -[no]Aquoted |
-charset CP | -[no]crypt | -envrionment {DEV | TEST | PROD} |
-Macro ¯o[=value] | -[no]quoterepl |
-site site-id[:site-id...] | -[no]subscriber | -undef ¯o |
comment ::= -- any-text
That is, first comes global configuration options, then follows any number of subsystem entries. A subsystem entry defines the name of the subsystem, its path, its version and its configuration options.
On this page we discuss the grammar of the config-file and the semantics on the subsystem entry. A separate page details the semantics of the various configuration options.
The subsystem entries should follow in dependency order: if subsystem B refers to subsystem A, B should come after A. Normally, in a config-file used for building a database, the first subsystem is ABAPERLS itself.
Subsys-name, the subsystem name, is a string with a leading uppercase letter followed by zero or more characters that must be uppercase letters, digits, hyphen or underscore. The name NAMELESS is reserved and cannot be used. Furthermore, the name for AbaPerls as a subsystem should be ABAPERLS and nothing else.
SS-path is an SS-path with a database name and a project path. In a config-file used for DBBUILD or DBUPDGEN, you include the version-subproject, but not the SQL part of the path which is implied. That is, if there is an AbaPerls SQL directory structure in SSDB/$/CUSTREG/4.40/SQL, you must specify SSDB/$/CUSTREG/4.40 as the SS-path.
If the SS-path includes spaces, you must enclose it
quotes(").
In a config-file for SSGREP or SSREPLACE you can include any subprojects you like, depending on how you want to constraint the search.
This field can have any of these values:
When you do not specify a version-designator, AbaPerls uses the
config-file as a starting point on how to find the version of the
project. If you retrieved the config-file from SourceSafe by specifying-label LATEST, then AbaPerls applies LATEST
to all projects. In all other cases, AbaPerls will always use a
labelled version of the project. If you specified a config-file on
disk, or you specified a config-file in SourceSafe without specifying
an explicit version of the config-file, AbaPerls will start searching
for labels at the end of the history of the project. But if you specify
a certain version of the config-file – by label, date or version number
– then AbaPerls will starting searching the history of the project from
the time that the config-file was checked in. (If all this is
bewildering, stay calm, there are examples below.) AbaPerls considers
all labels that apply to the project, that is labels that were set on
upper-level projects are also included in the search.
By default, AbaPerls only considers labels that adheres to the standard
AbaPerls label format
LetterMajor.Middle.Minor. You can use the configuration
options -onlylabel
The usage with an explicit label or LATEST as version-designator, is intended for special cases. While the rules for a blank version-designator are complex, they are devised to be what you want. The tool LISTCONFIG is available to see what versions you get from a certain config-file.
Note that with the tools SSGREP and SSREPLACE, the version-designator does not matter, because these tools always retrieve the config-file by version LATEST.
When you build a database with DBBUILD you specify configuration options in a config-file or on the command line. The settings of the options are saved in the database if the AbaPerls system tables are present in the database. Later on when in you invoke ABASQL or an update script generated by DBUPDGEN, they will read these settings and apply them, as if you had specified them on the command line.
When you enter the configuration options for a subsystem, you can enter them after the version-designator, or you can enter them on the following line. You can split the options on several lines if you like. If an option takes a parameter, the parameter and the option must be on the same line, though.
The rule is that as long as a line starts with a hyphen or a period it is a line of configuration options. (Lines that start with two hyphens are comments of course.) If a line starts with a letter, the line is the beginning of a new subsystem entry.
From this follows that any any configuration options that comes before the first subsystem entry are global configuration options that applies to all subsystems (unless explicitly overridden).
If a line starts with a period followed by a space and a configuration
option, all the text that follows the configuration option is a
parameter to that option. This is necessary when the argument includes space
characters or characters that could confuse the option parser. The typical case
for this is macro definitions. Thus, this line defines the macro &nisse
to have the value
. -macro &nisse=use -crypt
While this line defines &nisse to have the value use
and also sets the option
-macro &nisse=use -crypt
The options apply only when the config-file is used as input to DBBUILD. LISTCONFIG, SSGREP and SSREPLACE ignores the options. However, the latter three will still complain if there are incorrectly specified options in the config-file.
For description of what each configuration option control, please see the configuration-options page.
Assume the config-file DATA6/$/TEST/TESTCONFIG.CFG:
-- This is a config-file for demonstration purposes.
-Macro &nisse
ABAPERLS data6/$/AbaPerls LATEST
TEST data6/$/test/4.40 -site charlie -crypt
. -Macro &colname=[space name]
KATI test2/$/kati/1.0 -undef &nisse
When we build a database from this config-file, this database will contain the subsystems ABAPERLS, TEST and KATI.
For the subsystems ABAPERLS and TEST the macro &nisse
is defined with the value of the empty string. The macro will also be defined
by default for any new subsystems that we may add later. For KATI,
&nisse is not defined, however, as there is an explicit
For the subsystem TEST only, the macro &colname is defined with the value [space name]. Also, only in TEST procedures, views, triggers and functions will be encrypted, and files with the site-id %charlie will be included. (Note: that in this example, the brackets are not marking any optional entry, but part of the value for the macro &colname.)
Then the following events takes place:
2000-02-22, 14:40:40 Labelling of DATA6/$/TEST/4.40 with
L4.40.0010
2000-02-22, 16:40:10 Labelling of TEST2/$/KATI/1.0 with
L1.0.0010
2000-02-22, 18:25:21 Labelling of TEST2/$/KATI/1.0 with
SPECIAL
2000-02-23, 09:13:35 Check-in of DATA6/$/TEST/TESTKONFIG.CFG,
version 7
2000-02-23, 12:35:16 Labelling of DATA6/$/TEST/4.40 with
L4.40.0020
2000-02-22, 14:09:46 Labelling of TEST2/$/KATI
/1.0 with L1.0.0020
Here we use LISTCONFIG to see what the config-file actually defines. The commands:
listconfig c:\temp\testconfig.cfg listconfig data6/$/test/testconfig.cfgboth yield:
Subsystem Label Version Date Project --------- ----- ------- ---- ------- ABAPERLS Current $/abaperls TEST L4.40.0020 10 2000-02-23 12:35:16 $/test/4.40 KATI L1.0.0020 10 2000-02-26 15:55:00 $/kati/1.0
Thus, we get the most recently labelled version of the subsystems, except for ABAPERLS. On the other hand, if we say:
listconfig data6/$/test/testconfig.cfg 7
we get:
Subsystem Label Version Date Project
--------- ----- ------- ---- -------
ABAPERLS Current $/abaperls
TEST L4.40.0010 9 2000-02-22 14:40:40 $/test/4.40
KATI L1.0.0010 9 2000-02-22 16:40:10 $/kati/1.0
Despite we are referring to the same version of TESTCONFIG.CFG in the two cases, we get different results. The difference is that, in the latter example we explicitly stated which version of the config-file that we wanted, and thus we got the labelled versions of TEST and KATI that were the most current when TESTCONFIG.CFG was checked in. When we did not specify the version for the config-file, we got what was the most recently labelled at the time of the command. Note also that the label SPECIAL was ignored. To include this label, we would have to add the configuration option -onlylabel.
If we say
listconfig data6/$/test/testconfig.cfg LATEST
we get:
Subsystem Label Version Date Project
--------- ----- ------- ---- -------
ABAPERLS Current $/abaperls
TEST Current $/test/4.40
KATI Current $/kati/1.0
Here LATEST applies to all subsystems.
Note: in these examples we have used LATEST as the version-designator for ABAPERLS. However, best practice is leave the version-designator blank for the ABAPERLS subsystem as well, as this makes it easier to deploy changes in AbaPerls' tables and stored procedures.