I_FLDMOD

Modify an input field’s attributes at runtime

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

xcall I_FLDMOD(window_id, field_spec, [length], [type][, qualifier, ...])

Arguments

window_id

The ID of the input window containing the field to be modified. (n)

field_spec

The specification for the field whose attributes I_FLDMOD will modify. See Field specifications for information. (a)

length

(optional) The maximum input length. Use length to shorten a field or re-lengthen a field after it has been shortened. The modified length must be greater than zero and less than or equal to the original length. (n)

type

(optional) The requested field type. Duplicates D_FLD_TYPE; see Type and D_FLD_TYPE. (n)

qualifier

(optional) One or more of the field qualifiers shown in the Field qualifiers table. (a or n)

Discussion

I_FLDMOD modifies various input field attributes at runtime. You can use I_FLDMOD to change the fields in your current input set. Note that I_FLDMOD changes only the field’s display, not the internal input buffer layout. In order to prevent invalid data, field_spec is always initialized, so alterations to the displayed data are reflected on the next input or display.

I_FLDMOD’s options are also available with the .FIELD script command. For more detailed information on I_FLDMOD options, see the corresponding qualifier in .FIELD qualifiers.

If either window_id or field_spec is invalid, a fatal error occurs. Any D_FLD_xxx argument flag not listed above will result in the fatal error “Invalid I_FLDMOD code (code),” where code is the invalid value passed. If you specify a qualifier (other than D_FLD_DEC) that does not apply to the field’s destination type, it is ignored.

You can specify methods with the following qualifiers even if the field did not originally define them: D_FLD_ARRIVE, D_FLD_CHANGE, D_FLD_DISPLAY, D_FLD_DRILL, D_FLD_EDITFMT, D_FLD_HYPERLINK, D_FLD_LEAVE.

For all the qualifiers that have text string arguments (such as D_FLD_USER), you can only specify a string that is equal to or shorter than the original text string. If you shorten the length, you can re-lengthen or restore the text string for the field as long as it doesn’t exceed the length of the original string; if it does exceed the original length, the modification will be ignored.

User-defined field methods are passed the user type and user text strings as arguments. Thus, it is important to know the order in which methods are invoked if the developer modifies either of these strings within a method. The input field methods are invoked in the following order: arrive method, EEDTDSP_METHOD, %IEDITFMT_METHOD, ECHKFLD_METHOD, change method, EDSPFLD_METHOD or %IDISPLAY_METHOD, leave method, and drill or hyperlink method.

The default qualifiers are also inspected when arriving upon the field so the default value can be displayed. Thus, modifying the default value within a method (other than the arrive method) will not cause that new default value to be used if the user presses Enter.

Because the information line is displayed when arriving on a field, modifying a field’s information line within a method (other than the arrive method) may not take visible effect until the next time the field is arrived upon. Otherwise, to immediately affect the information line, use either E_SECT to modify it or %M_SIGNAL to exit the method and force the arrival on the field to occur again.

