Type Definition

Define a named compound data type.

structure STRUCT_NAME is

{integer|float|string}

{ NAME

| NAME[N]

| NAME[N1, N2, ...]

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

| NAME[N thru N]} ...

[ using {integer|float|string} [size N] [format STRING]

[DLL_ENTRY]

#OR#

using external size N [format STRING]

"DLLFILENAME.ROUTINENAME" ]

end structure

 

#OR#

 

structure STRUCT_NAME is

structure STRUCT_NAME1

{ NAME

| NAME[N]

| NAME[N1, N2, ...]

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

| NAME[N thru N]} ...

STRUCTURE_DEFINITION

{ NAME

| NAME[N]

| NAME[N1, N2, ...]

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

| NAME[N thru N]} ...

end structure

STRUCT_NAME

The identifier for the structure type. You can specify this name as the type in a structure declaration to declare a structure variable.

integer | float | string

The ESL type for the field or fields specified. The ESL type defines the set of permissible ESL operations for the field. For fields with a using clause, the ESL type is the type to which the external format is converted for a read reference. Note that you cannot specify boolean as a type for a field.

NAME

The field name. Each field must have a name that is unique within that structure type definition; however, the field can have the same name as a field within a different structure type definition in the same program. Because you must always specify the structure name when you reference a field, the field itself can have the same name as a region, record, action routine, or variable within the same program. The field can be simple or it can be an array. If it is an array, you specify the dimensions following the name. Note that the brackets shown with the array dimensions are literal; you must specify them exactly as shown.

A field is like an ESL variable. It holds a value you can change within your program, and it can be referenced the same way you would use an ESL variable, with some exceptions. A field can itself have a structure type. Structures can be nested up to 25 levels.

N

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

N1, N2, ...

Integer values representing the number of elements for each dimension of the array field, starting with 1 and ending with N1, N2, ... respectively. The number of dimensions must not exceed 11 and a single dimension of an array field can contain no more than 32767 elements.

N thru N...

Integer values representing the beginning and ending integers used to reference the elements of the array field.

If you specify more than one name in a single field definition, ESL creates a series of fields, each with the same definition.

using integer

using float

using string

The data in the field is stored in an external, non-ESL format of integer, float, or string at the specified size, and is suitable for one of the default conversions supplied by the ESL compiler. Whenever your ESL program references the field, if the field has a using clause, ESL copies the field and converts it from the external format to the ESL type before performing the operation. When your program writes to the field, ESL converts the value to the external format first.

size N

The size in eight-bit bytes of the external field as it is actually stored. This value must be a non-zero integer value. To use a default conversion for a C signed integer, the size must be one, two, or four bytes. To use a default conversion for a C float, the size must be four or eight bytes. If specifying the size of a string, unless the "nonull" format is specified, add one (1) to the actual length of the string to account for the null terminator that ESL places at the end of strings. If this "size" clause is missing, a default size of 4 bytes is used.

format STRING

A string of any format containing additional information that you want passed to an external conversion routine (DLL_ENTRY). This is useful for custom-written external conversion routines. ESL imposes no requirements on the contents of this string, other than the requirements imposed by the conversion routine itself. However, if you want to define a C string data type that is not terminated by a null, then STRING must be "nonull" (Note. this format string is not case sensitive).

"DLLFILENAME.ROUTINENAME"

DLLFILENAME is the name of a DLL file without the extension. ROUTINENAME is the name of a routine that resides in the DLL file and is exported in the definition file for the DLL. It must be an external conversion routine capable of converting the field from its external storage format into the ESL type specified for the field, and vice versa. The ESL type, which you specify before the field name, defines the set of operations that can be performed on the field within ESL. Because the external conversion routine is called by the ESL runtime system, you do not call it explicitly in your ESL program and you do not declare it in ESL as a function or subroutine. For information about external conversion routines, see Exchanging Structures with External Routines.

using external

The field is stored in an external, non-ESL format for which ESL does not provide a default conversion. If you specify external, you must also specify the size clause and a quoted string that is the name of an entry in a DLL file.

Because a field with a using clause is always stored in the external format, there might be some performance impact when manipulating that field in ESL because the conversion is performed each time the external field is referenced.

If performance becomes an issue, you can use the following approach in your ESL source code. Define a second structure without using clauses, or just define a group of ESL variables and copy the data there for all ESL operations. You can then copy it back to the structure with external-format fields only when you need to pass it to an external subroutine or function.

STRUCT_NAME1

The identifier for a structure type that was previously defined in the program. STRUCTDEF_NAME1 specifies a structure type for the field. This allows you to nest one structure inside another by referring to a previously defined structure type. Note that STRUCTDEF_NAME1 cannot be the same as STRUCTDEF_NAME. A structure type definition cannot contain a reference to itself.

Use the form structure STRUCT_NAME1 STRUCTFIELD_LIST to specify a field definition (named STRUCT_NAME1) that is itself a structure type that has previously been defined in the program or an included file. Structures can be nested up to 25 levels.

STRUCTURE_DEFINITION

The complete definition of another structure type, embedded within this structure type. This allows you to nest the definition of one structure physically within the definition of another structure type. When you nest the whole definition of one structure inside another, the nested structure definition cannot be referenced outside the parent structure.

Description

The structure is type definition defines a named compound data type, composed of one or more fields of varying ESL types. You must define a structure type before referencing it in a variable declaration. You can then specify the name of the structure type as the type of an ESL variable.

Use structures for any of the following purposes:

To group variables under one name as a convenient way of passing arguments to subroutines within ESL programs.

To pass data to and from external subroutines and functions, even if they expect and store data in non-ESL formats.

To pass data to external functions that expect some arguments by reference and some by value. See the Writing Your Own Conversion Routines for more information.

When a structure is passed to an external routine, it is always passed by reference, even if you define the external routine as a function. Although ESL normally passes all arguments to functions by value, there is an exception for structures.

Structures also allow you to pass data to external subroutines and functions that expect to receive a data structure containing a field whose value is the address of (pointer to) another structure. To do this, use the copy action statement with the "handle of" built-in function to copy the address pointer of one structure into a field in another structure. For more information, see the "handle of" built-in function.

If you plan to write an application comprising more than one ESL program, and you plan to use global structures within that application, you should define the structure type and declare the global structure variables in an include file. This will ensure that there are no differences between structures declared in different programs, which could lead to unpredictable results.

Default Conversions for C Data

ESL provides default conversions for some C storage formats. The following table shows how to specify the using clause for each of these C storage formats:

Note: ESL stores integers internally as four-byte signed integers, so the using clause is optional in that case. Likewise, ESL stores floats internally as eight-byte double floats, so the using clause is optional in that case as well.

For any C data type other than the types shown here, you must specify using external and the name of your own external conversion routine.

Both SBCS (Single-Byte Character Set) and DBCS (Double-Byte Character Set) strings are supported within structures.

You should not convert a C-language unsigned long into an ESL integer value. This is because all ESL integers are signed, so ESL always treats the high-order bit of an integer as the sign rather than as part of the value.

Example

# Using ESL types:

structure Employee is

string Name

Address

integer NumDependents

end structure

# Using an external format:

structure Date is

integer Month

Day

Year using integer size 2 # Field with C language

# format.

end structure

See Also

Array Definition and Reference

initialize Action Statement

structure Variable Declaration

Structure Field Reference

The Programming Guide for information about how to write your own external conversion routine.

Handle of built-in function.