Download SDK 5.0 User Manual - grass valley developers

Cartridge functions
Cartridge functions
PlsConnectCartridge binds a cartridge label to a handle for a cartridge. This binding is
always immediate so the command executes synchronously. An application can request a
cartridge handle for a cartridge it has reserved. The library server identifies who has reserved
the cartridge by comparing library handles. Multiple handles can be open to the same
cartridge.
PlsAllocateCartridge reserves a cartridge. Cartridges are reserved by label instead of a
cartridge handle so the acquisition of a cartridge and its reservation are an atomic action. It is
assumed this command will be used to reserve cartridges for short periods of time in near real
time applications.
PlsCloseCartridge releases and recycles a cartridge handle. It should be used when the
cartridge associated with the handle is no longer needed.
PlsGetCartridgeConfig returns a structure with information about a specific cartridge. This
command will draw an error if the cartridge handle is for a cartridge category.
PlsGetCartridgeStatus requests status information for a given tape cartridge. The
information returned is the same as the cartridge information commands
(PlsFindFirstCartridgeInfo).
PlsGetPartitionMap finds the free space in one or more partitions. The user may specify the
starting partition number and the number of values to be returned. The maximum number of
returned values is limited to PlsPartMapSize. If the starting partition number is 0, the value
returned is the space allocated to the tape directory partition. If the tape is not partitioned, the
directory size is returned as 0. If the starting partition value is greater than the number of
partitions on the tape, an error is returned. If the starting partition number plus the number of
partitions is greater than the number of partitions on the tape, the number of returned values
is limited to the actual partitions on the given cartridge. In the current implementation, the
directory partition size and data partition’s free space can’t be acquired in a single command.
The returned partition size information is a vector of not more than PlsPartMapSize values.
The size entries are 32 bit integers in units of megabytes. The function will return the number
of partitions and map vector during a synchronous function call as parameters, or with the
command completion event for a concurrent command execution.
PlsInventoryCartridge updates the inventory (read the directory) for a given cartridge and
update the local catalog. Operators can use this command when they think the local or master
catalog and the actual contents of a cartridge are not in agreement.
PlsUpdateCartridge forces directory updates on a cartridge. Delete and Rename will make
entries in a local catalog and not update a cartridge directory until the cartridge is loaded into
a transport. Exactly how and when tape directory updates are accomplished is not specified,
with two exceptions. Cartridge directories are always updated by a PlsUpdateCartridge
command and by an Export Cartridge (if “forget” is not specified.) This command can be used
to force cartridge directory updates when a tape may not be used for a long period of time.
PlsFormatCartridge formats a cartridge for later use. The cartridge label must be provided
to insure the correct cartridge is formatted. In systems without barcode readers (stand-alone
transports) no verification of the label can be performed. The cartridge master directory
records the barcode label at the time the cartridge is formatted. The value of the cartridge
barcode label stored on the tape is used as a hint only. The machine-readable barcode label is
always considered to be the correct cartridge label. The data partition size is in megabytes.
The cartridge is divided into as many equal-sized partitions as possible. If the partition size
Preliminary — 12 July 2001
Profile Software Development Kit User
143