Compaq COBOL
Reference Manual

Examples

The examples assume these Data Division entries:

01 CUSTOMER-REC. 03 CUSTOMER-USPS-STATE PIC XX. 03 CUSTOMER-REGION PIC X. 03 CUSTOMER-NAME PIC X(15). 01 STATE-TAB. 03 FILLER PIC X(153) VALUE "AK3AL5AR5AZ4CA4CO4CT1DC1DE1FL5GA5HI3 - "IA2ID3IL2IN2KS2KY5LA5MA1MD1ME1MI2MN2 - "MO5MS5MT3NC5ND3NE2NH1NJ1NM4NV4NY1OH2 - "OK4OR3PA1RI1SC5SD3TN5TX4UT4VA5VT1WA3 - "WI2WV5WY4". 01 STATE-TABLE REDEFINES STATE-TAB. 03 STATES OCCURS 51 TIMES ASCENDING KEY IS STATE-USPS-CODE INDEXED BY STATE-INDEX. 05 STATE-USPS-CODE PIC XX. 05 STATE-REGION PIC X. 01 STATE-NUM PIC 99. 01 STATE-ERROR PIC 9. 01 NAME-TABLE VALUE SPACES. 03 NAME-ENTRY OCCURS 8 TIMES INDEXED BY NAME-INDEX. 05 LAST-NAME PIC X(15). 05 NAME-COUNT PIC 999.

