ADASEL (PLOG Selection Tool)

#### Search Results

Search

# ADASEL (PLOG Selection Tool)

This document describes the utility "ADASEL".

The following topics are covered:

- Functional Overview

- Procedure Flow

- Checkpoints

- Control Parameters

- Query Syntax

- Examples and Special Cases

## Functional Overview

The ADASEL utility selects records from Protection log files and WORK containers.

## Procedure Flow

Data Set | Environment Variable/Logical Name | Storage Medium | Additional Information
--- | --- | --- | ---
Associator | ASSOx | Disk | n/a
Alternate FDTs | SELFDTn | Disk | Only required if you process a query with keyword FDTINPUT, to read the FDT from a file (file number 'n'), instead of the database. In case all files are defined as alternate FDT, then no database is required.
Optional output | SELOUT | Disk | The output file location can be defined here. Otherwise, the output is written to stdout.
Optional FDT output | SELFDTOUT | Disk | The FDT output file location can be defined here. The FDTs used in the selection will be exported here, if the FDT parameter is selected.
Protection log | SELPLG | Disk | The input PLOG file is defined here. Alternatively, a directory can be specified here, so that all NUCPLG files in there will be processed.
Control statements | stdin | - | Utilities Manual
ADASEL report | stdout | - | Messages and Codes
Work storage | WORK1 | Disk | Utilities Manual

The sequential file SELPLG can have multiple extents. For information about sequential files with multiple extents, see Adabas Basics, Using Utilities.

## Checkpoints

The utility writes no checkpoints.

## Control Parameters

The following control parameters are available:

          D   DATASET = { PLOG | WORK }

              DBID = number

              FDT

              FILE = <filepath>

              FORMAT = { CSV | DISPLAY | JSON | JSONPRETTY }

              SELECT = <select query>

              SELECTALL { = FDTINPUT }

              SEPARATOR = character | \character

          D   [NO]STAT

Note
The query is case insensitive.

### DATASET

    DATASET = { PLOG | WORK }

This parameter selects the file containing the protection log information to be processed. The keyword can take the values PLOG or WORK, where PLOG is the default.

#### Example:

    adasel: dataset=work

The WORK dataset is selected.

### DBID

    DBID = number

This parameter behaves differently based on the dataset defined.

- PLOG dataset

  It can be used to select a different database than the one defined in the PLOG file. The default is the database number defined in the PLOG file.

- WORK dataset

  It must be used to define the database containing the WORK dataset. There is no default in this case.

#### Examples:

    adasel: dbid=200

The database currently being used is database 200. The PLOG dataset is selected by default.

    adasel: dbid=200 dataset=WORK

The database currently being used is database 200. The WORK dataset is selected.

### FDT

    FDT

The file FDTs used in the selection will be exported as JSON with this parameter. This will be written to a file, if the environment variable SELFDTOUT is defined. Otherwise, it is printed to stdout.

### FILE

    FILE = <filepath>

This function reads a text file containing one or more queries on the dataset.

#### Example:

    adasel: file=query.in

The content of the file query.in will be executed on the dataset.

### FORMAT

    FORMAT = { CSV | DISPLAY | JSON | JSONPRETTY }

This parameter selects the output format. The selection CSV creates a “comma-separated values” output. If DISPLAY is selected, then the output format will be similar to the mainframe output. The JSON and JSONPRETTY selections create a JSON file in CDC style. The JSON format is for machine processing, while the JSONPRETTY format is human readable. The default is DISPLAY.

### SELECT

    SELECT = <select query>

The select function executes a text string containing one or more queries on the dataset.

#### Example:

    adasel: select=select all from file 1 display all end

The specified query will be executed on the dataset.

### SELECTALL

    SELECTALL { = FDTINPUT }

The 'select all' function creates an output containing the complete content of the dataset. This happens without any library call. If the optional parameter FDTINUT is set, then FDT information will be retrieved from the files defined in the environment variable(s) SELFDTn.

### SEPARATOR

    SEPARATOR = character | \character

This parameter defines the separator character for the CSV output. The default is comma.

### [NO]STAT

    [NO]STAT

This function enables or disables the display of performance statistics at the end of the execution. The default is NOSTAT.

