Remote tasks

A remote task is the unit of work when performing central administration of remote databases. A remote task consists of the following:

One or more trigger mechanisms
Optional conditions
An ordered collection of commands
Other properties

Tasks are created by the administrator using the MobiLink 12 plug-in for Sybase Central. At design-time they are stored locally on the administrator's computer in the project. For a list of commands that can be used to build tasks, see Commands.

Generally, one task should not depend on the completion of another task. However, it is possible to create a task that depends on another by having one task write something to the remote database and having the condition of another task query that value.

Once the administrator is ready for Agents to receive a task, the administrator deploys the task. When deployed, a task is copied into the consolidated database. There are now two copies of the task: the deployed task in the consolidated database and the design-time task in the project. Deployed tasks may not be modified. However, the design-time task used to create them may be modified and deployed again (to create a second deployed task). Deployed tasks can be canceled, initiated (SIRT), reactivated and assigned to new recipients.

Once deployed, a task may be assigned to one or more Agents for execution. When assigned to an Agent, the task is downloaded to the Agent. The Agent then executes the task at an appropriate time and optionally uploads the results back to the consolidated database where they can be reviewed by an administrator using the MobiLink 12 plug-in for Sybase Central.

Tasks have the following attributes:

Name A remote task has two names: one identifies the design-time version of the task stored in the project while the other identifies the task once it is deployed. Often the two names are the same.
A task's design-time name is assigned when the task is created and must be unique among tasks in the project. A deployed task name is assigned when the task is deployed and this name must be unique among deployed tasks in the consolidated database.
Description A description of the task can be entered and may contain any text you wish to associate with the task. The description is stored in the project and in the consolidated database (once the task is deployed), but is not sent to the Agent.
Trigger mechanisms A remote task's trigger mechanisms determine when the Agent attempts to execute the task. A task may have more than one trigger mechanism. There are three supported trigger mechanisms:
- Based on a schedule The task is triggered at specific times or at specific time intervals. This option must be explicitly set for a task.
- When received by an Agent The task is triggered when it is received by the Agent, and will run only once. This option must be explicitly set for a task.
- On demand The task may be triggered at any time by a message from the server in a process called Server-Initiated Remote Task (SIRT). All tasks that are not configured to run only once support being triggered on demand.
Conditions Before a task can be executed, all its conditions must be satisfied. If a task is triggered but all its conditions are not met, then the run attempt is considered a failure and the task must be triggered again before the conditions are reevaluated.
Remote schema name A task can optionally be associated with a remote schema name. Tasks that require access to a remote database must be associated with a remote schema name. The remote schema name is used by the Agent to determine which of the databases the Agent needs to access when executing the task. Tasks must be associated with a remote schema name if they contain any of the following commands: create database, drop database, execute SQL or synchronize. A remote task must also be associated with a remote schema name if you want to use a SQL condition to determine if the task can run.
Commands A task contains an ordered set of commands that carry out the work required for the task. The order in which the commands are specified defines the order in which the commands are executed within the task. It is important to be aware of the order of the commands because commands could be dependent on each other. See Commands.
Maximum number of retries Each command has an on failure action that can be used to cause the task or the command to be retried if the command fails. This option lets you limit the number of retries allowed during a single run attempt.
Delay between retries This option specifies the amount of time to wait after a command fails before attempting to retry the command or task. This delay may allow a transitory condition (such as a locked database table or a locked file) that caused the failure to pass before the command or task is reattempted. Retry delays are assumed to be "short" periods of time. A task condition is not re-evaluated between retries.
Maximum running time It is possible that a task when executed, does not behave as the administrator intended. An OS call could hang; an attempt to synchronize could be very slow—a SQL statement could be blocked on another connection using the database. Setting a maximum running time for a task lets you limit how long the task may run. If the maximum running time is reached, the task is terminated (the actual time at which the task is terminated depends on the ability to interrupt the operation). The status for the task is set to reflect the timeout and the task is not retried until it is triggered again. If a command in a task fails and the task or command needs to be retried, the maximum running time is reset after the delay. So, the maximum running time is considered to be per attempted task execution or retry. It does not include the aggregate time of all retries and it does not include Prompt commands.
Schema change Schema change tasks change the schema of a remote database. If the task succeeds, the remote schema name of the remote database is also updated. Schema change tasks are always high priority tasks and they report their status on completion.
High priority High priority tasks are always triggered when received by an Agent and executed as soon as any currently executing tasks are complete. They may not be executed based on a schedule and they may not have any conditions on their execution. A task marked high priority is only executed when there are no other tasks being executed to ensure that no other task interferes with the execution of a high priority task.
Status reporting Status reporting options on a task allow you to specify when and if results are reported back to the consolidated database, both when the task completes successfully and when it fails. The available options are:
- Send status only Task results are not reported. However, information about the number of task successes or failures is maintained and reported.
- Return results the next time the Agent synchronizes the agent database Task results and status are maintained and reported the next time the Agent synchronizes the agent database.
- Return results immediately when task execution completes Task results and status are reported as soon as the task completes.
Random delay interval If a given task sends results to the MobiLink server after execution or causes a remote database to synchronize with the server, and it is triggered simultaneously across a large number of remotes, then setting a random delay for the task uniformly distributes the synchronization workload for the server over a configurable period of time.
A remote task can have a random delay interval, which is an interval N, in seconds, with which each agent generates a random number of seconds in [0, N) to delay each task execution. If the task is a scheduled task, the random delay is generated before the first task execution, and used for each execution. The task is executed at the scheduled times, offset by the random delay. This ensures that the deltas of the task execution times are consistent with the schedule.

