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 | |
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 |
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 - Linux
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.
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.
## 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 - Linux
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 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 Linux.
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.
## 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].
[[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.
## 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.}
record-item.
{record-item.}
where record-item is a group item:
level-number data-name.
record-item.
{record-item.}
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.
## 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.
PIC S9(2) USAGE COMP.
Compiling and Declaring External Compiled Forms - Linux
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.
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.
Concluding Example
The following example demonstrates some simple EQUEL declarations.
Linux:
*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.
## 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.
Last modified date: 04/03/2024