Reprinted from the help file, with two obvious changes:
You can use the command-line utility for Removable Storage to manage media resources and to write batch scripts for applications that do not currently support the Removable Storage API (are not aware of Removable Storage). You can run the command-line utility from a command prompt by typing rsm.
The syntax of the command-line utility is:
rsm allocate | createpool | deallocate | deletepool | dismount | eject | ejectatapi | mount | refresh | view
Each command has its own optional parameters, called argument switches, that you can specify, keeping the following points in mind:
Notes
Media are allocated from the media pool that is specified by the /m switch. When using the allocate command, logical media can be specified by a name and a description using the /ln and /ld switches respectively. Similarly, media sides (or partitions) can be specified by a name and description using the /pn and /pd switches respectively.
Logical media names and side names can be used in other commands to specify media as the parameter to the /lf or /pf switch respectively. If logical media names (which are friendly names) are not used with the allocate command, you can only use GUIDs (and not friendly names) in subsequent commands to specify logical media.
The syntax of the allocate command is as follows:
where:
media_pool_name specifies the media pool from which to allocate media. This means that you will have allocated media in that pool.
logical_media_id specifies the next side of multi-sided media to allocate. This parameter is optional and must be used with the /o switch and the next parameter. After deallocating this media, the logical-media ID is invalid.
partition_id specifies the media side to allocate. This parameter is optional and remains persistent even after the media is deallocated.
timeout specifies the command time-out, in milliseconds. This parameter is optional, with the default timeout value being infinite.
One of the following optional parameters may also be used with the /o switch:
Errunavail prevents the submission of an operator request for new media if none can be allocated with the specificed constraints.
New allocates a media side that cannot be shared with another application. This can be used to reserve the second side of two-sided media. The second side can then be allocated using the next parameter.
Next allocates the next side of media that was previously allocated using the new parameter.
If the optional /b switch is used, only the GUID for the allocate operation is displayed. This aids in scripting where you want to pass the output of one command to the next with minimal parsing.
Creates a media pool. The name of the media pool is specified using the /m switch.
The syntax of the createpool command is as follows:
where:
media_pool_name specifies the name of the media pool to be created.
media_pool_type_id specifies the type of media that the media pool will contain. Either the friendly name or the GUID can be specified. This parameter is optional, with the default type being a media pool that contains other media pools.
One of the following optional parameters may also be used with the /a switch:
Existing opens the existing media pool or returns an error if the media pool specified does not exist.
Always opens the existing media pool or creates a new media pool if not found.
New creates a new media pool or returns an error if the media pool specified already exists.
If the optional /d switch is used, the media pool can automatically draw media from the free media pool. The default is not to draw media from the free media pool.
If the optional /r switch is used, the media pool can automatically return media to the free media pool. The default is not to return media to the free media pool.
The logical media name or the media side (partition) name can be used to specify the logical media to deallocate only if one of these names were specified with the allocate command using the /ln or /pn switch respectively. Otherwise, either the logical media ID (LMID) or the partition ID (PARTID) must be specified instead.
The syntax of the deallocate command is as follows:
where:
logical_media_id specifies the logical media to deallocate. Either the friendly name or the GUID can be specified.
partition_id specifies the media side to deallocate. Either the friendly name or the GUID can be specified.
The deletepool command deletes a media pool. The name of the media pool is specified using the /m switch.
The syntax of the deletepool command is as follows:
rsm deletepool /mmedia_pool_name
where:
media_pool_name specifies the name of the media pool to be deleted.
The logical media name or the media side (partition) name can be used to specify the logical media to dismount only if one of these names were specified with the allocate command using the /ln or /pn switch respectively. Otherwise, either the logical media ID (LMID) or the partition ID (PARTID) must be specified instead.
The syntax of the dismount command is as follows:
where:
logical_media_id specifies the logical media to dismount. Either the friendly name or the GUID can be specified.
partition_id specifies the media side to dismount. Either the friendly name or the GUID can be specified.
If the optional /o switch with the optional deferred parameter is used, the media is marked as dismountable, but the media is kept in the drive. Subsequent mount commands can be completed normally. If not used, the media is dismounted from the drive immediately.
The media to be ejected can be specified by either the physical-media ID (PMID) or the physical media name.
The syntax of the eject command is as follows:
where:
physical_media_id specifies the physical media to eject. Either the friendly name or the GUID can be specified.
eject_operation_id specifies the GUID for the particular eject operation. The optional /o switch can be used in conjunction with the /a switch and the stop parameter to terminate a particular eject operation. This can also be used in conjunction with the /a switch and the start parameter to display the GUID of the particular eject operation.
The /a switch is optional, with the default parameter being start. One of the following optional parameters may also be used with the /a switch:
Start starts the eject operation immediately. The media is ejected until a timeout occurs, or unless another eject command is issued with the /a switch and the stop parameter. Such eject commands must also specify the eject operation GUID using the /o switch. The timeout parameter is specified in the library object (for all eject operations) for the library. To set this timeout parameter, you must use the Removable Storage API. Can also be used in conjunction with the /o switch to display the GUID of a particular eject operation.
Stop terminates the eject operation prior to a timeout expiring. The particular eject operation can be determined using the GUID displayed when the start parameter is used with the /a switch and the /o switch.
Queue queues the media for later ejection. This can be used for libraries with multi-slot inject/eject (IE) ports.
The optional /b switch displays only the eject operation GUID for scripting purposes.
Ejects media from an ATAPI changer by specifying the changer number. You should manually stop the Ntmssvc service before issuing this command.
The syntax of the ejectatapi command is as follows:
rsm ejectatapi /natapi_changer_number
where:
atapi_changer_number is the numeral found at the end of the string for the device name of the changer. For example, \\.\CdChanger0 has 0 as the ATAPI changer number.
The logical media to be mounted can be specified using either the logical-media ID (LMID) or the logical media name.
If you do not specify a drive ID for a multidrive library, Removable Storage selects an available drive in the library.
The syntax of the mount command is as follows:
logical_media_id specifies the logical media to mount. Either the friendly name or the GUID can be specified.
partition_id specifies the media side to mount. Either the friendly name or the GUID can be specified.
changer_id specifies the changer that contains the media to be mounted. Either the friendly name or the GUID can be specified. This can only be used in conjunction with the /sg switch and the slot GUID.
slot_id specifies the media slot that contains the media to be mounted. Either the friendly name or the GUID can be specified. This can only be used in conjunction with the /cg switch and the changer GUID.
drive_id specifies the particular drive on which to mount the applicable media. Either the friendly name or the GUID can be specified. This parameter is optional, and must be used in conjunction with the /o switch and the drive parameter.
One of the following optional parameters may also be used with the /o switch:
Errunavail generates an error if either the media or the drive is unavailable.
Drive specifies that a particular drive is to be mounted. This parameter is used in conjunction with the /d switch.
Read mounts the media for read access.
Write mounts the media for write access. If this parameter is used, completed media will not be mounted.
Offline generates an error if the media is offline.
The optional /r switch specifies the mount order, or priority. Mount priority may also be specified using one of the listed parameters. These parameters are optional with the default priority being normal.
timeout specifies the command time-out, in milliseconds. This parameter is optional with the default timeout being infinite.
Note
The refresh command is used to refresh a library, physical media, or all devices of a particular media type. This command causes a single poll of the target devices so that the Removable Storage database contains the current state of the device. This command can be useful after media inject or eject operations.
rsm refresh /l\[g|f\]library_id | /p\[g|f\]physical_media_id | /tgmedia_type_id
library_id specifies the library to be refreshed. Either the friendly name or the GUID can be specified.
physical_media_id specifies the physical media to be refreshed. Either the friendly name or the GUID can be specified.
media_type_id specifies the media type to be refreshed. Only the GUID can be specified. This parameter can be used to refresh all removable media devices by specifying the GUID for the "removable media" media type. This GUID can be determined using the view command as follows: rsm view /tmedia_type /guiddisplay.
The view command displays a list of media objects. When used without any parameter for the /t switch, this command displays a list of all media pools in the Removable Storage system (collection of libraries).
The syntax of the view command is as follows:
where:
container_id specifies the GUID for the object container. The type of container depends on the object type (parameter) specified with the /t switch. If the container ID is not specified, all instances of the applicable object type are displayed.
The optional /guiddisplay switch displays both the GUID and the friendly name for objects.
The optional /b switch displays only the object GUID for scripting purposes.
Note
If a command succeeds, then the code ERROR_SUCCESS is returned. All commands that fail return an error code, which can be used for scripting purposes. The error code is either a system-defined error code or one of the following:
536870913: Invalid arguments were specified. Frequently, this is caused by a space after an argument switch, for example, /t 50 instead of /t50.
536870914: Duplicate argument switches were specified. For example, the allocate command used with two /m switches.
536870915: No GUID matches the friendly name that was specified. Check capitalization, as friendly names are case-sensitive.
536870916: An insufficient number of argument switches were specified. Check to see if a required switch is missing.
536870917: An invalid GUID was specified. Use the view command to determine the correct GUID for an object.
536870918: This is returned only by the ejectatapi command. Verify that the ATAPI changer is functioning correctly.
NOTE: See tip 2265.