ES Statuses and Update

Question from: Pearl Janifer Janifer@COMPUSERVE.COM Mon, 11 Aug 1997 05:37:36 -0400

Please explain the various Extended Service status values, particulary as they apply to the Update Extended Service.

OperationStatus and taskStatus both apply to Extended Services in general; updateStatus and recordStatus are specific to Update.

OperationStatus and taskStatus distinguish the ES operation from the ES task. The "ES operation" is the ES request followed by the ES response, the result of which is the spawning of an ES task, which may be monitored by taskStatus. Thus operationStatus is set only once, after the operation is complete, in contrast to taskStatus, a dynamic status that changes as the status of the operation changes.

However neither operationStatus nor taskStatus convey any status information specific to the ES type, and therefore it is assumed that each ES definition will include one or more additional statuses as needed.

For Update, there are updateStatus and recordStatus. These distinguish the update task at large from update action that applies to each individual record.

Following is a summary of these four statuses.

• TaskStatus
  taskStatus is a general ES parameter, not specific to Update, and it exists only in the task package (i.e. it is not an explicit parameter of the ES response). Values are:
  • 'pending',
  • 'active',
  • 'complete', and
  • 'aborted'
  It's purpose is to allow the client, by repetitively retrieving the package, to monitor the progress of its execution, from initiation of the ES operation until completion of the task. But it is not intended to provide status specific to the type of task, and in particular, it is not intended to convey whether the task was completed successfully, only that it completed. That's the reason for individual statuses like "update status".

  According to the abstract ES model, when the server receives the ES request, if it passes preliminary inspection and the task is queued, the taskStatus is pending; if it does not pass preliminary inspection then at the servers discretion there may not even be a task package created (see Operation status) but if there is, its status is set to 'aborted'. Once the task starts (which may or may not be before the server sends back the ES response) the status is set to 'active'. If it subsequently aborts, it is set to 'aborted' and if it subsequently completes, it is set to 'complete.

• Operation status
  An important property about taskStatus is that it exists only in the task package, and the task package might not be included in the ES response. So operation status is included in the ES response. Its values are:
  • 'done',
  • 'accepted', and
  • 'failure'.
  'done' means the task package is included in the ES response (in that case this status is redundant); 'accepted' corresponds to taskStatus of 'pending' or 'active', and 'failure' corresponds to the case where the task package was not even set up because the task did not pass preliminary inspection.

• Update status
  UpdateStatus is specific to the Update ES, and is not set until the task is complete, or rejected. Its values are:
  • 'success',
  • 'partial', and
  • 'failure'.

• recordStatus
  UpdateStatus (above) is global to the task; so in addition there is a "record status", for each record, with values:
  • 'success',
  • 'failure',
  • 'queued', and
  • 'inProcess'.
  According to the abstract model for Update, this status is set for each record as soon as the task package is set up, initially to 'queued' and subsequently to either 'success' or 'failure' when update action is complete for the record. In the interim, at target discretion, the status may change from 'queued' to 'inProcess' (but the target may skip this status). So at any time after the task begins, any given record may have status of 'queued', 'inProcess', 'success' or 'failure' (and once the status becomes 'success' or 'failure', it will not subsequently change). One usage of this status is to enable a client to monitor the progress of the task, on a record-by-record basis.

  Note that updateStatus is not set until recordStatus is set for each individual record, and will be 'success' if recordStatus is 'success' for every record, and will be 'partial' if recordStatus is 'success' for some but not all records.

  So 'partial' (for updateStatus), which has been the source of some confusion, doesn't mean "partially done" it means "task done, but only some of the records were successfully updated".

  Note that when taskStatus is 'pending' all the record statuses are 'queued'. When taskStatus is 'active' some of the record statuses may be other than 'queued'. When taskStatus is 'complete' or 'aborted' none of the record statuses should be 'queued'.