Content-type: text/html Man page of NSR_OP

NSR_OP

Section: File Formats (5)
Updated: Dec 11, 08
Index Return to Main Contents

NAME

nsr_op - NetWorker resource type ``NSR operation status''

SYNOPSIS

type: NSR operation status

DESCRIPTION

Some of the operations performed by a NetWorker server (e.g jukebox operations) are tracked by means of a single resource of type NSR operation status per operation. The resource is used by the calling program (e.g. nsrjb) both for tracking purposes (to know when the operation is complete, to follow error and verbose messages etc.), and for control purposes (cancellation, prompt responses, etc).

See nsr_resource(5) for information on NetWorker resources. To view the NSR operation status resources within nsradmin, run:

: nsradmin -c "type:NSR operation status"

Be careful to include the spaces between the words that make up the resource type name, as well as the surrounding quotes. See nsradmin(1m) for information on using the NetWorker administration program.

The NSR operation status resources are transient resources - that is, they exist only as long as is deemed necessary in order to track the status of the operation in question. Each resource will be created when the operation is initiated, and will be removed a certain amount of time after it has completed.

Note that because the initiating client program (e.g. nsrjb) polls nsrd to get information on the current state of its operation, there must be a grace period between when the operation completes, and when nsrd removes the Nsr operation status resource, otherwise the client program may not see the completion information. For jukebox operations, this grace period is defined on a per-jukebox basis, by means of the "operation lifespan" attribute in the "Nsr jukebox" resource. The lifespan is in seconds, and defaults to 1800 (equal to 30 minutes). For non-jukebox operations, a fixed grace period of 5 minutes applies.

All NSR operation status resources will also be deleted automatically during Networker's start-up and shut-down phases, since no operation may continue beyond a single run of Networker. If nsrmmgd (which is responsible for controlling all jukebox operations on behalf of a nsrd server) terminates unexpectedly for any reason, then nsrd will also automatically mark all jukebox related operations as aborted.

ATTRIBUTES

The following attributes are defined for resource type NSR operation status. The information in parentheses describes additional information about how the attribute values are accessed. Hidden means that these attributes can only be seen when the hidden option is turned on in nsradmin(1m). single string means that these attributes can only have a single value, whereas multiple strings means that the attribute may have multiple values. choice means that the attribute value may only be selected from a series of well defined choices.

Note that none of the attributes of the NSR operation status resource should be changed by the user or administrator - they are for use by other Networker programs only. Manual changing any of the NSR operation status resources or their attributes, may cause unexpected behavior.

operation source (single string)

Indicates the source of the operation - e.g. "nsrjb", "GUI jb op", "nsrd jb op", "jbverify", "dvdetect", etc. This is used by Networker to handle any aspects of the operation that vary according to the origin of the operation, as well as being used by the GUI to allow sorting, filtering etc., of operations based on their origin.

name (single string)

If this is a jukebox operation, then the name attribute specifies the name of the jukebox that this operation is being performed on. For non-jukebox operations, this attribute may be left blank.

operation instance (single number)

