Chapter 4: Support Library

This chapter describes the Databridge Support Library and the GenFormat program and how you can use them to create tailored support libraries.

Understanding the Support Library

The Support Library provides translation, filtering, and formatting services for Databridge Accessories. The Accessories pass the records they receive from DBEngine to entry points in the Support Library for filtering and then, if the record successfully passes through the filter, for formatting.

Although you can use the Support Library “as is” or with minor formatting customizations, it is highly recommended that you create a tailored support library for each database you plan to clone and update.

Important

In a nontailored support library, you cannot use any data set or data item names, nor can you use any SELECT statements. Therefore, you must create a tailored support library to create effective filters. For example, if a filter refers to specific data sets, such as BANK1 or OHIOCUSTOMERS, you must compile the Support Library as a tailored library.

A tailored support library is a database-specific version of the Support Library and works the same as the generic Support Library. However, tailoring a library for a specific database enhances performance by increasing throughput. A nontailored Support Library uses interpretive routines for each data set. You can tailor the Support Library for the following:

Translation
Filtering
Formatting
Reformatting (ALTERations)
Transforming (VIRTUAL data sets)

You can customize the Support Library by using the GenFormat program explained in the next section. GenFormat generates source code for filters and formats that you can include when you compile the Support Library. It is highly recommended that you use GenFormat to generate a tailored (database-specific) support library for each database you plan to replicate.

Tailoring a Support Library

A tailored support library is a database-specific version of the Support Library. Tailoring a support library enhances performance by increasing throughput.

To tailor a support library

Use CANDE or another editor to get the GenFormat parameter file DATA/GENFORMAT/SAMPLE/CONTROL.

For a general description of the GenFormat parameter file, see GenFormat Parameter File.
Save the file with a new name, as follows:

DATA/GENFORMAT/databasename/CONTROL

where databasename is the name of the database for which you are creating the tailored support library.

Example: DATA/GENFORMAT/PRODUCTDB/CONTROL

Note

You can also create an alternate parameter file when you compile the support library, as explained in step 5.
Modify this new file (DATA/GENFORMAT/databasename/CONTROL) for any of the following:
- Formatting routines. See Creating a Format.
- Filtering routines. See Creating a Filter.
- Transforms. See Transforms.
- Error manager. See Error Manager.
- Data item conversion. See ALTER and VIRTUAL Data Sets.
- Virtual data sets. See ALTER and VIRTUAL Data Sets.
- Primary keys. See Creating a Primary Key.
- Translation tables. See Creating and Using Translation Tables.
Save DATA/GENFORMAT/databasename/CONTROL.

To create and compile the new support library, including layout tables for each data set in the designated databases, start WFL/DATABRIDGE/COMP:

START WFL/DATABRIDGE/COMP ("SUPPORT", "databasename" [,"logicaldatabasename"])

Where	Is
`"SUPPORT"`	The literal that represents the Support Library program. The quotation marks are required.
`"databasename"`	The name of the database for which you are creating the tailored support library. The database name can include a usercode and pack, which are used to locate the database DESCRIPTION file, as follows: `"(usercode)databasename ON packname"` The quotation marks are required.
`"logicaldatabasename"`	An optional name of an alternate database when you want to create one of the following: A tailored support library for the logical database. An alternate parameter file for the physical database, which is useful when you want to generate multiple support libraries for the same database but with different parameter files. In either case, the GenFormat file must be titled `DATA/GENFORMAT/databasename/logicaldatabasename/CONTROL`

Caution

You cannot compile tailored support libraries for more than one database of a given name in one usercode—the second tailored support library will replace the first.

This results in the new tailored support library titled as follows:

OBJECT/DATABRIDGE/SUPPORT/databasename

-or—

OBJECT/DATABRIDGE/SUPPORT/databasename/logicaldatabasename

The data set-specific layout tables in the tailored support library have the offsets and sizes of individual data items hardcoded. In addition to creating this file, the WFL will create a copy that adds the update level as the last node. This makes the library more easily identifiable and helps prevent accidental deletion of a version of the Support Library that may still be needed. For example, the Support Library for BANKDB update level 4 will be copied as follows:

OBJECT/DATABRIDGE/SUPPORT/BANKDB/4

To use the tailored support library

Specify the new tailored support library file title for the SUPPORT parameter in the appropriate Accessory parameter file:

Understanding GenFormat

Use the GenFormat program to create formats, filters, and translation tables—without programming—that you can compile into a tailored support library. Specifically, you can use the GenFormat program (also referred to as DBGenFormat) to include the following in your tailored support library:

Alter data sets*
Virtual data sets*
Primary keys
Reformatting
Translation tables
Transforms*
Formatting
Filtering
Error management*
Startup and shutdown*
These items require additional programming. Refer to the Databridge Host Programmer’s Reference for instructions.

To use the GenFormat program, edit the GenFormat parameter file using CANDE or some other text editor, and then compile the Support Library using WFL/DATABRIDGE/COMP. The parameter file can contain as many formats and filters as you want.

The GenFormat program interprets your textual descriptions of filters, formats, etc., in its parameter file, generates ALGOL source code patches, and includes them in a tailored support library. The tailored support library implements the filter and format routines you specify in a Databridge Accessory parameter file (or in your user-written Accessories).

For instructions, see Tailoring a Support Library.

GenFormat Parameter File

Each part of the GenFormat parameter file is described on the following pages, along with an excerpt from the actual sample GenFormat parameter file (DATA/GENFORMAT/SAMPLE/CONTROL). This topic describes the format that the GenFormat parameter file requires.

Declarations in the parameter file must be in the following order:

1—ALTERs and VIRTUALs 2—PRIMARY KEYs 3—REFORMAT, TRANSLATIONs, TRANSFORMs, FORMATs, FILTERs, ERROR MANAGER, STARTUP, and SHUTDOWN
You can list the options for a reformat, translation, transform, format, filter, error manager, startup, or shutdown in any order.
You can list multiple options on a single line.
You can split options across multiple lines.
There is no termination character.
There is no continuation character.
The comment character is the percent sign (%). The comment character can appear anywhere on a line and anything after the comment character is ignored.
The default format for floating point real numbers is SCIENTIFIC (11), which has the following format:

#.#####E-##
You can use GenFormat keywords as filter or format names. This includes, for example, the keywords TRANSLATION, FORMAT, and FILTER. To use keywords as filter or format names, enclose the name in quotation marks. To use FORMAT as a format name, you would enter the following:

FORMAT "FORMAT"

Sample DBGenFormat Parameter File.

