Read Modified Fields (QsnReadMDT) API

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:

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

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