Read Modified Alternate (QsnReadMDTAlt) API

Required Parameter Group:

1	Control character byte 1	Input	Char(1)
2	Control character byte 1	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 Alternate (QsnReadMDTAlt) API reads the contents of all modified fields on the screen, alternate form, requiring an AID-generating key to be pressed. The QsnReadMDTAlt API is functionally equivalent to the QsnReadMDT API with the following exceptions:

Leading and embedded nulls within the fields remain nulls. However, trailing nulls are stripped off.
For fields consisting entirely of nulls, but with their MDT bit on, only the field's address is returned.

See Read Modified Fields (QsnReadMDT) API for details.

This command corresponds directly to the 5250 Read MDT Alternate command.

Authorities and Locks

None.

Restrictions

This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue this command to a control unit that does not support it.

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.

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

Field count: OUTPUT; BINARY(4)
The variable that will contain the number of input fields read after the QsnReadMDTAlt 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)
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, 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.
CPFA306 E	Command not supported by current device.
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 ]