I_PUTFLD

Put data into an input field

xcall I_PUTFLD(window_id, [set_name], data_area, field_spec, new_data
&     [, a_methoddata1, ..., a_methoddata20])

Arguments

window_id

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

set_name

(optional) The name of the input set. (a)

data_area

The data area for the input set. (a)

field_spec

The specification for the field that I_PUTFLD will load data into. (See Field specifications for information.) (a)

new_data

The data to load. (a)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

I_PUTFLD places data into an input field. It displays new_data in the field and puts it into data_area.

If you do not specify a set name, set_name defaults to the first input set.

Data_area must correspond to the structure associated with the input set.

Field_spec must be part of the input set, and if either window_id or field_spec is invalid, a fatal error occurs.

Data is retrieved from new_data according to the definition within the input window (regardless of the actual type of new_data) so you need to make sure the data you pass as new_data has the same type and precision as the input field (field_spec). If the input field is a dimensioned alpha field, new_data is assumed to be the first element of the array as specified in the field’s definition, and remaining elements are assumed to follow new_data in memory. (If the other elements aren’t defined in the memory that follows new_data, subsequent elements of the alpha arrayed field will be filled with garbage.) For dimensioned alpha fields then, it’s best to define the data for all elements in the field in an identical dimensioned alpha variable, and then pass the first element as new_data.

Note that by default, Toolkit does not ensure that the size of data_area or the size of new_data matches the size of the referenced field (field_spec) or that they are even large enough for the field. However, bounds checking can check for the following conditions. (See g_dtkbounds for more information.)

If g_dtkbounds is set to 1, Toolkit generates a fatal error if data_record is not large enough for the field.
If g_dtkbounds is set to 2 or greater, Toolkit generates a fatal error if data_area is not large enough (as it does if g_dtkbounds is set to 1). It generates a nonfatal error if data_area is large enough for the field, but isn’t the exact size. And it generates a nonfatal error if new_data is smaller than the field.

Note that if g_dtkbounds is set to 2 or greater, Toolkit also generates a fatal error if an integer value is passed for a non-integer field or vice versa (though no error is generated for user-defined data types).

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_PUTFLD. I_ PUTFLD, in turn, passes them directly to %IDISPLAY_METHOD. This allows you to communicate additional information to your display method.

If I_PUTFLD is used with an unframed field after the input window for the field has been added to a tab set, renditions will be applied to the field that may not match the renditions for the window. See %TS_TABSET for more information.