adabas-go-api

README

Exploit your assets in Adabas by using the Adabas API for Go

• Exploit your assets in Adabas by using the Adabas API for Go
  • Introduction
  • Features
  • Usage
    • Enable native library access
  • First step
  • Adabas API for Go example
    • Standard usage
    • Classic database usage
    • Using a Go struct
  • Log output
  • Summary

Introduction

This package is designed for using Adabas databases from Go. You can find a detailed overview about the design and technical implementation here.

For details have a look at the API documentation. It can be referenced here: https://godoc.org/github.com/SoftwareAG/adabas-go-api/adabas

Features

In general, users of the Adabas API for Go do not need to know a basic level of Adabas APIs such as Adabas control blocks or Adabas buffer layouts. The Adabas API for Go provides a more user friendly use of Adabas files and fields. It is similar to the Adabas Client for Java product delivered by Software AG.

This is a list of features which the Adabas API for Go supports:

• Read, Search, Insert, Delete and Update of Adabas records
• Work with field descriptors and special descriptors like sub-/super-descriptors
• Work with the Adabas TCP/IP layer on Linux, Unix and Windows
• Work with Adabas Mainframe using the Entire Network infrastructure
• Support Unicode access of Adabas Unicode fields
• Work with Adabas Maps, a short name to long name definition
• Work with Adabas period groups and multiple fields
• Work with large object reads and writes
• Work with partial large object reads and writes
• Provide Go structure usage by reflecting structure fields to Adabas Map definitions

Usage

Inside the code the Adabas API for Go can be used importing the Go API. Beside the API, some small sample applications are provided in GitHub. These examples of the Adabas API for Go can be downloaded using the go get command:

go get -u github.com/softwareag/adabas-go-api/adabas

You can compile it with the new Adabas TCP/IP interface on Linux, Unix and Windows. In this case no additional native library is needed. Alternatively the Adabas local access with Adabas client native libraries can be used. The AdabasClient installation is a prerequisite in this case.

Enable native library access

By default only the Adabas TCP/IP interface is enabled. To enable Adabas Client native link support you need to provide the Go build tag adalnk and the CGO compile flags defining build flags for the Adabas Client library. If the Adabas environment is sourced, you can define CGO compile flags as follows:

On Unix:

CGO_CFLAGS=-I${ACLDIR}/inc
CGO_LDFLAGS=-L${ACLDIR}/lib -ladalnkx -lsagsmp2 -lsagxts3 -ladazbuf

On Windows:

CGO_CFLAGS=-I%ACLDIR%\..\inc
CGO_LDFLAGS=-L%ACLDIR%\..\bin -L%ACLDIR%\..\lib -ladalnkx

The application is built with Adabas API for Go as follows (please note that the tag adalnk is needed to enable local IPC access):

go build -tags adalnk application.go

First step

A detailed description how to do the first steps using the Adabas Docker community edition is provided here. Independent of the used environment of Docker (like Kubernetes or others), it describes how to call Adabas.

Adabas API for Go example

Standard usage

The logical view of the data can be defined using Adabas maps. A detailed description of Adabas maps is available here.

The creation of Adabas maps is done by the infrastructure of the Java API for Adabas (Adabas Client for Java). The Adabas Data Designer rich client or Eclipse plugin provides the management of Adabas map definitions. A programmatical approach to create Adabas maps is part of the Adabas API for Go.

In the first example a logical read on the database file uses Adabas maps:

import (
  "github.com/SoftwareAG/adabas-go-api/adabas"
)
// Create new connection handler using the Adabas Map repository in database 24 file 4
connection, cerr := adabas.NewConnection("acj;map;config=[24,4]")
if cerr != nil {
  return
}
defer connection.Close()
// Create a read request using the Map definition
request, err := connection.CreateMapReadRequest("EMPLOYEES-NAT-DDM")
// Define the result records content
request.QueryFields("NAME,PERSONNEL-ID")
request.Limit = 2
// Read logical using a range search query
result,rerr := request.ReadLogicalWith("PERSONNEL-ID=[11100301:11100303]")
// Result is dumped to stdout
result.DumpValues()

The next example shows a cursor read on the database file:

// Read logical with cursor using a range search query
result,rerr := request.ReadLogicalWithCursoring("PERSONNEL-ID=[11100301:11100303]")
// Result is dumped to stdout
for col.HasNextRecord() {
  record, rerr := col.NextRecord()
    ...
}

See detailed documentation here.

Classic database usage

A quick example to read data from a database file 11 of the Adabas database with database ID 23 is here:

// Create new connection handler to database
connection, err := adabas.NewConnection("acj;target=23")
if err!=nil {
  return
}
defer connection.Close()
connection.Open()
// To work on file 11 create corresponding read request
request, rErr := connection.CreateFileReadRequest(11)
// Define the result records content
request.QueryFields("AA,AB")
request.Limit = 0
// Read in the database using search query
result,err := request.ReadLogicalWith("AA=60010001")
var aa,ac,ad,ae string
// Read given AA(alpha) and all entries of group AB to string variables
result.Values[0].Scan(&aa,&ac,&ad,&ae)

The example code is referenced here. See detailed documentation here.

Using a Go struct

The Adabas API for Go can handle simple Go struct definitions to map them to a Adabas Map definition.

For example if the structure is defined like this:

type Employees struct {
ID        string
Birth     int64
Name      string `adabas:"Name"`
FirstName string `adabas:"FirstName"`
}

The struct can be used to read or store data directly. The store of the whole structure will be done.

To store the struct record, do this:

storeRequest, err := adabas.NewStoreRequest(Employees{}, ada, repository)
e:=  &Employees{ID: "ID3", Birth: 456, Name: "Name3", FirstName: "First name3"}
err = storeRequest.StoreData(e)
err = storeRequest.EndTransaction()

The read of the struct data will be done with:

request, err := adabas.NewReadRequest(Employees{}, adabas, mapRepository)
defer request.Close()
result, err := request.ReadLogicalWith("ID>'ID'")
e := result.Data[0].(*Employees)

All fields of the struct are mapped to an Adabas Map field name. The adabas tag of the struct definition changes the mapped name.

Log output

To enable log output in sample executables, please set the ENABLE_DEBUG environment variable to 1 for debug level output and 2 for info level output. This will enable the logging.

To use logging in your code with the Adabas API, you can enable logging by setting the log instance with your logger instances with:

adatypes.Central.Log = logger

Summary

The Adabas API for Go offers easy access to store or read data in or out of Adabas. The Go API should help developers to work with data in Adabas without needing to be an expert on special Adabas database features. Go functions enable developers to use Go as a programming language to access Adabas in the same way as other data sources are embedded in a Go project. By using the native AdabasClient library, you can access all platforms Adabas runs on like Linux, Unix, Windows and Mainframe (z/OS with Entire Network). Step by step all relevant Adabas features are supported.

---

These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.

---

For more information you can Ask a Question in the TECHcommunity Forums.

You can find additional information in the Software AG TECHcommunity.

---

Contact us at TECHcommunity if you have any questions.