Configuring IMS connections

The ims.connections.json file is the central configuration file for IMS database connections. It is located in the IMS workspace directory and supports a range of optional parameters that control connection behavior, data visibility, performance, SSL security, and diagnostics.

Overview

When you create a connection using the IMS Connections view, the extension generates a minimal ims.connections.json entry. You can edit this file directly to apply any of the advanced settings described in this topic.

Connection properties

The following properties apply to each named connection entry under profiles:

Property	Type	Description
dataStoreServer	String	The hostname or IP address of the IMS Connect server.
portNumber	Integer	The TCP/IP port number used to communicate with IMS Connect.
databaseName	String	The name of the database metadata representing the target IMS database.
metadataSource	String	The source of database metadata. Accepted values: "IMS Catalog".
fetchSize	Integer	Number of rows fetched per round trip to the server.
maxRows	Integer	Maximum number of rows returned by a query.
imsId	String	The identifier of the target IMS system.
imsPlexName	String	The name of the IMS plex that the target IMS system belongs to.

Show IMS Catalogs

Control visibility of system-level IMS catalog DBDs and PSBs (those with the DFSC prefix) by setting showIMSCatalogs in your connection configuration:

{
  "name": "MyConnection",
  "showIMSCatalogs": false
}

The default value is false, which hides system catalogs. Set to true to reveal them.

SSL certificate management

SSL certificate attributes can be configured for a database profile in ims.connections.json to establish secure connections to IMS.

{
  "profiles": {
    "imsdb": {
      "databaseConnectionName": {
        "dataStoreServer": "imshost.example.com",
        "portNumber": 8895,
        "databaseName": "IMSPROD1",
        "sslConnection": true,
        "sslKeyStoreType": "JKS",
        "sslKeyStoreLocation": "/path/to/keystore.jks",
        "sslTrustStoreLocation": "/path/to/truststore.jks",
        "sslKeyStorePassword": "<keystore-password>",
        "sslTrustStorePassword": "<truststore-password>",
        "sslSecureSocketProtocol": "TLS"
      }
    }
  }
}

Attribute	Description
sslConnection	Set to true to enable SSL for the connection.
sslKeyStoreType	The key store format. Accepted value: "JKS".
sslKeyStoreLocation	Absolute path to the key store file (.jks).
sslTrustStoreLocation	Absolute path to the trust store file (.jks).
sslKeyStorePassword	Password for the key store.
sslTrustStorePassword	Password for the trust store.
sslSecureSocketProtocol	The SSL protocol to use. Recommended value: "TLS" or "TLSv1.2".

Note: Store key store and trust store files in a secure location. Avoid committing passwords directly to source control. Consider using VS Code secret storage or environment variables to manage credentials.

Tracing and diagnostics

Tracing can be enabled on a per-connection basis to capture detailed diagnostic information about a connection's activity. Trace output is written to a file in the directory specified by traceDirectory.

{
  "traceFile": "imsdb.log",
  "traceFileAppend": true,
  "traceDirectory": "/path/to/logs",
  "traceLevel": -1
}

Attribute	Description
traceFile	Name of the trace output file.
traceFileAppend	Set to true to append to an existing trace file rather than overwriting it.
traceDirectory	Absolute path to the directory where the trace file is written.
traceLevel	Verbosity level for trace output. Use -1 for maximum detail.

Example: ims.connections.json

The following example shows a fully configured ims.connections.json file. It includes an imsdatabases profile with multiple named database connections—one standard, one with SSL and tracing enabled—and an imsconnects profile with IMS system identifier and IMS plex name properties.

{
  "profiles": {
    "imsdatabases": {
      "myConnection": {
        "dataStoreServer": "imshost1.example.com",
        "portNumber": 5555,
        "databaseName": "IMSPROD1",
        "metadataSource": "IMS Catalog",
        "fetchSize": 100,
        "maxRows": 500
      },
      "myConnection2": {
        "dataStoreServer": "imshost2.example.com",
        "portNumber": 5555,
        "databaseName": "IMSTEST1",
        "metadataSource": "IMS Catalog",
        "fetchSize": 100,
        "maxRows": 500
      },
      "ssl-connection": {
        "dataStoreServer": "imshost3.example.com",
        "portNumber": 8895,
        "databaseName": "IMSSEC1",
        "fetchSize": 100,
        "maxRows": 500,
        "sslConnection": true,
        "sslKeyStoreType": "JKS",
        "sslKeyStoreLocation": "/path/to/keystore.jks",
        "sslKeyStorePassword": "<keystore-password>",
        "sslTrustStoreLocation": "/path/to/truststore.jks",
        "sslTrustStorePassword": "<truststore-password>",
        "sslSecureSocketProtocol": "TLSv1.2",
        "traceFile": "imsdb.log",
        "traceFileAppend": true,
        "traceDirectory": "/path/to/logs",
        "traceLevel": -1,
        "metadataSource": "IMS Catalog"
      }
    },
    "imsconnects": {
      "myImsConnect": {
        "dataStoreServer": "imshost4.example.com",
        "portNumber": 9989,
        "imsId": "IMS1",
        "imsPlexName": "PLEX1"
      }
    }
  }
}