Chapter 3: Volume Location Server Interface

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