UCM configuration can be either automatic or manual. This section explains how devices are configured automatically. Section 25.4 explains how to configure a device manually.

Automatic configuration of devices is simple: the device is configured by plugging it in. UCM automatically configures any new (non-permanent) device that is on the generic list, loads the OpenVMS device driver for it, and makes the device permanent.

The following list describes the actual steps that take place automatically, beginning at system startup:

1. OpenVMS starts the UCM server, which does the following:
   1. Reads the settings for automatic loading and permanence as well as the exclude and include lists.
   2. Reads the generic list of supported devices.
   3. Reads the permanent list for descriptions of previously configured devices.
2. UCM initializes an empty tentative list.
3. UCM turns on the USB bus; a device on the bus announces itself.
4. UCM checks for device data on the permanent list. If device data is on the permanent list, UCM loads it and makes it available.
   If device data is not on the list, UCM performs the next steps.
5. UCM checks for data on the generic list. If device data is on this list, UCM uses it to make an entry in the tentative list.
6. If automatic loading is enabled (the default), UCM attempts to load and connect the OpenVMS device driver for the device and creates an OpenVMS device instance.
7. If automatic permanence is enabled (the default), UCM moves the device from the tentative list to the permanent list, and updates the on-disk database of configured devices.
8. If the SET AUTO command has disabled automatic loading, the data stays on the tentative list until the user either adds the device to or deletes the device from the permanent list.

   Notes In configuring devices, keep in mind the following: Unplugging a device does not delete a tentative item. When automatic loading and permanence are disabled, a device added to the permanent list following UCM startup is not configured (that is, it is not available for use) until the device is subsequently disconnected and reconnected (unplugged and replugged). Any modification to the permanent list creates a new version of the file.

9. Steps 3 through 8 repeat until all devices on all buses are processed.
10. UCM then waits for a user request or until a device is plugged in or unplugged.

Log Files

UCM uses the following log file to record disconnections, connections, and errors:

SYS$MANAGER:USB$UCM_EVENTS.LOG

You do not need special permission to access the event log. However, you need OPER privilege to use the UCM command SET LOG/NEW command to create a new log file. ( Section 25.7 contains a table of UCM commands and the privileges required to issue each command.)

25.4 Configuring Devices Manually

You might decide to disable automatic recognition and configuration of new devices, or to restrict the automatic configuration only to specific devices.

25.4.1 Disabling Automatic Configuration

If you do decide to disable all automatic configuration, enter the UCM SET AUTO/DISABLE command:

UCM> SET AUTO/DISABLE=(LOAD)

This command disables all automatic loading of all devices that are not in the permanent database.

This statement means that once a device has been configured and added to the permanent database, whenever it is connected to the system, UCM loads the driver for it and creates the device. Devices that are not in the permanent database are usually loaded automatically, and the device is created and placed in the permanent database.

When you turn off automatic loading with the SET AUTO/DISABLE=LOAD command, the device driver is not loaded, and the device is neither created nor placed on the permanent database. Instead, it is placed on the TENTATIVE list for manual user action.

Excluding One Type of Device from Loading

The other way to exclude a device from loading is to use the /EXCLUDE switch in the SET AUTO command. This is how a specific device is prevented from being loaded.

To disable the loading of a particular type of device, enter a command like the following:

UCM> SET AUTO/DISABLE=DNA

This command blocks DNA disks from automatic loading.

See the SET AUTO command for more information about its command qualifiers.

25.4.2 Creating an Entry in the Permanent List

This section describes the process of configuring a device that the UCM has not configured automatically because the device was excluded from automatic loading or automatic loading was disabled for all devices.

Before UCM can configure a USB device, the device must have a corresponding entry on the permanent list.

When you connect a USB device of a known type that has no entry on the permanent list, UCM uses information in the read-only generic list to create an entry in the tentative list. You must approve the entry before UCM will create an entry in the permanent list.

To set up a device to be configured, add the device as an entry in the permanent list. After you do this, UCM recognizes the device each time you connect it.

In the following example, you connect a printer to the USB. The printer is a known device type; in other words, the printer has an entry in the generic list. However, it does not yet have an entry in the permanent list.

Follow these steps to configure the device:

1. Physically connect the printer.
2. Enter the UCM command to enter the UCM environment and to display a message about configured and unconfigured devices on your system:

   $ UCM UCM>

3. To display more information about the unconfigured device, enter the following command:

   $ UCM Universal Serial Bus Configuration Manager, Version V1.0 UCM> SHOW DEVICE /UNCONFIGURED DEVICE DEVICE_TYPE TENTATIVE DEVICE_NAME_ROOT LPA UNIT_NUMBER 0 BUS 1 PATH 1.0.0.0.0.0 END_DEVICE UCM>

   
   Note that the display on your screen might be somewhat different from the one you see here.

