[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

OpenVMS Utility Routines Manual


Previous Contents Index


Chapter 3
Backup (BACKUP) Routine

This chapter describes the Backup application programming interface (API). User-written applications can use the Backup API to perform BACKUP operations.

3.1 Introduction to the Backup API

The Backup API allows application programs to save individual files or the contents of entire disk volume sets. The Backup API also allows application programs to get information about files or disk and tape volumes.

In general, the Backup API gives application programs access to (relevant) BACKUP functions that are available to an interactive user via the DCL command BACKUP. The application program calls routine BACKUP$START with an argument that points to a variable-length array, which consists of option structures to specify the required BACKUP operation. The call to BACKUP$START in combination with the option structures in the variable-length array form the equivalent of a BACKUP command at DCL level.

Each relevant BACKUP qualifier is represented by an option structure or combination of option structures. Each option structure consists of a longword that contains the option structure identifier, followed by a value field of 1 to 7 longwords. Each option structure must be quadword-aligned within the variable-length array. There are six option structure types:

Option Definition
bck_opt_struct_adr 32-bit address
bck_opt_struct_dsc Static string descriptor
bck_opt_struct_dsc64 Reserved for use by Compaq
bck_opt_struct_dt Date/Time quadword (ADT)
bck_opt_struct_flag Logical bit flags
bck_opt_struct_int 32-bit integer

The option structure types are defined in the language definition files. Table 3-1 lists the language definition files.

Table 3-1 Backup API Language Definition Files
Language API Definitions Media Format (Save Set) Definitions Backup Utility Data Structures
BASIC BAPIDEF.BAS BACKDEF.BAS BACKSTRUC.BAS
BLISS BAPIDEF.R32 BACKDEF.R32 BACKSTRUC.R32
C BAPIDEF.H BACKDEF.H BACKSTRUC.H
Fortran BAPIDEF.FOR BACKDEF.FOR BACKSTRUC.FOR
MACRO BAPIDEF.MAR BACKDEF.MAR BACKSTRUC.MAR

See the OpenVMS System Management Utilities Reference Manual: A--L for detailed definitions of the DCL command BACKUP qualifiers. See the OpenVMS System Manager's Manual, Volume 1: Essentials for detailed information about using BACKUP. You can also use the Help facility for more information about the Backup command and its qualifiers.

3.2 Using the Backup API: An Example

Example 3-1 shows a VAX C program that calls the Backup API. This program produces the same result as the following DCL command:


    $  BACKUP [.WRK]*.* A.BCK/SAVE

Example 3-1 Calling the Backup API with a VAX C Program

#include <stdio.h>
#include <stdlib.h>
#include <ssdef.h>
#include <descrip.h>
#include "sys$examples:bapidef.h"

typedef struct _buf_arg
               {
                bck_opt_struct_dsc arg1;
                bck_opt_struct_dsc arg2;
                bck_opt_struct_flag arg3;
                bck_opt_struct_flag arg4;
                bck_opt_struct_flag arg5;

               } 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(void *);

static char  input_str[]      = "[.wrk]";
static char  output_str[]      = "a.bck";

main()
{
        input_dsc.dsc$b_dtype =
        output_dsc.dsc$b_dtype = DSC$K_DTYPE_T;

        input_dsc.dsc$b_class =
        output_dsc.dsc$b_class = DSC$K_CLASS_S;

        input_dsc.dsc$w_length = sizeof(input_str);
        output_dsc.dsc$w_length = sizeof(output_str);

        input_dsc.dsc$a_pointer = input_str;
        output_dsc.dsc$a_pointer = output_str;


 myarg_buff.arg1.opt_dsc_type = BCK_OPT_K_INPUT;
 myarg_buff.arg1.opt_dsc = input_dsc;

 myarg_buff.arg2.opt_dsc_type = BCK_OPT_K_OUTPUT;
 myarg_buff.arg2.opt_dsc = output_dsc;

 myarg_buff.arg3.option_type = BCK_OPT_K_SAVE_SET_OUT;
 myarg_buff.arg3.opt_flag_value = TRUE;

 myarg_buff.arg4.option_type = BCK_OPT_K_OPERATION_TYPE;
 myarg_buff.arg4.opt_flag_value = BCK_OP_K_SAVE ;

 myarg_buff.arg5.option_type = BCK_OPT_K_END_OPT;
 myarg_buff.arg5.opt_flag_value = FALSE;

        status = backup$start(&myarg_buff);

        exit (status);
}

3.3 Backup API

This section describes the Backup API.


BACKUP$START

BACKUP$START is the entry point through which applications invoke the OpenVMS Backup utility.

Format

BACKUP$START argument-buffer


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.


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. Table 3-2 describes the option structures.

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.

Table 3-2 BACKUP Option Structure Types
Option Structure Description
BCK_OPT_K_END_OPT Flag that contains all zeros to denote the end of argument-buffer. This option structure consists of 2 longwords. The first longword, with a value of 0, identifies the BCK_OPT_K_END_OPT option structure. The second longword is ignored by BACKUP. However it is recommended that the second longword contain all zeros.
BCK_OPT_K_ALIAS Flag that specifies whether to maintain the previous behavior of multiple processing of alias and primary file entries.

Values are TRUE (default) or FALSE. (See the BACKUP qualifier /ALIAS.)

Note: Use of BCK_OPT_K_ALIAS and BCK_OPT_K_PHYSICAL in the same call results in a fatal error.

BCK_OPT_K_ASSIST Flag that specifies whether to allow operator or user intervention if a request to mount a magnetic tape fails during a BACKUP operation.

Values are TRUE (default) or FALSE.

(See the BACKUP qualifier /ASSIST.)

BCK_OPT_K_BACKUP Flag that specifies whether to select files according to the BACKUP date written in the file header record.

Values are TRUE or FALSE. Use this flag to set the corresponding logical bit flag for BCK_OPT_K_BEFORE_TYPE and BCK_OPT_K_SINCE_TYPE.

(See the BACKUP qualifiers /BEFORE, /SINCE, and /BACKUP.)

BCK_OPT_K_BEFORE_TYPE Logical bit flags that qualify the date specified in the BCK_OPT_K_BEFORE_VALUE option structure. Type can be one of the following:
BCK_OPTYP_BEFORE_K_BACKUP
  Selects files last saved or copied by BACKUP before the date specified. Also selects files with no BACKUP date.
BCK_OPTYP_BEFORE_K_CREATED
  Selects files created before the date specified.
BCK_OPTYP_BEFORE_K_EXPIRED
  Selects files that have expired as of the date specified.
BCK_OPTYP_BEFORE_K_MODIFIED
  (Default) Selects files last modified before the date specified.
BCK_OPTYP_BEFORE_K_SPECIFIED
  Reserved for use by Compaq.


(See the BACKUP qualifiers /BEFORE, /BACKUP, /CREATED, /EXPIRED, and /MODIFIED.)

BCK_OPT_K_BEFORE_VALUE Date-Time Quadword that specifies the date qualified by BCK_OPT_K_BEFORE_TYPE. You cannot use delta time.

(See the BACKUP qualifier /BEFORE.)

BCK_OPT_K_BLOCK Integer that specifies the block size in bytes for data records in the BACKUP save set.

The default block size for magnetic tape is 8,192 bytes. The default block size for disk is 32,256 bytes.

(See the BACKUP qualifier /BLOCK_SIZE.)

BCK_OPT_K_CARTRIDGE_MEDIA_IN 1 32-bit descriptor.

Note: Use of BCK_OPT_K_CARTRIDGE_MEDIA_IN and BCK_OPT_K_CARTRIDGE_NAME_IN or any of the BCK_OPT_K_SCRATCH_* option structures in the same call results in a fatal error.

BCK_OPT_K_CARTRIDGE_NAME_IN 1 32-bit descriptor.

Note: Use of BCK_OPT_K_CARTRIDGE_NAME_IN and BCK_OPT_K_CARTRIDGE_MEDIA_IN or any of the BCK_OPT_K_SCRATCH_* option structures in the same call results in a fatal error.

BCK_OPT_K_CARTRIDGE_SIDE_IN 1 32-bit descriptor.

Note: Use of BCK_OPT_K_CARTRIDGE_SIDE_IN without BCK_OPT_K_CARTRIDGE_NAME_IN in the same call results in a fatal error.

Note: Use of BCK_OPT_K_CARTRIDGE_SIDE_IN with any of the BCK_OPT_K_SCRATCH_* option structures in the same call results in a fatal error.

BCK_OPT_K_CARTRIDGE_MEDIA_OUT 1 32-bit descriptor.

Note: Use of BCK_OPT_K_CARTRIDGE_MEDIA_OUT and BCK_OPT_K_CARTRIDGE_NAME_OUT or any of the BCK_OPT_K_SCRATCH_* option structures in the same call results in a fatal error.

BCK_OPT_K_CARTRIDGE_NAME_OUT 1 32-bit descriptor.

Note: Use of BCK_OPT_K_CARTRIDGE_NAME_OUT and BCK_OPT_K_CARTRIDGE_MEDIA_OUT or any of the BCK_OPT_K_SCRATCH_* option structures in the same call results in a fatal error.

BCK_OPT_K_CARTRIDGE_SIDE_OUT 1 32-bit descriptor.

Note: Use of BCK_OPT_K_CARTRIDGE_SIDE_OUT without BCK_OPT_K_CARTRIDGE_NAME_OUT in the same call results in a fatal error.

Note: Use of BCK_OPT_K_CARTRIDGE_SIDE_OUT with any of the BCK_OPT_K_SCRATCH_* option structures in the same call results in a fatal error.

BCK_OPT_K_COMMAND Reserved for use by Compaq.
BCK_OPT_K_COMMENT 32-bit descriptor that specifies a comment string to be placed in the output save set.

(See the BACKUP qualifier /COMMENT.)

BCK_OPT_K_COMPARE Flag that specifies whether to compare the entity specified by BCK_OPT_K_INPUT with the entity specified by BCK_OPT_K_OUTPUT. Values are TRUE and FALSE (default).

(See the BACKUP qualifier /COMPARE.)

BCK_OPT_K_CONFIRM Flag that specifies whether to prompt for confirmation before processing each file.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /CONFIRM.)

