Variable Usage
COBOL variables (that is, data items) declared to EQUEL can substitute for most elements of EQUEL statements that are not keywords. Of course, the variable and its data type must make sense in the context of the element. The generic uses of host language variables in EQUEL statements are described the QUEL Reference Guide. The following discussion covers only the usage issues particular to COBOL language variable types.
The following retrieve statement uses the variables "NAMEVAR" and "NUMVAR" to receive data, and the variable "IDNO" as an expression in the where clause:
## RETRIEVE (NAMEVAR = employee.empname,
## NUMVAR = employee.empnum) WHERE
## employee.empnum = IDNO
To distinguish the minus sign used as a subtraction operator in an EQUEL statement from the hyphen used as a character in a data item name, you must delimit the minus sign by blanks. For example, the statement:
## APPEND TO employee (ename="Jones", eno=ENO-2)
indicates that the data item "ENO-2" is to be appended to column "eno". To append a value two less than the value in the data item "ENO" you must instead use the following statement:
## APPEND TO employee (ename="Jones", eno=ENO - 2)
Note the spaces surrounding the minus sign.
Elementary Data Items
The following syntax refers to a simple scalar-valued data item (numeric, alphanumeric, or alphabetic):
simplename
The following program fragment demonstrates a typical error handling paragraph. The data items "BUFFER" and "SECONDS" are scalar-valued variables.
DATA DIVISION.
WORKING-STORAGE SECTION.
## 01 SECONDS PIC S9(4) USAGE COMP.
## 01 BUFFER PIC X(100).
## DECLARE.
* Program code
ERROR-HANDLE.
## MESSAGE BUFFER.
## SLEEP SECONDS.
* More error code.
COBOL Tables
The following syntax refers to a COBOL array or table:
tablename(subscript{,subscript})
Syntax Notes:
• You must subscript the tablename because only elementary data items are legal EQUEL values.
• When you declare a COBOL table, the preprocessor notes from the OCCURS clause that it is a table and not some other data item. When you later reference the table, the preprocessor confirms that a subscript is present but does not check the legality of the subscript inside the parentheses. Consequently, you must ensure that the subscript is legal and that the correct number of subscripts are used.
In the following example, the variable "SUB1" is used as a subscript and does not need to be declared to EQUEL declaration section, because the preprocessor ignores it.
DATA DIVISION.
WORKING-STORAGE SECTION.
## 01 FORMNAMES.
## 02 FORM-TABLE PIC X(8) OCCURS 3 TIMES.
## 01 SUB1 PIC S9(4) USAGE COMP VALUE ZEROES.
## DECLARE.
PROCEDURE DIVISION.
BEGIN.
* Program code
PERFORM VARYING SUB1 FROM 1 BY 1
UNTIL SUB1 > 3
## FORMINIT FORM-TABLE(SUB1).
END-PERFORM.
* More program code.
Record Data Items
You cannot use a record data item (also referred to as a structure variable) as a single entity in an EQUEL statement. Only elementary data items can communicate with Ingres objects and data.
EQUEL and COBOL use the same syntax to refer to an elementary record item:
elementary-item-name IN | OF{ groupname IN | OF} recordname
Syntax Notes:
• The item in the above reference must be a scalar value (numeric, alphanumeric, or alphabetic). You can use any combination of tables and records, but the last referenced item must be a scalar value. Thus, the following references are all legal:
* Element of a record
SAL IN EMPLOYEE
SAL OF EMPLOYEE
* Element of a record as an item of a table
NAME IN PERSON(3)
* Deeply nested element
ELEMENTARY-ITEM OF GROUP3 OF GROUP2 OF REC
• The qualification of an elementary item in a record can be elliptical; that is, you do not need to specify all the names in the hierarchy in order to reference the item. You must not, however, use an ambiguous reference that does not clearly qualify an item. For example, assume the following declaration:
## 01 PERSON.
## 02 NAME PIC X(30).
## 02 AGE PIC S9(4) USAGE COMP.
## 02 ADDR PIC X(50).
If you reference the variable "NAME", the preprocessor assumes the elementary item "NAME IN PERSON" is being referred to. However, if there also was the declaration:
## 01 CHILD.
## 02 NAME PIC X(30).
## 02 PARENT PIC X(30).
then the reference to "NAME" is ambiguous, because it can refer to either "NAME IN PERSON" or "NAME IN CHILD."
• Subscripts, if present, must qualify the data item declared with the OCCURS clause.
The following example uses the record "EMPREC" that contains the elementary data items "ENO", "ENAME," AGE," "JOB," "SALARY," and "DEPT". Assume "EMPREC" was declared to EQUEL in the file "employee.dcl".
DATA DIVISION.
WORKING-STORAGE SECTION.
* See above for description.
## EXEC SQL INCLUDE "employee.dcl".
## DECLARE.
PROCEDURE DIVISION.
* Program Code
## PUTFORM empform
## (eno = ENO IN EMPREC, ename = ENAME IN EMPREC,
## age = AGE IN EMPREC, job = JOB IN EMPREC,
## sal = SAL IN EMPREC, dept = DEPT IN EMPREC)
Note that you can write the putform statement without the "EMPREC" qualifications, assuming there were no ambiguous references to the item names:
## PUTFORM empform
## (eno = ENO, ename = ENAME, age = AGE,
## job = JOB, sal = SAL, dept = DEPT)
Using Indicator Data Items
The syntax for referring to an indicator data item is the same as for an elementary data item, except that an indicator variable is always associated with another COBOL data item:
data_item:indicator_item
Syntax Note:
• The indicator data item must be a 2-byte integer numeric elementary data item. For example:
## 01 IND-1 PIC S9(4) USAGE COMP.
## 01 IND-TABLE.
## 02 IND-2 PIC S9(4) USAGE COMP OCCURS 5 TIMES.
## 01 NUMVAR PIC S9(9) USAGE COMP.
## 01 EMPNAMES.
## 02 ENAME PIC X(30) OCCURS 5 TIMES.
## 01 SUB1 PIC S9(4) USAGE COMP VALUE ZEROES.
## APPEND TO employee (empnum=NUMVAR:IND-1)
## RETRIEVE (ENAME(SUB1): IND-2(SUB1)=
## employee.empname)
## {
program code
ADD 1 TO SUB1
## }