Ingres 11.0 | Data Types

Embedded QUEL Companion Guide > Embedded QUEL Companion Guide > Embedded QUEL for COBOL > COBOL Variables and Data Types > Data Types

Was this helpful?

Data Types

EQUEL/COBOL supports a subset of the COBOL data types. The following table maps the COBOL data types to their corresponding Ingres types. Note that the COBOL data type is determined by its category, picture and usage.

COBOL Type			Ingres Type
Category	PICTURE	USAGE	Ingres Type
ALPHABETIC	any	DISPLAY	character
ALPHANUMERIC	any	DISPLAY	character
ALPHANUMERIC EDITED	any	DISPLAY	character
NUMERIC	9(p) where p <= 10	COMP, DISPLAY	integer
NUMERIC	9(p)V9(s) where p+s <= 9	COMP, DISPLAY	float
NUMERIC	9(p) where p <= 10	COMP-3	integer
NUMERIC		INDEX	integer
NUMERIC EDITED	any	DISPLAY	integer, float

VMS:

COBOL Type			Ingres Type
Category	PICTURE	USAGE	Ingres Type
NUMERIC		COMP-1	float
NUMERIC		COMP-2	float

COMP is an abbreviation for COMPUTATIONAL. You can use either form. Note that POINTER data items are not supported. The following sections describe the various data categories and the manner in which EQUEL interacts with them.

The Numeric Data Category - UNIX

EQUEL/COBOL accepts the following declarations of numeric variables:

level-number data-name PIC [IS] pic-string [USAGE [IS]]
COMP|COMP-3|COMP-5 |DISPLAY.
level-number data-name [USAGE [IS]] INDEX.

Syntax Notes:

• Use the symbol "S" on numeric picture strings to indicate the presence of an operational sign.

• The picture string (pic-string) of a COMP, COMP-3, COMP-5 data item can contain only the symbols "9", "S", and "V" in addition to the parenthesized length.

• In order to interact with Ingres integer-valued objects, the picture string of a COMP, COMP-3 or DISPLAY or COMP-5 item must describe a maximum of 10 digit positions with no scaling.

• Do not use a picture string for INDEX data items. While the preprocessor ignores such a picture string, the compiler does not allow it.

You can use any data items in the numeric category to assign and receive Ingres numeric data in database tables and forms. However, you can only use non-scaled COMP, COMP-3, COMP-5 and DISPLAY items of 10 digit positions or less to specify simple numeric objects, such as table field row numbers. Generally, try to use COMP data items with no scaling to interact with Ingres integer-valued objects, since the internal format of COMP data is compatible with Ingres integer data.

Ingres effects the necessary conversions between all numeric data types, so the use of DISPLAY and COMP-3 scaled data items is allowed. For more information on type conversion, see Data Type Conversion.

The following example contains numeric data categories:

##  01 QUAD-INTVAR       PIC S9(10) USAGE COMP.
##  01 LONG-INTVAR       PIC S9(9) USAGE COMP.
##  01 SHORT-INTVAR      PIC S9(4) USAGE COMP.
##  01 DISPLAY-VAR       PIC S9(10) USAGE DISPLAY.
##  01 PACKED-VAR        PIC S9(12)V9(4) USAGE COMP-3.

Numeric Data Items with Usage COMP-5 - UNIX

Ingres supports data items declared with USAGE COMP-5. When you specify this clause, the data item is stored in the same machine storage format as the native host processor rather than in the byte-wise Micro Focus storage format. Of course, sometimes the two storage formats are identical. Since the Ingres runtime system that is linked into your COBOL runtime support module (RTS) is written in C, it is important that Ingres interact with native data types rather than Micro Focus data types. Consequently, many of your normal USAGE COMP data items are transferred (using COBOL MOVE statements) into internally declared Ingres USAGE COMP-5 data items. Data items declared with this USAGE will cause a compiler informational message (209-I) to occur.

The Numeric Data Category - VMS

EQUEL/COBOL accepts the following declarations of numeric variables:

Syntax Notes:

• Use the symbol "S" on numeric picture strings to indicate the presence of an operational sign.

