1 BACKUP_API The Backup application programming interface (API) allows user- written applications to perform BACKUP operations. 2 BACKUP$START BACKUP$START is the entry point through which applications invoke the OpenVMS Backup utility. Format BACKUP$START argument-buffer 3 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. 3 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. 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, 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. 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 HP ctx [2] unsigned int bckevt_l_event_ Reserved for use by HP 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 = 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 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 HP. response_status unsigned int bckCntrl_l_ Reserved for use by HP. 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 HP OpenVMS System Management Utilities Reference Manual: A-L for a table of valid combinations of BACKUP qualifiers. 3 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.