Skip to content

Chapter 8: Lister

This chapter explains how you can use the Databridge Lister Accessory to create reports about your DMSII database. For information about additional reports that you can generate, see DBInfo Utility.

How Lister Works

Lister reads a DMSII DESCRIPTION file and a parameter file to produce a report describing the data definition of a DMSII database (database layout). This report also lists the structure numbers of the data sets you want to replicate. These structure numbers appear in the Span parameter file.

The Lister report lists all the data sets in the DMSII database. Note that if you are using a tailored support library, data sets excluded by a filter will not appear on the report.

In addition to the data set structure number, the report shows information for formatting routines, such as offsets and sizes, and the name of the Support Library used to generate the report. By default, the report is written to a printer file, but you can file equate the output device by modifying the WFL. For example, to write the report to a data file, equate the FILE LINE as follows:


where datafilename is the name of the data file to which the report will be written.

Run the Lister Accessory

Use the following procedure for running Lister to produce a database layout report. You can run Lister at any time.

To run Lister

  1. Using CANDE or another editor, open the sample Lister parameter file (DATA/LISTER/SAMPLE/CONTROL).

  2. Save the sample parameter file as follows:


    where databasename is the name of the database or logical database from which you plan to create the report. 3. Edit the new Lister parameter file (DATA/LISTER/databasename/CONTROL), and set report options. See the Lister Parameter File for an explanation of each option.

  3. Start Lister using the following syntax.


    For a description of the Lister WFL runtime options, see “Lister WFL” on page166.

    START WFL/DATABRIDGE/LISTER ("databasename")

    — or —

    START WFL/DATABRIDGE/LISTER ("databasename", "logicaldatabasename")

    The logicaldatabasename parameter provides a means for having multiple parameter files for the same database. If logicaldatabasename is the name of a logical database within the databasename database, Lister uses that logical database. Otherwise, it simply uses the logicaldatabasename as a way to specify an alternate parameter file (DATA/LISTER/databasename/logicaldatabasename/CONTROL). Lister then creates a report, which it directs to a printer file.

  4. Print or view the report generated by Lister. By default it is named as follows:


    — or —


    For an example and explanation of this report, see Lister Report.


    The following command:


    indicates that Lister should use the following file:


    The Lister printer file will be named as follows:


Lister WFL

You can modify the Lister WFL for the following:

  • QUEUE—If you want this job to enter the system through job queue 10, you must modify the WFL to include the QUEUE (or CLASS) = 10 declaration.
  • BDNAME—This is the default file naming convention for the printer file.

Lister Parameter File

Lister reads the Lister CONTROL parameter file to determine the amount and type of information on the Lister report.

Note the following for the format of the Lister parameter file:

  • The parameters in the parameter file can be in any order.
  • You can list multiple parameters on a single line.
  • You can split parameters 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 remainder of this section describes the syntax and semantics of each parameter. Enter the parameters in the Lister parameter file, following the commented section that describes each parameter.


Syntax: NAMES ONLY [ = ] [ TRUE | FALSE ] Default: FALSE

NAMES ONLY lists only the names of the DMSII database data sets. Note, however, that you can use this option in combination with any other Lister option except MAX RECORDS. (The MAX RECORDS option is ignored if the NAMES ONLY option is set to TRUE.) For example, if you set NAMES ONLY to TRUE and set SETS to TRUE, you will create a report that contains a list of the Database DMSII data sets names and the sets associated with each data set.


Syntax: PARENT [ = ] [ TRUE | FALSE ] Default: TRUE

PARENT shows the name and number of the parent data set if the data set is embedded.


Syntax: MAX RECORDS [ = ] [ TRUE | FALSE ] Default: FALSE

MAX RECORDS shows the upper bound estimate of the number of records in a data set.


The MAX RECORDS option is ignored if the NAMES ONLY option is set to TRUE.


Syntax: SETS [ = ] [ TRUE | FALSE ] Default: TRUE

SETS lists the sets associated with each data set.


Syntax: SUBSETS [ = ] [ TRUE | FALSE ] Default: FALSE

SUBSETS lists the subsets associated with each data set.


Syntax: KEYS [ = ] [ TRUE | FALSE ] Default: TRUE

KEYS lists the data items that compose the keys of each set and also list any KEY DATA items declared in the set. The KEY DATA items will appear below the keys list, introduced with the literal “Data:”.


The KEYS option is ignored if the SETS option is set to FALSE.


Syntax: DATAITEMS [ = ] [ TRUE | FALSE ] Default: TRUE

DATAITEMS lists the data items contained in each data set.


Syntax: NULL [ = ] [ TRUE | FALSE ] Default: FALSE

NULL shows the NULL value for each data item.


Syntax: COMMENTS [ = ] [ TRUE | FALSE ] Default: FALSE

If the COMMENTS option is TRUE, Lister will report DASDL- specified comments for structures and data items on the next line with a leading %.


