set

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

• Effect on a record as a whole

• Effect on a form as a whole

• Effect on an SQL item

• Effect on a field in a text form

Effect on a record as a whole

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

Format of set statement	Effect
set record empty	Initializes each of the elementary structure items, which are those at the lowest level of the record structure. The effect on each item depends on the primitive type, as described in Data initialization. This format is available for an array of records.
set record initial	Resets the item values to those specified at development time. In the case of a record declared in a page handler or form, the content (if any) of the value property is reinstated. If that property has no value or if the record is not in a page handler or form, the effect of set record initial is the same as the effect of set record empty. This format is available for an array of records.
set record position	Establishes position in the VSAM file associated with an indexed record, as described later. This format is not available for an array of records.

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 record from the next.

The syntax diagram is as follows:

record name

Name of a record of any type. You can specify a record array.

indexed record name

Name of a record of type indexedRecord. You can specify a record 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 position based on the set value, which is the key value in an indexed record. The overall effect depends on the next input or output operation that your code performs against the same indexed record:

• If the next operation is an EGL get next statement, that statement reads the first file record that has a key value equal to or greater than the set value. If no such record 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.

• Any other operation after set record position resets the file position, and the set record position has no effect.

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

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	Initializes the value of each field in the form, clearing any content. The effect on a given field depends on the primitive type, as described in 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.
set form initialAttributes	Resets each form field to its originally defined state, as expressed in the form declaration, but with one exception: The statement does not use the value property, which specifies the current content of a given field, to reset the contents of the fields.

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:

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 an SQL item

The next table describes the format of the set statement that affects an item in an SQL record.

Format of set statement	Effect
set item null	Nulls the item, as is valid only for structure items that are in records of type SQLRecord, and only if the IsNullable property of the item is set to yes. (Arrays are not valid in records of type SQLRecord.) For details on null processing, see SQL item properties.

The syntax diagram is as follows:

SQL item name

Name of the item.

The options are as 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.

Note: 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.
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 null 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.
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
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:

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.

Related concepts
Form part
Modified data tag and modified property
Syntax diagram

Related reference
Data initialization
EGL statements
Field-presentation properties
get next
get previous
Items

SQL item properties