#### Example:

    adasel: stat

    ------------------------------------------------------------------------------------------------
    Total run time:           84,371,489 us,         84.37 sec
      Library init/next:             814 us
      Processing time:        67,242,964 us,         67.24 sec,    14,581,622 PLOG records
        Process FDT cache:     1,202,276 us,          1.20 sec,     1,199,999 hits,    avg:     1 us
                                                                          100 % hit rate, 1 file(s)
        Decompress time:       3,707,651 us,          3.70 sec,     1,200,000 records, avg:     3 us
        Library run:          33,869,021 us,         33.86 sec,     1,200,000 calls,   avg:    28 us
        Print time:            8,331,534 us,          8.33 sec,     1,200,000 records
      Library finish:                 36 us
    ----- Library measurements ------------
    Init/Next Total:                 400 us
      Init/Next Set-Up:              147 us
      Compile query:                 238 us
      Stackm. Set-Up:                  2 us
      Criterion handover:             11 us
    Run Total:                45,322,926 us
      Run Setup:                  73,677 us
      Parsing PLOG:            6,271,616 us
      Stack machine:          12,986,070 us
      Run Handover:           25,991,563 us

    ------------------------------------------------------------------------------------------------

## Query Syntax

The following paragraphs detail the currently implemented keywords, their control flow, and their function. The keywords are given in capital letters but can be written in any case.

The only exceptions from this rule are field names. These are case sensitive, making AA1 different from Aa1, aA1, and aa1. On top of that, special formatting and naming rules apply, which are explained further down. See FDT Record Structure for more naming recommendations.

- Control Flow SELECT

- Control Flow IF

- Comparison Operators

- Control Flow DISPLAY

- Control Flow OUTPUT

- Control Flow NEWPAGE

- Control Flow SKIP

### Control Flow SELECT

- SELECT

  - marks the beginning of a query

  - has to be paired with an END statement

  - select options:

    - ALL

      - is a combination of all options except BACKOUT and ETCMD

    - ALLCMD

    - - is a combination of all select options

    - BEFORE IMAGE / BI

      - selects before images derived from A1 and E1 commands

      - alternatively, the shorter form SELECT BI can be used

    - AFTER IMAGE / AI

      - selects after images derived from A1 and N1 commands

      - alternatively, the shorter form SELECT AI can be used

    - BACKOUT

      selects before and after images derived from BT commands

    - DELETED

      selects before images derived from E1 commands

    - ETCMD

      selects ET information

    - NEW

      selects after images derived from N1 commands

    - NEWDEL

      selects after images derived from N1 and E1 commands

    - UPDATED

      selects before and after images derived from A1 commands

  - RECORDS

    optional keyword, may be omitted

  - RECSYNC

    - specifies whether before and after images are displayed together

    - if omitted, takes the following default values, based on select option:

      - TRUE for

        - ALL

        - ALLCMD

        - ETCMD

        - DELETED

        - BACKOUT

        - NEW

        - NEWDEL

        - UPDATED

        - `format=json`

        - `format=jsonpretty`

      - FALSE for

        - BEFORE IMAGE / BI

        - AFTER IMAGE / AI

    - if given, TRUE for all cases

  - mode options:

    the mode options are mutually exclusive, only one can be used at a time

  - FROM FILE / IN FILE

    - marks the selection of blocks based on file number

    - * (asterisk) can be used for searching all files

    - file number or * have to follow immediately after

    - FROM FILE and IN FILE have the same function, they act like synonyms

  - FROM USER

    - marks the selection of blocks by user

    - username can be supplied in WITH statement

    - if username is omitted, blocks from all users are displayed

      - this can act as an alternative to 'SELECT FROM FILE *'

  - FDTINPUT

    - marks the use of an external FDT

    - the FDT has to be supplied in the environment variable SELPLGn

- STARTING FROM

- ENDING AT

  - set a timeframe for the selection of a PLOG record

  - the borders are inclusive

  - the date and time can be supplied in the following ways:

    - Gregorian in the format YYYYMMDD/HHMMSS

    - Julian in the format J(YYYYDDD/HHMMSS)

  - the time zone of the supplied date and time will be the one of the local machine, but then converted to a Unix timestamp in UTC

  - if omitted, defaults to the timeframe

    - Unix timestamp 0 (January 1, 1970 00:00:00 (UTC))

    - Unix timestamp 9223372036854775807 (max_int64, theoretically August 17, 292278994 07:12:55 (UTC))

  - if given, overrides the corresponding default value

