{"id":13691967,"url":"https://github.com/SoftwareAG/adabas-go-api","last_synced_at":"2025-05-02T16:31:04.322Z","repository":{"id":34183588,"uuid":"161291238","full_name":"SoftwareAG/adabas-go-api","owner":"SoftwareAG","description":"This module provides direct access to Adabas database data in a Golang-based application. This contains all transactional operations on the database.","archived":false,"fork":false,"pushed_at":"2024-04-19T12:18:39.000Z","size":16449,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-08-03T17:13:01.995Z","etag":null,"topics":["adabas","go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SoftwareAG.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-11T07:01:04.000Z","updated_at":"2024-04-19T16:35:31.000Z","dependencies_parsed_at":"2024-04-08T02:02:59.067Z","dependency_job_id":"3ad03b40-0786-408e-a391-98f688e2a2a8","html_url":"https://github.com/SoftwareAG/adabas-go-api","commit_stats":null,"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareAG%2Fadabas-go-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareAG%2Fadabas-go-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareAG%2Fadabas-go-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareAG%2Fadabas-go-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftwareAG","download_url":"https://codeload.github.com/SoftwareAG/adabas-go-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224319514,"owners_count":17291855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adabas","go","golang"],"created_at":"2024-08-02T17:00:52.101Z","updated_at":"2025-05-02T16:31:04.315Z","avatar_url":"https://github.com/SoftwareAG.png","language":"Go","readme":"# Exploit your assets in Adabas by using the Adabas API for Go\n\u003c!-- TOC --\u003e\n\n- [Exploit your assets in Adabas by using the Adabas API for Go](#exploit-your-assets-in-adabas-by-using-the-adabas-api-for-go)\n  - [Introduction](#introduction)\n  - [Features](#features)\n  - [Usage](#usage)\n    - [Enable native library access](#enable-native-library-access)\n  - [First step](#first-step)\n  - [Adabas API for Go example](#adabas-api-for-go-example)\n    - [Standard usage](#standard-usage)\n    - [Classic database usage](#classic-database-usage)\n    - [Adabas reflected to Go-struct](#adabas-reflected-to-go-struct)\n      - [Go-struct with Adabas Map definition](#go-struct-with-adabas-map-definition)\n      - [Define Go-struct to Adabas shortname field definition](#define-go-struct-to-adabas-shortname-field-definition)\n  - [Log output](#log-output)\n  - [Summary](#summary)\n\n\u003c!-- /TOC --\u003e\n## Introduction\n\nThis package is designed for using Adabas databases from Go. It's an data interface to Adabas. You can find a detailed overview about the design and technical implementation [here](.//doc//Overview.md).\n\nFor details have a look at the API documentation. It can be referenced here: \u003chttps://godoc.org/github.com/SoftwareAG/adabas-go-api/adabas\u003e\n\n## Features\n\nIn 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.\nThe Adabas API for Go provides a more user friendly and optimized use of Adabas files and fields.\nIt is similar to the `Adabas Client for Java` product delivered by Software GmbH.\n\nThis is a list of features which the Adabas API for Go supports:\n\n- Read,  Insert, Delete and Update of Adabas records\n- [Search](.//doc//QUERY.md) are limited to the Adabas standard search capabilities (see [Search](.//doc//QUERY.md) documentation)\n- Work with field descriptors and special descriptors like sub-/super-descriptors\n- Work with the Adabas TCP/IP (ADATCP) layer on Linux, Unix and Windows\n- Work with interface to Adabas Client library (ADALNK)\n- Work with Adabas Mainframe using the Entire Network infrastructure (ADALNK)\n- Support Unicode access of Adabas Unicode fields\n- Work with Adabas Maps, a short name to long name definition\n- Work with Adabas period groups and multiple fields\n- Work with large object reads and writes\n- Work with partial large object reads and writes\n- Is optimized for network access using ADATCP by using Multifetch feature\n- Provide Go structure usage by reflecting structure fields to Adabas Map definitions or plain Adabas shortnames\n\n## Usage\n\nInside 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:\n\n```bash\ngo get -u github.com/softwareag/adabas-go-api/adabas\n```\n\nYou can compile it with the new Adabas TCP/IP interface on Linux, Unix and Windows. In this case no additional native library is needed. This is the default behavior.\n\nAlternatively the Adabas native local access with Adabas client native libraries (ADALNK) can be used. The `AdabasClient` installation is a prerequisite in this case.\n\n### Enable native library access\n\nThe default is the Adabas TCP/IP interface enabled in the Go API. It is possible to enable Adabas Client native interface support using the Adabas Client library. 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:\n\nOn Unix:\n\n```sh\nCGO_CFLAGS=-I${ACLDIR}/inc\nCGO_LDFLAGS=-L${ACLDIR}/lib -ladalnkx -lsagsmp2 -lsagxts3 -ladazbuf\n```\n\nOn Windows:\n\n```bat\nCGO_CFLAGS=-I%ACLDIR%\\..\\inc\nCGO_LDFLAGS=-L%ACLDIR%\\..\\bin -L%ACLDIR%\\..\\lib -ladalnkx\n```\n\nThe application is built with Adabas API for Go as follows (please note that the tag `adalnk` is needed to enable local IPC access):\n\n```go\ngo build -tags adalnk application.go\n```\n\n## First step\n\nA detailed description how to do the first steps using the Adabas Docker community edition is provided [here](.//doc//FirstSteps.md).\nIndependent of the used environment of Docker (like Kubernetes or others), it describes how to call Adabas in a Microservice environment.\n\n## Adabas API for Go example\n\n### Standard usage\n\nThe logical view of the data can be defined using Adabas Maps. The Adabas Maps are introduced in the *Adabas Client for Java* product delivered by Software GmbH. A detailed description of Adabas maps is available [here](.//doc//AdabasMap.md).\n\nThe creation of Adabas maps is done by the infrastructure of the *Adabas Client for Java*. The product contains a Adabas Data Designer rich client or Eclipse plugin. The tools provide the management of Adabas map definitions. A programmatical approach to create Adabas maps is part of the Adabas API for Go.\n\nIn the first example a logical read on the database file uses Adabas maps:\n\n```go\nimport (\n  \"github.com/SoftwareAG/adabas-go-api/adabas\"\n)\n// Create new connection handler using the Adabas Map repository in database 24 file 4\nconnection, _ := adabas.NewConnection(\"acj;map;config=[24,4]\")\ndefer connection.Close()\n// Create a read request using the Map definition\nrequest, _ := connection.CreateMapReadRequest(\"EMPLOYEES-NAT-DDM\")\n// Define the result records content\n_ = request.QueryFields(\"NAME,PERSONNEL-ID\")\n// Read logical using a range search query\nresult, _ := request.ReadLogicalWith(\"PERSONNEL-ID=[11100301:11100303]\")\n// Result is dumped to stdout\nresult.DumpValues()\n```\n\nThe next example shows a cursor read  on the database file:\n\n```go\n// Read logical with cursor using a range search query\nresult,rerr := request.ReadLogicalWithCursoring(\"PERSONNEL-ID=[11100301:11100303]\")\n// Result is dumped to stdout\nfor col.HasNextRecord() {\n  record, rerr := col.NextRecord()\n    ...\n}\n```\n\nSee detailed documentation [here](.//doc//AdabasMap.md).\n\n### Classic database usage\n\nIt is possible to use classical Adabas database parameters to read data. The approach does not contain format enhancements like Natural DDM's or the Adabas Map approach. It is a raw access to the database.\n\nA quick example to read data from a database file 11 of the Adabas database with database ID 23 is here:\n\n```go\n// Create new connection handler to database\nconnection, _ := adabas.NewConnection(\"acj;target=23\")\ndefer connection.Close()\n// To work on file 11 create corresponding read request\nrequest, _ := connection.CreateFileReadRequest(11)\n// Define the result records content\nrequest.QueryFields(\"AA,AB\")\n// Requst unlimited number of records\nrequest.Limit = 0\n// Read in the database using search query\nresult,_ := request.ReadLogicalWith(\"AA=60010001\")\nvar aa,ac,ad,ae string\n// Read given AA(alpha) and all entries of group AB to string variables\nresult.Values[0].Scan(\u0026aa,\u0026ac,\u0026ad,\u0026ae)\n```\n\nThe example code is referenced [here](.//tests//simple_read.go). See detailed documentation [here](.//doc//README.md).\n\n### Adabas reflected to Go-struct \n\n#### Go-struct with Adabas Map definition\n\nThe Adabas API for Go can handle simple Go struct-definitions to map them to an Adabas Map definition.\n\nFor example if the structure is defined like this:\n\n```go\ntype Employees struct {\nID        string\nBirth     int64\nName      string `adabas:\"Name\"`\nFirst     string `adabas:\"FirstName\"`\n}\n```\n\nThe struct can be used to read or store data of the Adabas Map field `Birth`, `Name` and `FirstName` directly using the corresponding struct-fields `Birth`, `Name` and `First`.\nTo store the struct record, do this:\n\n```go\n// Create new connection handler to database\nconnection, _ := adabas.NewConnection(\"acj;map=EMPLOYEES\")\ndefer connection.Close()\n\nstoreRequest, err := connection.NewMapStoreRequest(Employees{})\ne:=  \u0026Employees{ID: \"ID3\", Birth: 456, Name: \"Name3\", FirstName: \"First name3\"}\nerr = storeRequest.StoreData(e)\nerr = storeRequest.EndTransaction()\n```\n\nThe read of the struct data will be done similar with:\n\n```go\n// Create new connection handler to database\nconnection, _ := adabas.NewConnection(\"acj;map=EMPLOYEE\")\ndefer connection.Close()\nrequest, _ := connection.CreateMapReadRequest(\u0026Employees{})\ndefer request.Close()\nresult, err := request.ReadLogicalWith(\"ID\u003e'ID'\")\ne := result.Data[0].(*Employees)\n```\n\nAll fields of the struct are mapped to an Adabas Map field name. The `adabas` tag of the struct definition changes the mapped name.\n\n\n#### Define Go-struct to Adabas shortname field definition\n\nThe Adabas API for Go can handle simple Go struct-definitions to map them to an Adabas field shortname. This is an direct connection into the database. It might be used to work on RAW data or Large objects directly.\n\nFor example if the structure is defined like this:\n\n```go\ntype NewEmployeesInMap struct {\n\tIndex  uint64                `adabas:\":isn\"`\n\tID     string                `adabas:\":key:AA\"`\n\tIncome []*NewEmployeesIncome `adabas:\"::L0\"`\n}\n\ntype NewEmployeesIncome struct {\n\tCurCode string `adabas:\"::LA\"`\n\tSalary  int    `adabas:\"::LB\"`\n\tBonus   []int  `adabas:\"::LC\"`\n}\n```\n\nThe Go-struct can be used to read or store data of the Adabas new employee example file (File 9) directly. In this example the slice of an sub structure is generated in the call. The third value in the `:`-separated field defines the Adabas shortname. In the example above, the period group L0 is read into the `NewEmployeesIncome` Go-struct-slice.\n\nTo read the record using the `NewEmployeesInMap`-struct out of Adabas database file 9 of database id 24:\n\n```go\nconnection, _ := NewConnection(\"acj;inmap=24\")\ndefer connection.Close()\nrequest, _ := connection.CreateMapReadRequest(\u0026NewEmployeesInMap{},9)\n_ = request.QueryFields(\"*\")\nresponse, rerr := request.SearchAndOrder(\"AA=11100108\", \"AA\")\n```\n\nTo read the record using the `NewEmployeesInMap`-struct out of Adabas database file 9 of database on ADATCP host `desthost` port `64100`, do this:\n\n```go\nconnection, _ := NewConnection(\"acj;inmap=adatcp://desthost:64100\")\ndefer connection.Close()\nrequest, _ := connection.CreateMapReadRequest(\u0026NewEmployeesInMap{},9)\n_ = request.QueryFields(\"*\")\nresponse, rerr := request.SearchAndOrder(\"AA=11100108\", \"AA\")\n```\n\nAll fields of the struct are mapped to an Adabas classic field shortname. The `adabas` tag of the struct definition defines the Adabas shortname.\n\n## Log output\n\nTo 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.\n\nTo use logging in your code with the Adabas API, you can enable logging by setting the log instance with your `logger` instances with:\n\n```go\nadatypes.Central.Log = logger\n```\n\n## Summary\n\nThe 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.\nGo 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.\nBy using the native `AdabasClient` library, you can access all platforms Adabas runs on like Linux, Unix, Windows and Mainframe (z/OS with Entire Network).\n\nStep by step all relevant Adabas features are or will be supported.\n\n______________________\nThese tools are provided as-is and without warranty or support. They do not constitute part of the Software GmbH product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software GmbH welcomes contributions, we cannot guarantee to include every contribution in the master project.\n______________\nFor more information you can Ask a Question in the [TECHcommunity Forums](https://tech.forums.softwareag.com/tag/adabas).\n\nYou can find additional information in the [Software GmbH TECHcommunity](http://techcommunity.softwareag.com/home/-/product/name/adabas).\n______________\nContact us at [TECHcommunity](mailto:technologycommunity@softwareag.com?subject=Github/SoftwareAG) if you have any questions.\n","funding_links":[],"categories":["Adabas and Natural"],"sub_categories":["![icon-Adabas-64x64](https://user-images.githubusercontent.com/23717841/230384852-da5ff0f6-5283-447d-9072-43b2c740d535.png) Adabas","adapya – Adabas Python packages"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSoftwareAG%2Fadabas-go-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSoftwareAG%2Fadabas-go-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSoftwareAG%2Fadabas-go-api/lists"}