Chapter 9 CDM Message Types

The purpose of this chapter is to provide CDMs with the following:

A comprehensive reference for the types of CDM messages (packaged in the CDMMessageStruct described in Chapter 5) that a CDM can expect to receive. Additionally, this reference outlines how a CDM should interpret the contents of each data field in the CDMMessageStruct so that it can properly build a corresponding HACB request.

A list of valid Media Manager completion codes used in completing a HACB at the end of its request cycle. These completion codes are passed to the Media Manager through CDI_Complete_Message().

9.1 Control Functions (0x0000 - 0x001F)

This section lists the CDM messages that identify Media Manager control functions.

CDMs Listed Alphabetically by Function:

Activate/Deactivate (0x0003)

Changer Functions (0x001C)

Format (0x0000)

Insert Functions (0x001B)

Lock/Unlock (0x0007)

Magazine Functions (0x001D)

Mount/Dismount (0x0004)

Tape Control (0x0001)

Reserved (0x0002, 0x0006, 0x0009 - 0x001F)

CDMs Listed Numerically by Function Code:

Format (0x0000)

Tape Control (0x0001)

Reserved (0x0002)

Activate/Deactivate (0x0003)

Mount/Dismount (0x0004)

Reserved (0x0006)

Lock/Unlock (0x0007)

Reserved (0x0009 - 0x001A)

Insert Functions (0x001B)

Changer Functions (0x001C)

Magazine Functions (0x001D)

Reserved (0x001E - 0x001F)

Activate/Deactivate	(0x0003)

Description:	The purpose of this function is to bring the media on-line or off-line. If the media is removable, function 0x0003 will mount or dismount the media in the device. This call is valid for both device and media objects.

Parameters:

Function	=	0x0003 -- activate/deactivate request

parameter0	=	This parameter specifies the operation to be performed.

0 activate

1 deactivate

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Important:	When acting on an activate request, the CDM must call CDI_Object_Update() before completing the request with a call to CDI_Complete_Message().

When acting on a deactivate device request, the CDM must call CDI_Complete_Message() before calling CDI_Object_Update().

Changer Functions	(0x001C)

This section lists the category of Media Manager control functions related to changers. Each message (packaged in a CDMMessageStruct) in this section has 0x001C as the value in its Function field to identify that it is a function in the changer category. The value in parameter0 acts as a sub-function index to identify what function to perform. The CDM can either implement a secondary jump table using the value in parameter0 as an index or use a switch statement on parameter0 to call its routine that will field the message.

Return Changer Media Mapping

Description:	Mandatory for Autochangers

This message directs the CDM to return a structure that contains the media mapping for the read/write devices, storage slots and exchange slots for an autochanger.

Parameters:

Function	=	0x001C -- changer function

parameter0	=	0x0002 -- return changer media mapping

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	Pointer to the buffer where the requested data is to be returned. The CDM fills in the data according to the following format:

BYTE AccessibleRWDevice#0 - status of read/write device #0 (1=Full 0=Empty)

BYTE AccessibleRWDevice#1 - status of read/write device #1 (1=Full 0=Empty)

.

.

BYTE StorageSlot#0 - status of storage slot #0 (1=Full 0=Empty)

BYTE StorageSlot#1 - status of storage slot #1 (1=Full 0=Empty)

.

.

BYTE ExchangeSlot#0 - status of exchange slot #0 (1=Full 0=Empty)

BYTE ExchangeSlot#1 - status of exchange slot #1 (1=Full 0=Empty)

.

.

Note:	The buffer is a byte table for all Read/Write devices, Storage slots, and Media Exchange slots configured as objects of the Autochanger. It is critical that the table be in the order as shown above. The value assigned each BYTE indicates that the corresponding object contains media or is empty (1=Full 0=Empty).

For example, if the NumberAccessibleRWDevices returned by ReturnChangerInfo = 2 and NumberStorageSlots returned by ReturnChangerInfo = 9 and NumberExchangeSlots returned by ReturnChangerInfo = 1, then the buffer might appear as follows (the actual representation depends on whether each slot has media):

