IB_FIELD

Add an input field to a new input window

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
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.

Note

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 return (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.)

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

See also

Examples

The following example adds the field company to the current input window being built. It is an alpha field, 15 characters long.

xcall ib_field(bldid, "company", D_FLD_TYPE, D_ALPHA, D_FLD_SIZE, 15)

The next example adds the field age to the current input window being built. It is a three‑digit decimal field, which the user is required to input. The field will prompt the user with the string “Enter your age.”

xcall ib_field(bldid, "age", D_FLD_TYPE, D_DECIMAL, D_FLD_SIZE, 3,
&     D_FLD_REQUIRED, D_FLD_PROMPT, "Enter your age ")

The following example adds the field date[2,6] to the current input window being built. It is an eight‑digit decimal field from an array named date defined in a repository named cusmas. Note that the IB_FIELD call specifies the format (YYYYMMDD), information that Toolkit does not import from the repository. The field will default to today’s date if the user presses enter without entering any data.

xcall ib_rps_structure(bldid, "cusmas")
xcall ib_field(bldid, "date[2,6]",D_FLD_DATE, D_DATE_Y4MD+D_DATE_TODAY)