- WITH

  - acts like a second stage for the SELECT statement

  - if FROM USER is specified a USERID can be specified here

  - all comparison operators can be used and joined with OR as well as AND

- END

  marks the end of a SELECT statement or query

### Control Flow IF

IF

- provides a conditional logic similar to other programming languages

- accepts every comparison operator

- comparison operators can be connected with OR as well as AND

- IFs can also be nested

- when `DISPLAY` clause comes beforehand, use `IFF` to avoid ambiguities in case of a single-line query or when the `DISPLAY` clause is on the same line

- THEN

  - keyword is optional

  - marks the part if logical statement is true

- ELSE

  code block that is executed when the conditional statement is false

- IGNORE

  stands in for an empty code block

- DO / DOEND

  - acts similar to curly brackets in other programming languages

  - can be used to enclose a multiline code block for THEN or ELSE part

  - can be omitted if code is on a single line only¬

### Comparison Operators

- evaluates a statement to TRUE or FALSE

- evaluates fields against literals or literals against literals

  - the evaluation depends on the format of the first literal value

  - statement will either evaluate numerical comparison or string comparison

    - AA = 'Test' => string comparison

    - AB(1) >= 10 => numerical comparison

    - USERID < '*adatst ' => string comparison

    - SESSNUM != 2 => numerical comparison

  - if the value formats do not match a runtime error is thrown

  - if two fields are compared, a numerical comparison is attempted first, if it fails a string comparison will occur

- EQUAL

  can be specified by EQUALS, EQUAL, EQ and =

- GREATER THAN

  can be specified by GREATER THAN, GT and >

- LESS THAN

  can be specified by LESS THAN, LT and <

- GREATER THAN OR EQUAL

  can be specified by GREATER EQUAL, GE and >=

- LESS THAN OR EQUAL

  can be specified by LESS EQUAL, LE and <=

- NOT EQUAL

  can be specified by NOTEQUAL, NOT EQUAL, NE, ¬=, ^= and !=

- THRU

  - specifies a range of values

  - the borders are inclusive

  - syntax can only be used with equal operator, e.g.

    - AA EQ 10 THRU 50

    - USERID EQ 'USER_0 ' THRU 'USER_10'

- OR

  - joins two conditional operations together

  - evaluates to TRUE if one of the two operations is TRUE

- AND

  - joins two conditional operations together

  - evaluates to TRUE if both operations are TRUE

  - when used in conjunction, AND takes precedence over OR, similar to how multiplication is "faster" than addition

### Control Flow DISPLAY

- DISPLAY

  - Prints content to STDOUT or SELOUT, if specified.

  - Must be enclosed in a SELECT statement.

  - Prints a header section for each record.

  - For multi-line queries, the `DISPLAY` clause ends after a new line

  - Is followed by an output specifier:

  - - field name

      Prints the content of one field.

      Field names must follow the patterns [A-Za-z][A-Za-z0-9], [A-Za-z][A-Za-z0-9]d+ or [A-Za-z][A-Za-z0-9]d+(d+), for example, AA, zA5, bb5(10).

    - free text

      Prints a free text, text has to be encased in quotation marks.

    - ALL

      Prints all data fields in the record.

    - ISN

      Prints the ISN of the record.

    - SESSNUM

      Prints the session number of the record.

    - USERID

      Prints the name of the user that modified the data in the record.

    - MU and PE fields

      - Format XXI(J):

        - XX: field specifier

        - I: PE number

        - J: MU number

      - XXJ / XXI(J): Prints the specified field.

      - XXI(1-n): Prints all MU fields in the given range for a given PE field I.

        e.g. AA5(1-10): prints the fields AA5(1) through AA5(10).

      - XXI(1-N): Searches and prints all MU fields for a given PE field I.

      - XX1-n(J): Prints the given MU field J for a given range of PE fields.

        e.g. AA1-10(5): prints the fields AA1(5) through AA10(5).

      - XX1-N(J): Searches and prints all PE fields that have a given MU field J.

      - XX1-N(1-N): Searches and prints all PE and MU fields.

    - RABN

      Prints the RABN of the record.

    - FNR

      Prints the file number of the record.

    - COMMID

      Prints the communication ID of the record.

    - TSN

      Prints the transaction number of the record.