1. Binary search:
   (The correctness of this statement's operation depends on the ascending order of key values in the source table.)

   INITIALIZE-SEARCH. MOVE "NH" TO CUSTOMER-USPS-STATE. SEARCH ALL STATES AT END MOVE 1 TO STATE-ERROR GO TO SEARCH-END WHEN STATE-USPS-CODE (STATE-INDEX) = CUSTOMER-USPS-STATE MOVE 0 TO STATE-ERROR MOVE STATE-REGION (STATE-INDEX) TO CUSTOMER-REGION. SEARCH-END. DISPLAY " ". DISPLAY "Customer State index number = " STATE-INDEX WITH CONVERSION " Region = " STATE-REGION (STATE-INDEX) " State Error Code = " STATE-ERROR.

   
   Following are the results of the binary search:

   Customer State index number = 31 Region = 1 State Error Code = 0

2. Serial search with WHEN phrase:

   INITIALIZE-SEARCH. MOVE "2" TO CUSTOMER-REGION. SEARCH-LOOP. SEARCH STATES AT END MOVE 1 TO STATE-ERROR GO TO SEARCH-END WHEN STATE-REGION (STATE-INDEX) = CUSTOMER-REGION MOVE 0 TO STATE-ERROR DISPLAY STATE-USPS-CODE (STATE-INDEX) " " STATE-INDEX WITH CONVERSION " " STATE-ERROR. SET STATE-INDEX UP BY 1. GO TO SEARCH-LOOP. SEARCH-END.

   
   The following lists the results of this serial search:

   IA 13 0 IL 15 0 IN 16 0 KS 17 0 MI 23 0 MN 24 0 NE 30 0 OH 36 0 WI 49 0

3. Serial search with two WHEN phrases:

   INITIALIZE-SEARCH. MOVE 1 TO CUSTOMER-REGION. MOVE "NH" TO CUSTOMER-USPS-STATE. DISPLAY "States in customer's region:". SEARCH-LOOP. SEARCH STATES AT END GO TO SEARCH-END WHEN STATE-USPS-CODE (STATE-INDEX) = CUSTOMER-USPS-STATE SET STATE-NUM TO STATE-INDEX WHEN STATE-REGION (STATE-INDEX) = CUSTOMER-REGION DISPLAY STATE-USPS-CODE (STATE-INDEX) " " WITH NO ADVANCING. SET STATE-INDEX UP BY 1. GO TO SEARCH-LOOP. SEARCH-END. DISPLAY " " DISPLAY "Customer state index number = " STATE-NUM.

   
   The following lists the results of the serial search with two WHEN phrases:

   States in customer's region: CT DC DE MA MD ME NJ NY PA RI VT Customer state index number = 31

4. Updating a table in a SEARCH statement:

   GET-NAME. DISPLAY "Enter name: " NO ADVANCING. ACCEPT CUSTOMER-NAME. SET NAME-INDEX TO 1. SEARCH NAME-ENTRY AT END DISPLAY " Table full" SET NAME-INDEX TO 1 PERFORM SHOW-TABLE 8 TIMES STOP RUN WHEN LAST-NAME (NAME-INDEX) = CUSTOMER-NAME ADD 1 TO NAME-COUNT (NAME-INDEX) WHEN LAST-NAME (NAME-INDEX) = SPACES MOVE CUSTOMER-NAME TO LAST-NAME (NAME-INDEX) MOVE 1 TO NAME-COUNT (NAME-INDEX). GO TO GET-NAME. SHOW-TABLE. DISPLAY LAST-NAME (NAME-INDEX) " " NAME-COUNT (NAME-INDEX). SET NAME-INDEX UP BY 1.

   
   The following lists the results of updating a table in a SEARCH statement:

   Enter name: CRONKITE
   Enter name: GEORGE
   Enter name: PHARES
   Enter name: CRONKITE
   Enter name: BELL
   Enter name: SMITH
   Enter name: FRANKLIN
   Enter name: HENRY
   Enter name: GEORGE
   Enter name: ROBBINS
   Enter name: BELL
   Enter name: FRANKLIN
   Enter name: SMITH
   Enter name: BELL
   Enter name: SMITH
   Table full
   CRONKITE 002
   GEORGE 002
   PHARES 001
   BELL 003
   SMITH 003
   FRANKLIN 002
   HENRY 001
   ROBBINS 001

Function

The SET statement sets values of indexes associated with table elements. It can also change the value of a conditional variable, change the status of an external switch, and store the address of a COBOL identifier reference at run time.

rsult

is an index-name, the identifier of an index data item, or an elementary numeric data item described as an integer.

val

is a positive integer, which can be signed. It can also be an index-name (or the identifier of an index data item) or an elementary numeric data item described as an integer.

indx

is an index-name.

increm

is an integer, which can be signed. It can also be the identifier of an elementary numeric data item described as an integer.

cond-name

is a condition-name that must be associated with a conditional variable.

switch-name

is the name of an external switch defined in the SPECIAL-NAMES paragraph.

pointer-id

is a data-name whose data description entry must contain the USAGE IS POINTER clause.

identifier

is a data item in the File, Working-Storage, Linkage, or Subschema Section.

status-code-id

is a word or longword integer data item represented by PIC S9(1) to S9(9) COMP or PIC 9(1) to 9(9) COMP.

Syntax Rule

No two occurrences of cond-name can refer to the same conditional variable.

General Rules

Formats 1 and 2

1. Index-names are associated with a table in the table's OCCURS clause INDEXED BY phrase.
2. If rsult is an index-name, its value after SET statement execution must correspond to an occurrence number of an element in the associated table.
3. If val is an index-name, its value before SET statement execution must correspond to an occurrence number of an element in the table associated with rsult.
4. The value of indx, both before and after SET statement execution, must correspond to an occurrence number of an element in the table associated with indx.

Format 1

5. The SET statement sets the value of rsult to refer to the table element whose occurrence number corresponds to the table element referred to by val. If val is an index data item, no conversion occurs.
6. If rsult is an index data item, val cannot be an integer. No conversion occurs when rsult is set to the value of val.
7. If rsult is not an index data item or an index-name, val can only be an index-name.
8. When there is more than one rsult, SET uses the original value of val in each operation. Subscript or index evaluation for rsult occurs immediately before its value changes.
9. Table 6-18 shows the validity of operand combinations. An asterisk (*) means that no conversion occurs during the SET operation.

Table 6-18 Validity of Operand Combinations in Format 1 SET Statements

Sending Item	Receiving Item
	Integer Data Item	Index	Index Data Item
Integer Literal	Invalid/Rule 7	Valid/Rule 5	Invalid/Rule 6
Integer Data Item	Invalid/Rule 7	Valid/Rule 5	Invalid/Rule 6
Index	Valid/Rule 7	Valid/Rule 5	Valid/Rule 6*
Index Data Item	Invalid/Rule 7	Valid/Rule 5*	Valid/Rule 6*

Format 2

10. The SET statement increments (UP) or decrements (DOWN) indx by a value that corresponds to the number of occurrences increm represents.
11. When there is more than one indx, SET uses the original value of increm in each operation.

Format 3

12. SET moves the literal in the VALUE clause for cond-name to its associated conditional variable. The transfer occurs according to the rules for elementary moves. If the VALUE clause contains more than one literal, the first is moved.

Format 4

13. SET changes the status of each switch-name in the statement.
14. The ON phrase changes the status of switch-name to on.
15. The OFF phrase changes the status of switch-name to off.
16. The SET statement changes the switch status only for the image in which it executes. When the image terminates, the status of each external switch is the same as when the image began.

Format 5

17. The address of identifier is evaluated and stored in pointer-id.

Format 6

18. Specifying the SUCCESS option sets status-code-id to the SUCCESS state (the low-bit of status-code-id is set to 1).
19. Specifying the FAILURE option sets status-code-id to the FAILURE state (the low-bit of status-code-id is set to 0).

Additional References

• Section 4.1.3, SPECIAL-NAMES paragraph in Chapter 4
• Section 6.5.4, Switch-Status Condition
• Section 6.5.6, Success/Failure Condition
• Section 6.8.22, MOVE statement
• Section 6.8.25, PERFORM statement
• Section 6.8.31, SEARCH statement

Examples

The examples assume these Environment and Data Division entries:

SPECIAL-NAMES. SWITCH 1 UPDATE-RUN ON STATUS IS DO-UPDATE SWITCH 3 REPORT-RUN ON STATUS IS DO-REPORT OFF STATUS IS SKIP-REPORT SWITCH 4 IS NEW-YEAR ON STATUS IS BEGIN-YEAR OFF IS CONTINUE-YEAR. DATA DIVISION. WORKING-STORAGE SECTION. 01 YEAR-LEVEL PIC 99. 88 FRESHMAN VALUE 1. 88 SOPHOMORE VALUE 2. 88 JUNIOR VALUE 3. 88 SENIOR VALUE 4. 88 FIRST-MASTERS VALUE 5. 88 MASTERS VALUE 5,6. 88 FIRST-DOCTORAL VALUE 7. 88 DOCTORAL VALUE 7,8. 88 NON-DEGREE-UNDERGRAD VALUE 9. 88 NON-DEGREE-GRAD VALUE 10. 88 UNDERGRAD VALUE 9, 1 THROUGH 4. 88 GRAD VALUE 10, 5 THROUGH 8. 01 COURSES-AVAILABLE. 02 OCCURS 100 TIMES INDEXED BY COURSE-INDEX. 03 COURSE-NAME PIC X(10). 03 COURSE-INSTRUCTOR PIC X(20). 03 COURSE-LOCATION PIC X(10). 03 COURSE-CODE PIC 9(5). 01 POINTER-VAL USAGE IS POINTER. 01 THREE-DIMENSIONAL-TABLE. 02 X OCCURS 5 TIMES INDEXED BY I. 03 Y OCCURS 7 TIMES INDEXED BY J. 04 Z PIC X(17) OCCURS 3 TIMES. 01 K PIC S9(9) COMP. 01 RETURN-STATUS PIC S9(9) COMP. 01 DECREMENT-VALUE PIC 9 VALUE 1.

1. Format 1---Initializing COURSE-INDEX.

   SET COURSE-INDEX TO 5.

2. Format 2---Adding to or subtracting from the index-name COURSE-INDEX.

   SET COURSE-INDEX UP BY 1. SET COURSE-INDEX DOWN BY DECREMENT-VALUE.

3. Format 3---Initializing a conditional variable:
   YEAR-LEVEL

   SET SOPHOMORE TO TRUE 02 SET MASTERS TO TRUE 05 SET GRAD TO TRUE 10 SET NON-DEGREE-GRAD TO TRUE 10

4. Format 4---Setting external switches. The truth value shows the result of the IF statements:

   
   TRUTH VALUE

   SET UPDATE-RUN TO ON. SET REPORT-RUN TO OFF. SET NEW-YEAR TO ON. IF DO-UPDATE ... true IF DO-REPORT ... false IF CONTINUE-YEAR... false SET REPORT-RUN TO ON. IF DO-REPORT ... true IF SKIP-REPORT ... false

5. Format 5---Setting POINTER-VAR to the address of the subscripted table item named Z(I,J,K).

   SET POINTER-VAR TO REFERENCE OF Z(I,J,K).

6. Format 6---On OpenVMS, initializing RETURN-STATUS to FAILURE before calling subprogram SUBPROGA and a Run-Time Library Procedure, then checking for SUCCESS from each.

   . . . SET RETURN-STATUS TO FAILURE. CALL "SUBPROGA" GIVING RETURN-STATUS. IF RETURN-STATUS IS SUCCESS THEN GO TO A0200-PARA ELSE DISPLAY "SUBPROGA failed" STOP RUN. A0200-PARA. SET RETURN-STATUS TO FAILURE. CALL "SCR$SET_CURSOR" USING BY VALUE 4, 22 GIVING RETURN-STATUS. IF RETURN-STATUS IS SUCCESS THEN DISPLAY "UPDATE ROUTINE COMPLETED" ELSE DISPLAY "Cursor positioning failed" STOP RUN. . . . IDENTIFICATION DIVISION. PROGRAM-ID. SUBPROGA. . . . 01 PROGRAM-STATUS PIC S9(9) COMP. . . . PROCEDURE DIVISION GIVING PROGRAM-STATUS. A000-BEGIN. . . . IF ... SET PROGRAM-STATUS TO SUCCESS ELSE SET PROGRAM-STATUS TO FAILURE. EXIT PROGRAM. <>

Function

The SORT statement (Format 1) creates a sort file by executing input procedures or transferring records from an input file. It sorts the records in the sort file using one or more keys that you specify. Finally, it returns each record from the sort file, in sorted order, to output procedures or an output file.

SORT (Format 2) orders the elements in a table. This is especially useful for tables used with SEARCH ALL. The table elements are sorted based on the keys as specified in the OCCURS for the table unless you override them by specifying keys in the SORT statement. If no key is specified, the table elements are the SORT keys.

sortfile

is a file-name described in a sort-merge file description (SD) entry in the Data Division.

sortkey

(Format 1) is the data-name of a data item in a record associated with sortfile.
(Format 2) is the data-name of a data item in the table-name table.

first-proc

is the section-name or paragraph-name of the first (or only) section or paragraph of the INPUT or OUTPUT procedure range.

end-proc

is the section-name or paragraph-name of the last section or paragraph of the INPUT or OUTPUT procedure range.

infile

is the file-name of the input file. It must be described in a file description (FD) entry in the Data Division.

outfile

is the file-name of the output file. It must be described in a file description (FD) entry in the Data Division.

table-name

is a table described with OCCURS in the Data Division.

alpha

is an alphabet-name defined in the SPECIAL-NAMES paragraph of the Environment Division.

Syntax Rules

All Formats

1. You can use SORT statements anywhere in the Procedure Division except in:
   • Declaratives (Format 1)
   • SORT or MERGE statement input or output procedures
2. sortkey can be qualified.
3. sortkey cannot be in a group item that contains variable occurrence data items.
4. The sortkey description cannot contain an OCCURS clause or be subordinate to a data description entry that does.

Format 1

5. If sortfile contains variable-length records, infile records must not be smaller than the smallest in sortfile nor larger than the largest.
6. If sortfile contains fixed-length records, infile records must not be larger than the largest record described for sortfile.
7. If outfile contains variable-length records, sortfile records must not be smaller than the smallest in outfile nor larger than the largest.
8. If outfile contains fixed-length records, sortfile records must not be larger than the largest record described for outfile.
9. sortfile can have more than one record description. However, sortkey needs to be described in only one of the record descriptions. The character positions referenced by sortkey are used as the key for all the file's records.
10. The words THRU and THROUGH are equivalent.
11. If outfile is an indexed file, the first sortkey must be in the ASCENDING phrase. It must specify the same character positions in its record as the prime record key for outfile.

Format 2

12. table-name may be qualified and must have an OCCURS clause in its data description entry. If table-name is subject to more than one level of OCCURS clauses, subscripts must be specified for all levels with OCCURS INDEXED BY.
13. table-name is a key data-name, subject to the following rules:
    • The data item identified by a key data-name must be the same as, or subordinate to, the data item referenced by table-name.
    • Key data items may be qualified.
    • The data items identified by key data-names must not be variable-length data items.
    • If the data item identified by a key data-name is subordinate to table-name, it must not be described with an OCCURS clause, and it must not be subordinate to an entry that is also subordinate to table-name and contains an OCCURS clause.
14. The KEY phrase may be omitted only if the description of the table referenced by table-name contains a KEY phrase.

General Rules

All Formats

1. The first sortkey you specify is the major key, the next sortkey you specify is the next most significant key, and so forth. The significance of sortkey data items is not affected by how you divide them into KEY phrases. Only first-to-last order determines significance.
2. The ASCENDING phrase causes the sorted sequence to be from the lowest to highest sortkey value.
3. The DESCENDING phrase causes the sorted sequence to be from the highest to the lowest sortkey value.
4. Sort sequence follows the rules for relation condition comparisons.
5. The DUPLICATES phrase affects the return order of records or table elements whose corresponding sortkey values are equal.
   • When there is a USING phrase, return order is the same as the order of appearance of infile names in the SORT statement.
   • When there is an INPUT PROCEDURE, return order is the same as the order in which the records were released.
   • When table elements are returned, the order is the relative order of the contents of these table elements before sorting.
6. If there is no DUPLICATES phrase, the return order for records or table elements with equal corresponding sortkey values is unpredictable.
7. The SORT statement determines the comparison collating sequence for nonnumeric sortkey items when it begins execution. If there is a COLLATING SEQUENCE phrase in the SORT statement, SORT uses that sequence. Otherwise, it uses the program collating sequence described in the OBJECT-COMPUTER paragraph.

Format 1

8. If sortfile contains fixed-length records, any shorter infile records are space-filled on the right, following the last character. Space-filling occurs before the infile record is released to sortfile.
9. The INPUT PROCEDURE range consists of one or more sections or paragraphs that:
   • Appear contiguously in the source program
   • Do not form a part of an OUTPUT PROCEDURE range
10. The statements in the INPUT PROCEDURE range must include at least one RELEASE statement to transfer records to sortfile.
11. The INPUT PROCEDURE range can consist of any procedure needed to select, modify, or copy the next record made available by the RELEASE statement to the file referenced by sortfile.
12. The range of the INPUT PROCEDURE additionally includes all statements executed as a result of a CALL, EXIT, GO TO, or PERFORM statement. The range of the INPUT PROCEDURE also includes all statements in the Declaratives Section that can be executed if control is transferred from statements in the range of the INPUT PROCEDURE.
13. The INPUT PROCEDURE range must not contain MERGE, RETURN, or SORT statements.
14. If there is an INPUT PROCEDURE phrase, control transfers to the first statement in its range before the SORT statement sequences the sortfile records. When control passes the last statement in the INPUT PROCEDURE range, the records released to sortfile are sorted.
15. During execution of the INPUT or OUTPUT procedures, or any USE AFTER EXCEPTION procedure implicitly invoked during the SORT statement, no outside statement can manipulate the files or record areas associated with infile or outfile.
16. If there is a USING phrase, the SORT statement transfers all records in infile to sortfile. This transfer is an implied SORT statement input procedure. When the SORT statement executes, infile must not be open.
17. For each infile, the SORT statement:
    • Initiates file processing as if the program had executed an OPEN statement with the INPUT phrase.
    • Gets the logical records and releases them to the sort operation. SORT obtains each record as if the program had executed a READ statement with the NEXT and AT END phrases.
    • Terminates file processing as if the program had executed a CLOSE statement with no optional phrases. The SORT statement ends file processing before it executes any output procedure.
    
    These implicit OPEN, READ, and CLOSE operations cause associated USE procedures to execute when an exception condition occurs.
18. OUTPUT PROCEDURE consists of one or more sections or paragraphs that:
    • Appear contiguously in the source program
    • Do not form part of an INPUT PROCEDURE range
19. When the SORT statement begins the OUTPUT PROCEDURE phrase, it is ready to select the next record in sorted order. The statements in the OUTPUT PROCEDURE range must include at least one RETURN statement to make records available for processing.
20. When the MERGE statement enters the OUTPUT PROCEDURE range, it is ready to select the next record in merged order. Statements in the OUTPUT PROCEDURE range must execute at least one RETURN statement to make records available for processing.
21. The OUTPUT PROCEDURE can consist of any procedure needed to select, modify, or copy the next record made available by the RETURN statement in sorted order from the file referenced by sortfile.
22. The range of the OUTPUT PROCEDURE additionally includes all statements executed as a result of a CALL, EXIT, GO TO, or PERFORM statement. The range of the OUTPUT PROCEDURE also includes all statements in the Declarative USE procedures that can be executed if control is transferred from statements in the range of the OUTPUT PROCEDURE.
23. The OUTPUT PROCEDURE range must not include MERGE, RELEASE, or SORT statements.
24. If there is an OUTPUT PROCEDURE phrase, control passes to the first statement in its range after the SORT statement sequences the records in sortfile. When control passes the last statement in the OUTPUT PROCEDURE range, the SORT statement ends. Control then transfers to the next executable statement after the SORT statement.
25. If there is a GIVING phrase, the SORT statement writes all sorted records to each outfile. This transfer is an implied SORT output procedure. When the SORT statement executes, outfile must not be open.
26. The SORT statement initiates outfile processing as if the program had executed an OPEN statement with the OUTPUT phrase. The SORT statement does not initiate outfile processing until after INPUT PROCEDURE execution.
27. The SORT statement obtains the sorted logical records and writes them to each outfile. SORT writes each record as if the program had executed a WRITE statement with no optional phrases.
    For relative files, the value of the relative key data item is 1 for the first returned record, 2 for the second, and so on. When the SORT statement ends, the value of the relative key data item indicates the number of outfile records.
28. The SORT statement terminates outfile processing as if the program had executed a CLOSE statement with no optional phrases.
29. These implicit OPEN, WRITE, and CLOSE operations can cause associated USE procedures to execute if they are present. If a USE procedure is present, processing terminates after the USE procedure has completed execution. If a USE procedure is not present, processing terminates as if the program had executed a CLOSE statement with no optional phrases.
30. If outfile contains fixed-length records, any shorter sortfile records are space-filled on the right, after the last character. Space-filling occurs before the sortfile record is released to outfile.
31. If the SORT statement is in a fixed segment, its input and output procedures must be completely in either:
    • Fixed segments
    • One independent segment
32. If the SORT statement is in an independent segment, its input and output procedures must be completely in either:
    • Fixed segments
    • The same independent segment as the SORT statement itself