Compaq COBOL Reference Manual

The SUBTRACT statement subtracts one, or the sum of two or more, numeric items from one or more items. It stores the difference in one or more items.

num
is a numeric literal or the identifier of an elementary numeric item.
rsult
is the identifier of an elementary numeric item. However, in Format 2, rsult can be an elementary numeric edited item. It is the resultant identifier.
stment
is an imperative statement executed when a size error condition has occurred.
stment2
is an imperative statement executed when no size error condition has occurred.
grp-1
is the identifier of a group item.
grp-2
is the identifier of a group item.

Syntax Rule

CORR is an abbreviation for CORRESPONDING.

In Format 1, the values of the operands before the word FROM are summed. This total is then subtracted from each rsult.
In Format 2, the values of the operands before the word FROM are summed. This total is subtracted from the num following the word FROM. The result replaces the current value of each rsult.
In Format 3, data items in grp-1 are subtracted from and stored in the corresponding data items in grp-2.

Examples

Each of the examples assume these data descriptions and initial values.

INITIAL VALUES

03 ITEMA PIC S99 VALUE -85. -85 03 ITEMB PIC 99 VALUE 2. 2 03 ITEMC VALUE "123". 05 ITEMD OCCURS 3 TIMES 1 2 3 PIC 9. 03 ITEME PIC S99 VALUE -95. -95

Without GIVING phrase: RESULTS

SUBTRACT 2 ITEMB FROM ITEMA. ITEMA = -89

SIZE ERROR clause:
(When the size error condition occurs and the SIZE ERROR clause is specified, the values of the affected resultant identifiers do not change.)

SUBTRACT 14 FROM ITEMA, ITEME ITEMA = -99 ON SIZE ERROR ITEME = -95 MOVE 0 TO ITEMB. ITEMB = 0

NOT ON SIZE ERROR clause:

SUBTRACT 14 FROM ITEMA ITEMA = -99 ON SIZE ERROR MOVE 9 TO ITEMB. NOT ON SIZE ERROR MOVE 1 TO ITEMB. ITEMB = 1

Multiple receiving fields:
(The operations proceed from left to right. Therefore, the subscript for ITEMB is evaluated after the subtraction changes its value.)
SUBTRACT 1 FROM ITEMB ITEMD (ITEMB). ITEMB = 1 ITEMD (1) = 0

GIVING phrase:

SUBTRACT ITEME ITEMD (ITEMB) FROM ITEMA ITEMB = 8 GIVING ITEMB.

END-SUBTRACT:
(The first SUBTRACT terminates with END-SUBTRACT. If the SIZE ERROR condition had not occurred, the second SUBTRACT statement would have executed anyway: the value of ITEMA would have been -86.)

SUBTRACT 10 ITEMB FROM ITEMD (ITEMB) ITEMD (2) = 2 ON SIZE ERROR ITEMA = 0 MOVE 0 TO ITEMA END-SUBTRACT. SUBTRACT 1 FROM ITEMA. ITEMA = -1

(The following example shows the usefulness of END-SUBTRACT inside an IF statement. Without it, there would be no way to code the DISPLAY statements.)

IF ITEMB < 3 AND > 1 SUBTRACT 1 FROM ITEMD(ITEMB) ON SIZE ERROR MOVE 0 TO ITEMA END-SUBTRACT DISPLAY 'yes' ELSE DISPLAY 'no'.

6.8.38 SUPPRESS

The SUPPRESS statement causes the Report Writer Control System (RWCS) to inhibit the presentation of a report group.

Syntax Rule

The SUPPRESS statement can appear only in a USE BEFORE REPORTING Declarative procedure.

The SUPPRESS statement inhibits only the presentation of a report-group-name (a 01-level Report Group Description entry).
Each time the presentation of a report group is to be inhibited, the program must execute a SUPPRESS statement.
The SUPPRESS statement directs the Report Writer Control System (RWCS) to inhibit the processing of these report group functions:
- The presentation of the print lines
- The processing of all LINE clauses
- The processing of the NEXT GROUP clause
- The adjustment of LINE-COUNTER
The SUPPRESS statement does not inhibit the processing of sum counters or control breaks.

Example

