Put Input Command (QsnPutInpCmd) API

The Put Input Command (QsnPutInpCmd) API is used to issue data stream input commands that are not directly supported through a DSM API. An Escape (X'04') character is inserted in the stream directly before the command itself for both direct and indirect operations.

You must use this operation to issue an input command that is not directly supported by DSM as this will cause the appropriate underlying screen I/O operation to occur in order to retrieve input. You cannot, for example, use the Put Output Command (QsnPutOutCmd) API to issue an input command because no input data will be requested by the underlying DSM screen I/O operation.

The following command buffer handle and input buffer handle combinations are valid.

• The command buffer handle is specified with a nonzero value. The input buffer handle is omitted or specified with a zero value.

  This is an indirect operation. The command is stored in the command buffer without an I/O operation taking place.

• The command buffer handle is omitted or specified with a zero value. The input buffer handle is specified with a nonzero value.

  This is a direct operation. The input operation is issued to the screen, and the resulting input data is stored in the input buffer.

• Both a command buffer handle and an input buffer handle are specified with nonzero values.

  This is a direct operation. The input operation is appended to the command stream given by the command buffer, and the entire command stream is written to the display. The resulting input data is stored in the input buffer. The contents of the command buffer are not affected by this operation. That is, the input operation is not stored in the command buffer.

This operation corresponds to an Escape character followed by the specified command.

Authorities and Locks

None

Required Parameter

Command

INPUT; CHAR(1)

The 1-byte character code for the input command to be issued. For example, to issue a Save Partial Screen command, the command data should contain X'03' and the command data will contain the dimensions of the partial screen to be saved.

Omissible Parameter Group

Command data

INPUT; CHAR(*)

The data for the command to be issued.

Command data length

INPUT; BINARY(4)

The length of the command data parameter.

Number of data bytes read

OUTPUT; BINARY(4)

The variable that contains the number of data bytes returned after the QsnPutInpCmd API has completed if a direct operation is specified. The parameter is not modified for an indirect operation and the value remains unchanged from whatever was passed.

Input buffer handle

INPUT; BINARY(4)

A handle for the input buffer that receives the result of the input operation if a direct operation is specified.

Command buffer handle

INPUT; BINARY(4)

A handle for the command buffer in which to store the command.

Low-level environment handle

INPUT; BINARY(4)

The low-level environment that the operation applies to. If this parameter is omitted or given with a value of zero, the default low-level environment is used.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Returned Value

Number of data bytes read

OUTPUT; BINARY(4)

This API returns the value for the number of data bytes read parameter if a direct operation was specified, or -1 if an error occurs during processing. If this is an indirect operation, this API returns zero if successful, or -1 if there was a general failure.

Error Messages