Syntax: FILTER filtername

where filtername is the name of any filter generated by GenFormat.

This option specifies the name of a filtering procedure, which is an entry point in a tailored Support Library. Lister calls the tailored Support Library to filter each data set specified in the filter. Data sets excluded by a filter will not appear on the Lister report.

Your entry for SUPPORT, explained next, determines which library Lister calls.


Syntax: SUPPORT "libraryname"

Type the name of the tailored Support Library for the database for which you want the Lister report. The filter name you enter for FILTER must be compiled in the tailored Support Library you specify for SUPPORT. If you have not created a tailored Support Library yet, see “Chapter 4: Support Library” on page43.

If you are using the default Support Library (OBJECT/DATABRIDGE/SUPPORT), leave this field as is.


Syntax: DATASET datasetname Default: List every data set

DATASET names the data set for which you want to run Lister. For Lister to report on more than one data set, enter DATASET datasetname as often as you want. For Lister to report on all data sets, make sure that DATASET is commented out.

Sample Lister Parameter File.

%  (C) Copyright 2021 Micro Focus or one of its affiliates.
%  Project: Databridge
%  Description: Databridge Lister Sample Parameter File
%  (C) Copyright 2021 Micro Focus or one of its affiliates.
%  Syntax: (Options may appear in any order.)
%        NAMES ONLY [=] [TRUE/FALSE]
%               structure names only--no structure numbers, levels,etc.
%               This option sets the SETS, KEYS, DATAITEMS, and
%               PARENT options to FALSE.
%               default: FALSE
%        PARENT [=] [TRUE/FALSE]
%               show structure number and name of parent dataset
%               for embedded datasets.
%               default: TRUE
%               show estimated maximum number of records in datasets;
%               default: FALSE
%        SETS [=] [TRUE/FALSE]
%               list sets associated with datasets;
%               default: TRUE
%        SUBSETS [=] [TRUE/FALSE]
%               list subsets associated with datasets;
%               default: FALSE
%        KEYS [=] [TRUE/FALSE]
%               list key items and KEY DATA items of sets and subsets;
%               ignored if SETS = FALSE;
%               default: TRUE
%               list data items for each dataset; ignored if DATASETS =
%               FALSE;
%               default: TRUE
%        NULL [=] [TRUE/FALSE]
%               show NULL value for each data item; ignored if
%               DATAITEMS = FALSE;
%               default: FALSE
%        COMMENTS [=] [TRUE/FALSE]
%               show DASDL comments for structures and data items,
%               if any;
%               default: FALSE
%        FILTER filtername
%               apply the filter to the datasets and data items returned
%        SUPPORT "libraryname"
%               location of the filter
%        DATASET [=] datasetname
%               list this dataset; not every dataset
%               this option may be repeated for all desired datasets
Names Only = false
Parent = true
Max Records = false
Comments = false

Sets = true Subsets = false Keys = true

Dataitems = true Null = false

Support "OBJECT/DATABRIDGE/SUPPORT" % add .../dbname if filtering

% Dataset = CUSTOMER
% Dataset = ACCOUNT

Lister Report

Following is a brief explanation of the main parts of the Lister report. Note that the report uses standard DMSII terms such as set, key, data type, offset, etc.

Dataset Each data set is identified by its structure number and its name. In addition, the following information may appear:

Column and Description
  • Format level: The DMSII update (format) level.
  • RecType: The record type value for a variable format data set. Note that RecType does not appear for fixed format data sets.
  • RecSz: The size of the record in words. Words is a common way of expressing size on a ClearPath NX, LX, or A Series host. You can convert words into bytes as follows:

    1 word = 6 bytes
  • MaxRecs: This is an upper bound record count estimate; it is not meant to be an accurate count of the records. Note that the MaxRecs count appears only when you set MAX RECORDS = TRUE.
Set Sets are listed underneath their parent data set name and before its data item list, if included. Each set is identified by the set structure number and set name. Lister also reports if the set allows duplicates.
Subset Subsets are listed after any sets and before the data item list, if included. Each subset is identified by the subset structure number and subset name. Lister also reports if the subset allows duplicates.
Key Keys are listed underneath their set or subset. Descending keys will be labeled as “Descending.”
DataItems The next several lines list the data items in the data set. The columns are explained in the following table.