BCK_OPT_K_CRC Flag that specifies whether the software cyclic redundancy check (CRC) is to be performed.

Values are TRUE (default) and FALSE.

(See the BACKUP qualifier /CRC.)

BCK_OPT_K_CREATED Flag that specifies whether to select files according to the creation date written in the file header record.

Values are TRUE or FALSE.

Use this flag to set the corresponding logical bit flag for BCK_OPT_K_BEFORE_TYPE and BCK_OPT_K_SINCE_TYPE.

(See the BACKUP qualifiers /BEFORE, /SINCE, and /CREATED.)

BCK_OPT_K_DCL_INTERFACE Reserved for use by Compaq.
BCK_OPT_K_DELETE Flag that specifies whether a copy or backup operation is to delete the input files from the input volume when the operation is complete.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /DELETE.)

BCK_OPT_K_DENSITY Integer that specifies the recording density of the output magnetic tape in bits per inch (bits/in).

The density specified must be supported by the magnetic tape hardware. The default density is the current density on the output tape drive. (See the BACKUP qualifier /DENSITY.)

Note: Use of BCK_OPT_K_DENSITY and BCK_OPT_K_MEDIA_FORMAT in the same call results in a fatal error.

BCK_OPT_K_DISMOUNT Reserved for use by Compaq.
BCK_OPT_K_DISPOSITION 1 Logical bit flags. Values are the following:
BCK_OPTYP_DISP_K_KEEP
BCK_OPTYP_DISP_K_RELEASE
BCK_OPT_K_DRIVE_CLASS_IN 1 32-bit descriptor.
BCK_OPT_K_DRIVE_CLASS_OUT 1 32-bit descriptor.
BCK_OPT_K_ENCRYPT 2 Flag.
BCK_OPT_K_ENCRYPT_USERALG 2 32-bit descriptor.
BCK_OPT_K_ENCRYPT_USERKEY 2 32-bit descriptor.