Buffer Entry	Object	Status	Corresponding MM Number
01h	read/write device "0"	has media	0x0000
00h	read/write device "1"	is empty	0x0001
01h	storage slot "0"	has media	0x0002
00h	storage slot "1"	is empty	0x0003
00h	storage slot "2"	is empty	0x0004
01h	storage slot "3"	has media	0x0005
01h	storage slot "4"	has media	0x0006
01h	storage slot "5"	has media	0x0007
00h	storage slot "6"	is empty	0x0008
01h	storage slot "7"	has media	0x0009
01h	storage slot "8"	has media	0x000A
00h	media exchange slot "0"	is empty	0x000B

Changer Command

Description:	Mandatory for Autochangers

This message directs the CDM to perform one of three commands associated with moving media within an autochanger - move, preload, or eject media.

Parameters:

Function	=	0x001C -- changer function

parameter0	=	0x0003 -- changer command

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	The Media Manager fills in the data according to the following format:

LONG Source

LONG Destination

LONG CommandType

The fields in the buffer structure are defined as follows:

Source	Contains the mapped location of the read/write device, storage slot or media exchange slot from which the media will move.

Destination	Contains the mapped location of the read/write device, storage slot or media exchange slot to which the media will move.

CommandType	Contains one of three values, depending on the desired operation.

0x00	changer move moves media from source to destination

0x01	changer preload (**) indicates to the driver that the next MESSAGE request will be a regular move command from source to destination.

0x02	changer eject moves media to the exchange slot and ejects the media.

(**) =	required for devices that execute a command before the user inserts the media.

Example:	Given the following changer configuration:

Object	ObjectID
read/write device "0"	0x0000
read/write device "1"	0x0001
storage slot "0"	0x0002
storage slot "1"	0x0003
storage slot "2"	0x0004
storage slot "3"	0x0005
storage slot "4"	0x0006
storage slot "5"	0x0007
storage slot "6"	0x0008
storage slot "7"	0x0009
storage slot "8"	0x000A
media exchange slot "0"	0x000B

If the Media Manager calls ChangerCommand and filled the buffer with this information,

0x000B <== source - exchange slot "0"

0x0001 <== destination - device "1"

0x0001 <== changer preload command

the next Media Manager command would fill the buffer with the following information:

0x000B

0x0001

0x0000 <== changer move command

Format	(0x0000)

Description:	This function formats fixed disk or tape media. It implies to the Media Manager that the media is new media. The media ID is implied by the object handle used.

Parameters:

Function	=	0x0000 -- format request

parameter0	=	This parameter is a flag specifying the type of format.

0 quick format (re-format)

1 security erase (complete format)

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Insert Functions	(0x001B)

Description:	The purpose of this function is to move media or magazine objects in and out of removable devices and autochangers. This function generates console alerts.

Parameters:

Function	=	0x001B -- insert/remove media or magazine request

parameter0	=	This parameter specifies the operation to be performed.

0 insert

1 remove

parameter1	=	Contains the object ID of the media or magazine object to be inserted. A "-1" specifies new media should be inserted.

parameter2	=	Specifies the correct mail (exchange) slot in an autochanger when there is more than one slot in the autochanger. This parameter should be 0 when there is only one mail slot, or the if the device is a stand-alone device.

BufferLength	=	not used

Buffer	=	not used

Lock/Unlock	(0x0007)

Description:	The purpose of this function is to lock a media in a, device. Once locked, the media cannot be manually removed by the operator.

Parameters:

Function	=	0x0007 -- lock/unlock media or magazine request

parameter0	=	This parameter specifies the operation to be performed.

0 lock media selection

1 unlock media selection

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Magazine Functions	(0x001D)

This section lists the category of Media Manager messages related to magazines. Each message (packaged in a CDMMessageStruct) in this section has 0x001D as the value in its Function field to identify that it is a function in the magazine category. The value in parameter0 acts as a sub-function index to identify what function to perform. The CDM can either implement a secondary jump table using the value in parameter0 as an index or use a switch statement on parameter0 to call its routine that will field the message.

