The "createAndStartDataChangeStreams" action starts processing one or more data change streams for the specified streaming connection. If a stream includes existing records, this action adds the stream to a queue where the server loads existing records from tables in the order you start them.
You can call "createAndStartDataChangeStreams" after it has already started to resume a paused stream.
This action returns the unique ID of the streams along with the stream properties. You use the unique ID to pause, list, and describe streams.
It uses the "streamingConnectionName" property to connect the stream to one table in a FairCom DB or RTG server. You must use the "sourceTableName", "sourceOwnerName", and "sourceDatabaseName" properties to specify the table. You may optionally use the "localTableName", "localOwnerName", and "localDatabaseName" properties to specify your own name for the table in FairCom MQ; otherwise the action uses the source name, owner, and database.
At any time, you can use the "tableName" property of MQ API's "configureTopic" action to assign or change the topic assigned to the local table created by this action.
You can set the "includeExistingRecords" property to true to start a data change stream from the first record in the table or set the "includeExistingRecords" property to false to start the stream from the next data change event. When a stream starts from the first record, FairCom MQ loads all existing data into the target servers as data change events. The time to synchronize existing records depends on the number of existing records.
You may optionally use the "recordFilter" property to include matching records in the stream. The filter uses FairCom's expression language.
You may optionally use the "includedFields" property to include specific fields in the stream.
Request examples
Minimal
{
"action": "createAndSstartDataChangeStreams",
"params": {
"streamingConnectionName": "db1",
"streams": [
{
"description": "new records from ctreesql_admin_custmast to custmast",
"topic": "custmast",
"sourceTableName": "custmast",
"sourceOwnerName": "admin",
"sourceDatabaseName": "ctreeSQL",
"includeExistingRecords": false
}
]
},
"authToken": "replaceWithAuthTokenFromCreateSession"
}Maximal
This example returns all information about each affected data change stream.
{
"api": "admin",
"action": "createAndSstartDataChangeStreams",
"params": {
"streamingConnectionName": "db1",
"streams": [
{
"description": "existing & new CA records from ctreesql_admin_custmast",
"topic": "custmast",
"localTableName": "custmast",
"localOwnerName": "admin",
"localDatabaseName": "faircom",
"localDataFilePath": "",
"sourceTableName": "custmast",
"sourceOwnerName": "admin",
"sourceDatabaseName": "ctreeSQL",
"sourceDataFilePath": "",
"includeExistingRecords": 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"
}
Response examples
Maximal
{
"api": "admin",
"action": "createASstartDataChangeStreams",
"params": {
"streams": [
{
"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",
"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": "",
"includeExistingRecords": 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) |
|---|---|---|---|---|
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. |
Required - No default value | string | 1 to 64 characters |
streams |
The "streams" property specifies an array of stream definitions. |
Required - No default value | Array of stream definitions | 1 or more stream definitions |
|
streams .description |
The "description" property describes objects such as code packages, labels, or things. The server indexes this field with a full-text index so that you can search for any word or phrase. You cannot use this property for filtering in the Thing API. |
Optional with default of
|
string |
0 to 65,500 bytes 1 to 512 bytes for the Thing API |
|
streams .fixedOutput |
The |
Optional with default of false
|
Boolean |
|
|
streams .includedFields |
The |
Optional with default of []
|
array of strings | 0 or more strings |
|
streams .includeExistingRecords |
The |
Optional with default of null
|
Boolean |
|
|
streams .includeMetadata |
The |
Optional with default of |
Boolean |
|
|
streams .includePrimaryKey |
The "includePrimaryKey" property specifies when to add the "pk" property to the data change event's "fields" object to indicate the field's position in the primary key. |
Optional with default of "forPrimaryKeyFields"
|
string enum |
|
|
streams .localDatabaseName |
The |
Optional with default of the "defaultDatabaseName" value that is set during "createSession". If no default is set during "createSession", then "faircom" is used. |
string | 1 to 64 bytes |
|
streams .localDataFilePath |
The |
Required if "localTableName" is not specified. |
string | No limits |
|
streams .localOwnerName |
The |
Optional with default of the "defaultOwnerName" value that is set during "createSession". If no default is set during "createSession", then "admin" is used. |
string | 1 to 64 bytes |
|
streams .localTableName |
The |
Required if "localDataFilePath" is not specified |
string | 1 to 64 bytes |
|
streams .recordFilter |
The |
Optional with default of ""
|
string | 1 to 65,000 bytes |
|
streams .recordFormat |
The |
Optional with default of "fields"
|
string enum |
|
|
streams .revealAfterValueOnFilteredDelete |
The |
Optional with default of false
|
Boolean |
|
|
streams .revealBeforeValueOnFilteredInsert |
The |
Optional with default of false
|
Boolean |
|
|
streams .sourceDatabaseName |
The |
Optional with default of the "defaultDatabaseName" value that is set during "createSession". If no default is set during "createSession", then "faircom" is used. |
string | 1 to 64 bytes |
|
streams .sourceDataFilePath |
The |
Required - if "sourceTableName" is not specified |
string | No limits |
|
streams .sourceOwnerName |
The |
Optional with default of the "defaultOwnerName" value that is set during "createSession". If no default is set during "createSession", then "admin" is used. |
string | 1 to 64 bytes |
|
streams .sourceTableName |
The |
Required if "sourceDataFilePath" is not specified |
string | 1 to 64 bytes |
|
streams .tagChanges |
The |
Optional with default of "forEachField"
|
string enum |
|
|
streams .topic |
The
|
Optional with default of ""
|
string | 1 to 65,500 bytes |
|
streams .triggers |
The |
Optional with default of [ "insert", "update", "delete" ]
|
array of enum strings |
|
Response properties ("result")
| Property | Description | Type | Limits (inclusive) |
|---|---|---|---|
streams |
The "streams" property specifies an array of stream definitions. |
Array of stream definitions | 1 or more stream definitions |
|
streams .dataChangeStreamFirstStartTimestamp |
The
|
string timestamp | "2025-06-07T12:23:19.275" |
|
streams .dataChangeStreamLastPausedTimestamp |
The
|
string timestamp | "2025-06-07T12:23:19.275" |
|
streams .dataChangeStreamLastStartTimestamp |
The
|
string timestamp | "2025-06-07T12:23:19.275" |
|
streams .dataChangeStreamStatus |
The "dataChangeStreamStatus" property specifies the status of the data change stream. It may specify any of the following states: |
string enum |
|
|
streams .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 |
|
streams .fixedOutput |
"fixedOutput" includes all properties in a data change event when true. |
Boolean |
|
|
streams .includedFields |
The |
array of strings | 0 or more strings |
|
streams .includeExistingRecordsFilter |
The |
Boolean |
|
|
streams .includeMetadata |
The |
array of metadata objects | [
{
"propertyPath": "myPath",
"propertyValue": "myValue"
}
] |
|
streams .includePrimaryKey |
The |
string |
|
|
streams .localDatabaseName |
The |
string | 1 to 64 bytes |
|
streams .localDataFilePath |
The |
string | No limits |
|
streams .localOwnerName |
The |
string | 1 to 64 bytes |
|
streams .localTableName |
The |
string | 1 to 64 bytes |
|
streams .recordFilter |
The |
string | 1 to 65,000 bytes |
|
streams .recordFormat |
The |
string |
|
|
streams .revealAfterValueOnFilteredDelete |
The |
Boolean |
|
|
streams .revealBeforeValueOnFilteredInsert |
The |
Boolean |
|
|
streams .sourceDatabaseName |
The |
string | 1 to 64 bytes |
|
streams .sourceDataFilePath |
The |
string | No limits |
|
streams .sourceOwnerName |
The |
string | 1 to 64 bytes |
|
streams .sourceTableName |
The |
string | 1 to 64 bytes |
|
streams .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": {}
}
|
|
streams 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
|
|
streams streamingConnection .metadata |
The |
JSON | 0 to 65,500 bytes |
|
streams 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 |
|
streams streamingConnection .sourcePassword |
The "sourcePassword" property specifies the login password of a FairCom DB or RTG server. |
string | 1 to 128 bytes |
|
streams streamingConnection .sourcePort |
The "sourcePort" property specifies the ISAM TCP/IP port of a FairCom DB or RTG server. |
int16 |
1 to 65535
|
|
streams 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 |
|
streams streamingConnection .sourceUsername |
The "sourceUsername" property specifies the name of a FairCom DB or RTG server. |
string | 1 to 64 bytes |
|
streams streamingConnection .tls |
The
|
object |
|
|
streams streamingConnection tls .allowedCipherSuites |
The
|
string | No limits |
|
streams streamingConnection tls .caCertificateFilename |
The
|
string | No limits |
|
streams 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 |
|
|
streams streamingConnection tls .clientCertificateFilename |
string | No limits | |
|
streams streamingConnection tls .clientPrivateKeyFilename |
string | No limits | |
|
streams streamingConnection tls .enabled |
The "tls": {
"enabled": true,
"caCertificateFilename": "ca.crt",
"allowedCipherSuites": "",
"clientCertificateEnabled": true,
"clientCertificateFilename": "admin_client.crt",
"clientPrivateKeyFilename": "admin_client.key"
} |
Boolean |
|
|
streams .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 |
|
streams .tagChanges |
The |
string |
|
|
streams .topic |
The |
string | A topic name between 1 and 65,500 bytes |
|
streams .triggers |
The "triggers" property specifies a list of events on a table that create data change events. |
array of enum strings |
|