Column Title and Description
  • Num: Data item number.
  • Name: Data item name. An asterisk (*) in front of the name indicates that it is a required item, i.e. it cannot be null.
  • Type: Type of data item, which can be one of the following: Number, Alpha, Binary, Boolean, Field, Group, Image, RecType, Link, and Kanji (for WIDE (n)).
  • Offset: Offset to the data item in digits (half-bytes). Offsets indicate the location of a data item in a record formatted by BINARYFORMAT. If the offset is a relative offset, rather than an absolute offset, a “+” precedes the number. Items in a group having an OCCURS clause have relative offsets. If the offset is a raw offset as opposed to a formatted offset, a "@" precedes the number.
  • Size: The physical size of the data item in 4-bit digits (half-bytes). Compare this to DecSz, which is a user declared size.
  • DecSz: The user-declared size of the item in the length of the field. The units of length vary according to the field type, as follows:

    NUMBER type is 4-bit digits (same as half-byte)
    ALPHA type is bytes
    GROUP is 0

    Compare this to the Size column (explained above). The Size column shows the physical size of the data item in 4-bit digits.
  • Decs: If the data item is numeric, the Decs column shows the number of digits to the right of the assumed decimal point. If the numeric has no decimals, the Decs field is blank.

    If the data item is Boolean, the Decs column shows the number of the bit within the four bit digit that contains the value of the Boolean. If the Decs field is blank, the bit number is zero.
  • Sign: If the data item is numeric, an S indicates it has a sign; if the numeric has no sign, the field is blank.
  • Occurs: The data item OCCURS value. For example, a data item called MONTH could occur 12 times.
  • Subs: The number of subscripts the data item requires for occurring items or groups. For example, an occurring data item within an occurring GROUP would have a SUBS = 2.
  • Target: The structure number referenced by a link item. The example Lister report does not show the Target column because Links were not enabled for the database.

Sample Lister Report

Following shows a partial sample report where the parameter file contained the settings shown in the Lister Report.

Databridge Lister Report for BANKDB using (GPC)DESCRIPTION/BANKDB ON USER
     Created Friday, March 18, 2021 @ 14:39:55
     Version compiled Saturday, March 10, 2021 @ 13:12:17


List Options
Names only    = False
Max records   = False
Comments      = False
Parent        = True
Sets          = True
Subsets       = False
Keys          = True
DataItems     = True
Null          = False
Links         = False
Filter        = DBFILTER

#0001 Dataset: BANKDB Format level 0 ItemCount 37 RecSz 10
Num   Name         Type  Offset  Size  DecSz  Decs Sign   Occurs  Subs
3     GLB-REAL      Float      0     12       0        S
4     GLB-ALPHA     Alpha     12     30      15
5     GLB-TS        Float     42     12       0        S
6     GLB-BANK-NAME Alpha     54     60      30
7     GLB-FIELD     Field    114      3      10
8     GLB-BOOLEAN   Boolean  117      1       1
9     GLB-FLAGS     Field    118      1       2
10    GLB-F1        Boolean  118      1       0        1
11    GLB-F2        Boolean  118      1       0

#0002 Dataset: DBTWINCONTROL Format level 0 ItemCount 13 RecSz 13
           Primary Key: DBTWIN-STRNUM
#0003      Set: DBTWINSET
           Key: DBTWIN-STRNUM
Num  Name                Type   Offset  Size  DecSz  Decs  Sign  Occurs  Subs
1*   DBTWIN-STRNUM       Binary       0     12     11          S
2*   DBTWIN-RECTYPE      Binary      12     12     11          S
3    DBTWIN-AFN          Binary      24     12     11          S
4    DBTWIN-ABSN         Binary      36     12     11          S
5    DBTWIN-SEG          Binary      48     12     11          S
6    DBTWIN-INX          Binary      60     12     11          S
7    DBTWIN-TIME         Float       72     12      0          S
8    DBTWIN-MODE         Binary      84     12     11          S
9    DBTWIN-FORMAT-LVL   Binary      96     12     11          S
10   DBTWIN-TABLE-LVL    Binary     108     12     11          S
11   DBTWIN-ITEM-COUNT   Binary     120     12     11          S
12   DBTWIN-OPTIONS      Binary     132     12     11          S
13   DBTWIN-HOST-INFO    Binary     144     12     11          S

#0004 Dataset: RG Format level 0 ItemCount 4 RecSz 10

      Remap of BANKDB
Num   Name          Type   Offset   Size   DecSz   Decs   Sign   Occurs   Subs
1     RG-REAL       Float       0      12    0             S
2     RG-ALPHA      Alpha      12      30   15
3     RG-TS         Float      42      12    0             S
4     RG-BANK-NAME  Alpha      54      60   30

#0005 Dataset: MASTER-DS Format level 0 ItemCount 3 RecSz 1
         Primary Key: MST-ITEM
#0010    Set: MASTER-SET
         Key: MST-ITEM
Num   Name       Type   Offset   Size   DecSz   Decs   Sign   Occurs   Subs
1*    MST-ITEM   Alpha       0        12       6

#0006 Dataset: ORDERED-DS Format level 0 ItemCount 2 RecSz 2
#0005   Parent: MASTER-DS
        Primary Key: ORD-ITEM
#0007   Set: ORD-ACCESS
        Key: ORD-ITEM
Num    Name      Type   Offset   Size   DecSz   Decs   Sign   Occurs   Subs
1*     ORD-ITEM  Number      0       12       12
2      ORD-NAME  Alpha      12        6        3