Control Device (QTACTLDV) API

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.

Authorities and Locks

API Public Authority

*EXCLUDE

Special Authority

*SERVICE

Device Description Authority

*CHANGE

Device Description Lock

*EXCLRD

Required Parameter Group

Device name

INPUT; CHAR(10)

The device description to which the request is sent.

Requested function

INPUT; BINARY(4)

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.

Send buffer

INPUT; CHAR(*)

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.

Length of send buffer

INPUT; BINARY(4)

The length of the send buffer.

This parameter must be 0 for the open connection and close connection functions.

Receive buffer

OUTPUT; CHAR(*)

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.

Length of receive buffer

INPUT; BINARY(4)

The length of the receive buffer.

This parameter must be 0 for the open connection and close connection functions.

Command format

INPUT; CHAR(8)

The format of the command data. The following format is supported.

CTLD0100

Issue command to a tape device.

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.

Command data

INPUT; CHAR(*)

The variable that contains the command data.

This parameter is ignored if the length of command data is set to 0.

Length of command data

INPUT; BINARY(4)

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.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

CTLD0100 Format

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.

Field Descriptions

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:

Ignore length errors. The possible values are:

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:

Error Messages

For descriptions of the reason codes in CPF67C8, see Reason Codes.

Reason Codes

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.

Usage Notes

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.

Usage Example

See Using the QTACTLDV API in API examples for an example of how to use the QTACTLDV API.