%-----------------------------------------------------------------------
%
% (C) Copyright 2019 Micro Focus or one of its affiliates.
%
% Module: DATA/GENFORMAT/SAMPLE/CONTROL
%
% Project: Databridge
%
% Description: Databridge GenFormat Sample Parameter File
%
% (C) Copyright 2019 Micro Focus or one of its affiliates.
%
%-----------------------------------------------------------------------%
% This is the input to the Databridge Format Generator program.
%
% (Upper/lower case is not significant.)
%
% This file has these main sections:
%       Alterations
%       Virtuals
%       Primary keys
%       Reformat
%       Translations
%       Transforms
%       Formats
%       Filters
%       Error Manager
%       Startup
%       Shutdown
% Alterations and Virtuals must precede the other sections.
% Translations, Transforms, Formats, and Filters can be intermixed with
% each other but cannot precede any Primary keys.
%
% When processing an update, the sequence is:
%
% 1. Apply the row filter (the FILTER's WHERE ... condition) and stop
%      processing if the condition is false.
%
% 2. Call the TRANSFORM.
%
% 3. The TRANSFORM calls the FORMAT zero or more times for real and/or
%      VIRTUAL records.
%
% 4. The FORMAT steps through the list of data items of the column
%      filter (the FILTER's SELECT ...).
%
% 5. For each data item, if the data item is ALTERed, call the REFORMAT
%      routine, otherwise format it according to its data type. If it
%      is an ALPHA item, use the TRANSLATION table, if any. The
%      reformatted values for ALTERed items are placed at the end of
%      the record and formatted according to their data type just like
%      unaltered items.
%
%
% Lines below beginning with %* indicate example declarations that you
% can uncomment and use immediately if you are compiling a tailored
% Support Library for the sample database, BANKDB.
%
%======================================================================
%                          Alterations
%                   (Data item reformatting)
%                   ========================
%
% In this section, list any data items that require transformation.
% When the formatting routines encounter a data item in the list, they
% will call the REFORMAT routine, which is either a procedure in the
% Support Library (see PATCH/DATABRIDGE/SAMPLE/SUPPORT/REFORMAT) or an
% entry point in a library (see SYMBOL/DATABRIDGE/SAMPLE/REFORMAT),
% before performing normal formatting. (The "Reformat" section below
% specifies where the REFORMAT routine resides.)
%
% For example, if dates are stored in a non-standard layout, the
% formatting routines could call REFORMAT to reformat the dates into
% a standard layout.
%
% The formatting routines will pass the number in brackets for the data
% item to REFORMAT, which can use the value to determine the type of
% formatting required.
%
%      ALTER <dataset>
%              (
%              [<uservalue1>]
%                     <original dataname1> <new DASDL definition>
%
%              [<uservalue2>]
%                     <original dataname2> <new DASDL definition>
%
%              [REDEFINE]
%                     <original dataname3> <new DASDL definition>
%              [DEFINE <uservalue3>]
%                     <new dataname4> <new DASDL definition>
%
%                     ...
%              );
%
%
% Note that the numbers do not have to be unique. In fact, all data
% items of a particular type, e.g. days-since-1900, would probably have
% the same value since a single routine could convert any of them.
%
%      Example:
%*           ALTER BRANCH
%*              (
%*              [1] TS           ALPHA (30);      % was REAL
%*              [2] BRANCH-ID    NUMBER (6);      % was NUMBER (4)
%*              [3] BRANCH-AD1   GROUP            % was ALPHA (40)
%*                             (
%*                             BR-ADD1   ALPHA (30);
%*                             BR-ADD2   ALPHA (30);
%*                             BR-CITY   ALPHA (20);
%*                             BR-REGION ALPHA (15);
%*                             );
%*              );
%*
%*          ALTER BANK
%*              (
%*              [REDEFINE] BANK-ADDR3 GROUP       % was ALPHA (30)
%*                              (
%*                              BR-CITY    ALPHA (18);
%*                              BR-STATE   ALPHA (2);
%*                              BR-ZIP     ALPHA (10);
%*                              );
%*              [DEFINE 6] BANK-PRES ALPHA (40);  % new item
%*              [DEFINE 7] BANK-PHONE ALPHA (12); % new item
%*              );
%*
%*          ALTER HISTORY
%*             (                                            % was:
%*             [REDEFINE]      TRAN-DATE NUMBER (YYMMDD);   % NUMBER (6)
%*             [REDEFINE]      TRAN-TIME NUMBER (HHMMSS);   % NUMBER (6)
%*             [REDEFINE]      PROC-DATE NUMBER (YYMMDD);   % NUMBER (6)
%*             [REDEFINE]      TS TIME_6;                   % REAL
%*             );
%*
%*
%*           ALTER EMPLOYEES
%*                 (
%*         % Alter multiple adjacent data items as a single item.
%*
%*                 [REDEFINE]      EMP-LAST-NAME,
%*                                 EMP-FIRST-NAME
%*                              AS EMP-PERSONAL ALPHA (32);
%*                 );
%
% alterations go here ...
%======================================================================
%                              Virtuals
%                         (Virtual datasets)
%                         ==================
%
%    These datasets will appear as normal datasets to Accessories
%    but do not actually exist in the DMSII database. Special
%    Transforms must "create" records in them.
%
%    VIRTUAL <datasetname> # <strnum> POPULATION <est. recs.>
%             DERIVED FROM <datasetlist>
%            (
%            <dataitems>
%            );
%
%    Example:
%
%*           VIRTUAL ADDRESS #79 POPULATION 100000
%*
%*                   DERIVED FROM BANK, CUSTOMER
%*
%*                   (ADDR-BANK-ID NUMBER (4);
%*                    ADDR-CUST-ID NUMBER (8);
%*                    ADDR-LINE-NBR NUMBER (1);
%*                    ADDR-LINE ALPHA (30);
%*                   );
%
%
%    The POPULATION clause is optional but strongly recommended. The
%    default value is 1000000.
%
%    The DERIVED FROM clause causes GenFormat to generate defines
%    and variables that the transform can use to build virtual
%    records. We recommend that you use the sample transform
%    PATCH/DATABRIDGE/SAMPLE/SUPPORT/VIRTUAL
%    as a starting point for writing the transform.
% virtuals go here ...
%======================================================================
%                          Primary Keys
%                          ============
%
% The PRIMARY KEY declarations below provide Databridge with a unique
% key for the designated datasets. This is useful for datasets that do
% not have a NO DUPLICATES set declared (but *could* have one declared).
%
% Syntax:
%
%      PRIMARY KEY OF <dataset> IS ( <key items> )
%
% (The keywords PRIMARY, OF, and IS are optional.)
%
%      Examples:
%
$
%*           Primary Key of CUSTOMER is (CUST-ID)
%*
%*           Key ADDRESS (ADDR-BANK-ID, ADDR-CUST-ID, ADDR-LINE-NBR);
%
% Databridge will *not* confirm that the specified key is unique.
%
%      Primary Key declarations go here ...
%
%
%======================================================================
%                           Reformat
%                           ========
%
%    This section specifies the location of the REFORMAT routine
%    that will convert any ALTERed data items.
%
%    An INTERNAL REFORMAT specifies a patchfile containing a REFORMAT
%    routine that converts ALTERed data items. This patchfile will be
%    compiled into the Support Library and called directly from the
%    formatting routines. The patchfile can contain "global" as
%    variables needed. This method makes the DBInterface definitions and
%    Engine entry points available to the REFORMAT routine without
%    having to declare them ($ INCLUDE "SYMBOL/DATABRIDGE/INTERFACE)
%    or explicitly linking to DBEngine. The patchfile should not
%    include an EXPORT declaration.
%
%    Syntax:
%            INTERNAL REFORMAT IN "<patchfiletitle>"
%
%    Example:
%*           INTERNAL REFORMAT
%*                   IN "PATCH/DATABRIDGE/SAMPLE/SUPPORT/REFORMAT"
%
%    An EXTERNAL REFORMAT indicates that the REFORMAT routine
%    resides in a separate library program, where it is declared as
%    an entry point and EXPORTed. In this method, the REFORMAT
%    routine must have $ SET INCLUDE_ENGINE (and INCLUDE_SUPPORT if
%    needed) as well as $ INCLUDE "SYMBOL/DATABRIDGE/INTERFACE".
%    The Support Library will ensure that the external REFORMAT
%    library is linked to the same instance of DBEngine as the
%    Accessory and Support.
%
%    Syntax:
%            EXTERNAL REFORMAT IN "<librarytitle>"
%
%    Example:
%            EXTERNAL REFORMAT IN "OBJECT/DATABRIDGE/REFORMAT"
%
%    You can specify only one REFORMAT declaration.
%
%    The default is
%            EXTERNAL REFORMAT IN "OBJECT/DATABRIDGE/REFORMAT".
%
%    The recommended method is to use INTERNAL REFORMAT ....
%
%======================================================================
%                         Translations
%                         ============
%
% The formatting routines use these translation tables to translate
% individual EBCDIC characters in text (ALPHA) data items. The
% format (declared below) specifies which table to use.
%
% Syntax:
%       TRANSLATION tablename
%               sourcevalue -> destinationvalue
%               ...
%
%       sourcevalue and destinationvalue can be the decimal value of
%       a character, or the hexadecimal value of a character, or a
%       quoted character. The following are equivalent.
%               193 -> 194
%               0xC1 -> 194
%               "A" -> 194
%               193 -> 0xC2
%               0xC1 -> 0xC2
%               "A" -> 0xC2
%               193 -> "B"
%               0xC1 -> "B"
%               "A" -> "B"
%
% You can comment out each of the TRANSLATION tables declared below
% unless you have a FORMAT that explicitly references it.
%======================================================================
Translation CRToLF % Convert Carriage Return to Line Feed
037 -> 013 % cr -> lf
Translation UnitedKingdom % United Kingdom
123 -> 068 % # -> ú
Translation Denmark % Denmark
161 -> 087 % ~ -> »
124 -> 138 % @ -> -
090 -> 139 % ] -> +
074 -> 140 % [ -> ¦
224 -> 176 % \ -> +
095 -> 180 % ^ -> _
121 -> 188 % ` -> S
208 -> 189 % } -> s
192 -> 190 % { -> μ
106 -> 238 % | -> °
161 -> 252 % ~ -> n
Translation Finland % Finland
091 -> 069 % $ -> ñ
074 -> 138 % [ -> -
090 -> 139 % ] -> +
124 -> 143 % @ -> +
224 -> 174 % \ -> +
095 -> 180 % ^ -> _
192 -> 188 % { -> S
208 -> 189 % } -> s
121 -> 203 % ` -> T
106 -> 236 % | -> ÷
161 -> 252 % ~ -> n
Translation France % France
123 -> 068 % # -> ú
090 -> 072 % ] -> º
161 -> 073 % ~ -> ¿
074 -> 088 % [ -> ¦
124 -> 184 % @ -> a
224 -> 191 % \ -> t
208 -> 202 % } -> F
192 -> 203 % { -> T
106 -> 239 % | -> ·
Translation Germany % Germany
036 -> 192 %? -> {
124 -> 072 % @ -> º
074 -> 138 % [ -> -
224 -> 174 % \ -> +
090 -> 180 % ] -> _
161 -> 183 % ~ -> ̄
192 -> 188 % { -> S
106 -> 236 % | -> ÷
208 -> 252 % } -> n
Translation Italy % Italy
224 -> 123 % \ -> #
123 -> 068 % # -> ú
124 -> 072 % @ -> º
074 -> 088 % [ -> ¦
192 -> 184 % { -> a
224 -> 191 % \ -> t
208 -> 202 % } -> F
090 -> 203 % ] -> T
161 -> 206 % ~ -> 8
106 -> 222 % | -> =
121 -> 239 % ` -> ·
Translation Norway % Norway
238 -> 106 % ° -> |
252 -> 161 % n -> ~
161 -> 087 % ~ -> »
124 -> 138 % @ -> -
090 -> 139 % ] -> +
074 -> 140 % [ -> ¦
224 -> 176 % \ -> +
095 -> 180 % ^ -> _
121 -> 188 % ` -> S
208 -> 189 % } -> s
192 -> 190 % { -> μ
106 -> 238 % | -> °
161 -> 252 % ~ -> n
Translation Spain % Spain
074 -> 066 % [ -> í
123 -> 068 % # -> ú
124 -> 072 % @ -> º
192 -> 088 % { -> ¦
090 -> 117 % ] -> +
224 -> 160 % \ -> -
208 -> 191 % } -> t
106 -> 221 % | -> ±
Translation Sweden % Sweden
091 -> 069 % $ -> ñ
074 -> 138 % [ -> -
090 -> 139 % ] -> +
124 -> 143 % @ -> +
224 -> 174 % \ -> +
095 -> 180 % ^ -> _
192 -> 188 % { -> S
208 -> 189 % } -> s
121 -> 203 % ` -> T
106 -> 236 % | -> ÷
161 -> 252 % ~ -> n
Translation SwissFrench % SwissFrench
123 -> 068 % # -> ú
090 -> 072 % ] -> º
161 -> 073 % ~ -> ¿
074 -> 088 % [ -> ¦
124 -> 184 % @ -> a
224 -> 191 % \ -> t
208 -> 202 % } -> F
192 -> 203 % { -> T
106 -> 239 % | -> ·
Translation SwissGerman % SwissGerman
124 -> 072 % @ -> º
074 -> 138 % [ -> -
224 -> 174 % \ -> +
090 -> 180 % ] -> _
161 -> 183 % ~ -> ̄
192 -> 188 % { -> S
106 -> 236 % | -> ÷
208 -> 252 % } -> n
Translation DenmarkEBCDIC % Denmark EBCDIC
124 -> 183 % @ -> ̄
066 -> 252 % í -> n
065 -> 250 % á -> ·
224 -> 251 % \ -> v
095 -> 187 % ^ -> p
121 -> 100 % ` -> ¦
208 -> 235 % } -> )
192 -> 225 % { -> ƒ
079 -> 234 %! -> (
161 -> 115 % ~ -> +
Translation FinlandEBCDIC % Finland EBCDIC
091 -> 070 % $ -> Ñ
065 -> 183 % á -> ̄
066 -> 252 % í -> n
124 -> 204 % @ -> O
224 -> 186 % \ -> G
095 -> 187 % ^ -> p
192 -> 100 % { -> ¦
208 -> 235 % } -> )
121 -> 105 % ` -> ¦
079 -> 120 %! -> -
161 -> 115 % ~ -> +
Translation FranceEBCDIC % France EBCDIC
123 -> 067 % # -> ó
066 -> 072 % í -> º
161 -> 127 % ~ -> "
065 -> 081 % á -> ¬
124 -> 103 % @ -> +
224 -> 236 % \ -> ÷
208 -> 104 % } -> +
192 -> 105 % { -> ¦
079 -> 099 %! -> ¦
Translation ItalyEBCDIC % Italy EBCDIC
123 -> 067 % # -> ó
124 -> 072 % @ -> º
065 -> 081 % á -> ¬
192 -> 103 % { -> +
224 -> 236 % \ -> ÷
208 -> 104 % } -> +
066 -> 105 % í -> ¦
161 -> 089 % ~ -> ¦
079 -> 098 %! -> ¦
121 -> 099 % ` -> ¦
Translation NorwayEBCDIC % Norway EBCDIC
234 -> 079 % ( ->!
115 -> 161 % + -> ~
124 -> 183 % @ -> ̄
066 -> 252 % í -> n
065 -> 250 % á -> ·
224 -> 251 % \ -> v
095 -> 187 % ^ -> p
121 -> 100 % ` -> ¦
208 -> 235 % } -> )
192 -> 225 % { -> ƒ
079 -> 234 %! -> (
161 -> 115 % ~ -> +
Translation SwissFrenchEBCDIC % Swiss French EBCDIC
123 -> 067 % # -> ó
066 -> 072 % í -> º
161 -> 127 % ~ -> "
065 -> 081 % á -> ¬
124 -> 103 % @ -> +
224 -> 236 % \ -> ÷
208 -> 104 % } -> +
192 -> 105 % { -> ¦
079 -> 099 %! -> ¦
Translation SwissGermanEBCDIC % Swiss German EBCDIC
124 -> 072 % @ -> º
065 -> 183 % á -> ̄
224 -> 186 % \ -> G
066 -> 187 % í -> p
161 -> 071 % ~ -> ª
192 -> 100 % { -> ¦
079 -> 120 %! -> -
208 -> 115 % } -> +
Translation SpainEBCDIC % Spain EBCDIC
065 -> 137 % á -> i
123 -> 067 % # -> ó
124 -> 072 % @ -> º
192 -> 081 % { -> ¬
066 -> 111 % í ->?
079 -> 220 %! -> =
208 -> 236 % } -> ÷
224 -> 157 % \ -> +
Translation SwedenEBCDIC % Sweden EBCDIC
091 -> 070 % $ -> Ñ
065 -> 183 % á -> ̄
066 -> 252 % í -> n
124 -> 204 % @ -> O
224 -> 186 % \ -> G
095 -> 187 % ^ -> p
192 -> 100 % { -> ¦
208 -> 235 % } -> )
121 -> 105 % ` ->
079 -> 120 %! -> -
161 -> 115 % ~ -> +
Translation UnitedKingdomEBCDIC % United Kingdom EBCDIC
123 -> 067 % # ->
Translation GermanEBCDIC % German EBCDIC
124 -> 072 % @ ->
065 -> 183 % á -> ̄
224 -> 186 % \ -> G
066 -> 187 % í -> p
161 -> 071 % ~ -> ª
192 -> 100 % { -> ¦
079 -> 120 %! ->
208 -> 115 % } -> +
%======================================================================
%                          Transforms
%                          ==========
%
%    A TRANSFORM is a special formatting routine used for populating
%    VIRTUAL datasets or transforming an update in other ways.
%    Syntax:
%
%            TRANSFORM <transformname> IN "<patchfiletitle>"
%    A transform is a user-written procedure in a patch file that
%    is compiled into Support (similar to an INTERNAL FORMAT). A
%    transform has access to both the before- and after-images at
%    the same time the formatting routine.
%
%    The patch file should declare the transform procedure header
%    using the DBTransformHead define in DBInterface. Unlike a
%    format, the procedure return value is DBMTYPE rather than a
%    boolean. The parameters are UI, BI, AI, Format, and Writer,
%    which are respectively, the UpdateInfo, before-image,
%    after-image, formatting routine, and the Accessory-supplied
%    output routine.
%
%    These transforms are predefined in Support:
%             ChangedRecordsOnly
%                  Discards records if none of the data items
%                  allowed by the filter are modified.
%
%             ChangedItemsOnly
%                  Discards unmodified data items. The Accessory
%                  receives only the key items and data items that
%                  changed.
%
%    Example:
%
%*   TRANSFORM VIRTUALADDRESS
%*       IN "PATCH/DATABRIDGE/SAMPLE/SUPPORT/FORMATADDRESS"
%
%    Transforms go here ...
%======================================================================
%                           Formats
%                           =======
%
% Option       Means                                          Default
% --------     ----------------------------                   -------
% <type>       type of format                                 DISPLAY
% FORMAT       name of the formatting routine
% PREFIX       what to put at the beginning of each record    Nothing
% POSTFIX      what to put at the end of each record          Nothing
% SEPARATOR    what to put between each data item             Nothing
% DECIMALPT    decimal point character in numbers             Nothing
% DATACHECK    generate code to check for nulls, invalid      TRUE
%              characters or illegal numbers and overflows
% PADDING      "fill" character for short records             48"00"
% OVERFLOW     "fill" character for integer overflows         9999...
% NULL         "fill" character for NULL values      numbers: 0000...
%                                                    text: Spaces
% POSITIVE     format of a non-negative number                VALUE
% NEGATIVE     format of a negative number                    VALUE
% UNSIGNED     format of an unsigned number                   VALUE
% TEXT         format of an alphanumeric item                 VALUE
% TRANSLATE    name of the translation table to use for text  None
% FLOAT        format of floating point REAL          SCIENTIFIC (11)
%              Either DECIMAL (w, d) or SCIENTIFIC (w)
% TRUE         string value to use for true                   "1"
% FALSE        string value to use for false                  "0"
%
% <Type>       Format type
% -------      -----------------------------------
% DISPLAY      readable formatting
% BINARY       binary formatting
% RAW          unformatted
% VARYING      variable-length, e.g. no trailing spaces, readable
%              fields
%
% Code         Represents
% -----        -----------------------------------
% STRNUM       structure number (4 digits)
% STRNAME      structure name (17 characters)
% RECTYPE      record type (3 digits)
% CHANGECODE   change code ('A' add, 'D' delete, 'M' modify)
% MODFLAG      modifies flag ('1' delete/add was a modify, else '0')
% STACKNBR     stack number of updating program (4 digits)
% MODE         "tracking" mode, ('0' extract, '2' normal, etc.)
% FORMATLEVEL  dataset format update level (4 digits)
% AFN          audit file number (4 digits)
% ABSN         audit block serial number (10 digits)
% SEG          audit file segment number (7 digits)
% INX          audit block word index (5 digits)
% YYYY         year (4 digits)
% YY           year (2 digits)
% MM           month (2 digits)
% DD           day (2 digits)
% HH           hour (2 digits)
% MN           minute (2 digits)
% SS           second (2 digits)
%
% UID          unique ID of record as 12 decimal digits*
% HEXUID       unique ID of record as 12 hexadecimal digits*
% PUID         unique ID of parent record as 12 decimal digits*
% HEXPUID      unique ID of parent record as 12 hexadecimal digits*
% BIGUID       unique ID of record as 15 decimal digits*
% BIGPUID      unique ID of parent record as 15 decimal digits*
% RSN          (same as BIGUID)
%
%...     * Note: These UIDs may or may not be present depending on the
%                type of dataset. If they are present, they will auto-
%                matically have the 'separator' characters around them.
%
%        BIGUID or RSN is required for unique IDs that are RSNs to avoid
%        losing significant digits.
%
% CR           carriage return character
% LF           line feed character
% SPACE        space character
% TAB          horizontal tab character
%
% DATANAME     name of the data item
% VALUE        value of the data item in EBCDIC form.
%              Type              Size (in bytes) in output:
%              ----              -------------------------
%              ALPHA (n)         n
%              NUMBER (n)        n
%              NUMBER (Sn)       1 (sign) + n
%              NUMBER (n, m)     n + 1 (decimal point)
%              NUMBER (Sn, m)    1 (sign) + n + 1 (decimal point)
%              REAL              1 (sign) + w [from FLOAT SCIENTIFIC (w)
%                                               or FLOAT DECIMAL (w, d)]
%              REAL (n)          11
%              REAL (Sn)         1 (sign) + 11
%              REAL (Sn, m)      1 (sign) + 11 + 1 (decimal point)
%              RECORD TYPE       11
%              FIELD (n)         11
%              BOOLEAN           1 ('0' is false, '1' is true)
%
%======================================================================
display format   KEYFORMAT
%                ---------
% formatting for key items. Required.
prefix           ==> SPACE
separator        SPACE
decimalpt        .
unsigned         DATANAME = VALUE
positive         DATANAME = +VALUE
negative         DATANAME = -VALUE
text             DATANAME = "VALUE"
boolean          DATANAME = VALUE
padding          SPACE
float            DECIMAL (12, 4)
display format   COMMAFORMAT
%                -----------
% prefix; comma between each data item
prefix           STRNUM , RECTYPE , CHANGECODE ,
postfix          UID PUID LF
separator        ,
decimalpt        .
positive         +VALUE
negative         -VALUE
text             "VALUE"
padding          SPACE
float            SCIENTIFIC (11) % #.#####E-##
%float           DECIMAL (12, 2) % #########.##
%translate       UnitedKingdom
%null            SPACE
%overflow        *
%true            "TRUE "
%false           "FALSE"
display format   RSNCOMMA
%                --------
% prefix; comma between each data item
prefix           STRNUM , RECTYPE , CHANGECODE ,
postfix          BIGUID BIGPUID LF
separator        ,
decimalpt        .
positive         +VALUE
negative         -VALUE
text             "VALUE"
padding          SPACE
float            SCIENTIFIC (11) % #.#####E-##
display format   SNAPSHOTCOMMA
%                -------------
% COMMAFORMAT but no prefix; just the data
postfix          UID PUID LF
separato         ,
decimalpt        .
positive         +VALUE
negative         -VALUE
text             "VALUE"
padding          SPACE
%translate       UnitedKingdom
%float           DECIMAL (12, 2)
true             "1"
false            "0"
%* display format  COMMAFORMATQUOTEALL
%                  -------------------
% COMMAFORMAT with quotes around everything
%* prefix          "STRNUM" , "RECTYPE" , "CHANGECODE" ,
%* postfix         UID PUID LF
%* separator       ,
%* decimalpt       .
%* positive        "+VALUE"
%* negative        "-VALUE"
%* unsigned        "VALUE"
%* text            "VALUE"
%* boolean         "VALUE"
%* true            "T"
%* false           "F"
%* padding         SPACE
%* float           DECIMAL (12, 2)
display format     FIXEDFORMAT
%                  -----------
% no delimiters; prefix has structure number, record type, change code
prefix             STRNUM RECTYPE CHANGECODE
postfix            UID PUID
decimalpt          .
positive           +VALUE
negative           -VALUE
padding            SPACE
%translate         UnitedKingdom
%float             DECIMAL (12, 2)
datacheck          TRUE
display format     SNAPSHOTFIXED
%                  -------------
% FIXEDFORMAT but no prefix; just the data
postfix            UID PUID
decimalpt          .
positive           +VALUE
negative           -VALUE
padding            SPACE
%translate         UnitedKingdom
%float             DECIMAL (12, 2)
display format     NameFormat
%                  ----------
% Insert the dataname in front of each data item value.
prefix             CHANGECODE SPACE STRNAME SPACE
separator          ,
unsigned           DATANAME = VALUE
positive           DATANAME = +VALUE
negative           DATANAME = -VALUE
text               DATANAME = "VALUE"
boolean            DATANAME = VALUE
padding            SPACE
binary format      BINARYFORMAT % required for DBServer
%                  ------------
%* translate       UnitedKingdom % translation for ALPHAs
format             AUDITLOC
%                  --------
prefix MM/DD/YYYY@HH:MN:SS[AFN,ABSN,INX] CHANGECODE
separator          ,
%
% A VARYING format has fields that vary in size depending on their
% contents. Alpha fields truncate trailing spaces. Numeric fields strip
% leading zeroes. The output file should be some type of STREAM file to
% allow for output records of different sizes.
%* varying format CSV
%               ---
%* prefix         STRNUM ,    RECTYPE ,   CHANGECODE ,
%* postfix        LF
%* separator      ,
%* decimalpt      .
%* positive       VALUE
%* negative       -VALUE
%* text           "VALUE"
%
%                    External formats
%                    ================
%
%     EXTERNAL FORMAT <formatname> IN "<librarytitle>"
%
% The <librarytitle> is the title of an ALGOL library codefile
% containing an EXPORTed formatting procedure called <formatname>.
% The user must write the library program. Example:
%
%        external format CUSTOMFORMAT
%                in "OBJECT/LOCAL/FORMATLIB"
%
%
%                    Internal formats
%                    ================
%
%    INTERNAL FORMAT <formatname> IN "<patchfiletitle>"
%
% The <patchfiletitle> is the title of an ALGOL source file
% containing a patch for Support that declares a formatting
% routine whose name is <formatname>.
%
%
%
%======================================================================
%                       Filters
%                       =======
%
% Option      Means                                      Default
% --------    ----------------------------               -------
% FILTER      name of filtering routine                  Nothing
% SELECT      specifies dataset name                     Nothing
% DEFAULT     default selection expression               NONE
% $ INCLUDE   include ALGOL source file                  Nothing
%
% Syntax for "SELECT" option:
%
% SELECT <filteritems> FROM <dataset> <optional where> <optional using>
%
%         where <filteritems> is:
%                 ALL
%
%.                * (same as ALL)
%
%                 <dataitem 1> <dataitem 2> ...
%
%                 ALL EXCEPT <dataitem 1> <dataitem 2> ...
%
%                 <vf 1>: <dataitem 1> <dataitem 2> ...
%                 <vf 2>: <dataitem 3> <dataitem 4> ...
%                 ELSE: * (or NONE or ALL)
%                 ... (for variable format datasets)
%
%        Dataitems can be GROUPs or elementary items. If the data item
%        OCCURS, all occurrences will be selected.
%
%        The <optional where> part has the following syntax:
%                WHERE <booleanexpression>
%                (if omitted, all records will be selected from the
%                dataset)
%
%        The <booleanexpression> can specify the type of update.
%        Syntax:
%
%                UPDATETYPE (<type>)
%
%        where <type> is CREATE, MODIFY, or DELETE.
%
%        Example:
%                select * from ORDERS
%                        where UpdateType (CREATE)
%                           or UpdateType (MODIFY)
%
%        The <optional using> part has the following syntax:
%        USING <(sub)set>
%
%        The <(sub)set> specifies the name of a set or subset that will
%        be used to extract records during a clone. If the subset has a
%        WHERE clause in the DASDL, GenFormat will automatically append
%        that expression to the WHERE clause in the SELECT statement.
%
%        Example:
%               select * from ACCOUNTS
%                       where ACCT-TYPE = 1
%                       using ACTIVEACCTS            % subset of ACCOUNTS
%
%
% Syntax for "DEFAULT" option:
%
% DEFAULT ALL (select all records for unSELECTed datasets)
% DEFAULT ANY (same as ALL)
% DEFAULT NONE (do not select any records for unSELECTed datasets)
% DEFAULT ALL EXCEPT datasetlist (exclude datasets in list)
% DEFAULT UPDATETYPE (<type>) [OR UPDATETYPE (<type>)]
%
% Relational
% Operator       Means
% ---------      -----------------------------------
% =              Equal to
% ^=             Not equal to
% >              Greater than
% >=             Greater than or equal to
% <              Less than
% <=             Less than or equal to
% EQL            Equal to
% NEQ            Not Equal to
% GTR            Greater than
% GEQ            Greater than or Equal
% LSS            Less than
% LEQ            Less than or Equal
% IS             Bit-for-bit equal
% ISNT           Not bit-for-bit equal
%
% "AND" and "OR" may be used to connect multiple expressions.
% "NOT" may be used to reverse the value of an expression.
filter   DISCARDALL   % discard every record
%        ----------
default  NONE
% ---------------------------------------------------------------------
filter   EVERYTHING   % keep every record
%        ----------
default ALL
% -----  Examples ------
%* filter    ONLYBANK1
%            ---------
%* default NONE       % return records only for the datasets specified in
% the SELECT statements
%* select  * from BANK     where BANK-ID = 1;
%* select  * from BRANCH   where BANK-ID = 1;
%* select  * from CUSTOMER where BANK-ID = 1;
% ---------------------------------------------------------------------
%
%* filter EXAMPLEFILTER
%       -------------
%* default ALL    % return all records for datasets that do not have
%*                % a SELECT statement
%* select     * from BRANCH where BRANCH-ID = 2
%*               and BRANCH-NAM = "SOUTH MANHATTAN";
%* select     * from TELLER where BRANCH-ID = 2 and TL-CSH-OUT > 99.99;
%* select     * from ACCOUNT where FALSE; % no records at all
%* select     * from L1 where DS-NAME > "a" using L1-SS2;
% ---------------------------------------------------------------------
%
%* filter CERTAINFIELDS
%      -------------
%* default  NONE    % don't return any records for datasets that do
%*                  % not have a SELECT statement
%* select   BRANCH-ID BRANCH-AD1
%*                from BRANCH
%*                where BRANCH-ID > 1
%*                and BRANCH-NAM = "SOUTH MANHATTAN"
%*                and BRANCH-AD1 NEQ " ";
%* select FS-NAME from FUNNY-STUFF where FS-2; % FS-2 is a BOOLEAN
% ACCOUNT is a variable-format dataset
%* select 1: AC-TYPE AC-NUMBER CUST-ID AC-BALANCE
%*           BRANCH-ID AC-HLD-AMT
%*        3: ac-number AC-TYPE % lowercase data item OK
%*        2: ALL
%*        4: ALL EXCEPT AC-BALANCE
%*        0: AC-NUMBER AC-DT-CLSE
%*        else: none
%*    from ACCOUNT where BANK-ID = 1;
%* select MONTH, BANK-ID from TRIALBALANCES;
% ---------------------------------------------------------------------
%
%* filter WAREHOUSE
%      ---------
%     Discard any deletes, but keep creates and modifies
%* select * from HISTORY
%*          where PROC-DATE >= 000101
%*             and not UpdateType (Delete);
%* default all except TRIALBALANCES, FUNNY-STUFF, SHORT-VF
% ---------------------------------------------------------------------
%
%        Put additional filters here ...
%
% ---------------------------------------------------------------------
%
%                          External filters
%                          ================
%
%         EXTERNAL FILTER <filtername> IN "<librarytitle>"
%
%    The <librarytitle> is the title of an ALGOL library codefile
%    containing an EXPORTed filtering procedure called <filtername>.
%    The user must write the library program. Example:
%
%% external filter CUSTOMFILTER in "OBJECT/LOCAL/FILTERLIB"
%
% ---------------------------------------------------------------------
%
%                         Internal filters
%                         ================
%
%          INTERNAL FILTER <filtername> IN "<patchfiletitle>"
%
%     The <patchfiletitle> is the title of an ALGOL source file
%     containing a patch for Support that declares a filtering
%     routine whose name is <filtername>. Example:
%
%% internal filter CustomSelection
%% in "PATCH/DATABRIDGE/SUPPORT/LOCALFILTERING"
%
% ---------------------------------------------------------------------
%
%                        Error Manager
%                        =============
%
%       ERROR MANAGER <errormanagername> IN "<patchfiletitle>"
%
%   The <patchfiletitle> is the title of an ALGOL source file containing
%   an error handling entry point called <errormanagername> that will
%   replace the DBErrorManager entry point in Support. This entry point
%   can analyze an error and log it, display it, etc., and its return
%   value indicates whether the Accessory should continue processing or
%   terminate.
%
%   The entry point can be declared with the DBErrorManagerHead define
%   declared in DBInterface. The patch file can contain declarations
%   global to the error manager procedure that will persist until
%   Support terminates. Example:
%
%*       Error Manager ErrorHandler
%*               in "PATCH/DATABRIDGE/SAMPLE/SUPPORT/ERRORHANDLER"
%
% ---------------------------------------------------------------------
%
%                           Startup
%                           =======
%
%               STARTUP IN "<patchfiletitle>"
%
%   The <patchfiletitle> is the title of an ALGOL source file
%   containing a patch for Support that contains user-written code that
%   is to be executed when the Support library is initializing *before*
%   it freezes. The contents of the patchfile is inserted into a
%   procedure called CustomStartup. It may contain declarations as well
%   as statements. Any variables declared in the patchfile will be
%   discarded when CustomStartup exits unless they are declared OWN.
%   Example:
%
%*         Startup in "PATCH/DATABRIDGE/SAMPLE/SUPPORT/STARTUP"
%
% ---------------------------------------------------------------------
%
%                           Shutdown
%                           ========
%
%                SHUTDOWN IN "<patchfiletitle>"
%
%    The <patchfiletitle> is the title of an ALGOL source file
%    containing a patch for Support that contains user-written code that
%    is to be executed after the Support library thaws. The contents of
%    the patchfile is inserted into a procedure called CustomShutdown. It
%    may contain declarations as well as statements. Example:
%
%*         Shutdown in "PATCH/DATABRIDGE/SAMPLE/SUPPORT/SHUTDOWN"
%
% =================== End of GenFormat input ==========================

Creating a Format

The GenFormat parameter file can contain any number of formats. To create a format, type it in the GenFormat parameter using the syntax for declaring formats. See “FORMAT Syntax” on page69.

Declaring Internal and External Formats

Instead of using GenFormat to define your formats, you can write custom internal and external formats that you specify in the GenFormat parameter file. For more information on user-written formats, refer to the Databridge Programmer’s Reference.

Format types

There are two main types of formats: binary and display.

Binary formats, e.g. BINARYFORMAT and RAWFORMAT, don’t convert the data types of the data items in the DMSII database in the output record. For example, NUMBER items consist of 4-bit digits in the database and retain exactly the same 4-bit values in the formatted output record. These formats are declared with either the keyword BINARY or RAW preceding the keyword FORMAT.

Display formats, e.g. COMMAFORMAT and FIXEDFORMAT, convert the database data items into EBCDIC characters such that the output record is easily readable by any text editor. These formats are declared with either the keyword DISPLAY or VARYING preceding the keyword FORMAT. DISPLAY is the default format type.

Binary Value Conversions

All DISPLAY formats generated by GenFormat routines convert binary values to 11-digit items in the output. For example, the data item FIELD (nn) is a binary value where nn is the number of bits. Bits do not map cleanly to digits, however, so the binary value the bits represent are converted to 11-digit items.

This binary value conversion occurs for all GenFormat DISPLAY formats. The default format (RAWFORMAT), BINARYFORMAT, and any formats you write will not have the binary format conversion.

DMSII uses FIELD in two ways. As discussed above, FIELD (nn) is an integer of nn bits. The other way DMSII uses FIELD is as a GROUP of one-bit BOOLEANs, as in the following DASDL example:

APPLE-FLAGS FIELD
(RED-GREEN;
SWEET-TART;
SOFT-HARD);

Although a FIELD item with no specified number of bits can be treated as an integer, it functions as a group for the BOOLEANs RED-GREEN, SWEET-TART, and SOFT-HARD. In this case, the GenFormat format routines ignoreAPPLE-FLAGS and return the value of the BOOLEANs within it.

Boolean Values

You can specify the representation of Boolean values in each DISPLAY format. The default is to represent TRUE as 1 and FALSE as 0, both as unsigned values. To change this representation:

BOOLEAN leadingcharacters VALUE trailingcharacters
TRUE "string"
FALSE "string"

Where	Is
leadingcharacters	Optional. Any character, such as single or double quotes, that you want to place in front of the value returned from a Boolean expression.
`VALUE`	Required. A literal that indicates the value returned when a Boolean expression is evaluated.
trailingcharacters	Optional. Any character, such as single or double quotes, that you want to place after the value returned from a Boolean expression.
`TRUE` or `FALSE`	Required. The Boolean values TRUE or FALSE.
"string"	Required. Any alphanumeric character or characters you want to use to represent the Boolean values TRUE or FALSE. You must enclose the string in quotation marks.

Example 1

In the following example, the Y represents TRUE and the N represents FALSE. If the Boolean evaluates to TRUE, Y is returned.

BOOLEAN VALUE
TRUE "Y"
FALSE "N"

Example 2

In the following example, lowercase true represents TRUE, and lowercase false represents FALSE. If this Boolean evaluates to true, "true" (in double quotation marks) is returned. The double quotation marks are returned because this example uses the optional leading and trailing characters for Boolean values.

Note

Insert one space after the word true so that the literals "true" and "false" have the same length (five characters). This assures that the formatted records have the same length. Otherwise, GenFormat displays a warning.

Default Formats

This section summarizes the formats available in the sample GenFormat parameter file.

Format	Description
AUDITLOC	AUDITLOC inserts a prefix consisting of the time-of-day, the audit location (AFN, ABSN, Inx), and a change code in front of the record values.
BINARYFORMAT	BINARYFORMAT copies the binary image of each data item in the record, except for the following: Data items that are not in the filter Text items when the TRANSLATE option is specified
COMMAFORMAT	COMMAFORMAT includes prefix, data, and postfix and is similar to FIXEDFORMAT except that it puts double quotes around alpha items and a comma between all items. This format is suitable for many PC and UNIX import programs.
COMMAFORMATQUOTEALL	COMMAFORMATQUOTEALL includes prefix, data, and postfix. Like COMMAFORMAT, each item is delimited by commas. Unlike COMMAFORMAT, all items (alpha or not) are placed in double quotes. NOTE: COMMAFORMATQUOTEALL is commented out by default. If you want to use it, you must uncomment it.
FIXEDFORMAT	FIXEDFORMAT includes prefix, data, and postfix. FIXEDFORMAT converts each data item to an EBCDIC representation of a fixed width. This would be similar to a COBOL program moving each field to a PIC ... DISPLAY.
KEYFORMAT	KEYFORMAT lists the data items (by name and value) for a primary key.
NAMEFORMAT	NAMEFORMAT inserts the name of the data item and an equal sign in front of the value of each data item.
RAWFORMAT	RAWFORMAT copies the DMSII record as a binary image without any formatting or data item filtering. It provides a datastream that is exactly the same as the data stored on the host. RAWFORMAT is an alias for the default DBFORMAT, which formats records as a binary image of the record as it would appear to a COBOL program.
RSNCOMMA	RSNCOMMA is similar to COMMAFORMAT but uses BIGUID and BIGPUID, the 15-digit versions of UID and PUID, which can accommodate RSN values. The sample GenFormat parameter file defines additional formats that are commented out with “%” at the beginning of each line. You can quickly uncomment those formats by replacing the “%” character sequence with spaces.
SNAPSHOTCOMMA	SNAPSHOTCOMMA includes data only, no prefix or postfix. Like COMMAFORMAT, each item is delimited by commas and alpha items have double quotes.
SNAPSHOTFIXED	SNAPSHOTFIXED is the same as FIXEDFORMAT except that only data is included. There is no prefix or postfix.

FORMAT Syntax

You can use generated formats or user-written formats. Literals for defining these formats are in the section that follows.

Option	Default	Description
`PREFIX`	Nothing	Items inserted before the record. The possible values are listed in PREFIX and POSTFIX Codes.
`POSTFIX`	Nothing	Items inserted before the record. The possible values are listed in PREFIX and POSTFIX Codes.
`DATACHECK`	`TRUE`	Determines whether the format should contain code for validating data, such as checking for nulls, illegal characters, and integer overflows. Syntax: `DATACHECK [ TRUE \| FALSE ]` By setting `DATACHECK` to `FALSE`, the formatting routines will be smaller and execute faster (by about 5%). For example: `format NoCheck` `prefix STRNAME RECTYPE CHANGECODE` `postfix UID PUID` `DataCheck false` The Span and Snapshot Accessories can benefit from setting `DATACHECK` to `FALSE` especially if they use a `DISPLAY FORMAT` such as `FIXEDFORMAT`. (DBServer/Databridge Client will see very little improvement.) NOTE: The DATACHECK option is not valid for RAW formats.
`SEPARATOR`	Nothing	Identifies the separator to use between each item (column). The value specified here will separate each of the DATAITEMS selected from each DATASET. This value does not apply to PREFIX or POSTFIX.
`DECIMALPT`	Nothing	Identifies the decimal point character
`PADDING`	`NULL`	The character used to fill short records.
`POSITIVE`	VALUE	The format of a non-negative number. For more information, see DATANAME and VALUE. If you want the name of the data item in the output records, enter the keyword DATANAME, as follows: `POSITIVE` DATANAME = +VALUE
`NEGATIVE`	VALUE	The format of a negative number. See DATANAME and VALUE. If you want the name of the data item in the output,
enter the keyword DATANAME, as follows: `NEGATIVE DATANAME` = -VALUE
`UNSIGNED`	VALUE	The format of an unsigned number. See DATANAME and VALUE. If you want the name of the data item in the output, enter the keyword DATANAME, as follows: `UNSIGNED DATANAME` = VALUE
`TEXT`	VALUE	The format of an alphanumeric item. See DATANAME and VALUE. If you want the name of the data item in the output, enter the keyword DATANAME, as follows: `TEXT DATANAME` = "VALUE"
`TRANSLATE`	None	The name of a translation table defined in the Translations portion of the GenFormat parameter file. Translation tables are explained in Creating and Using Translation Tables.
`FLOAT`	`SCIENTIFIC (11)`	The format of a real number. Can be specified as `DECIMAL (w,d)` or `SCIENTIFIC (w)`. DECIMAL has a fixed number of decimal places, indicated by d. For example, `DECIMAL (12, 2)` means 12 total characters, two of which are to the right of the decimal point. Example: `#########.##` `SCIENTIFIC` uses exponential notation to represent a floating point number in a fixed width, indicated by w. For example, `SCIENTIFIC (11)` means 11 total characters in the following format: `#.#####E-##`
`OVERFLOW`	9	When you include the `OVERFLOW` option, an integer overflow replaces the field with the `OVERFLOW` character for the width of the field. If you do not specify an `OVERFLOW` character, the field will contain all nines and will be formatted normally.
`NULL`	Numbers: 0 Text: spaces	If specified and the field contains the DMSII defined NULL character(s), then the formatting routine will replace the field with the FORMAT-defined NULL character for the width of the field.

PREFIX and POSTFIX Codes

This topic includes a table of valid codes for the PREFIX and POSTFIX format options. You can use all of these codes in any combination.

Code	Description
STRNUM	Structure number of the data set, 4 digits
STRNAME	The 17-character data set name
RECTYPE	Type of record for variable-format data sets, 3 digits
CHANGECODE	A = add D = delete M = modify H = audit file header record L = link after-image N = link before-image S = state update X = documentation record
MODFLAG	1= if ADD was originally the after-image or DELETE was originally the beforeimage of a MODIFY 0 = otherwise
STACKNBR	Stack number of updating program, 4 digits
MODE	The state of the data set related to cloning, as follows: 0 = The data set is in the extract phase. 1 = The data set is in the fixup phase. 2 = The data set is in the update phase. 3 = The data set was reorganized. 4 = The data set was purged.
FORMATLEVEL	Data set format level, 4 digits
AFN	Audit file number, 4 digits
ABSN	Audit block serial number, 10 digits
SEG	Audit file segment number, 7 digits
INX	Audit block word index number, 5 digits
YYYY YY MM DD HH MN SS	Year, 4 digits Year, 2 digits Month, 2 digits Day, 2 digits Hour, 2 digits Minute, 2 digits Second, 2 digits NOTE:These time values represent an estimate of when an update occurred. The actual time of the update could be later than these values indicate.
UID	Unique ID (absolute address) of the record. The UID may not be present, depending on the type of data set. If the UID is present, it is a 12-digit number without leading or trailing characters.
BIGUID	For data sets having an RSN, the format will use the RSN as the BIGUID Unique ID (absolute address) of the record. The BIGUID may not be present,depending on the type of data set. If the BIGUID is present, it is a 15-digit number without leading or trailing characters. RSN is a synonym for BIGUID.
HEXUID	Unique ID (absolute address) of the record. The HEXUID may not be present, depending on the type of data set. If the HEXUID is present, it is a 12-digit hexadecimal number without leading or trailing characters.
PUID	Parent unique ID (parent absolute address) of the parent record. The PUID may not be present, depending on the type of data set. For example, a PUID is typically present for embedded data sets. If the PUID is present, it is a 12-digit number without leading or trailing characters.
BIGPUID	Parent unique ID (parent absolute address) of the parent record. The BIGPUID may not be present, depending on the type of data set. For example, a BIGPUID is typically present for embedded data sets. If the PUID is present, it is a 15-digit number without leading or trailing characters.
HEXPUID	Parent unique ID (parent absolute address) of the parent record. The HEXPUID may not be present, depending on the type of data set. For example, a HEXPUID is typically present for embedded data sets. If the HEXPUID is present, it is a 12-digit hexadecimal number without leading or trailing characters.
CR	Carriage return
LF	Line feed
SPACE	Space character
TAB	Horizontal tab character

DATANAME and VALUE

DATANAME

DATANAME is the name of the data item and the associated subscript used in conjunction with VALUE so that output has the format of data item=value. For example, for a data item named EMPLOYEE-ID (5), the output would be EMPLOYEE-ID.

VALUE

VALUE represents the EBCDIC representation of a data item. The following chart shows the number of bytes Databridge uses to format various types of data items.

Type	Size
ALPHA(n)	n characters, depending on the actual size of the data item
NUMBER(n)	n digits, depending on the actual size of the data item
NUMBER(Sn)	1 character (sign) + n digits
NUMBER(n, m)	1 character (decimal point) + n digits, of which m are to the right of the assumed decimal point
NUMBER(Sn, m)	1 character (sign) + 1 character (decimal point) + n digits, of which m are to the right of the assumed decimal point
REAL	1 character (sign) + w digits where w is from FLOAT SCIENTIFIC (w) or from FLOAT DECIMAL (w, d)
REAL(n)	11 digits
REAL(Sn)	1 character (sign) + 11 digits
REAL(Sn,m)	1 character (sign) + 1 character (decimal point) + 11 digits, of which m are to the right of the assumed decimal point
RECORDTYPE	11 digits
FIELD(n)	11 digits
BOOLEAN	1 character, as follows (by default): 0 = false 1 = true

FORMAT Example

The following example shows a FORMAT declaration:

format        COMMAFORMAT
%             -----------
% prefix; comma between each data item
This example uses the following formatting guidelines
PREFIX        STRNUM , RECTYPE , CHANGECODE ,
POSTFIX       UID PUID LF
SEPARATOR     ,
DECIMALPT     .
POSITIVE      +VALUE
NEGATIVE      -VALUE
TEXT          "VALUE"
PADDING       SPACE
FLOAT         SCIENTIFIC (11)             % #.#####E-##

The preceding example uses the following formatting principles:

As designated by the entry for PREFIX, each record will start with the structure number, record type, and change code. Each field of the prefix will also be separated by commas.
As designated by the entry for POSTFIX, each record will end with the absolute address (unique ID or UID), the parent unique ID (if present), and a line feed (LF).
All of the data within the record will be separated by commas as designated by the entry for SEPARATOR.
Positive numbers within the data will be formatted, for example, as +000120 (designated by the entry for POSITIVE).
Negative numbers within the data will be formatted, for example, as -000120 (designated by the entry for NEGATIVE).
The decimal point character is the period (.), as designated by the entry for DECIMALPT.
All text within the record will be enclosed in quotation marks, as designated by the entry for TEXT.
Any unused area at the end of a record will be filled with spaces, as designated by the entry for PADDING.
All real numbers within the record will use the scientific format, as designated by the entry for FLOAT.

Creating a Filter

By default, GenFormat allows all supported DMSII data sets and records to be replicated. You can create filters to limit the records that can be replicated. To create a filter, you must compile a tailored support library.

The GenFormat parameter file can contain any number of filters. The only predefined filter in the GenFormat parameter file is DISCARDALL, which discards every record. To create a filter using GenFormat, type the filter into the GenFormat parameter file using the syntax for declaring filters. See FILTER Syntax.

Declaring User-Written Filters

Instead of using GenFormat to define your filters, you can also write your own ALGOL filter (refer to the Databridge Programmer’s Reference for information about user-written filters), you must specify it when you declare the filter in the GenFormat parameter file.

There are three ways to declare user-written filters:

INTERNAL FILTER
EXTERNAL FILTER
$ INCLUDE

When you declare an INTERNAL, EXTERNAL, or $ INCLUDE filter, you cannot use any other filter options with that filter.

INTERNAL FILTER

Use the INTERNAL FILTER statement to include your user-written filter as a patch file when the Support Library is compiled. In an INTERNAL FILTER, you can declare a procedure name, a procedure heading, and global data. Using INTERNAL FILTER rather than the $ INCLUDE type of filter is preferred because it allows you to declare data global to the filter procedure and the procedure heading is in the patch file.

Use the following syntax to declare an INTERNAL FILTER:

INTERNAL FILTER filtername IN "patchfiletitle"

where patchfiletitle is the title of an ALGOL source file containing a patch for the Support Library that declares a filter whose name is filtername. Note that if you have Accessories running under a different usercode from where the Databridge software is installed and you want to use the automatic recompilation of the Support Library feature, you must include the usercode and pack name where the patch file resides in patchfiletitle.

EXTERNAL FILTER

Use the EXTERNAL FILTER statement to indicate that your user-written filter is an entry point in a library.

Use the following syntax to declare an EXTERNAL FILTER:

EXTERNAL FILTER filtername IN "librarytitle"

where filtername is the name you have given to the filter and libarytitle is the file title of your compiled ALGOL library code.

$ INCLUDE

Use the $ INCLUDE statement to include your user-written filter as a patch file when the Support Library is compiled. The included file must contain ALGOL for the body of the filter. GenFormat will automatically declare the procedure heading and the outer BEGIN and END.

Use the following syntax to declare an $ INCLUDE:

FILTER filtername $ INCLUDE "patchfiletitle"

where patchfiletitle is the title of an ALGOL source file containing a patch for the Support Library that defines a filter whose name is filtername. If you have Accessories running under a different usercode from where the Databridge software is installed and you want to use the automatic recompilation of the Support Library feature, you must include the usercode and pack name where the patch file resides in patchfiletitle.

FILTER Syntax

Filters use the following syntax:

FILTER filtername DEFAULT defaultoption SELECT statements

Where	Is
filtername	The name of the filter you will enter in Accessory parameter files when you want to use this particular filter. The name must start with a letter followed by letters, numbers, or underscores. There is no limit on the length of the filter name; however, it must fit on a single line.
defaultoption	An option that only affects data sets that are not included in a `SELECT` statement. Set defaultoption to one of the following: `ALL`, which indicates that Databridge should return all records for data sets that are not included in SELECT statements. `ALL EXCEPT` dataset1, dataset2, ..., which indicates that all datasets not having a `SELECT` statement are included in the filter except for dataset1, dataset2, etc. Example:filter PUBLIC select * from ORDERS where ORD-TOTAL < 10000 default all except SALARY, REVIEWS NOTE:In the preceding example, SALARY and REVIEWS are not visible to the Accessory using the PUBLIC filter. ANY, which is a synonym for ALL. NONE, which indicates that Databridge should return no records except those you specify in SELECT statements. UPDATETYPE (updatetype) [OR UPDATETYPE (updatetype)] where updatetype is CREATE, MODIFY, or DELETE. Example: DEFAULT UpdateType (Create) or UpdateType (Modify)
statements	The series of statements that actually filter the data items and records for each
specified data set. See SELECT Statement Syntax.

SELECT Statement Syntax

Enter the SELECT statements to specify the data sets and the records you want to be filtered. Use the following format:

SELECT filteritems FROM datasetname [WHERE expression] [USING set_or_subset]

Where	Is
`SELECT`	A required literal.
filteritems	One of the following: or the literal `ALL` to select all the data items in the data set. Note that if the `SELECT` statement specifies * or `ALL` for the item list of a variable format data set and no rectypenumber lists, then each variable format will return all items belonging to that format part. If the `SELECT` statement specifies a data item list without a rectypenumber, then that list applies to every variable format part. One or more data items from a fixed-format data set, as follows: `dataitem[,] dataitem[,] dataitem` One or more data items from a variable-format data set, as follows: `rectypenumber: dataitem[,] dataitem[,] dataitem[,]` `rectypenumber:` `rectypenumber: ALL` `[ ELSE: elseoption ]` NOTE: The elseoption can be `NONE`, `` , or `ALL`. If the elseoption is `NONE`, unlisted record types will not be in the dataset enumeration and no data records of those types will be sent to the Accessory. If elseoption is `` or `ALL`, unlisted record types will be in the dataset enumeration, and records that satisfy the `WHERE` clause will be sent to the Accessory. If the ELSE clause is not specified, it defaults to the filter’s DEFAULT option value.
`FROM`	A literal
datasetname	The name of the data set or remap from which you want to filter records.
`WHERE`	A literal
expression	One of the following: A data item from the data set followed by a relational operator and a value, as in the following examples: `WHERE dataitem = n;` `WHERE BANK-ID = 1;` `WHERE BRANCH-ID = 2 AND BRANCH-NAME = "SOUTH MANHATTAN";` A BOOLEAN data item, as in the following examples: `WHERE EMP-SALARIED;` `WHERE EMP-GENDER OR EMP-ACTIVE;` A type of update—CREATE, MODIFY or DELETE. Specifying an update type is useful for data warehousing, where sites don’t want to delete records. For example: `WHERE UPDATETYPE (Modify);` `WHERE DI-ORD-PLANT = 23 and not UpdateType (Delete);` An ALTERed data item. Specify the original attributes for the ALTERed data item. For example, if a data item was ALTERed from a NUMBER to an ALPHA, use the original numeric value in the WHERE clause, as follows: `WHERE dataitem = numericvalue` The DIV (integer division) or MOD (remainder) operators. This capability can be used to select representative sample records for testing purposes. For example: `WHERE CUST-ID MOD 5 = 1` NOTE: expression can also use the literal CONTAINS, as in the following syntax: `dataitem CONTAINS "string"` `WHERE alphadataitem CONTAINS "casesensitivestring"` The `CONTAINS` expression is true if the alpha data item contains the casesensitive string enclosed in double quotation marks. You must include the quotation marks, as in the following example: `WHERE ADDR-LINE1 CONTAINS "BOX" OR ADDR-LINE1 CONTAINS "RURAL ROUTE"`
`USING`	A literal.
set_or_subset	The name of an existing set or subset that points to the data set. DBEngine uses this during an extract to locate records in the data set, which means records will be extracted in the order specified by the key. You can decrease the time it takes to do the extract by specifying a subset that has relatively few records. If set_or_subset is the name of an automatic subset, the `WHERE` clause defined in the DASDL for the subset will be appended to expression. Therefore, the Accessory will receive only the records that satisfy both the subset and the `WHERE` clauses. If set_or_subset is the name of a set or manual subset, there are no changes to expression. If set_or_subset is the name of a manual subset, you must ensure that the manual subset actually contains all of the records satisfying the `WHERE` clause. DBEngine will not extract any records unless they are in the manual subset, but it will retrieve updates during the tracking phase for all records satisfying the `WHERE` clause, whether or not they are in the manual subset. If set_or_subset does not allow duplicates, it becomes the primary set. When DBEngine enumerates the sets of a data set, it includes the specified subset.

Filter Examples

Example 1

The following examples show how to select all records that contain a data item that meets the WHERE criteria. The data items can be selected only from the specified data set.

SELECT ALL FROM BANK WHERE REGION-ID = 10;
SELECT * FROM BRANCH WHERE BRANCH-NAME = "Pittsburgh"

Example 2

The following two examples show how to select one or more data items from a data set.

This example shows one data item to be selected from the data set FINANCIAL-STATUS. Note that FS- 2 is a Boolean.

SELECT FS-NAME FROM FINANCIAL-STATUS WHERE FS-2;

This example selects two data items (BRANCH-ID and BRANCH-AD1) for the data set named BRANCH.

SELECT BRANCH-ID BRANCH-AD1 FROM BRANCH
WHERE BRANCH-ID > 1
AND BRANCH-NAME = "SOUTH MANHATTAN"
AND BRANCH-AD1 NEQ " ";

Example 3

The following example shows how to select one or more data items from a variable-format data set.

SELECT % variable-format dataset
1: AC-TYPE AC-NUMBER CUST-ID AC-BALANCE
AC-STAT1 BRANCH-ID AC-HLD-AMT
2: AC-TYPE AC-NUMBER AC-STAT2
3: AC-NUMBER, AC-STAT3, AC-TYPE
5: *
0: AC-NUMBER AC-DT-CLSE
FROM ACCOUNT WHERE BANK-ID = 1;

The following examples build on the previous example, using the ELSE: clause (assuming ACCOUNT has a record type 4):

filter NoType4
%      -------
select 1: AC-TYPE AC-NUMBER AC-BALANCE AC-VF1-GROUP
BRANCH-ID AC-HLD-AMT
2: AC-TYPE AC-NUMBER AC-VF2-GROUP
3: AC-NUMBER AC-VF3-GROUP AC-TYPE
0: AC-NUMBER AC-DT-CLSE
% no type 4 in enumeration; no type 4 updates
else: none
from ACCOUNT where BANK-ID > 5000;
filter WithType4
%      ---------
select 1: AC-TYPE AC-NUMBER AC-BALANCE AC-VF1-GROUP
BRANCH-ID AC-HLD-AMT
2: AC-TYPE AC-NUMBER AC-VF2-GROUP
3: AC-NUMBER AC-VF3-GROUP AC-TYPE
0: AC-NUMBER AC-DT-CLSE
% type 4 is in enumeration; type 4 updates
% must satisfy the WHERE clause
else: *
from ACCOUNT where BANK-ID > 5000;
filter NoType4PerDefault
%     -----------------
default none
select 1: AC-TYPE AC-NUMBER AC-BALANCE AC-VF1-GROUP
BRANCH-ID AC-HLD-AMT
2: AC-TYPE AC-NUMBER AC-VF2-GROUP
3: AC-NUMBER AC-VF3-GROUP AC-TYPE
0: AC-NUMBER AC-DT-CLSE
% no type 4 in enumeration; no type 4 updates
from ACCOUNT where BANK-ID > 5000;
filter Type4PerDefault
%      ---------------
default all
select 1: AC-TYPE AC-NUMBER AC-BALANCE AC-VF1-GROUP
BRANCH-ID AC-HLD-AMT
2: AC-TYPE AC-NUMBER AC-VF2-GROUP
3: AC-NUMBER AC-VF3-GROUP AC-TYPE
0: AC-NUMBER AC-DT-CLSE
% type 4 is in enumeration; type 4 updates
% must satisfy the WHERE clause
from ACCOUNT where BANK-ID > 5000;

Transforms

A transform is a special routine used for populating VIRTUAL data sets or transforming an update in other ways.

A transform is a user-written procedure that is used by the Support Library. A transform has access to both the before- and after-images at the same time.

The following transforms are predefined in the Support Library:

ChangedRecordsOnly—Discards records if none of the data items allowed by the filter are modified.
ChangedItemsOnly—Discards unmodified data items. The Accessory receives only the key items and data items that changed. Note that this transform is not supported by the Databridge Client.

Refer to the Databridge Host Programmer’s Reference for instructions on creating transforms.

Error Manager

The Support Library contains a default error manager that displays all error messages. If desired, you can write a custom error manager that, for example, analyzes an error and logs it, displays it, and determines whether the Accessory should continue processing or terminate. To use a custom error manager, you must write the error manager and then declare it in the GenFormat parameter file. Refer to the Databridge Host Programmer’s Reference for instructions on writing a custom error manager.

Use the following syntax to declare a custom written error manager in the GenFormat parameter file:

ERROR MANAGER errormanagername IN "patchfiletitle"

where errormanagername is the name you have given to the error manager and patchfiletitle is the file name of the ALGOL patch file containing the error manager.

ALTER and VIRTUAL Data Sets.

Refer to the Databridge Host Programmer’s Reference for instructions on creating ALTER or VIRTUAL data sets.

ALTER Data Set

Use the ALTER declaration when you want to reformat data items in a data set to different layouts (i.e., data item conversion). If you want to change date formats and are using Databridge Clients, however, it is often less expensive to use the date formats provided by the Databridge Client software. Common uses of the ALTER declaration include the following:

Subdividing items.
Merging adjacent items in the same parent group
Formatting dates that cannot be done in the Client

VIRTUAL Data Set

VIRTUAL data sets allow you to create a structure that does not physically reside in the DMSII database, while appearing as a normal data set to the Accessories.

When to Use Primary Keys

DBEngine supports data sets whether or not they have unique key sets. Accessories, on the other hand, support data sets as follows:

Span does not require that data sets have unique key sets.
Snapshot requires data sets that don't have valid AAs, such as ORDERED and COMPACT, to have a unique key set. If the dataset does not have a unique key set, you can define a primary key via the GenFormat program.
Databridge Clients require that data sets have unique key sets or valid AAs or RSNs. Use the GenFormat program to define primary keys for data sets, or set the key items manually in the client control tables.

Creating a Primary Key.

Declare a primary key in the following circumstances:

For VIRTUAL data sets that you want Databridge to update. Declaring the primary key allows Databridge to update the records in the VIRTUAL data set.
For data sets where Databridge requires a unique key set, but the unique key set does not exist in the DMSII DASDL. Declaring the primary key satisfies the Databridge requirements, without any DASDL modifications.

To create a primary key, GenFormat allows you to specify the data items for a data set that form a primary key.

Caution

Databridge does not check the validity of the primary key you define. It is your responsibility to choose a primary key that is unique for all records in the data set. Failure to do so could result in duplicate or lost records.

Primary Key Syntax.

Syntax: PRIMARY KEY OF dataset IS (keyitems)

Where	Is
`PRIMARY`	An optional word
`KEY`	A required word
`OF`	An optional word
dataset	The name of the VIRTUAL data set that you declared in the GenFormat parameter file -or- A data set in the DMSII database
`IS`	An optional word
keyitems	One or more data items that will make a unique key. Separate each data item with a comma. The parentheses are required.

Example:

The following example uses all of the key words and only one data item:

Primary Key of CUSTOMER is (CUST-ID)

The following example does not use the optional key words; it does, however, use a combination of data items to create a primary key.

KEY ORDER-DETAIL
(
ORD-NBR,
LINE-NBR
)

Creating and Using Translation Tables..

The formatting routines you create can use translation tables to translate individual EBCDIC characters in text (ALPHA) data items. This is useful for converting between international character sets.

Syntax for Creating Translation Tables..

Syntax:

TRANSLATION tablename sourcevalue -> destinationvalue

Where	Is
tablename	The name of a table you create. The name must start with a letter followed by letters, numbers, or underscores. This is the name you will enter for the TRANSLATE option in the FORMAT declaration.
sourcevalue	The value that you want to translate. This value can be in any of the following forms: Decimal value of a character Hexadecimal value of a character, 0xnn where n is 0–9 or A–F Quoted character
->	The required characters between the source value and the destination value.
destinationvalue	The replacement value for the source. This value can be in any of the following forms: Decimal value of a character Hexadecimal value of a character, 0xnn where n is 0–9 or A–F Quoted character

Example:

Translation CRToLF % Convert Carriage Return to Line Feed
013 -> 037 %? ->?

—or—

0x0D -> 0x25

The percent sign (%) designates a comment.

Syntax for Using Translation Tables.

The GenFormat parameter file supplies you with several translation tables. To use a translation table, you must add the translation table name to a FORMAT, as in the following example

FORMAT formatname translate translationtablename . .

where translationtablename is the name of a translation table. The following translation tables are predefined in the DATA/GENFORMAT/SAMPLE/CONTROL file:

Translation Table	EBCDIC Translation Table
CRToLF	N/A
UnitedKingdom	UnitedKingdomEBCDIC
Denmark	DenmarkEBCDIC
Finland	FinlandEBCDIC
France	FranceEBCDIC
Germany	GermanEBCDIC
Italy	ItalyEBCDIC
Norway	NorwayEBCDIC
Spain	SpainEBCDIC
Sweden	SwedenEBCDIC
SwissFrench	SwissFrenchEBCDIC
SwissGerman	SwissGermanEBCDIC