Get data cartridges

Request syntax

Path parameters

volser (string)

The volume serial number (VOLSER) or bar code number of the cartridge.

internalAddress (string)

The unique identifier of the cartridge within the library represented by a 6-character hex string. If there are duplicate VOLSERs, this value is used to identify the cartridge. The value changes if the cartridge is assigned or unassigned from a logical library or if the cartridge is moved by the host or library. Query the value before you use.

Example

> GET /v1/dataCartridges
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 33330

[
     {
          "volser": "SG1122L2", 
          "state": "normal", 
          "accessible":"normal"
          "location": "slot_F1C6R13T0", 
          "mediaType": "LTO",
          "type": "L8",
          "typeDescription": "LTO-8",
          "vendor": "IBM",
          "manufactureDate": "2022-01-28",
          "sn": "EVCXX0DNRP",
          "worm": "false",
          "format": "LTO-8 Type M",
          "density": "U-832M",
          "densityCode": "5D",
          "nativeCapacity": 9000,
          "encrypted": "yes",
          "mostRecentVerification": "2019-03-01T03:44:07-0700",
          "nextVerification": "2019-03-29T11:12:04-0700",
          "mostRecentUsage": "2019-03-25T13:33:58-0700",
          "logicalLibrary": "myLL2",
          "elementAddress": 1025,
          "internalAddress": "030403",
          "lifetimeRemaining": 83
     }, {
          . . .
     }
]

Attributes

volser (string)

The volume serial number (VOLSER) or bar code number of the cartridge.

state (string)

The health status of the data cartridge. The following values are included in order of priority:

Table 1.

State	Description
unknown	The state recorded by firmware for this resource is unknown. Reset the LCC node card and contact IBM for support if issue persists.
failedVerification	The cartridge failed last verification. You may need to migrate the data to another cartridge.
atEndOfLife	The cartridge has 0% useful life remaining and may no longer be covered by warranty. Migrate data to another cartridge.
assignmentRequired	The cartridge is in a slot but is unassigned to a logical library because an empty import/export element (IEE) address is not currently available for assignment. The cartridge must be manually assigned to the logical library or removed from the library.
uncertainBarcode	Possible mismatch between a scanned bar code label and the copy of the bar code stored on cartridge memory. The library will try to resolve on the next mount/demount cycle of this cartridge. If issue persists, contact IBM Support.
exportQueued	The cartridge is queued to be moved to an I/O station.
importing	The cartridge is being imported. The import is complete when the host application performs a move of the cartridge.
verifying	Verification in a media verification drive in progress.
lifetimeRemaining	The percentage of useful life remaining for the cartridge
normal	The cartridge status is normal.

accessible (string)

Indicates whether the cartridge is accessible by all accessors or not. Values include normal when all installed accessors have normal access to the cartridge as defined by the elastic capacity library setting, limited when one accessor in a dual-accessor library is unable to reach the cartridge due to errors, and no when none of the installed accessors can reach the drive due to errors.

location (string)

The current location of the cartridge. This is the location of a gripper, drive, slot, or I/O slot.

mediaType (string)

The media type of the cartridge. Supported values include 3592 and LTO.

type (string)

The 2-character at the end of the VOLSER on the bar code label that describes what type of cartridge this is. For LTO media types, this is one of "LA", "L9", "LZ", "L8", "LY", "M8", "L7", "LX", "L6", "LW", "L5", "LV", "L4", "LU", "L3", or "LT". For 3592 media types, this is one of "JB”, "JC", "JD", "JE", "JK", "JL", "JV", "JM", "JX", "JY", "JZ", or "JF".

typeDescription (string)

The unique description of the cartridge type.

vendor (string)

The name of the vendor of this tape cartridge.

manufactureDate (string)

The date the cartridge was manufactured.

sn (string)

The serial number of the cartridge defined by the manufacturer.

worm (string)

This is “true” if this is a WORM cartridge and “false” if there is no innate write restriction built into this cartridge.

format (string)

The format of the cartridge media which determines its data density and thus its native capacity. For 3592 media types, this is one of “3592 J1A (J1A)”, “TS1120 (E05)”, “TS1130 (E06)”, “TS1140 (E07)”, “TS1150 (E08)”, “TS1155 (55F)”, “TS1160 (60F)”, or “TS1170 (70F)”. For LTO media types, this is one of “LTO-3”, “LTO-4”, “LTO-5”, “LTO-6”, “LTO-7”, “LTO-8 Type M”, “LTO-8”, “LTO-9”, or "LTO-10".

density (string)

The density setting of the cartridge media as determined by its format. There is one unique density identifier for each format.

densityCode (string)

A hex string surfaced by the drive to hosts that describes the density of the media as determined by its format.

nativeCapacity (string)

The uncompressed native capacity of the cartridge in gigabytes (GB). This is determined by a combination of cartridge type and format.

encrypted (string)

The state of encryption on the cartridge. If yes, the data on the cartridge is encrypted and if no, the data on the cartridge is not encrypted. If the cartridge has not been mounted, this is null.

mostRecentVerification (string)

The last date and time this cartridge was verified by using media verification in a drive, which was assigned as a media verification drive. If media verification was not run on this cartridge, it returns null.

nextVerification (string)

The date and time media verification will be or was queued to automatically run on this cartridge. After the media verification is queued, this value will remain the same until the verification is performed. If automatic media verification is not enabled for this logical library, null is returned.

mostRecentUsage(string)

The last date and time this cartridge was mounted into a drive, or null if this is unknown or the cartridge has not been mounted. Time format is YYYY-MM-DDThh:mm:ss±hh:mm

logicalLibrary (string)

The name of the logical library this cartridge is assigned to. This cartridge is accessible only to drives that are also assigned to this logical library. If it is not assigned to a logical library, this is null.

elementAddress (number)

The SCSI element address of the cartridge. This value is reported to hosts via the Read Element Status SCSI command. If not yet reported to host, this is null.

internalAddress (string)

The unique identifier of the cartridge within the library represented by a 6-character hex string. If there are duplicate VOLSERs, this value is used to identify the cartridge. The value changes if the cartridge is assigned or unassigned from a logical library or if the cartridge is moved by the host or library. Query the value before you use.

lifetimeRemaining (number)

Indicates the estimated percentage of cartridge media life remaining based on overall usage of this cartridge. When this reaches 0%, the cartridge is at risk of data loss, may not be covered by warranty, and should be migrated to another cartridge. This factors in motionMeters, mounts, and dataWrittenToCartridge among other internal factors. The exact calculation varies depending on cartridge format and type. This value is null if this is unknown.