Using the Editors

Data entry widgets are used to accept and display text or data that the user enters. They also accept data from external sources, such as a database or an LDB screen.

• Single line text widget, by nature, accepts a single line of data.

• Multiline text widget accepts one or more lines and is enclosed within a single border.

• Combo box allows data entry and also provides the user with a drop-down list from which to choose a value.

In addition, the following widget types function as input devices. These widgets accept data that a user specifies either by selecting an option or by setting a value on the device. They do not allow the user to actually type the data.

• Option menu

• Scale

This chapter describes:

• Each of the data entry widget types and how to use them.

• How you control what keystrokes are acceptable at runtime for a widget. For example, defining if the field accepts numbers or letters and if it should be in a particular format.

• How you control the contents of the field as a whole. For example, defining what occurs when the user first enters the field, and whether data is required, converted, validated, and protected.

Defining the Input with Keystroke Filters

The Keystroke Filter property, a property for single line and multiline text widgets and combo boxes, provides a mechanism for validating input, character-by-character, as a user types. In addition, you can define a regular expression that also validates the entire field when the field is exited at runtime. In general, if a user attempts to enter a character that does not match the Keystroke Filter specification for the field, a warning beep sounds, and the character is rejected.

By default, the Keystroke Filter property is set to Unfiltered, meaning that entry of any character is accepted when typed.

How to Define an Input Data Filter for a Selected Widget

Under Input, in the Keystroke Filter property, select the desired filter from the Setting option menu. Possible filters are:

• Digits only

• Logical yes/no values

• Alphabetic, numeric, and alphanumeric characters

• Regular expression—A regular expression subproperty is displayed where you can enter the string expression.

• Edit mask—An edit mask subproperty is displayed where you can enter the data mask string.

Digits Only Filter

Specifying Digits-only as a filter type:

• Allows entry of the digits 0 through 9 only.

• Allows no blanks to the left of any digit if the widget has a left-justified (default) format.

• Allows no blanks to the right of any digit if the Justification property is set to Right.

• Does not allow leading or trailing blanks.

In general, use this type of data filter for fields requiring no special punctuation or format, or if the input can be variable in length. For example, specify a digits-only filter for a field where a quantity is entered. On the other hand, if you have a field used for entering a number of fixed length and format, like a Social Security number or identification number, consider using an edit mask filter.

How to Embed Special Characters in a Digits-Only Field

You can embed alphabetic characters, punctuation, or special characters in a digits-only field.

1. Select the data entry widget.
2. Under Format/Display, enter the format in the Initial Text property.

   For example, an initial text entry of # - - displays in the field at runtime. The user can type numbers without overwriting the punctuation.

Refer to Chapter 10, "Controlling the Way Things Look," for more information on defining the display format.

Yes/No Entries

Specifying Yes-No as a Keystroke Filter setting allows entry of the initial letters of "yes" and "no." This edit uses the initial letters, in upper and lower case, defined in the SM_YES and SM_NO entries in the Panther message file. You can change the message file to support non-English equivalents of Y and N. Refer to "Setting Yes/No Values" in Application Development Guide for details on changing the default values.

By default, all of the following entries are acceptable at runtime: y, Y, n, N, or space, which is converted to n.

Character and Numeric Edits

The alphabetic and numeric keystroke filters let you enforce entry of alphabetic characters, numbers, or a combination of both. In general, these filters are useful for a field that accepts data that can vary in length, like names or titles, or that requires no special punctuation or format.

How to Embed Punctuation or Special Characters, Such as Hyphens, Periods, and Pound Signs (#)

1. Select the data entry widget.
2. Under Format/Display, specify the format in the Initial Text property. Refer to "Giving Widgets Initial Data" for details on defining display format.

Panther uses library functions to evaluate alphabetic and numeric input.

For information on how Panther interprets keystroke filters for multilingual applications, refer to "Keystroke Filter Translation" in Application Development Guide.

Alphabetic Edits

Allows only a-z, A-Z, and the space character. Alphabetic filters allow the entry of a variable number of characters. For example, in a Name field, the user can enter any size name, up to the length specified for the field.

Numeric Edits

Allows entry of digits, a plus or minus sign, and one decimal point. If a plus or minus sign is entered, it must be leftmost in the field. When a valid character is entered into the middle of an otherwise empty field, it is rejected (due to the leading/trailing blanks).

• Left-justified numbers—No blanks are allowed to the left of any character entered.

• Right-justified numbers—No blanks are allowed to the right of any character.

Numeric filters are useful when input data must be specified to be positive or negative, or when the data length is not fixed or formatted.

Alphanumeric Edits

Allows entry of any digits, the letters a-z and A-Z, and the space character.

Edit Masks

Edit masks let you:

• Impose a pattern of symbols or characters that limits the kind and number of characters that the user can type into a field—and are useful for data of fixed length and format, such as social security numbers and telephone numbers.

• Enforce digits-only, alphabetic, or alphanumeric input as well as the display of embedded punctuation and special characters.

• Include data characters and display characters: display characters are protected and serve as place savers for static text/numbers, and data characters allow data entry and are filtered on a character-by-character basis.

Panther strips out the display characters, or mask, from the data. Library functions like sm_getfield return data characters only.

How to Define an Edit Mask

1. Select the data entry widget.
2. Under Input, set the Keystroke Filter to Edit Mask. The Edit Mask subproperty is displayed.
3. In the Edit Mask property, type the display and data characters (refer to Table 14-1) required to define the mask.

   Note: If your edit mask includes embedded punctuation, omit the punctuation from other format properties, substring operations, and JPL procedures when validating, comparing, or manipulating the data.

   Table 14-1 Edit mask characters

   Character	Name	Function
   9		Digit specification
   X		Letter specification
   A		Alphanumeric specification
   *	asterisk	Any character
   \	backslash*	Causes next character to be treated as a data character
   * To specify a backslash as display text, use two backslashes.

1. Select the data entry widget.
2. Under Input, set the Keystroke Filter to Edit Mask. The Edit Mask subproperty is displayed.
3. In the Edit Mask property, enter the display and data characters (refer to Table 14-1) required to define the mask. This filters the data as the user types it.
4. Under Input, in the Regular Exp property, define an expression (refer to "Regular Expressions" on page 14-7 for details) to check the pattern (for example, numbers between 900 and 999) when the field is exited.

The following mask represents an 11-character field; seven of the characters are data characters; the letters C, N, pound sign, and hyphen are display characters:

CN#\9\9\9-\9\9\9\9

When the user enters the field, the cursor is positioned on the first data character, in this example, on the first digit position, bypassing the display characters (CN#).

Edit Mask on Widgets with Null Values

If a widget has an edit mask and also has the Null Field property under Format/ Display set to Yes, only the data characters are replaced by the null edit. Consider defining a null text string indicator in the Null Text property (a subproperty of Null Field), such as an asterisk, and set the Repeating property to Yes. This ensures that a field with the edit mask CN#\9\9\9-\9\9\9\9 appears as CN#***-**** when the field is null.

Edit Mask on a Widget with a Data Formatting Property Set to Date/Time

Include the display characters in the edit mask, for instance, as \9\9-\9\9-\9\9. Specify a custom date format in the Format Type property that does not include the special characters—for example, MON2DATE2YR2 as opposed to MON2-DATE2-YR2. This latter specification would result in an invalid date/time format error when the user enters a date value.

Regular Expressions

Regular expressions let you:

• Enforce or exclude a specific pattern of letters and/or numbers, as well as a specified length.

• Restrict the field to a range or set of characters (for example, [0-5] allows only a number between zero and five).

• Validate data on a character-by-character basis (as a keystroke filter) or as a field validation filter (as a Regular Expression property).

  You might use character-level expressions, for example, to restrict a field to a set of characters (e.g., [0-9]), and use the field-level expression to establish a pattern (that is, 9... to match any number between 900 and 999).

The rules for defining a regular expression are the same for both character-level and field-level expressions, except they are stored as different properties.

How to Define a Character-Level Regular Expression

1. Select the data entry widget.
2. Under Input, set the Keystroke Filter property to Regular Exp. The Regular Exp subproperty is displayed.
3. In the Regular Exp property, enter the expression string.

   At runtime, each character is checked against the regular expression as the use types. Invalid input is rejected immediately, and a warning beep is issued. The data is also verified when the field is validated, in the event that the user deleted a character, causing the string to be invalid.

Select the data entry widget. Under Input, type the expression string in the Regular Expression property.

At runtime, the content of the field is matched against the regular expression when the field is validated. If the data doesn't match the specified pattern, Panther displays a message (for example, Entry out of range) and the cursor is automatically positioned at the invalid character if the entry does not match the specified pattern.

Examples of Regular Expressions

[0-9]\{3\}-[a-zA-Z0-9]\{3,6\} defines an identification number of three-digits followed by a hyphen, followed by a minimum of three letters or numbers, but no more than six.

[iI][cC][eE] matches ice, icE, iCe, Ice, IcE, ICe, or ICE.

212-[0-9]\{3\}-[0-9]\{4\} matches any phone number having a 212 area code.

[0-9]\{3\}-[0-9]\{2\}-[0-9]\{4\} matches any social security number.

[a-zA-Z_][0-9a-zA-Z_]* matches an identifier in the C programming language.

Constructing Expressions

There are two kinds of rules for constructing a regular expression: one for forming simple expressions, and one for combining expressions into more complex expressions.

Rules for Defining a Simple Expression

The simplest regular expression is a single character, which matches itself. The regular expression z matches the string z. A blank in a regular expression matches a blank in a field. Table 14-2 identifies special characters you can use in constructing a regular expression.

The backslash (\):

• Followed by a character forces the character to match itself even if the character is special. For instance, the sequence \. matches the dot, and the sequence \\ matches a single backslash.

• Makes certain ordinary characters special; for example, backslashes that precede curly braces are quoted curly braces and are used to define a repeat count expression (refer to "Rules for Defining an Expression with a Repeated Pattern Match" on page 14-11 for information on the type of expression).

Rules for Character Classes

Character classes are a group of characters between brackets ([]). A valid entry matches any of the specified characters within the brackets. For example, the expression [13579] matches any single, odd-digit; the expression [aA] matches an a of either case.

Table 14-3 lists special characters that you can include within a character class when constructing a regular expression.

• Characters in the character class are sorted by ASCII value when the expression is saved.

• Abbreviate long lists of consecutive characters by using a hyphen (-). For instance, [a-z] matches any lowercase letter, and [A-Za-z] matches any letter at all. Because of the ASCII collating sequence, [A-z] matches all letters plus some punctuation characters that fall between Z and a.

• You can use any number and combination of characters and ranges within one set of brackets.

• To negate or restrict character classes, place a caret (^) immediately after the opening bracket. This causes the class to match any character not in the class. The expression [^0-9+.-] matches any non-numeric character.

• The backslash is not a special character and cannot be used as the quote character in a character class. It stands for itself.

  Table 14-3 Special characters within a character class

  Character	Name	Function
  ^	caret	Negates the character class when it immediately follows [ (square bracket)
  -	hyphen	Denotes a character class range unless it is the first or last character in the class
  ]	square brackets	Closes the character class unless it is the first character, or the first character after an opening ^ (caret)

The following exceptions indicate when a caret, hyphen or bracket stands for itself:

• The caret stands for itself if it is not the first character.

• The closing bracket stands for itself if it is the first character, or if it is the first character after an opening caret.

• The hyphen stands for itself if it is the first or last character, or if it is the first character after an opening caret.

For example, to allow a field to accept any character except ^ (caret), - (hyphen), [ (opening square bracket), ] (closing square bracket, . (dot or period), or \ (backslash), use the following expression:

[^][.\-]

Put one expression after the other. The entered data must match whatever matches the first expression, followed by whatever matches the next, and so on. Data is matched sequentially with each subexpression.

For example, an expression that comprises the following subexpressions:

[^xXyYzZ][a-z][a-z][a-z][a-z]

accepts any five-letter word that doesn't begin with upper or lower case X, Y, or Z and whose second, third, and fourth letters are lower case characters.

Rules for Defining an Expression with a Repeated Pattern Match

You can define an expression that includes the number of times that the expression, or subexpression, is to be repeated.

• An asterisk * that follows an expression or subexpression means that the pattern defined in the preceding expression is to be repeated zero or more times. For example, the expression [0-9]* matches any number of digits or none at all, as opposed to [0-9] which matches only one digit in the range of zero to nine.

  To force the entry of at least one digit, use the expression [0-9][0-9]*.

• To enforce a more definite repeat count for an expression, specify the count within quoted curly braces \{ and \} immediately after the expression or subexpression. The count or number you define specifies the number of times that the expression is to be repeated. There are three forms you can use to specify a repeat number:

  • \{n \}— Specifies exactly n repetitions.

  • \{n,\}—Specifies n or more repetitions.

  • \{n,m\}—Specifies at least n repetitions but no more than m.

    For example, [0-9]\{5\} matches a number of exactly five digits. While a five letter word, beginning with the letter J, could be expressed as:

    [J][a-z]\{4\}

Rules for Rematching Subexpressions

You can construct a complex expression using abbreviated syntax. These types of expressions are useful when specific repeated patterns are required as input in a field.

• Use quoted parentheses \( and \) around the subexpression. Then place a quoted digit later in your expression; for example, \n will match whatever the nth subexpression surrounded by \(\) matched.

  For example, to enforce a string construction that expects the first and third characters to be the same, your expression might be:

  \([A-Z]\)\([0-9]\)\1

  Acceptable input would be B5B, J9J, and so on; while A8B is not accepted. To rematch the second subexpression as well as the first, change the expression to

  \([A-Z]\)\([0-9]\)\1\2

  in which case, acceptable input would be B5B5, A1A1, and so on, while input like U2U5 and A7B7 are not.

Converting Case

1. Select the data entry widget.
2. Under Input, in the Convert Case property, specify the case style:

   • Lower

   • Upper

   • Mixed (combination of both upper and lower case characters)

     As the data is entered at runtime, the characters are converted.

---

Controlling What Occurs on Input

For the most part, Input properties control the behavior of the field and not the actual content of the field. These properties apply to those widgets that accept data—single line and multiline text widgets, combo boxes, and, in some cases, scales.

Specifying a Range of Values

A range specification can ensure that a user stays within a specified range when entering data in the selected widget. Any widget that can accept data by user input, including a scale widget, can have a Minimum Value and Maximum Value property specification.

How to Set a Range

1. Select the data entry widget or scale widget.

   Note: If the data entry widget has a Keystroke Filter property setting of Numeric, or if the widget's Keystroke Filter property setting is one of Unfiltered, Regular Exp or Edit Mask and if the Data Formatting property setting is Numeric, the values entered are compared numerically. Otherwise, the values are compared as character strings. For example, a Minimum Value of Martin and a Maximum Value of Mary accept any character string that falls within the specified range—where Marty is a valid entry, but Marilyn is not.

2. Under Input, enter a value in the Minimum Value property. At runtime, empty fields are considered within the range specification. Scale widgets require both minimum and maximum values; by default, scale widgets have a minimum setting of 0 (zero).

   If you only specify a Minimum Value, then data greater than or equal to the specification are accepted at runtime and empty fields are considered to be within the range.

3. Under Input, enter a value in the Maximum Value property. At runtime, empty fields are considered within the range specification. Scale widgets require both minimum and maximum values; by default, scale widgets have a maximum setting of 100.

   If you only specify a Maximum Value, then data less than or equal to the specification are accepted at runtime.

The following properties let you define the restrictions or behavior of a field when the user brings focus to that field at runtime.

Required

1. Select the data entry widget.
2. Under Input, set the Required property appropriately:

   • Yes—At runtime, the user must enter at least one non-blank character before exiting the field. If the user leaves the field blank, an error message is displayed and the cursor returns to the field's first enterable position.

   • No—(default) The field can be empty.

If the Null Field under Format/Display is set to Yes and the Required property is set to Yes, then the field must be non-null at runtime in order to pass validation. The null indicator string (set in the Null Text property) does not satisfy the requirement for data.

Rules for Data Required in Arrays

For widgets that are arrays, the Required property specifies that data is required only for the number of onscreen occurrences.

Must Fill

1. Select the data entry widget.
2. Under Input, set the Must Fill property to Yes.

   At runtime, the field is considered valid in either of the following cases:

   • The field is completely empty.

   • The field has no blanks. This includes leading, trailing, and embedded blanks.

3. To ensure that the field is completely filled and not left empty, set both the Must Fill property and the Required property to Yes.

The Select on Entry property can be useful for:

• Right-justified fields.

• Currency fields, in which editing previous data might be confusing for the user.

• Fields that have data that would tend to change completely.

How to Control if Data is Selected when Tabbing into a Field

1. Select the data entry widget.
2. Under Input, set the Select on Entry property appropriately:

   • Yes—At runtime, the contents of the field is selected when the user first enters the field; the selected text is deleted when the user types new data. Moving the cursor from the first position deselects the text.

   • No—(default) The cursor moves to the first position in the field. New data is inserted and existing data is pushed to the right and not overwritten.

By default, text widgets and combo boxes are not protected from data entry; however, you can change the property setting. At runtime, library functions can remove the input protection, while other functions can put data into fields that are protected.

How to Control Whether Data Can be Overwritten

1. Select the data entry widget.
2. Under Input, set the Input Protection property:

   • Yes—At runtime, the user cannot type into the field; all characters are rejected and a warning beep sounds. However, the user can make selections, scroll the data in a scrolling array, or clear data.

   • No—(default) Data can be overwritten by the user.

All data entry and input device widgets (except for option menus which do not have this property) have the Clearing Protect property. You can protect the data in such widgets by setting the property accordingly.

How to Control Whether Existing Data in a Field Can be Cleared

1. Select the widget.
2. Under Input, set the Clearing Protect property:

   • Yes—The data in the field cannot be cleared when the user presses the CLR (clear all), FERA (clear field), DELL (delete line), or INSL (insert line) logical keys.

   • No—(default) The field can be cleared of data by using the logical keys that delete or clear data.

---

Entering Data on Multiple Lines

Both a single line text widget having an array specification greater than one and a multiline text widget can accept and display multiple lines of text. However, they look different. An arrayed single line text widget displays as a collection of separate widgets, while a multiline text widget's onscreen elements are enclosed within a single border.

For character mode Panther applications, you can define different border styles, a title, and horizontal scroll bars on a multiline text widget.

Refer to "Arrays"in Application Development Guide for more information about using arrays.

Both single line and multiline text widgets can have a greater number of occurrences than can display on the screen. This is referred to as a scrolling array. On a multiline text widget you can include a vertical scroll bar to allow users to view offscreen occurrences.

If the maximum length of the widget is greater than the display length, the widget is referred to as a shifting field. When the Word Wrap property under Format/Display is set to No for a multiline text widget, you can include a horizontal scroll bar on the widget to allow users to view offscreen data. Refer to "Creating Shifting/Scrolling Fields" for more information on defining scrolling/shifting properties and behavior.

In addition, users can view offscreen data by using vertical scroll bars, the right/left arrow keys, or the SHIFT, SCROLL, or ZOOM keys.

Defining a Word Wrap Field

A multiline text widget, by default, accepts and displays data in a word wrap fashion. It is nonshifting and scrollable. As the user types into a multiline field, words shift between occurrences to avoid being split, and large unused portions of occurrences are eliminated. The following properties define a multiline text widget:

• Under Format/Display, Word Wrap is set to Yes.

• Under Geometry, the Length and Max Data Length are the same; therefore, the field is nonshifting and the Horizontal Scroll Bar property has no effect (except in character mode).

In word wrap fields, the following logical keys are available to aid in editing the content:

Note: The ZOOM logical key is not supported if the Word Wrap property is set to Yes for a multiline text widget.

Word Wrap Function

For the most part, word wrap is handled by the native GUI (Motif and Windows specifically). Therefore, word wrapped fields behave as follows:

• Arrow keys move the user up, down, right, and left within the array.

• To exit a word wrapped array, the user can click out of the field or press TAB.

• If you want each line to be validated when the user moves from occurrence to occurrence, you can set the WW_COMPATIBLE setup variable (refer to page 2-30 in Configuration Guide).

Using Input Devices

Scales and option menus provide users of your application with the ability to enter data without actually typing the information. Combo boxes provide both a list from which to choose as well as a means of typing data. These input device widgets are particularly useful when you want to provide users with a range or list of choices, but with some restrictions. These devices also occupy a minimal amount of space on a screen, and therefore are useful when conservation of screen real estate is an issue.

Using Scales

A scale widget allows a user to specify a numeric value within a predefined range of values. The scale widget can be horizontal or vertical in position and consists of:

• A slider that moves between two values.

• A label that dynamically changes to reflect the current value.

Use the library functions sm_getfield and sm_putfield to retrieve and set a value at runtime.

How to Implement a Scale Widget

1. Select a scale widget—either horizontal or vertical.
2. Under Input, set the Minimum and Maximum Value properties to the desired values (refer to "Specifying a Range of Values" for more information).

By default, scales have a minimum value of 0 and a maximum value of 100. The length of the scale is determined by the maximum and minimum values and the number of decimal places you specify.

Note: Vertical widgets always have the lower end of the range at the lower end of the scale.

How to Set the Scale to an Initial Value

1. Select the scale widget.
2. Under Input, set the Initial Value property to a value that falls within the minimum and maximum range specifications.

   On screen entry, the scale's slider is positioned to this value and can act as a default.

   Note: If the user chooses the CLR (clear all) or FERA (clear field) keys, the scale resets to its minimum value, as opposed to the initial value specification.

3. (Optional) To protect the initial value specification from being cleared, under Input, set the Clearing Protect property to Yes.

• Under Format/Display, specify a number in the Decimal Places property.

  • The default 0 forces a whole number specification on the scale

  • 2 sets the decimals to two places

Using Option Menus and Combo Boxes

Option menus and combo boxes are similar in appearance—each has a text portion and a list portion; however, option menus are protected from data entry, while combo boxes allow users to type into the text portion of the widget.

At runtime, the user can select from these widget types by:

1. Clicking on the widget's indicator to expand the list of options or, for an option menu, entering the initial character of an item on the list.
2. With the list expanded, a selection can be made by doing either of the following:

   • Entering the first character of an item on the list.

   • Clicking on the desired item.

     The selected item is displayed in the text portion of the widget.

The list of options for these widgets can be populated in two ways:

• By entering data directly in the Properties window.

• By identifying a screen that contains the data (which can be populated from a database or from an LDB).

To determine what selection is made or entered (if a combo box) by the user, use the library function sm_e_getfield.

Populating the List with Constant Data

1. Select or create an option menu or combo box.
2. Under Identity, specify Constant Data (default) in the Drop-Down Source property.
3. Select the Drop-Down Data property. The Drop-Down Data dialog box opens.
4. Enter or edit data by doing any of the following:

   • Type the data directly in the dialog box window.

   • Choose Editor to invoke your local editor and enter the desired data.

   • Choose Read File to import an external file.

     This data is displayed when the user clicks on the widget's indicator.

In Motif, the drop-down list displays all occurrences to their full length. In character mode and Windows, the list width is determined by the length/width of the option menu widget itself, and therefore, some occurrences may appear truncated.

Defining the Number of Occurrences

For applications running in character mode and Windows, you can define the number of entries that are immediately visible when the user expands an option menu or combo box. This property setting is particularly useful if the data list is extensive or screen space is limited.

Note: In Motif, option menus and combo boxes do not scroll; therefore, the Drop-Down Size property has no effect.

How to Define the Number of Occurrences that Display on an Option Menu or Combo Box (for Windows and Character Mode Applications)

• Under Identity, specify the number of occurrences to be displayed in the Drop-Down Size property.

  A blank value causes all occurrences to be displayed. If the number is less than the total number of occurrences, the drop-down list will have a vertical scroll bar so the user can scroll to the offscreen occurrences.

Using Data from an External Source

You can populate an option menu or combo box from an external source, for example, a screen that is dynamically populated from a database. You must also create the external source screen.

How to Populate an Option Menu or Combo Box List from an External Source

1. Select an option menu or combo box.
2. Under Identity, specify External Screen in the Drop-Down Source property.
3. In the Drop-Down Screen property, type the screen name or choose More and select it from the Select Library Member dialog box.

   The screen you specify should consist of a list box (or any other array widget) that can have either a specific or infinite number of occurrences. It can be populated dynamically at runtime from still another source, such as another screen (LDB, local data block) or a database.

4. Under Identity, in the Initialization subproperty, choose either of the following settings:

   • Fill at Popup—(default) Invokes the external screen only when the user activates the combo box or option menu. If the external screen is populated as the result of a database query, you can ensure that the list contains the most up-to-date information. This specification does not force the opening and closing of the external screen until user-activated.

   • Fill at Init—Opens the external screen when the selected combo box or option menu is initialized—that is, the external screen populates the widget when the screen opens. If the external screen, for example, is populated from a database, the data is retrieved any time the widget is initialized. Opening and closing the external screen can take time, particularly if a database query is involved. On the other hand, if the data on the external screen are not likely to change while the current screen is displayed or if other widgets on the screen use the same external screen, use this specification.

Create a screen that holds a database-derived widget that you copied from a repository entry. The screen will contain a simple screen entry function that invokes a VIEW command, and fetches the required data.

1. Select the widget in the untitled screen.
2. Under Geometry, set the Array Size property to a number greater than 1.
3. Under Geometry, set the Scrolling property to Yes.
4. Set the Max Occurrences subproperty to the number of occurrences to be read in. A blank value allows for an unspecified number of occurrences (the actual maximum number is platform-specific).
5. Select the screen (click in an empty area of the screen to deselect the widget).
6. Under Focus, select JPL Procedures. The JPL Program Text dialog box opens.
7. Type a simple procedure to call a VIEW transaction command, for example:

   proc procedureName
   {
   	call sm_tm_command("VIEW")
   }

   Choose FileCloseJPL/Javascript to save the procedure and to return to the Properties window.

8. Under Focus, type the procedureName in the Entry Function property.
9. Save the screen (this is the name you provide in your option menu's Drop-Down Screen property).

Create a screen that holds one widget that has more than one occurrence (list box, multiline text, or single line text with an Array Size property value greater than 1). Refer to "Using Local Data Blocks" in Application Development Guide for more details on using LDBs.

When a widget gets its data from an LDB, the widget on the external screen should be initialized with no data.

Defining Initial Setting

Only the top portion of a combo box and option menu displays when the screen opens at runtime.

How to Define What Displays in the Text Portion of an Option Menu or Combo Box

1. Select the option menu or combo box.
2. Under Format/Display, enter the desired text string in the Initial Text property.

The data can be one of the items in the drop-down portion of the widget, and can serve as a default. If you clear the Initial Text property of any text, on entry to the screen, the option menu/combo box will be blank.