  | 
		
HP OpenVMS Utility Routines Manual
 
 
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. Table 3-4 lists the
specific event types and identifiers.
 
A callback routine:
 
  -  Is called with one argument; a pointer to a bckEvent data
  structure that contains information to enable the application to
  process the event
  
 -  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, HP 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.
 
Table 3-3 describes the format of the bckEvent data structure.
Table 3-6 describes the format of the bckControl data structure.  
 
  Table 3-3 bckEvent Format
  
    | Data Type  | 
    Element Name  | 
    Description  | 
   
  
    | 
      struct dsc$descriptor
     | 
    
      bckevt_r_event_buffer
     | 
    
      Pointer to event data
     | 
   
  
    | 
      unsigned int
     | 
    
      bckevt_l_event_type
     | 
    
      Event type
     | 
   
  
    | 
      unsigned int
     | 
    
      bckevt_l_event_subtype
     | 
    
      Event subtype (if any)
     | 
   
  
    | 
      unsigned int
     | 
    
      bckevt_q_event_ctx [2]
     | 
    
      Reserved for use by HP
     | 
   
  
    | 
      unsigned int
     | 
    
      bckevt_l_event_handle
     | 
    
      Reserved for use by HP
     | 
   
 
Table 3-4 describes the values returned in the bckEvent data
structure.  
 
  Table 3-4 Event Callback Buffer Formats
  
    | Type/Subtype  | 
    Format  | 
    Value Returned  | 
   
  
    | 
      BCK_EVENT_K_CONTROL
     | 
    
      bckControl
     | 
    
       See Table 3-5.
     | 
   
  
    | 
      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 block
     | 
    
       File descriptor of journal buffer (condensed journal records, refer to
       the BJLDEF structure definition in the BAPIDEF files).
     | 
   
  
    | Type/Subtype  | 
    Format  | 
    Value Returned  | 
   
  
    | 
      BCK_EVENT_K_LIST_CLOSE
     | 
    
       
     | 
    
       
     | 
   
  
    | 
       
     | 
    
      (no subtype)
     | 
    
      Array of 2 longwords
     | 
    
      LIST_TOTFILE: Total 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 = 1, indicates /FULL
      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 Value
     | 
    
      Start of verify operation (obtain message text with $GETMSG).
     | 
   
  
    | 
       
     | 
    
      BACKUP$_STARTDELETE
     | 
    
       Condition Value
     | 
    
       Start of delete operation (obtain message text with $GETMSG).
     | 
   
  
    | 
       
     | 
    
      BACKUP$_STARTRECORD
     | 
    
       Condition Value
     | 
    
       Start of record 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 Buffer Control Block (BCBBLK)
     | 
    
      A BACKUP save set block/buffer has been read from the input save set.
     | 
   
  
    | 
      BCK_EVENT_K_SAVESET_WRITE
     | 
    
       
     | 
   
  
    | 
       
     | 
    
      (no subtype)
     | 
    
      BACKUP Buffer Control Block (BCBBLK)
     | 
    
      A BACKUP save set block/buffer is ready to be written to the output
      save set.
     | 
   
  
    | 
      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).
     | 
   
 
