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:
FILE LINE (KIND=DISK, TITLE=datafilename,
PROTECTION=SAVE)
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
-
Using CANDE or another editor, open the sample Lister parameter file (
DATA/LISTER/SAMPLE/CONTROL). -
Save the sample parameter file as follows:
DATA/LISTER/databasename/CONTROLwhere 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.
-
Start Lister using the following syntax.
Note
For a description of the Lister WFL runtime options, see Lister WFL.
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.
-
Print or view the report generated by Lister. By default it is named as follows:
DBBD/RUN/LISTER/databasename— or —
DBBD/RUN/LISTER/logicaldatabasenameFor an example and explanation of this report, see Lister Report.
Example:
The following command:
START WFL/DATABRIDGE/LISTER ("(PROD)INVENTORY ON DEVPACK")indicates that Lister should use the following file:
(PROD)DESCRIPTION/INVENTORY ON DEVPACKThe Lister printer file will be named as follows:
DBBD/RUN/LISTER/INVENTORY/=
Lister WFL
You can modify the Lister WFL for the following:
- STARTTIME
- 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.
NAMES ONLY
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.
PARENT
Syntax: PARENT [ = ] [ TRUE | FALSE ]
Default: TRUE
PARENT shows the name and number of the parent data set if the data set is embedded.
MAX RECORDS
Syntax: MAX RECORDS [ = ] [ TRUE | FALSE ]
Default: FALSE
MAX RECORDS shows the upper bound estimate of the number of records in a data set.
Note
The MAX RECORDS option is ignored if the NAMES ONLY option is set to TRUE.
SETS
Syntax: SETS [ = ] [ TRUE | FALSE ]
Default: TRUE
SETS lists the sets associated with each data set.
SUBSETS
Syntax: SUBSETS [ = ] [ TRUE | FALSE ]
Default: FALSE
SUBSETS lists the subsets associated with each data set.
KEYS
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:”.
Note
The KEYS option is ignored if the SETS option is set to FALSE.
DATAITEMS
Syntax: DATAITEMS [ = ] [ TRUE | FALSE ]
Default: TRUE
DATAITEMS lists the data items contained in each data set.
NULL
Syntax: NULL [ = ] [ TRUE | FALSE ]
Default: FALSE
NULL shows the NULL value for each data item.
COMMENTS
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 %.
FILTER
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.
SUPPORT
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.
If you are using the default Support Library (OBJECT/DATABRIDGE/SUPPORT), leave this field as is.
DATASET
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.
%
% Module: DATA/LISTER/SAMPLE/CONTROL
%
% 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
%
% MAX RECORDS [=] [TRUE/FALSE]
% 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
%
% DATAITEMS [=] [TRUE/FALSE]
% 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
Filter DBFILTER
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
|
| 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
|
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 7.0.0.001 compiled Saturday, March 10, 2021 @ 13:12:17
Reading parameter file (DB66)DATA/LISTER/BANKDB/CONTROL ON USER
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
Support = OBJECT/DATABRIDGE/SUPPORT
#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
DBTWIN-RECTYPE
#0003 Set: DBTWINSET
Key: DBTWIN-STRNUM
DBTWIN-RECTYPE
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