Using the Data Browser

This document covers the following topics:


General Information

With the data browser, you can quickly and easily issue database queries against Adabas and SQL databases. You can use the data browser during application development to find out whether the application works properly. Or you can simply use it to find out which data has been stored in a database.

So that you are able to generate data reports from Adabas or SQL databases which are available in your current Natural server environment, an appropriate DDM is required for each database file.

Creating a Report Template

To get a report from a database, a template is required which specifies the database fields that are to be retrieved from the database. You create (or edit) a so-called "report template" which defines the required fields. The report template is stored for further use in the Eclipse workspace.

Start of instruction setTo create a report template

  1. In the Project Explorer view or in the Natural Navigator view, select the DDM for which you want to define a new report.

  2. From the context menu, choose Browse Data.

    Or:
    From the File menu, choose New > Other. In the resulting New dialog box, expand the Natural node, select Browse Data and then choose the Next button.

    The following dialog box appears.

    New report template for data browser

  3. Enter a name for the report template.

  4. Choose the Finish button.

    The selected DDM is now validated on the Natural server.

    It may happen that there are differences between the local DDM and the DDM on the server (for example, when the DDM on the server has been changed in the meantime and therefore has a different version). It may also happen that the DDM is no longer available on the server or that it is not cataloged on the server. The corresponding information is then provided, for example, in the Properties view and/or in the Problems view.

    When the DDM has been validated, a new report template for the selected DDM is opened in the editor area. For further information, see About the Data Browser Editor.

    Note:
    The Adabas file which is referenced in the DDM may be protected. In this case a dialog to specify the Adabas password is displayed.

    The new report template is an XML file that is stored in the RES folder of the library which contains the DDM that you have selected.

About the Data Browser Editor

The report templates are edited using the data browser editor. This editor is invoked when you create a new report template or when you open an existing report template.

The data browser editor is a multi-page editor which provides the following pages:

Selecting the Fields for the Report

The Fields page of the data browser editor shows a tree structure with the fields of the DDM. Example:

Report template for data browser - fields

By default, no fields are selected.

The following general fields are shown at the top of the tree, before the DDM name:

  • .COUNTER
    When selected, the records are numbered in the sequence in which they are read from the database. This number is then shown in the report. This feature is available as of Natural Development Server Version 2.2.6.

  • *ISN
    This corresponds to the Natural system variable *ISN. When selected, the internal sequence number (ISN) of a record is shown in the report. This field is only available for Adabas and Tamino databases. This feature is available as of Natural Development Server Version 2.2.6.

Groups can be expanded and collapsed. For a multiple field, the indices of the separate dimensions are indicated in parentheses. For a group, only an asterisk is shown in parentheses to indicate that this is a multiple group.

Note:
Under Additional DDM Fields, you can see the fields which are available in the current DDM, but which are not available in the report template. This may only happen when you have selected a different DDM on the Report page. See Setting Options for the Report.

Start of instruction setTo select the fields for the report

  1. In the tree structure of the Fields page, activate the check box for each field and/or group that you want to include in the report.

    When you activate the top-most check box of the DDM (next to the DDM name), all DDM fields are automatically selected.

    When you activate the check box for a group, all individual fields and subgroups that belong to the group are automatically selected.

    Each selected field is shown on the right side of the Fields page.

    If you want to remove a selected field, simply deactivate the corresponding check box in the tree structure.

  2. Optional. In order to design the report, you can arrange the sequence of the selected fields individually. To do so, select one or more fields on the right side of the Fields page and drag them to the desired positions.

    As long as you do not change the sequence of the selected fields, any new fields that you select are inserted in the same sequence as in the tree structure. However, if the selected fields have already been arranged individually, further fields that are selected in the tree structure are always added at the end of the list. Thus, the individual sequence is not corrupted.

    In the list of selected fields, you can choose Reset from the context menu. This rearranges the selected fields in the same order as in the tree structure.

  3. Optional. When you select a field (either in the list of available or selected fields), information on this field is shown in the Properties view. Some field properties have modifiable options. See Displaying the Properties for a Field for further information.

Displaying the Properties for a Field

The Properties view shows additional information for the entry which is currently selected on the Fields page of the data browser editor.

For the DDM, the following information is shown: database ID, file number, type (for example, Adabas) and DDM name (long name).

For a field, the following information is shown:

Properties

Option Description
Name Name of the field.
Type Type of field:

Elementary field.
Group (G).
Multiple-value field (M).
Periodic group (P).

Level Level number assigned to the field.
Format Natural data format of an elementary field, such as "Alphanumeric (A)".
Length Length of an elementary field.
Descriptor Descriptor type:

