Section 3.1: Introduction
- This chapter documents the API for the Volume Location Server facility, as defined by the vldbint.xg Rxgen interface file and the vldbint.h include file. Descriptions of all the constants, structures, macros, and interface functions available to the application programmer appear here.
- It is expected that Volume Location Server client programs run in user space, as does the associated vos volume utility. However, the kernel-resident Cache Manager agent also needs to call a subset of the Volume Location Server's RPC interface routines. Thus, a second Volume Location Server interface is available, built exclusively to satisfy the Cache Manager's limited needs. This subset interface is defined by the afsvlint.xg Rxgen interface file, and is examined in the final section of this chapter.
3.2: Constants
- This section covers the basic constant definitions of interest to the Volume Location Server application programmer. These definitions appear in the vldbint.h file, automatically generated from the vldbint.xg Rxgen interface file, and in vlserver.h.
- Each subsection is devoted to describing the constants falling into the following categories:
- Configuration and boundary quantities
- Update entry bits
- List-by-attribute bits
- Volume type indices
- States for struct vlentry
- States for struct vldbentry
- ReleaseType argument values
- Miscellaneous items
Section 3.2.1: Configuration and Boundary
Quantities
- These constants define some basic system values, including configuration information.
- Name
- MAXNAMELEN
- Value
- 65
- Description
- Maximum size of various character strings, including volume name fields in structures and host names.
- Name
- MAXNSERVERS
- Value
- 8
- Description
- Maximum number of replications sites for a volume.
- Name
- MAXTYPES
- Value
- 3
- Description
- Maximum number of volume types.
- Name
- VLDBVERSION
- Value
- 1
- Description
- VLDB database version number
- Name
- HASHSIZE
- Value
- 8,191
- Description
- Size of internal Volume Location Server volume name and volume ID hash tables. This must always be a prime number.
- Name
- NULLO
- Value
- 0
- Description
- Specifies a null pointer value.
- Name
- VLDBALLOCCOUNT
- Value
- 40
- Description
- Value used when allocating memory internally for VLDB entry records.
- Name
- BADSERVERID
- Value
- 255
- Description
- Illegal Volume Location Server host ID.
- Name
- MAXSERVERID
- Value
- 30
- Description
- Maximum number of servers appearing in the VLDB.
- Name
- MAXSERVERFLAG
- Value
- 0x80
- Description
- First unused flag value in such fields as serverFlags in struct vldbentry and RepsitesNewFlags in struct VldbUpdateEntry.
- Name
- MAXPARTITIONID
- Value
- 126
- Description
- Maximum number of AFS disk partitions for any one server.
- Name
- MAXBUMPCOUNT
- Value
- 0x7fffffff
- Description
- Maximum interval that the current high-watermark value for a volume ID can be increased in one operation.
- Name
- MAXLOCKTIME
- Value
- 0x7fffffff
- Description
- Maximum number of seconds that any VLDB entry can remain locked.
- Name
- SIZE
- Value
- 1,024
- Description
- Maximum size of the name field within a struct.
Section 3.2.2: Update Entry Bits
- These constants define bit values for the Mask field in the struct VldbUpdateEntry. Specifically, setting these bits is equivalent to declaring that the corresponding field within an object of type struct VldbUpdateEntry has been set. For example, setting the VLUPDATE VOLUMENAME flag in Mask indicates that the name field contains a valid value.
- Name
- VLUPDATE VOLUMENAME
- Value
- 0x0001
- Description
- If set, indicates that the name field is valid.
- Name
- VLUPDATE VOLUMETYPE
- Value
- 0x0002
- Description
- If set, indicates that the volumeType field is valid.
- Name
- VLUPDATE FLAGS
- Value
- 0x0004
- Description
- If set, indicates that the flags field is valid.
- Name
- VLUPDATE READONLYID
- Value
- 0x0008
- Description
- If set, indicates that the ReadOnlyId field is valid.
- Name
- VLUPDATE BACKUPID
- Value
- 0x0010
- Description
- If set, indicates that the BackupId field is valid.
- Name
- VLUPDATE REPSITES
- Value
- 0x0020
- Description
- If set, indicates that the nModifiedRepsites field is valid.
- Name
- VLUPDATE CLONEID
- Value
- 0x0080
- Description
- If set, indicates that the cloneId field is valid.
- Name
- VLUPDATE REPS DELETE
- Value
- 0x0100
- Description
- Is the replica being deleted?
- Name
- VLUPDATE REPS ADD
- Value
- 0x0200
- Description
- Is the replica being added?
- Name
- VLUPDATE REPS MODSERV
- Value
- 0x0400
- Description
- Is the server part of the replica location correct?
- Name
- VLUPDATE REPS MODPART
- Value
- 0x0800
- Description
- Is the partition part of the replica location correct?
- Name
- VLUPDATE REPS MODFLAG
- Value
- 0x1000
- Description
- Various modification flag values.
Section 3.2.3: List-By-Attribute Bits
- These constants define bit values for the Mask field in the struct VldbListByAttributes is to be used in a match. Specifically, setting these bits is equivalent to declaring that the corresponding field within an object of type struct VldbListByAttributes is set. For example, setting the VLLIST SERVER flag in Mask indicates that the server field contains a valid value.
- Name
- VLLIST SERVER
- Value
- 0x1
- Description
- If set, indicates that the server field is valid.
- Name
- VLLIST PARTITION
- Value
- 0x2
- Description
- If set, indicates that the partition field is valid.
- Name
- VLLIST VOLUMETYPE
- Value
- 0x4
- Description
- If set, indicates that the volumetype field is valid.
- Name
- VLLIST VOLUMEID
- Value
- 0x8
- Description
- If set, indicates that the volumeid field is valid.
- Name
- VLLIST FLAG
- Value
- 0x10
- Description
- If set, indicates that that flag field is valid.
Section 3.2.4: Volume Type Indices
- These constants specify the order of entries in the volumeid array in an object of type struct vldbentry. They also identify the three different types of volumes in AFS.
- Name
- RWVOL
- Value
- 0
- Description
- Read-write volume.
- Name
- ROVOL
- Value
- 1
- Description
- Read-only volume.
- Name
- BACKVOL
- Value
- 2
- Description
- Backup volume.
Section 3.2.5: States for struct vlentry
- The following constants appear in the flags field in objects of type struct vlentry. The first three values listed specify the state of the entry, while all the rest stamp the entry with the type of an ongoing volume operation, such as a move, clone, backup, deletion, and dump. These volume operations are the legal values to provide to the voloper parameter of the VL SetLock() interface routine.
- For convenience, the constant VLOP ALLOPERS is defined as the inclusive OR of the above values from VLOP MOVE through VLOP DUMP.
- Name
- VLFREE
- Value
- 0x1
- Description
- Entry is in the free list.
- Name
- VLDELETED
- Value
- 0x2
- Description
- Entry is soft-deleted.
- Name
- VLLOCKED
- Value
- 0x4
- Description
- Advisory lock held on the entry.
- Name
- VLOP MOVE
- Value
- 0x10
- Description
- The associated volume is being moved between servers.
- Name
- VLOP RELEASE
- Value
- 0x20
- Description
- The associated volume is being cloned to its replication sites.
- Name
- VLOP BACKUP
- Value
- 0x40
- Description
- A backup volume is being created for the associated volume.
- Name
- VLOP DELETE
- Value
- 0x80
- Description
- The associated volume is being deleted.
- Name
- VLOP DUMP
- Value
- 0x100
- Description
- A dump is being taken of the associated volume.
Section 3.2.6: States for struct vldbentry
- Of the following constants, the first three appear in the flags field within an object of type struct vldbentry, advising of the existence of the basic volume types for the given volume, and hence the validity of the entries in the volumeId array field. The rest of the values provided in this table appear in the serverFlags array field, and apply to the instances of the volume appearing in the various replication sites.
- This structure appears in numerous Volume Location Server interface calls, namely VL CreateEntry(), VL GetEntryByID(), VL GetEntryByName(), VL ReplaceEntry() and VL ListEntry().
- Name
- VLF RWEXISTS
- Value
- 0x1000
- Description
- The read-write volume ID is valid.
- Name
- VLF ROEXISTS
- Value
- 0x2000
- Description
- The read-only volume ID is valid.
- Name
- VLF BACKEXISTS
- Value
- 0x4000
- Description
- The backup volume ID is valid.
- Name
- VLSF NEWREPSITE
- Value
- 0x01
- Description
- Not used; originally intended to mark an entry as belonging to a partially-created volume instance.
- Name
- VLSF ROVOL
- Value
- 0x02
- Description
- A read-only version of the volume appears at this server.
- Name
- VLSF RWVOL
- Value
- 0x02
- Description
- A read-write version of the volume appears at this server.
- Name
- VLSF BACKVOL
- Value
- 0x08
- Description
- A backup version of the volume appears at this server.
Section 3.2.7: ReleaseType Argument Values
- The following values are used in the ReleaseType argument to various Volume Location Server interface routines, namely VL ReplaceEntry(), VL UpdateEntry() and VL ReleaseLock().
- Name
- LOCKREL TIMESTAMP
- Value
- 1
- Description
- Is the LockTimestamp field valid?
- Name
- LOCKREL OPCODE
- Value
- 2
- Description
- Are any of the bits valid in the flags field?
- Name
- LOCKREL AFSID
- Value
- 4
- Description
- Is the LockAfsId field valid?
Section 3.2.8: Miscellaneous
- Miscellaneous values.
- Name
- VLREPSITE NEW
- Value
- 1
- Description
- Has a replication site gotten a new release of a volume?
- A synonym for this constant is VLSF NEWREPSITE.
Section 3.3: Structures and Typedefs
- This section describes the major exported Volume Location Server data structures of interest to application programmers, along with the typedefs based upon those structures.
Section 3.3.1: struct vldbentry
- This structure represents an entry in the VLDB as made visible to Volume Location Server clients. It appears in numerous Volume Location Server interface calls, namely VL CreateEntry(), VL GetEntryByID(), VL GetEntryByName(), VL ReplaceEntry() and VL ListEntry().
Fields
- char name[] - The string name for the volume, with a maximum length of MAXNAMELEN (65) characters, including the trailing null.
- long volumeType - The volume type, one of RWVOL, ROVOL, or BACKVOL.
- long nServers - The number of servers that have an instance of this volume.
- long serverNumber[] - An array of indices into the table of servers, identifying the sites holding an instance of this volume. There are at most MAXNSERVERS (8) of these server sites allowed by the Volume Location Server.
- long serverPartition[] - An array of partition identifiers, corresponding directly to the serverNumber array, specifying the partition on which each of those volume instances is located. As with the serverNumber array, serverPartition has up to MAXNSERVERS (8) entries.
- long serverFlags[] - This array holds one flag value for each of the servers in the previous arrays. Again, there are MAXNSERVERS (8) slots in this array.
- u long volumeId[] - An array of volume IDs, one for each volume type. There are MAXTYPES slots in this array.
- long cloneId - This field is used during a cloning operation.
- long flags - Flags concerning the status of the fields within this structure; see Section 3.2.6 for the bit values that apply.
Section 3.3.2: struct vlentry
- This structure is used internally by the Volume Location Server to fully represent a VLDB entry. The client-visible struct vldbentry represents merely a subset of the information contained herein.
Fields
- u long volumeId[] - An array of volume IDs, one for each of the MAXTYPES of volume types.
- long flags - Flags concerning the status of the fields within this structure; see Section 3.2.6 for the bit values that apply.
- long LockAfsId - The individual who locked the entry. This feature has not yet been implemented.
- long LockTimestamp - Time stamp on the entry lock.
- long cloneId - This field is used during a cloning operation.
- long AssociatedChain - Pointer to the linked list of associated VLDB entries.
- long nextIdHash[] - Array of MAXTYPES next pointers for the ID hash table pointer, one for each related volume ID.
- long nextNameHash - Next pointer for the volume name hash table.
- long spares1[] - Two longword spare fields.
- char name[] - The volume's string name, with a maximum of MAXNAMELEN (65) characters, including the trailing null.
- u char volumeType - The volume's type, one of RWVOL, ROVOL, or BACKVOL.
- u char serverNumber[] - An array of indices into the table of servers, identifying the sites holding an instance of this volume. There are at most MAXNSERVERS (8) of these server sites allowed by the Volume Location Server.
- u char serverPartition[] - An array of partition identifiers, corresponding directly to the serverNumber array, specifying the partition on which each of those volume instances is located. As with the serverNumber array, serverPartition has up to MAXNSERVERS (8) entries.
- u char serverFlags[] - This array holds one flag value for each of the servers in the previous arrays. Again, there are MAXNSERVERS (8) slots in this array.
- u char RefCount - Only valid for read-write volumes, this field serves as a reference count, basically the number of dependent children volumes.
- char spares2[] - This field is used for 32-bit alignment.
Section 3.3.3: struct vital vlheader
- This structure defines the leading section of the VLDB header, of type struct vlheader. It contains frequently-used global variables and general statistics information.
Fields
- long vldbversion - The VLDB version number. This field must appear first in the structure.
- long headersize - The total number of bytes in the header.
- long freePtr - Pointer to the first free enry in the free list, if any.
- long eofPtr - Pointer to the first free byte in the header file.
- long allocs - The total number of calls to the internal AllocBlock() function directed at this file.
- long frees - The total number of calls to the internal FreeBlock() function directed at this file.
- long MaxVolumeId - The largest volume ID ever granted for this cell.
- long totalEntries[] - The total number of VLDB entries by volume type in the VLDB. This array has MAXTYPES slots, one for each volume type.
Section 3.3.4: struct vlheader
- This is the layout of the information stored in the VLDB header. Notice it includes an object of type struct vital vlheader described above (see Section 3.3.3) as the first field.
Fields
- struct vital vlheader vital header - Holds critical VLDB header information.
- u long IpMappedAddr[] - Keeps MAXSERVERID+1 mappings of IP addresses to relative ones.
- long VolnameHash[] - The volume name hash table, with HASHSIZE slots.
- long VolidHash[][] - The volume ID hash table. The first dimension in this array selects which of the MAXTYPES volume types is desired, and the second dimension actually implements the HASHSIZE hash table buckets for the given volume type.
Section 3.3.5: struct VldbUpdateEntry
- This structure is used as an argument to the VL UpdateEntry() routine (see Section 3.6.7). Please note that multiple entries can be updated at once by setting the appropriate Mask bits. The bit values for this purpose are defined in Section 3.2.2.
Fields
- u long Mask - Bit values determining which fields are to be affected by the update operation.
- char name[] - The volume name, up to MAXNAMELEN (65) characters including the trailing null.
- long volumeType - The volume type.
- long flags - This field is used in conjuction with Mask (in fact, one of the Mask bits determines if this field is valid) to choose the valid fields in this record.
- u long ReadOnlyId - The read-only ID.
- u long BackupId - The backup ID.
- long cloneId - The clone ID.
- long nModifiedRepsites - Number of replication sites whose entry is to be changed as below.
- u long RepsitesMask[] - Array of bit masks applying to the up to MAXNSERVERS (8) replication sites involved.
- long RepsitesTargetServer[] - Array of target servers for the operation, at most MAXNSERVERS (8) of them.
- long RepsitesTargetPart[] - Array of target server partitions for the operation, at most MAXNSERVERS (8) of them.
- long RepsitesNewServer[] - Array of new server sites, at most MAXNSERVERS (8) of them.
- long RepsitesNewPart[] - Array of new server partitions for the operation, at most MAXNSERVERS (8) of them.
- long RepsitesNewFlags[] - Flags applying to each of the new sites, at most MAXNSERVERS (8) of them.
Section 3.3.6: struct VldbListByAttributes
- This structure is used by the VL ListAttributes() routine (see Section 3.6.11).
Fields
- u long Mask - Bit mask used to select the following attribute fields on which to match.
- long server - The server address to match.
- long partition - The partition ID to match.
- long volumetype - The volume type to match.
- long volumeid - The volume ID to match.
- long flag - Flags concerning these values.
Section 3.3.7: struct single vldbentry
- This structure is used to construct the vldblist object (See Section 3.3.12), which basically generates a queueable (singly-linked) version of struct vldbentry.
Fields
- vldbentry VldbEntry - The VLDB entry to be queued.
- vldblist next vldb - The next pointer in the list.
Section 3.3.8: struct vldb list
- This structure defines the item returned in linked list form from the VL LinkedList() function (see Section 3.6.12). This same object is also returned in bulk form in calls to the VL ListAttributes() routine (see Section 3.6.11).
Fields
- vldblist node - The body of the first object in the linked list.
Section 3.3.9: struct vldstats
- This structure defines fields to record statistics on opcode hit frequency. The MAX NUMBER OPCODES constant has been defined as the maximum number of opcodes supported by this structure, and is set to 30.
Fields
- unsigned long start time - Clock time when opcode statistics were last cleared.
- long requests[] - Number of requests received for each of the MAX NUMBER OPCODES opcode types.
- long aborts[] - Number of aborts experienced for each of the MAX NUMBER OPCODES opcode types.
- long reserved[] - These five longword fields are reserved for future use.
Section 3.3.10: bulk
typedef opaque bulk<DEFAULTBULK>;
- This typedef may be used to transfer an uninterpreted set of bytes across the Volume Location Server interface. It may carry up to DEFAULTBULK (10,000) bytes.
Fields
- bulk len - The number of bytes contained within the data pointed to by the next field.
- bulk val - A pointer to a sequence of bulk len bytes.
Section 3.3.11: bulkentries
typedef vldbentry bulkentries<>;
- This typedef is used to transfer an unbounded number of struct vldbentry objects. It appears in the parameter list for the VL ListAttributes() interface function.
Fields
- bulkentries len - The number of vldbentry structures contained within the data pointed to by the next field.
- bulkentries val - A pointer to a sequence of bulkentries len vldbentry structures.
Section 3.3.12: vldblist
typedef struct single_vldbentry *vldblist;
- This typedef defines a queueable struct vldbentry object, referenced by the single vldbentry typedef as well as struct vldb list.
Section 3.3.13: vlheader
typedef struct vlheader vlheader;
- This typedef provides a short name for objects of type struct vlheader (see Section 3.3.4).
Section 3.3.14: vlentry
typedef struct vlentry vlentry;
- This typedef provides a short name for objects of type struct vlentry (see Section 3.3.2).
Section 3.4: Error Codes
- This section covers the set of error codes exported by the Volume Location Server, displaying the printable phrases with which they are associated.
- Name
- VL IDEXIST
- Value
- (363520L)
- Description
- Volume Id entry exists in vl database.
- Name
- VL IO
- Value
- (363521L)
- Description
- I/O related error.
- Name
- VL NAMEEXIST
- Value
- (363522L)
- Description
- Volume name entry exists in vl database.
- Name
- VL CREATEFAIL
- Value
- (363523L)
- Description
- Internal creation failure.
- Name
- VL NOENT
- Value
- (363524L)
- Description
- No such entry.
- Name
- VL EMPTY
- Value
- (363525L)
- Description
- Vl database is empty.
- Name
- VL ENTDELETED
- Value
- (363526L)
- Description
- Entry is deleted (soft delete).
- Name
- VL BADNAME
- Value
- (363527L)
- Description
- Volume name is illegal.
- Name
- VL BADINDEX
- Value
- (363528L)
- Description
- Index is out of range.
- Name
- VL BADVOLTYPE
- Value
- (363529L)
- Description
- Bad volume range.
- Name
- VL BADSERVER
- Value
- (363530L)
- Description
- Illegal server number (out of range).
- Name
- VL BADPARTITION
- Value
- (363531L)
- Description
- Bad partition number.
- Name
- VL REPSFULL
- Value
- (363532L)
- Description
- Run out of space for Replication sites.
- Name
- VL NOREPSERVER
- Value
- (363533L)
- Description
- No such Replication server site exists.
- Name
- VL DUPREPSERVER
- Value
- (363534L)
- Description
- Replication site already exists.
- Name
- RL RWNOTFOUND
- Value
- (363535L)
- Description
- Parent R/W entry not found.
- Name
- VL BADREFCOUNT
- Value
- (363536L)
- Description
- Illegal Reference Count number.
- Name
- VL SIZEEXCEEDED
- Value
- (363537L)
- Description
- Vl size for attributes exceeded.
- Name
- VL BADENTRY
- Value
- (363538L)
- Description
- Bad incoming vl entry.
- Name
- VL BADVOLIDBUMP
- Value
- (363539L)
- Description
- Illegal max volid increment.
- Name
- VL IDALREADYHASHED
- Value
- (363540L)
- Description
- RO/BACK id already hashed.
- Name
- VL ENTRYLOCKED
- Value
- (363541L)
- Description
- Vl entry is already locked.
- Name
- VL BADVOLOPER
- Value
- (363542L)
- Description
- Bad volume operation code.
- Name
- VL BADRELLOCKTYPE
- Value
- (363543L)
- Description
- Bad release lock type.
- Name
- VL RERELEASE
- Value
- (363544L)
- Description
- Status report: last release was aborted.
- Name
- VL BADSERVERFLAG
- Value
- (363545L)
- Description
- Invalid replication site server flag.
- Name
- VL PERM
- Value
- (363546L)
- Description
- No permission access.
- Name
- VL NOMEM
- Value
- (363547L)
- Description
- malloc(realloc) failed to alloc enough memory.
Section 3.5: Macros
- The Volume Location Server defines a small number of macros, as described in this section. They are used to update the internal statistics variables and to compute offsets into character strings. All of these macros really refer to internal operations, and strictly speaking should not be exposed in this interface.
Section 3.5.1: COUNT REQ()
#define COUNT_REQ(op)
static int this_op = op-VL_LOWEST_OPCODE;
dynamic_statistics.requests[this_op]++
- Bump the appropriate entry in the variable maintaining opcode usage statistics for the Volume Location Server. Note that a static variable is set up to record this op, namely the index into the opcode monitoring array. This static variable is used by the related COUNT ABO() macro defined below.
Section 3.5.2: COUNT ABO()
#define COUNT_ABO dynamic_statistics.aborts[this_op]++
- Bump the appropriate entry in the variable maintaining opcode abort statistics for the Volume Location Server. Note that this macro does not take any arguemnts. It expects to find a this op variable in its environment, and thus depends on its related macro, COUNT REQ() to define that variable.
Section 3.5.3: DOFFSET()
#define DOFFSET(abase, astr, aitem) ((abase)+(((char *)(aitem)) -((char
*)(astr))))
- Compute the byte offset of charcter object aitem within the enclosing object astr, also expressed as a character-based object, then offset the resulting address by abase. This macro is used ot compute locations within the VLDB when actually writing out information.
Section 3.6: Functions
- This section covers the Volume Location Server RPC interface routines. The majority of them are generated from the vldbint.xg Rxgen file, and are meant to be used by user-space agents. There is also a subset interface definition provided in the afsvlint.xg Rxgen file. These routines, described in Section 3.7, are meant to be used by a kernel-space agent when dealing with the Volume Location Server; in particular, they are called by the Cache Manager.
Section 3.6.1: VL CreateEntry - Create a VLDB
entry
int VL CreateEntry(IN struct rx connection *z conn,
IN vldbentry *newentry)
- Description
- This function creates a new entry in the VLDB, as specified in the newentry argument. Both the name and numerical ID of the new volume must be unique (e.g., it must not already appear in the VLDB). For non-read-write entries, the read-write parent volume is accessed so that its reference count can be updated, and the new entry is added to the parent's chain of associated entries. The VLDB is write-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function. VL NAMEEXIST The volume name already appears in the VLDB. VL CREATEFAIL Space for the new entry cannot be allocated within the VLDB. VL BADNAME The volume name is invalid. VL BADVOLTYPE The volume type is invalid. VL BADSERVER The indicated server information is invalid. VL BADPARTITION The indicated partition information is invalid. VL BADSERVERFLAG The server flag field is invalid. VL IO An error occurred while writing to the VLDB.
Section 3.6.2: VL DeleteEntry - Delete a VLDB
entry
int VL DeleteEntry(IN struct rx connection *z conn,
IN long Volid,
IN long voltype)
- Description
- Delete the entry matching the given volume identifier and volume type as specified in the Volid and voltype arguments. For a read-write entry whose reference count is greater than 1, the entry is not actually deleted, since at least one child (read-only or backup) volume still depends on it. For cases of non-read-write volumes, the parent's reference count and associated chains are updated.
- If the associated VLDB entry is already marked as deleted (i.e., its flags field has the VLDELETED bit set), then no further action is taken, and VL ENTDELETED is returned. The VLDB is write-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function. VL BADVOLTYPE An illegal volume type has been specified by the voltype argument. VL NOENT This volume instance does not appear in the VLDB. VL ENTDELETED The given VLDB entry has already been marked as deleted. VL IO An error occurred while writing to the VLDB.
Section 3.6.3: VL GetEntryByID - Get VLDB entry by
volume ID/type
int VL GetEntryByID(IN struct rx connection *z conn, IN long Volid, IN long
voltype, OUT vldbentry *entry)
- Description
- Given a volume's numerical identifier (Volid) and type (voltype), return a pointer to the entry in the VLDB describing the given volume instance.
- The VLDB is read-locked for the duration of this operation.
- Error Codes
- VL BADVOLTYPE An illegal volume type has been specified by the voltype argument.
VL NOENT This volume instance does not appear in the VLDB.
VL ENTDELETED The given VLDB entry has already been marked as deleted.
Section 3.6.4: VL GetEntryByName - Get VLDB entry
by volume name
int VL GetEntryByName(IN struct rx connection *z conn,
IN char *volumename,
OUT vldbentry *entry)
- Description
- Given the volume name in the volumename parameter, return a pointer to the entry in the VLDB describing the given volume. The name in volumename may be no longer than MAXNAMELEN (65) characters, including the trailing null. Note that it is legal to use the volume's numerical identifier (in string form) as the volume name.
- The VLDB is read-locked for the duration of this operation.
- This function is closely related to the VL GetEntryByID() routine, as might be expected. In fact, the by-ID routine is called if the volume name provided in volumename is the string version of the volume's numerical identifier.
- Error Codes
- VL BADVOLTYPE An illegal volume type has been specified by the voltype argument.
VL NOENT This volume instance does not appear in the VLDB.
VL ENTDELETED The given VLDB entry has already been marked as deleted.
VL BADNAME The volume name is invalid.
Section 3.6.5: VL GetNewVolumeId - Generate a new
volume ID
int VL GetNewVolumeId(IN struct rx connection *z conn,
IN long bumpcount,
OUT long *newvolumid)
- Description
- Acquire bumpcount unused, consecutively-numbered volume identifiers from the Volume Location Server. The lowest-numbered of the newly-acquired set is placed in the newvolumid argument. The largest number of volume IDs that may be generated with any one call is bounded by the MAXBUMPCOUNT constant defined in Section 3.2.1. Currently, there is (effectively) no restriction on the number of volume identifiers that may thus be reserved in a single call.
- The VLDB is write-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function.
VL BADVOLIDBUMP The value of the bumpcount parameter exceeds the system limit of MAXBUMPCOUNT.
VL IO An error occurred while writing to the VLDB.
Section 3.6.6: VL ReplaceEntry - Replace entire
contents of VLDB entry
int VL ReplaceEntry(IN struct rx connection *z conn,
IN long Volid,
IN long voltype,
IN vldbentry *newentry,
IN long ReleaseType)
- Description
- Perform a wholesale replacement of the VLDB entry corresponding to the volume instance whose identifier is Volid and type voltype with the information contained in the newentry argument. Individual VLDB entry fields cannot be selectively changed while the others are preserved; VL UpdateEntry() should be used for this objective. The permissible values for the ReleaseType parameter are defined in Section 3.2.7.
- The VLDB is write-locked for the duration of this operation. All of the hash tables impacted are brought up to date to incorporate the new information.
- Error Codes
- VL PERM The caller is not authorized to execute this function.
VL BADVOLTYPE An illegal volume type has been specified by the voltype argument.
VL BADRELLOCKTYPE An illegal release lock has been specified by the ReleaseType argument.
VL NOENT This volume instance does not appear in the VLDB.
VL BADENTRY An attempt was made to change a read-write volume ID.
VL IO An error occurred while writing to the VLDB.
Section 3.6.7: VL UpdateEntry - Update contents of
VLDB entry
int VL UpdateEntry(IN struct rx connection *z conn,
IN long Volid,
IN long voltype,
IN VldbUpdateEntry *UpdateEntry,
IN long ReleaseType)
- Description
- Update the VLDB entry corresponding to the volume instance whose identifier is Volid and type voltype with the information contained in the UpdateEntry argument. Most of the entry's fields can be modified in a single call to VL UpdateEntry(). The Mask field within the UpdateEntry parameter selects the fields to update with the values stored within the other UpdateEntry fields. Permissible values for the ReleaseType parameter are defined in Section 3.2.7.
- The VLDB is write-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function.
VL BADVOLTYPE An illegal volume type has been specified by the voltype argument.
VL BADRELLOCKTYPE An illegal release lock has been specified by the ReleaseType argument.
VL NOENT This volume instance does not appear in the VLDB.
VL IO An error occurred while writing to the VLDB.
Section 3.6.8: VL SetLock - Lock VLDB entry
int VL SetLock(IN struct rx connection *z conn,
IN long Volid,
IN long voltype,
IN long voloper)
- Description
- Lock the VLDB entry matching the given volume ID (Volid) and type (voltype) for volume operation voloper (e.g., VLOP MOVE and VLOP RELEASE). If the entry is currently unlocked, then its LockTimestamp will be zero. If the lock is obtained, the given voloper is stamped into the flags field, and the LockTimestamp is set to the time of the call. When the caller attempts to lock the entry for a release operation, special care is taken to abort the operation if the entry has already been locked for this operation, and the existing lock has timed out. In this case, VL SetLock() returns VL RERELEASE.
- The VLDB is write-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function.
VL BADVOLTYPE An illegal volume type has been specified by the voltype argument.
VL BADVOLOPER An illegal volume operation was specified in the voloper argument. Legal values are defined in the latter part of the table in Section 3.2.5.
VL ENTDELETED The given VLDB entry has already been marked as deleted.
VL ENTRYLOCKED The given VLDB entry has already been locked (which has not yet timed out).
VL RERELEASE A VLDB entry locked for release has timed out, and the caller also wanted to perform a release operation on it.
VL IO An error was experienced while attempting to write to the VLDB.
Section 3.6.9: VL ReleaseLock - Unlock VLDB entry
int VL ReleaseLock(IN struct rx connection *z conn,
IN long Volid,
IN long voltype,
IN long ReleaseType)
- Description
- Unlock the VLDB entry matching the given volume ID (Volid) and type (voltype). The ReleaseType argument determines which VLDB entry fields from flags and LockAfsId will be cleared along with the lock timestamp in LockTimestamp. Permissible values for the ReleaseType parameter are defined in Section 3.2.7.
- The VLDB is write-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function.
VL BADVOLTYPE An illegal volume type has been specified by the voltype argument.
VL BADRELLOCKTYPE An illegal release lock has been specified by the ReleaseType argument.
VL NOENT This volume instance does not appear in the VLDB.
VL ENTDELETED The given VLDB entry has already been marked as deleted.
VL IO An error was experienced while attempting to write to the VLDB.
Section 3.6.10: VL ListEntry - Get contents of
VLDB via index
int VL ListEntry(IN struct rx connection *z conn,
IN long previous index,
OUT long *count,
OUT long *next index,
OUT vldbentry *entry)
- Description
- This function assists in the task of enumerating the contents of the VLDB. Given an index into the database, previous index, this call return the single VLDB entry at that offset, placing it in the entry argument. The number of VLDB entries left to list is placed in count, and the index of the next entry to request is returned in next index. If an illegal index is provided, count is set to -1.
- The VLDB is read-locked for the duration of this operation.
- Error Codes
- ---None.
Section 3.6.11: VL ListAttributes - List all VLDB
entry matching given attributes, single return object
int VL ListAttributes(IN struct rx connection *z conn,
IN VldbListByAttributes *attributes,
OUT long *nentries,
OUT bulkentries *blkentries)
- Description
- Retrieve all the VLDB entries that match the attributes listed in the attributes parameter, placing them in the blkentries object. The number of matching entries is placed in nentries. Matching can be done by server number, partition, volume type, flag, or volume ID. The legal values to use in the attributes argument are listed in Section 3.2.3. Note that if the VLLIST VOLUMEID bit is set in attributes, all other bit values are ignored and the volume ID provided is the sole search criterion.
- The VLDB is read-locked for the duration of this operation.
- Note that VL ListAttributes() is a potentially expensive function, as sequential search through all of the VLDB entries is performed in most cases.
- Error Codes
- VL NOMEM Memory for the blkentries object could not be allocated.
VL NOENT This specified volume instance does not appear in the VLDB.
VL SIZEEXCEEDED Ran out of room in the blkentries object.
VL IO Error while reading from the VLDB.
Section 3.6.12: VL LinkedList - List all VLDB
entry matching given attributes, linked list return object
int VL LinkedList(IN struct rx connection *z conn,
IN VldbListByAttributes *attributes,
OUT long *nentries,
OUT vldb list *linkedentries)
- Description
- Retrieve all the VLDB entries that match the attributes listed in the attributes parameter, creating a linked list of entries based in the linkedentries object. The number of matching entries is placed in nentries. Matching can be done by server number, partition, volume type, flag, or volume ID. The legal values to use in the attributes argument are listed in Section 3.2.3. Note that if the VLLIST VOLUMEID bit is set in attributes, all other bit values are ignored and the volume ID provided is the sole search criterion.
- The VL LinkedList() function is identical to the VL ListAttributes(), except for the method of delivering the VLDB entries to the caller.
- The VLDB is read-locked for the duration of this operation.
- Error Codes
- VL NOMEM Memory for an entry in the list based at linkedentries object could not be allocated.
VL NOENT This specified volume instance does not appear in the VLDB.
VL SIZEEXCEEDED Ran out of room in the current list object.
VL IO Error while reading from the VLDB.
Section 3.6.13: VL GetStats - Get Volume Location
Server statistics
int VL GetStats(IN struct rx connection *z conn,
OUT vldstats *stats,
OUT vital vlheader *vital header)
- Description
- Collect the different types of VLDB statistics. Part of the VLDB header is returned in vital header, which includes such information as the number of allocations and frees performed, and the next volume ID to be allocated. The dynamic per-operation stats are returned in the stats argument, reporting the number and types of operations and aborts.
- The VLDB is read-locked for the duration of this operation.
- Error Codes
- VL PERM The caller is not authorized to execute this function.
Section 3.6.14: VL Probe - Verify Volume Location
Server connectivity/status
int VL Probe(IN struct rx connection *z conn)
- Description
- This routine serves a 'pinging' function to determine whether the Volume Location Server is still running. If this call succeeds, then the Volume Location Server is shown to be capable of responding to RPCs, thus confirming connectivity and basic operation.
- The VLDB is not locked for this operation.
- Error Codes
- ---None.
Section 3.7: Kernel Interface Subset
- The interface described by this document so far applies to user-level clients, such as the vos utility. However, some volume location operations must be performed from within the kernel. Specifically, the Cache Manager must find out where volumes reside and otherwise gather information about them in order to conduct its business with the File Servers holding them. In order to support Volume Location Server interconnection for agents operating within the kernel, the afsvlint.xg Rxgen interface was built. It is a minimal subset of the user-level vldbint.xg definition. Within afsvlint.xg, there are duplicate definitions for such constants as MAXNAMELEN, MAXNSERVERS, MAXTYPES, VLF RWEXISTS, VLF ROEXISTS, VLF BACKEXISTS, VLSF NEWREPSITE, VLSF ROVOL, VLSF RWVOL, and VLSF BACKVOL. Since the only operations the Cache Manager must perform are volume location given a specific volume ID or name, and to find out about unresponsive Volume Location Servers, the following interface routines are duplicated in afsvlint.xg, along with the struct vldbentry declaration:
- VL GetEntryByID()
- VL GetEntryByName()
- VL Probe()