Note: Use of BCK_OPT_K_ENCRYPT_USERKEY and BCK_OPT_K_ENCRYPT_KEY_VALUE in the same call results in a fatal error.

BCK_OPT_K_ENCRYPT_KEY_VALUE 2 32-bit descriptor.

Note: Use of BCK_OPT_K_ENCRYPT_KEY_VALUE and BCK_OPT_K_ENCRYPT_USERKEY in the same call results in a fatal error.

BCK_OPT_K_EVENT_CALLBACK Address of a routine in the calling application to be called to process BACKUP events. See the Description section for detailed information about event callbacks.
BCK_OPT_K_EXACT_ORDER Flag that specifies whether a BACKUP operation is to accept an exact order of tape volume labels, preserve an existing volume label, and prevent previous volumes of a multivolume save operation from being overwritten.

Values are TRUE (default) and FALSE.

(See the BACKUP qualifier /EXACT_ORDER.)

BCK_OPT_K_EXCLUDE 32-bit descriptor that specifies the name of an input file to be excluded from the current BACKUP save or copy operation. Wildcards are permitted. Each file specification, whether wildcarded or not, requires its own BCK_OPT_K_EXCLUDE option structure (lists are not supported).

(See the BACKUP qualifier /EXCLUDE.)

BCK_OPT_K_EXPIRED Flag that specifies whether to select files according to the expiration date written in the file header record.