Elementary descriptor (D).
Hyperdescriptor (H).
Non-descriptor (N).
Phonetic descriptor (P).
Subdescriptor or superdescriptor (S).

When a descriptor is not defined, this text box is blank.

Edit mask

Two text boxes are shown for the edit mask.

The first text box shows the value that is defined in the DDM. This is the default edit mask to be used when the field is output, for example, with a DISPLAY statement. This value cannot be modified.

The second text box (under the heading User-defined properties) is modifiable. This edit mask is used in the report in order to show the values of a field.

When the DDM-defined or user-defined edit mask is to be used in the report, you must also set the corresponding option on the Report page of the data browser editor. See Setting Options for the Report.

Header

Two text boxes are shown for the header.

The first text box shows the value that is defined in the DDM. This is the header to be produced for each field specified in a DISPLAY statement. This value cannot be modified.

The second text box (under the heading User-defined properties) is modifiable. You can specify a user-defined header for this field.

When the DDM-defined or user-defined header is to be used in the report, you must also set the corresponding option on the Report page of the data browser editor. See Setting Options for the Report.

Occurrence n

Only shown for a multiple field. The range that is to be used in the report can be modified. You can specify a different start value and a different end value for the range. This feature is available as of Natural Development Server Version 2.2.4.

Note:
When the preference to Use maximum number of occurrences is selected, the defined number of occurrences for multiple fields and periodic groups in the Predict file for the Adabas DDM are used. If no Predict file is defined or Predict is not installed on the server, the maximum number of occurrences for a multiple field (191) or periodic group (91) is used. See also Data Browser in Setting the Preferences.

Caution:
If you specify a large range, this may result in a long waiting time.

Setting Options for the Report

Optional. When you have selected the fields that are to be included in the report, you can set several options. This is done on the Report page of the data browser editor.

Report template for data browser - report

You can set the following options:

Option Name Description
Filter
Field

The report is sorted according to the value that is selected in this drop-down list box. By default, the records are read as they stand physically in the file (physical read).

You can select another sorting criterion from this drop-down list box. The drop-down list box provides for selection the ISN and all descriptors that are defined in the DDM (including subdescriptor and superdescriptor).

Start value / End value The range of values of the descriptor field can be defined by a start value and/or by an end value. If only an end value is defined, the start value is set to the format-dependent default initial value (for example, it is set to blank for format A or to 0 for format N). The start value must be less than the end value.
Maximum results All filter criteria can be further limited by entering an absolute record limit (the default setting is 100 records). Regardless of the filter criteria, only the corresponding number of records is written to the report. By entering 0 (zero), the record limit is switched off.
Options
Edit mask The edit masks to be used in the report. This drop-down list box provides for selection the following options:
  • None
    Edit masks are not used for the fields in the report.

  • DDM-defined
    For all fields in the report, the edit masks as defined in the DDM are used.

  • User-defined
    For all fields in the report, the edit masks as defined in the Properties view are used. See Displaying the Properties for a Field.

  • User- or DDM-defined
    For all fields in the report, the user-defined edit masks as defined in the Properties view are used. When a user-defined edit mask cannot be found for a field, the edit mask as defined in the DDM is used. When a DDM-defined edit mask cannot be found, no edit mask is used for this field.

Field header The column headers to be used in the report. This drop-down list box provides for selection the following options:
  • None
    Field headers are not used as column headers. Instead, the field names are used as the column headers.

  • DDM-defined
    The field headers as defined in the DDM are used as the column headers.

  • User-defined
    The field headers as defined in the Properties view are used as the column headers. See Displaying the Properties for a Field.

  • User- or DDM-defined
    The user-defined field headers as defined in the Properties view are used as the column headers. When a user-defined field header cannot be found, the field header as defined in the DDM is used as the column header. When a DDM-defined field header cannot be found, the field name is used as the column header.

Report Information
Description A brief description for the report. You can specify any description you like.
Created at Shows the date and time when the report definition was created.
DDM and Server Information
DDM

Shows the path to the DDM to which this report definition pertains. When you choose the DDM action, this DDM is opened in the DDM editor.

Using the Browse button, you can also use another DDM with the current report definition. When you select a DDM which is not suitable for the current report definition, errors and/or warnings are shown in the Properties view and in the Problems view. On the Fields page of the data browser editor, the errors and warnings are indicated by corresponding icons, and all fields that are not available in the report definition are listed under Additional DDM Fields.

DDM name Shows the name of the DDM to which this report definition pertains.
Host name Shows the name of the host on which the DDM is located.
Port number Shows the port number on the above host.
Actions
Calculate Report When you choose this action, the number of records is calculated and shown on this page.
Create Report When you choose this action, the report is created. See also Creating the Report.

