Device Selection Exit Program

The Device Selection exit program provides an interface to control virtual device selection and automatic creation used by the system for connection requests from clients using virtual device support. The interface allows the user to write an exit program to specify the naming conventions used for automatically created virtual devices and virtual controllers and to specify the automatic creation limit to be used for the specific request.

The exit program can:

1. Reject a specific name for a device connection request.
   
   
2. Specify a naming pattern to be used for the automatic creation of a virtual device. This is used only if a specific device name was not requested on the client's connection request.
   
   
3. Specify the naming pattern of the virtual controller to be used:
   • to search in an attempt to select an existing device (if a specific device name was not requested on the client's connection request) or to specify a controller to which to attach the automatically created device.
   • This naming pattern is also used to 'count' the number of existing devices toward the automatic creation limit.
   • Specify a second controller naming pattern to be used to 'count' the number of existing virtual devices.
     
     
   • Specify the number of devices that can exist on the virtual controllers whose naming pattern is specified.

Authorities and Locks

You must have *ALLOBJ authority to register an exit program for the QIBM_QPA_DEVSEL exit point.

Required Parameter Group

Format name

INPUT; CHAR(8)

The format of the information provided in the Device selection information parameter. The format name is PDSC0100.

Device selection information

INPUT/OUTPUT; CHAR(*)

The structure containing the data that is being passed to the exit program and that is returned from the exit program.

Return code

OUTPUT; BINARY(4)

Whether to allow the connection request to continue. The possible values are:

0	Do not allow connection request.
1	Allow connection request.

If any other value is returned, the request for selection and automatic creation of a device description for the client request will be processed using the system defaults for the QAUTOVRT system value and the defaults for the device and controller naming conventions.

This parameter is initialized to 0 on the call to the exit program.

PDSC0100 Format

For details about the fields in the following table, see Field Descriptions.

PDSR0100 Format

For details about the fields in the following table, see Field Descriptions.

Field Descriptions

Additional controller naming pattern. The naming pattern for the controllers to be used for the device automatic creation limit. When applying the check for automatic creation limit, devices attached to these controllers are also counted when determining ifr the limit is exceeded. This field is initialized to blanks before the call is made to the exit program.

Autocreation limit. The number to be used for the virtual device automatic creation limit for this connection request. Possible values are:

Controller naming pattern for device attachment. The naming pattern for the controller to which an automatically created device is to be attached. These characters must be a valid input to the CRTCTLVWS command. If there are not six characters, the pattern is padded with zeros. If the Autocreation limit is 1-32500, the devices attached to controllers with this pattern are counted and this number is used toward the automatic creation limit. This field is initialized to blanks before the call is made to the exit program.

Format of returned data. The format name specified by the user exit program for the output data returned from the Device Selection exit point. The only format supported currently is PDSR0100. This field is initialized to PDSR0100 on the call to the exit program.

Function. The function being used by the client. Possible values are:

Name for requested device. The name of the device requested by the client. If Specific name requested is set to 0, this field is blank.

Naming pattern for device. The naming pattern to be used for device automatic creation. These characters must be a valid input to the CRTDEVDSP command. This field is checked only if the Specific name requested field is 0. This field is initialized to blanks before the call is made to the exit program.

Reserved. A reserved field that must be set to hexadecimal zeros.

Size of structure. The size of the structure containing the data being passed to and returned from the exit program.

Specific name requested. Whether a specific name was requested by the client. If a specific name was requested, this name will be passed to the exit program in the Name for requested device field.

Coding Guidelines

Applications should consider the following when coding this exit program:

• The program should return an exception for the requested operation only if there has been a failure in the operation. If the program signals an escape message to the API, the system assumes there is a failure. A diagnostic message is returned to the calling program. The request for selection and automatic creation of a device description for the client request will be processed using the system defaults for the QAUTOVRT system value and the defaults for the device and controller naming conventions.
  
  
• The program must clean up any locks that it acquires.
  
  
• The program must handle all potential error conditions associated with its own operations (be fault tolerant).
  
  
• The program must avoid infinite looping conditions.