Values are TRUE or FALSE.

Use this flag to set the corresponding logical bit flag for BCK_OPT_K_BEFORE_TYPE and BCK_OPT_K_SINCE_TYPE.

(See the BACKUP qualifiers /BEFORE, /SINCE, and /EXPIRED.)

BCK_OPT_K_FAST Flag that specifies whether to reduce processing time by performing a fast file scan of the input specifier.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /FAST.)

BCK_OPT_K_FILE_CALLBACK Reserved for use by Compaq.
BCK_OPT_K_FILEMERGE Reserved for use by Compaq.
BCK_OPT_K_FULL Flag that specifies whether to display information produced by a BCK_OPT_K_LIST value of TRUE in a format similar to that produced by the DCL command DIRECTORY/FULL.

Values are TRUE and FALSE (default).

(See the BACKUP qualifiers /LIST and /FULL.)

BCK_OPT_K_GROUP Integer that specifies the number of backup blocks or backup buffers BACKUP places in each redundancy group.

The default is 10 blocks.

(See the BACKUP qualifier /GROUP_SIZE.)

BCK_OPT_K_HANDLE Reserved for use by Compaq.
BCK_OPT_K_IGNORE_TYPES Logical bit flags that override tape labeling checks or restrictions placed on files. Values are one of the following:
BCK_OPTYP_IGNORE_K_ACCESS
  Processes files on a tape that is protected by a volume accessibility character, or a tape created by HSC Backup. Applies to all tapes in the save set.
BCK_OPTYP_IGNORE_K_INTERLOCK
  Processes files otherwise inaccessible because of file access conflicts.
BCK_OPTYP_IGNORE_K_LABELS
  Ignores the contents of the volume header record. You cannot use this flag if the BCK_OPTYP_K_EXACT_ORDER option structure flag value is TRUE.
BCK_OPTYP_IGNORE_K_NOBACKUP
  Processes both the file header and the contents of files marked with the NOBACKUP option.


(See the BACKUP qualifier /IGNORE.)

BCK_OPT_K_IMAGE Flag that directs that an entire volume or volume set be processed.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /IMAGE.)

BCK_OPT_K_INCREMENTAL Flag that specifies whether to restore an incremental save set.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /INCREMENTAL.)

BCK_OPT_K_INITIALIZE Flag that specifies whether to initialize an entire output volume, thereby making its previous contents inaccessible.

Values are TRUE and FALSE (default, except for image restore and copy operations).

(See the BACKUP qualifier /INITIALIZE.)

BCK_OPT_K_INPUT 32-bit descriptor that specifies a single input-specifier. You can use wildcards. You must use a separate BCK_OPT_K_INPUT option structure for each specification.

(See the BACKUP Format description.)

BCK_OPT_K_INTERCHANGE Flag that specifies whether to process files in a manner suitable for data interchange.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /INTERCHANGE.)

