Writing a Define Method

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

Syntax

defDev  -c Class -s SubClass -t Type [  -p Parent  -w Connection  ] [  -l Name  ]

Description

The Define method is responsible for creating a customized device in the Customized database. It does this by adding an object for the device into the Customized Devices (CuDv) object class. The Define method is invoked either by the mkdev configuration command, by a node configuration program, or by the Configure method of a device that is detecting and defining child devices.

The Define method uses information supplied as input, as well as information in the Predefined database, for filling in the CuDv object. If the method is written to support a single device, it can ignore the class, subclass, and type options. In contrast, if the method supports multiple devices, it may need to use these options to obtain the PdDv device object for the type of device being customized.

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

Flags

Guidelines for Writing a Define Method

This list of tasks is meant to serve as a guideline for writing a Define method. In writing a method for a specific device, some tasks may be omitted. For instance, if a device does not have a parent, there is no need to include all of the parent and connection validation tasks. Additionally, a device may have special needs that are not listed in these tasks.

The Define method must:

1. Validate the input parameters. Generally, a Configure method that invokes the child-device Define method is coded to pass the options expected by the child-device Define method. However, the mkdev command always passes the class, subclass, and type options, while only passing the other options based on user input to the mkdev command. Thus, the Define method may need to ensure that all of the options it requires have been supplied. For example, if the Define method expects parent and connection options for the device being defined, it must ensure that the options are supplied. Also, a Define method that does not support the -l name specification option will exit with an error if the option is supplied.
2. Initialize the Object Data Manager (ODM) using the odm_initialize subroutine and lock the configuration database using the odm_lock subroutine. The following code fragment illustrates this process:

   #include <cf.h>
    
   if (odm_initialize() < 0)
           exit(E_ODMINIT);         /* initialization failed */
    
   if (odm_lock("/etc/objrepos/config_lock",0) == -1) {
           odm_terminate();
           exit(E_ODMLOCK);        /* database lock failed */
   }

3. Retrieve the predefined PdDv object for the type of device being defined. This is done by obtaining the object from the PdDv object class whose class, subclass, and type descriptors match the class, subclass, and type options supplied to the Define method. If no match is found, the Define method will exit with an error. Information will be taken from the PdDv device object in order to create the CuDv device object.
4. Ensure that the parent device exists. If the device being defined connects to a parent device and the name of the parent has been supplied, the Define method must ensure that the specified device actually exists. It does this by retrieving the CuDv object whose Device Name descriptor matches the name of the parent device supplied using the -p flag. If no match is found, the Define method will exit with an error.
5. If the device has a parent and that parent device exists in the CuDv object class, validate that the device being defined can be connected to the specified parent device. To do this, retrieve the predefined connection object from the Predefined Connection (PdCn) object class whose Unique Type, Connection Key, and Connection Location descriptors match the Link to Predefined Devices Object Class descriptor of the parent's CuDv object obtained in the previous step and the subclass and connection options input into the Define method, respectively. If no match is found, an invalid connection is specified. This may occur because the specified parent is not an intermediate device, does not accept the type of device being defined (as described by subclass), or does not have the connection location identified by the connection option.
6. Assign a logical name to the device. Each newly assigned logical name must be unique to the system. If a name has been supplied using the -l flag, make certain it is unique before assigning it to the device. This is done by checking the CuDv object class for any object whose Device Name descriptor matches the desired name. If a match is found, the name is already used and the Define method must exit with an error.

   If the Define method is to generate a name, it can do so by obtaining the prefix name from the Prefix Name descriptor of the device's PdDv device object and invoking the genseq subroutine to obtain a unique sequence number for this prefix. Appending the sequence number to the prefix name results in a unique name. The genseq routine looks in the CuDv object class to ensure that it assigns a sequence number that has not been used with the specified prefix to form a device name.

   In some cases, a Define method may need to ensure that only one device of a particular type has been defined. For example, there can only be one pty device customized in the CuDv object class. The pty Define method does this by querying the CuDv object class to see if a device by the name pty0 exists. If it does, the pty device has already been defined. Otherwise, the Define method proceeds to define the pty device using the name pty0.

7. Determine the device's location code. If the device being defined is a physical device, it has a location code. "Device location codes" in AIX® Version 7.1 Operating system and device management has more information about location codes.
8. Create the new CuDv object.

   Set the CuDv object descriptors as follows:

   Descriptor	Setting
   Device name	Use the name as determined in step 6.
   Device status flag	Set to the Defined state.
   Change status flag	Set to the same value as that found in the Change Status Flag descriptor in the device's PdDv object.
   Device driver instance	Set to the same value as the Device Driver Name descriptor in the device's PdDv object. This value may be used later by the Configure method.
   Device location code	Set to a null string if the device does not have a location code. Otherwise, set it to the value computed.
   Parent device logical name	Set to a null string if the device does not have a parent. Otherwise, set this descriptor to the parent name as specified by the parent option.
   Location where connected on parent device	Set to a null string if the device does not have a parent. Otherwise, set this descriptor to the value specified by the connection option.
   Link to predefined devices object class	Set to the value obtained from the Unique Type descriptor of the device's PdDv object.

9. Write the name of the device to standard output. A blank should be appended to the device name to serve as a separator in case other methods write device names to standard output. Either the mkdev command or the Configure method that invoked the Define method will intercept standard output to obtain the device name assigned to the device.
10. Close all object classes and terminate the ODM. Exit with an exit code of 0 if there were no errors.