- NOHEADER

  - Switches off the output of the header.

  - The header will be turned off for all output produced.

    - Has no effect for the options `format=json` or `format=jsonpretty`.

  - NOHEADER only needs to be specified once per SELECT statement.

- NOFIELDS

  - Suppresses record decompression and output of fields.

  - Cannot be used in conjunction with any other keywords in DISPLAY.

  - Since no record decompression happens, fields, e.g. AA = 10 or AB(1) != 100, cannot be used in conditional statements within IF or WHEN.

    - Only header information such as SESSNUM, ISN, RABN, FNR, COMMID, TSN and USERID are allowed.

Field names are case sensitive. This means, as mentioned above, a field AA1 is different from Aa1, aA1, and aa1. When typing a query, this must be kept in mind. A field name cannot start with a number or a special character, making, for example, 1AA or @ab invalid. Field names must follow the patterns [A-Za-z][A-Za-z0-9], [A-Za-z][A-Za-z0-9]d+ or [A-Za-z][A-Za-z0-9]d+(d+). Furthermore, the Adabas documentation recommends under FDT Record Structure that names which are English prepositions or articles such as AN, AT, BY, IF, IN, OF, ON etc. should not be used because of a possible conflict with syntactical terms used by Natural. These field names will still be supported by ADASEL, though, should the user choose to go against this recommendation.

Record decompression is a computationally intensive operation, yet it is essential for evaluating and displaying field information. Suppressing it entirely can substantially accelerate execution time. This approach proves beneficial when only header information is needed or during data pre-assessment.

The output of a display command contains a header section and an output body. An example in the main frame format can look as follows:

For the main frame format, the header section contains the following fields:

- session number

- file number

- ISN

- communication ID

- transaction number

- user ID

- record type

- time stamp of the data block

The body of the output lists the desired output fields as described in the query. In the example, e.g. the output specifier `ISN` results in the display of the corresponding number and the specifier `ALL` lists all the data fields contained in the block. The result of each output specifier will always be printed in a separate line. It is possible to combine multiple specifiers in one `DISPLAY` command or have multiple `DISPLAY` commands.

The same example in JSON format can look like this:

The JSON format lists all blocks as an array structure. This structure is machine readable and can be used to interface with other applications, programs, scripts, etc. The option `format=json` produces a compact output which is more memory efficient. The option `format=jsonpretty` produces the output above with tabs and line breaks for better readability.

Yet the same example in CSV format can look like this:

The CSV format list all blocks in a table structure and can be produced with the option `format=csv`. The output is either machine readable or can be evaluated with a spreadsheet program, e.g. MS Excel. The content of the header section is identical to the main frame and json format. Selected records with header and field information follow below.

### Control Flow OUTPUT

The OUTPUT command on the mainframe version of ADASEL was meant to produce a machine-readable hex dump.

For the Linux version, please use the option format=json or format=jsonpretty.

### Control Flow NEWPAGE

NEWPAGE

- In the mainframe version, was meant to create a page break or feed paper through to the next top of the page.

- For the Linux version, the keyword is parsed for backwards compatibility, but no new page is generated.

### Control Flow SKIP

SKIP

- Produces line breaks in the output.

- If ADASEL is called with the option format=json or format=jsonpretty, no line break will be produced.

- Number of lines:

  - Specifies the number of lines to be skipped.

  - Can be omitted.

    If omitted, will produce 1 line break.

- LINES

  - Closes SKIP instruction.

  - Keyword can be omitted.

- Examples:

  - SKIP: produces one line break.

  - SKIP 2: produces two line breaks.

  - SKIP 3 LINES: produces three line breaks.

## Examples and Special Cases

The following section lists examples and special cases.

### Multi-line query with DISPLAY and IF

In this example a `DISPLAY` clause is directly followed by an `IF` clause. The first case is a multi-line query, the second case a single-line query.

For a multi-line query, the `DISPLAY` clause ends at the line break and does not need any further consideration.

For a single-line query, it is unclear where the `DISPLAY` clause ends. Using an `IF` clause would be interpreted as a field identifier and is necessary should a field IF be required. To resolve this situation, an `IFF` clause should be used. This signals an end of the `DISPLAY` clause and allows for correct parsing of the following `IF` clause.

### On this page

- Functional Overview
- Procedure Flow
- Checkpoints
- Control Parameters
- Query Syntax
- Examples and Special Cases