The Adabas Client for Java API is used to introduce Adabas functionality into the Java programming language.
Adabas Client for Java maps long names to the Adabas short names in the FDTs. The main advantages of this include:
The map configuration is stored in an Adabas file which is part of the database. The mapping can be accessed from everywhere, even remotely.
Various input formats can be used as the source of the map definitions. It is possible to use SYSTRANS files based on Natural DDMs to define the map; FDT comments and XML Schema files (XSD) can also be used.
Data can be accessed without having to know the database ID and file number, only the map name is required.
The API provides a class called AdabasMapper,
which performs all read and write operations out of and into the map
configuration. The AdabasMapper also provides search
functionality to find maps.
The AdabasMapper class produces so-called Adabas
targets and Adabas sessions which are described below.
The Adabas target defines the connection to the target database. This might be just a database ID, or, in case of mainframe databases where the Entire Net-Work port number is known, the target is a combination of the database ID and Entire Net-Work connection URL. The Software AG Directory Server is the reference for remote databases.
The Adabas target also contains a number of connection parameters, such as the host's endianness or the character set used. The Adabas target handles the current connection state.
An Adabas session contains all Adabas user-specific information. This includes the user ID, process identification (EID) and some security-related information, such as the RACF or LUW Adabas Security credentials.
An Adabas Client Java Session is essentially defined by the two
parameters Adabas Target (AdabasTarget.class) and Adabas
Session (AdabasSession.class). These two objects are
created either directly, using the specific AdabasTarget
or AdabasSession classes, or they can be created using
the AdabasConnection helper class.
The AdabasConnection class is created using an
SQL-like connection string. With an AdabasConnection
instance you can create request instances which handle specific read, delete,
update or write operations on the database. Each request contains information
that is specific to the operation it provides. Multiple requests can be used
per session. Multiple requests need to be used to read a different set of
fields out of an Adabas database. If a number of Adabas files are accessed in
an Adabas session, each access need to be distributed in several request
classes. Internally, each request uses a format buffer and other
Adabas-specific objects, which are generated on a per request basis.
A transaction consists of a chain of request operations. Any number of transactions can be part of an Adabas session.
The following is an example of how a request chain might look:
AdabasTarget target = new AdabasTarget(getDynamicDbid());
try {
/* Setting the target to not implicit close the request provides the possiblity for multiple
request in one Adabas session */
target.setImplicitClose(false);
/* Read target database on file 11 field "AA", "AB" */
try (ReadRequest request = new ReadRequest(target, 11)) {
request.addFieldsQuery(new String[] { "AA", "AB" });
QueryResultList list = (QueryResultList) request.readIsnSequence();
}
/* Store records in file 17 and file 16 with different fields dependent on each file */
try (StoreRequest storeRequest1 = new StoreRequest(target, 17)) {
try (StoreRequest storeRequest2 = new StoreRequest(target, 16)) {
/* Create a new record with corresponding fields and fill value */
RecordEntry entry = storeRequest1.createRecordEntry(new String[] { "AA", "AE" });
entry.addValue("AA", 123);
/* Store entry - Dependent on the cache the store is not send to the database */
storeRequest1.storeEntry(entry);
try (ReadRequest request = new ReadRequest(target, 11)) {
request.addFieldsQuery(new String[] { "AA", "AW" });
QueryResultList list = (QueryResultList) request.readIsnSequence();
list.output(System.out);
} /* Close here is omitted */
/* Create a new record for file 16 with corresponding fields and fill value */
RecordEntry entry = storeRequest2.createRecordEntry(new String[] { "AA", "AE" });
entry.addValue("AA", String.format("%06d", i));
storeRequest2.storeEntry(entry);
/* Flush records to database file 16 */
storeRequest2.endTransaction();
/* Flush records to database file 17*/
storeRequest1.endTransaction();
}
} /* Pay attention, a implict ET is done here */
/* Read with the same connection target the file 16 after the Transaction */
try (ReadRequest request = new ReadRequest(target, 16)) {
request.addFieldsQuery(new String[] { "AA", "A1", "AQ", "AW" });
QueryResultList list = (QueryResultList) request.readIsnSequence();
list.output(System.out);
}
} finally {
target.close();
}
An Adabas session can be reused after the current Adabas target connection is being closed; the target will open automatically if a new request is initiated on the target. If it is used for map-based access, the AdabasConnection or the AdabasMapper instance will be used instead of the target and the file number.
Adabas Client for Java supports the following Adabas session types:
| Type | Description |
|---|---|
| NONE | The default Adabas ID is generated containing the user ID, host and an additional process identification (so-called ESID) describing the uniqueness. |
| ADA_SECURITY | The Adabas security password is sent to the database. Refer to Adabas Security in the Adabas documentation for further information. |
| ADA_PW_SECURITY | This session type supports the new Adabas Security on Linux, UNIX and Windows platforms. In addition to the Adabas ID, information like the user ID and pasword are required. |
| ADASAF | This session type is used to send credentials to a remote mainframe database, which is secured using ADASAF and the external security system RACF. |