Screen class

Introduced in version 7.1 of the Sirius Mods, Screen objects are designed to make writing and maintaining User Language full-screen applications easier. They also let you take advantage of dynamic 3270 screen sizes in your applications.

Most modern 3270 emulators allow flexible definitions of 3270 screen sizes beyond the standard Models 2, 3, 4, and 5. Traditional User Language screen definitions define a fixed layout for a screen and so must be designed to be display correctly on even the smallest screen. This is usually the 3278 Model 2, which contains a none-too-generous 24 rows by 80 columns. Though a screen designed for a 24x80 layout will usually display correctly on other models, screens designed for other models may display misaligned data on a smaller screen, often rendering the application unusable on these screen types. This leaves the application programmer little choice but to design for the lowest common denominator -- Model 2 -- wasting precious screen space on larger screens.

With Screen objects, screen definition takes place during User Language request evaluation instead of during compilation, freeing the programmer to detect and take advantage of the current screen size and to make more efficient use of available screen space. It is therefore possible for a single application to support many different screen sizes without changing User Language code or resorting to special $functions to manipulate a traditional screen layout.

A Screen object is populated with ScreenField objects.

---

The Screen class provides an object-oriented equivalent of the Model 204 full-screen feature. An instance of a Screen object is equivalent to a screen you might define with the User Language full-screen feature. The Screen methods specify layout and certain visual attributes of each screen: where screen items are to appear on the video display, and how they are to be highlighted or colored.

Screen objects are composed of screen fields and not screenlines as in the full-screen feature, and multiple screen fields may form the equivalent of a single screenline (or row). These screen fields are themselves objects: instances of the Screenfield class. In this documentat, ScreenField objects are sometimes referred to as “fields” and sometimes as “screenfields.”

Screen methods

The individual Screen methods are described in the following sections. For information about the conventions followed, see Conventions and terminology.

ActionKey property

This read-only property returns an actionKey enumeration which is the keyboard key that activated the last screen read. ActionKey enumerations are pf1 through pf24, and enter.

  %key = %screen:actionKey

ActionKey syntax

%key

A declared ActionKey enumeration. Valid values are Enter and pf1, pf2, and so on through pf24. The value that is set initially is Enter.

%screen

A reference to an instance of a Screen object.

Usage Notes

You can use the ActionKey class ToNumber method to convert ActionKey enumeration values to a numeric value: the integer that remains after the key name is stripped of its “PF” prefix. For Enter, the numeric value is 0. These values are useful in a value-testing loop in conjunction with the User Language JUMP statement.

AddField function

This callable function adds a field (an instance of a ScreenField object) to the screen represented by the method object (an instance of a Screen object).

A ScreenField can only be defined within the limits of the current screen. The number of rows and columns in the current screen is determined by Screen class methods (“Rows property” and “Columns property”, below). An attempt to define a field outside these boundaries results in request cancellation. If any part of a new screen field would overlap an existing field, the request is cancelled.

  [%sfield =] %screen:AddField( [Color=fieldcolor,] [Column=num,] [Highlight=bool,] [Invisible=bool,] [Itemid=num,] [Modified=bool,] [Numeric=bool,] [Protected=bool,] [Row=num,] [Value=string,] [Width=num,] )

AddField syntax

%sfield

A declared ScreenField object that is set to a new ScreenField object reference.

%screen

A reference to an instance of a Screen object.

Color= fieldcolor

The optional Color argument (name required) is a Fieldcolor enumeration value. Valid values (case unimportant) are turquoise, green, blue, red, white, yellow, and pink. The default is blue.

This parameter explicitly sets the color for a screen field. The Color method (“Color property”, below) lets you reset it. You can use the ProtectedColor (“ProtectedColor property”) and UnprotectedColor (“UnprotectedColor property”) methods to set defaults for a screen's protected and unprotected fields, respectively.

Column= num

The optional Column argument (name required) is a numeric value indicating the first column position in the field. This first column, in any field, is reserved for an attribute byte and cannot contain displayable data (it appears on a screen as a blank). The field's value (display data) begins by default in the column immediately following the reserved column. The first column in a screen is column 1; the last column can be determined with the Columns method (“Columns property”, below).

The default Column value is one greater than the ending column number of the preceding field, or it is 1.

Highlight= highlight

The optional Highlight argument (name required) is a Highlight enumeration value. Valid values (case unimportant) are: Underline, Reverse, Blink, or None. A ScreenField may have only one Highlight attribute. The Highlight property (“Highlight” on page 909) lets you reset it. The default is None.

Invisible= bool

The optional Invisible argument (name required) is a Boolean enumeration value: if True, any data in the field will not displayed on the terminal. If False (the default), the screen field data is displayed on the terminal. The Invisible property lets you reset the value. The invisible attribute can be applied to protected or nonprotected fields. It is typically used to hide password prompts or other private data, but it does not encrypt or suppress transmission of data over the network. It is intended to minimize theft of private data at terminals situated in non-private areas.

Itemid= num

The optional Itemid argument (name required) is a numeric value assigned to the the screenfield that allows the CursorItemID method to identify the screenfield that contains the cursor after a screen read.

The default ID number is 0. The item ID should be a unique value for each screenfield, but this is not enforced by the AddField method. You can reset the ID using the ScreenField ItemID method (“Itemid property”, below). ItemIDs are most useful when using arraylists of ScreenFields. This is commonly done for scrolling applications.

Modified= bool

The optional Modified argument (name required) is a Boolean enumeration value that indicates whether a ScreenField value has been modified by the user: True indicates the ScreenField has been modified by the user. The default, False, indicates the ScreenField has not been modified.

Regardless of the initial setting of this argument, the value of the Modified property for a field is always set by the Read method.

Numeric= bool

The optional Numeric argument (name required) is a Boolean enumeration value: if True, and the field is not protected, only numeric values may be entered in the field. Numeric values must be composed of the characters 0 through 9, plus (+), minus (-), and period (.). If False (the default), field input is not restricted to numeric data. The Numeric property (“Numeric”, below) lets you reset the value.

Regardless of the value of the Numeric attribute, the programmer can assign any type of value to the field. Enforcement of the Numeric attribute takes place only when a user enters data in the field. Some terminal emulators do not enforce numeric field restrictions, so the programmer should be aware that the value of a numeric field must still be checked for validity.

Protected= bool

The optional Protected argument (name required) is a Boolean enumeration value: if True, the field will be protected against modification by the user when the screen is displayed. If False, the screen field will be an input field. New fields are protected by default. The value of this attribute can be reset using the Protected method (“Protected property”, below).

Row= num

The optional Row argument (name required) is a numeric value indicating the starting row number for the field. The first row in a screen is row 1, and the last can be determined with the Rows method (“Rows property”, below). Any row number in the screen may be used for a field. No rows are reserved by Janus SOAP. A field may occupy more than one row.

The first position in any field is reserved for an attribute byte, which cannot contain displayable data and appears on a screen as a blank. A field's display data begins by default in the column immediately following the reserved byte.

The Row default value is 1 or the value specified or implied by the previous AddField call.

Value= string

The optional Value argument (name required) is a string that contains the screen data to be displayed. The Value parameter is simply a convenient way to set display data when the screenfield is instantiated.

The Screenfield class Value method performs the same work, but can also get user-entered data for a screenField. For more information on setting and getting screenField values, see “Value property”.

Width=width

The optional Width argument (name required) is a numeric value indicating the length of the screen field, excluding the attribute byte. The first position in any field is occupied by an attribute byte, which cannot contain user data. The minimum width for a field is 1, and the maximum width is 255. If no width is specified, the width of the field is determined by the length of the string specified in the method's Value parameter. If neither a Width nor a Value parameter is specified, the request is cancelled. If both Width and Value parameters are specified, the Width parameter is used to set the field width, and the Value is silently padded or truncated accordingly.

The Width property lets you reset the width.

Usage Notes

Each of the screenfield attributes specified by the AddField optional parameters can be updated by their like-named methods in the ScreenField class. The “modified” and “value” attributes are also set by a user screen-interaction.

Columns property

This read-only property returns the number of columns in the current screen. This number corresponds to the column value returned by a Model 204 VIEW MODEL command.

  %num = %screen:Columns

Columns syntax

%num

A numeric variable to contain the returned number of columns. %screen A reference to an instance of a Screen object.

Copy function

This method returns a Screen object that is a copy of the method object. For more information about copyability, see “Copying Objects”

  %outscreen = %screen:Copy

Copy syntax

%outscreen

A declared Screen object.

%screen

A reference to an instance of a Screen object.

Usage Notes

The method object (%screen) may be null. The output of a copy of a null object is a null object.

CursorColumn property

This property either gets the column number where the cursor is currently positioned, or it sets the column number for the cursor position.

  %screen:cursorColumn = %num
  %num = %screen:cursorColumn

cursorColumn syntax

%num

A numeric variable or expression for the column number.

%screen

A reference to an instance of a Screen object.

Usage Notes

Although you can set an absolute position for the cursor using CursorColumn and CursorRow, it is generally more useful to use the ScreenField SetCursor function to move the cursor to a particular field, independent of its absolute location on the screen.

CursorItemID function

This callable function returns the numeric item ID of the ScreenField where the cursor is located. A ScreenField is assigned an item ID either when it is instantiated by the AddField method (“AddField” on page 894), or if it is specified with the Screenfield Itemid method.

  [%num =] %screen:cursorItemID

cursorItemID syntax

%num

A numeric variable to contain the returned item ID. If no item ID was assigned to the screenField, zero is returned.

%screen

A reference to an instance of a Screen object.

CursorRow property

This property gets the row number where the cursor is currently positioned, or it sets the row number for the cursor position.

  %screen:cursorRow = %num

  %num = %screen:cursorRow

cursorRow syntax

%num

A numeric variable or expression for the cursor's row number.

%screen

A reference to an instance of a Screen object.

Usage Notes

You can set an absolute position for the cursor using the CursorRow and CursorColumn properties, but it is generally more useful to use the ScreenField SetCursor function (“SetCursor subroutine”, below) to move the cursor to a particular field, independent of its absolute location on the screen.

DeepCopy function

This method returns a Screen object that is a deep copy of the method object. DeepCopy is identical to the Copy method (“Copy function”, above). For more information about copyability, see “Copying Objects”.

  %outscreen = %screen:DeepCopy

DeepCopy syntax

%outscreen

A declared Screen object.

%screen

A reference to an instance of a Screen object.

Usage Notes

The method object (%screen) may be null. The output of a copy of a null object is a null object.

MaxActionKey property

This property sets or gets the enumeration of the keyboard action key on this screen that has the highest equivalent numeric value. Each action key, which activates a screen read, is identified by an ActionKey enumeration (Enter and pf1 through pf24). A key's numeric value is the number associated with its enumeration: for Enter this is 0; for pf1 it is 1; for pf2 it is 2, and so on.

MaxActionKey lets you limit the range of possible ActionKey enumeration return values you need to allow for in your program code (for example, if the values are the possible targets of a User Language computed JUMP TO statement as shown in “Screen example” on page 889).

  %key = %screen:MaxActionKey
  %screen:MaxActionKey = %key

MaxActionKey syntax

%key

A declared MaxActionKey enumeration. Valid values are Enter and pf1, pf2, and so on through pf24. The value that is set initially is Enter.

%screen

A reference to an instance of a Screen object.

Usage Notes

You can use the ActionKey class ToNumber method to convert ActionKey enumeration values to their equivalent numeric values.

New constructor

This shared function instantiates a Screen object.

  %screen = New

New syntax

%screen

A declared Screen object variable.

Usage Notes

New is a constructor and as such it can be called with no object, with an explicit class name, or with an object variable, even if that object is null:

%scr = new
%scr = %(screen):new
%scr = %scr:new

NewFieldColumn property

This property sets or gets the column number for the next added field. Unless set explicitly, the next added field is adjacent to the last added field. If no fields have been added, the first screen column (1) is returned.

  %screen:NewFieldColumn = %num
  %num = %screen:NewFieldColumn

NewFieldColumn syntax

%num

A numeric variable or expression for the column number of the next added field.

%screen

A reference to an instance of a Screen object.

NewFieldRow

This property sets or gets the row number for the next added field. Unless set explicitly, the next added field is adjacent to the last added field. If no fields have been added, the first screen row (1) is returned.

  %screen:NewfieldRow = %num
  %num = %screen:NewfieldRow

NewFieldRow syntax

%num

A numeric variable or expression for the row number of the next added field.

%screen

A reference to an instance of a Screen object.

ProtectedColor property

This property sets or gets the current default for the color of protected fields in a Screen object. A protected field is assigned this color unless another color value is explicitly specified in the AddField statement that defines the field. A field's color can also be changed by the ScreenField class Color method (“Color property”).

  %screen:ProtectedColor = fieldcolor
  fieldcolor = %screen:ProtectedColor

ProtectedColor syntax

fieldcolor

A Fieldcolor enumeration. Valid values (case unimportant) are turquoise, green, blue, red, white, yellow, and pink. The default value is blue.

%screen

A reference to an instance of a Screen object.

Examples

The following statement prints the color of the %scr screen:

Print %scr:protectedColor:ToString

ProtectedHighlight property

This property gets or sets the current highlight default for protected fields in a Screen object. A protected field is assigned this highlight unless another highlight value is explicitly specified in the AddField statement that defines the field. A field's highlight can also be changed by the ScreenField class Highlight method.

 %screen:ProtectedHighlight = highlight
 highlight = %screen:ProtectedHighlight

ProtectedHighlight syntax

highlight

A Highlight enumeration. Valid values (case unimportant) are none, underline, reverse, and blink. The default value is none.

%screen

A reference to an instance of a Screen object.

Read function

This callable function does the actual write of the screen to the "terminal," and it invokes a Model 204 wait while the user responds to the displayed screen. It then reads from the terminal the subsequent user response and updates the values of any modified ScreenField objects.

  [%key =] %screen:Read

Read syntax

%key

A declared actionKey enumeration set to the identifier of the key that activated the reading of the screen. Valid values (case unimportant) are Enter and pf1, pf2, and so on through pf24.

%screen

A reference to an instance of a Screen object.

Usage Notes

The Modified property (“Modified” on page 911) is reset for all non-protected ScreenFields after the Read method is invoked. If a particular ScreenField value has been modified by the user, the Modified property for that field is set to True. Otherwise, the Modified property is set to False.

For an example using the Read method, see “Screen class Example.

Rows property

This read-only property returns the number of rows in the current screen. This number corresponds to the row value returned by a Model 204 VIEW MODEL command.

  %num = %screen:Rows

Rows syntax

%num

A numeric variable to contain the number of screen rows.

%screen

A reference to an instance of a Screen object.

UnprotectedColor property

This property sets or gets the current default for the color of unprotected fields in a Screen object. An unprotected field is assigned this color unless another color value is explicitly specified in the AddField statement that defines the field. A field's color can also be changed by the ScreenField class Color method.

  %screen:UnprotectedColor = fieldcolor
  fieldcolor = %screen:UnprotectedColor

UnprotectedColor syntax

fieldcolor

A Fieldcolor enumeration. Valid values (case unimportant) are turquoise, green, blue, red, white, yellow, and pink. The default is green.

%screen

A reference to an instance of a Screen object.

UnprotectedHighlight property

This property sets or gets the current highlight default for unprotected fields in a Screen object. An unprotected field is assigned this highlight unless another highlight value is explicitly specified in the AddField statement that defines the field. A field's highlight can also be changed by the ScreenField class Highlight method.

  %screen:UnprotectedHighlight = highlight
  highlight = %screen:UnprotectedHighlight

UnprotectedHighlight syntax

highlight

A Highlight enumeration. Valid values (case unimportant) are none, underline, reverse, and blink. The default value is none.

%screen

A reference to an instance of a Screen object.

System space for Screen objects

Traditional User Language full-screen applications use FSCB (Full SCreen Buffer) space to hold 3270 screen definitions. Since screen objects are part of Janus SOAP, the design must fit within this existing object-oriented architecture, which cannot utilize FSCB space. As a result, screen objects use STBL space for dynamic screen definitions.

Because the entire screen image must be in contiguous storage, any instance of a screen object must allocate the maximum allowable STBL space, even if some of this space may not be used by a particular application. You use the SCRNSTBL user parameter, which specifies the maximum size per screen, to prevent unnecessary waste of STBL space and to limit an application to a reasonable amount of space to prevent STBL exhaustion.

A good starting value for SCRNSTBL is 6144 (this is the default as of Sirius Mods 7.3 and maintenance to earlier versions). Scrolling applications and applications designed for large screens with many fields may require two or more times this storage. An application that exceeds its screen STBL allocation is canceled.

References

The Janus SOAP manual in PDF format: http://sirius-software.com/maint/download/jansoapr.pdf

The Screenfield class page on the Sirius Wiki.

Screen Object Sample Code

How to use Model 6, or Dynamically Sized screens in Model 204.

Conventions and terminology used in Sirius Software technical documentation.