set

The following sections describe the effect of an EGL set statement:

Effect on a record (or fixed record) as a whole

The next table describes the set statements that affect a record as a whole, a fixed record as a whole, or an array of either.

Format of set statement Effect
set record empty Empties each of the elementary fields. For a record, each subordinate record is emptied, as is each subordinate of those subordinates, and so on. For a fixed record (which may itself be in a record), the elementary fields are at the lowest level of the fixed structure.
The effect on each elementary field depends on the primitive type of that field:
  • For a field of type ANY, the set statement initializes the field according to the field's current type; and if the field is of type ANY and has no other type, the set statement has no effect
  • For details on fields of other types, see Data initialization
set record initial Resets the field values to those specified by the value property at development time, as is possible for a record or fixed record that is declared in a pageHandler or form. A value set by assignment is never reinstated.

If the value property has no value or if the record is not in a pageHandler or form, the effect of set record initial is the same as the effect of set record empty, with one exception: for a field that is of type ANY, the set statement removes any type specification other than ANY.

set record position Establishes position in the VSAM file associated with a fixed record of type indexedRecord (described later), or establishes position in DL/I database associated with a record of type DLISegment (also described later).

This set-statement format is not available for an array.

You can combine statement formats by inserting a comma to separate the options. For a given record, the options take effect in the order in which they appear in the set statement. Also, you can specify multiple records by inserting a comma to separate one from the next.

The syntax diagram is as follows:


Syntax diagram for the set statement that affects a record as a whole
record name
Name of a record or fixed record of any type. You can specify an array.
indexed record name
Name of a fixed record of type indexedRecord. You can specify an array only if you do not include set record position.
empty
As described in the previous table.
initial
As described in the previous table.
position
Establishes a file or database position based on the set value, which is the key value in an indexed record or DLISegment record. The overall effect depends on the next input or output operation that your code performs against the same record:
  • If the next operation is an EGL get next statement, that statement reads the first file record or segment that has a key value equal to or greater than the set value. If no such record or segment exists, the result of the get next statement is endOfFile.
  • If the next operation after set record position is an EGL get previous statement, that statement reads the first file record that has a key value equal to or less than the set value. If no such record exists, the result of get previous is endOfFile. (The get previous statement does not support DL/I access.)
  • Any other operation after set record position resets the file position, and the set record position has no effect.
For indexed records, if the set value is filled with hexadecimal FF values, the following is true:
  • The set record position establishes a file position after the last record in the file
  • If the next operation is a get previous statement, the last record in the file is retrieved
The set record position performs no I/O. For DL/I databases, it sets a flag telling the system that a subsequent GN (get next) call should execute the default GU (get unique) call implied by the key fields in the various DLISegment records. Performing a set record position before entering a loop with a get next statement may be more efficient than performing an explicit get before entering the loop.

Effect on a form as a whole

The next table describes the set statements that affect a form as a whole.

Format of set statement Effect
set form alarm For text forms only; sounds an alarm the next time that a converse statement presents the form.
set form empty Empties the value of each field in the form, clearing any content. The effect on a given field depends on the primitive type:
  • For a field of type ANY, the set statement initializes the field according to the field's current type; and if the field is of type ANY and has no other type, the set statement has no effect
  • For details on fields of other types, see Data initialization
set form initial Resets each form field to its originally defined state, as expressed in the form declaration. Changes that were made by the program are canceled. for a field that is of type ANY, the set statement removes any type specification other than ANY.
set form initialAttributes Resets each form field to its originally defined state, as expressed in the form declaration. The content of the field is not affected, neither (in the case of a field of type ANY) is the type affected.

You can combine statement formats by inserting a comma to separate options such as empty and alarm. Also, you can specify multiple forms by inserting a comma to separate one form from the next.

Of the following formats, you can choose one or none:
  • set form empty
  • set form initial
Of the following formats, you can choose one, both, or none:
  • set form alarm (available only for text forms)
  • set form initialAttributes

The syntax diagram is as follows:


Syntax diagram for the set statement that affects a form as a whole
form name
Name of a form of type text or print, as described in Form part.
text form name
Name of a form of type text, as described in Form part.

The options are as described in the previous table.

Effect on a field in any context

The next table describes the format of the set statement that affects a field in any context.

Format of set statement Effect
set field empty Empties the field or (for a fixed field that has a substructure) empties every subordinate, elementary field.
The effect depends on the primitive type of a field:
  • For a field of type ANY, the set statement initializes the field according to the field's current type; and if the field is of type ANY and has no other type, the set statement has no effect
  • For details on fields of other types, see Data initialization
set field null Nulls the field, if doing so is valid. For details on when the operation is valid, see itemsNullable.

The syntax diagram is as follows:


Syntax diagram for the set statement that affects a non-form item or array
field name
Name of the field.

