Use Cases

#### Search Results

Search

# Use Cases

The following document presents some common use cases for Adabas Client for Java.

- Connecting to an Adabas Database Engine

- Read Adabas Data

- Read Adabas Data using Map Definition

- Simple Search Example

- Advanced Search Example using Super Descriptor

## Connecting to an Adabas Database Engine

The Adabas target can be a local database, or it can be a remote database connection path.

#### Local Database

A local Adabas database target is accessed using the classic ADALNK libraries to send Adabas calls. In this case, only a database number must be specified.

    /* simple Adabas Database target definition (dbid) */
    AdabasTarget target = new AdabasTarget(dbid);
    target.open();

#### Remote Database

A remote Adabas database is referenced using an Entire Net-Work (WCP) URL connection string.

    AdabasTarget(int dbid, java.lang.String url)
    Adabas Target definition with an Entire Net-Work remote URL reference.

Sample URL reference: `tcpip://<hostname>.<domainname>:<port>`

On mainframe platforms, Adabas Client for Java API uses the EBCDIC (037) character set to connect to and communicate with an Adabas server environment. Software AG recommends that you use UES-enabled mainframe databases in order to avoid this restriction.

Note
It is also possible to use an Adabas Directory Server or a flat file named xtsurl.cfg, that contains remote database URL references.

## Read Adabas Data

In addition to the database ID, additional parameters, such as the file number and short name fields, need to be specified. The main class used to read data from Adabas is the `ReadRequest` class.

A simple example application (which accesses the fields AA and AB of file number 11 in database 24) would require the following settings:

     /* Short name fields to generate the Adabas Format Buffer */

         String fields = new String{"AA","AB"};

         /* Create read request with parameter database id and file number */

        ReadRequest request = new ReadRequest(24,11).queryFields(fields);

        /* Send request and receive results */

        QueryResultList list = (QueryResultList) request.readIsnSequence();

The `readIsnSequence()` method sends the query to the database and the results will be collected in a list array. The list contains entries for each database record.

The following example will return the field value instance of field "AC" in the first record:

     IRecordEntry record = list.get(0);

        IAdaFieldValue fieldValueFirstName = record.getDeepFieldValuebyShortName("AC");

        String firstName = fieldValueFirstName.getValue();

Note
By default, database security is disabled, and therefore no session information is required for further initialization. As soon as the database is protected, either by authentication and/or by authorization rules, session information is required - refer to the `ReadRequest` constructors and `AdabasSession` class for further information.

## Read Adabas Data using Map Definition

The mapping extension allows you to use long names instead of short names (2 byte) to reference Adabas fields. The corresponding metadata is stored in an Adabas database file (map configuration file). It is recommended that you use one configuration file per database.

Refer to the description of the Data Designer for further details about mapping.

The location of the map definition must be registered. This can be done using the `AdabasMapper` or `ReadRequest` classes:

- `AdabasMapper`

      AdabasMapper.addMapStorage(<URL location>,<configuration file number> );

- `ReadRequest`

      ReadRequest request = new ReadRequest("EmployeeMap",<url to database>,<map configuration file>).queryFields(fields);

The main class used to read data from Adabas is the `ReadRequest` class. The `ReadRequest` can be initialized with just the classic parameters. A simple example application requires the following statements:

     /* Long name fields now possible */
         String fields = new String{"FirstName","LastName"};

         /* Create request containing needed parameters */
        ReadRequest request = new ReadRequest("EmployeeMap").queryFields(fields);

        /* Send request and receive result */
        QueryResultList list = (QueryResultList) request.readIsnSequence();

This example uses the map named `EmployeeMap`. The database ID and file number are part of the mapping information. In this example, the map defines database ID 24 and the file number 11 as the data location. File 11 is the standard employee demo file delivered with Adabas on all Linux, Unix and Windows platforms. The Adabas fields are listed in the “fields” variable. The field FirstName is mapped to AC and the field LastName is mapped to AE.

The following statements return the field value instance of field LastName in the first record:

    IRecordEntry record = list.get(0);
      IAdaFieldValue fieldValueFirstName = record.getDeepFieldValueby("LastName");
      String firstName = fieldValueFirstName.getValue();

Note
Please look at the examples folder (mapping) delivered with the package. Compiling and executing GenerateMappingsExample will add two example mapping definitions named `EmployeeMap` and `VehicleMap`, which are used in the other examples. See also the tutorial Adding the Adabas Client for Java Example Programs in Eclipse.

## Simple Search Example

The `ReadRequest` class includes extensions to support the search capabilties of Adabas.

### Simple Search

The Adabas Client for Java API includes the method `setSearch`. The following table shows some example search queries.

Search | Result
--- | ---
AE='SMITH' | Search for records with field AE and value SMITH
AE>'ADAM' | Search for records with field AE and values greater than ADAM
AA>12345 | Search for records where field AA is greater than 12345

You only need to add an additional statement to your read request :

    String fields = new String{"AA","AB"};
      /* Create request containing needed parameters */
      ReadRequest request = new ReadRequest(24,11).queryFields(fields);
      request.setSearch("AE='SMITH'");
      /* Send request and receive result */
      QueryResultList list = (QueryResultList) request.readIsnSequence();

### Adabas-specific Search

A further method is to generate a search tree. Instead of using the `setSearch(...)` method, the application can generate search trees to support further Adabas search capabilities. For example, it is possible to define values for lower and upper limits:

    RecordDefinition definition = request.addFieldsQuery(fields);
      /* Get field type for field AE */
      AdaFieldType lastName = definition.getDeepFieldbyShortName("AE");
      /* Define search tree, one node for lower limit and one node for upper limit */
      SearchTree lowerTree = new SearchTree("GE", (IAdaFieldValue) lastName.getFieldValue());
      lowerTree.setValue("SCHNEIDER".getBytes());
      SearchTree upperTree = new SearchTree("LT", (IAdaFieldValue) lastName.getFieldValue());
      upperTree.setValue("SD".getBytes());
      lowerTree.bound(upperTree, SearchTree.AND);
      request.setSearchTree(lowerTree);

This example will extract only those records that meet the specified criterion of AE >= "SCHNEIDER" and AE < "SD".

## Advanced Search Example using Super Descriptor

This example is also intended to illustrate the relationship between the Data Designer and the variable declarations in the java example programs provided - it shows screen shots from the Data Designer together with variable declarations and statements from the example SuperdescriptorSearchExample.java.

Group field AB.

Super descriptor field S2.

Variable declaration from example SuperdescriptorSearchExample.java.

Statements from example SuperdescriptorSearchExample.java.

### On this page

- Connecting to an Adabas Database Engine
- Read Adabas Data
- Read Adabas Data using Map Definition
- Simple Search Example
- Advanced Search Example using Super Descriptor