The Backup application programming interface (API) allows user-
written applications to perform BACKUP operations.
1 – BACKUP$START
BACKUP$START is the entry point through which applications invoke
the OpenVMS Backup utility.
Format
BACKUP$START argument-buffer
1.1 – Returns
OpenVMS usage:COND_VALUE
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Condition values that this routine can
return are listed under Condition Values Returned.
1.2 – Argument
argument-buffer
OpenVMS usage:user-defined array
type: longword (unsigned)
access: read only
mechanism: by reference
Arguments that specify the BACKUP operation to be performed.
The argument-buffer argument is the address of a variable-length
array of one or more Backup API option structures that define
the attributes of the requested BACKUP operation. The variable-
length array is terminated by an option structure of 16 bytes
that contains all zeros.
NOTE
The length of the terminating option structure is 2
longwords (16 bytes). The first longword identifies the
option structure and has a value of 0. It is recommended
that the second longword contain a value of 0.
For more information about the Backup API option structures,
refer to the OpenVMS Utility Routines Manual.
1.3 – Description
Application programs call the Backup API to invoke the OpenVMS
Backup utility via a call to the BACKUP$START routine. There
is only one parameter, the address of an argument buffer that
contains a number of option structures that together define the
operation requested of the Backup utility. Most of these option
structures are equivalent, singly or in combination, to the
qualifiers available when invoking the BACKUP utility with the
DCL command BACKUP; the call to the API is analogous to a user
entering an interactive command to the Backup utility.
The call to BACKUP$START is synchronous; that is, it does not
return until the operation is complete or is terminated by a
fatal error. In the case of a fatal error, the call is aborted.
BACKUP Event Callbacks
An application can request that the BACKUP API notify the
application whenever specific events occur. The application can
specify different callback routines to handle different types of
BACKUP events, or one routine to handle all events. To do so, the
application registers the callback routine by including option
structure BCK_OPTYP_K_EVENT_CALLBACK in the call to BACKUP$START.
This option structure specifies an event type (or all events)
and the address of a routine to be called when the event occurs.
The application must include one such option structure for each
requested event type. To specify all events, use BCK_EVENT_K_ALL.
Event Callback Buffer Formats lists the specific event types and
identifiers.
A callback routine:
o Is called with one argument; a pointer to a bckEvent data
structure that contains information to enable the application
to process the event
o Returns an unsigned integer status value (of any valid OpenVMS
message) in R0 to enable the API to perform proper logging of
the event
NOTE
The API does not currently process the return status of
the callback routine. However, VSI strongly recommends
that the callback routine provide the appropriate status
in R0 when returning control to the API.
The bckEvent structure contains information about the type
of event, and also contains a descriptor of a data structure
that contains information to be used to process the event. The
bckEvent structure may point to a bckControl structure that
specifies control aspects of an event that may require user or
operator action.
bckEvent Format describes the format of the bckEvent data
structure. bckControl Format describes the format of the
bckControl data structure.
Table 1-1 bckEvent Format
Data Type Element Name Description
struct bckevt_r_event_ Pointer to event data
dsc$descriptor buffer
unsigned int bckevt_l_event_ Event type
type
unsigned int bckevt_l_event_ Event subtype (if any)
subtype
unsigned int bckevt_q_event_ Reserved for use by VSI
ctx [2]
unsigned int bckevt_l_event_ Reserved for use by VSI
handle
Event Callback Buffer Formats describes the values returned in
the bckEvent data structure.
Table 1-2 Event Callback Buffer Formats
Type/Subtype Format Value Returned
BCK_EVENT_K_CONTROL bckControl See Control Event
Subtypes.
BCK_EVENT_K_ERROR_MSG
(no subtype) bckMsgVect Message vector (use
$PUTMSG to output
message to user).
BCK_EVENT_K_JOURNAL_OPEN
(no subtype) dsc$descriptor String descriptor (name
of file to create).
BCK_EVENT_K_JOURNAL_CLOSE
(no subtype) dsc$descriptor String descriptor (name
of file to close).
BCK_EVENT_K_JOURNAL_WRITE
(no subtype) 512-byte File descriptor
block of journal buffer
(condensed journal
records, refer to
the BJLDEF structure
definition in the
BAPIDEF files).
Table 1-2 (Cont.) Event Callback Buffer Formats
Type/Subtype Format Value Returned
BCK_EVENT_K_LIST_CLOSE
(no subtype) Array of 2 LIST_TOTFILE: Total
longwords files listed.
LIST_TOTSIZE: Total
blocks listed. Note:
The application should
close the list file.
BCK_EVENT_K_LIST_OPEN
TRUE dsc$descriptor File specification of
list file to open (TRUE
listing).
FALSE dsc$descriptor (FALSE = 0).
BCK_EVENT_K_LIST_WRITE
BRH$K_SUMMARY BSRBLK List BACKUP save set
- save set summary
record.
BRH$K_VOLUME BSRBLK List BACKUP save set -
volume summary record.
BRH$K_PHYSVOL PVABLK List BACKUP save set -
physical volume record.
BRH$K_FILE FARBLK List BACKUP save set -
file record.
BCK_EVENT_K_LISTJOUR_WRITE Subtype is a condition
value that indicates
the type of action
that occurred for the
specified file/item.
Obtain message text
with the $GETMSG system
service.
TRUE bckLisJourblk Journal file listing
information (TRUE = 1,
indicates a change of
volume or save set).
FALSE dsc$descriptor Journal file listing of
file/item specification
string (descriptor)
(FALSE = 0).
BCK_EVENT_K_LOG
BACKUP$_AECREATED dsc$descriptor String descriptor (file
logging).
BACKUP$_COMPARED dsc$descriptor String descriptor (file
logging).
BACKUP$_COPIED dsc$descriptor String descriptor (file
logging).
BACKUP$_CREATED dsc$descriptor String descriptor (file
logging).
BACKUP$_CREDIR dsc$descriptor String descriptor (file
logging).
BACKUP$_HEADCOPIED dsc$descriptor String descriptor (file
logging).
BACKUP$_INCDELETE dsc$descriptor String descriptor (file
logging).
BACKUP$_NEWSAVSET dsc$descriptor String descriptor (file
logging).
BCK_EVENT_K_OP_PHASE
BACKUP$_STARTVERIFY Condition Start of verify
Value operation (obtain
message text with
$GETMSG).
BACKUP$_STARTDELETE Condition Start of delete
Value operation (obtain
message text with
$GETMSG).
BACKUP$_STARTRECORD Condition Start of record
Value operation (obtain
message text with
$GETMSG).
BCK_EVENT_K_SAVESET_CLOSE
(no subtype) RMS FOB A BACKUP save set must
be closed.
BCK_EVENT_K_SAVESET_OPEN
(no subtype) RMS FOB A BACKUP save set must
be opened or created.
BCK_EVENT_K_SAVESET_READ
(no subtype) BACKUP A BACKUP save set
Buffer block/buffer has been
Control read from the input
Block save set.
(BCBBLK)
BCK_EVENT_K_SAVESET_WRITE
(no subtype) BACKUP A BACKUP save set
Buffer block/buffer is ready
Control to be written to the
Block output save set.
(BCBBLK)
BCK_EVENT_K_STATISTICS
(no subtype) bckMsgVect Statistics message;
one of the following
message condition
values (use $PUTMSG
to output message to
user):
BACKUP$_STAT_
PHYSICAL
BACKUP$_STAT_SAVCOP_
ACT
BACKUP$_STAT_
INACTIVE
BACKUP$_STAT_COMPARE
BACKUP$_STAT_RESTORE
BCK_EVENT_K_USER_MSG
(no subtype) bckMsgVect Message vector (use
$PUTMSG to output
message to user).
Control Event Subtypes describes the control event subtypes
of the BCK_EVENT_K_CONTROL event callback. bckControl Format
describes the format of the bckControl data structure.
Table 1-3 Control Event Subtypes
Format
Subtype Field Description
Confirmation is required for
BCKEVTST_K_CONFIRM_EVENT compare or copy operation.
bckCntrl_l_event BCKCNTRL_K_CONFIRM_EVENT
bckCntrl_l_function Backup operation type (integer
value)
bckCntrl_a_ Confirmation message (bckMsgVect,
outmsgvect BACKUP$_CNTRL_CONFCOMP or BACKUP$_
CNTRL_CONFCOPY)
bckCntrl_v_response_ TRUE (response is required)
required
bckCntrl_r_response_ dsc$descriptor ("Yes/No" string
buffer descriptor)
Operator or user assistance
is required to determine
BCKEVTST_K_ASSIST_EVENT continuation/actions.
bckCntrl_l_event BCKCNTRL_K_USER_ASSIST_EVENT or
BCKCNTRL_K_OPER_ASSIST_EVENT
bckCntrl_l_function Backup operation type (integer
value)
bckCntrl_a_ bckMsgVect (assist and other
outmsgvect messages)
bckCntrl_v_response_ TRUE or FALSE (TRUE = 1, if
required response is required)
bckCntrl_r_response_ dsc$descriptor (response string
buffer descriptor)
BACKUP operation restart is
BCKCNTRL_K_RESTART_EVENT initiated.
bckCntrl_l_event BCKCNTRL_K_RESTART_EVENT
bckCntrl_l_function Backup operation type (integer
value)
bckCntrl_a_ bckMsgVect (operation restart
outmsgvect message vector)
bckCntrl_v_response_ FALSE (= 0, no response is
required required)
bckCntrl_r_response_ dsc$descriptor ("Yes/No" string
buffer descriptor)
Control events are described by the Control event subtype, via
the bckevt_l_event_subtype field in the bckEvent structure.
bckControl Format describes the format of the bckControl data
structure.
Table 1-4 bckControl Format
Data Type Element Name Description
unsigned int bckCntrl_l_event Control event type.
unsigned int bckCntrl_l_ Backup operation type.
function
bckMsgVect *bckCntrl_a_ Output messages and
outmsgvect parameters.
union {
unsigned int bckCntrl_l_ Flags.
ctlflags
struct {
unsigned bckCntrl_v_ Response required = 1.
response_required
: 1
unsigned bckCntrl_v_fill_5 Filler.
: 7
}
}
struct bckCntrl_r_ Descriptor for buffer to
dsc$descriptor response_buffer which response text is
to be written.
unsigned int bckCntrl_l_ Reserved for use by VSI.
response_status
unsigned int bckCntrl_l_ Reserved for use by VSI.
control_options
Error Messages
Where possible, the Backup API emulates the behavior of the
interactive BACKUP utility if you pass a call that contains
conflicting qualifiers by:
1. Making a best guess as to your intentions
2. Ignoring the least likely of the conflicting qualifiers
3. Issuing a message that warns of the conflicting qualifiers
4. Processing the BACKUP request
See the VSI OpenVMS System Management Utilities Reference Manual:
A-L for a table of valid combinations of BACKUP qualifiers.
1.4 – Condition Values Returned
SS$_NORMAL Normal successful completion.
BACKUP$_BADOPTDSC Invalid callable interface option descriptor.
BACKUP$_BADOPTTYP Invalid callable interface option type.
BACKUP$_BADOPTVAL Invalid callable interface option value.
BACKUP$_ Invalid callable interface option value.
BADOPTVALQ
BACKUP$_DUPOPT Previously specified callable interface option
type invalid.
BACKUP$_NOAPIARGS Callable interface required parameter not
specified or invalid.
Any condition value returned by the OpenVMS Backup utility.