You may select one or the other option, and each is described in the previous table.

Effect on a field in a text form

The next table describes the set statements that affect a field or an array of fields in a text form. A given set statement can combine options only in a particular set of ways, as described later. Many of the actions described are dependent on the device where the text form is displayed. It is recommended that you test your output on each of the devices that you are supporting.

Format of set statement Effect
set field blink Causes the text to blink repeatedly. This option is available only in COBOL programs.
set field bold Cause the text to appear in boldface.
set field cursor Positions the cursor in the specified field.

If the field identifies an array and has no occurs value, the cursor is positioned at the first array element by default.

If your program runs multiple statements of the format set field cursor, the last is in effect when the converse statement runs.

set field defaultColor Sets the field-specific color property to defaultColor, which means that other conditions determine the displayed color. For details, see Field-presentation properties.
set field dim Causes the field to be appear in lower intensity than normal. Use this effect to deemphasize field contents. In COBOL environments, the clause has the same effect as set field normalIntensity, causing the field to be visible, without boldface.
set field empty Initializes the value of the field, clearing any content. The effect on a given field depends on the primitive type, as described in Data initialization.
set field full Sets an empty, blank, or null field to a series of identical characters before the form is presented:
  • The character is an asterisk (*) if the field property fillCharacter is the following value (which is also the default value for fillCharacter):
    • 0 for fields of type HEX
    • space for fields of a numeric type
    • empty string for other fields
  • If fillCharacter is not set as described, the character is identical to the value of fillCharacter.

The on-form characters are returned to the program only if the modified data tag for the field is set, as described in Modified data tag and property. A user who changes the field must remove all the on-field characters to prevent their return to the program.

Use of set field full has an effect only if the form group is generated with the build descriptor option setFormItemFull.

A field of type MBCHAR is considered to be empty if it contains all single-byte spaces. In relation to such fields, set field full assigns a series of single-byte characters.

set field initial Resets the field to its originally defined state, independent of any changes made by the program
set field initialAttributes Resets the field to its originally defined state, without using the value property (which specifies the current content of the field)
set field invisible Makes the field text invisible
set field masked Appropriate for password fields. If the text form is presented by a Java™ program, an asterisk is displayed instead of any non-blank character that the user types into an input field. If the text form is presented by a COBOL program, this option makes the field text invisible.
set field modified Sets the modified data tag, as described in Modified data tag and property.
set field noHighlight Eliminates the special effects of blink, reverse, and underline.
set field normal Resets the fields as described in relation to the following formats:
  • Set field normalIntensity
  • Set field unmodified
  • Set field unprotected

For details, see the next table.

set field normalIntensity Sets the field to be visible, without boldface.
set field protect Sets the field so that the user cannot overwrite the value in it. See also set field skip.
set field reverse Reverses the text and background colors, so that (for example) if the display has a dark background with light letters, the background becomes light and the text becomes dark.
set field selectedColor Sets the field-specific color property to the value you specify. The valid values for selectedColor are as follows:
  • black
  • blue
  • green
  • pink
  • red
  • torquoise
  • white
  • yellow
In COBOL environments, the value of black is implemented as defaultColor, which means that other conditions determine the displayed color. For details, see Field-presentation properties.
set field skip Sets the field so that the user cannot overwrite the value in it. In addition, the cursor skips the field in either of these cases:
  • The user is working on the previous field in the tab order and either presses Tab or fills that previous field with content; or
  • The user is working on the next field in the tab order and presses Shift Tab.
set field underline Places an underline at the bottom of the field.
set field unprotect Sets the field so that the user can overwrite the value in it.
You can combine statement formats, inserting a comma to separate options such as cursor and full, in any of three ways:
  1. You can construct a set statement as follows--
    • Choose one or none of these field-attribute formats:
      • set field initialAttributes
      • set field normal
    • Choose any number of the next formats:
      • set field cursor
      • set field empty
      • set field full
  2. Second, you can construct a set statement from any number of the next formats:
    • set field cursor
    • set field full
    • set field initial or set field initialAttributes
  3. Last, you can construct a set statement as follows--
    • Choose any number of the next formats:
      • set field cursor
      • set field full
      • set field modified
    • Choose one or none of the color formats:
      • set field defaultColor
      • set field selectedColor
    • Choose one or none of the highlight formats:
      • set field blink
      • set field reverse
      • set field underline
      • set field noHighlight
    • Choose one or none of the intensity formats:
      • set field bold
      • set field dim
      • set field invisible
      • set field masked
      • set field normalIntensity
    • Choose one or none of the protection formats:
      • set field protect
      • set field skip
      • set field unprotect

The syntax diagram is as follows:


Syntax diagram for the set statements that affect a text field
field name
Name of the field in a text form. The name may refer to an array of fields.

The options are as described in the previous table.

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.