Return Magazine Info

Description:	Mandatory for Magazines

This message directs the CDM to return the number of storage slots in the magazine. This message will not be issued until after the Magazine Load message is issued.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0000 -- return magazine info

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	Pointer to the buffer where the requested data (of type LONG) is to be returned. This value indicates the number of media storage bays the magazine supports. Subsequent references to specific storage slots in this magazine use numbers 1 through n where the number returned here is n.

Return Magazine Media Mapping

Description:	Mandatory for Magazines

This message directs the CDM to request the return of a structure that provides the slot mapping for a magazine device. This message should not be issued until after the Return Magazine Info message is issued.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0002 -- return magazine media mapping

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	Pointer to the buffer where the requested data is to be returned. The buffer must contain a byte table for the read/write device and the storage slots. A value of 01h in a byte indicates full, and a value of 00h indicates empty. For example, if the number of storage slots returned by Return Magazine Info = 4, then the buffer might appear as follows (an exact representation depends on whether the slots have media and the order shown here is critical):

01h the read/write device has media

00h storage slot "1" is empty

01h storage slot "2" has media

01h storage slot "3" has media

00h storage slot "4" is empty

Magazine Select Media

Description:	Mandatory for Removables with Magazines

This message directs the CDM to transfer a specific piece of media into the read/write device associated with a magazine.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0003 -- magazine select

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	This value is the storage slot number of the media to be selected.

Magazine Deselect Media

Description:	Mandatory for Removables with Magazines

This message directs the CDM to transfer a piece of media from the device into a specified slot in the magazine.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0004 -- magazine deselect

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	This value is the number of the destination storage slot.

Magazine Load

Description: Mandatory for Magazines

This message directs the CDM to load the magazine into the magazine mechanism.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0005 -- magazine load

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Magazine Unload

Description:	Mandatory for Magazines

This message directs the CDM to inhibit the execution of any subsequent Magazine messages until another Magazine Load message is received. The Magazine messages other than Magazine Load should be returned with a "Magazine Not Present" completion code.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0006 -- magazine unload

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Magazine Eject

Description:	Mandatory for Magazines

This message directs the CDM to eject the magazine.

Parameters:

Function	=	0x001D -- magazine function

parameter0	=	0x0007 -- magazine eject

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Mount/Dismount	(0x0004)

Description:	The purpose of this function is to bring the media inside a physical device on-line or off-line. The mount/dismount function assumes that the media is present. This operation will identify or verify the media in the device.

Parameters:

Function	=	0x0004 -- mount/dismount request

parameter0	=	This parameter specifies the operation to be performed.

0 mount

1 dismount

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Important:	When acting on a mount request, the CDM must call CDI_Object_Update() before completing the request with a call to CDI_Complete_Message().

When acting on a dismount request, the CDM must call CDI_Complete_Message() before calling CDI_Object_Update().

Tape Control	(0x0001)

Description:	Provides additional functions to manage tapes. Use various combinations of parameters to create partitions, retension, and two kinds of erase partition operations. Both erase functions take place from the current position to the end of the partition. The erase functions DO NOT imply a rewind of tape media. At the end of the retension operation, the current partition is undefined. Select another partition (See the "Select Partition" in the list of I/O functions) before continuing.

Parameters:

Function	=	0x0001 -- tape operation request

parameter0	=	This parameter is a flag specifying the type of erase.

0 quick erase (re-format)

1 security erase (zero out all blocks)

2 create partition

3 retension

parameter1	=	Indicates the number of partitions to create.

Note: Only used if parameter0=2 (create partition)

parameter2	=	not used

BufferLength	=	Byte count of buffer array; equals (parameter1)*4

Buffer	=	Pointer to array of LONGs, where each LONG indicates the size of each partition in megabytes. A "-1" in an array location indicates the partition should take the remainder of the tape. The last partition should always have a "-1".

9.2 I/O Functions (0x0020 - 0xFFFF)

Listed Alphabetically by Function:

Locate Data Blocks (0x002B)

Multiple File Mark (0x0027)

