nsr_op(5)
nsr_op(5)
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 oper-
ation 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(8)
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 "opera-
tion 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 informa-
tion 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 speci-
fies the name of the jukebox that this operation is being per-
formed 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 com-
pletely 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 fail-
ure 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 initi-
ated 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 uncom-
pleted 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 informa-
tion 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 per-
formed 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 "run-
ning" state while the attempts to label the other 9 tapes pro-
ceeds. (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 any-
more.
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 can-
cel. 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" cancella-
tion tells nsrmmgd to not wait for such responses. An "immedi-
ate" 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. nsr-
mmgd 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 cancel-
lation 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.
EXAMPLE
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 pro-
ceed.
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: ;
SEE ALSO
nsr(5), nsr_resource(5), nsr_jukebox, nsrjb(8), jbedit(1m)
NetWorker 7.6.2 Jul 14, 11 nsr_op(5)