Read Input Fields (QsnReadInp) API

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

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