PROCEDURE DIVISION. DECLARATIVES. DET SECTION. USE BEFORE REPORTING DETAIL-LINE. DETA-1. IF SORTED-NAME = NAME ADD A TO B SUPPRESS PRINTING. IF NAME = SPACES SUPPRESS PRINTING. END DECLARATIVES. MAIN SECTION. . . .

6.8.39 TERMINATE

The TERMINATE statement causes the Report Writer Control System (RWCS) to complete the processing of the specified report.

report-name
names a report defined by a Report Description entry in the Report Section of the Data Division.

If the TERMINATE statement includes more than one report-name, the statement executes as if there were a separate TERMINATE statement for each report-name.
The program cannot execute a TERMINATE statement unless an INITIATE statement was executed before the TERMINATE statement for that report, and the program did not already execute a TERMINATE statement for that report.
If the program did not execute a GENERATE statement, the execution of a TERMINATE statement does not cause the RWCS to produce any of its report groups or perform any of the related processing.
The TERMINATE statement causes the RWCS to:
- Produce all CONTROL FOOTING report groups beginning with the minor CONTROL FOOTING report group.
- Produce the REPORT FOOTING report group.
The RWCS makes the prior set of control data item values available to these two report groups and to any associated USE procedure. This action simulates a control break at the most major level.
The RWCS automatically processes the PAGE HEADING and PAGE FOOTING report groups, if present, when it must advance the report to a new page to present a CONTROL HEADING, DETAIL, or CONTROL FOOTING report group.
The TERMINATE statement does not automatically close a report file; the program must close the file. The program must terminate the report before the CLOSE statement can close the report file.

Additional Reference

Section 6.8.42, USE statement.

6.8.40 UNLOCK

UNLOCK statement removes a record lock from the current record or from all locked records in the file. The X/Open standard UNLOCK statement always removes the record lock from all locked records in the file.

file-name
is the name of a sequential, relative, or indexed file described in the Data Division.

Syntax Rules

For Format 1, if the UNLOCK statement does not include the RECORD or the ALL RECORDS option, the singular RECORD option is the default. (However, see General Rule 3.)
For Format 2, the RECORD and RECORDS options have the same effect: to unlock all currently locked records. This behavior also is the default if neither option is specified.

The first access stream to lock a record owns the record lock for that record.
Only the owner of a record lock can unlock the record.
For Format 1, implicitly (by default) or explicitly specifying the RECORD option unlocks the current record. Therefore, you must specify ALL RECORDS explicitly to unlock all the record locks held on file-name.
The single exception to this rule for Format 1 is that for indexed files the RECORD option (implicitly or explicitly) is unsupported on Tru64 UNIX and Windows NT systems. The ALL RECORDS phrase is assumed. <>
For Format 2, whether you specify the RECORD option or the RECORDS option, the effect is the same: to unlock all record locks held on file-name by the current access stream.
If an access stream attempts to unlock a record (or records) in a file containing no record locks, the statement is considered successful and execution resumes at the statement following the UNLOCK statement.
Because both formats of the UNLOCK statement include the UNLOCK RECORD and UNLOCK forms, the compiler determines whether to interpret these forms of the statement as X/Open standard or Compaq standard as follows:
- If X/Open standard syntax (LOCK MODE or WITH (NO) LOCK) has been specified for file-name prior to the UNLOCK statement, the compiler interprets the statement according to the X/Open standard.
- If Compaq standard syntax (LOCK-HOLDING, ALLOWING, or REGARDLESS) has been specified for file-name prior to the UNLOCK statement, the compiler interprets the statement according to the Compaq standard.
- If no file-sharing syntax (LOCK-HOLDING, ALLOWING, REGARDLESS, LOCK MODE, or WITH [NO] LOCK) has been specified for file-name prior to the UNLOCK statement, then the compiler uses the /STANDARD=[NO]XOPEN qualifier on OpenVMS (or the Tru64 UNIX equivalent -std [no]xopen flag) to determine whether the START statement is interpreted as X/Open or Compaq standard: a setting of xopen selects the X/Open standard, whereas a setting of noxopen selects the Compaq standard.
Any subsequent I-O locking syntax for the same file connector in your program must be consistent: X/Open standard locking and Compaq standard locking (implicit or explicit) cannot be mixed for the same file connector.

Technical Notes

On Windows NT, the REGARDLESS and ALLOWING READERS phrases are not supported. <>

