NSADALoader

What NSADALoader is

nsadaloader loads data from JSON, CSV, TSV and XML files into Adabas databases. It inserts new records (STORE, no isn field) and updates existing ones (UPDATE, with isn field) from a single file that can span multiple files and databases. It supports MU fields (arrays), PE groups (arrays of objects) and index notation (FIELD[n], FIELD[n,m]), plus exporting (-output) and template generation (-describe).

Ideal uses:

Data migration from external systems into Adabas.
Initial master-data loads and automated ETL.
Mass updates of records (by ISN or MU/PE indexes).
Export, edit and reload (the -output → edit → -input flow).

Dbids, fnrs, field names and data in the examples are fictitious.

Use cases

1. Initial customer load (STORE)

Insert three new customers from a self-contained JSON file.

nsadaloader -input /tmp/load/new_customers.json

{ "dbid": 50, "fnr": 15, "records": [{ "AA": "CLI001", "AB": "EXAMPLE CORP" }] }

2. Mass update by ISN (UPDATE)

Update names and salaries of existing records identified by ISN.

nsadaloader -input /tmp/load/update_salaries.json

3. Multi-file migration in a single pass

Load customers (file 15) and orders with a PE group (file 16) of the same database from one file.

nsadaloader -input /tmp/load/full_migration.json -batch 100

4. CSV load with a DDM schema

Load invoices from CSV with type conversion driven by the DDM (dates, packed fields, PE/MU).

nsadaloader -dbid 50 -fnr 20 -config /tmp/cfg/ddm_invoices.json -input /tmp/load/invoices.csv

5. Export, edit and reload

Export with ISN, fix in an editor and reload: records with isn are updated, without isn are inserted.

nsadaloader -dbid 50 -fnr 15 -output /tmp/load/employees_export.json
nsadaloader -input /tmp/load/employees_export.json

Command reference

Loading (STORE/UPDATE)

Parameter	Description	Required
`-input`	Input file with the records (JSON, CSV, TSV or XML)	Unless `-describe` or `-output`
`-dbid`	Adabas database ID (overrides the file value)	Depends on format (yes for legacy/flat)
`-fnr`	Adabas file number (overrides the file value)	Depends on format (yes for legacy/flat)
`-ddmname`	DDM name from the configuration file	Depends on format
`-config`	JSON configuration file with DDM definitions (generated by `nsddm`)	If `-ddmname` is used (recommended with CSV/TSV/XML)
`-format`	Input format: `json`, `csv`, `tsv` or `xml` (default: detected from the extension)	No
`-batch`	Records per transaction (default 100; 0 = single transaction)	No

Export

Parameter	Description	Required
`-output`	Output JSON file to export records from Adabas (compatible with `-input`)	When exporting
`-limit`	Maximum records to export (0 = no limit)	No

Templates and reads (`-describe`)

Parameter	Description	Required
`-describe`	Describes the file structure and generates an editable JSON template (read-only connection)	No
`-isn`	ISN to read, only with `-describe` (template with real data)	No

Common and licensing

Parameter	Description	Required
`-silence`	Silent mode	No
`-debug`	Detailed logging	No
`-etid`	External Transaction ID (ETID)	No
`-version`	Shows version information	No
`-license`	Path to the signed `license.key` file (default: automatic resolution)	No
`-license-fingerprint`	Prints this machine’s license fingerprint and exits	No

Commented examples

# 1. Basic self-contained load (STORE without isn / UPDATE with isn)
nsadaloader -input /tmp/load/basic_load.json

# 2. One transaction every 50 records (recommended for large loads)
nsadaloader -input /tmp/load/batch_50000.json -batch 50

# 3. Empty template, edit and load (the -describe flow)
nsadaloader -dbid 50 -fnr 15 -describe > /tmp/load/template.json
nsadaloader -input /tmp/load/template.json

# 4. Read a real record as a template (ISN 42) and export a sample
nsadaloader -dbid 50 -fnr 15 -describe -isn 42 > /tmp/load/record42.json
nsadaloader -dbid 50 -fnr 16 -output /tmp/load/sample.json -limit 50

# 5. CSV load with DDM and flat XML load with CLI flags
nsadaloader -dbid 50 -fnr 20 -config /tmp/cfg/ddm_invoices.json -input /tmp/load/invoices.csv
nsadaloader -dbid 50 -fnr 20 -config /tmp/cfg/ddm_invoices.json -input /tmp/load/invoices_flat.xml

# 6. Machine fingerprint and load with an explicit license
nsadaloader -license-fingerprint
nsadaloader -license /opt/ns/licenses/nsadaloader.key -input /tmp/load/records.json

Return codes

Code	Meaning
`0`	Success
`1`	Parameter error
`2`	Configuration or input file error
`3`	Connection error
`4`	Error during load

An invalid license (wrong app, different machine, expired or corrupt) blocks execution with a non-zero exit code.

FAQ

How does it tell STORE from UPDATE? By the isn field: without isn it inserts (Adabas assigns a new ISN); with isn it updates that record. In CSV/TSV/XML the isn column or element matches the JSON field. To duplicate exported records, remove the isn.

Do I need -config? Only with -ddmname or DDM names in the data. Without -config, the file must use short names (AA, AB). With CSV/TSV/XML, -config is recommended so dates, packed and numeric values convert per each field’s real type.

How do I load MU and PE fields? MU as arrays ("AG": ["a@x.com", "b@x.com"]), PE as arrays of objects ("AD": [{"AE": "...", "AF": "..."}]). To update single occurrences use 1-based indexes: AG[2], AE[1], AJ[1,2] (PE n, MU m). In CSV the notation is BC[1], AE[1].AF, AQ[1].AU[2]; in XML, repeated elements.

Which -batch size should I use? The default (100) fits most cases; above 10,000 records use 50–500. With -batch 0 everything goes in one transaction (faster but riskier on failure). If one record fails, the utility continues with the next.