Multiple Set Mark (0x0029)

Position Media (0x002D)

Position Partition (0x002C)

Random Read (0x0020)

Random Write (0x0021)

Random Write Once (0x0022)

Restart Queue (0x0025)

Sequential Read (0x0023)

Sequential Write (0x0024)

Single File Mark (0x0026)

Single Set Mark (0x0028)

Space Data Blocks (0x002A)

Reserved (0x002E - 0x003F)

Listed Numerically by Function Code:

Random Read (0x0020)

Random Write (0x0021)

Random Write Once (0x0022)

Sequential Read (0x0023)

Sequential Write (0x0024)

Restart Queue (0x0025)

Single File Mark (0x0026)

Multiple File Mark (0x0027)

Single Set Mark (0x0028)

Multiple Set Mark (0x0029)

Space Data Blocks (0x002A)

Locate Data Blocks (0x002B)

Position Partition (0x002C)

Position Media (0x002D)

Reserved (0x002E - 0x003F)

Locate Data Blocks	(0x002B)

Description:	This function locates specific data blocks and returns location information.

Parameters:

Function	=	0x002B -- locate data blocks request

parameter0	=	This parameter is a flag indicating whether to locate a data block or return location information.

0 return location information

1 go to specified location

parameter1	=	not used

parameter2	=	not used

BufferLength	=	This parameter indicates the size of the buffer where location information is to be copy or accessed. The buffer must be of sufficient length to accommodate the location information.

Buffer	=	If return location information is specified, this parameter points to a buffer where the location information is copied, otherwise, it contains the location information needed to locate the data block

Multiple File Mark	(0x0027)

Description:	This function performs the writing and locating of multiple file marks.

Parameters:

Function	=	0x0027 -- multiple file marks request

parameter0	=	This parameter contains a flag indicating whether or not a multiple file marks are to be written or searched.

0 write multiple file marks

1 space forward for multiple file marks

2 space backward for multiple file marks.

parameter1	=	This parameter indicates the number of consecutive file marks to be written to or spaced over.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Multiple Set Mark	(0x0029)

Description:	This function performs the writing and locating of multiple set marks.

Parameters:

Function	=	0x0029 -- multiple set marks request

parameter0	=	This parameter contains a flag indicating whether or not a multiple set marks are to be written or searched.

0 write multiple set marks

1 space forward for multiple set marks

2 space backward for multiple set marks

parameter1	=	This parameter indicates the number of consecutive set marks to be written to or spaced over.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Position Media	(0x002D)

Description:	This function provides support to position sequential media devices.

Parameters:

Function	=	0x002D -- sequential media request

parameter0	=	This parameter is a flag indicating the type of media function.

1 rewind media

2 go to end of recorded media (logical end of media)

parameter1	=	This parameter indicates the number of consecutive set marks to be written to or spaced over.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Select Partition	(0x002C)

Description:	This function selects a partition and positions the media at the beginning or end of partition depending on parameter0.

Parameters:

Function	=	0x002C -- select partition request

parameter0	=	This parameter is a flag indicating the type of partition function.

1 rewind/select partition

2 go to end of file/select partition

parameter1	=	This parameter indicates the partition to be selected.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Random Read	(0x0020)

Description:	This function performs random read I/O from the device.

Parameters:

Function	=	0x0020 -- read request

parameter0	=	This parameter specifies the number of units to be read.

parameter1	=	This parameter specifies the logical unit number of the beginning unit.

parameter2	=	not used

BufferLength	=	This parameter is the size of the buffer (i.e. the number of units the unit size)

Buffer	=	This parameter points to a buffer in memory where the data is to be read.

Random Write	(0x0021)

Description:	This function performs write I/O to any part of the media in a device.

Parameters:

Function	=	0x0021 -- write request

parameter0	=	Specifies the number of units to be written.

parameter1	=	Specifies the logical unit number of the beginning unit.

parameter2	=	not used

BufferLength	=	The size of the buffer (i.e. the number of units the unit size)

Buffer	=	Points to a buffer in memory where the data is written from.