• The picture string (pic-string) of a COMP, COMP-3 data item can contain only the symbols "9", "S", and "V" in addition to the parenthesized length.

• In order to interact with Ingres integer-valued objects, the picture string of a COMP, COMP-3, or DISPLAY item must describe a maximum of 10 digit positions with no scaling.

• Do not use a picture string for INDEX, COMP-1, or COMP-2 data items. While the preprocessor ignores such a picture string, the compiler does not allow it.

You can use any data items in the numeric category to assign and receive Ingres numeric data in database tables and forms. However, you can only use non-scaled COMP, COMP-3, and DISPLAY items of 10 digit positions or less to specify simple numeric objects, such as table field row numbers. Generally, try to use COMP data items with no scaling to interact with Ingres integer-valued objects, since the internal format of COMP data is compatible with Ingres integer data.

Similarly, COMP-1 and COMP-2 data items are compatible with Ingres floating-point data.

The following example contains numeric data categories:

##  01 QUAD-INTVAR        PIC S9(10) USAGE COMP.
##  01 LONG-INTVAR        PIC S9(9) USAGE COMP.
##  01 SHORT-INTVAR       PIC S9(4) USAGE COMP.
##  01 DISPLAY-VAR        PIC S9(10) USAGE DISPLAY.
##  01 SING-FLOATVAR     USAGE COMP-1.
##  01 DOUB-FLOATVAR     USAGE COMP-2.
##  01 PACKED-VAR         PIC S9(12)V9(4) USAGE COMP-3.

The Numeric Edited Data Category

The syntax for a declaration of numeric edited data is:

level-number data-name PIC [IS] pic-string [[USAGE [IS]] DISPLAY].

Syntax Notes:

• The pic-string can be any legal COBOL picture string for numeric edited data. The preprocessor notes only the type, scale, and size of the data item.

• In order to interact with Ingres integer-valued objects, the picture string must describe a maximum of 10 digit positions with no scaling.

While you can use numeric edited data items to assign data to, and receive data from, Ingres database tables and forms, be prepared for some loss of precision for numeric edited data items with scaling. The runtime interface communicates using integer (COMP) or packed (COMP-3) variables for UNIX or float (COMP-2) variables for VMS.

In moving from these variables into your program's edited data items, truncation can occur due to MOVE statement rules and the COBOL standard alignment rules. For more information on type conversion, see Data Type Conversion.

The following example illustrates the numeric edited data category:

## 01 DAILY-SALES PIC $$$,$$9DB USAGE DISPLAY.
## 01 GROWTH-PERCENT PIC ZZZ.9(3) USAGE DISPLAY.

The Alphabetic, Alphanumeric, and Alphanumeric Edited Categories

EQUEL/COBOL accepts data declarations in the alphabetic, alphanumeric, and alphanumeric edited categories. The syntax for declaring data items in those categories is:

level-number data-name PIC [IS] pic-string
[[USAGE [IS]] DISPLAY].

Syntax Note:

• The pic-string can be any legal COBOL picture string for the alphabetic, alphanumeric and alphanumeric edited classes. The preprocessor notes only the length of the data item and that the data item is in the alphanumeric class.

You can use alphabetic, alphanumeric, and alphanumeric edited data items with any Ingres object of character (c, char, text or varchar) type. You can also use them to replace names of objects such as forms, fields, tables and columns. However, when a value is transferred into a data item from a Ingres object it is copied directly into the variable storage area without regard to the COBOL special insertion rules. When data in the database is in a different format from the alphanumeric edited picture, you must provide an extra variable to receive the data. You can then MOVE the data into the alphanumeric edited variable. However, if data in the database is in the same format as the alphanumeric edited picture (which would be the case, for example, if you had inserted data using the same variable you are retrieving into), you can assign the data directly into the edited data item, without any need for the extra variable. For more information on type conversion, see Data Type Conversion.

The following example illustrates the syntax for these categories:

## 01 ENAME PIC X(20).
## 01 EMP-CODE PIC xx/99/00.

Declaring Records

EQUEL/COBOL accepts COBOL record and group declarations. The following syntax declares a record:

01 data-name.
record-item.
{record-item.}

where record-item is a group item:

level-number data-name.
record-item.
{record-item.}

or an elementary item:

level-number data-name elementary-item-description.

Syntax Notes:

• The record must have a level number of 01. Thereafter, the level numbers of record-items can be 02 through 49. The preprocessor applies the same rules as the COBOL compiler in using the level numbers to order the groups and elementary items in a record definition into a hierarchical structure.

• If you do not specify the elementary-item-description for a record item, the record item is assumed to be a group item.

• The elementary-item-description can consist of any of the attributes described for data declarations (see Data Item Declaration Syntax). The preprocessor does not confirm that the different clauses are acceptable for record items.

• The OCCURS clause, denoting a COBOL table, may appear on any record item.

• Only record-items that EQUEL statements reference need to be declared to EQUEL. The following example declares a COBOL record with several "filler" record-items that are not declared to EQUEL:

##   01   PERSON-REC.
##        02   NAME.
##             03    FIRST-NAME      PIC X(10).
               03    FILLER          PIC X.
##             03    LAST-NAME       PIC X(15).
##        02   STREET-ADDRESS.
##             03    ST-NUMBER       PIC 99999 DISPLAY.
               03    FILLER          PIC X.
##             03    STREET          PIC X(30).
##        02   TOWN-STATE.
##             03    TOWN            PIC X(20).
               03    FILLER          PIC X.
##             03    STATE           PIC X(3).
               03    FILLER          PIC X.
##             03    ZIP             PIC 99999 DISPLAY.

Indicator Data Items

An indicator data item is a 2-byte integer numeric data item. There are three possible ways to use these in an application:

• In a statement that retrieves data from Ingres, you can use an indicator data item to determine if its associated host variable was assigned a null value.

• In a statement that sets data to Ingres, you can use an indicator data item 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 data item as a check that the associated host variable is large enough to hold the full length of the returned character string.

An indicator declaration must have the following syntax:

level-number indicator-name PIC [IS] S9(p) [USAGE [IS]] COMP.

where p is less than or equal to 4.

The following is an example of an indicator declaration:

## 01 IND-VAR
PIC S9(2) USAGE COMP.

Compiling and Declaring External Compiled Forms - UNIX

