IB_STRUCTURE

Define a local structure within a new input window

xcall IB_STRUCTURE(build_id, structure, count, fields, [pos][, offset_fields])

Arguments

build_id

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

structure

The name of the local structure (a maximum of 30 characters). (a)

count

The number of structure specifications in the fields array. (n)

fields

An array of structure specifications. A structure specification can be either a field name, or “<value>” where value is the number of pad characters. You can use value to skip space in your structure between fields. Value must be enclosed in angle brackets. (a)

pos

(optional) An array, parallel to the fields array, which contains absolute record positions. (n)

offset_fields

(optional) An array, parallel to the fields array, which contains the field names from which to offset. (a)

Discussion

IB_STRUCTURE defines a local structure within the input window being built. This subroutine is used when building a new input window at runtime.

Structure definitions are used to verify that no input sets contain fields from different structures; a field can only be a member of one structure. Note, however, that a field does not have to be a member of any structure.

Structure definitions are used to transfer data to and from the field’s data position within its record buffer.

Although a given field can only be a member of one structure you can define up to 25 structures per input window.

The maximum size of a structure is 9999 characters (d4). Text fields take up space that equals (size * dimension).

You should not call IB_STRUCTURE for fields drawn from a repository structure. In fact, calling IB_STRUCTURE with the same structure name as in IB_RPS_STRUCTURE will result in a “Structure already defined” error.

IB_STRUCTURE is only needed for fields defined after calling IB_LOCAL. (IB_LOCAL is also the default state.)

If you do not call IB_STRUCTURE or IB_RPS_STRUCTURE for a given input window, a default structure is defined. Its name is the name of the input window, and it is composed of all fields in the order that they are created in the order the IB_FIELD calls were made. (If the input window has no fields, the default structure will have no fields.) Thus, if you need only one record, you don’t need to define it with IB_STRUCTURE. It will be created by default.

IB_STRUCTURE defines membership and position for each field specified. If you do not pass fields, all the fields will be used in the order they were defined.

If pos is zero or not passed, the next position after the previous specification will be used.

If offset_fields is passed and non-blank for a given fields entry, the corresponding pos entry is assumed to be the relative offset from that field.