| 1 | Device name | Input | Char(10) |
| 2 | Requested function | Input | Binary(4) |
| 3 | Send buffer | Input | Char(*) |
| 4 | Length of send buffer | Input | Binary(4) |
| 5 | Receive buffer | Output | Char(*) |
| 6 | Length of receive buffer | Input | Binary(4) |
| 7 | Command format | Input | Char(8) |
| 8 | Command data | Input | Char(*) |
| 9 | Length of command data | Input | Binary(4) |
| 10 | Error code | I/O | Char(*) |
The Control Device (QTACTLDV) API provides a direct command interface to a device. The caller of this API can issue any command directly to a device and transfer data to or from the device.
Note: For tape devices, the Retrieve Device Capabilities (QTARDCAP) API can be used to determine if the tape device supports the QTACTLDV API. Other kinds of devices currently do not support this API. This API can be used for a tape device within a media library if the device is deallocated from the library.
Note: Incorrect use of this API can cause damage to data saved on tape media or can interfere with I/O processor function.
The device description to which the request is sent.
The function to perform. The possible values are:
| 1 | Open a connection to the device. This function must be performed before any commands can be sent to the device. The device must be varied on before this function is performed. No other job can use the device while the connection is open. |
| 2 | Send a command to the device. When running in a multithreaded environment, a command sent by a thread must be complete before another command can be sent by another thread. |
| 3 | Close the connection to the device. This function must be performed after the user has completed sending commands to the device. No other job can use the device until the connection is closed. |
A buffer containing data to send to the device when a data transfer command is sent. No support is provided to send and receive data on the same command.
This parameter is ignored if the length of the send buffer is 0.
The length of the send buffer.
This parameter must be 0 for the open connection and close connection functions.
A buffer to store data received from the device after a data transfer command is sent. No support is provided to send and receive data on the same command.
This parameter is ignored if the length of the receive buffer is 0.
The length of the receive buffer.
This parameter must be 0 for the open connection and close connection functions.
The format of the command data. The following format is supported.
Note: The connection must be opened using the open function before a command can be issued to the device.
See CTLD0100 Format for more information on the command data format.
The variable that contains the command data.
This parameter is ignored if the length of command data is set to 0.
The length of the command data to be sent to the device. The command data must be 0, or a minimum of 32 bytes long and a maximum of 56 bytes long.
This parameter must be 0 for the open connection and close connection functions.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table shows the command information that is required for the
CTLD0100 format. For more details about the fields in the following table, see
Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Data transfer direction |
| 4 | 4 | BINARY(4) | Requested transfer length |
| 8 | 8 | BINARY(4) | Ignore length errors |
| 12 | C | BINARY(4) | Command timeout value |
| 16 | 10 | BINARY(4) | Type of command |
| 20 | 14 | BINARY(4) | Offset to command string |
| 24 | 18 | BINARY(4) | Length of command string |
| 28 | 1C | BINARY(4) | Reserved |
| CHAR(*) | Command string | ||
Command string. The command string to send to the device. See the device specifications to determine what command strings are supported by the device.
Command timeout value. The time, in seconds, to wait for the command to complete. Valid values are 1 through 7200.
Data transfer direction. The direction of any data transfer associated with the command. The possible values are:
| 0 | No data transfer. |
| 1 | Receive data from the device. |
| 2 | Send data to the device. |
Ignore length errors. The possible values are:
| 0 | Report length errors. |
| 1 | Ignore length errors. |
Length of command string. The length of the command string to send to the device. Valid values are 0 through 24.
Offset to command string. The offset from the start of the command data, in bytes, to the start of the command string. Valid values are 32 and greater.
Requested transfer length. The expected length of the data to be transferred by the command. The requested transfer length must be less than or equal to the length of the buffer parameter that will be used to send or receive the data.
Note: This field must be 0 for commands with no data transfer.
Reserved. An ignored field. This value must be set to 0.
Type of Command. The type of command. The possible values are:
| 0 | Small Computer System Interface (SCSI) command. |
| 1 | Reset the device. |
For descriptions of the reason codes in CPF67C8, see Reason Codes.
| Message ID | Error Message Text |
|---|---|
| CPF222E E | &1 special authority is required. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C4C E | Value not valid for field &1. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF6708 E | Command ended due to error. |
| CPF67C8 E | Command failed for device &1. Reason code &2. |
| CPF9814 E | Device &1 not found. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
This topic contains the description of the reason codes returned in message CPF67C8.
Note: For command timeouts, I/O processor errors, system bus errors, and device bus errors, a reset operation might occur on the device bus. Other devices attached to the same bus may be affected by this reset operation.
Possible reason code values are:
| '010300'x | Command length not valid: The command length was too long for existing device interface specifications. |
| '010700'x | Data length not valid: The IOP does not support the size of the data transfer. Use the Retrieve Device Capabilities (QTARDCAP) API to determine the maximum block size supported. |
| '020900'x | Insufficient data: The data transfer buffer is not large enough. |
| '02C0yy'x | Device detected error: The tape device reported an error condition. For an SCSI type of command, yy is set to the value of the completion status. |
| '02C100'x | Selection timeout: The tape device did not respond to the command. Check device power and cables and retry the command. If the problem persists, contact your hardware service provider. |
| '02C200'x | I/O processor length error: Length error on the data transfer. The ignore length errors field was not set in the command data. |
| '02C300'x | I/O processor error: The I/O processor card detected an internal hardware failure. Contact your hardware service provider. |
| '02C400'x | Command timed out: The tape device did not complete the requested command within the specified time. Correct the command timeout value and retry the command. If the problem persists, contact your hardware service provider. |
| '02C500'x | System bus error: The host internal system bus failed. Contact your hardware service provider. |
| '02C600'x | Device bus error: The I/O processor detected a failure in the device interface. Check the device power and cables and retry the command. If the problem persists, contact your hardware service provider. |
| '02C700'x | Device detected error: The device rejected a microcode update. |
| '100000'x | Open failure: A connection could not be opened to the device. The device may not be varied on or is being used by another job. |
| '100001'x | Open failure: A connection could not be opened to the device. The device does not support the QTACTLDV API. |
| '100002'x | Open failure: A connection could not be opened to the device. The device is in a failed state. |
| '200000'x | Close failure: The connection to the device could not be closed. The device may not be varied on or is being used by another job. |
| '200002'x | Close failure: The connection to the device could not be closed. The device is in a failed state. |
| '300000'x | Device not valid: The device specified is not a tape device. |
| '300001'x | Resource not valid: The resource name associated with the specified device is not valid or does not exist. |
| '400000'x | Connection not open: The command could not be completed because there is not an open connection. |
When running in a multithreaded environment, a command sent by a thread to a device must be complete before a command can be sent by another thread to the same device.
See Examples: Using the Control Device (QTACTLDV) API for examples of how to use the QTACTLDV API.