7.15 Control Repstance Processes

There are three commands that are used to control the Capture and Apply Processes. They are :

• run
• stop
• status

Each of these commands can be used to control a single Process, a group of Processes or all Processes. The default is to run “All” the Processes that are available to be run, stopped or get the status of, if no additional “Parameters” are specified.

The syntax used for these commands is:

Here are some examples of using run command.

This command will “run” everything (all existing Capture and Apply Processes):

This command will “run” all Capture Processes:

This command will “run” a single specified Capture Process:

The command format is identical in use for both the “stop” and “status” commands.

7.15.1 Run any Capture or Apply Processes

This command is used to “Run” either a single Capture or Apply Process or a group of either Capture, or Apply Processes or all configured Processes. The default is to run all Processes that are available to be run, if no additional “Parameters” are specified.

As part of the “run” command, Repstance carries out background checks to ensure that Source and/or Target Databases are properly configured with the necessary functionality to enable the Capture and/or Apply Processes to run. In the event that either of the Databases are not properly configured, it will display an error message listing the inconsistencies.

At the “first time” run of the Capture Process for MS SQL database it creates CDC tables needed for the replication and start extracting the changes from the first available LSN generated in the CDC tables.

For the Oracle database at the “first time” run the “current database SCN” is used as the start point of the replication.

Note – If there are any active transactions were running at the “current database SCN”, and these transactions are committed after this SCN, the ALL changes generated by these transactions are included into the replication, so the tables will be in consistent state and no data is missed.

If the previously defined Objects (see chapter 7.4.4 Capture Objects Specification) are changed or the Transformation Rules (see chapter 7.4.7 Transformation Rules and Triggering Order) are altered, at this point all the DDL and DML changes will be re-implemented using the new criteria.

If any Objects are no longer configured for Capture Process the “run” command will “Turn Off” CDC on these Objects and they will no longer be written to the Trail Files – the reverse is true i.e. if new Objects are specified then the “run” command will enable CDC for them and they will now be written to the Trial Files.

If this is the “First time” an Apply Process has been run, it isonlyat this point that data from the specified Capture Process will be written to the Target Database using the first available LSN in the Trail File generated by this Capture Process.

The Apply Process can be configured to use a specific LSN from a Capture Process as a start point, i.e it can be configured to use any available LSN from a Trail File, but this is done by using the “reset” command (see chapter 7.13 Reset Apply Process).

If the specified Capture Process either is not configured or has never been run, the Apply Process will fail.

REST API:

• Endpoint: https://repstance_url/control/process
• Method: POST
• Header:
  • Content-Type: application/json
  • X-Token: token
• Body:
  {
    "command": "run",
    "parameters": [
      ["process","apply|capture"],
      ["id","processID"]
    ]
  }

Server response:

• HTTP Status – Status of the command, possible codes are:
  • 200 – if no error occurs
  • 422 – if error occurs
• Body:
  {
    "Status":"{Completed|Error}",
    "Message":"The command execution details"
  }

CLI Syntax:

The input parameters are:

• process – Constant value apply for Apply Processes or constant value capture for Capture Processes
• id – Identifier of the Process

The output parameters are:

• Status – Status of the command, possible values are:
  • Error – the command has failed to run
  • Completed – the command has completed successfully
• Message – Details of command execution

7.15.2 Stop any Capture or Apply Processes

This command is used to stop either a single Capture or an Apply Process or a group of either Capture, or Apply Processes or all configured Processes. The default is to stop everything that is running, if no additional parameters are specified.

REST API:

• Endpoint: https://repstance_url/control/process
• Method: POST
• Header:
  • Content-Type: application/json
  • X-Token: token
• Body:
  {
    "command": "stop",
    "parameters": [
      ["process","apply|capture"],
      ["id","processID"]
    ]
  }

Server response:

• HTTP Status – Status of the command, possible codes are:
  • 200 – if no error occurs
  • 422 – if error occurs
• Body:
  {
    "Status":"{Completed|Error}",
    "Message":"The command execution details",
  }

CLI Syntax:

The input parameters are:

• process – Constant value apply for Apply Processes or constant value capture for Capture Processes
• id – Identifier of the Process

The output parameters are:

• Status – Status of the command, possible values are:
  • Error – the command has failed to run
  • Completed – the command has completed successfully
• Message – The details of command execution

7.15.3 Status of any Capture or Apply Processes

This command is used to show the status of either a single Capture or an Apply Process or a group of either Capture, or Apply Processes or all configured Processes. The default is to show the status of every Process that is running, if no additional parameters are specified.

REST API:

• Endpoint: https://repstance_url/control/process
• Method: POST
• Header:
  • Content-Type: application/json
  • X-Token: token
• Body:
  {
    "command": "status",
    "parameters": [
      ["process","apply|capture"],
      ["id","processID"]
    ]
  }

Server response:

• HTTP Status – Status of the command, possible codes are:
  • 200 – if no error occurs
  • 422 – if error occurs