Field qualifiers
Qualifier and arguments	Description
D_FLD_DEC, num_places	Decimal places.
D_FLD_SIZE, storage_size	Storage size. See D_FLD_SIZE for size limits.
D_FLD_TYPE, type	Field type. See Type and D_FLD_TYPE.
D_ON	Turn on one or more of the following field qualifiers. See D_ON and D_OFF for details. (default)
D_OFF	Turn off one or more of the following field qualifiers. When qualifiers are preceded by D_OFF, flags that normally require an argument do not. See D_ON and D_OFF for details.
D_FLD_ARRIVE, arrive_method	Arrive method.
D_FLD_ATTR, attribute	Attributes. See D_FLD_ATTR for valid values for attribute.
D_FLD_AUTO	Automatic input.
D_FLD_BREAK	Cause break processing to occur when the field is changed. See BREAK, NOBREAK for more information.
D_FLD_BRK_ALWAYS	Cause break processing to occur every time the user leaves the field. See BREAK, NOBREAK for more information.
D_FLD_BRK_RTRN	Cause break processing to occur only when the field is changed or Enter is pressed. See BREAK, NOBREAK for more information.
D_FLD_BZRO	Blank if zero.
D_FLD_CHANGE, change_method	Change method.
D_FLD_CHECKBOX	Check box field.
D_FLD_COLOR, palette#	Color.
D_FLD_COPY	Copy default.
D_FLD_DATE, date_type	Date format. See D_FLD_DATE for valid values for date_type.
D_FLD_DECR	Decrement default.
D_FLD_DISABLED	Disabled.
D_FLD_DISPLAY, display_method	Display method.
D_FLD_DFLT, string	Default entry.
D_FLD_DRILL, drill_method	Drill method.
D_FLD_DSPLEN, display_len	Display length. Cannot be specified for check boxes, radio buttons, selection windows, or multi-line fields.
D_FLD_EDITFMT, editfmt_method	Edit format method.
D_FLD_ENUM, [dlen],[base],[step]	Enumeration properties. See D_FLD_ENUM.
D_FLD_FMT, string	Format string.
D_FLD_FONT, font_id	Field font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id.
D_FLD_FPOS [, D_CHANGE], row, col	Field position. See D_FLD_FPOS and D_FLD_POS.
D_FLD_HELP, string	Help identifier.
D_FLD_HYPERLINK, hyper_method	Hyperlink method.
D_FLD_INCR	Increment default.
D_FLD_INFO, string	Information text.
D_FLD_INPLEN, input_len	Maximum input length. Cannot be specified for check boxes, radio buttons, selection windows, or multi-line fields.
D_FLD_JUST, just_flag	Justification, where just_flag is D_JST_CENTER, D_JST_LEFT, or D_JST_RIGHT.
D_FLD_LEAVE, leave_method	Leave method.
D_FLD_NEG	Negative allowed.
D_FLD_NEGONLY	Negative allowed only.
D_FLD_NEGORZERO	Negative or zero allowed only.
D_FLD_NODEC	No decimal required.
D_FLD_NOECHO	No echo.
D_FLD_NOECHR, char	Fill character when D_FLD_NOECHO is specified (otherwise ignored).
D_FLD_NOTERM	No termination.
D_FLD_PAINT, char	Paint character.
D_FLD_POS [, D_CHANGE], row, col	Prompt position. See D_FLD_FPOS and D_FLD_POS.
D_FLD_PROMPTFONT, font_id	Prompt font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id.
D_FLD_RADIO	Radio buttons.
D_FLD_RANGE, min, max	Range. See D_FLD_RANGE.
D_FLD_READONLY	Read-only. Not valid for check boxes, radio buttons, selection lists and windows. See D_FLD_READONLY.
D_FLD_REQUIRED	Required input.
D_FLD_RETPOS	Retain position in text field.
D_FLD_TIME, time_type	Time format. See D_FLD_TIME for valid values for time_type.
D_FLD_TIMESTAMP, format	Timestamp. See D_FLD_TIMESTAMP for details on this option and valid values for format.
D_FLD_UC	Uppercase only.
D_FLD_USER, string	User-defined text string.
D_FLD_VIEWLEN, view_length	The width of the field (i.e., the width of the area on the screen that will display data for the field). Cannot be specified for check boxes or radio buttons.
D_FLD_WAIT, wait_time	Input time-out for the field, where wait_time is the number of seconds to wait or one of the options shown in D_FLD_WAIT.

Type and D_FLD_TYPE

Type is retained for compatibility with earlier versions of Toolkit. It duplicates the functionality of D_FLD_TYPE, except that it does not support D_USERTYPE. A user-defined field can only be specified using D_FLD_TYPE.

Type and D_FLD_TYPE supports the following options for type:

D_ALPHA	Alphanumeric
D_DECIMAL	Decimal
D_INTEGER	Integer
D_NUMERIC	Numeric (same as decimal)
D_USERTYPE, type_string	User-defined

I_FLDMOD will change the field type between alpha, decimal, and integer; requests to change to or from text fields will be ignored.

If you change the field type from alpha, the following defaults apply unless you override them:

• Zero decimal places (D_FLD_DEC, 0)
• Negative not allowed (D_OFF, D_FLD_NEG)

If you change the field type to alpha, the following defaults apply unless you override them:

• Lowercase allowed (D_OFF, D_FLD_UC)
• No echo character is blank (D_FLD_NOECHR)
• No matching case (.FIELD’s MATCH(NOCASE))

If you change the field type to D_INTEGER, the storage size is changed to the nearest (but not larger) valid integer storage size. Valid sizes are 1, 2, 4, or 8. Integer fields support all qualifiers that are valid for decimal fields without precision.

If you want the field to become an implied-decimal field, you can pass D_FLD_DEC, num_places as a qualifier. Regardless of its original setting, any field type can be converted to implied-decimal. Note that you can specify up to nine digits after the decimal point.

D_ON and D_OFF

The D_ON and D_OFF codes indicate whether the field qualifiers that follow in the argument list are to be turned on or off. D_ON is the default state for any qualifiers listed.

When qualifiers are preceded by D_OFF, flags that normally require an argument do not. For example, the first I_FLDMOD call below turns no echo on. The second call turns it off.

xcall i_fldmod(inpid, "myfield",,, D_FLD_NOECHR, '*')
xcall i_fldmod(inpid, "myfield",,, D_OFF, D_FLD_NOECHR)

Turning off D_FLD_BRK, D_FLD_BRK_ALWAYS, or D_FLD_BRK_RTRN results in a field with no break.

D_FLD_ATTR

