OpenVMS Utility Routines Manual

Document revision date: 19 July 1999

OpenVMS Utility Routines Manual

Contents

Index

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, Compaq 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 Compaq

unsigned int bckevt_l_event_handle Reserved for use by Compaq

**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 Compaq
unsigned int	bckevt_l_event_handle	Reserved for use by Compaq

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-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)

**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 Compaq.

unsigned int bckCntrl_l_control_options Reserved for use by Compaq.

**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 Compaq.
unsigned int	bckCntrl_l_control_options	Reserved for use by Compaq.

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 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); }

 
#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); 
}

Contents

Index

privacy and legal statement

4493PRO_002.HTML

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.