A UIM is called with a request for initialization by

• HCD initialization
• IPL processing
• Dynamic activation

As already mentioned, a UIM must be able to handle an initialization request. During this call, the UIM "registers" to HCD any control unit type, I/O device type, or ESCON director type (switch) it defines. Only I/O units that are registered to HCD are later accepted as valid.

• To register a control unit type, the UIM must set up the control unit information parameters (CIP) and then call the CIT build routine. The CIP contains descriptive information about the control unit, such as maximum and default values, as well as the list of devices that can be attached to the control unit. The entry point address of the CIT build routine is contained in the UCA. See CIT Build Routine for details on how to call the CIT build routine.

  The UIM must repeatedly call the CIT build routine for each control unit type it defines.

• To register an ESCON director type, the UIM must set up the switch information parameters (SIP) and then call the SIT build routine. The entry point address of the SIT build routine is contained in the UCA. The SIP contains descriptive information about the switch, such as valid port range and attachment information. See SIT Build Routine for details on how to invoke the SIT build routine.

  The UIM must repeatedly call the SIT build routine for each switch type it defines.

• Prior to registering any I/O device, the UIM must register the generic device type of the devices. This is done by setting up the generic information parameters (GIP) and then calling the GIT build routine. See GIT Build Routine for details on how to call the GIT build routine. The UIM must repeatedly call the GIT build routine for each generic device type.
• To register an I/O device type, the UIM must set up the unit information parameters (UIP) and then call the UIT build routine. The UIP contains relevant information about the device. In detail, the UIP consists of multiple sections:
  • A general section containing device type/model and other data that define the physical characteristics of the device as well the list of devices that are look-alikes.
  • An MVS section containing the MVS parameters and features, default values, and so forth.

  See UIT Build Routine for details on how to call the UIT build routine.

  The UIM must repeatedly call the UIT build routine for each device type/model it defines.

  If the device is a DASD device, the UIM must also define the physical DASD characteristics of the device, such as number of cylinders and tracks. This is done by setting up the device characteristics parameters (DCP) and then calling the DCT build routine. See DCT Build Routine for details on how to call the DCT build routine.

Device Parameter Validation Request

If the UIM indicates, through its unit information table (UIT), that device parameters can or must be specified, HCD calls the UIM with a request to validate all specified device parameters.

Device parameters are either common or private. Common parameters apply to all devices in the system, such as the DYNAMIC parameter (see Summary of Device Information for a list of common parameters). Private parameters apply only to the device they are defined to, such as the LIBRARY parameter of a 3480 or 3490 device type. When you write an HCD UIM, you can define common and private parameters for the device supported by that UIM.

If called to perform the device parameter validation for the device(s) described in the IODV, the UIM must validate the specified parameters. The UIM does not need to check if required parameters are present; this has been already ensured by HCD validation. HCD validates the following definitions:

• The parameter is supported for the device type
• Required parameters are specified
• The type of private parameter value is correct - hex, decimal, value within defined decimal range
• If a selection list is specified for a parameter value, the value is contained in the selection list.

The UIM must validate only the parameter value. The IODV contains a bitstring (IODVPARM) that indicates which parameters are specified. If the bit is on, the corresponding parameter is present. The position of the bit, representing a parameter, in the bitstring is given by the parameter identifier. See the CBDZUDT macro for the mapping of the parameter identifiers.

The values of the common parameters, which are parameters with identifiers in the range from 1 - 32, are contained in the IODV. HCD has already ensured that the parameter value is correct from the syntax point of view. For example, the SETADDR parameter must be a decimal number; in this case, HCD has already verified that the user's specification for SETADDR is decimal and can fit in the field provided in the IODV for the SETADDR parameter.

Common parameters for which a selection list was specified at "registration" time do not need to be validated. HCD has already verified that the specified value is one of the choices in the parameter selection list.

If a parameter can contain only Yes or No, it does not require any additional validation logic. HCD has already verified that either Yes or No was specified. The IODV contains a flag for each Yes/No parameter that, if set, indicates that "Yes" was specified for the parameter.

Private parameters require a slightly different handling. The values for private parameters, which are parameters with identifiers in the range from 33 - 64, are contained in the private parameter value array (PPVA) rather than the IODV. The PPVA is pointed to by IODVPPVA in the IODV. The PPVA is an array of 64 entries, one for each possible parameter. The parameter identifier can be used as an index into the PPVA. Like the common parameters, the private parameters are already verified for correct syntax according to the parameter syntax description in the UDT. The format of the parameter value stored in the PPVA depends on the type of the parameter defined in the UDT.

• If the parameter type is numeric, its value is stored in a 4-byte binary field (fullword).
• If the parameter type is hexadecimal, its value is stored in a field with a length specified in the UDT, right-justified, converted to binary and filled with leading zeros.
• If the parameter type is either alphanumeric or character, its value is stored in a field with a length specified in the UDT, left-justified, and padded with blanks.
• If the parameter type is "YESNO", its value is either PPVAYES or PPVANO, stored in a 1-byte character field.
• If the parameter type is none of the above, its value is stored as is in a field with the length specified in the UDT and padded with blanks.

