Skip to main content

"listStreamingConnections" (JSON Action)

Return a list of streaming connections that match all specified filters

The "listStreamingConnections" action lists streaming connections. 

This action ANDs together all the filter properties to create the filter. Omit a filter property or set it to null to prevent it from filtering the results. Omit all filters to return all connections.

When a filter property value is a string, the server treats it as a partial match of each character in the property's value to the corresponding character in the definitions. The server does not process characters as wildcards.

The action returns the following metrics:

  • The "estimatedBacklogSeconds" property reports the approximate time, in seconds, needed by the FairCom MQ server to apply data changes from the source server.

  • The "incomingBytesPerSecond" property reports the data change throughput, in bytes per second, streamed from the source FairCom server to FairCom MQ.

  • The "appliedBytesPerSecond" property reports the data change throughput, in bytes per second, applied by FairCom MQ. The difference between the incoming and applied throughput indicates whether the backlog is increasing or decreasing.

Note

There is no "describeStreamingConnections" action because a server will have too few connections to streaming servers.

Request examples

Minimal

This example returns all streaming connections.

{
  "api": "admin",
  "action": "listStreamingConnections",
  "params": {},
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

This example returns only those streaming connections that match the filter criteria.

{
  "api": "admin",
  "action": "listStreamingConnections",
  "params": {
    "streamingConnectionNameFilter": "fmq",
    "sourceServerNameFilter": "FC",
    "sourceHostnameFilter": "10.70.13",
    "sourcePortFilter": 5597,
    "sourceUsernameFilter": "AD"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response examples

Maximal

{
  "authToken": "authToken",
  "result": {
    "streamingConnections": [
      {
        "streamingConnectionName": "db1",
        "estimatedBacklogSeconds": 100,
        "metadata": {
        },
        "maxSecondsBeforeConnectingToNextServer": 15,
        "streamParallelism": 4,
        "sourceServers": [
          {
            "purpose": "Primary Server",
            "sourceServerName": "FAIRCOMS",
            "sourceHostname": "10.70.13.112",
            "sourcePort": 5597,
            "sourceUsername": "ADMIN",
            "sourcePassword": "ADMIN",
            "tls": {
              "enabled": true,
              "caCertificateFilename": "ca.crt",
              "allowedCipherSuites": "",
              "clientCertificateEnabled": true,
              "clientCertificateFilename": "admin_client.crt",
              "clientPrivateKeyFilename": "admin_client.key"
            }
          },
          {
            "purpose": "Secondary Server",
            "sourceServerName": "FAIRCOMS2",
            "sourceHostname": "10.70.13.113",
            "sourcePort": 5597,
            "sourceUsername": "ADMIN",
            "sourcePassword": "ADMIN",
            "tls": {
              "enabled": true,
              "caCertificateFilename": "ca.crt",
              "allowedCipherSuites": "",
              "clientCertificateEnabled": true,
              "clientCertificateFilename": "admin_client.crt",
              "clientPrivateKeyFilename": "admin_client.key"
            }
          }
        ]
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": ""
}

"params"

Table 1. listStreamingConnections "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

sourceHostnameFilter

(optional) specifies a partial match for a hostname.

null

string

1 to 64 bytes

sourcePortFilter

(optional) specifies a complete match for a port number.

null

integer

1 to 65535

sourceServerNameFilter

(optional) specifies a partial match for a server name.

null

string

1 to 64 bytes

sourceUsernameFilter

(optional) specifies a partial match for a user name.

null

string

1 to 64 bytes

streamingConnectionNameFilter

(optional) specifies a partial match for a streaming connection name.

null

string

1 to 512 bytes



"sourceHostnameFilter"

The "sourceHostnameFilter" property is an optional string that specifies a partial match for a hostname.

"sourcePortFilter"

The "sourcePortFilter" property is an optional integer that specifies a complete match for a port number.

"sourceServerNameFilter"

The "sourceServerNameFilter" property is an optional string that specifies a partial match for a server name.

"sourceUsernameFilter"

The "sourceUsernameFilter" property is an optional string that specifies a partial match for a user name.

"streamingConnectionNameFilter"

The "streamingConnectionNameFilter" property is an optional string that specifies a partial match for a connection name.

"result"

Table 2. listStreamingConnections "result" property summaries

Property

Description

Type

Contents

streamingConnections

lists the streaming connections that match the filters in the request as separate objects.

array of objects

0 or more objects

streamingConnections
.estimatedBacklogSeconds

reports the approximate time, in seconds, needed by the FairCom MQ server to apply data changes from the source server.

integer

0 to 4294967296

streamingConnections
.metadata

specifies metadata about the streaming connection. It must be a JSON object and you may add your own properties to it.

object

No limits

streamingConnections
.sourceServers

specifies a list of FairCom DB or RTG servers. FairCom MQ attempts to connect to the first server in the list. If that fails, it attempts to connect to the next one. If it reaches the last server in the list, it attempts to connect to the first.

array of server connection objects

{
  "purpose": "Primary Server",
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  }
}
streamingConnections
.sourceServers
.purpose

defines a short description of the server's purpose.

string

1 to 64 bytes

streamingConnections
.sourceServers
.sourceHostname

specifies a unique host name or TCP/IP address of a FairCom DB or RTG server.

string

1 to 255 bytes

streamingConnections
.sourceServers
.sourcePassword

specifies the login password of a FairCom DB or RTG server.

string

1 to 128 bytes

streamingConnections
.sourceServers
.sourcePort

specifies the ISAM TCP/IP port of a FairCom DB or RTG server.

int16

1 to 65535

streamingConnections
.sourceServers
.sourceServerName

specifies the server name of a FairCom DB or RTG server. It is the name specified by the SERVER_NAME keyword defined in the target server's configuration file, ctsrvr.cfg. The server name used by most FairCom DB and RTG servers is "FAIRCOMS".

string

1 to 255 bytes

streamingConnections
.sourceServers
.sourceUsername

specifies the login name of a FairCom DB or RTG server.

string

1 to 64 bytes

streamingConnections
.sourceServers
.tls

specifies Transport Layer Security settings for connecting to a FairCom DB or RTG server.

object

"allowedCipherSuite"
"caCertificateFilename"
"clientCertificateEnabled"
"clientCertificateFilename"
"clientPrivateKeyFilename"
"enabled"
streamingConnections
.sourceServers
.tls
.allowedCipherSuites

limits the ciphers that FairCom MQ is willing to use when communicating with a FairCom DB or RTG server.

string

No limits

streamingConnections
.sourceServers
.tls
.caCertificateFilename

specifies the name and optional path of the CA certificate file (such as ca.pem).

string

No limits

streamingConnections
.sourceServers
.tls
.clientCertificateEnabled

enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates.

Boolean

false
true
streamingConnections
.sourceServers
.tls
.clientCertificateFilename

specifies the file name, such as admin_client.crt, of a client certificate accepted by the target FairCom DB or RTG server.

string

No limits

streamingConnections
.sourceServers
.tls
.clientPrivateKeyFilename

specifies the file name, such as admin_client.key, of a client certificate private key file accepted by the target FairCom DB or RTG server.

string

No limits

streamingConnections
.sourceServers
.tls
.enabled

enables or disables tls.

Boolean

false
true
streamingConnections
.streamingConnectionName

specifies a unique, user-defined name for a streaming connection. This API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server.

string

1 to 64 bytes

streamingConnections
.streamParallelism

specifies the number of parallel streams the server uses to deliver data changes to the FairCom MQ server. You typically use a number that does not exceed the number of cores on the FairCom MQ server.

integer

1 to 65535



"streamingConnections"

The "streamingConnections" property is an array of objects that list the streaming connections that match the filters in the request as separate objects.

"estimatedBacklogSeconds"

The "estimatedBacklogSeconds" property is an integer that reports the approximate time, in seconds, needed by the FairCom MQ server to apply data changes from the source server.

"metadata"

The "metadata" property is an optional JSON object. It exists primarily for the user interface to find integration information. By default, it is an empty JSON object.

  • It contains a flexible set of properties.

  • It typically contains tags and description properties.

Example

{
  "description": "",
  "tags": [""],
  "yourOwnProperties": "usage, purpose, notes, location, etc.",
}

"sourceServers"

The "sourceServers" property is a required array containing a list of FairCom DB or RTG server connection objects. FairCom MQ attempts to connect to the first server in the list. If that fails, it attempts to connect to the next one. If it reaches the last server in the list, it attempts to connect to the first.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"purpose"

The "purpose" property is an optional string that provides a short description of the specified server's purpose.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourceHostname"

The "sourceHostname" property is a required string that specifies a unique host name or TCP/IP address of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourcePassword"

The "sourcePassword" property is an optional string that specifies the login password of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourcePort"

The "sourcePort" property is an optional integer that specifies the ISAM TCP/IP port of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourceServerName"

The "sourceServerName" property is a conditional string that specifies the server name of a FairCom DB or RTG server. It is the name specified by the SERVER_NAME keyword defined in the target server's configuration file, ctsrvr.cfg. The server name used by most FairCom DB and RTG servers is "FAIRCOMS". This property is required if the "sourceHostname" is not defined.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourceUsername"

The "sourceUsername" property is an optional string that specifies the name of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"tls"

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the cipher suites that are allowed, and whether the client certificate is required. This property is optional. It defaults to an empty object. 

Example

"tls": { 
  "serverCertificateFilename": "server.crt", 
  "privateKeyFilename": "server.key",
  "caCertificateFilename": "ca.crt",
  "allowedCipherSuites": "AES256-SHA256"
  "requireClientCertificate": "true"
}

"allowedCipherSuites"

"caCertificateFilename"

"requireClientCertificate"

"allowedCipherSuites"

"caCertificateFilename"

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

"clientCertificateEnabled"

The "clientCertificateEnabled" property is an optional boolean that enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

"clientCertificateFilename"

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

"clientPrivateKeyFilename"

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

"enabled"

The "enabled" property is an optional Boolean that specifies whether or not the feature is enabled. The example below enables the TLS feature.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

"streamingConnectionName"

The "streamingConnectionName" property is a required string that specifies a unique, user-defined name for a streaming connection. The API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server.

  "params": {
    "streamingConnectionName": "db1",
    "metadata": {},
    "maxSecondsBeforeConnectingToNextServer": 15,
    "streamParallelism": 4,
    "sourceServers": []
  },

"streamParallelism"

The "streamParallelism" property is an optional integer that specifies the number of parallel streams the server uses to deliver data changes to the FairCom MQ server. You typically use a number that does not exceed the number of cores on the FairCom MQ server.

  "params": {
    "streamingConnectionName": "db1",
    "metadata": {},
    "maxSecondsBeforeConnectingToNextServer": 15,
    "streamParallelism": 4,
    "sourceServers": []
  },

JavaScript Object Notation (JSON) is a simple format for representing data. It requires very little markup and is flexible enough to represent the majority of data structures. It is self-describing, which makes it ideal for schemaless applications and search. It can optionally be paired with a schema to define an expected structure.