BCK_OPT_K_JOURNAL Flag that specifies whether a BACKUP journal file is to be processed. You can specify a journal file name other than BACKUP.BJL (the default) with the BCK_OPT_K_JOURNAL_FILE option structure.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /JOURNAL.)

BCK_OPT_K_JOURNAL_FILE 32-bit descriptor that specifies the name of a BACKUP journal file to be processed.

(See the BACKUP qualifier /JOURNAL.)

BCK_OPT_K_LABEL 32-bit descriptor that specifies the volume label to be written. To specify more than one label, use additional BCK_OPT_K_LABEL option structures.

(See the BACKUP qualifier /LABEL.)

Note: Use of BCK_OPT_K_LABEL with any BCK_OPT_K_SCRATCH_* option structure in the same call results in a fatal error.

BCK_OPT_K_LIST Flag that specifies whether to process a BACKUP list file. You can specify a list output destination other than TTY: (the default) with the BCK_OPT_K_LIST_FILE option structure.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /LIST.)

BCK_OPT_K_LIST_FILE 32-bit descriptor that specifies the name of a file of a BACKUP journal file to be processed.

(See the BACKUP qualifier /LIST.)

BCK_OPT_K_LOG Flag that specifies whether to display the file specification of each file processed. The display is to SYS$OUTPUT.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /LOG.)

BCK_OPT_K_MEDIA_FORMAT Logical bit flags that specify whether data records are automatically compacted and blocked together. The tape drive must support compaction.

Values are one of the following:

BCK_OPTYP_MEDIA_K_COMPACTION
BCK_OPTYP_MEDIA_K_NO_COMPACTION (default)

(See the BACKUP qualifier /MEDIA_FORMAT.)


Note: Use of BCK_OPT_K_MEDIA_FORMAT and BCK_OPT_K_DENSITY in the same call results in a fatal error.

BCK_OPT_K_MODIFIED Flag that specifies whether to select files according to the modification date written in the file header record.

Values are TRUE and FALSE.

Use this flag to set the corresponding logical bit flag for BCK_OPT_K_BEFORE_TYPE and BCK_OPT_K_SINCE_TYPE.

(See the BACKUP qualifiers /BEFORE, /SINCE, and /MODIFIED.)

BCK_OPT_K_NEW_VERSION Flag that specifies whether to create a new version of a file if a file with an identical file specification already exists at the location to which the file is being copied or restored.

Values are TRUE and FALSE (default).

Because this qualifier causes version numbers to change, using it with the BCK_OPT_K_VERIFY flag set to TRUE can cause unpredictable results. Compaq recommends that you not use these two options in combination.

(See the BACKUP qualifier /NEW_VERSION.)

BCK_OPT_K_OPERATION_TYPE Logical bit flags that specify the type of BACKUP operation to be performed.

Values are one of the following:

BCK_OP_K_SAVE (default)
BCK_OP_K_RESTORE
BCK_OP_K_COPY
BCK_OPT_K_LIST
BCK_OPT_K_COMPARE
BCK_OPT_K_OUTPUT 32-bit descriptor that specifies the name of a single output-specifier. You can use wildcards. Each file specification requires a separate BCK_OPT_K_OUTPUT option structure. Lists are not supported.

(See BACKUP Format description.)

BCK_OPT_K_OVERLAY Flag that specifies whether to overlay (at the same physical location) an existing file with a file specification identical to that of the file that is being copied or restored.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /OVERLAY.)

BCK_OPT_K_OWNER_IN_VALUE Integer that specifies the user identification code (UIC) of the files to be processed by a BACKUP input operation. The default is the UIC of the current process. If you do not include this option structure, BACKUP processes all files specified by BCK_OPT_K_INPUT.

(See the BACKUP qualifier /BY_OWNER.)

BCK_OPT_K_OWNER_OUT_TYPE Logical bit flags to specify the user identification code (UIC) of restored files.

Values are one of the following:

BCK_OPTYP_OWN_OUT_K_DEFAULT
  Sets the owner UIC to the UIC of the current process (default unless BCK_OPT_K_IMAGE or BCK_OPT_K_INCREMENTAL is TRUE).