If the UIM detects an error, it must

• Indicate which parameter was incorrectly specified (using the parameter identifier) in the UCAPID field in the UCA.
• Issue an error message, explaining what was wrong, by means of the CBDIMSG macro.
• Set the error return code in the UCA

If the parameter validation requires additional information that is not supplied in the IODV, the UIM might call the device lookup routine to get information about:

• All devices attached to the same control unit
• All devices grouped together by means of the same PCU value
• Control unit data for a particular control unit (type/model)
• Device data for a particular device, identified by its device number.

See Device Lookup Routine for more details about how to call the device lookup routine. The device lookup routine returns device information for just one device at a time. The device data is returned in the form of an IODV without the PPVA. The UIM must repeatedly call the Device Lookup Routine using the same, unmodified DEVL parameter list to pick up the data for other devices.

If the generic device type varies depending on the specification of certain parameters or features, the UIM might specify a new generic device type for the device by calling the generic update routine and passing the new generic name, a generic name that must have been previously defined as a valid generic. See Generic Update Routine for more details on how to call the generic update routine. Calling the generic update routine is only allowed when the UIM indicated in the UIP at initialization time that the generic device type might change.

Device Feature Validation Request

If called to perform the device feature validation for the device(s) described in the IODV, the UIM must validate whether two specified features are mutually exclusive or the presence of one feature requires another feature to be specified. The UIM does not have to validate whether the specified feature is supported or compatible, HCD already does that validation.

Whether or not a feature is specified is indicated in the IODVFEAT bitstring, where each feature is represented by one bit. If the bit is on, the feature is specified. The order of the bits is determined by the order of the feature definitions in the UIM's associated UDT.

If the UIM detects an error, it must

• Indicate in field UCAPID in the UCA that the error occurred while checking the device features.
• Indicate in field UCAPPOS in the UCA which feature was incorrectly specified (by specifying the offset in the bitstring).
• Issue an error message, explaining what was wrong, by means of the CBDIMSG macro.
• Set the error return code in the UCA

The UIM might also set default features by setting the appropriate bit in the feature bit string (IODVFEAT). This has the same effect as if the HCD user had specified the feature.

Device Number Validation Request

If called to perform device number validation for the device(s) described in the IODV, the UIM might validate the device number for special rules (for example low order digits=zero). Note, that the UIM might be called for a range of devices. The range value is contained in the IODV (IODVNBRD). Each device number in the range must be checked for correctness.

If the UIM detects an error, it must:

• Use the CBDIMSG macro to issue an error message that gives information about the erroneous device
• Set the error return code in the UCA.

Device Unit Address Validation Request

If called to perform the unit address validation for the device(s) described in the IODV, the UIM might validate the unit address for special rules (for example, low order digit=zero). Note, that the UIM might be called for a range of devices. The range value is contained in the IODV (IODVNBRD). Each unit address in the range must be checked for correctness. The unit address of the first device is contained in IODVUNIA.

If the UIM detects an error, it must:

• Use the CBDIMSG macro to issue an error message that gives information about the erroneous device
• Set the error return code in the UCA.

Device Feature Table Build Request

Device feature tables (DFTs) are required by:

• The IPL and dynamic activation process to build unit control blocks (UCBs) for each device contained in the configuration
• The HCD report function to generate the device report

If called to perform the DFT build for the device(s) described in the passed IODV, the UIM must set up the device feature parameters (DFP) and then call the DFT build routine. The entry point address of the DFT build routine is contained in the UCA. The DFP contains information used to construct the UCB for the device. See DFT Build Routine for details on how to call the DFT build routine.

The UIM might be called with the DFT build request for a range of devices; the range value (IODVNBRD) is contained in the IODV. In this case, the UIM must call the DFT build routine repeatedly for each device in the range.

In the case of a multiple exposure device (supported in a system prior to MVS/ESA SP 5.2), the UIM is only called for the base exposure device. The UIM, however, must call the DFT build routine for each non-base exposure. For a parallel access volume, the UIM is called only for the base device number. At that time, the UIM must also build a DFT for each alias device number.

Because a group of devices might share the same

• Device dependent segment
• Device class extension
• Device dependent extension

the DFT build routine returns the addresses of the listed areas in the UCA. These areas might then be updated during the end-of-data request.

End-of-data Request

For IPL, the UIM is called with this request only if the UCAEODAT flag is set in the UCA on return of the initialization request. This is only of interest when the device dependent segment, device dependent extension, or device class extension of the UCB needs to be updated for a group of devices sharing the same data.

In this case, the UIM must collect the necessary data while handling the DFT build requests for all devices defined for the operating system in the IODF.

The UIM must not issue any message while handling this request.