Write to Display (QsnWTD) API

The Write to Display (QsnWTD) API issues a Write to Display (WTD) command. A WTD command is used to indicate the beginning of a series of output operations. For most of the DSM screen output operations, the control unit requires that a WTD be issued prior to the actual operation itself, in the same I/O operation. Multiple output operations can be sent with a given WTD command by using a command buffer. For direct operations, such output APIs, implicitly issue a WTD command. For indirect operations, a WTD is added to the buffer if one does not exist already. Each time a WTD command is received, the control unit implicitly sets the display address to row 1, column 1, prior to issuing the operation.

For example, if two direct QsnWrtDta operations are performed in succession and the second operation does not specify the row and column parameters, the data is written to row 1, column 1, and not the display address following the first QsnWrtDta operation. If two indirect QsnWrtDta operations are issued to an empty command buffer, the first QsnWrtDta operation causes a WTD command to be added to the buffer, but the second QsnWrtDta operation can use the existing command. In this case, if no row and column are specified, the display address used for the second operation will be the one after the first operation is issued. If an intervening operation that does not require a WTD, such as a QsnClrScr or a QsnSetErr, is added to the command buffer between two operations that do require a WTD command, a second WTD command is added to the buffer for the second operation.

The screen output APIs that require a WTD command and that correspond to the WTD command orders (as described in 5250 Functions Reference, SA21-9247) are as follows:

Set Output Address (QsnSetOutAdr)

Write Data (QsnWrtDta)

Write Transparent Data (QsnWrtTDta)

Pad for N Positions (QsnWrtPad)

Pad between Two Screen Addresses (QsnWrtPadAdr)

Set Field (QsnSetFld)

Set Cursor Address (QsnSetCsrAdr)

Insert Cursor (QsnInsCsr)

The cursor position is not affected if the keyboard is unlocked when command processing begins and is not locked during command processing, or if a parameter error is detected. If specified by control character byte 1, the cursor will be moved to the insert cursor or default location when the keyboard is unlocked.

This operation corresponds directly to the 5250 Write to Display command. If this is an indirect operation, this operation will issue a new WTD command to the command buffer.

Authorities and Locks

None

Required Parameter Group

Control character byte 1

INPUT; CHAR(1)

The operation for the display to perform prior to processing the Write to Display command. 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 Write to Display command has been processed. See Control Characters for a description of the control character values.

Omissible Parameter Group

Command buffer handle

INPUT; BINARY(4)

A handle for the command buffer in which to store the command. If this parameter is omitted or specified as 0, this is a direct operation and the command is sent to the display. Otherwise, this is an indirect operation and the command is stored in the command buffer without an I/O operation taking place.

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

Return code

OUTPUT; BINARY(4)

A return code indicating the result of the operation. The value returned will be 0 if the operation was successful, or -1 otherwise.

Error Messages