Variable and Type Declarations
This section describes how to declare variables to EQUEL. It provides a general description of declaration sections and a detailed description of the declaration syntax for all data types.
EQUEL Variable Declaration Procedures
Any Fortran language variable an EQUEL statement uses must be made known to the preprocessor so that it can determine the type of the variable. EQUEL/Fortran does not know the implicit typing conventions Fortran uses, so you must explicitly declare all variables. The preprocessor uses the declaration to set up type information for the Ingres runtime system.
Use two number signs (##) to begin a declaration of a variable in an EQUEL/Fortran program. Begin the signs in the first column position of the line. If the EQUEL statement does not use a variable, you do not need to use number signs.
The Declare and Declare Forms Statements
Prior to any EQUEL declarations or statements in a program unit, you must issue the following statement:
## declare
This statement must follow all implicit statements in the unit. If there are no implicit statements, the ## declare directive must be the first statement in the unit. When your program unit includes EQUEL/FORMS statements, you must use a slightly different variant of the ## declare directive:
## declare forms
These statements make the preprocessor generate a Fortran include statement that includes a file of declarations the Ingres runtime system needs. You cannot link an EQUEL/Fortran program unless you include one of these statements in every program unit that contains EQUEL statements.
The declare statements also served the purpose of scope delimiters in earlier versions of EQUEL/Fortran. For examples of string continuation, see The Scope of Variables.
Reserved Words in Declarations
In declarations, all EQUEL keywords are reserved. Therefore, you cannot declare types or variables with the same name as those keywords. Also, when you use the following EQUEL/Fortran keywords in declarations, they are reserved by the preprocessor and you cannot use them elsewhere, except in quoted string constants:
byte character complex declare | double external function integer | logical map parameter precision | program real record subroutine | structure union |
The EQUEL preprocessor does not distinguish between uppercase and lowercase in keywords. When it generates Fortran code, it converts any uppercase letters in keywords to lowercase. This rule is true only for keywords. The preprocessor does distinguish between case in program-defined types and variable names.
Variable and type names must be legal Fortran identifiers that begin with an alphabetic character.
Typed Data Declarations
Linux: The preprocessor recognizes numeric variables declared with the following format:
data_type [*default_type_len]
var_name [*type_len] [(array_spec)]
{, var_name [*type_len] [(array_spec)]
var_name [*type_len] [(array_spec)]
{, var_name [*type_len] [(array_spec)]
The preprocessor recognizes character variables declared with the following format:
data_type [*default_type_len[,]]
var_name [(array_spec)] [*type_len]
{, var_name [(array_spec)] [*type_len]}
var_name [(array_spec)] [*type_len]
{, var_name [(array_spec)] [*type_len]}
Windows: The preprocessor recognizes numeric variables declared with the following format:
data_type [*default_type_len]
var_name [*type_len] [(array_spec)] [/init_clause/]
{, var_name [*type_len] [(array_spec)] [/init_clause/] }
var_name [*type_len] [(array_spec)] [/init_clause/]
{, var_name [*type_len] [(array_spec)] [/init_clause/] }
The preprocessor recognizes character variables declared with the following format:
data_type [*default_type_len[,]]
var_name [(array_spec)] [*type_len] [/init_clause/]
{, var_name [(array_spec)] [*type_len] [/init_clause/] }
var_name [(array_spec)] [*type_len] [/init_clause/]
{, var_name [(array_spec)] [*type_len] [/init_clause/] }
Syntax Notes:
• The default_type_len specifies the size of the declared variable. To specify size for a numeric type variable, use an integer literal of an acceptable length for the particular data type. To specify size for a character type variable, use an integer literal or a parenthesized expression, followed optionally by a comma. The preprocessor does not interpret the length field for variables of type character but merely passes that information to the output file. Note the default type lengths in the following declarations:
C Declares "eage" a 2-byte integer
integer*2 eage
C Declares "stat" a 2-byte integer
logical*2 stat
C Declares "ename" a character string
character*(4+len) ename
integer*2 eage
C Declares "stat" a 2-byte integer
logical*2 stat
C Declares "ename" a character string
character*(4+len) ename
• The type_len allows you to declare a variable with a length different from default_type_len. Again, you can use a parenthesized expression only to declare the length of character variable declarations. The type length for a numeric variable must be an integer literal that represents an acceptable numeric size. For example:
C Default-sized integer and 2-byte integer
integer length
integer*2 height
character*15 name, socsec*(numlen)
integer length
integer*2 height
character*15 name, socsec*(numlen)
Some Fortran compilers do not permit the redeclaration of the length of a character variable.
• The variable names must be legal Fortran identifiers.
• The array_spec must conform to Fortran syntax rules. The preprocessor simply notes that the declared variable is an array, but does not parse the array_spec clause.
Constant Declarations
To declare constants to EQUEL/Fortran, use the Fortran parameter statement with the following syntax:
Linux:
parameter (const_name = value {, const_name = value}) 
Windows:
parameter const_name = value {, const_name = value}
or
parameter( const_name = value {, const_name = value}) 
Syntax Notes:
• The data type of const_name derives its data type from the data type of value. Do not put explicit data type declarations in parameter statements. In addition, as with variable declarations, the preprocessor does not assign a data type based on the first letter of const_name.
• The value can be a real, integer or character literal. It cannot be an expression or a symbolic name.
The following example declarations illustrate the parameter statement:
Linux:
C real constant
parameter (pi = 3.14159 )
C integer and real
parameter (bigint = 2147483648, bgreal = 999999.99)
parameter (pi = 3.14159 )
C integer and real
parameter (bigint = 2147483648, bgreal = 999999.99)
Windows:
## parameter pi = 3.14159 ! real constant
## parameter(bigint = 2147483648, bgreal = 999999.99)
! integer and real
## parameter(bigint = 2147483648, bgreal = 999999.99)
! integer and real
Data Types
The EQUEL/Fortran preprocessor accepts the elementary Fortran data types shown in the following table. The table maps these types to corresponding Ingres types. For more information on type mapping between Ingres and Fortran data, see Data Type Conversion.
Fortran Data Type | Ingres Types |
|---|---|
integer | integer |
integer*N where N = 2 or 4 | integer |
logical | integer |
logical*N where N = 1, 2 or 4 | integer |
byte | integer |
real | float |
real*N where N = 4 or 8 | float |
double precision | float |
character*N where N > 0 | character |
real*8 | decimal |
The Integer Data Type
The Fortran compiler allows the default size of integer variables to be either two or four bytes in length, depending on whether the -i2 compiler flag (Linux) or the /integer_size:16 compiler option (Windows) is set.
EQUEL/Fortran also supports this feature by means of the -i2 preprocessor flag. This flag tells the preprocessor to treat the default size of integer variables as two instead of the normal default size of four bytes. For more information on type mapping between Ingres and Fortran data, see Precompiling, Compiling, and Linking an EQUEL Program) .
You can explicitly override the default size when declaring the Fortran variable to the preprocessor. To do so, you must specify a size indicator (*2 or *4) following the integer keyword, as these examples illustrate:
integer*4 bigint
integer*2 smalli
integer*2 smalli
The preprocessor then treats these variables as a four-byte integer and a two-byte integer, regardless of the default setting.
Linux: The preprocessor treats the logical data type as an integer data type. A logical variable has a default size of 4 bytes. To override this default size, use a size indicator of 2 or 4. For example:
logical*2 log2
logical*4 log4
logical*1 log1
logical*4 log4
logical*1 log1
Windows: The preprocessor treats byte and logical data types as an integer data type. A logical variable has a default size of 4 bytes. To override this default size, use a size indicator of 2 or 4. For example:
## logical*2 log2
## logical*4 log4
## logical*1 log1
## logical*4 log4
## logical*1 log1
The byte data type has a size of one byte. You cannot override this size.
You can use an integer or byte variable with any numeric-valued object to assign or receive numeric data. For example, you can use such a variable to set a field in a form or to select a column from a database table. This variable can also specify simple numeric objects, such as table field row numbers. You can use a logical variable to assign or receive integer data, although your program must restrict its value to 1 and 0, which map respectively to the Fortran logical values .TRUE. and .FALSE..
The Real Data Type
EQUEL/Fortran accepts real and double precision as legal real data types. The preprocessor accepts both 4-byte and 8-byte real variables. It makes no distinction between an 8-byte real variable and a double precision variable. The default size of a real variable is 4 bytes. However, you can override this size if you use a size indicator (*8) that follows the real keyword or the variable's name.
You can only use a real variable to assign or receive numeric data (both real, decimal, and integer). You cannot use it to specify numeric objects, such as table field row numbers.
C 4-byte real variable
## real salary
C 8-byte real variable
## real*8 yrtoda
C 8-byte real variable
## double precision saltot
## real salary, yrtodate*8
## real salary
C 8-byte real variable
## real*8 yrtoda
C 8-byte real variable
## double precision saltot
## real salary, yrtodate*8
Only use a real variable to assign or receive numeric data (both real and integer). Do not use it to specify numeric objects, such as table field row numbers.
The Character Data Type
Fortran variables of type character are compatible with all Ingres character string objects. EQUEL/Fortran does not need to know the declared length of a character string variable to use it at runtime. Therefore, it does not check the validity of any expression or symbolic name that declares the length of the string variable. You should ensure that your string variables are long enough to accommodate any possible runtime values. For information on the interaction between character string variables and Ingres data at runtime, see Runtime Character Conversion.
## character*7 first
## character*10 last
## character*1 init
## character*(bufsiz) msgbuf
## character*10 last
## character*1 init
## character*(bufsiz) msgbuf
Structure and Record Declarations
EQUEL/Fortran supports the declaration and use of user-defined structure variables. The syntax of a structure definition is:
structure [/structdef_name/] [field_namelist]
field_declaration
{field_declaration}
end structure
field_declaration
{field_declaration}
end structure
Syntax Notes:
• The structdef_name is optional only for a nested structure definition.
• The field_namelist is allowed only with a nested structure definition. Each name in the field_namelist constitutes a field in the enclosing structure.
• The field_declaration can be a typed data declaration (see Typed Data Declarations), a nested structure declaration, a union declaration, a record declaration, or a fill item.
The syntax of a union declaration is as follows:
union
map_declaration
map_declaration
{map_declaration}
end union
map_declaration
map_declaration
{map_declaration}
end union
where map_declaration is:
map
field_declaration
{field_declaration}
end map
field_declaration
{field_declaration}
end map
• Only field_declarations that are referenced in EQUEL statements need to be declared to EQUEL. The following example declares a Fortran structure with a member "checked" that is not known to EQUEL.
## structure /address/
## integer number
## character*20 street
## character*10 town
## integer*2 zip
logical checked
## end structure
## record /address/addr
## integer number
## character*20 street
## character*10 town
## integer*2 zip
logical checked
## end structure
## record /address/addr
To use a structure with EQUEL statements, you must both define the structure and declare the structure's record to EQUEL. The record declaration has the following syntax:
record /structdef_name/ structurename {,[/structdef_name/]
structurename}
structurename}
Syntax Note:
The structdef_name must be previously defined in a structure statement.
For information on the use of structure variables in EQUEL statements, see Using a Structure Member.
The following example includes a structure definition and a record declaration:
## structure /name_map/
## union
## map
## character*30 fullname
## end map
## map
## character*10 firstnm
## character*2 init
## character*18 lastnm
## end map
## end union
## end structure
## record /name_map/ empname
## union
## map
## character*30 fullname
## end map
## map
## character*10 firstnm
## character*2 init
## character*18 lastnm
## end map
## end union
## end structure
## record /name_map/ empname
The next example shows the definition of a structure containing an array of nested structures:
## structure /class_struct/
## character*10 subject
## integer*2 year
## structure student(100)
C No structure definition name needed
## character*12 name
## byte grade
## end structure
## end structure
## record /class_struct/ classrec
## character*10 subject
## integer*2 year
## structure student(100)
C No structure definition name needed
## character*12 name
## byte grade
## end structure
## end structure
## record /class_struct/ classrec
Indicator Variables
An indicator variable is a 2-byte integer variable. There are three ways to use in an application:
• In a statement that retrieves data from Ingres, you can use an indicator variable to determine if its associated host variable was assigned a null.
• In a statement that sets Ingres data, you can use an indicator variable to assign a null to the database column, form field, or table field column.
• In a statement that retrieves character data from Ingres, you can use the indicator variable as a check that the associated host variable was large enough to hold the full length of the returned character string.
The following declaration illustrates how to declare a null indicator variable:
C Indicator variable
## integer*2 ind
## integer*2 ind
Compiling and Declaring External Compiled Forms - Linux
You can precompile your forms in VIFRED. This saves the time otherwise required at runtime to extract the form's definition from the database forms catalogs. When you compile a form in VIFRED, VIFRED creates a file in your directory describing the form in C. VIFRED prompts you for the name of the file with the description. After the file is created, you can use the following cc command to compile it into linkable object code:
cc -c filename
This command produces an object file that contains a global symbol with the same name as your form.
Before the EQUEL/FORMS statement addform can refer to this global object, use the following syntax to declare it to EQUEL:
extern int *formname;
Next, for the program to access the external form definition, you must declare the formname as an external symbol:
external formname
Because this second declaration is not an EQUEL declaration, do not precede it with the ## mark. Its purpose is to inform the linker to associate the global symbol in the compiled form file with the object of the addform statement.
Syntax Notes:
• formname is the actual name of the form and appears as the title of the form in EQUEL/FORMS statements other than the addform statement. It is also the name that VIFRED gives to the global object in the compiled form file.
In all EQUEL/FORMS statements other than the addform statement that expect a form name you must dereference formname with # so that it is interpreted as a name and not as an integer variable.
• The EXTERNAL statement associates the external form definition with the integer object used by the addform statement.
## integer empfrm
external empfrm
C The global object
## ADDFORM empfrm
C The name of the form must be dereferenced
C because it is also the name of a variable
## DISPLAY #empfrm
external empfrm
C The global object
## ADDFORM empfrm
C The name of the form must be dereferenced
C because it is also the name of a variable
## DISPLAY #empfrm
Compiling and Declaring External Compiled Forms - Windows
You can precompile your forms in VIFRED. By doing so, you save the time otherwise required at run time to extract the form's definition from the database forms catalogs. When you compile a form in VIFRED, VIFRED creates a file in your directory describing the form in C. VIFRED prompts you for the name of the file in which to write the description. After the file is created, you can use the following Windows command to compile it into a linkable object module:
cl –c filename
This command produces an object file containing a global symbol with the same name as your form. Before the EQUEL/FORMS statement addform can refer to this global object, you must declare it to EQUEL with the following syntax:
integer formname
Next, in order for the program to access the external form definition, you must declare the formname as an external symbol:
external formname
This second declaration is not an EQUEL declaration and you should not precede it by the ## mark. Its purpose is to inform the linker to associate the global symbol in the compiled form file with the object of the addform statement.
Syntax Notes:
• formname is the actual name of the form; it appears as the title of the form in EQUEL/FORMS statements other than the addform statement. It is also the name that VIFRED gives to the global object in the compiled form file. In all EQUEL/FORMS statements other than the addform statement that expect a form name, you must dereference formname with # so that it is interpreted as a name and not as an integer variable.
• The EXTERNAL statement associates the external form definition with the integer object used by the addform statement.
The following example illustrates these points:
## integer empfrm
external empfrm
## addform empfrm ! The global object
## display #empfrm ! The name of the form must be dereferenced
## ! because it is also the name of a variable
external empfrm
## addform empfrm ! The global object
## display #empfrm ! The name of the form must be dereferenced
## ! because it is also the name of a variable
Concluding Example
The following example contains some simple EQUEL/Fortran declarations:
Linux:
## declare
C Variables of each data type
## byte dbyte
## logical*4 log4
## logical logdef
## integer*2 dint2
## integer*4 dint4
## integer intdef
## real*4 dreal4
## real*8 dreal8
## real dreal
C Constant
## parameter (MAXVAL = 1000)
## character*12 dbname
## character*12 drmnam, tblnam, colnam
C Compiled forms
## integer empfrm, dptfrm
external empfrm, dptfrm
C Variables of each data type
## byte dbyte
## logical*4 log4
## logical logdef
## integer*2 dint2
## integer*4 dint4
## integer intdef
## real*4 dreal4
## real*8 dreal8
## real dreal
C Constant
## parameter (MAXVAL = 1000)
## character*12 dbname
## character*12 drmnam, tblnam, colnam
C Compiled forms
## integer empfrm, dptfrm
external empfrm, dptfrm
Windows:
## declare
## byte d_byte !Variables of each data type
## logical*1 d_log1
## logical*2 d_log2
## logical*4 d_log4
## logical d_logdef
## integer*2 d_int2
## integer*4 d_int4
## integer d_intdef
## real*4 d_real4
## real*8 d_real8
## real d_realdef
## double precision d_doub
## parameter MAX_PERSONS = 1000 ! Constant
## character*12 dbname/'personnel'/
## character*12 formname, tablename, columnname
## structure /person/ ! Structure with a union
## byte age
## integer flags
## union
## map
## character*30 full_name
## end map
## map
## character*12 firstname
## character*18 lastname
## end map
## end union
## end structure
! Record/array of records
## record /person/ person, p_table(MAX_PERSONS)
## integer empfrm, deptform ! Compiled forms
external empfrm, deptform ! Compiled forms
## byte d_byte !Variables of each data type
## logical*1 d_log1
## logical*2 d_log2
## logical*4 d_log4
## logical d_logdef
## integer*2 d_int2
## integer*4 d_int4
## integer d_intdef
## real*4 d_real4
## real*8 d_real8
## real d_realdef
## double precision d_doub
## parameter MAX_PERSONS = 1000 ! Constant
## character*12 dbname/'personnel'/
## character*12 formname, tablename, columnname
## structure /person/ ! Structure with a union
## byte age
## integer flags
## union
## map
## character*30 full_name
## end map
## map
## character*12 firstname
## character*18 lastname
## end map
## end union
## end structure
! Record/array of records
## record /person/ person, p_table(MAX_PERSONS)
## integer empfrm, deptform ! Compiled forms
external empfrm, deptform ! Compiled forms
Last modified date: 04/03/2024