Read Immediate (QsnReadImm) API

Omissible Parameter Group:

1	Number of field data bytes read	Output	Binary(4)
2	Input buffer handle	Input	Binary(4)
3	Command buffer handle	Input	Binary(4)
4	Low-level environment handle	Input	Binary(4)
5	Error code	I/O	Char(*)

Returned Value:

Number of field data bytes read

Output

Binary(4)

  Public Default Authority: *USE

  Service Program: QSNAPI

  Threadsafe: No

The Read Immediate (QsnReadImm) API reads the contents of all input fields on the display without requiring an AID key to be pressed. The command buffer handle or input buffer handle parameter must be specified as described in Put Input Command (QsnPutInpCmd) API.

The information returned depends on the condition of the master MDT bit. (See Modified Data Tag (MDT) Bit.) If the bit is not set, the input returned consists of the cursor address and an AID code only. If the bit is set, the input returned also includes the field data in the data portion of the input buffer. In each case, the returned cursor address indicates the current location of the cursor and an AID code of X'00'. The format of the field data returned is the same as that for the Read Input Fields (QsnReadInp) API.

This command corresponds directly to the 5250 Read Immediate command.

Authorities and Locks

Restrictions

This command must be the last command in the command buffer. A CPFA305 error is issued if there is a subsequent attempt to add another command to the specified command buffer after this command.

Omissible Parameter Group

Number of field data bytes read

OUTPUT; BINARY(4)

The variable that contains the number of field data bytes returned after the QsnReadImm 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. The result can be queried using the input buffer query operations. See Retrieve Pointer to Field Data (QsnRtvFldDta) API and Retrieve Length of Field Data in Buffer (QsnRtvFldDtaLen) API.

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 field data bytes read

OUTPUT; BINARY(4)

This API returns the value for the number of field 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 otherwise.

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.
CPFA302 E	Command buffer or input buffer parameters required.
CPFA304 E	Data-stream error &1 reported for screen I/O operation.
CPFA305 E	Cannot add operation to command buffer.
CPFA309 E	Invalid cursor position in command buffer.
CPFA313 E	Command buffer already contains an input operation.
CPFA331 E	Buffer handle incorrect.
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.

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.

CPFA302 E

Command buffer or input buffer parameters required.

CPFA304 E

Data-stream error &1 reported for screen I/O operation.

CPFA305 E

Cannot add operation to command buffer.

CPFA309 E

Invalid cursor position in command buffer.

CPFA313 E

Command buffer already contains an input operation.

CPFA331 E

Buffer handle incorrect.

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.