Create a Window (QsnCrtWin) AP

The Create a Window (QsnCrtWin) API creates a window and returns a handle for that window. The window must be deleted using the Delete Low-Level Environment (QsnDltEnv) API. Whenever a window is made current, the window mode is set to the usable area of the window.

Authorities and Locks

Exit Routine Authority

*EXECUTE

Required Parameter Group

Window description

INPUT; CHAR(*)

The window description defines the attributes for the window. The format of the window description is shown in Format of the Window Description.

Length of window description

INPUT; BINARY(4)

The length of the window description parameter.

Omissible Parameter Group

User extension information

INPUT; CHAR(*)

The user extension information is used to associate data and exit routines with the window. This parameter is required if the length of user extension information parameter is supplied. This essentially enables the object-oriented programming concept of inheritance, allowing the window to be extended in a natural way. The user extension information cannot be changed once the window has been created. The format of this parameter is shown in Format of the Window User Extension Information.

Length of user extension information

INPUT; BINARY(4)

The length of the user extension information parameter.

Start window

Input; CHAR(1)

Whether the window should be displayed on the screen when it is allocated. The possible values are:

0	The window is not displayed on the screen when it is allocated. You must use the Start a Window (QsnStrWin) API to start the window.
1	The window is displayed on the screen when it is allocated. This is the default if this parameter is omitted.

Low-level environment description

INPUT; CHAR(*)

The low-level environment description defines the operating environment for low-level operations used to create and manipulate the window. This parameter is required if the length of the low-level environment description parameter is supplied. The format of the low-level environment description is shown in Format of the Low-Level Environment Description. If this parameter is omitted, a low-level environment will be created with default values.

Length of low-level environment description

INPUT; BINARY(4)

The length of the low-level environment description parameter.

Window handle

OUTPUT; BINARY(4)

The variable containing the handle for the window created after the QsnCrtWin API has completed. This handle can be used across activation groups if the activation group in which the handle was created is still active.

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

Window handle

OUTPUT; BINARY(4)

This API returns the value for the window handle parameter or a -1 if an error occurred during processing.

Restrictions

Windows where the associated low-level environment indicates DBCS support cannot be resized. GUI windows must fit within the screen boundary. This includes the leading left border attribute and the center border continuation attribute. GUI windows must have a border and the associated left and center border attributes for the left and center borders. The concept of current and noncurrent window border attributes does not apply to GUI windows. No error-checking is performed for GUI-specific fields. The fields are passed to the control unit, as specified, and any errors will be detected by the control unit.

Format of the Window Description

Field Descriptions

In the following descriptions, the default value refers to the value set by the Initialize Window Description (QsnInzWinD) API.

The GUI-only fields in the following descriptions refer to fields within the data stream for the Create Window command major and minor structures. See the 5494 Remote Control Unit Functions Reference, SC30-3533, manual for details.

Border attributes flag for the window. Whether or not the window border has left and center border attributes. (See DSM Window Layout in Window Services APIs.) The possible values are:

For GUI windows, 1 must be specified.

Border flag for the window. This flag indicates whether or not the window has a border. (See DSM Window Layout in Window Services APIs.) The possible values are:

If this field is set to 0, the border attributes are not written to the screen, regardless of the values of the other fields.

For GUI windows, 1 must be specified.

Border flags (GUI only). Determines if border presentation characters are used (byte 3 of the border presentation minor structure of the GUI Create Window command). The default is X'80'.

Bottom border character. The character used for the bottom border. The default is X'00' for all border characters. The default border character used for non-GUI windows is '.'. For GUI windows, the default GUI character is used.

Color title attribute. The display attribute to precede the title on a color display. The default is X'20'. If this attribute is not valid, it is ignored.