Table 3-5 describes the control event subtypes of the
BCK_EVENT_K_CONTROL event callback. Table 3-6 describes the format
of the bckControl data structure.  
 
  Table 3-5 Control Event Subtypes
  
    |   | 
    Format  | 
   
  
    | Subtype  | 
    Field  | 
      | 
    Description  | 
   
  
    | BCKEVTST_K_CONFIRM_EVENT  | 
    Confirmation is required for compare or copy operation.  | 
   
  
    | 
       
     | 
    
      bckCntrl_l_event
     | 
    
      BCKCNTRL_K_CONFIRM_EVENT
     | 
   
  
    | 
       
     | 
    
      bckCntrl_l_function
     | 
    
      Backup operation type (integer value)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_a_outmsgvect
     | 
    
      Confirmation message (bckMsgVect, BACKUP$_CNTRL_CONFCOMP or
      BACKUP$_CNTRL_CONFCOPY)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_v_response_required
     | 
    
      TRUE (response is required)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_r_response_buffer
     | 
    
      dsc$descriptor ("Yes/No" string descriptor)
     | 
   
  
    | BCKEVTST_K_ASSIST_EVENT  | 
    Operator or user assistance is required to determine 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_outmsgvect
     | 
    
      bckMsgVect (assist and other messages)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_v_response_required
     | 
    
      TRUE or FALSE (TRUE = 1, if response is required)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_r_response_buffer
     | 
    
      dsc$descriptor (response string descriptor)
     | 
   
  
    | BCKCNTRL_K_RESTART_EVENT  | 
    BACKUP operation restart is initiated.  | 
   
  
    | 
       
     | 
    
      bckCntrl_l_event
     | 
    
      BCKCNTRL_K_RESTART_EVENT
     | 
   
  
    | 
       
     | 
    
      bckCntrl_l_function
     | 
    
      Backup operation type (integer value)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_a_outmsgvect
     | 
    
      bckMsgVect (operation restart message vector)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_v_response_required
     | 
    
      FALSE (= 0, no response is required)
     | 
   
  
    | 
       
     | 
    
      bckCntrl_r_response_buffer
     | 
    
      dsc$descriptor ("Yes/No" string descriptor)
     | 
   
 
Control events are described by the Control event subtype, via the
bckevt_l_event_subtype field in the bckEvent structure. Table 3-6
describes the format of the bckControl data structure.  
 
  Table 3-6 bckControl Format
  
    | Data Type  | 
    Element Name  | 
    Description  | 
   
  
    | 
       unsigned int
     | 
    
      bckCntrl_l_event
     | 
    
      Control event type.
     | 
   
  
    | 
       unsigned int
     | 
    
      bckCntrl_l_function
     | 
    
      Backup operation type.
     | 
   
  
    | 
       bckMsgVect
     | 
    
      *bckCntrl_a_outmsgvect
     | 
    
      Output messages and parameters.
     | 
   
  
    | 
       union {
     | 
    
       
     | 
    
       
     | 
   
  
    | 
       
     | 
    
       unsigned int
     | 
    
      bckCntrl_l_ctlflags
     | 
    
      Flags.
     | 
   
  
    | 
       
     | 
    
       struct {
     | 
    
       
     | 
    
       
     | 
   
  
    | 
       
     | 
    
       
     | 
    
       unsigned
     | 
    
      bckCntrl_v_response_required : 1
     | 
    
      Response required = 1.
     | 
   
  
    | 
       
     | 
    
       
     | 
    
       unsigned
     | 
    
      bckCntrl_v_fill_5 : 7
     | 
    
      Filler.
     | 
   
  
    | 
       
     | 
    
       
     | 
    
       }
     | 
    
       
     | 
    
       
     | 
   
  
    | 
       
     | 
    
       }
     | 
    
       
     | 
    
       
     | 
    
       
     | 
   
  
    | 
       struct dsc$descriptor
     | 
    
      bckCntrl_r_response_buffer
     | 
    
      Descriptor for buffer to which response text is to be written.
     | 
   
  
    | 
       unsigned int
     | 
    
      bckCntrl_l_response_status
     | 
    
      Reserved for use by HP.
     | 
   
  
    | 
       unsigned int
     | 
    
      bckCntrl_l_control_options
     | 
    
      Reserved for use by HP.
     | 
   
 
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:
 
  -  Making a best guess as to your intentions
  
 -  Ignoring the least likely of the conflicting qualifiers
  
 -  Issuing a message that warns of the conflicting qualifiers
  
 -  Processing the BACKUP request
  
See the HP OpenVMS System Management Utilities  Reference Manual: A--L for a table of valid combinations of BACKUP
qualifiers.
  
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$_BADOPTVALQ
     | 
    
      Invalid callable interface option value.
     | 
   
  
    | 
      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.
  