Creating the Report

When you have selected the fields that are to be included in the report (and when you have set any optional report options), you can create the report.

Start of instruction setTo create the report

  • Choose the following button which is shown at the top of the data browser editor (it is available on the Fields page and on the Report page):

    Create report

    Or:
    On the Report page, choose the Create Report action.

    The report is generated. It is shown in the Report Data view. Example:

    Report data

    Note:
    This view is automatically opened when you create a report. It is not shown by default when you open the NaturalONE perspective. See also Showing a View of the NaturalONE Perspective.

    In the Report Data view, you can

    • sort a report according to a specific column by clicking on the column header;

    • drag a column header to a different position.

    When you have created more than one report, all of these reports are shown in the Report Data view (unless you have closed them). The tab of each report page contains the name of the DDM, the name of the report template that has been used to create the report, and a time stamp which indicates when this report has been created.

    When a range is defined for a field, this is indicated in the column header (for example, "1:4"). In this case, only the first element of the range is initially shown and expand/collapse icons are provided. You can also double-click an entry in order to expand or collapse it. When you expand an entry, all elements of the range are shown (see the example below). When you move the mouse pointer over a column which shows ranges (either in expanded or collapsed state), a tooltip appears, listing all elements of the range. This feature is available as of Natural Development Server Version 2.2.4.

    Report

    When expand/collapse icons are shown in the report, the context menu contains the commands Expand All and Collapse All. Using these commands you can expand or collapse all entries in the report at once.

Saving a Report Template

You save a report template using the standard Eclipse functionality (for example, by pressing CTRL+S).

The following applies when your report template has been changed in such a way so that it contains the former template structure, but pertains to a different DDM. When you save the report template (with Save or Save As), a dialog box appears asking whether you want to use the new DDM with the report template. You have two options for saving:

  • To use the new DDM, you choose the Yes button.

    The fields of the new DDM are shown as the available fields on the Fields page.

    The fields that are also available in the new DDM remain selected on the Fields page. All other selected fields are cleaned. For example, when the selected field PERSONNEL-ID is used in both DDMs, this field is kept.

    When a descriptor which has been defined as a filter on the Report page is no longer available in the new DDM, the filter is reset to its default value.

  • If you do not want to use the new DDM, you choose the No button.

    The definition of the new DDM is disregarded and the report template is saved with the original DDM. The next time you open the report template, you can see that the original DDM is used again.

Saving a Report

You can save each report which is currently shown in the Report Data view. Different commands are available for this purpose. You can either save the whole report or just selected lines of the report. The result is a text file containing, by default, a comma-separated list of fields. The character that is used to separate the field values is determined by the Natural input delimiter character (ID parameter) as defined in the character assignments of the current project properties.

Start of instruction setTo save the report

  1. In the Report Data view, go to the page which contains the report that you want to save.

  2. In the list of fields, open the context menu and choose Save Report.

    A dialog box appears.

  3. Select a folder and specify a file name.

  4. Choose the Save button.

Start of instruction setTo save selected lines of the report

  1. In the Report Data view, go to the page which contains the report that you want to save.

  2. In the list of fields, select each line that is to be included in the report.

    You can use the standard key combinations for selecting a range of fields (using the SHIFT key) or individual fields (using the CTRL key).

  3. Open the context menu and choose Save Selection.

    A dialog box appears.

  4. Select a folder and specify a file name.

  5. Choose the Save button.

Note:
A file extension is not automatically added to the file name. You have to specify it yourself.

Displaying the Properties for a Report

When you select a report in the Report Data view, the Properties view shows metadata for this report.

Report properties

The following pages are provided:

  • General
    Shows general information about the report. This includes the name and location of the DDM and the report template that has been used to create the report.

  • Filter
    Shows the filter criteria for the report. These are the definitions which have been made on the Report page of the data browser editor (see Setting Options for the Report). In addition, the number of processed records is shown.

  • Fields
    Shows the fields that are used in the report. These are the fields that have been selected on the Fields page of the data browser editor (see Selecting the Fields for the Report).

Opening an Existing Report Template

A report template is an XML file that is stored in the RES folder of the library which contains the DDM to which it pertains. When you open a report template, you can change all required information as described previously and you can create a new report.

Start of instruction setTo open a report template

  • In the Project Explorer view or in the Natural Navigator view, select the report template, invoke the context menu and choose Open.

    Or:
    Double-click the report template.

    The report template is opened in the data browser editor.

Note:
The report template may be copied from the RES folder of the original into the RES folder of a new Natural project. To find the DDM which pertains to the report template, the new Natural project must have a reference to the original project. For further information about referenced projects, see Types of Natural Projects.