.STRUCTURE

Define the structure of a data area

.STRUCTURE data_area[, field_def | value][, ...]

Arguments

data_area

The name of the data area (a maximum of 30 characters).

field_def

(optional) A field definition that has one of the following forms:

field

field@character_pos

field@field_name

field@field_name+offset

where character_pos is a base-one character position within the structure, field_name is a field previously specified within the structure, and field_name+offset is an offset from a field previously specified within the structure.

value

(optional) The number of pad characters, enclosed in angle brackets. You can use value to skip space in your data area between fields.

Discussion

The .STRUCTURE command defines field membership and position within a data area (usually a record).

.STRUCTURE creates a local structure within the current input window. A structure definition is used to verify that no input set contains fields from different structures; a field can be a member of only one structure. Note, however, that a field does not have to be a member of any structure.

At runtime, structure definitions are used to transfer data to and from the field’s data position within its record buffer.

Although a given field can be a member of only one structure, you can specify up to 25 structures in an input window.

You cannot use .STRUCTURE for a repository structure (.REPOSITORY_STRUCTURE). .STRUCTURE is only needed for local fields.

If there are no repository structures and you do not include a .STRUCTURE statement for local fields, a default structure is defined. Its name is the name of the input window, and it comprises all fields in the order that their .FIELD commands are specified. (If the input window has no fields, the default structure will have no fields.)

Thus, if you need only one record containing all fields in the order defined, you don’t need to define the record with .STRUCTURE because it will be created by default.

You can specify up to 507 field_def or values. If you do not specify either, all the fields will be used in the order they are defined. A field name can have a maximum of 30 characters. The maximum size of a structure is 9999 characters (d4). Text fields take up space that equals size x dimension.

In the first form of field_def, the position of field within the structure follows the previous field (or filler) definition. In the second form, field starts at position character_pos within the structure. The third and fourth forms position field relative to field_name within the structure. Note that if the field is specifically positioned by one of the latter three forms, the default position for the next field definition is after this field, regardless of this field’s position within the structure. (Specifically, the next field will not default to the end of the structure.)

Examples

The following example defines a data area named cusinf that has the following fields: cusnum, name, addr1, addr2, city, state, zip.

.structure cusinf, cusnum, name, addr1, addr2, city, state, zip

The next example is very similar to the first, but it designates that 60 pad characters should be placed in the data area between the fields name and city.

.structure cusinf, cusnum, name, <60>, city, state, zip

The following example specifies city to be positioned 30 characters after the beginning of address. If address began at 60, city would begin at 90.

.structure cusinf, cusnam, name, address, city@address+30, state, zip