This attribute is a number which is used to uniquely identify a given operation. The instance number may be "wrapped around" such that a lower instance number does not necessarily indicate a resource that was created before another such resource that has a higher instance number. (See the "start time" attribute" for determining relative ages of NSR operation status resources).

status (choice)

Defines the current status of the operation. Possible values are:
queued: The default state for a new operation, this indicates that the operation has been sent to the appropriate daemon where it will be performed.
running: Indicates that the controlling daemon is currently working on the operation.
succeeded: The operation has completed, and was successful.
failed: The operation has been terminated without it being completely successful. Note that this status value covers the entire operation, so if you tried to label 10 volumes and 9 of the 10 were successful, the operation would still indicate failure due to the fact that it was not completely successful.

retryable: Like "failure", except that Networker believes that there is a reasonable chance that the operation would complete successfully if simply retried.

completion code (single number)

This attribute is not always used (depending on the operation type and origin), but when it is non-NULL it contains a numeric value that gives more information about the completion status of the operation that the simple "status" attribute provides.

command (single string)

This attribute indicates what the command line was that initiated the operation. It is provided mainly to help the user track which operations are in which state, including knowing which were uncompleted when Networker shut down (a list of such uncompleted operations will be printed out during shutdown).

progress (multiple string)

This attribute is not always used (depending on the operation type and origin), but when it is non-NULL it contains information about the current progress of the operation. The multiple values of this attribute may be used so that the first value indicates e.g. percentage completion of the operation, while the second value gives a description of the current task being performed for that operation.

error message (mutliple string)

A list of error messages associated with the operation. Note that the operation does not have to be in the "failed" status for there to be error messages contained in this attribute. This is because the operation may contain multiple parts which do not all need to be aborted once a single part has experienced an error. For example, if you issue a nsrjb command to label 10 tapes, and there is an error that prevents the first tape from being labeled, the error message will be logged in the "error message" attribute, but the operation will continue in the "running" state while the attempts to label the other 9 tapes proceeds. (Unless the user elects to cancel the operation due to the initial failure).

prompt (single string)

This attribute's value is normally empty. If it is non-empty, then this indicates that the operation is awaiting user-input in order to continue. The prompt will be shown by the client application that started the operation.

prompt response (single string)

The response that the user gave, to the prompt. Once a prompt response is entered, the prompt string will automatically be cleared to show that no prompt need be shown to the user anymore.

cancellation (choice)

Defaults to "none". If set by the administrator to either "full" or "immediate", this will cause the controlling daemon (e.g. nsrmmgd ) to cancel the operation. Note that some stages of certain operations may take a significant amount of time to cancel. The type of cancellation (full or immediate) determines whether the controlling daemon waits for the operation to be properly cleaned up before removing the operation from its queue and marking it as complete. Consider the example of a nsrjb operation. It is possible that nsrmmgd is waiting for a response from nsrlcpd or nsrd when the cancellation request comes in. In such cases, a "full" cancellation tells nsrmmgd to wait for any pending responses from other processes in order to correctly set the appropriate values in the jukebox resource that indicate the true state of the system. By contrast, an "immediate" cancellation tells nsrmmgd to not wait for such responses. An "immediate" cancellation may cause the jukebox resource to mismatch the actual jukebox status for a while, so should only be done in those cases where a full cancellation is not working (e.g. nsrmmgd is awaiting a response from nsrlcpd but nsrlcpd has already been killed and restarted).

If the operation was initiated via nsrjb, then the cancellation attribute will be set to "full" if you cancel the operation by pressing Control-C. If you do not wish to wait for the cancellation to be completed and acknowledged, a second Control-C to nsrjb will cause nsrjb to exit without showing the progress of the cancellation, but the cancellation type will still remain "full".

If the controlling daemon terminates unexpectedly, then nsrd will automatically mark all outstanding operations as cancelled, by setting the cancellation type to "immediate".

messages (mutliple string)

A list of informational messages associated with the operation. This attribute is used for verbose logging of the progress of the operation. The higher the level of verbosity associated with the operation (typically set in the client application's command line), the greater the number of entries in the messages attribute is likely to be for a given operation).

start time (single string, hidden)

A machine-readable time-stamp indicating when the operation was initiated and this NSR operation status resource was created.

last update (single string, hidden)

A machine-readable time-stamp indicating when the last update to this NSR operation status resource was made. This value is updated when the resource is changed to e.g. require the issuing of a prompt, a prompt response, a verbose or error message being added, the operation being cancelled, or any other change in the status of the operation being tracked.

source (single string, dynamic, hidden)

Used by Networker to determine the source of the last change to the resource. This is used to cut down on unnecessary network traffic. This attribute is only used for certain operations.

The following example shows a resource that defines a label operation on jukebox "adic", in which a nsrjb command has been issued to label the volume in Slot 2. The volume already has a label of 'XYX', (as can be see in the verbose messages attribute), and so a prompt is issued to confirm with the user whether the (destructive) re-label should proceed.

                   type: NSR operation status;
       operation source: nsrjb;
                   name: adic;
     operation instance: 3;
                 status: queued   [running]  succeeded  failed  retryable;
        completion code: ;
                command: nsrjb -L -S 2;
               progress: ;
          error message: ;
               messages: "Loaded volume ABC from Slot 2"
                 prompt: "Confirm re-label of volume 'ABC' to 'XYZ' ? [Yes/No]";
        prompt response: ;
    operation cancelled: [No]   Yes ;
             start time: 1070557031;
            last update: 1070557031;
                 source: ;