• Body:
  [
    { 
      "Process":"capture|apply",
      "ID":processID,
      "Parameters":{
  "Name|CaptureName":"captureName",
  "Server":"databaseHost",
  "Port":"databasePort",
  "DBname":"databaseName"},
  "Command":"INITIALISED|RUN|STOP|RESET",
  "CommandStatus":"Completed|In Process|Failed",
  "StatusDetails":"Waiting for the Next Command|
  Processing the Transactions|
  Waiting for Transactions",
  "CommandStartTime":"Time_in_UTC",
  "LastActivityTime":"Time_in_UTC",
  "StartLSN":"LSN",
  "StartLSNTime":"Time_in_UTC",
  "CheckpointLSN":"LSN",
  "CheckpointLSNTime":"Time_in_UTC",
  "LastDBLSN":"LSN",
  "LastDBLSNTime":"Time_in_UTC",
  "WAITING":"time_in_nanoseconds",
  "PROCESSING":"time_in_nanoseconds",
  "LOADING":"time_in_nanoseconds",
  "Message":"The command execution details",
  "CNTD":"Number_of_deletes",
  "CNTI":"Number_of_inserts",
  "CNTU":"Number_of_updates",
  "CNTDDL":"Number_of_ddls",
  "CNTLOBJ":"Number_of_loaded_objects",
  "CNTLOBJREC":"Number_of_loaded_records",
  "CNTTX":"Number_of_transactions"
    },
    {
      Next_Process_description
    }, ...
  ]

CLI Syntax:

The input parameters are:

• process – The apply value for Apply Processes or the capture value for Capture Processes
• id – The identifier of the Process

The output parameters are:

• Process – Name of the configured Process, possible values are:
  • capture
  • apply
• ID – The identifier of the Process
• Parameters – The list of the currently configured parameters:
  • Name – name of a Capture Process (only for Capture Processes)
  • CaptureName – name of Capture Process being used by the Apply Process (only for Apply Processes)
  • Server – Host name or IP address of the database server
  • Port – Database port
  • DBname – Database name
• Command – The last executed command on the listed Process, possible values are:
  • INITIALISED – means that the Process exists but currently has no command executed
  • RUN – means that the Process is running
  • STOP – means that the Process is stopping
  • RESET – means that the Apply Process is resetting to the specified LSN
• CommandStatus – Status of the command, possible values are:
  • Waiting for the Next Command
  • Processing the Transactions
  • Waiting for Transactions
  • Loading the Data
• CommandStartTime – Time in UTC format when the command was initialized (the parameter is available only in JSON response)
• LastActivityTime – Time in UTC format when the Process activity changed (the parameter is available only in JSON response)
• StartLSN – The first LSN (in hexadecimal format) when a transaction was processed (in repcli the parameter is displayed in the “Total since” section)
• StartLSNTime – Time of the transaction in UTC format the Process has started with (in repcli the parameter is displayed in the “Total since” section)
• CheckpointLSN – The LSN (in hexadecimal format) of the last transaction that has been successfully processed (in repcli the parameter is displayed in the “Last Captured/Applied DB Change” section)
• CheckpointLSNTime – Time in UTC format of the last transaction that has been successfully processed (in repcli the parameter is displayed in the “Last Captured/Applied DB Change” section)
• LastDBLSN – The last known transaction LSN (in hexadecimal format) in the Source Database. The parameter is provided by Capture Process and valid only in the case the Capture Process is running (in repcli the parameter is displayed in the “Last Sourced DB Change” section)
• LastDBLSNTime – Time in UTC format of the last known transaction LSN in the Source Database. The parameter is provided by Capture Process and valid only in the case the Capture Process is running (in repcli the parameter is displayed in the “Last Sourced DB Change” section)
• WAITING – Number of nanoseconds that the Process has been waiting for data to process (in repcli the parameter is displayed in the “Waiting for Transactions” section in HH:MM:SS.FFF format)
• PROCESSING – Number of nanoseconds that the Process has been processing the data (in repcli the parameter is displayed in the “Processing the Transactions” section in HH:MM:SS.FFF format)
• LOADING – Number of nanoseconds that the Process has been loading the data (in repcli the parameter is displayed in the “Loading the Data” section in HH:MM:SS.FFF format)
• Message – Details of the command execution
• CNTD – Number of Delete Operations currently performed by the Process (in repcli the parameter is displayed in the “Transactions” section on “Delete” position)
• CNTI – Number of Insert Operations currently performed by the Process (in repcli the parameter is displayed in the “Transactions” section on “Insert” position)
• CNTU – Number of Update Operations currently performed by the Process (in repcli the parameter is displayed in the “Transactions” section on “Update” position)
• CNTDDL – Number of DDL statements currently processed by the Process (in repcli the parameter is displayed in the “Transactions” section on “DDL” position)
• CNTLOBJ – Number of Objects currently processed by Initial Loading (in repcli the parameter is displayed in the “Loaded Objects” section)
• CNTLOBJREC – Number of records currently processed by Initial Loading (in repcli the parameter is displayed in the “Loaded Objects” section on “Rows” position)
• CNTTX – Number of transactions currently processed by the Process (in repcli the parameter is displayed in the “Transactions” section)

The AverageSpeed parameter is average number of records processed per second (calculated value).

The Lag parameter is the latency (delay) between the last record processed and the timestamp of the last transaction in Source Database - calculated value. The Lag is valid only in the case that the corresponding Capture Process is running. In repcli it is displayed in HH:MM:SS.FFF format.

The following example shows statuses of all existing Processes:

The following example shows status of Capture Processes: