Put Input Command (QsnPutInpCmd) API
Required Parameter:
| 1 | Command | Input | Char(1) |
Omissible Parameter Group:
| 2 | Command data | Input | Char(*) |
| 3 | Command data length | Input | Binary(4) |
| 4 | Number of data bytes read | Output | Binary(4) |
| 5 | Input buffer handle | Input | Binary(4) |
| 6 | Command buffer handle | Input | Binary(4) |
| 7 | Low-level environment handle | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Returned Value:
| Number of data bytes read | Output | Binary(4) |
Public Default Authority: *USE
Service Program: QSNAPI
Threadsafe: No
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
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFA301 E | Command buffer is full. |
| CPFA303 E | Error occurred for screen I/O operation. |
| CPFA304 E | Data-stream error &1 reported for screen I/O operation. |
| CPFA305 E | Cannot add operation to command buffer. |
| CPFA313 E | Command buffer already contains an input operation. |
| CPFA31E E | Required parameter &1 omitted. |
| CPFA331 E | Buffer handle incorrect. |
| CPFA333 E | Parameter &1 not positive integer value. |
| CPFA334 E | Low level environment handle incorrect. |
| CPFA343 E | Output operation not done. |
| CPFA344 E | The file &2 in library &3 is not valid. |
| CPFA345 E | The invite active flag is not valid. |
API introduced: V2R3
[ Back to top | Dynamic Screen Manager APIs | APIs by category ]