Read Input Fields (QsnReadInp) API

Required Parameter Group:

1	Control character byte 1	Input	Char(1)
2	Control character byte 2	Input	Char(1)

Omissible Parameter Group:

3	Number of field data bytes read	Output	Binary(4)
4	Input buffer handle	Input	Binary(4)
5	Command buffer handle	Input	Binary(4)
6	Low-level environment handle	Input	Binary(4)
7	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 Input Fields (QsnReadInp) API reads the contents of all input fields on the display while requiring an AID-generating 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 format of the data returned is:

Cursor
Address in
Row/Column
FMT
2 bytes

AID Code
1 byte

Field Data

The information returned depends on the condition of the master MDT bit (see Modified Data Tag (MDT) Bit) and the AID-generating key pressed. 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 either case, the returned cursor address indicates the location of the cursor when the AID-generating key was pressed and the AID code for the AID-generating key the operator used. See AID-Generating Keys for a description of the AID-generating character values.

Field data is returned only when one of the following AID-generating keys is used:

Roll Up

Roll Down

Enter/Auto Record Advance

Auto Enter

An unmasked command function key

The field data, when returned, consists of the contents of all input fields as they appear on the display, unless resequencing has been specified. (See Resequencing.) Any attributes contained in a field are treated as data and returned as such. The attributes that start and end a field are not returned. These are considered to be outside the boundaries of the field. No field delimiters are added; data from each field is followed directly by the data from the next field. Data for nontransparent fields is formatted as follows:

All nulls (leading, embedded, or trailing) are converted to blanks.
If the specified field is a signed numeric field:
- The last character of the field is stripped off.
- The last location of the field is checked for a negative sign. If detected, the zone portion of the second to last character of the field is changed to a X'D'.

The data returned for transparent or CCSID-capable fields is not edited. A transparent field is defined with a transparency field control word X'84yy' (see Set Field (QsnSetFld) API.) The QsnSetFldCC API creates CCSID-capable fields. Each field read is returned unedited with no intervening control information. If a field is both transparent and signed numeric, unpredictable results can occur in the field data. CDRA conversion may be peformed upon this data, see Limitations and Restrictions for further details.

This command corresponds directly to the 5250 Read Input Fields command.

Restrictions

This command cannot be issued if the control unit supports ideographic data types. A CPFA306 error will occur if an attempt is made to issue this command to a control unit that supports ideographic data types.

Some control units, like those emulated by the Client Access program, do not support a control character associated with input commands. For such units, the control character specified would be ignored. A program could cause further actions to be suspended if, for example, the control character byte 2 specified to unlock the keyboard and this action was not specified elsewhere in the data stream. If the underlying control unit does not support a control character with input commands, you must specify the action to perform using the QsnWTD API.

Authorities and Locks

None.

Required Parameter Group

Control character byte 1: INPUT; CHAR(1)
The operation for the display to perform after the read operation has been serviced. See Control Characters for a description of the control character values.
Control character byte 2: INPUT; CHAR(1)
The operation for the display to perform after the read operation and control character byte 1 have been serviced. See Control Characters for a description of the control character values.

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 QsnReadInp 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.
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.
CPFA309 E	Invalid cursor position in command buffer.
CPFA313 E	Command buffer already contains an input operation.
CPFA31C E	Incorrect value for control character byte &1.
CPFA31E E	Required parameter &1 omitted.
CPFA326 E	Screen must be redrawn.
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.

API introduced: V2R3

[ Back to top | Dynamic Screen Manager APIs | APIs by category ]