Random Write Once	(0x0022)

Description:	This function performs one write to any part of the media in a device.

Parameters:

Function	=	0x0022 -- write once request

parameter0	=	This parameter specifies the number of units to be written.

parameter1	=	This parameter specifies the logical unit number of the beginning unit.

parameter2	=	not used

BufferLength	=	This parameter is the size of the buffer (i.e. the number of units the unit size).

Buffer	=	Points to a buffer in memory where the data is written from.

Reset Queue	(0x0025)

Description:	This function allows an application to restart (or unfreeze) a device queue. This function is particularly geared toward tape applications, since they need tighter control of how sequential requests are executed. When the CDM gets this message, it must translate it into either a HACB Type=0 or priority HACB request. Otherwise, if the device queue (which is controlled by the HAM) is currently frozen, the unfreeze request will sit in the queue and never get executed.

Parameters:

Function	=	0x0025 -- Reset Queue request

parameter0	=	not used

parameter1	=	not used

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

Sequential Read	(0x0023)

Description:	This function reads sequential data from tape.

Parameters:

Function	=	0x0023 -- sequential read request

parameter0	=	This parameter specifies the number of units to be read, where units refers to what used to be called sectors in the fixed media world.

parameter1	=	not used

parameter2	=	not used

BufferLength	=	This parameter is the size of the buffer (i.e. the number of units the unit size) in bytes. The "number of units" (parameter0) cannot exceed the maximum number of units specified in the blocksize field of the UpdateInfoStruct used when the CDM bound to the target device. Additionally, the device's unit size (unitsize field) is specified in this structure.

Buffer	=	Points to a buffer in memory where the data is to be read.

ReturnParameter	=	The number of units read.

Note:	ReturnParameter is not a data member of the CDM message structure (CDMMessageStruct). However, CDMs supporting this function are required to provide the data specified by ReturnParameter. The Media Manager passes this value on to the application, and the CDM passes this value to the Media Manager as an input parameter to CDI_Complete_Message().

Sequential Write	(0x0024)

Description:	This function performs sequential writes to the device.

Parameters:

Function	=	0x0024 -- sequential write request

parameter0	=	This parameter specifies the number of units to be written, where units refers to what used to be called sectors in the fixed media world.

parameter1	=	not used

parameter2	=	not used

BufferLength	=	This parameter is the size of the buffer (i.e. the number of units the unit size).

Buffer	=	Points to a buffer in memory where the data is written from.

ReturnParameter	=	The number of units written. See note on Sequential Read above.

Single File Mark	(0x0026)

Description:	This function performs the writing and locating of single file marks.

Parameters:

Function	=	0x0026 -- single file mark request

parameter0	=	This parameter contains a flag indicating whether or not a single file mark is to be written or searched.

0 write single file mark

1 space forward for single file marks

2 space backward for single file marks

parameter1	=	If a space function was requested, this parameter indicates how many file marks to space over.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

ReturnParameter	=	If the space function was requested, the number of file marks spaced over is returned in this field. See note on Sequential Read above.

Single Set Mark	(0x0028)

Description:	This function performs the writing and locating of single set marks.

Parameters:

Function	=	0x0028 -- single set mark request

parameter0	=	This parameter contains a flag indicating whether or not a single set mark is to be written or searched.

0 write single set mark

1 space forward for single set marks

2 space backward for single set marks

parameter1	=	If a space function was requested, this parameter indicated how many set marks to space over.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

ReturnParameter	=	If the space function was requested, the number of set marks spaced over is returned in this field. See note on Sequential Read above.

Space Data Blocks	(0x002A)

Description:	This function spaces over data blocks.

Parameters:

Function	=	0x002A -- space data blocks request

parameter0	=	This parameter indicates the direction of the space.

1 space forward for multiple data blocks

2 space backward for multiple data blocks

parameter1	=	This parameter indicates the number of data blocks to be spaced over.

parameter2	=	not used

BufferLength	=	not used

Buffer	=	not used

ReturnParameter	=	The actual number of data blocks spaced over. See note on Sequential Read above.