Read Modified Fields (QsnReadMDT) API

Required Parameter Group:

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

Omissible Parameter Group:

3	Field count	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:

Field count

Output

Binary(4)

  Default Public Authority: *USE

  Service Program: QSNAPI

  Threadsafe: No

The Read Modified Fields (QsnReadMDT) API reads the contents of all modified fields on the screen 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. See Control Characters for a description of the control character values. The format of the data returned is:

Cursor Row/Column
2 bytes

AID Code
1 byte

SBA
X'11'

Field Row/Column
2 bytes

Field Data

SBA
X'11'

Field Row/Column
2 bytes

Field Data

The field data returned for transparent fields and CCSID-capable fields (created with QsnSetFldCC) includes an additional order and a length:

Field Data

Inbound Transparent Data order
X'10'

Length of the following data
2 bytes

Transparent data or data in Field CCSID

The information returned depends on the state of the MDT bit for each field (see Modified Data Tag (MDT) Bit) and the AID-generating key used. If no bits are set, the input returned consists of the cursor address and an AID code only. If at least one bit is set, the input may also include field data. In each 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.

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

Roll Up

Roll Down

Enter/Auto Record Advance

An unmasked command function key

The field data, when returned, consists of the row and column address and the contents of each field that has an MDT bit on as they appear on the display, unless resequencing has been specified. (See Resequencing.) The input buffer query routines Retrieve Number of Fields Read (QsnRtvFldCnt) API and Retrieve Field Information (QsnRtvFldInf) API can be used to retrieve the value for each field. (To interpret the data directly, QsnRtvDta can be used to obtain a pointer for the data portion of the input buffer. The first data byte will be the SBA order for the first field as defined in the 5250 data stream documentation.)

Data for nontransparent fields is formatted as follows:

Leading and embedded nulls within the field are translated to blanks, and trailing nulls are stripped off. Only the field's address is returned for fields whose MDT bit is on but which consist entirely of nulls.
If the specified field is a signed numeric field:
- The last character of the field is stripped off unless it was previously stripped because it was null.
- 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'.

If the field is a transparent or CCSID-capable field, no formatting is performed.

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 MDT Fields command.

Restrictions

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 or 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

Field count: OUTPUT; BINARY(4)
The variable that contains the number of input fields read after the QsnReadMDT 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

Field count: OUTPUT; BINARY(4)
This API returns the value for the field count 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.
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 ]