 |
HP OpenVMS System Management Utilities Reference
Manual
22.4 UCM Usage Summary
The Universal Serial Bus (USB) Configuration Manager (UCM) utility
allows you to connect a computer to a variety of USB devices using a
single four-wire cable.
Format
UCM
To invoke UCM, enter UCM at the DCL command prompt ($):
At the UCM> prompt, you can enter any of the UCM commands described
briefly in Section 22.5 and in more detail in the following sections.
Alternatively, you can enter UCM commands at the DCL prompt. For
example:
To exit from UCM, enter the EXIT command at the UCM> prompt, or
press Ctrl/Z.
22.5 UCM Commands
The following table summarizes the UCM commands.
| Command |
Description |
Privilege Required |
|
ADD DEVICE
|
Allows you to add a new device to the collection of known USB devices.
|
SYSPRV
|
|
DELETE DEVICE
|
Allows you to remove a device from the collection of known devices.
|
SYSPRV
|
|
EXIT
|
Exits the UCM utility.
|
None
|
|
HELP
|
Provides online help information for using the UCM commands.
|
None
|
|
MODIFY DEVICE
|
Modifies the unit number or flags of an entry in the permanent list.
The changes take effect immediately.
|
SYSPRV
|
|
RELOAD
|
Reads the generic and permanent lists from disk.
|
SYSPRV
|
|
RESTART
|
Restarts the configuration server.
|
CMKRNL
|
|
SET LOG/NEW
|
Creates a new version of the event log file.
|
OPER
|
|
SHOW DEVICE
|
Displays configured and unconfigured devices that are connected to the
USB.
|
None
|
|
SHOW EVENTS
|
Displays events in the event log file.
|
None
|
ADD DEVICE
Allows you to add a new device to the collection of known USB devices.
Requires SYSPRV privilege.
Format
ADD DEVICE device-name:
Parameter
device-name:
The name of the device whose characteristics are to be added. The
device name has the form ddcu, where:
|
dd
|
is the device code---for example, LP. (The driver name corresponds to
the device code; in this case, the driver name would be SYS$LPDRIVER.)
|
|
c
|
is the controller designation A through Z; unless UCM specifies a
different letter, all USB devices are A.
|
|
u
|
is the unit number (0 through 9999).
|
OpenVMS device names are made up of the two-character device code,
followed by the controller designation, then by the unit number (which
can be 1 to 4 characters long), then by a colon (:).
Qualifiers
/BUS_NUMBER=number
Specifies the USB bus number of the device. This parameter is required
to identify a particular device on a system that has multiple USB
buses. If you do not use this qualifier, the bus number defaults to
zero.
The number can be any number from 0 through 25.
/PATH=(n1[.n2.n3.n4.n5.n6])
Specifies the path to the device on the bus. The path is used to
uniquely identify a device if the device does not have a serial number.
The path specification is a series of six or fewer nonzero numbers,
where:
|
n1
|
is the number of the port on the root hub (at tier 0).
|
|
n2 through
n6
|
are port numbers for downstream hubs at tiers 1, 2, 3, 4, and 5. (If
you do not specify trailing zeros, the UCM server supplies them.)
|
For example, /PATH=1.4.3 indicates that the device is plugged into port
3 of the second tier hub, which is plugged into port 4 of the first
tier hub, which in turn is plugged into the root hub 1.
For a more detailed explanation of path specifications, see
Figure 22-2 and the text that introduces the figure.
/UNIT_NUMBER=number
Unit numbers can be between 0 and 9999. By default, UCM selects the
next available unit number. This qualifier allows you to change the
unit number to suit your needs.
Example
|
$ UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> SHOW DEVICE /UNCONFIGURED
DEVICE
DEVICE_TYPE TENTATIVE
DEVICE_NAME_ROOT AG
UNIT_NUMBER 0
BUS 1
PATH 1.0.0.0.0.0
END_DEVICE
UCM> ADD DEVICE AGA0:
UCM> SHOW DEVICE /PERMANENT /FULL AGA0:
DEVICE
DEVICE_TYPE PERMANENT
DEVICE_NAME_ROOT AG
UNIT_NUMBER 0
DRIVER SYS$AGDRIVER.EXE
BUS_NUMBER 1
PATH 1.0.0.0.0.0
HID_USAGE_DATA 65540
BEGIN_INTERFACE
HID_USAGE_DATA 65540
END_INTERFACE
END_DEVICE
UCM>
|
In this example, the first UCM command SHOW DEVICE /UNCONFIGURED
indicates that the device has not yet been configured. It displays only
the information that appears in the generic list: the device name root,
the unit number, the bus, and the path.
After the ADD DEVICE command, the second SHOW DEVICE command, with the
/PERMANENT and /FULL qualifiers, displays the information in the
permanent list. The list includes the name of the driver assigned to
the device, the bus number; and the Human Interface Device (HID) usage
data number, which is used to configures devices in the HID interface
class. Examples of HID devices are keyboards, mice, joysticks, and so
on.
DELETE DEVICE
Allows you to remove a device from the the permanent list.
Requires SYSPRV privilege.
Format
DELETE DEVICE device-name:
Parameters
device-name:
The name of the device whose characteristics are to be deleted. The
device name has the form ddcu, where:
|
dd
|
is the device code---for example, LP. (The driver name corresponds to
the device code; in this case, the driver name would be SYS$LPDRIVER.)
|
|
c
|
is the controller designation A through Z; unless UCM specifies a
different letter, all USB devices are A.
|
|
u
|
is the unit number (0 through 9999).
|
OpenVMS device names are made up of the two-character device code,
followed by the controller designation, then by the unit number (which
can be 1 to 4 characters long), then by a colon (:).
Example
|
$ UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> SHOW DEVICE /PERMANENT AGA0:
DEVICE
DEVICE_TYPE PERMANENT
DEVICE_NAME_ROOT AG
UNIT_NUMBER 0
BUS 1
PATH 1.0.0.0.0.0
END_DEVICE
UCM> DELETE DEVICE AGA0:
UCM> SHOW DEVICE /PERMANENT AGA0:
%USB-E-NOSUCHDEV, Device name or device unit not found
UCM>
|
In this example, the first SHOW DEVICE AGA0: command displays
information about the device that is in the permanent list. After the
DELETE DEVICE AGA0: command, the second SHOW DEVICE AGA0: command
displays an error message indicating that the device is no longer in
the permanent list.
EXIT
Stops the execution of UCM and returns control to DCL command level.
You can also press Ctrl/Z to perform the same function.
Format
EXIT
HELP
Provides online help for using the UCM commands.
Format
HELP [command-name]
Parameter
command-name
The name of a UCM command. When you enter the HELP command with a
command name, UCM displays a list of all the command keywords used with
the command.
Example
|
UCM> HELP RESTART
RESTART
Restarts the configuration server. This command should be used
only if the server is no longer responding to configuration requests
or if the client cannot get the server to respond to commands. Use
of this command requires the CMKRNL privilege.
Format
RESTART
Additional information available:
Qualifiers
/CONFIRM
RESTART Subtopic?
|
The HELP RESTART command describes the command, shows its format, and
indicates what additional information is available, such as qualifiers.
It then prompts you to enter the name of the /CONFIRM qualifier to
display information about this qualifier.
MODIFY DEVICE
Allows you to modify the path and unit number of a device in the
permanent list. The changes take place immediately.
Requires SYSPRV privilege.
Format
MODIFY DEVICE device-name:
Parameter
device-name:
The name of the device whose characteristics are to be modified. The
device name has the form ddcu, where:
|
dd
|
is the device code---for example, LP. (The driver name corresponds to
the device code; in this case, the driver name would be SYS$LPDRIVER.)
|
|
c
|
is the controller designation A through Z; unless UCM specifies a
different letter, all USB devices are A.
|
|
u
|
is the unit number (0 through 9999).
|
OpenVMS device names are made up of the two-character device code,
followed by the controller designation, then by the unit number (which
can be 1 to 4 characters long), and then by a colon (:).
Qualifiers
/BUS_NUMBER=number
Specifies the USB bus number of the device. This parameter is required
to identify a particular device on a system that has multiple USB
buses. If you do not use this qualifier, the bus number defaults to
zero.
The number can be any number from 0 through 25.
/PATH=(n1[.n2.n3.n4.n5.n6])
Specifies the path to the device on the bus. The path is used to
uniquely identify a device if the device does not have a serial number.
The path specification is a series of six or fewer numbers, where:
|
n1
|
is the number of the root hub (at tier 0).
|
|
n2 through
n6
|
are port numbers for downstream hubs at tiers 1, 2, 3, 4, and 5.
|
For example, /PATH=1.4.3 indicates that the device is in turn plugged
into port 3 of the second tier, which is plugged into port 4 of the
first tier, which in turn is plugged into the root hub 1.
/UNIT_NUMBER=number
Unit numbers can be between 0 and 9999. By default, the configuration
code selects the next available unit number. This qualifier allows you
to change the unit number to suit your needs.
Example
|
$ UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> SHOW DEVICE /UNCONFIGURED
DEVICE
DEVICE_TYPE TENTATIVE
DEVICE_NAME_ROOT AG
UNIT_NUMBER 0
BUS 1
PATH 1.0.0.0.0.0
END_DEVICE
UCM> ADD DEVICE AGA0:
UCM> MODIFY DEVICE AGA0:/UNIT=9999
UCM> SHOW DEVICE /PERMANENT /FULL AGA9999:
DEVICE
DEVICE_TYPE PERMANENT
DEVICE_NAME_ROOT AG
UNIT_NUMBER 9999
DRIVER SYS$AGDRIVER.EXE
BUS_NUMBER 1
PATH 1.0.0.0.0.0
HID_USAGE_DATA 65540
BEGIN_INTERFACE
HID_USAGE_DATA 65540
END_INTERFACE
END_DEVICE
UCM>
|
The first SHOW DEVICE command displays information from the generic
list about the unconfigured AG device. The ADD DEVICE command adds the
device to the permanent list, and the MODIFY DEVICE command changes the
unit number of the device. The second SHOW DEVICE command displays this
change.
RELOAD
Forces the configuration server to reload the configuration data from
the generic and permanent device files and to rebuild the lists. This
allows you to add a new device type and lets the server find out about
it without restarting UCM.
Requires SYSPRV privilege.
Format
RELOAD
RESTART
Restarts the configuration server.
Note
Use this command only if the server no longer responds to configuration
requests or client commands.
|
Requires CMKRNL privilege.
Format
RESTART
Qualifier
/CONFIRM (default)
/NOCONFIRM
Asks you to confirm the restart of the configuration server. If you
answer yes, the configuration server is restarted. If you answer no,
the operation is not performed.
Example
|
$ UCM
UCM> RESTART
Restart UCM Server? [N]: yes
Waiting for UCM Server image to exit....
Waiting for UCM Server image to restart....
%USB-S-SRVRRESTART, Identification of new UCM Server is 00000217
UCM>
|
Following the RESTART command, UCM prompts you to confirm this command.
The system assigns a new identification number to the UCM server when
it restarts.
SET LOG
Tells the configuration server to create a new log file. You must use
the /NEW qualifier with this command.
Requires OPER privilege.
Format
SET LOG /NEW
Qualifier
/NEW
Creates a new SYS$MANAGER:USB$UCM_EVENTS.DAT file. This qualifier is
required with the SET LOG command.
SHOW DEVICE
Displays information about devices.
Format
SHOW DEVICE device-name:
Parameter
device-name:
The name of the device whose characteristics are to be displayed. The
device name has the form ddcu, where:
|
dd
|
is the device code---for example, LP. (The driver name corresponds to
the device code; in this case, the driver name would be SYS$LPDRIVER.)
|
|
c
|
is the controller designation A through Z; unless UCM specifies a
different letter, all USB devices are A.
|
|
u
|
is the unit number (0 through 9999.)
|
OpenVMS device names are made up of the two-character device code,
followed by the controller designation, then by the unit number (which
can be 1 to 4 characters long), and then by a colon (:).
Display_Qualifiers
/BRIEF (default)
Displays summary information for each device.
/FULL
Displays complete information for each device.
Selection_Qualifiers
/ALL (default)
Displays all device entries, including those that the /CONFIGURED,
/GENERIC, /PERMANENT, /PHYSICAL, and /UNCONFIGURED qualifiers display.
/CONFIGURED
Displays all the devices connected to the bus that have been configured
successfully.
/GENERIC
Displays the devices that are on the generic device list.
/PERMANENT
Displays the devices for which the system automatically loads device
drivers if the devices are plugged in.
/PHYSICAL
Displays the devices that are connected to the bus even if drivers for
these devices are not loaded.
/UNCONFIGURED
Displays devices that are attached to the bus and that have drivers,
but that do not have entries in the permanent list. (These are also
known as tentative devices.)
You must execute an ADD DEVICE command to make these devices part of
the permanent list. Once the drivers have been added, the device is
automatically configured the next time it is plugged in.
Example
|
$ UCM
UCM> SHOW DEVICE /PERMANENT /FULL DNA3:
DEVICE
DEVICE_TYPE PERMANENT
DEVICE_NAME_ROOT DN
UNIT_NUMBER 3
DRIVER SYS$DNDRIVER.EXE
USB_CONFIG_TYPE INTERFACE
VENDOR_ID 3519
PRODUCT_ID 768
RELEASE_NUMBER 4352
BUS_NUMBER 1
PATH 1.0.0.0.0.0
DEVICE_CLASS 0
DEVICE_SUB_CLASS 0
DEVICE_PROTOCOL 0
NUMBER_OF_INTERFACES 1
CONFIGURATION_VALUE 2
NUMBER_OF_CONFIGURATIONS 1
SERIAL_NUMBER 2B0301060D97A4C8
MANUFACTURER_STRING QTS
PRODUCT_STRING USB 2.0 ATAPI Bridge
CONFIGURATION_NUMBER 0
BEGIN_INTERFACE
INTERFACE_CLASS 8
INTERFACE_SUB_CLASS 6
INTERFACE_PROTOCOL 80
END_INTERFACE
END_DEVICE
UCM>
|
In this example, the SHOW DEVICE command displays complete information
about DNA3:.
SHOW EVENTS
Displays important events that occur on the USB bus. Data displayed can
include information about device events, such as removals, connections,
unrecognized devices, new devices, and so on.
Format
SHOW EVENTS
Qualifiers
/BEFORE=time
Selects events that occurred before the specified time. You can specify
time as an absolute time, as a combination of absolute and
delta times, or as the keyword TODAY (default), TOMORROW, or YESTERDAY.
Times are expressed in standard OpenVMS date/time format.
/OUTPUT=file-name
Writes the selected events to the specified file. By default, output is
sent to the current SYS$OUTPUT device (usually your terminal).
You cannot use the /OUTPUT qualifier with the /PAGE qualifier.
/PAGE
/NOPAGE (default)
Controls how information is displayed. /PAGE displays events on one
screen at a time.
You cannot use the /PAGE qualifier with the /OUTPUT qualifier.
/SINCE=time
Selects only those events that occurred on or after the specified time.
You can specify time as absolute time, as a combination of absolute and
delta times, or as the keyword TODAY (default) or YESTERDAY.
/TYPE=event-type
Selects only the specified type of events. Valid event-types are the
following:
|
ALL
|
All event-types (default).
|
|
CONFIGURED
|
Device was recognized and configured.
|
|
DECONFIGURE
|
Device was removed from the bus.
|
|
DRIVER
|
Driver events.
|
|
UCM
|
UCM server events.
|
|
UNCONFIGURE
|
Device was recognized but not configured.
|
|
UNKNOWN
|
Event type is unknown.
|
/VALUE=event-number
Selects only the events specified by the event number. In a future
version of this product, you will be able to use this qualifier as an
alternative to the /TYPE qualifier for events that do not have an
assigned keyword.
Example
|
$ UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> SHOW EVENTS /SINCE=YESTERDAY
USB EVENT LISTING
-----------------
Date Time Type Priority Component
-----------------------------------------------------------------------
31-JUL-2002 11:46:20.76 DRIVER NORMAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x9/0x0 1
31-JUL-2002 11:46:20.76 DRIVER NORMAL HUBDRIVER
Message: Configured device UCM0 using driver SYS$HUBDRIVER: 2)
31-JUL-2002 11:46:21.06 DRIVER NORMAL HUBDRIVER
Message: Find a driver for DeviceClass/DeviceSubClass = 0x0/0x0 3)
31-JUL-2002 11:46:21.31 UNKNOWN NORMAL UCM UNKNOWN DEVICE
Message: VENDOR_ID = 3519.PRODUCT_ID = 768.RELEASE_NUMBER =
4352.BUS_NUMBER = 1.PATH = 1.0.0.0.0.0.DEVICE_CLASS =
0.DEVICE_SUB_CLASS = 0.DEVICE_PROTOCOL = 0.NUMBER_OF_INTERFACES =
1.NUMBER_OF_CONFIGURATIONS = 1.SERIAL_NUMBER =
2B0301060D97A4C8.MANUFACTUR 4)
31-JUL-2002 11:46:21.31 DRIVER NORMAL HUBDRIVER
Message: Find a driver for InterfaceClass/InterfaceSubClass/
Protocol = 0x8/0x6/0x50 5)
31-JUL-2002 11:46:21.46 DRIVER NORMAL HUBDRIVER
Message: Configured device DNA3 using driver SYS$DNDRIVER: 6)
1-AUG-2002 11:16:07.71 DECONFIGURED NORMAL HUBDRIVER
Message: Deconfiguring device on bus 1 at port 1 bus tier 1 usb
address 2 7)
|
Note that the display on your screen might be somewhat different from
the one you see here.
Numbers in the example correspond to the following explanations:
- UCM saw the root hub.
- UCM configured the root hub.
- UCM saw a new device.
- Data about the new device in number 3 is displayed.
- For the device in number 3, UCM attempted to locate a drive based
on device interface data.
- UCM found and loaded the driver for the device in number 3.
- The device specified in the message line was unplugged.
|
