Write Data with CCSID (QsnWrtDtaCC) API

The Write Data with CCSID (QsnWrtDtaCC) API writes data to the display at a given row and column using standard attributes. If a command buffer is specified that does not contain a previous or current WTD command, one is implicitly added to the buffer using the control characters QSN_CC1_NULL and QSN_CC2_UNLOCKBD. The display address after this operation will be one position past the last data character position written to the screen (including the ending screen attribute, if any).

This command corresponds indirectly to the 5250 Write to Display command (WTD) with a Set Buffer Address order and Structured Field order if the row and column are specified. (For an indirect operation, a WTD is placed in the command buffer only if one does not already exist in that buffer.)

Note: CDRA conversion is not performed upon this data.

Restrictions

If window mode is not set and the data (including attributes) exceeds the length of a row, the data will be wrapped to the next line. If bottom-to-top wrapping is not supported, a CPFA308 error occurs when the data (including attributes) exceeds the last row on the screen. If window mode is set, data that exceeds the width of the window will not be truncated or wrapped within the window, but will wrap across screen rows.

If the field ID given was created or last redefined by the QsnSetFld API, a CPFA346 will be signaled. This API should only be used to write data to CCSID-capable fields. QsnWrtDtaCC is only able to enforce this for fields that have an associated field ID, however.

QsnWrtDtaCC does not validate the data passed to it. If the data is invalid for some reason, an exception may occur if the control unit encounters improperly coded CCSID-based data. QsnWrtDta is not able to truncate data if it does not fit within the bounds of a field or low level environment window area as QsnWrtDta does for EBCDIC data.

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.

The CCSID value given must be supported by the device or emulator, otherwise a CPF3BDE will be signaled.

Authorities and Locks

None.

Required Parameter Group

Data

INPUT; CHAR(*)

The data in the CCSID given by the CCSID parameter to write to the screen.

Data length

INPUT; BINARY(4)

The number of bytes contained in the data parameter.

Omissible Parameter Group

Field ID

INPUT; BINARY(4)

The field ID indicating the field at which to set the display address. If this parameter is specified with a nonzero value, the row and column parameters are ignored and the row and column values corresponding to the field ID are used to set the display address. If neither the field ID nor the row and column parameters are specified, the current display address is used. If this parameter is specified with a nonzero value, the CCSID parameter is also ignored, and the data written to the screen is assumed have the same CCSID as the field ID.

CCSID

INPUT; BINARY(4)

The CCSID of the data to be written. If the CCSID given is not supported by the device, a CPF3BDE is signaled.

If this parameter is omitted (zero is passed in as the CCSID), and the field ID parameter was omitted or previously undefined, the job CCSID is used. If the job CCSID is 65535, the default job CCSID is used instead.

Row

INPUT; BINARY(4)

The row at which to write the data. The row parameter must refer to a row no greater than the current screen or window mode height (if window mode is enabled). The actual screen row used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the row location of the top window border (0 for full screen) if offset is positive, or the row location of the bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error occurs if an incorrect row value is specified.

If both the field ID and the row and column parameters are omitted, the data is written starting at the current display address. If this is the case and the command is a direct operation, or the buffer specified does not contain a preceding output operation that sets the display address, the current display address is set to row 1, column 1 prior to writing the data.

Row and column must both be specified or omitted; one cannot be specified if the other is omitted.

Column

INPUT; BINARY(4)

The column at which to write the data. The column parameter must refer to a column no greater than the current screen or window mode width (if window mode is on). The actual screen column used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the column location of the left window border (0 for full screen) if offset is positive, or the column location of the right window border (screen width plus 1 for full screen) if offset is negative. The offset is the column parameter value specified, and actual is the actual screen column to be used. A CPFA307 error occurs if an incorrect column value is specified.

Starting monochrome attribute

INPUT; CHAR(1)

The initial screen attribute for monochrome displays. If this parameter is omitted and monochrome attributes are to be used, no initial attribute is written to the display for the data.

The monochrome and color attributes parameters are the initial and ending screen attributes: an initial and ending screen attribute to be used for a monochrome or a color display, respectively. One of these parameters will be selected based on the underlying display type, and the other will be discarded. Any of the attributes can be specified as a special value, X'00', indicating that no screen attribute should be written to the display. If the initial screen attribute is specified as an actual attribute, the data column, if specified, must be greater than or equal to 2. The initial screen attribute, if not X'00', will be written to the screen at the column previous to the first data character if row and column are specified, otherwise to the current display address. The ending screen attribute, if not X'00', will be written at the column directly after the last data character. See Screen Attribute Characters for a description of the screen attribute values.

Ending monochrome attribute

INPUT; CHAR(1)

The ending screen attribute for monochrome displays. If this parameter is omitted, and monochrome attributes are to be used, no ending attribute is written to the display for the data.

Starting color attribute

INPUT; CHAR(1)

The initial screen attribute for color displays. If this parameter is omitted and color attributes are to be used, no initial attribute is written to the display for the data.

Ending color attribute

INPUT; CHAR(1)

The ending screen attribute for color displays. If this parameter is omitted and color attributes are to be used, no ending attribute is written to the display for the data.

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 data is written to the screen at the specified location. 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