IB_FIELD

Add an input field to a new input window

xcall IB_FIELD(build_id, field_spec[, qualifier, ...])

Arguments

build_id

The ID of the input window under construction. (n)

field_spec

The field specification for the input window field. See Field specifications for information. (a)

qualifier

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

Discussion

IB_FIELD adds a field to a new input window being built at runtime. The maximum number of input fields in an input window or input set is 253.

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

Defaults are used for qualifiers that are not specified. If IB_RPS_STRUCTURE has been called prior to IB_FIELD, default values will be drawn from the repository, and the field must exist in the repository or a fatal error will occur. For notes on fields drawn from repositories, see Using .FIELD with .REPOSITORY_STRUCTURE.

If you specify a qualifier that does not apply to the field’s destination type, it is ignored. (Integer fields support all qualifiers that are valid for decimal fields without precision.)

Any D_FLD_xxx qualifier not listed will result in the fatal error “Invalid IB_FIELD code (code),” where code is the invalid value passed.

Field qualifiers
Qualifier and argument	Definition
D_FLD_TYPE, type	Field type. See D_FLD_TYPE for valid values for type.
D_FLD_SIZE, storage_size	Storage size. See D_FLD_SIZE for size limits.
D_FLD_DEC, num_places	Decimal places.
D_FLD_DIM, dim_size	Dimension. Only single dimension alpha arrays are supported.
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 a following argument do not need one. See D_ON and D_OFF for details.
D_FLD_ALLOW, num_entries, entry_array	Allow list.
D_FLD_ARRIVE, arrive_method	Arrive method.
D_FLD_ATTR, attribute	Attributes. See D_FLD_ATTR for valid values for attribute.
D_FLD_AUTO	Auto entry.
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_CASE	Match case.
D_FLD_CHANGE, change_method	Change method.
D_FLD_CHECKBOX	Check box.
D_FLD_COLOR, palette#	Color.
D_FLD_COPY	Copy default.
D_FLD_DATE, date_type	Date field. 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, default_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 text fields.
D_FLD_EDITFMT, editfmt_method	Edit format method.
D_FLD_ENUM, dsp_len,[base],[step]	Enumeration properties.
D_FLD_EXACT	Match exact.
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.
D_FLD_HELP, help_id	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 text 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 required.
D_FLD_PAINT, char	Paint character.
D_FLD_POS [, D_CHANGE], row, col	Prompt position.
D_FLD_PROMPT, prompt_string	Prompt.
D_FLD_PROMPTFONT, font_id	Prompt font. See D_FLD_FONT and D_FLD_PROMPTFONT for valid values for font_id.
D_FLD_PROMPTLEN, length	Runtime prompt.
D_FLD_RADIO	Radio buttons. See D_FLD_RADIO.
D_FLD_RANGE, min, max	Range for numeric field. If you use variables for the min and max arguments, they must be alpha variable; decimal variables will not work.
D_FLD_READONLY	Read-only.
D_FLD_REQUIRED	Required entry.
D_FLD_RETPOS	Retain position in text field.
D_FLD_SELECT, row, col, numrows, [numcols], num_entries, entry_array	Selection list. On Windows, use with D_FLD_RADIO to specify radio buttons or without to specify a combo box. For the former, see D_FLD_RADIO.
D_FLD_SELWND, row, col, window_name	Selection window. On Windows, use with D_FLD_RADIO to specify radio buttons or without to specify a combo box. For the former, see D_FLD_RADIO.
D_FLD_TIME, time_type	Time field. See D_FLD_TIME for valid values for time_type.
D_FLD_TIMESTAMP, format	Timestamp field. 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. See D_FLD_WAIT for valid values for wait_time.

D_FLD_TYPE

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

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

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. If the size is not correct, Toolkit will ignore the field.

If IB_FIELD creates a text field that is too large for the window, a warning will display only if g_dtkbounds is set to a value of 2 or greater. See g_dtkbounds.

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 a following argument do not need one. Thus, a prompt defined with the following call to IB_FIELD

xcall ib_field(bldid, "myfield", D_FLD_PROMPT, "Help")

can be turned off with the following:

xcall ib_field(bldid, "myfield", D_OFF, D_FLD_PROMPT)

Even though the prompt defined above is a text prompt, it could also be turned off by using D_OFF with D_FLD_PROMPTLEN. This is because, when used with either D_FLD_PROMPT or D_FLD_PROMPTLEN, D_OFF always turns off the specified prompt, regardless of its type (text or runtime).

Turning off D_FLD_BRK, D_FLD_BRK_ALWAYS, or D_FLD_BRK_RTRN results in no break for the field.

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_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

D_FLD_RADIO

On Windows, use D_FLD_RADIO with either D_FLD_SELECT or D_FLD_SELWND to specify a field that is a group of radio buttons. (If you use D_FLD_SELECT or D_FLD_SELWND without specifying D_FLD_RADIO on Windows, the field will be a combo box.)

If you use D_FLD_SELECT with D_FLD_RADIO, the numrows argument for D_FLD_SELECT determines how may radio buttons can fit in a column. If numrows is not passed, the radio buttons will be placed vertically in a single column.
If you use D_FLD_SELWND with D_FLD_RADIO, the height of the associated selection window determines how many buttons can fit in a column. You can control spacing between radio button columns by changing the column width for the selection window. This spacing is calculated by adding the width of the radio button to the width of a column in the selection window (which is equal to the number of characters times the character width for the font).

For more information on radio buttons, see RADIO, NORADIO .

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

By default, an autotime or ctimestamp field from a repository results in a timestamp field in a Toolkit application. However, you can use D_FLD_TIMESTAMP with D_OFF to create a standard integer field from a repository autotime field or with D_ON to create a timestamp field from scratch or from a standard repository 8-byte integer field.

When D_OFF is in effect, do not use the format argument. (It will be interpreted as another qualifier.)

When 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