4. Next, approve the entry by entering the ADD command. For example:

   UCM> ADD DEVICE LPA0: UCM> EXIT

   
   This command places the device information in the permanent list.

5. The last step before using the printer is to unplug the printer and reconnect it. This makes the device available for use. (If a device has no serial number, you must either plug it into the same port, or use the MODIFY command to indicate its new location.)
   When you reconnect the printer, its serial number and vendor ID identify it as LPA0:. UCM configures the device and makes it available for use. (This step is not necessary if the UCM server is restarted or the system is rebooted.)

The UCM event logger records events such as device connections and disconnections and certain types of errors. To see this information, use the UCM utility SHOW EVENTS command. You can also use qualifiers to limit the display of various types of events.

Events stored in the event log include the following:

• A device was configured or unconfigured.
• A known device was connected but not configured.
• An unknown device was connected.
• Text messages were sent by USB drivers.

The following sections explain how to display information about unknown devices and configuration failures.

25.5.1 Getting Information About Unknown Devices

UCM records unknown device connections in its event log. You can view this information by adding the /TYPE=UNKNOWN qualifier to the SHOW EVENT command.

The information in the following example includes the vendor ID, the product ID, and other optional device-supplied information. If an unknown device is connected to the USB, you might want to view only events showing the activity of unknown devices for today; for example:

UCM> SHOW EVENTS /TYPE=UNKNOWN /SINCE=TODAY Date Time Type Priority Component -------------------------------------------------------------------------------- 22-AUG-2005 13:04:23.26 UNKNOWN NORMAL UCM UNKNOWN DEVICE Message: VENDOR_ID = 1118 PRODUCT_ID = 8 RELEASE_NUMBER = 256 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 MANUFACTURER_STRING = Microsoft PRODUCT_STRING = Microsoft SideWinder Precision Pro (USB) CONFIGURATION_NUMBER = 0. UCM>

Note that the display on your screen might be somewhat different from the one you see here.

25.5.2 Getting Information about Configuration Failures

When UCM does not configure a device---because UCM cannot find an entry in the permanent list or because of a driver error---it stores this information in the event log. You can view such information using the SHOW EVENTS command and a qualifier that limits the display. The following is an example of plugging in a joystick with a missing device driver.

UCM> SHOW EVENTS /SINCE=YESTERDAY Date Time Type Priority Component _________________________________________________________________________ 3-OCT-2005 09:06:11.20 UCM NORMAL SYS$AGDRIVER.EXE Message: Tentative device AGA0 proposed... auto-loading driver. 3-OCT-2005 09:06:11.20 UCM NORMAL SYS$AGDRIVER.EXE Message: Error from auto-load for AGA0 - status 0x18292. 3-OCT-2005 09:06:11.20 DRIVER NORMAL HUBDRIVER Message: Configured device HID0 using driver SYS$HIDDRIVER: UCM> exit

Note that the display on your screen might be somewhat different from the one you see here.

If no entry for the device is in the generic list, the log displays what is known about the device. If an error caused the failure, the error code is listed in the log.

You can use UCM commands to select the devices you want to configure and to view USB events such as connections, disconnections, and errors.

For a more detailed discussion of how you would add a device using UCM, see SYS$COMMON:[SYSHLP.EXAMPLES.USB]UGDRIVER_PROGRAMMERS_GUIDE in .PS, .PDF, AND HTML formats. This document tells how to use the USB generic driver and how to add USB generic entries.

25.6 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.

To invoke UCM, enter UCM at the DCL command prompt ($):

$ UCM UCM>

At the UCM> prompt, you can enter any UCM command described briefly in Section 25.7 and in more detail in the following sections.

Alternatively, you can enter UCM commands at the DCL prompt if you precede them with UCM. For example:

$ UCM RELOAD $

To exit from UCM, enter the EXIT command at the UCM> prompt, or press Ctrl/Z.

25.7 UCM Commands

The following table summarizes 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 AUTO	Enables (/ENABLE) or disables (DISABLE) auto-loading and permanence. Also allows setting both exclude and include lists.	SYSPRV
SET LOG/NEW	Creates a new version of the event log file.	OPER
SHOW AUTO	Displays the settings of auto-load, auto-perm, and include and exclude lists.	None
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, the unit number (which can be 1 to 4 characters long), and, finally, 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 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 identify a device uniquely 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 25-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                AGA 
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                AGA 
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, the unit number (which can be 1 to 4 characters long), and, finally, a colon (:).

Example

$  UCM
Universal Serial Bus Configuration Manager, Version V1.0
UCM> SHOW DEVICE /PERMANENT AGA0:
DEVICE 
DEVICE_TYPE                     PERMANENT 
DEVICE_NAME_ROOT                AGA 
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.  Use this command 
     only if the server is no longer responding to configuration requests 
     or if the server does respond to client commands.  To use 
     this command, you must have 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.