HELPLIB.HLB  —  BACKUP_API
    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.
Close Help