The "describeDataChangeStreams" action describes data change streams that you specify by ID. You typically list data streams and then describe the streams for which you want more information.
Request examples
Minimal
This example describes the data change stream with the unique identifier of 2.
{
"action": "describeDataChangeStreams",
"params": {
"ids": [2],
"includeMetrics": true
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Response examples
Maximal
This example returns all information about each affected data change stream.
{
"api": "admin",
"action": "deleteDataChangeStream",
"result": {
"description": "existing & new CA records from db1 ctreesql_admin_custmast",
"dataChangeStreamStatus": "starting",
"dataChangeStreamFirstStartTimestamp": "2025-06-07T12:23:19.275",
"dataChangeStreamLastStartTimestamp": "2025-06-07T12:23:19.275",
"dataChangeStreamLastPausedTimestamp": null,
"streamingConnectionName": "db1",
"streamingConnection": {
"sourceServerName": "FAIRCOMS",
"sourceHostname": "10.70.13.112",
"sourcePort": 5597,
"sourceUsername": "ADMIN",
"sourcePassword": "ADMIN",
"maxSecondsBeforeConnectingToNextServer": 15,
"tls": {
"enabled": true,
"caCertificateFilename": "ca.crt",
"allowedCipherSuites": "",
"clientCertificateEnabled": true,
"clientCertificateFilename": "admin_client.crt",
"clientPrivateKeyFilename": "admin_client.key"
},
"metadata": {
}
},
"topic": "custmast",
"localTableName": "custmast",
"localOwnerName": "admin",
"localDatabaseName": "faircom",
"localDataFilePath": "",
"sourceTableName": "custmast",
"sourceOwnerName": "admin",
"sourceDatabaseName": "ctreeSQL",
"sourceDataFilePath": "",
"includeExistingRecordsFilter": true,
"recordFilter": "!stricmp(cm_custstat,\"CA\")",
"includedFields": [
"cm_custnumb",
"cm_custzipc",
"cm_custcity"
],
"triggers": [
"insert",
"update",
"delete"
],
"recordFormat": "fields",
"tagChanges": "forEachField",
"includePrimaryKey": "forPrimaryKeyFields",
"includeMetadata": [
],
"revealAfterValueOnFilteredDelete": false,
"revealBeforeValueOnFilteredInsert": false,
"fixedOutput": false
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}
Properties
Request properties ("params")
| Property | Description | Default | Type | Limits (inclusive) |
|---|---|---|---|---|
ids |
The
|
Optional with default of Required when |
array | 0 or more ids |
includeMetrics |
The
By default, dynamically calculated properties are not included in the results because they take extra time to retrieve. |
Optional with default of false
|
Boolean |
|
Response properties ("result")
| Property | Description | Type | Limits (inclusive) |
|---|---|---|---|
dataChangeStreamFirstStartTimestamp |
The
|
string timestamp | "2025-06-07T12:23:19.275" |
dataChangeStreamLastPausedTimestamp |
The
|
string timestamp | "2025-06-07T12:23:19.275" |
dataChangeStreamLastStartTimestamp |
The
|
string timestamp | "2025-06-07T12:23:19.275" |
dataChangeStreamStatus |
The "dataChangeStreamStatus" property specifies the status of the data change stream. It may specify any of the following states: |
string enum |
|
description |
The Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:
In the Thing API, It defaults to
|
string | 1 to 65,500 bytes |
fixedOutput |
"fixedOutput" includes all properties in a data change event when true. |
Boolean |
|
includedFields |
The |
array of strings | 0 or more strings |
includeExistingRecordsFilter |
The |
Boolean |
|
includeMetadata |
The |
array of metadata objects | [
{
"propertyPath": "myPath",
"propertyValue": "myValue"
}
] |
includePrimaryKey |
The |
string |
|
localDatabaseName |
The |
string | 1 to 64 bytes |
localDataFilePath |
The |
string | No limits |
localOwnerName |
The |
string | 1 to 64 bytes |
localTableName |
The |
string | 1 to 64 bytes |
recordFilter |
The |
string | 1 to 65,000 bytes |
recordFormat |
The |
string |
|
revealAfterValueOnFilteredDelete |
The |
Boolean |
|
revealBeforeValueOnFilteredInsert |
The |
Boolean |
|
sourceDatabaseName |
The |
string | 1 to 64 bytes |
sourceDataFilePath |
The |
string | No limits |
sourceOwnerName |
The |
string | 1 to 64 bytes |
sourceTableName |
The |
string | 1 to 64 bytes |
streamingConnection |
The |
object | "streamingConnection": {
"sourceServerName": "FAIRCOMS",
"sourceHostname": "10.70.13.112",
"sourcePort": 5597,
"sourceUsername": "ADMIN",
"sourcePassword": "ADMIN",
"maxSecondsBeforeConnectingToNextServer": 15,
"tls": {
"enabled": true,
"caCertificateFilename": "ca.crt",
"allowedCipherSuites": "",
"clientCertificateEnabled": true,
"clientCertificateFilename": "admin_client.crt",
"clientPrivateKeyFilename": "admin_client.key"
},
"metadata": {}
}
|
|
streamingConnection .maxSecondsBeforeConnectingToNextServer |
The "maxSecondsBeforeConnectingToNextServer" property specifies the maximum number of seconds the server will attempt to reconnect to the existing server before it attempts to connect to the next server in the "sourceServers" list. |
int32 |
1 to 65535
|
|
streamingConnection .metadata |
The |
JSON | 0 to 65,500 bytes |
|
streamingConnection .sourceHostname |
The "sourceHostname" property specifies a unique host name or TCP/IP address of a FairCom DB or RTG server. |
string | 1 to 255 bytes |
|
streamingConnection .sourcePassword |
The "sourcePassword" property specifies the login password of a FairCom DB or RTG server. |
string | 1 to 128 bytes |
|
streamingConnection .sourcePort |
The "sourcePort" property specifies the ISAM TCP/IP port of a FairCom DB or RTG server. |
int16 |
1 to 65535
|
|
streamingConnection .sourceServerName |
The "sourceServerName" property 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. |
string | 1 to 255 bytes |
|
streamingConnection .sourceUsername |
The "sourceUsername" property specifies the name of a FairCom DB or RTG server. |
string | 1 to 64 bytes |
|
streamingConnection .tls |
The
|
object |
|
|
streamingConnection tls .allowedCipherSuites |
The
|
string | No limits |
|
streamingConnection tls .caCertificateFilename |
The
|
string | No limits |
|
streamingConnection tls .clientCertificateEnabled |
The "clientCertificateEnabled" property enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates. |
boolean |
|
|
streamingConnection tls .clientCertificateFilename |
string | No limits | |
|
streamingConnection tls .clientPrivateKeyFilename |
string | No limits | |
|
streamingConnection tls .enabled |
The "tls": {
"enabled": true,
"caCertificateFilename": "ca.crt",
"allowedCipherSuites": "",
"clientCertificateEnabled": true,
"clientCertificateFilename": "admin_client.crt",
"clientPrivateKeyFilename": "admin_client.key"
} |
Boolean |
|
streamingConnectionName |
The "streamingConnectionName" property 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. |
string | 1 to 64 characters |
tagChanges |
The |
string |
|
topic |
The |
string | A topic name between 1 and 65,500 bytes |
triggers |
The "triggers" property specifies a list of events on a table that create data change events. |
array of enum strings |
|