D_FLD_ATTR accepts the following values for attribute (defined in tools.def):

A_ALL	All attributes (same as A_BHRU)
A_NONE	No attributes
A_B | A_I	Blinking (UNIX and OpenVMS) or italic (Windows). “I” can be substituted whenever “B” appears in the following flags.
A_BH	Blinking, highlighted
A_BHR	Blinking, highlighted, reverse
A_BHRU	Blinking, highlighted, reverse, underlined
A_BHU	Blinking, highlighted, underlined
A_BR	Blinking, reverse
A_BRU	Blinking, reverse, underlined
A_BU	Blinking, underlined
A_H	Highlighted
A_HR	Highlighted, reverse
A_HRU	Highlighted, reverse, underlined
A_HU	Highlighted, underlined
A_R	Reverse
A_RU	Reverse, underlined
A_U	Underlined

D_FLD_DATE

D_FLD_DATE accepts the following values for date_type:

D_DATE_Y2J	YYJJJ date format
D_DATE_Y2MD	YYMMDD date format
D_DATE_Y2P	YYPP date format
D_DATE_Y4J	YYYJJJ date format
D_DATE_Y4MD	YYYYMMDD date format
D_DATE_Y4P	YYYYPP date format

To make the field default to the today’s date, add D_DATE_TODAY to any of the above. For a short date, add D_DATE_SHORT to any of the above. (You can add both of these if desired,)

D_FLD_ENUM

To use D_FLD_ENUM, the field must already be an enumerated field. You cannot use this to turn a non-enumerated field into an enumerated field, and you cannot use D_OFF with this qualifier to change an enumerated field into a non-enumerated field. (D_OFF causes D_FLD_ENUM to be ignored.)

A display length (dlen) set with D_FLD_ENUM overrides any previously specified display length (for example, any display length set with D_FLD_DSPLEN).

When using D_FLD_ENUM, you must include all comma placeholders for the arguments (even those you don’t pass) unless this is the last qualifier for the I_FLDMOD call, in which case you must include only the comma placeholders that precede the last argument specified for D_FLD_ENUM. If you omit an argument, the corresponding enumeration property will remain unchanged.

D_FLD_FONT and D_FLD_PROMPTFONT

The font_id argument to D_FLD_FONT and D_FLD_PROMPTFONT can be the name of a font palette entry, a font handle, or one of the following:

DF_ALTERNATE	Alternate font
DF_CURRENT	Current font
DF_DEBUGGER	Debugger font
DF_DEFAULT	Global font

If you change the type of a field (for example, alpha to numeric) and you are using any of the FONT_ initialization settings, be aware that the corresponding font isn’t automatically applied. To update the font, use D_FLD_FONT. (Note that if a view length is specified on Windows, changing the font may change the width of the field. See VIEW_LENGTH, NOVIEW_LENGTH for information.)

Because a list has only one font setting, using I_FLDMOD to change the font for a field in a list has no effect. With the ActiveX Toolkit list, however, you can manipulate the font for individual cells by using the API Extension methods SetCellFont, Set headerCellFont, and SetFooterCellFont.

On Windows, do not use I_FLDMOD to change font settings for a column in a Toolkit list or an ActiveX implementation of a Toolkit list. This doesn’t work on Windows: the font will revert to the standard typeface and size, and data in the column will be blanked out. This is because input field fonts are not applied to lists. For an ActiveX Toolkit list, you can use the SetCellFont method to change the font of a specific cell.

I_FLDMOD settings for an ActiveX Toolkit list will not override cell-level fonts or colors specified by the SetCellFont and SetCellColor ActiveX Toolkit list methods.

D_FLD_FPOS and D_FLD_POS

D_FLD_POS modifies the position of the prompt only. It does not affect the field’s position (unlike changing the default field position for IB_FIELD or .FIELD). To modify the field position, you must use D_FLD_FPOS. You must also use D_FLD_FPOS to modify the position of a check box prompt on Windows because the position of a check box’s prompt is determined by its field position. If either position places any part of a field or prompt outside the window, the positions are automatically adjusted so that the field and prompt fit in the window.

D_FLD_RANGE

D_FLD_RANGE can be specified only for input fields that had a range originally, either using the RANGE qualifier in Script, or using IB_FIELD’s D_FLD_RANGE. The field must be numeric, and min and max must not exceed the field’s storage size. If you use variables for beg and end, they must be alpha variables; decimal variables will not work.

D_FLD_READONLY

If you use D_FLD_READONLY for a field that can’t be set to read-only (i.e., a check box, a radio button set, or a field with a selection list or a selection window), the read-only setting will be accepted, but it won’t affect the field. (For these field types, use I_DISABLE rather than I_READONLY.) However, if the field is subsequently changed to a regular text field, Toolkit may use this setting because when a field is changed to a text field, the most recent read-only state setting is used to determine whether the field will be read-only or read/write.

