Examples

This chapter provides annotated examples of some of the source code clauses and statements explained in detail elswhere in this book and in yourLanguage Reference. For the complete syntax and general rules for any item included in this chapter, please see the appropriate reference manual entry.

The sample code extracts provided within this chapter are not intended to be complete COBOL programs but rather sufficient excerpts to illustrate specific coding tasks. A number of complete COBOL source programs are provided with your COBOL system in machine readable format. If you look in the on-disk document, Products Contents Checklist and search for the word "sample", you will see which sample programs are provided with your COBOL system.

Note: No boxes, bubbles or other dialect designations are included in this chapter. See relevant reference entries and your COBOL system documentation for information on what syntax and semantic differences may exist for the COBOL options used in this chapter.

The examples in this chapter are presented in alphabetic order according to the phrase, clause, or statement which they are primarily demonstrating. Of course, within most of these examples other COBOL syntax may also appear. These examples are not divided according to the division or module in which they appear.

6.1 CALL Prototypes

The following program demonstrates the use of CALL prototypes. Assume that you have defined the following CALL prototype:

If you had the following "real" source coded in the same source file as the previous CALL prototype:

Example 1

The preceding CALL statement would generate an error since the number of parameters is wrong.

Example 2

The preceding CALL statement would generate an error since the call-convention is wrong.

Example 3

The preceding CALL statement would generate an error since x1 should be passed by value.

Example 4

Example 5

The preceding CALL statement would generate an error since x4 has the wrong length.

Example 6

Example 7

Example 8

Example 9

Example 10

The preceding CALL statement would generate an error as there are too many parameters being passed.

6.1.1 Example of CALL Prototype Usage

If a COBOL application programmer wants to call a C function from within his COBOL application the following need to be done:

The use of COBOL TYPEDEFS and COBOL CALL prototypes may be used to automate the above process. This includes the automatic conversion of text strings into null terminated C strings. The following is an example of how all this may be done.

Suppose I have a C function that I want to call. Let us call it my_C_function. The following is a segment of C code that shows this function:

There is a header file that contains the C typedef definitions and also the C function prototype. It is as follows:

The first step is to convert the C typedefs and function prototypes into COBOL TYPEDEFS and COBOL CALL prototypes. This may be done using the h2cpy utility provided with Micro Focus COBOL.

The following is an example of the COBOL application that makes a call to the my_C_function function.

The following is the output that results when the specific example above is run:

6.2 Calling and Setting a Procedure-Pointer

6.3 Call Returning a Dynamically Allocated Data Area from a Subprogram

