Ingres 12.0 | Variable and Type Declarations

Embedded QUEL Companion Guide > Embedded QUEL Companion Guide > Embedded QUEL for Fortran > Fortran Variables and Data Types > Variable and Type Declarations

Was this helpful?

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

UNIX: 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)]

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]}

VMS: 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/] }

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/] }

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/] }

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/] }

Syntax Notes:

• For information on the allowable data_types, see Data Types.

• 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

• 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)

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.

VMS: Note that, if you specify both an array and a type length, the order of those two clauses differs depending on whether the variable being declared is of character or numeric type. Note the following examples of array declarations:

## character*16 enames(100), edepts(15)*10
! Array specification first

## real*4 salestab(5,12), yeartotals*8(12)
! Type length first

• The preprocessor allows you to initialize a variable or array in the declaration statement using the init_clause. The preprocessor accepts, but does not examine, any initial data. The Fortran compiler, however, later detects any errors in the initial data. For example:

## real*8 initcash /512.56/
## character*4 baseyear /'1950'/
## character*4 year /1950/
! Acceptable to preprocessor but not to compiler

Do not continue initial data over multiple lines. If an initialization value is too long for the line, as could be the case with a string constant, use the Fortran data statement instead.

Constant Declarations

To declare constants to EQUEL/Fortran, use the Fortran parameter statement with the following syntax:

UNIX:

parameter (const_name = value {, const_name = value})

VMS:

parameter const_name = value {, const_name = value}

Windows:

parameter const_name = value {, const_name = value}

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:

UNIX:

C real constant
parameter (pi = 3.14159 )
C integer and real
parameter (bigint = 2147483648, bgreal = 999999.99)

VMS:

##  parameter pi = 3.14159   ! real constant
##  parameter bigint = 2147483648, bgreal = 999999.99
            ! integer and real

Windows:

##  parameter pi = 3.14159   ! real constant
##  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 (UNIX), the noi4 qualifier (VMS), 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

The preprocessor then treats these variables as a four-byte integer and a two-byte integer, regardless of the default setting.

UNIX: 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

VMS: The preprocessor treats byte and logical data types as integer data types. A logical variable has a default size of either two or four bytes, according to whether the -i2 flag has been set. You can override this default size by a size indicator of 1, 2 or 4. For example:

## logical log1*1, log2*2, log4*4

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

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.

VMS: The preprocessor expects the internal format of real and double precision variables to be the standard VAX format. For this reason, you should not compile your program with the g_floating qualifier.

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

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

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

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

where map_declaration is:

       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

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}

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

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

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

Assembling and Declaring External Compiled Forms - VMS

You can precompile your forms in the Visual Forms Editor (VIFRED). By doing so, you save 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 the VAX-11 MACRO language. VIFRED prompts you for the name of the file in which to write the MACRO description. After the file is created, you can use the following VMS command to assemble it into a linkable object module:

macro 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

Compiling and Declaring External Compiled Forms - UNIX

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

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

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

Syntax Notes:

• 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

Concluding Example

The following example contains some simple EQUEL/Fortran declarations:

UNIX:

##    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

VMS:

##    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

Windows:

Last modified date: 08/28/2024