Example
The following C example program demonstrates calling the Backup API to
perform the following DCL commands:
 
  
    
       
      
$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_IN:*.*;* -
_$ APITEST1_OUT:A.BCK/SAVE_SET
 
 |   
 
  
    
       
      
$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_OUT:A.BCK/SAVE_SET -
_$ APITEST2_OUT:*.*;*
 
 |   
 
  
     | 
   
    
       
      
#include <stdio.h>
#include <stdlib.h>
#include <ssdef.h>
#include <descrip.h>
#include "sys$examples:bapidef.h"
/*
** Define a fixed size (simple) structure for specifying the
** BACKUP operation.
*/
typedef struct _buf_arg
               {
                bck_opt_struct_flag arg1;
                bck_opt_struct_flag arg2;
                bck_opt_struct_flag arg3;
                bck_opt_struct_flag arg4;
                bck_opt_struct_dsc arg5;
                bck_opt_struct_dsc arg6;
                bck_opt_struct_flag arg7;
                bck_opt_struct_flag arg8;
                bck_opt_struct_adr arg9;
                bck_opt_struct_adr arg10;
                bck_opt_struct_adr arg11;
                bck_opt_struct_flag arg12;
                bck_opt_struct_flag arg13;
               } buf_arg;
struct dsc$descriptor
               input_dsc,
               output_dsc,
               event_type_dsc;