BCK_OPTYP_OWN_OUT_K_ORIGINAL
  Retains the owner UIC of the file being restored (default if BCK_OPT_K_IMAGE or BCK_OPT_K_INCREMENTAL is TRUE).
BCK_OPTYP_OWN_OUT_K_PARENT
  Sets the owner UIC to the owner UIC of the directory to which the file is being written. The current process must have the SYSPRV user privilege, or be the owner of the output volume, or must have the parent UIC.


(See the BACKUP qualifier /BY_OWNER.)

BCK_OPT_K_OWNER_OUT_VALUE Integer that redefines the UIC of the files written by a BACKUP restore or copy operation, or specifies the UIC of an output save set.

If BCK_OPT_K_OUTPUT specifies a save set, the default is the UIC of the current process. To specify the UIC of a Files-11 save set, the current process must have the SYSPRV user privilege, or must have the UIC specified.

If BCK_OPT_K_OUTPUT specifies files, the UIC of the output files is set to the UIC specified. To specify the UIC, the UIC must be that of the current process, or must have the SYSPRV user privilege, or the current process must be the owner of the output device.

(See the BACKUP qualifier /BY_OWNER.)

BCK_OPT_K_PHYSICAL Flag that specifies that a BACKUP operation is to ignore any file structure on the input volume and instead process the volume in terms of logical blocks.

Values are TRUE and FALSE (default). Note that output operations on a save set must be performed with the same physical option as that used to create the save set. (See the BACKUP qualifier /PHYSICAL.)

Note: Use of BCK_OPT_K_PHYSICAL and BCK_OPT_K_UNSHELVE or BCK_OPT_K_ALIAS in the same call results in a fatal error.

BCK_OPT_K_PROTECTION Logical bit flags that specify file protection. Bits 0 to 15 of the option structure value field are in the format of the RMS field XAB$W_PRO. See the OpenVMS Record Management Services Reference Manual for information about the format of this field.

(Also see BACKUP utility qualifier /PROTECTION.)

BCK_OPT_K_RECORD Flag that specifies whether to record the current date and time in the BACKUP date field in each file header once a file is successfully saved or copied.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /RECORD.)

BCK_OPT_K_RELEASE_TAPE Flag that specifies whether to dismount and unload a tape after a BACKUP save operation has either reached the end of the tape or has written and verified the save set.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /RELEASE_TAPE.)

BCK_OPT_K_REPLACE Flag that specifies whether to replace (at a different physical location), with an identical version number, an existing file with a file specification identical to that of the file that is being copied or restored.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /REPLACE.)

BCK_OPT_K_REWIND Flag. Reserved for use by Compaq.
BCK_OPT_K_REWIND_IN Flag that specifies whether the input device is a tape drive, and that it is to be rewound to the beginning-of-tape marker before beginning the BACKUP operation.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /REWIND.)

BCK_OPT_K_REWIND_OUT Flag that specifies whether the output device is a tape drive, and that it is to be rewound to the beginning-of-tape marker and initialized before beginning the BACKUP operation.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /REWIND.)

Note: Use of BCK_OPT_K_REWIND_OUT with any BCK_OPT_K_SCRATCH_* option structure in the same call results in a fatal error.

BCK_OPT_K_SAVE_SET_IN Flag that indicates whether the input specifier is a BACKUP save-set file.

Values are TRUE and FALSE (default; indicates that the input specifier refers to a Files-11 file).

(See the BACKUP qualifier /SAVE_SET.)

BCK_OPT_K_SAVE_SET_OUT Flag that indicates whether the output specifier specifies a BACKUP save-set file.

Values are TRUE and FALSE (default; indicates that the output specifier refers to a Files-11 file).

(See the BACKUP qualifier /SAVE_SET.)

BCK_OPT_K_SCRATCH_ASGN_TYPE 1 Logical bit flags.

Note: Use of BCK_OPT_K_SCRATCH_ASGN_TYPE with BCK_OPT_K_LABEL, BCK_OPT_K_REWIND_OUT, any of the BCK_OPT_K_CARTRIDGE_* option structures, or any other BCK_OPT_K_SCRATCH_* option structure in the same call results in a fatal error.

BCK_OPT_K_SCRATCH_COLLECTION 1 32-bit descriptor.