UNLOCK statement execution can result in these FILE STATUS data item values:

File Status	File Organization	Access Method	Meaning
00	All	All	Unlock is successful
93	All	All	No current record
94	All	All	File not open, or incompatible open mode
30	All	All	All other permanent errors

Compaq Standard Examples

LOCK-HOLDING phrase in APPLY Clause in Section 4.2.10, I-O-CONTROL paragraph in Chapter 4
LOCK MODE phrase in SELECT clause in File Control paragraph in Chapter 4
Technical Notes for Section 6.8.9, DELETE statement
Section 6.8.24, OPEN statement

These examples assume only one access stream for the image. The following examples refer to this partial program:

CONFIGURATION SECTION. FILE-CONTROL. SELECT MASTER-FILE ASSIGN TO "CLIENT.DAT" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS MASTER-KEY FILE STATUS IS FILE-STAT. I-O-CONTROL. * * This APPLY clause is required syntax for manual record locking * APPLY LOCK-HOLDING ON MASTER-FILE. DATA DIVISION. FD MASTER-FILE LABEL RECORDS STANDARD. 01 MASTER-RECORD. . . . PROCEDURE DIVISION. A100-BEGIN. * * The ALLOWING phrase enables file sharing * OPEN I-O MASTER-FILE ALLOWING ALL. . . . A900-END-OF-JOB.

Unlocking the record lock on the current record by taking the default RECORD option:

READ MASTER-FILE KEY IS MASTER-KEY ALLOWING NO OTHERS. REWRITE MASTER-RECORD ALLOWING NO OTHERS. UNLOCK MASTER-FILE.

Explicitly unlocking the record lock on the current record:

READ MASTER-FILE KEY IS MASTER-KEY ALLOWING NO OTHERS. . . . UNLOCK MASTER-FILE RECORD.

Unlocking all records in MASTER-FILE:

PERFORM A100-READ-MASTER UNTIL MASTER-KEY = ID-KEY OR MASTER-KEY > ID-KEY. . . . UNLOCK MASTER-FILE ALL RECORDS. . . . A100-READ-MASTER. READ MASTER-FILE ALLOWING NO OTHERS.

X/Open Standard Example

The following example shows the use of X/Open standard syntax:

SELECT employee-file ASSIGN TO "EMPFIL" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS employee-id LOCK MANUAL LOCK ON MULTIPLE RECORDS FILE STATUS IS emp-stat. . . . * The file is implicitly shareable via the SELECT specification. OPEN I-O employee-file. PERFORM UNTIL emp-stat = end-of-file READ employee-file NEXT RECORD WITH LOCK IF employee-job-code = peon-code PERFORM find-boss-record ENDIF . . . REWRITE employee-record * This will unlock this record and the boss's * record found earlier. UNLOCK employee-file RECORDS END-PERFORM. FIND-BOSS-RECORD. START employee-file KEY > employee-job-code. READ employee-file NEXT WITH LOCK.

6.8.41 UNSTRING

The UNSTRING statement separates contiguous data in a sending field and stores it in one or more receiving fields.

src-string
is the identifier of an alphanumeric class data item. It cannot be reference modified. Src-string is the sending field.
delim
is a nonnumeric literal or the identifier of an alphanumeric data item. It is the delimiter for the UNSTRING operation.
dest-string
is the identifier of an alphanumeric, alphabetic, or numeric DISPLAY data item. It is the receiving field for the data from src-string.
delim-dest
is the identifier of an alphanumeric data item. It is the receiving field for delimiters.
countr
is the identifier of an elementary numeric data item described as an integer. It contains the count of characters moved.
pointr
is the identifier of an elementary numeric data item described as an integer. It points to the current character position in src-string.
tally-ctr
is the identifier of an elementary numeric data item described as an integer. It counts the number of dest-string fields accessed during the UNSTRING operation.
stment
is an imperative statement executed for an on overflow condition.
stment2
is an imperative statement executed for a not on overflow condition.

Syntax Rules

Literals can be any figurative constant other than ALL literal.
pointr must be large enough to contain a value one greater than the size of src-string.
The DELIMITER IN and COUNT IN phrases can appear only if there is a DELIMITED BY phrase.
countr, pointr, dest-string, and tally-ctr cannot define the assumed decimal scaling position character P in their PICTURE clauses.