buf_arg myarg_buff;
unsigned int status;
extern unsigned int backup$start(buf_arg  *myarg_buff);
unsigned int subtest(bckEvent *param);
static char  input_str[]      = "APITEST1_IN:";
static char  output_str1[]      = "APITEST1_OUT:a.bck";
static char  output_str2[]      = "APITEST2_OUT:";
main()
{
 myarg_buff.arg1.option_type = BCK_OPT_K_ALIAS;
 myarg_buff.arg1.opt_flag_value = TRUE;
 myarg_buff.arg2.option_type = BCK_OPT_K_VERIFY;
 myarg_buff.arg2.opt_flag_value = TRUE;
 myarg_buff.arg3.option_type = BCK_OPT_K_CRC;
 myarg_buff.arg3.opt_flag_value = TRUE;
 myarg_buff.arg4.option_type = BCK_OPT_K_LOG;
 myarg_buff.arg4.opt_flag_value = TRUE;
 myarg_buff.arg5.opt_dsc_type = BCK_OPT_K_INPUT;
 myarg_buff.arg5.opt_dsc.dsc$b_dtype = DSC$K_DTYPE_T;
 myarg_buff.arg5.opt_dsc.dsc$b_class = DSC$K_CLASS_S;
 myarg_buff.arg5.opt_dsc.dsc$w_length = sizeof(input_str) - 1;
 myarg_buff.arg5.opt_dsc.dsc$a_pointer = input_str;
 myarg_buff.arg6.opt_dsc_type = BCK_OPT_K_OUTPUT;
 myarg_buff.arg6.opt_dsc.dsc$b_dtype = DSC$K_DTYPE_T;
 myarg_buff.arg6.opt_dsc.dsc$b_class = DSC$K_CLASS_S;
 myarg_buff.arg6.opt_dsc.dsc$w_length = sizeof(output_str1) - 1;
 myarg_buff.arg6.opt_dsc.dsc$a_pointer = output_str1;
 myarg_buff.arg7.option_type = BCK_OPT_K_SAVE_SET_OUT;
 myarg_buff.arg7.opt_flag_value = TRUE;
 myarg_buff.arg8.option_type = BCK_OPT_K_OPERATION_TYPE;
 myarg_buff.arg8.opt_flag_value = BCK_OP_K_SAVE ;
 myarg_buff.arg9.opt_adr_type = BCK_OPT_K_EVENT_CALLBACK;
 myarg_buff.arg9.opt_adr_attributes = BCK_EVENT_K_LOG;
 myarg_buff.arg9.opt_adr_value[0] = (int *)subtest;
 myarg_buff.arg9.opt_adr_value[1] = 0;
 /*
 ** Specify that this application will handle user-visible messages.
 ** (The operation phase, and user/file-logging messages.)
 */
 myarg_buff.arg10.opt_adr_type = BCK_OPT_K_EVENT_CALLBACK;
 myarg_buff.arg10.opt_adr_attributes = BCK_EVENT_K_OP_PHASE;
 myarg_buff.arg10.opt_adr_value[0] = (int *)subtest;
 myarg_buff.arg10.opt_adr_value[1] = 0;
 myarg_buff.arg11.opt_adr_type = BCK_OPT_K_EVENT_CALLBACK;
 myarg_buff.arg11.opt_adr_attributes = BCK_EVENT_K_USER_MSG;
 myarg_buff.arg11.opt_adr_value[0] = (int *)subtest;
 myarg_buff.arg11.opt_adr_value[1] = 0;
 /*
 ** Indicate the end of options that specify the BACKUP operation
 ** to be performed.
 */
 myarg_buff.arg12.option_type = BCK_OPT_K_END_OPT;
 myarg_buff.arg12.opt_flag_value = FALSE;
 /*
 ** Notes:
 **  An extra option structure (# 13) was allocated for testing.
 **
 **  The DCL command analogous to the following BACKUP API call
 ** is illustrated below.
 **
 ** "$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_IN:*.*;* -"
 ** "_$  APITEST1_OUT:a.bck/SAVE_SET "
 */
        status = backup$start(&myarg_buff);
 if (! (status & 1))
 {
     exit (status);  /* EXIT if the first part of the test failed. */
 }
 /*
 **  Now use the resultant saveset to perform a restore operation.
 */
 /*
 **  Change the input string to specify the saveset, ("output_str1").
 */
 myarg_buff.arg5.opt_dsc.dsc$w_length = sizeof(output_str1) - 1;
 myarg_buff.arg5.opt_dsc.dsc$a_pointer = output_str1;
 /*
 **  Change the output string to specify the output device/directory).
 */
 myarg_buff.arg6.opt_dsc.dsc$w_length = sizeof(output_str2) - 1;
 myarg_buff.arg6.opt_dsc.dsc$a_pointer = output_str2;
 /*
 **  Change the option to denote it is now an input saveset,
 **  (not an output saveset).
 */
 myarg_buff.arg7.option_type = BCK_OPT_K_SAVE_SET_IN;
 /*
 **  Change the option to specify a restore operation,
 **  (not a save operation).
 */
 myarg_buff.arg8.opt_flag_value = BCK_OP_K_RESTORE;
 /*
 **  The DCL command analogous to the following BACKUP API call
 ** is illustrated below.
 **
 ** "$ BACKUP/LOG/VERIFY/CRC/ALIAS APITEST1_OUT:a.bck/SAVE_SET -"
 ** "_$  APITEST2_OUT:*.*;*"
 */
 status = backup$start(&myarg_buff);
        exit (status);
}
unsigned int subtest(bckEvent *param)
{
 printf("\n BACKUP API Event Type = %d,\n",param->bckevt_l_event_type);
 printf("               Subtype = %d\n",param->bckevt_l_event_subtype);
 if (param->bckevt_l_event_type == BCK_EVENT_K_LOG)
 {
     printf(" BACKUP API LOG Event item:\n %.*s\n",
      param->bckevt_r_event_buffer.dsc$w_length,
      param->bckevt_r_event_buffer.dsc$a_pointer);
 }
 if (param->bckevt_l_event_type == BCK_EVENT_K_OP_PHASE)
 {
     printf(" BACKUP API Operation Phase Event\n %.*s\n",
      param->bckevt_r_event_buffer.dsc$w_length,
      param->bckevt_r_event_buffer.dsc$a_pointer);
 }
 fflush(stdout);
        return (1);
}
      
      
     | 
   
 
  
 
  
  
		 |