Note: Use of BCK_OPT_K_SCRATCH_COLLECTION with BCK_OPT_K_LABEL, BCK_OPT_K_REWIND_OUT, any of the BCK_OPT_K_CARTRIDGE_* option structures, or any other BCK_OPT_K_SCRATCH_* option structure in the same call results in a fatal error.

BCK_OPT_K_SCRATCH_LOCATION 1 32-bit descriptor.

Note: Use of BCK_OPT_K_SCRATCH_LOCATION with BCK_OPT_K_LABEL, BCK_OPT_K_REWIND_OUT, any of the BCK_OPT_K_CARTRIDGE_* option structures, or any other BCK_OPT_K_SCRATCH_* option structure in the same call results in a fatal error.

BCK_OPT_K_SCRATCH_MEDIA_NAME 1 32-bit descriptor.

Note: Use of BCK_OPT_K_SCRATCH_MEDIA_NAME with BCK_OPT_K_LABEL, BCK_OPT_K_REWIND_OUT, any of the BCK_OPT_K_CARTRIDGE_* option structures, or any other BCK_OPT_K_SCRATCH_* option structure in the same call results in a fatal error.

BCK_OPT_K_SELECT 32-bit descriptor that references the file specification of a file or files from the input save set to be processed by the current BACKUP save or copy operation. Wildcards are permitted. Each file specification, whether wildcards are used or not, requires its own BCK_OPT_K_SELECT option structure (lists are not supported).

(See the BACKUP qualifier /SELECT.)

BCK_OPT_K_SINCE_TYPE Logical bit flags that qualify the date specified in the BCK_OPT_K_SINCE_VALUE option structure.

Type can be one of the following:

BCK_OPTYP_SINCE_K_BACKUP
  Selects files last saved or copied by BACKUP on or after the date specified. Also selects files with no BACKUP date.
BCK_OPTYP_SINCE_K_CREATED
  Selects files created on or after the date specified.
BCK_OPTYP_SINCE_K_EXPIRED
  Selects files that have expired since the date specified.
BCK_OPTYP_SINCE_K_MODIFIED
  Selects files last modified on or after the date specified (default).
BCK_OPTYP_SINCE_K_SPECIFIED
  Reserved for use by Compaq.


(See the BACKUP qualifiers /SINCE, /BACKUP, /CREATED, /EXPIRED, and /MODIFIED.)

BCK_OPT_K_SINCE_VALUE Date-Time Quadword that specifies the date qualified by BCK_OPTYP_K_SINCE_TYPE. You cannot use delta time.

(See the BACKUP qualifier /SINCE.)

BCK_OPT_K_STORAGE_MANAGEMENT 1 32-bit descriptor.
BCK_OPT_K_TAPE_EXPIRATION ADT (Date-Time) that specifies when the tape expires.

(See the BACKUP qualifier /TAPE_EXPIRATION.)

BCK_OPT_K_TRUNCATE Flag that specifies whether a copy or restore operation truncates a sequential output file at the end-of-file (EOF) when creating it.

Values are TRUE and FALSE (default; the size of the output file is determined by the allocation of the input file).

(See the BACKUP qualifier /TRUNCATE.)

BCK_OPT_K_UNSHELVE Flag that is reserved for use with file-shelving layered products.

Values are TRUE and FALSE.

Note: Use of BCK_OPT_K_UNSHELVE and BCK_OPT_K_PHYSICAL in the same call results in a fatal error.

BCK_OPT_K_VALIDATE_PARAMETERS Reserved for use by Compaq.
BCK_OPT_K_VERIFY Flag that specifies whether the contents of the output specifier be compared with the contents of the input specifier after a save, restore, or copy operation has been completed.

Values are TRUE and FALSE (default).

(See the BACKUP qualifier /VERIFY.)

BCK_OPT_K_VOLUME Integer that specifies the specific disk volume in a disk volume set to be processed (valid only when BCK_OPT_K_IMAGE is TRUE).

(See the BACKUP qualifier /VOLUME.)


1Reserved for use by Media Management Extension (MME) layered products.
2Reserved for future use by a security utility or layered product.


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.


Previous Next Contents Index