It is not recommended that the random delay interval be larger than smallest delta time of a scheduled task. If the task is an on demand task, meaning it is initiated by the server, the random delay is generated and used to delay the execution each time the task is initiated. If the task is a run on receipt task, the random delay is generated and used to delay the execution at the first and only time the task is executed.

Remote task logic

The following is an outline of the logic used to execute a remote task.

current_command = 1;
num_tries = 0;
EXECUTE_TASK:
loop {
      num_tries = num_tries + 1;
      EXECUTE_COMMANDS;
      if( task_success or task_abort ) break EXECUTE_TASK;
      if( task_retry and at maximum tries ) {
            break EXECUTE_TASK;
      } else {
            continue;
      }
}

EXECUTE_COMMANDS:
for each command starting at current_command {
      execute current_command;
      if( command failed ) {
            if( action on failure is "abort task" ) {
                  break EXECUTE_COMMANDS, returning task_abort;
            } else if( action on failure is "continue" ) {
                  // no action, continue at next command
            } else if( action on failure is "retry task" ) {
                  current_command = 1;
                  break EXECUTE_COMMANDS, returning task_retry;
            } else if( action on failure is "retry command" ) {
                  // no change to current_command
                  break EXECUTE_COMMANDS, returning task_retry;
            }
      }
      current_command = next command number;
}
return task_success;

The maximum running time is reset for a task when the task starts and when a command or the entire task is retried because a command fails.

Notice that when a command or task is retried because a command fails, the condition is not reevaluated and no new trigger event is required. It is important to consider whether properties referenced in the condition can change during the execution of the task, and whether retrying a command if the condition fails would produced undesirable results.

Creating a remote task

Tasks are defined and managed within the context of a MobiLink project. An administrator can create, alter and remove a task without requiring a connection to the consolidated database. Tasks that have not been deployed are considered to be in development and exist locally in the MobiLink project only.

Create a task (Sybase Central)

Follow the procedure below to create a new task. You create the task first, and then it can be deployed to the consolidated, and then assigned to recipients (Agents):

Ensure the MobiLink project you are working with is selected in the left pane in Folders view, then right-click Remote Tasks and click New » Remote Task.
Follow the steps in the Create Remote Task Wizard and click Finish.

Note

If you need to create a new remote schema name, which identifies a group of remote databases that have the same schema, click Create a Remote Schema Name on the Welcome page of the Create Remote Task Wizard. The Create Remote Schema Name Wizard appears and the Create Remote Task Wizard remains open. Once you have created the new remote schema name, it appears in the Remote Schema Name dropdown of the Create Remote Task Wizard.
Follow the procedure to add one or more commands to the task. See Adding a command.

Editing a remote task

Edit a remote task (Sybase Central)

Ensure the MobiLink project you are working with is selected in the Folders view in the left pane, then right-click the remote task you want to edit and click Properties.
Edit the remote task properties.
When you are finished editing the remote task properties, click Apply.

Deploying a remote task

When you are ready to add the task to the system, the task needs to be deployed. Deploying a remote task means that the task is copied into the consolidated database and the new copy is given a name. The deployed task name is often the same name that the task had during development.

When you deploy a task you can also assign it to a list of Agents. Agents can be added after a task is deployed, so it is not necessary to add them when the task is first deployed. This is useful when new Agents are added to the system after a task has already been deployed.

Deploy a remote task (Sybase Central)

A remote task must contain at least one command before it can be deployed. For information about commands, see Commands and Adding a command.

Ensure the MobiLink project you are working with is selected in the Folders view in the left pane, then right-click the remote task you want to deploy and click Deploy.
Follow the instructions in the Deploy a Remote Task Wizard.
Click Finish.

Working with deployed remote tasks
Server-initiated remote tasks (SIRT)
Commands
Variables in parameters
Status
System procedures

Discuss this page in DocCommentXchange.