6.4 COPY (ANSI'68 or LANGLVL(1) Variation)

The COPY statement's behavior is slightly modified when the OLDCOPY Compiler directive is set. This modification changes it from acting as defined by the ANSI'74 and ANSI'85 standards to behaving as the old ANSI'68 standard defined. This modified behavior is also consistent with how OS/VS COBOL and DOS/VS COBOL behave when the LANGLVL(1) compiler option is used on an IBM mainframe.

When the OLDCOPY Compiler directive is set and a copy member is intended to include an entire 01 level data description, both the COPY statement and the copied description should be defined with an 01 level item. However, only the data name from the copying statement will be available to the rest of the COBOL program. For example:

6.5 COPY (Partial Word Replacement)

The COPY statement in an ANSI'85 conforming compiler can be used to modify parts of words in the copy member source. It should be carefully noted that this syntax only works when certain conventions (and special characters) are used. When using this technique, the programmer must set up their copy members with the modifiable sections pre-established. In fact, once this technique is used, the copy members will NOT compile cleanly when not replaced. For example:

6.6 CRT Status Clause of the SPECIAL-NAMES Paragraph

The CRT status clause of the SPECIAL-NAMES paragraph provides a data item composed as follows:

The following examples show how the CRT status-key should be coded and referenced.

6.7 IF Statement (Conditional Compilation)

The $IF statement can be used to "conditionally compile" portions of your source code. In the following example, if the program is compiled with the directives:

/MF /CONSTANT WHERE "PC"

then at compile time, the word "NO" will be displayed and the object code will include an EVALUATE rather than a GO TO statement. If the MF directive were not set, "Not MF dialect" would also be displayed.

$if WHERE = "PC"
     evaluate test-field
       when 5  perform test-a
     end-evaluate
$if OTHER-CONSTANT defined
$display Program compiled with other-constant set
$else
$display NO
$end
$else
     go to test-a test-b depending on test-field
$end
$if NOMF set
$display Not MF dialect
$end

6.8 INSPECT Statement (Tallying, Replacing, and Converting)

The INSPECT statement can be used to tally the number of occurrences of specific character strings, to replace characters by other characters, or to convert from one set of characters to another. Setting the conditons for these inspections can be quite complex. The following examples demonstrate some of the variations and uses of this verb.

In each of the following examples of the INSPECT statement, COUNT-n is assumed to be zero immediately prior to execution of the statement. The results shown for each example, except the last, are the result of executing the two successive INSPECT statements shown above them.

Example 1:

Example 2:

Example 3:

Example 4:

Example 5:

Initial Value of ITEM	COUNT-0	COUNT-1	COUNT-2	COUNT-3	COUNT-4	Final Value of ITEM
EFABDBCGABEFGG	3	1	1	0	5	TUXYXVWRXYZZPZ
BABABC	2	0	0	1	1	SXYXYZ
BBBC	0	1	0	2	0	SSVW

Intial Value of ITEM	COUNT-0	COUNT-1	Final Value of ITEM
BBB	3	0	ZZZ
ABA	3	0	ZZZ

Initial Value of ITEM	COUNT-0	COUNT-1	COUNT-2	Final Value of ITEM
BBEABDABABBCABEE	3	0	2	BBEXYZXYXYZCABVE
ADDDDC	0	0	4	AZZZZC
ADDDDA	0	0	5	AZZZZZ
CDDDDC	0	0	0	CDDDDC
BDBBBDB	0	3	0	BDWWWDB

Initial Value of Item	COUNT-0	Final Value of Item
ABABABABC	1	ABABXYABC

Initial Value of ITEM	Final Value of ITEM
AC"AEBDFBCD#AB"D	AC"XEYXFYZX#AB"D

6.9 NEXT Clause of CONSTANT-NAMES

The NEXT clause of the constant-name format of a VALUE clause always points to the offset at which the next byte of storage occurs after the previous data declaration. For example, given the following:

the value in next-offset will be the location of the second byte of x1 and not the starting location of x3.

This also can cause confusion with OCCURS clauses. For example, given the following:

offset-a will point to the offset at the start of the first occurrence of elem while offset-b will point to the starting location of the second occurrence of table element elem and not to the starting location of after-tabl. If you wanted to get the starting location of after-tabl, you should recode your source as follows:

6.10 SEARCH

There are two types of SEARCH statements.

The first type, a serial search, starts with an element determined by the setting of the associated index. To search the entire table, the index must be set to one.

The second type is a binary search. It ignores the initial setting of the associated index and searches the entire table.

In both formats

the programmer specifies the conditions that a table element must satisfy to terminate the search successfully
the WHEN phrase can be used to specify an action to be taken when an element is found that does satisfy these conditions
the AT END phrase can be used to specify an action to be taken if no element satisfies these conditions

The following data description is used in both examples of the SEARCH statement. The binary search requires that the KEY phrase be specified in the OCCURS clause, the serial search does not require this, but does allow it.

 working-storage section.
 01 states.
   03 state-abbr pic x(2) occurs 50 ascending key state-abbr indexed by i. 
 01 state-code pic x(2).

The two coding examples are equivalent. They illustrate the difference between the serial and the binary search. In both examples, the user enters a two-character state abbreviation and the SEARCH statement is used to determine whether the entered abbreviation matches any of the valid abbreviations listed in the table. If the abbreviation is invalid, another one must be entered. A CONTINUE statement is coded at the location where you would process a valid state abbreviation, if additional processing beyond the validation were desired.

Serial Search

 enter-state. 
     accept state-code
     set i to 1
     search state-abbr
      at end display "invalid state code, please reenter" 
         go to enter-state
      when state-code = state-abbr (i)
         continue
     end-search
     stop run.

Binary Search

 enter-state. 
     accept state-code
     search all state-abbr
      at end display "invalid state code, please reenter" 
             go to enter-state
      when state-code = state-abbr (i)
         continue
     end-search
     stop run.

The differences in these two examples of the SEARCH statement are

the keyword ALL in the second example indicates that a binary search is to be used
the example of the serial search initializes the associated index with a SET statement
before a binary search is executed, the elements of the table must be ordered according to the specified keys. (SORT Table Entries later in this chapter shows an example of this.)

6.11 SORT a File Using Input and Output Procedures

The SORT statement can be used to sort the records in a file. The following program takes the names of the input and output files from the command line. RELEASE and RETURN statements are used in the input and output procedures which input records, sort the records, and output a sorted file.

6.12 SORT Table Entries

This is a simple sort in which the table is sorted in ascending order using the key definitions in the OCCURS clause of data item Tabl to determine the sequence, that is Elem-Item2 would be the major key (ascending) and Elem-Item1 would be the secondary key (descending).

This is a simple sort in which the table is sorted in ascending order using each entire element of the table to determine the sequence.

This is a sort in which the table is sorted based on specified key data items. The major key would be Elem-Item2, even though it was not specified as a KEY in the OCCURS clause. The secondary key would be Elem-Item3. It would be treated as a DESCENDING key for this sort because the DESCENDING (which is transitive across KEY data items) specified in the SORT statement would take precedence over the ASCENDING specified in the OCCURS clause.

This sorts only the third instance of Tabl2, that is Tabl2(3). It uses the qualified data-item, Elem-Item1 of Group2 as its key. In normal Procedure Division references, Elem-Item1 of Group2 would require two levels of subscripting/indexing while in this reference it has none. (Similarly, Tabl2 normally requires one level of subscripting, but cannot be subscripted as data-name-2 in the SORT statement. Instead it uses the value of T1-Ind for determining which instance is to be sorted.)

6.13 Split Key

would cause the COBOL system to treat fullname as though it were an explicitly defined group item consisting of:

6.14 TYPEDEF – User Defined USAGE or Structure

which defines struct-1 and USHORT to be new usages that can be used as in the following: