Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API

The Set Low-Level Environment Window Mode (QsnSetEnvWinMod) API enables or disables the window mode for the low-level environment. Use this API to affect how row and cursor positions specified on low-level interface operations are interpreted for operations to the given low-level environment. Additional details regarding windows can be found in Window Services APIs.

When window mode is enabled, screen locations and cursor positions specified and retrieved in the low-level interface routines are interpreted relative to the logical window area defined. The logical window area is treated as a logical screen in terms of validity of cursor and data starting positions. If an attempt is made to write data or define a field that starts outside of the current window area, a CPFA31D error is issued for that particular API. If data or a field is written to the window that exceeds the window boundary, no error condition occurs and the data or field is truncated.

The size of the logical window area can be determined through the Retrieve Low-Level Environment Window Mode (QsnRtvEnvWinMod) API. When window mode is enabled, screen addresses must be explicitly specified for APIs such as the QsnWrtDta API in order for the address to be interpreted relative to the window area. If a screen address is not specified, the current display address will be used as an absolute screen address irrespective of the current window mode. This is because the current screen address is not tracked by DSM, but is handled by the control unit.

When window mode is enabled, APIs where a cursor position is specified, such as the QsnSetFld API, issue a CPFA307 error if the given cursor position is outside the bounds of the current window area. For APIs that return a cursor position, such as the Get Cursor Address (QsnGetCsrAdr) API, both the row and column returned will be -1 if the cursor screen location is outside of the current window area, 0 if the cursor is on the top or left border, or the number of screen rows or columns plus 1 if the cursor is on the bottom or center border of the window area, respectively. The following low-level APIs are affected by the window mode:

QsnRtvReadAdr
QsnRtvFldInf
QsnGetCsrAdr
QsnGetCsrAdrAID
QsnSetOutAdr
QsnWrtDta
QsnWrtSFMaj
QsnWrtTDta
QsnWrtExtAtr
QsnWrtPad
QsnWrtPadAdr
QsnSetFld
QsnSetCsrAdr
QsnInsCsr
QsnSetErr

The actual screen location used for a screen I/O operation is calculated using the formula base+offset=actual, where base is the upper left row/column location of the window border (0 for full screen) if offset is positive and the lower center row/column location of the window border (screen height/width plus 1 for full screen), if offset is negative, offset is the row/column specified on the API, and actual is the actual screen location. For example, if the window area were defined to be from row 3, column 10 with 15 rows and 30 columns, as shown in Window Area, then an attempt to position the cursor through the QsnSetCsrAdr API at row 4, column 5 would actually position the cursor on the screen at row 7, column 15, as indicated by the letter a in Window Area. Specifying row 9, column -7 would position the cursor on the screen at row 12, column 34 (b in Window Area). An attempt to position the cursor at error issue a CPFA307 error row 16, column 5 would result error (Screen position &1,&2 outside of display or window area). since this position is outside the bounds of the current window area. Given the same window area description, a call to the QsnRtvFldInf API specifying an input buffer containing a field read from row 10, column 20 on the actual screen (the c in Window Area), would return a field row and column location of 7 and 10 respectively. A call to the QsnGetCsrAdr API would return -1,-1 if the cursor were located outside of the window area, such as in row 18 column 32.

Enabling or disabling the window mode does not affect any data currently displayed on the screen or the behavior of any commands stored previously in a command buffer. For example, if the window mode was enabled as described above and the QsnSetCsrAdr API was called as an indirect operation specifying row 4 and column 5, the cursor position command stored in the command buffer would reflect the current window mode. Whenever that command buffer is written out, the cursor would always be set on the screen at row 6, column 14, regardless of whether or not window mode was disabled or changed at the point when the command buffer was written to the screen.

Window Area

Authorities and Locks

None

Required Parameter

Window mode

INPUT; CHAR(1)

Whether window mode should be enabled or disabled. The possible values are:

0	Disable window mode
1	Enable window mode

Window mode is initially disabled.

Omissible Parameter Group

Previous window mode setting

OUTPUT; CHAR(1)

Whether window mode was enabled or disabled prior to this API being called. The possible values returned are:

0	Window mode was disabled prior to this API being called
1	Window mode was enabled prior to this API being called

Window mode description

INPUT; CHAR(*)

The window mode description. If this parameter is omitted or the length parameter is specified as 0, and window mode is to be enabled, the values from the previous window mode setting will be used. If no such values exist, the current screen size will be used. The window area described must fall within the bounds of the current screen size. in a CPFA307 error (Screen position &1,&2 outside of display or window area). The format of this field is shown in Format of the Window Mode Description.

This parameter is ignored if window mode is to be disabled.

Length of window mode description

INPUT; BINARY(4)

The length of the window mode description parameter. If this parameter is specified, it must be either 0, in which case the window mode description parameter is ignored, or exactly 13 bytes in which case the window mode description is required.

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.

Format of the Window Mode Description

Field Descriptions

Attribute column indication. Whether the column containing the left border of the logical window is an attribute column. Operations such as QsnWrtDta can specify column 1 for the data location and specify a leading attribute. In this case the data will be written to the first column of the window area and the attribute will be written to the column containing the logical window border. If the attribute column is not specified for the window area, such an operation would result in a CPFA31D error (Attempt to write outside of window area.). This column would also be used to insert the leading attribute when line wrapping occurs within the window.

The allowable values are:

Number of columns in window area. The number of columns in the window area.

Number of rows in window area. The number of rows in the window area.

Upper left column of window area border. The column location of the leftmost column in the window area. This parameter must be a value between 0 and the screen width inclusive.

Upper left row of window border. The row location of the upper border of the logical window area. This parameter must be a value between 0 and the screen height inclusive.

Error Messages