You can precompile your forms in the Visual Forms Editor (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. Once the C file is created, you can use the following command to compile it into a linkable object module:

cc -c filename.c

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 use the following syntax to declare it to EQUEL:

01 formname [IS] EXTERNAL PIC S9(9) [USAGE [IS]] COMP-5.

Some platforms do not support the above syntax. If EXTERNAL data items cannot be referenced in your COBOL program, use an alternative procedure. For an alternate procedure, see Including External Compiled Forms in the RTS.

Syntax Notes:

• The formname is the actual name of the form. VIFRED gives this name to the global object. The formname is used to refer to the form in EQUEL/FORMS statements after the form has been made known to the FRS using the addform statement.

• The EXTERNAL clause causes the linker to associate the formname data item with the external formname symbol.

The following example shows a typical form declaration and illustrates the difference between using the form's global object definition and the form's name. (Currently, this example does not work on all Micro Focus platforms.)

DATA DIVISION.
WORKING-STORAGE SECTION.

##   01  empform IS EXTERNAL PIC S9(9) USAGE COMP-5.

*    Other data declarations.

PROCEDURE DIVISION.

*    Program initialization.

*    Making the form known to the FRS via the global
*    form object.
##     ADDFORM empform.

*    Displaying the form via the name of the form.
##     DISPLAY #empform

*    The program continues.

For information on using external compiled forms with your EQUEL program, see Including External Compiled Forms in the RTS.

Assembling and Declaring External Compiled Forms -VMS

You can pre-compile 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 the VAX-11 MACRO language. VIFRED prompts you for the name of the file with the MACRO description. After the MACRO file is created, you can use the VMS command to assemble it into a linkable object module:

macro filename

01 formid PIC S9(9) [USAGE [IS]] COMP VALUE [IS] EXTERNAL
formname.

Syntax Notes:

• The formid is a COBOL data item. It is used with the addform statement to declare the form to the Forms Runtime System (FRS).

• The formname is the actual name of the form. VIFRED gives this name to the global object. The formname is used to refer to the form in EQUEL/FORMS statements after the form is made known to the FRS with the addform statement.

• The EXTERNAL clause causes the VAX linker to associate the formid data item with the external formname symbol.

The example below shows a typical form declaration and illustrates the difference between using the form's object definition (the formid) and the form's name (the formname).

DATA DIVISION.
WORKING-STORAGE SECTION.

##  01  EMPFORM-ID PIC S9(9) USAGE COMP VALUE IS EXTERNAL
##      empform.

* Other data declarations.

PROCEDURE DIVISION.

Program initialization.

*     Making the form known to the FRS via the global form
*     object.
##      ADDFORM EMPFORM-ID.

*     Displaying the form via the name of the form.
##    DISPLAY empform

*  The program continues.

Concluding Examples

The following UNIX and VMS examples demonstrate some simple EQUEL declarations.

UNIX:

*Data item to hold database name.
##   01 DBNAME       PIC X(9) VALUE IS "Personnel".

* Scaled data
##   01 SALARY       PIC S9(8)V9(2) USAGE COMP.
##   01 MONEY        PIC S999V99 USAGE COMP-3.

* Array of numerics
##   01 NUMS.
##       02 NUM-ARR            PIC S99 OCCURS 10 TIMES.

* Record of a full name and a redefinition of its parts.
##   01 NAME-REC.
##       02 FULL-NAME          PIC X(20).
##       02 NAME-PARTS REDEFINES FULL-NAME.
##          03 FIRST-NAME     PIC X(8).
##          03 MIDDLE-INIT    PIC X(2).
##          03 LAST-NAME      PIC X(10).

* Record for fetching and displaying.
#  # 01 OUT-REC.
##       02 FILLER   PIC X(15) VALUE "Value fetched: ".
##       02 FROM-DB  PIC S9(4) USAGE DISPLAY.

* Miscellaneous attributes (some declaration clauses are
* ignored by preprocessor)
##   01 SALES-TOT         PIC S9(6)V99 SIGN IS TRAILING.

##   01 SYNC-REC.
##       02 NUM1          PIC S99 USAGE COMP SYNCHRONIZED.
##       02 FILLER        PIC X VALUE SPACES.
##       02 NUM2          PIC S99 USAGE COMP SYNCHRONIZED.

##   01 RIGHT-ALIGN       PIC X(30) JUSTIFIED RIGHT.

##   01 NUM-OUT  PIC S99V99 USAGE DISPLAY BLANK WHEN ZERO.

##      DECLARE.

VMS:

* Data item to hold database name.
##   01 DBNAME       PIC X(9) VALUE IS "Personnel".

* Scaled data
##   01 SALARY       USAGE COMP-1.
##   01 MONEY        PIC S999V99 USAGE COMP-3.

* Array of numerics
##   01 NUMS.
##       02 NUM-ARR         PIC S99 OCCURS 10 TIMES.

* Record of a full name and a redefinition of its parts.
##   01 NAME-REC.
##       02 FULL-NAME           PIC X(20).
##       02 NAME-PARTS REDEFINES FULL-NAME.
##           03 FIRST-NAME    PIC X(8).
##           03 MIDDLE-INIT   PIC X(2).
##           03 LAST-NAME     PIC X(10).

* Record for fetching and displaying.
##   01 OUT-REC.
##       02 FILLER    PIC X(15) VALUE "Value fetched: ".
##       02 FROM-DB   PIC S9(4) USAGE DISPLAY.

* Miscellaneous attributes (ignored by preprocessor)
##   01 SALES-TOT        PIC S9(6)V99 SIGN IS TRAILING.

##   01 SYNC-REC.
##       02 NUM1       PIC S99 USAGE COMP SYNCHRONIZED.
##       02 FILLER     PIC X VALUE SPACES.
##       02 NUM2       USAGE COMP-2 SYNCHRONIZED.

##   01 RIGHT-ALIGN    PIC X(30) JUSTIFIED RIGHT.

##   01 NUM-OUT  PIC S99V99 USAGE DISPLAY BLANK WHEN ZERO.
##      DECLARE.

Last modified date: 01/30/2023