HP OpenVMS Systems Documentation

HP COBOL
User Manual

You can also use data names to specify subscripts. To use a data name as a subscript, define it with COMP, COMP-1, COMP-2, COMP-3, or DISPLAY usage and with a numeric integer value. If the data name is signed, the sign must be positive at the time the data name is used as a subscript.

A data name that is a subscript can also be subscripted; for example, A(B(C)). Note that for efficiency your subscripts should be S9(5) to S9(9) COMP.

The sample subscripts and data names used in Table 4-2 refer to the table defined in Example 4-16.

The same rules apply for specifying indexes as for subscripts, except that the index must be named in the INDEXED BY phrase of the OCCURS clause.

You cannot access index items as normal data items; that is, you cannot use them, redefine them, or write them to a file. However, the SET statement can change their values, and relation tests can examine their values. The index integer you specify in the SET statement must be in the range of one to the integer value in the OCCURS clause. The sample MOVE statement shown in Example 4-17 moves the contents of the third element of A-GROUP to I-FIELD.

Table Description:

      01 A-TABLE.
         03 A-GROUP OCCURS 5 TIMES
            INDEXED BY IND-NAME.
            05   ITEMC   PIC X  VALUE "C".
            05   ITEMD   PIC X  VALUE "D".
      01 I-FIELD     PIC X(5).

Procedural Instructions:

      SET IND-NAME TO 3.
      MOVE A-GROUP(IND-NAME) TO I-FIELD.

To perform relative indexing when referring to a table element, you follow the index name with a plus or minus sign and an integer literal. Although it is easy to use, relative indexing generates additional overhead each time a table element is referenced in this way. The run-time overhead for relative indexing of variable-length tables is significantly greater than that required for fixed-length tables. If any of the range checks reveals an out-of-range index value, program execution terminates, and an error message is issued. You can use the -check flag (on Tru64 UNIX systems) or the /CHECK qualifier (on OpenVMS systems) to check the range when you compile the program.

On Tru64 UNIX, see Chapter 1 or the cobol man page for more information about the -check flag. <>

On OpenVMS, invoke the online help facility for HP COBOL at the OpenVMS system prompt for more information about the /CHECK qualifier. <>

The following sample MOVE statement moves the fourth repetition of A-GROUP to I-FIELD:

SET IND-NAME TO 1.
MOVE A-GROUP(IND-NAME + 3) TO I-FIELD.

Often a program requires that the value of an index be stored outside of that item. HP COBOL provides the index data item to fulfill this requirement.

Index data items are stored as longword COMP items and must be declared with a USAGE IS INDEX phrase in the item description. Index data items can be explicitly modified only with the SET statement.

4.3.7 Assigning Index Values Using the SET Statement

You can use the SET statement to assign values to indexes associated with tables to reference particular table elements. The following sections discuss the two relevant SET statement formats. (All six SET statement formats are shown in the HP COBOL Reference Manual.)

4.3.7.1 Assigning an Integer Index Value with a SET Statement

When you use the SET statement, the index is set to the value you specify. The most straightforward use of the SET statement is to set an index name to an integer literal value. This example assigns a value of 5 to IND-5:

SET IND-5 TO 5.

You can also set an index name to an integer data item. For example:

SET INDEX-A TO COUNT-1.

More than one index can be set with a single SET statement. For example:

SET TAB1-IND TAB2-IND TO 15.

Table indexes specified in INDEXED BY phrases can be displayed by using the WITH CONVERSION option with the DISPLAY statement. Also, you can display, move, and manipulate the value of the table index with an index data item. You do this by setting an index data item to the present value of an index. You can, for example, set an index data item and then display its value as shown in the following example:

SET INDEX-ITEM TO TAB-IND.
         .
         .
         .
DISPLAY INDEX-ITEM WITH CONVERSION.

You can use the SET statement with the UP BY/DOWN BY clause to arithmetically alter the value of a index. A numeric literal is added to (UP BY) or subtracted from (DOWN BY) a table index. For example:

SET TABLE-INDEX UP BY 12.

SET TABLE-INDEX DOWN BY 5.

The SEARCH statement is used to search a table for an element that satisfies a known condition. The statement provides for sequential and binary searches, which are described in the following sections.

4.3.8.1 Implementing a Sequential Search

The SEARCH statement allows you to perform a sequential search of a table. The OCCURS clause of the table description entry must contain the INDEXED BY phrase. If more than one index is specified in the INDEXED BY phrase, the first index is the controlling index for the table search unless you specify otherwise in the SEARCH statement.

The search begins at the current index setting and progresses through the table, checking each element against the conditional expression. The index is incremented by 1 as each element is checked. If the conditional expression is true, the associated imperative statement executes; otherwise, program control passes to the next procedural sentence. This terminates the search, and the index points to the current table element that satisfied the conditional expression.

If no table element is found that satisfies the conditional expression, program control passes to the AT END exit path; otherwise, program control passes to the next procedural sentence.

You can use the optional VARYING phrase of the SEARCH statement by specifying any of the following:

• VARYING index name associated with table search
• VARYING index data item or integer data item
• VARYING index name not associated with table search

Regardless of which method you use, the index specified in the INDEXED BY phrase of the table being searched is incremented. This controlling index, when compared against the allowable number of occurrences in the table, dictates the permissible search range. When the search terminates, either successfully or unsuccessfully, the index remains at its current setting. At this point, you can reference the data in the table element pointed to by the index, unless the AT END condition is true. If the AT END condition is true, and if the -check flag (on Tru64 UNIX systems) or the /CHECK qualifier (on OpenVMS systems) has been specified, the compiler issues a run-time error message indicating that the subscript is out of range.

When you vary an index associated with the table being searched, the index name can be any index you specify in the INDEXED BY phrase. It becomes the controlling index for the search and is the only index incremented. Example 4-18 and Example 4-20 show how to vary an index other than the first index.

When you vary an index data item or an integer data item, either the index data item or the integer data item is incremented. The first index name you specify in the INDEXED BY phrase of the table being searched becomes the controlling index and is also incremented. The index data item or the integer data item you vary does not function as an index; it merely allows you to maintain an additional pointer to elements within a table. Example 4-18 and Example 4-21 show how to vary an index data item or an integer data item.