Column location of upper left corner of window border. The column number of the upper left corner of the window. If the window has a leading window attribute, the first window column is two greater than the value specified in this field; otherwise, it is one greater. This must be a positive integer value greater than or equal to 0. For GUI windows, the minimum value must be 2. Otherwise, it must be a positive integer value greater than or equal to 0. For non-GUI windows, if 0 or 1 is specified, the left border of the window or the leading border attribute, respectively, will not be displayed on the screen unless the window is moved. The default value is such that the maximum-sized window will be displayed, with border and attributes, given the other window description attributes (for example, window border attributes). If the window is a full-screen window, this field is ignored.

Flag byte 1 (GUI only). Byte 5 of the GUI Create Window command major structure. The default is X'00'.

Flag byte 2 (GUI only). Byte 6 of the GUI Create Window command major structure. The default is X'00'.

Full-screen flag for the window. Indicates whether or not this is a full-screen window. (A full-screen window cannot be moved or resized.) The possible values are:

GUI support flag for the window. This flag indicates whether or not GUI support should be used to build the window if the underlying device supports it. GUI windows always include a leading and trailing border attribute. The possible values are:

Leading attribute flag for the window. This flag indicates whether or not the window has a leading attribute. (See DSM Window Layout in Window Services APIs.) The possible values are:

For GUI windows, 1 must be specified.

Left border character. The character used for the left border. The default is X'00' for all border characters. The default border character used for non-GUI windows is ':'. For GUI windows, the default GUI character is used.

Length of title text. The length of the title text. The default value is 0.

Lower left border character. The character used for the lower left border. The default is X'00' for all border characters. The default border character used for non-GUI windows is ':'. For GUI windows, the default GUI character is used.

Lower center border character. The character used for the lower center border. The default is X'00' for all border characters. The default border character used for non-GUI windows is ':'. For GUI windows, the default GUI character is used.

Maximum number of columns within the window. A value of 0, which is the default, indicates this value is the same as the maximum number of columns for the device in its current mode. If the window is a full-screen window, this field is ignored.

Maximum number of rows within the window. A value of 0, which is the default, indicates this value is the same as the maximum number of rows for the device in its current mode. If the window is a full-screen window, this field is ignored.

Message line flag for the window. This flag indicates whether or not the window has a message line. (See DSM Window Layout in Window Services APIs). The possible values are:

Minimum number of columns within the window. The minimum value allowed is 1. This is the default. If the window is a full-screen window, this field is ignored.

Minimum number of rows within the window. The minimum value allowed is 1. This is the default. If the window is a full-screen window, this field is ignored.

Monochrome title attribute. The display attribute to precede the title on a monochrome display. The default is X'20'. If this attribute is not valid, it is ignored.

Number of columns within the window. The number of columns in the window, from the first window column to the last. This excludes the left and center border, and the border and window attributes. (See DSM Window Layout in Window Services APIs.) A value of 0, which is the default, indicates this value is the maximum number of columns that can be defined given the other window description attributes (for example, window border attributes). The minimum allowed number of columns is 1. If the window is a full-screen window, this field is ignored.

Number of rows within the window. The number of rows in the window, from the first window row to the last. This includes the message line, if specified. (See DSM Window Layout in Window Services APIs.) A value of 0, which is the default, indicates this value is the maximum number of rows that can be defined given the other window description attributes (for example, window message line). The minimum allowed number of rows is 1. If the window is a full-screen window, this field is ignored.

Offset to title text. The offset for the window title text. The default value is 0.

Center border character. The character used for the center border. The default is X'00' for all border characters. The default border character used for non-GUI windows is ':'. For GUI windows, the default GUI character is used.

Center continuation attribute flag for the window. Whether or not the window has a center continuation attribute (see DSM Window Layout in Window Services APIs). The possible values are:

The center continuation attribute used is X'20', which is green for color displays and normal attribute for monochrome displays.

Row location of upper left corner of window border. The row number of the upper left corner of the window. The first window row is one greater than the value specified in this field. This must be a positive integer value greater than or equal to 0. For GUI windows, the minimum value must be 1. Otherwise, it must be a positive integer value greater than or equal to 0. For non-GUI windows, if 0 is specified, the top border of the window will not be displayed on the screen unless the window is moved. The default value is such that the maximum-sized window will be displayed, with border and attributes, given the other window description attributes (for example, window border attributes). If the window is a full-screen window, this field is ignored.

Title text. The text for the window title, which is written in the top border of the window. If the title text is too long to fit in the window border, it is truncated. Otherwise, it is centered in the window border. You can add padding (extra blanks beside the text) to specify left or center justification for the title. If an attribute is specified for the title text, the window border attribute is placed after the title text. This field is ignored if the window does not have a top border.

The default is no title text.

Top border character. The character used for the top border. The default is X'00' for all border characters. The default border character used for non-GUI windows is '.'. For GUI windows, the default GUI character is used.

Upper left border character. The character used for the upper left border. The default is X'00' for all border characters. The default border character used for non-GUI windows is '.'. For GUI windows, the default GUI character is used.

Upper center border character. The character used for the upper center border. The default is X'00' for all border characters. The default border character used for non-GUI windows is '.'. For GUI windows, the default GUI character is used.

Window display attributes for a color display. The window display attributes for a color display. The first character is the attribute for the window border when the window is not current, the second for when the window is current, and the third for the leading window attribute. All bytes may contain the same value. The special value X'00' can be used to indicate that no screen attribute should be used for the given character. The first attribute is ignored for GUI windows, which only use the second attribute. If X'00' is specified as the second attribute for a GUI window, the default GUI border attribute will be used. Both the current and noncurrent border attributes must be either X'00' or a valid attribute. For example, it is incorrect to specify the current attribute field X'00' and the noncurrent attribute field with a valid attribute.

The default values for these fields are those specified by the window services mode description (see Format of the Window Services Attribute Description).

Window display attributes for a monochrome display. The window display attributes for a monochrome display. The first character is the attribute for the window border when the window is not current, the second for when the window is current, and the third is for the leading window attribute. All bytes may contain the same value. The special value X'00' can be used to indicate that no screen attribute should be used for the given character. The first attribute is ignored for GUI windows, which only use the second attribute. If X'00' is specified as the second attribute for a GUI window, the default GUI border attribute will be used. Both the current and noncurrent border attributes must be either X'00' or a valid attribute. For example, it is incorrect to specify the current attribute field X'00' and the noncurrent attribute field with a valid attribute.

The default values for these fields are those specified by the window services mode description (see Format of the Window Services Attribute Description).

Window title flags (GUI only). Byte 3 of the window title minor structure of the Create Window command. The default is X'00'.

Format of the Window User Extension Information

Field Descriptions

Exit routine for Change Window (QsnChgWin) API. This exit routine is called after the window is changed. If the window is redrawn, it is called after the window is redrawn.

Exit routine for Delete Low-Level Environment (QsnDltEnv) API. The exit routine to call when a window is deleted using the Delete Low-Level Environment (QsnDltEnv) API.

Exit routine for Display Window (QsnDspWin) API. The exit routine to call immediately before the window is drawn or redrawn. The following APIs may cause the window to be redrawn: QsnCrtWin, QsnStrWin, QsnChgWin, QsnMovWin, QsnMovWinUsr, QsnRszWin, QsnRszWinUsr, QsnDspWin, and QsnSetCurWin.

Exit routine for move or resize window APIs. The exit routine to call when window coordinates are changed using the QsnMovWin, Move Window by User (QsnMovWinUsr), Resize Window (QsnRszWin), or Resize Window by User (QsnRszWinUsr) APIs. This exit routine is called after the window is redrawn.

Exit routine for Set Current Window (QsnSetCurWin) API. The exit routine to call whenever a window is made current by one of the following APIs: QsnCrtWin, QsnStrWin, or QsnSetCurWin. This exit routine is called after the window is drawn or redrawn.

User data associated with window. A pointer to any data that the user wants to associate with this window.

Window Exit Routines

Exit routines are user-supplied functions with a defined interface. The routines are called from certain APIs and allow the programmer to attach additional function to those APIs. For instance, if fields have been set up in a window, a Change Coordinates exit routine could be supplied to move the fields if the window is moved.

Exit Routine Error Handling

If an exception occurs during the processing of an exit routine, the exception is ignored and processing continues. A CPFA318 will be issued as a diagnostic message only. You can explicitly handle errors in an exit routine by adding an exception handler to the routine.

Change Window Exit Routine

This exit routine, if specified on the user extension information, is called when the window is changed. The following parameter is passed to the exit routine:

Change Window Exit Routine Parameter

Window handle

INPUT; BINARY(4)

The window that was changed.

Delete Window Exit Routine

This exit routine, if specified on the user extension information, is called when the window is deleted. The following parameter is passed to the exit routine:

Delete Window Exit Routine Parameter

Window handle

INPUT; BINARY(4)

The window that was deleted.

Change Window Coordinates Exit Routine

This exit routine, if specified on the user extension information, is called when the move or resize APIs are called, after the window has been successfully moved or resized, but before the window is drawn on the screen. For this reason, you should not use this exit routine to draw anything in the window. The draw exit routine is called when the window is moved or resized. The following parameters are passed to the exit routine:

Change Window Coordinates Exit Routine Parameters

Window handle

INPUT; BINARY(4)

The window for which the coordinates were changed.

Top border offset

INPUT; BINARY(4)

The offset, in screen rows, from the previous top window border to the current top window border (after the window coordinates have been changed). It can be positive, negative, or zero, depending on how the top window border was changed. For example, if the top border was moved down two rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the top row was not changed, this value would be 0.

Left border offset

INPUT; BINARY(4)

The offset, in screen columns, from the previous left window border to the current left window border (after the window coordinates have been changed). It can be positive, negative, or zero, depending on how the left window border was changed. For example, if the left border was moved two columns to the center, this value would be 2; if it was moved 4 columns to the left, this value would be -4, and if the left column was not changed, this value would be 0.

Bottom border offset

INPUT; BINARY(4)

The offset, in screen rows, from the previous bottom window border to the current bottom window border (after the window coordinates have been changed). It can be positive, negative, or zero, depending on how the bottom window border was changed. For example, if the border was moved down two rows, this value would be 2; if it was moved up 4 rows, this value would be -4; if the bottom row was not changed, this value would be 0.

Center border offset

INPUT; BINARY(4)

The offset, in screen columns, from the previous center window border to the current center window border (after the window coordinates have been changed). It can be positive, negative, or zero, depending on how the center window border was changed. For example, if the center border was moved two columns to the center, this value would be 2; if it was moved 4 columns to the left, this value would be -4; if the center column was not changed, this value would be 0.

Draw Window Exit Routine

This exit routine, if specified on the user extension information, is called when the Display Window (QsnDspWin) API is called, before the window is drawn. Because the exit routine is called before the window is drawn, you should only write inside the window using the command buffer parameter. Direct operations should not be used for the exit routine. The following parameters are passed to the exit routine:

Draw Window Exit Routine Parameters

Window handle

INPUT; BINARY(4)

The window to be drawn.

Command buffer

INPUT; BINARY(4)

The command buffer used to store the commands that re-create the window contents. The contents of the command buffer are written to the screen along with the window border. This allows the window and its contents to be redrawn in a single I/O operation.

Current Window Exit Routine

This exit routine, if specified on the user extension information, is called when the window is made current through the Set Current Window (QsnSetCurWin) API. The following parameter is passed to the exit routine:

Current Window Exit Routine Parameter

Window handle

INPUT; BINARY(4)

A handle for the window that is made current.

Error Messages

Additional errors may be generated by this API. They are listed in Error Messages under the Create Low-Level Environment (QsnCrtEnv) API.