Retrieving the Data Gate on Cloud status

The HTTP API described here retrieves the status of the Data Gate on Cloud service. The status displayed on the Data Gate on Cloud dashboard depends on the response that is issued by this API.

The result of a status retrieval is exposed in several key/value pairs. In the following example, the status retrieval reports a healthy Data Gate on Cloud, which is ready for load jobs and synchronization:

"resStatus":"SUCCESS"
"maskReplicationEngineStatus":"ACTIVE"
"maskCloneServerStatus":"ACTIVE"

Endpoint URL

The URL follows this pattern:
https://{endpoint_hostname}/clone_system/clone_engine/status?force_refresh=true

where:

{endpoint_hostname}
Is the hostname of the Data Gate on Cloud that was manually created in the on-premises VPC to connect by a private link to the Data Gate on Cloud instance endpoint service.
Draft comment: kuester@de.ibm.com
(<Add ref to documentation about manual steps for clarity>). --> This is from the Box note. I don't know exactly what's meant by this. Please clarify.
force_refresh=
This is a required part of the query string. Setting force_refresh=true retrieves the status, including the most recent information.

Response

A successful response returns a JSON object similar to the following:

{
  "resStatus": "SUCCESS",
  "result": {
      "cloneEngineName": "TESTDEMO",
      "connectionName": "TESTDEMO",
      "locationName": "ABCD",
      "resStatus": "ACTIVE",
      "maskReplicationEngineStatus": "ACTIVE",
      "maskCloneServerStatus": "ACTIVE",
      "cloneStatus": "Online",
      "iuStatus": "ENABLED",
      "replicationStatus": "STARTED",
      "resStatusMessage": "Success",
      "hostName": "11.22.33.44",
      "portNumber": "1234",
      "tableCloneStatus": {
          "initialLoadPending": 1,
          "loading": 2,
          "loadedOnly": 3,
          "synchronizationActive": 4,
          "error": 0
      }
  }
}

The response to a partly unsuccessful request looks like this:

{
  "resStatus": "SUCCESS",
  "result": {
      "cloneEngineName": "TESTDEMO",
      "connectionName": "TESTDEMO",
      "locationName": "ABCD",
      "resStatus": "UNAVAILABLE",
      "maskReplicationEngineStatus": "UNAVAILABLE",
      "maskCloneServerStatus": "UNAVAILABLE",
      "cloneStatus": "Unavailable",
      "iuStatus": "UNAVAILABLE",
      "replicationStatus": "UNAVAILABLE",
      "resStatusMessage": "Server does not exist or failed to get status.",
      "hostName": "11.22.33.44",
      "portNumber": "1234",
      "tableCloneStatus": {
          "initialLoadPending": 0,
          "loading": 0,
          "loadedOnly": 0,
          "synchronizationActive": 0,
          "error": 0
      }
  }
}

where:

"resStatus":
Indicates whether the HTTP request was successful or not. Possible values are "SUCCESS" or "FAIL".
"result":
The nested result object, which contains the following key/value pairs:
"cloneEngineName":
The pairing name.
"connectionName":
Again the Data Gate on Cloud pairing name:
"locactionName":
The location name of the Db2® for z/OS® source database as found in the SYSIBM.LOCATIONS system table.
"resStatus":
An internal status of the Data Gate on Cloud, as shown on the Data Gate on Cloud web UI.
"maskReplicationEngineStatus":
Indicates the status of the synchronization service. Possible values are:
  • "ACTIVE"
  • "INACTIVE"
  • "DISABLED"
  • "ERROR"
  • "UNAVAILABLE"

The data in the source tables is synchronized with the target table if the synchronization service is in the ACTIVE state.

"maskCloneServerStatus":
Indicates the status of the Data Gate on Cloud server (service). Possible values are:
  • "ACTIVE"
  • "INACTIVE"
  • "UNAVAILABLE"
"cloneStatus":
An internal status of the Data Gate on Cloud server service, which is used by the Data Gate on Cloud web UI.
"iuStatus":
An internal status of the Data Gate on Cloud server service, which is used by the Data Gate on Cloud web UI.
"replicationStatus":
An internal status of the replication service. It is used by the Data Gate on Cloud web UI.
"resStatusMessage":
The error message that was issued for the API call.
"hostName":
The host name of the Db2 for z/OS source database.
"portNumber":
The secure DDF port of the source database.
"tableCloneStatus":
Another nested object that contains the following values:
"initialLoadPending":
Number of the target database tables in Load pending state, as shown on the dashboard of the Data Gate on Cloud web UI.
"loading":
Number of the target database tables in Loading state, as shown on the dashboard of the Data Gate on Cloud web UI.
"loadedOnly":
Number of the target database tables that are fully loaded, as shown on the dashboard of the Data Gate on Cloud web UI.
"synchronizationActive":
Number of the target database tables in Active state, that is, the number of tables successfully enabled for synchronization. The number is shown on the dashboard of the Data Gate on Cloud web UI.
"error":
Number of target database tables in Error state, as shown on the dashboard of the Data Gate on Cloud web UI.
"synchronizationStatistics":
Introduces the block of key/value pairs containing synchronization metrics. The values reflect the last status that was saved by the system.
"monitorTime":
A timestamp that indicates when the metrics were retrieved.
"latencyInSeconds":
The synchronization latency in seconds.
"throughputPerSecond":
The synchronization throughput per second.
"sourceInsertedRows":
The number of synchronized table rows that were inserted into the source database.
"sourceUpdatedRows":
The number of synchronized table rows that were updated in the source database.
"sourceDeletedRows":
The number of synchronized table rows that were deleted from the source database.
"compensatedRows":
The number of synchronized table rows (INSERTs, UPDATEs, DELETEs) in the source database that were ignored because the operations were not committed, but rolled back.
"utilityLogs":
The number of log records that were generated by Db2 for z/OS utilities.
"targetInsertedRows":
The number of synchronized table rows that were inserted into the target database.
"targetDeletedRows":
The number of synchronized table rows that were deleted from the target database.
"netEffectOperations":
The number of unnecessary operations that the database engine has skipped to optimize the performance.

The response to a failed request looks like this:

{
  "resStatus": "FAIL",
  "error": "Source not defined. ",
  "code": "dgoc_00005"
}

where:

"resStatus":
Shows the value "FAIL".
"error":
The error message that was issued for the failed request.
"code":
An error code.