Writing a Change Method

This article describes how a Change device method works. It also suggests guidelines for programmers writing their own Change device configuration methods.

Syntax

chgDev -l Name [  -p Parent ] [  -w Connection ] [  -P |  -T ] [  -a Attr=Value [ -a Attr=Value  ... ] ... ]

Description

The Change method applies configuration changes to a device. If the device is in the Defined state, the changes are simply recorded in the Customized database. If the device is in the Available state, the Change method must also apply the changes to the actual device by reconfiguring it.

A Change method does not need to support all the flags described for Change methods. For example, if your device is a pseudo-device with no parent, it need not support parent and connection changes. For devices that have parents, it may be desirable to disallow parent and connection changes. For printers, such changes are logical because they are easily moved from one port to another. By contrast, an adapter card is not usually moved without first shutting off the system. It is then automatically configured at its new location when the system is rebooted. Consequently, there may not be a need for a Change method to support parent and connection changes.

Note: In deciding whether to support the -T and -P flags, remember that these options allow a device's configuration to get out of sync with the Configuration database. The -P flag is useful for devices that are typically kept open by the system. The Change methods for most supported devices do not support the -T flag.

In applying changes to a device in the Available state, the Change method could terminate the device from the driver, rebuild the device-dependent structure (DDS) using the new information, and redefine the device to the driver using the new DDS. The method may also need to reload adapter software or perform other device-specific operations. An alternative is to invoke the device's Unconfigure method, update the Customized database, and invoke the device's Configure method.

By convention, the first three characters of the name of the Change method should be chg. The remainder of the name (Dev) can be any characters, subject to operating system file-name restrictions, that identify the device or group of devices that use the method.

Flags

Item Description
-l Name Identifies the logical name of the device to be changed.
-p Parent Identifies the logical name of a new parent for the device. This flag is used to move a device from one parent to another.
-w Connection Identifies a new connection location for the device. This flag either identifies a new connection location on the device's existing parent, or if the -p flag is also used, it identifies the connection location on the new parent device.
-P Indicates that the changes are to be recorded in the Customized database without those changes being applied to the actual device. This is a useful option for a device which is usually kept open by the system such that it cannot be changed. Changes made to the database with this flag are later applied to the device when it is configured at system reboot.
-T Indicates that the changes are to be applied only to the actual device and not recorded in the database. This is a useful option for allowing temporary configuration changes that will not apply once the system is rebooted.
-a Attr=Value Specifies the device attribute value pairs used for changing specific attribute values. The Attr=Value parameter contains one or more attribute value pairs for the -a flag. If you use a -a flag with multiple attribute value pairs, the list of pairs must be enclosed in quotes with spaces between the pairs. For example, entering -a Attr=Value lists one attribute value pair, while entering -a 'Attr1=Value1 Attr2=Value2' lists more than one attribute value pair.

Guidelines for Writing a Change Method

This list of tasks is intended as a guideline for writing a Change method. When writing for a specific device, some tasks may be omitted. For example, if a device does not support the changing of a parent or connection, there is no need to include those tasks. A device may have special needs that are not included in these tasks.

If the Change method is written to invoke the Unconfigure and Configure methods, it must:

  1. Validate the input parameters. The -l flag must be supplied to identify the device that is to be changed. If your method does not support the specified flag, exit with an error.
  2. Initialize the Object Data Manager (ODM). Use the odm_initialize subroutine and lock the Configuration database using the odm_lock subroutine. See "Writing a Define Method" for an example.
  3. Retrieve the Customized Device (CuDv) object for the device to be changed by getting the CuDv object whose Device Name descriptor matches the name supplied with the -l flag. If no object is found with the specified name, exit with an error.
  4. Validate all attributes being changed. Make certain that the attributes apply to the specified device, that they can be set by the user, and that they are being set to valid values. The attrval subroutine can be used for this purpose. If some attributes have values that are dependent on each other, write the code to cross check them. If invalid attributes are found, the method needs to write information to standard error describing them. See "Handling Invalid Attributes" .
  5. Determine if a new parent device exists. If a new parent device has been specified, find out whether it exists by querying the CuDv object class for an object whose Device Name descriptor matches the new parent name. If no match is found, the method exits with an error.
  6. If a new connection has been specified, validate that this device can be connected there. Do this by querying the Predefined Connection (PdCn) object class for an object whose Unique Type descriptor matches the link to the Predefined Devices (PdDv) object class descriptor of the parent's CuDv object. The Connection Key descriptor of the CuDv object must match the subclass name of the device being changed, and the Connection Location descriptor of the CuDv object must match the new connection value. If no match is found, the method exits with an error.
  7. If a match is found, the new connection is valid. If the device is in the Available state, then it should still be available after being moved to the new connection. Since only one device can be available at a particular connection, the Change method must check for other available devices at that connection. If one is found, the method exits with an error.
  8. If the device state is Available and the -P flag was not specified, invoke the device's Unconfigure method using the odm_run_method command. This fails if the device has Available child devices, which is why the Change method does not need to check explicitly for child devices.
  9. If any attribute settings were changed, update the database to reflect the new settings. If a parent or connection changed, update the Parent Device Logical Name, Location Where Connected on Parent Device, and Location Code descriptors of the device's CuDv object.
  10. If the device state was in the Available state before being unconfigured, invoke the device's Configure method using the odm_run_method command. If this returns an error, leaving the device unconfigured, the Change method should restore the Customized database to its pre-change state.
  11. Close all object classes and terminate the ODM. Exit with an exit code of 0 if there were no errors.

Handling Invalid Attributes

If the Change method detects attributes that are in error, it must write information to the stderr file to identify them. This consists of writing the attribute name followed by the attribute description. Only one attribute and its description is to be written per line. If an attribute name was mistyped so that it does not match any of the device's attributes, write the attribute name supplied on a line by itself.

The mkdev and chdev configuration commands intercept the information written to the standard error file by the Change method. These commands write out the information following an error message describing that there were invalid attributes. Both the attribute name and attribute description are needed to identify the attribute. By invoking the mkdev or chdev command directly, the attributes can be identified by name. When using SMIT, these attributes can be identified by description.

The attribute description is obtained from the appropriate message catalog. A message is identified by catalog name, set number, and message number. The catalog name and set number are obtained from the device's PdDv object. The message number is obtained from the NLS Index descriptor in either the Predefined Attribute (PdAt) or Customized Attribute (CuAt) object corresponding to the attribute.

Writing a Device Method, ODM Device Configuration Object Classes.