You can also set a field’s read-only state with I_READONLY. For information on the differences between D_FLD_READONLY and I_READONLY, see I_READONLY.

For information on changing read-only settings from an input method for the field, see Notes on input methods.

D_FLD_SIZE

Alpha and alpha arrayed fields can have up to 65,535 characters. Decimal fields (including implied decimal fields) have a maximum size of 28, and for implied-decimal fields, up to 28 digits can follow the decimal point. Integer fields on any operating system can have 1, 2, 4, or 8 digits, depending on size.

D_FLD_TIME

D_FLD_TIME accepts the following values for time_type:

D_TIME_HM	HHMM time format
D_TIME_HMS	HHMMSS time format

To make the field default to the current time, add D_TIME_NOW to either of the above. To add AM/PM to the display, add D_TIME_AMPM to either of the above. (You can add both of these if desired.)

D_FLD_TIMESTAMP

If D_OFF is in effect, D_FLD_TIMESTAMP changes a timestamp field to a standard read-only 8-byte integer field. Do not use the format argument when D_OFF is in effect. (It will be interpreted as another qualifier.)

If D_ON is in effect, D_FLD_TIMESTAMP must be followed by the format argument, which enables you to change the formatting used for a timestamp field. The format argument can be one or both of the following, or 0 (for neither):

D_TIMESTAMP_AMPM	Use 12-hour notation and AM/PM designation
D_TIMESTAMP_SHORT	Use short display format (no century, seconds, or milliseconds)

To specify both D_TIMESTAMP_AMPM and D_TIMESTAMP_SHORT, use the bitwise OR operator (.BOR. or |) or add them. If a flag isn’t passed, it will be reset to its default value. For example, if you don’t pass D_TIMESTAMP_SHORT, the long display format will be used even if the field was previously set to use the short format.

For D_ON, D_FLD_TYPE must be set to D_INTEGER, and the field must be a read-only, 8-byte integer. It cannot be a selection field, a radio button set, or a check box. Otherwise, an error will occur.

D_FLD_WAIT

The wait_time argument to D_FLD_WAIT can be the number of seconds to wait or one of the following:

D_FOREVER or -1	Wait until I/O processing is completed
D_GLOBAL or -2	Use the globally specified time-out
D_IMMEDIATE or 0	Time out immediately

See also

• .FIELD script command
• Renditions for information and notes on setting field-level renditions
• Using fonts on Windows for information on fonts and font palettes

Examples

The following is a sample interface for a room scheduler. This program assumes two different companies in the same building use this scheduler. Company Alpha likes to describe all of its rooms with an alpha field, such as “Conference room,” “Laboratory,” and “Break room.” Company Numeric, however, prefers to use room numbers that are no larger than 9999. Company Alpha does not allow a blank room name, but Company Numeric allows a room #0.

The first field in this input window asks whether Company Alpha or Company Numeric is entering the schedule, and it modifies the room field accordingly.

.include "WND:tools.def"
record
  id                    ,i4
  colid                 ,i4

record data
  company               ,a30
  room                  ,a20
  time                  ,a5
  ampm                  ,a2
proc
;Set up stuff 
xcall u_start("rmsched") 
xcall i_ldinp(id, g_utlib, "rmsched") 
;Start input processing 
do forever
  begin
    xcall i_input(id,, data)
    if (g_setsts) then              ;At company break field
      begin
        if (company .eq. "Numeric Company") then
          xcall i_fldmod(id, "room", 4, D_NUMERIC, D_OFF, D_FLD_REQUIRED) 
        else
          xcall i_fldmod(id, "room", 20, D_ALPHA, D_ON, D_FLD_REQUIRED)
      end
    else
      begin                         ;Process the input
        xcall i_init(id)
      end
  end                               ;End of "do forever"
xcall u_finish
.end

The input window looks like this:

.input rmsched, 10, 65
.field company, a30, req, break, prompt("Company Name  "),–
      sel(0, 30, 2, "Alpha Company", "Numeric Company")
.field room, a20, pos(2, 9), prompt("Room   ")
.field time, d5, pos(3, 9), prompt("Time   "), format("ZX:XX")
.field ampm, a2, sel(0, 2, 2, "am", "pm"), pos(change, 0, 1)
.end

The following example changes the custno field to type alpha, with uppercase input only.

xcall i_fldmod(inpid, "custno",,, D_FLD_TYPE, D_ALPHA, D_FLD_UC)

The next example removes the “required” status from the field creditref.

xcall i_fldmod(inpid, "creditref",,, D_OFF, D_FLD_REQUIRED)

The following example modifies the field date to default to today’s date.

xcall i_fldmod(inpid, "date",,, D_FLD_DATE, D_DATE_Y4MD+D_DATE_TODAY)