Creating ISAM Metadata
ISAM metadata is used to implement ISAM-to-ISAM replication via the ISAM Agent which is configured in the environment using the IsamFileMapping section of MasterConfig.json.
View the current ISAM metadata
- Use the Configuration Server UI to review the current mappings, which are for two sample ISAM files named DEPARTMENT.ISM and EMPLOYEE.ISM.
You will see metadata like this:
"IsamFileMapping": {
"Logicals": {
"SIP_DAT": "C:/PATH/TO/DIRECTORY"
},
"Mappings": [
{
"Enabled": true,
"FileName": "DEPARTMENT.ISM",
"FileSpec": "SIP_DAT:DEPARTMENT.ISM",
"FileType": "ISAM",
"RecordLength": 100,
"FileAttributes": "FIXED,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=15,NAME=\"dept_id\",TYPE=ALPHA,ORDER=A,DENSITY=75,NODUPS,NOMODIFY,ASCEND",
"START=66,LENGTH=6,NAME=\"dept_manager\",TYPE=ALPHA,ORDER=A,DENSITY=50,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "20240901000000000000"
},
{
"Enabled": true,
"FileName": "EMPLOYEE.ISM",
"FileSpec": "SIP_DAT:EMPLOYEE.ISM",
"FileType": "ISAM",
"RecordLength": 300,
"FileAttributes": "FIXED,COMPRESS,DENSITY=50,PAGE=1024,TBYTE",
"IsamKeys": [
"START=1,LENGTH=8,NAME=EMP_ID,TYPE=DECIMAL,ORDER=A,DENSITY=50,NODUPS,NOMODIFY",
"START=49,LENGTH=15,NAME=EMP_DEPT,ASCEND,DENSITY=50,DUPS,ATEND,MODIFY",
"START=29,LENGTH=20,NAME=EMP_LAST_NAME,TYPE=NOCASE,ORDER=A,DENSITY=50,DUPS,ATEND,MODIFY",
"START=218,LENGTH=2,NAME=STATE_CODE,TYPE=ALPHA,ORDER=A,DENSITY=50,DUPS,ATEND,MODIFY",
"START=220,LENGTH=5,NAME=ZIP_CODE,TYPE=DECIMAL,ORDER=A,DENSITY=50,DUPS,ATEND,MODIFY"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "20240901000000000000"
}
]
}
As you can see, the ISAM Metadata contains all of the data required to define and create a new instance of the ISAM file. Imagine you were writing DBL code to create a file, the data that you would need to successfully create the files using XCALL ISAMC is all here.
But the application environment that we will be working in does not use these two files, it uses these files:
DAT:customer.ism
DAT:employee.ism
DAT:inventory.ism
DAT:order.ism
DAT:orderline.ism
DAT:shipto.ism
DAT:user.ism
DAT:vendor.ism
DAT:warehouse.ism
So you need to generate new metadata for these files, and replace the metadata in MasterConfig.json.
Creating ISAM metadata is one of the functions of metadatatool which you recently installed on your Linux system.
Metadatatool can create ISAM metadata either by reading information directly from ISAM files, or by parsing the necessary information out of OpenVMS FDL files. In this case you will make the metadata directly from the ISAM files.
Generate new ISAM metadata
cd ~ && export DAT=~/data && metadatatool isamfile --input DAT:*.ism --verbose
You should see something like this:
Input file : /home/admin/data/*.ism
Matching files : 9
Missing : 0
Failed to process : 0
Created : /home/admin/FILES.JSON
You should also have a new FILES.JSON file in your current directory. If you want to see what was created, it's here:
Click to see the new ISAM Metadata
[
{
"Enabled": true,
"FileName": "customer.ism",
"FileSpec": "DAT:customer.ism",
"MetaDataSource": "customer.ism",
"FileType": "ISAM",
"RecordLength": 287,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=8,NAME=CUSTOMER_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=9,LENGTH=40,NAME=NAME,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=270,LENGTH=6,NAME=SALES_REP_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=146:109,LENGTH=2:25,NAME=COUNTRY_CITY,TYPE=ALPHA:ALPHA,ORDER=A:A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=163,LENGTH=50,NAME=EMAIL,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=255,LENGTH=15,NAME=TAX_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=243,LENGTH=1,NAME=TYPE,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=279,LENGTH=1,NAME=STATUS,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8007022Z"
},
{
"Enabled": true,
"FileName": "employee.ism",
"FileSpec": "DAT:employee.ism",
"MetaDataSource": "employee.ism",
"FileType": "ISAM",
"RecordLength": 280,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=6,NAME=EMPLOYEE_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=27:7,LENGTH=30:20,NAME=NAME_LAST_FIRST,TYPE=ALPHA:ALPHA,ORDER=A:A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=221,LENGTH=4,NAME=WAREHOUSE_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=265,LENGTH=6,NAME=SUPERVISOR_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8019442Z"
},
{
"Enabled": true,
"FileName": "inventory.ism",
"FileSpec": "DAT:inventory.ism",
"MetaDataSource": "inventory.ism",
"FileType": "ISAM",
"RecordLength": 125,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=8,NAME=SKU,TYPE=ALPHA,ORDER=A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=9,LENGTH=40,NAME=DESCRIPTION,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=100,LENGTH=6,NAME=VENDOR_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=106,LENGTH=4,NAME=WAREHOUSE_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=49,LENGTH=2,NAME=CATEGORY,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=117,LENGTH=1,NAME=STATUS,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8026874Z"
},
{
"Enabled": true,
"FileName": "order.ism",
"FileSpec": "DAT:order.ism",
"MetaDataSource": "order.ism",
"FileType": "ISAM",
"RecordLength": 83,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=8,NAME=ORDER_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=9,LENGTH=8,NAME=CUSTOMER_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=21,LENGTH=4,NAME=WAREHOUSE_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=25,LENGTH=6,NAME=SALES_REP_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=31,LENGTH=8,NAME=ORDER_DATE,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=9:17,LENGTH=8:4,NAME=SHIPTO_ID,TYPE=ALPHA:ALPHA,ORDER=A:A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8034747Z"
},
{
"Enabled": true,
"FileName": "orderline.ism",
"FileSpec": "DAT:orderline.ism",
"MetaDataSource": "orderline.ism",
"FileType": "ISAM",
"RecordLength": 63,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1:9,LENGTH=8:4,NAME=ORDERLINE_ID,TYPE=ALPHA:ALPHA,ORDER=A:A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=13,LENGTH=8,NAME=SKU,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=21,LENGTH=4,NAME=WAREHOUSE_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8042889Z"
},
{
"Enabled": true,
"FileName": "shipto.ism",
"FileSpec": "DAT:shipto.ism",
"MetaDataSource": "shipto.ism",
"FileType": "ISAM",
"RecordLength": 198,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1:9,LENGTH=8:4,NAME=SHIPTO_ID,TYPE=ALPHA:ALPHA,ORDER=A:A,DENSITY=0,NODUPS,NOMODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8051487Z"
},
{
"Enabled": true,
"FileName": "user.ism",
"FileSpec": "DAT:user.ism",
"MetaDataSource": "user.ism",
"FileType": "ISAM",
"RecordLength": 162,
"FileAttributes": "FIXED,COMPRESS,PAGE=1024,SGRFA,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=40,NAME=USERNAME,TYPE=NOCASE,ORDER=A,DENSITY=50,NODUPS,NOMODIFY,ASCEND",
"START=61,LENGTH=20,NAME=LASTNAME,TYPE=NOCASE,ORDER=A,DENSITY=50,DUPS,ATEND,MODIFY,ASCEND",
"START=81,LENGTH=50,NAME=EMAIL,TYPE=NOCASE,ORDER=A,DENSITY=50,NODUPS,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8058344Z"
},
{
"Enabled": true,
"FileName": "vendor.ism",
"FileSpec": "DAT:vendor.ism",
"MetaDataSource": "vendor.ism",
"FileType": "ISAM",
"RecordLength": 270,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=6,NAME=ID,TYPE=ALPHA,ORDER=A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=7,LENGTH=40,NAME=NAME,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=144:107,LENGTH=2:25,NAME=COUNTRY_CITY,TYPE=ALPHA:ALPHA,ORDER=A:A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=161,LENGTH=50,NAME=EMAIL,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=244,LENGTH=15,NAME=TAX_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=241,LENGTH=1,NAME=TYPE,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND",
"START=262,LENGTH=1,NAME=STATUS,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8066427Z"
},
{
"Enabled": true,
"FileName": "warehouse.ism",
"FileSpec": "DAT:warehouse.ism",
"MetaDataSource": "warehouse.ism",
"FileType": "ISAM",
"RecordLength": 158,
"FileAttributes": "FIXED,COMPRESS,PAGE=4096,STATIC_RFA,TBYTE",
"IsamKeys": [
"START=1,LENGTH=4,NAME=WAREHOUSE_ID,TYPE=ALPHA,ORDER=A,DENSITY=0,NODUPS,NOMODIFY,ASCEND",
"START=5,LENGTH=30,NAME=WAREHOUSE_NAME,TYPE=ALPHA,ORDER=A,DENSITY=0,DUPS,ATEND,MODIFY,ASCEND"
],
"IsamReplicationKeyNum": 0,
"RequiresReplicationKey": false,
"ReplicationKeyPosition": 0,
"Revision": 1,
"Created": "2026-10-07T21:11:41.8072996Z"
}
]
Next you must update MasterConfig.json by putting the new metadata into the IsamFileMapping.Mappings property. On Linux this can be achieved with a single jq command:
Execute this command to replace the ISAM metadata in MasterConfig.json
CONFDIR=/etc/synergex/sip/config-server/default && sudo cp $CONFDIR/MasterConfig.json{,.bak} && sudo jq --slurpfile files ~/FILES.JSON '.IsamFileMapping.Mappings = $files[0]' $CONFDIR/MasterConfig.json > /tmp/MasterConfig.json && sudo cp /tmp/MasterConfig.json $CONFDIR/MasterConfig.json && unset CONFDIR
Before proceeding, it is a good idea to verify that the updated ISAM metadata is in place.
Verify ISAM metadata in Configuration Server
- Use the Configuration Server UI to view the updated ISAM metadata.
You should see that the ISAM metadata has been updated to reflect the nine ISAM files.
The final part of this step is to make sure that we tell the ISAM Agent where to store its replica data set.
In Configuration Server
- Select MasterConfig.json
- Click the Edit File button to make the file editable.
- Scroll to the IsamFileMapping section and locate the Logicals property.
- Add a value for the logical nmae DAT with a value of /sip/data.
- Remove the trailing comma after the first logical name, and the second logical name definition.
- Click the Save File button to save the change.
More about MetaDataTool
If you would like to read more about how to install metadatatool, and its capabilities, you can do so HERE.