Reset Backup Flag

Purpose

Used by backup programs to reset the backup bit after completion of a backup. The backup program is expected to quiesce the aggregate and save the quiesce handle before beginning the backup. After completing the backup, the backup bit should be reset before unquiescing the aggregate.

Format

syscall_parmlist
   opcode                  int             157 AGOP_RESETFLAG_PARMDATA
   parms[0]                int             offset to AGGR_ID
   parms[1]                int             quiesce handle
   parms[2]                int             0
   parms[3]                int             0
   parms[4]                int             0
   parms[5]                int             0
   parms[6]                int             0
AGGR_ID
   aid_eye                 char[4]         "AGID"
   aid_len                 char            sizeof(AGGR_ID)
   aid_ver                 char 1
   aid_name                char[45]        "OMVS.PRV.AGGR001.LDS0001"
   aid_reserved            char[33]        0

Return_value 0 if request is successful, -1 if it is not successful

Return_code
  EINVAL   Invalid input parameters
  ENOENT   Aggregate not found
  ENOSYS   Aggregate not locally owned
  EBUSY    Aggregate is growing 
  EMVSERR  Internal error using an osi service

Reason_code
  0xEFnnxxxx   See z/OS Distributed File Service Messages and Codes  
  EINVAL       Invalid parameters
  
Reason_code
  0xEFnnxxxx   See z/OS Distributed File Service Messages and Codes

Usage notes

The backup bit must be reset while the aggregate is still quiesced for backup.
Reserved fields and undefined flags must be set to binary zeros.

Privilege required

The issuer must be logged in as root or must have READ authority to the SUPERUSER.FILESYS.PFSCTL resource in the z/OS® UNIXPRIV class.

Related services

Quiesce Aggregate
Unquiesce Aggregate

Restrictions

None.

Examples

#pragma linkage(BPX1PCT, OS)
extern void BPX1PCT(char *, int, int, char *, int *, int *, int *);

#include <stdio.h>

#define ZFSCALL_AGGR 0x40000005
#define AGOP_RESETFLAG_PARMDATA 157

typedef struct syscall_parmlist_t
{
    int  opcode;                /* Operation code to perform */
    int  parms[7];              /* Specific to type of operation, */
                                /* provides access to the parms */
                                /* parms[2]-parms[6] are currently unused*/
} syscall_parmlist;

#define ZFS_MAX_AGGRNAME 44

typedef struct aggr_id_t
{
    char aid_eye[4];                    /* Eye Catcher */
#define  AID_EYE "AGID"
    char aid_len;                       /* Length of this structure */
    char aid_ver;                       /* Version */
#define  AID_VER_INITIAL 1              /* Initial version */
    char aid_name[ZFS_MAX_AGGRNAME+1];  /* aggr name, null terminated */
    char aid_reserved[33];              /* Reserved for the future */
} AGGR_ID;

struct parmstruct {
    syscall_parmlist myparms;
    AGGR_ID          aggr_id;
};

int main(int argc, char **argv) 
{
    int               bpxrv;
    int               bpxrc;
    int               bpxrs;
    
    /*Aggregate name to attach, aggregate must 
      be quiesced for this API to run successfully */
    char              aggrname[45]       = "PLEX.DCEIMGQX.FS"; 
    
    struct parmstruct myparmstruct;
    AGGR_ID           *idp           = &(myparmstruct.aggr_id);

    /* This is the handle returned by zFS on a quiesce aggregate   */
    /* Ensure that the quiesce_handle is set to the value returned */
    /* by the quiesce                                              */
    int               quiesce_handle = 1;                                          

    myparmstruct.myparms.opcode   = AGOP_RESETFLAG_PARMDATA;
    myparmstruct.myparms.parms[0] = sizeof(syscall_parmlist);
    myparmstruct.myparms.parms[1] = quiesce_handle;
    myparmstruct.myparms.parms[2] = 0;
    myparmstruct.myparms.parms[3] = 0;
    myparmstruct.myparms.parms[4] = 0;
    myparmstruct.myparms.parms[5] = 0;
    myparmstruct.myparms.parms[6] = 0;
    memset(idp, 0, sizeof(AGGR_ID));      /* Ensure reserved fields are 0 */

    memcpy(&myparmstruct.aggr_id.aid_eye, AID_EYE, 4);
    myparmstruct.aggr_id.aid_len = sizeof(AGGR_ID);
    myparmstruct.aggr_id.aid_ver = AID_VER_INITIAL;
    strcpy(myparmstruct.aggr_id.aid_name, aggrname);

    BPX1PCT("ZFS     ",
            ZFSCALL_AGGR,                /* Aggregate operation */
            sizeof(myparmstruct),        /* Length of Argument */
            (char *)&myparmstruct,       /* Pointer to Argument */
            &bpxrv,                      /* Pointer to Return_value */
            &bpxrc,                      /* Pointer to Return_code */
            &bpxrs);                     /* Pointer to Reason_code */

    if (bpxrv < 0) 
    {
        printf("Error resetting backup flag for aggregate %s\n", aggrname);
        printf("BPXRV = %d BPXRC = %d BPXRS = %x\n", bpxrv, bpxrc, bpxrs);
        return bpxrc;
    } 
    else /* Return from reset was successful */
        printf("Successfully reset backup flag for aggregate %s\n", aggrname);
    return 0;
}