Refer to a field within a structure.

STRUCTVAR_NAME [[N]|[N1,N2,...]]

{.FIELD_NAME [[N]|[N1,N2,...]]} ...

STRUCTVAR_NAME

A structure variable that has previously been defined in the program or in an included file.

N

An integer value that specifies the subscript of a particular element in a one-dimensional array field.

N1, N2, ...

Integer values that specify the subscripts of a particular element in a multi-dimensional array field.

. (period)

The field selector, which must precede each field name. Do not insert a space before or after the period.

FIELD_NAME

The identifier for a field within the structure. In a nested structure, only the fields at the bottom level can be referenced like normal variables.

Description

Refer to a field within a structure variable in an ESL program. A structure variable is a named aggregate variable composed of one or more fields of varying types. Each field can be used as a variable.

First you define a structure type, then you declare one or more instances of structure variables. After it is declared, a structure variable and its individual fields can be referenced in the program.

To reference a field in a structure, you specify the name of the structure, a period which is the field selector, and the name of the field. Because you can manipulate only the fields at the bottom level of the structure, you must specify, in order, all the intermediate-level fields in a nested structure, ending with the lowest-level field. Precede the name of each field with a period. This syntax allows the precise specification of an individual field.

In general, you can reference a field in ESL anywhere you can reference a variable. There are some exceptions where field references are not allowed. These are listed under "Illegal Field References."

Individual fields cannot be passed as arguments to subroutines. However, an entire structure variable can be passed as an argument to an ESL subroutine or an external subroutine.

You can also pass a structure as an argument to an external function. Usually, arguments are passed to functions by value. However, when structures are passed to external functions, they are passed by reference.

If a structure is declared as global, it can also be referenced in other ESL programs to which control has been transferred.

When you define an ESL subroutine, any variables local to the subroutine cannot be fields in a structure.

If the structure variable is an array of structures, you must specify the subscripts to indicate the appropriate structure element. If a field is an array, you must specify subscripts to indicate the appropriate element within the field.

Illegal Field References

The following list shows the cases in which, although you can reference a variable, you cannot reference a field in a structure.

In a record definition, for use with the File I/O Library subroutines.

As the event filter or parameter filter in a response to stimulus match clause.

As the counter variable (INTEGER_VAR_NAME) in a for loop action statement.

As the object of a resize action statement.

In addition, a field in a structure:

Cannot be statically initialized. For example, in a statement such as "integer I is 3", "I" cannot be a field.

Cannot be initialized with the -d runtime command line option.

Other Restrictions

Note that, in general, it does not make sense to reference fields in compile-time references. That is because fields always have a value of zero at compile time. A field cannot have a value other than zero until another value is assigned to it during execution of the program. For example, although the ESL compiler allows you to specify a field as the X or Y dimension of an ESL region, you will always get the compile time value of zero for the field.

Normally, you cannot use the append statement to append a string to an array. However, you can append to a string element within an array as long as the array is within a structure.

Copying a Pointer to a Structure

If you have an external subroutine or function that expects a structure containing a field that points to another structure, you can use the copy action statement with the handle of built-in function to copy a pointer to one structure into an integer field in another structure. This technique cannot be used to obtain a pointer to a single structure within an array of structures. However, you can use it to obtain a pointer to an array of structures. For more information, see Chapter 9 in the Programming Guide.

Example

copy "Boston" to Employee.Address.City

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

copy Employee.Salary to YearlySalary

See Also

structure Variable Declaration

structure is Type Definition