Variable Declaration

Declare a structure variable.

[global] structure STRUCTDEF_NAME

{ NAME

| NAME[N]

| NAME[N1, N2, ...]

| NAME[N thru N, N thru N ...]

| NAME[N thru N] }

global

Define a global structure variable. If you define a structure as global, you can refer to it not only in the program in which it is defined, but in any other program to which control is transferred with the change to program action statement.

STRUCTDEF_NAME

The identifier of a structure type that was previously defined in the ESL program.

NAME

The identifier for the structure variable. The variable can be a single instance of the specified structure type, or an array. If it is an array, each element is a structure of the specified type. Note that the brackets shown with the subscripts in the model are literal. For an array, these subscript brackets must be specified exactly as shown.

N

An integer value representing the number of structures in a one-dimensional array, starting with 1 and ending with N.

N1, N2, ...

Integer values representing the number of structures for each dimension of the array, starting with 1 and ending with N1, N2, ... respectively. The number of dimensions must not exceed 11.

N thru N

Integer values representing the beginning and ending integers used to reference the structure elements.

Description

Use this statement to declare a structure variable, which is a named aggregate variable composed of one or more fields of varying types.

A named structure type must be defined before a structure variable of that type can be declared.

The individual fields in a structure variable can be used like normal ESL variables, with some exceptions. For a list of places where you cannot reference a field, see "Structure Field Reference."

After it is declared, a structure variable can be passed as an argument to an ESL subroutine, an external subroutine, or an external function. A structure is always passed by reference, and normally an ESL function can accept only arguments passed by value. However, there is an exception that allows you to pass structures to external functions. If the structure is declared as global, it can also be referenced in other ESL programs to which control has been transferred.

You can pass a whole structure to an external function by reference. You can pass an individual field in a structure to an ESL function or an external function by value.

Before global structures are loaded from global space into program space for an ESL program that is executed by a change to program statement, ESL checks whether a structure being loaded matches any structure in the program being changed to. If the structures have the same name, type, and length, but differ internally (for example, the fields are in a different order), results are unpredictable. To avoid this situation, be sure to define every structure type to be used for a global structure in an include file, and include the file in any ESL program in which the structure will be used.

When you declare an array of structures or a structure containing array fields, all the rules that pertain to arrays apply. In addition, for ESL for Windows programs, you must ensure that the structure fits into 64K bytes. For information about how to calculate the overall length of a structure type, see Chapter 9 in the Programming Guide.

A single dimension of an array of structures can contain no more than 32767 elements.

You can pass the name of any structure variable to an internal ESL subroutine. The structure can contain array fields. You cannot pass an array of structures to a subroutine, nor can you pass an individual field to a subroutine.

You cannot declare a structure variable within an ESL subroutine.

You cannot define a global structure variable with the same name as a subroutine parameter.

You cannot dynamically resize a field in a structure, a structure in an array of structures, or a structure of arrays using the resize action statement.

For the best results, always define a structure type in an include file if it will be used to declare global structure variables. You should also declare all global structure variables in an include file. If you put both the structure type definitions and all global structure declarations into an include file, your code is simpler, and you ensure that the global structures are defined and declared the same way in every program in which they are used.

Default Values

The default value for initializing a field in a structure depends on its type, as follows:

All fields in a structure are always initialized to zero. This includes all array elements, if the structure contains an array. You cannot override this initialization with the -d runtime command line option. A field has a value of zero or null until another value is assigned to it during execution.

Example

# Given the following structure type definitions:

 

# Structure type AddressRecord

structure AddressRecord is

 string Street

 City

 State

 Zip

end structure # Continued

 

# Structure type EmergencyContactRecord

structure EmergencyContactRecord is

string Name

structure AddressRecord Address

string Phone

end structure

 

# Structure type EmployeeRecord

structure EmployeeRecord is

string Name

structure AddressRecord Address

integer NumDependents

structure Dependents is

 string DependentName

 structure AddressRecord DependentAddress

end structure Dependents[10]

structure EmergencyContactRecord EmergencyContact

float Salary

end structure

 

# Structure variable declaration:

structure EmployeeRecord Employee

 

# Subroutine declarations:

subroutine GetEmployeeData

 (structure EmployeeRecord: Emprec)

subroutine UpdateEmployeeDB

 (structure EmployeeRecord: Emprec)

 

# Examples of valid references to structure fields:

copy "Boston"         to Employee.Address.City

copy "John"         to Employee.DependentList[1].DependentName

copy "Tom"         to Employee.EmergencyContact.Name

send Employee.Salary to errorlog

 

# Examples of valid references to structure variables:

call GetEmployeeData (Employee)

call UpdateEmployeeDB (Employee)

 

Example #2: # Structure type definitions:

structure Employee is

 string Name

 integer AddressPtr

end structure

 

structure Address is

 string Street

 City

 State

 Zip

end structure

 

# Structure variable declarations:

structure Employee Emp

 structure Address Addr

 

# Copy handle of one structure into field in another

copy handle of Addr to Emp.AddressPtr

See Also

Structure Field Reference

structure is Type Definition