countr represents the number of characters in src-string isolated by the delimiters for the move to dest-string. The count does not include the delimiter characters.
When delim is a figurative constant, its length is one character.
When the ALL phrase is present:
- One occurrence, or two or more contiguous occurrences, of delim (whether or not they are figurative constants) is treated as only one occurrence.
- One occurrence of delim is moved to delim-dest when there is a DELIMITER IN phrase.
When any examination finds two contiguous delimiters, the current dest-string is filled with:
- Spaces, if its class is alphabetic or alphanumeric
- Zeros, if its class is numeric
delim can contain any characters in the computer character set.
Each delim is one delimiter. When delim contains more than one character, all its characters must be in src-string (in contiguous positions and the given order) to qualify as a delimiter.
When the DELIMITED BY phrase contains an OR phrase, an OR condition exists between all occurrences of delim. Each delim is compared to src-string. If a match occurs, the character in src-string is a single delimiter. No character in src-string can be part of more than one delimiter.
Each delim applies to src-string in the order it appears in the UNSTRING statement.
When execution of the UNSTRING statement begins, the current receiving field is the first dest-string.
If there is a POINTER phrase, the string of characters in src-string is examined, beginning with the position indicated by pointr. Otherwise, examination begins with the leftmost character position.
If there is a DELIMITED BY phrase, examination proceeds to the right until the UNSTRING statement detects delim. (See General Rule 6.)
If there is no DELIMITED BY phrase, the number of characters examined equals the size of the current dest-string. However, if the sign of dest-string is defined as occupying a separate character position, UNSTRING examines one less character than the size of dest-string. If dest-string is a variable-length data item, its current size determines the number of characters examined.
If the UNSTRING statement reaches the end of src-string before detecting the delimiting condition, examination ends with the last character examined.
The characters examined (excluding delim) are:
- Treated as an elementary alphanumeric data item
- Moved to the current dest-string according to the MOVE statement rules
When there is a DELIMITER IN phrase, the delimiter is:
- Treated as an elementary alphanumeric data item
- Moved to delim-dest according to the MOVE statement rules
If the delimiting condition is the end of src-string, delim-dest is space-filled.
The COUNT IN phrase causes the UNSTRING statement to:
- Count the number of characters examined (excluding the delimiter).
- Move the count to countr according to the elementary move rules.
When there is a DELIMITED BY phrase, UNSTRING continues examining characters immediately to the right of the delimiter. Otherwise, examination continues with the character immediately to the right of the last one transferred.
After data transfers to dest-string, the next dest-string becomes the current receiving field.
The process described in General Rules 12 to 18 repeats until either:
- There are no more characters in src-string.
- The last dest-string has been processed.
The UNSTRING statement does not initialize pointr or tally-ctr. The program must set their initial values before executing the UNSTRING statement.
The UNSTRING statement adds one to pointr for each character it examines in src-string. When UNSTRING execution ends, pointr contains a value equal to its beginning value plus the number of characters the statement examined in src-string.
At the end of an UNSTRING statement with the TALLYING phrase, tally-ctr contains a value equal to its beginning value plus the number of dest-string fields the statement accessed.
An overflow condition can arise from either of these conditions:
- When the UNSTRING statement begins, the value of pointr is less than one or greater than the number of characters in src-string.
- During UNSTRING execution, all dest-string fields have been processed, and there are unexamined src-string characters.
When an overflow condition occurs, if there is a NOT ON OVERFLOW phrase, this phrase is ignored and the UNSTRING operation ends. If there is an ON OVERFLOW phrase, stment executes. Otherwise, control passes to the end of the UNSTRING statement.
At the end of the UNSTRING operation, when an overflow condition does not exist, the ON OVERFLOW phrase is ignored and the UNSTRING operation ends if a NOT ON OVERFLOW phrase does not exist. If there is a NOT ON OVERFLOW phrase, stment2 executes. After stment2 executes, control is passed to the end of the UNSTRING statement.
If there is a DELIMITED BY phrase and the size of dest-string is zero characters, no characters are moved. However, delim-dest contains the matched delimiter and countr contains the character count.
If there is no DELIMITED BY phrase and the size of dest-string is zero characters, no characters are moved. The value of pointr does not change. UNSTRING continues with the next dest-string.
If the size of delim is zero characters, delim does not match any characters in src-string.