PreviousInheritance Tutorial Exception Handling TutorialNext

Chapter 7: Collections, Intrinsics and Dictionaries Tutorial

This tutorial is about using the collection classes. Collections are very useful in object-oriented programming. They are used to store groups of objects. You usually store objects of the same type in any particular collection, although you can also store objects of different types in a collection.

Object COBOL also enables you to store COBOL intrinsic data, which is not represented by objects, in collections. This is done by a mechanism which enables you to treat an item of intrinsic data, for example a PIC X(20), as though it were an object. You can't mix intrinsic data and objects inside a single collection, or mix different types of intrinsic data.

Finally, this tutorial covers dictionaries, which are another type of collection.

This tutorial consists of the following sessions:

Time to complete: 25 minutes.

7.1 Different Categories of Collections

The different types of collection in the Class Library can all be categorized by the following properties:

The different collection classes available are listed below, with their properties.

Bag Non-indexed, automatically growable, duplicates allowed
Array Indexed, manually growable, duplicates allowed
CharacterArray Indexed, manually growable, duplicates allowed
OrderedCollection Indexed by insertion order, automatically growable, duplicates allowed
SortedCollection Indexed by sort order, automatically growable, duplicates allowed
ValueSet Non-indexed, automatically growable, duplicate values disallowed
IdentitySet Non-indexed, automatically growable, duplicate object handles disallowed
Dictionary Indexed by key, automatically growable, duplicate key values disallowed
IdentityDictionary Indexed by key, automatically growable, duplicate key object handles disallowed

ValueSet and IdentitySet only differ in the way they determine duplicate elements. ValueSets compare the values of elements and disallow duplicate values; IdentitySets compare object references, and disallow storing the same object more than once.

Dictionary and IdentityDictionary are special types of collection which are dealt with in a later section of this tutorial. They determine duplicate keys in the same way that ValueSet and IdentitySet determine duplicate elements.

Next you will look at a simple COBOL program, coll0.cbl which illustrates some of the differences and similarities between the main types of collection. The program is not an Object COBOL class program, but procedural COBOL code which uses the Class Library collection objects.

To animate coll0.cbl

  1. Use Infomgr to locate the demonstration programs and transfer them to working directory.

  2. Compile coll0.cbl ready for animation. Enter the following command line:

    cob -a coll0.cbl

  3. Start animating coll0. Enter the following command line:

    anim coll0

  4. Scroll through the Working-Storage Section until you see the declaration for fruitData.

    This is a set of strings the program stores in different types of collection.

  5. Step through the statements from A001 to A005 to create instances of the different types of collection.

    You need to specify an initial size for all types of collection. In the case of an Array, you can't exceed the initial capacity of the collection unless you send it the "grow" message. Other types of collection will grow in size if you add more elements than initially specified.

    However, growing collections can be an expensive operation at run-time, so you should still always try to pick an initial size which will reduce the number of times a collection needs to grow.

  6. Step through the statements below tag A006 (move 20 to i).

    Data item i holds the length for the instances of CharacterArray which will be created as elements for the different types of collection.

  7. Step the statement below tag A007 (invoke CharacterArray "withLengthValue"...).

    A CharacterArray is an object for storing strings. The "withLengthValue" message creates a new instance of CharacterArray and initializes it with some data.

  8. Step the statements below tag A008 (invoke aBag "add"...) until the end-perform statement.

    With all the different collection types, except Array, you use the "add" message to add new elements. With the Array, which does not grow automatically, you use "atPut" which stores the element at the specified index position.

    Although OrderedCollection is indexed, you can't use "atPut" until you have added elements to the collection. For example, once you have used "add" to add the first five elements, you can use "atPut" and an index between one and five to replace any of those elements. You can't do an "atPut" with an index greater than five until you have added more elements.

    You can't ever use "atPut" to put an element in a SortedCollection. A SortedCollection uses the value of each element to determine its position in the collection.

  9. Push the Prfm Exit keys.

    This completes execution of the perform loop without you needing to step through each statement in turn.

  10. Step the statements up to tag A011 (display " ").

    This retrieves the object reference to the fourth element in the Array instance. Sending the "display" message to the CharacterArray displays it on the screen. Its contents should be the word "banana". Push the F2=View key to see the console contents, and any other key to return to the Animator display.

  11. Step the next statement (invoke aBag "includes"...).

    Because a Bag is not indexed, you can't retrieve elements from it directly. Instead, you can query it to find out whether it has one or more occurrences of an object with a given value.

    The "includes" message returns 1 if a Bag contains an object with a matching value and 0 if it doesn't. You can also examine the contents of unindexed collections (Bags and ValueSets) by using the iterator methods. These are covered later in this tutorial.

  12. Step the statements up until tag A012 (display " ").

    These test the result of the returned value and tell you whether or not the bag contained an object with a matching value.

  13. Step the statement below tag A012 (invoke aBag "add"...).

    This adds the string to the Bag again. A Bag stores objects with duplicate values by recording the number of occurrences of each object with a different value.

  14. Step the statement below tag A013 (invoke aBag "occurrencesOf"...).

    The "occurrencesOf" message returns the number of elements a collection has which match the specified object in value.

  15. Step the statements up until tag A014 (display " ").

    This displays the information that this Bag has two occurrences of the specified string.

  16. Step the statements between tag A014 (invoke anArray "occurrencesOf"...) and A015 (display " ").

    This code demonstrates how the Array also responds to the "occurrencesOf" message. You can use "occurrencesOf" and "includes" on indexed collections as well as instances of Bag and ValueSet. This tells you whether or not the element exists, but not its position.

  17. Step the first statement below tag A015 (invoke aValueSet "add"...).

    Instances of ValueSet do not maintain duplicate elements. The ValueSet already contains an element with value "banana", so it will not be added a second time.

  18. Step the next statement (invoke aValueSet "occurrencesOf"...).

    This message always returns 1 or 0 for ValueSet instances.

  19. Step the other statements to tag A016 (display " ").

    This displays the result of the "occurrencesOf" message.

  20. Push the Zoom key to execute the rest of the code in the program.

    The statements below tag A016 (display "Collection contents") display every string in the OrderedCollection and SortedCollection in indexed order. The elements in the OrderedCollection appear in the order in which they were added. The elements in the SortedCollection appear sorted into ascending alphabetical order. Ascending order is the default for a SortedCollection.

  21. Push the Esc key to exit Animator.

At the end of this section, you may have some questions to ask:

Program coll0.cbl stores instances of CharacterArray in the collections it creates. An instance of a CharacterArray is a simple object, with an obvious single value (the string you store in it). But if you stored Account objects, like the ones used in the Inheritance Tutorial in a collection, how would you determine the value? Would it be the name, the balance or the account number?

The answer is that the collection objects provide a framework within which objects stored as elements must work. When a collection needs to know whether two objects are equal, it sends one object the "equal" message, passing it the other as a parameter. It is then up to the object to interrogate the other element and decide whether they are equal or not.

The default sort method for the SortedCollection works in a similar way. The SortedCollection sends one element the "lessThanOrEqual" method and a second element as a parameter. The receiving element can then compare itself to the second element and return a result.

If you are writing your own objects to store in collections, you may need to implement these methods yourself, unless you are subclassing from a class like CharacterArray, which implements them for you. There is also a default "equal" method in Base which compares the object handles of two objects. This implementation of "equal" will only find two elements equal if they are actually the same object.

For full information on the methods you might need to implement to use the Collection classes, see the chapter Collection Frameworks .

7.2 Using Intrinsics

In the previous session, you looked at a program which stored objects in different types of collection. There may be occasions when you want to store intrinsic COBOL data, like numbers, in collections. You can do this by using the intrinsic classes of the Class Library.

Object COBOL provides a mechanism which enables you to send a message to an intrinsic data item, as though it were an object.

To send a message to an intrinsic data item

  1. Clone an intrinsic class to create a new class for the type and length of intrinsic data you are using.

    The class library includes classes for three different types of intrinsic data (PIC X, PIC X COMP-X, PIC X COMP-5). These classes are templates which handle data of fixed length. When you clone the class, you specify the actual size of data you want to handle.

  2. Send messages to intrinsic data items using the INVOKE ... AS statement.

The example below sends the "hash" message to a numeric data item:

00001 working-storage section.
00002 01  aValue          pic x(2) comp-5.
00003 01  cloneX2Class    object reference. 
00004 01  aLength         pic x(4) comp-5.
00005 procedure division.
00006     move 2 to aLength
00007     invoke COBOLCOMP5 "newClass" using aLength
00008                            returning cloneX2Class
00009     invoke aValue as cloneX2Class "hash"
00010                         returning aHashValue

This is what the code above is doing:

Lines 1-4 Declaring data.
Lines 6-8 Cloning the COBOLCOMP5 to create a new class for comp-5 data items two bytes long.
Line 9 Sending a message to the data in data item aValue.

The statement uses the data item as an instance of the cloned class. You can think of an intrinsic object as a static object which has memory allocated to it at compile time. Static objects do not have object handles, unlike the dynamic objects created by the OO RTS at run-time. Intrinsic data objects are the only examples of static objects in Object COBOL.

We will now look at a short sample program, coll1.cbl, which uses the intrinsic classes to store a set of integers in an array.

To animate coll1.cbl

  1. Use Infomgr to locate the demonstration programs and transfer them to working directory.

  2. Compile coll1.cbl ready for animation. Enter the following command line:

    cob -a coll1.cbl

  3. Start animating coll1. Enter the following command line:

    anim coll1

  4. Step the two statements below tag A001 (move 4 to i).

    The "newClass" message creates a clone of the CobolComp5 class, initialized in this case for data four bytes in length. The object returned is a new class object, and not an instance of CobolComp5.

  5. Step the two statements below tag A002 (move 10 to i).

    This creates an instance of Array with space for ten elements. This time the message to create the Array instance is "ofValues" (in the example in the previous section it was "ofReferences").

    When a collection is created with the "ofValues" message, it stores intrinsic data instead of object handles. The cloned class, PicX4Comp5, is used as a template so that the Array knows how much space to allocate for each element.

    You can't mix objects and intrinsics inside a single collection. Once you create a collection you can only store the type of data for which it is initialized. If you want to mix many different kinds of data in a collection, you should create the collection using "ofReferences", and use different types of objects to represent the different types of data. There is no restriction on mixing different kinds of object inside a collection of references.

  6. Step the first statement below tag A003 (move 10 to element).

  7. Push the Prfm Step keys while the execution point is on the next statement (perform varying from 1 ...).

    This executes the entire perform loop to initialize the array.

  8. Step the statements below tag A004.

    This retrieves the fourth element from the array (which has a value of 7) and displays it. Because a data item is returned, we can show it using the display verb; when we got back objects in the previous example we had to send them the "display" message to show them.

  9. Press the Esc key to exit Animator.

This completes this part of the tutorial on using intrinsic data. For more information, see the chapter Intrinsic Data.

7.3 Associations and Dictionaries

Dictionaries are a special sort of indexed collection, which store key-data pairs (known as associations). In a dictionary, the key is used as the index when you store or retrieve the data. Dictionaries do not allow you to store duplicate keys.

Like the other collection types, you can store either objects or intrinsic data in a dictionary. In a dictionary though, either the key or the data part can be an intrinsic or an object. This gives you four possible combinations for intrinsic or object storage:

When you create a dictionary you have to give it a template so that it knows how the key and data portions are to be stored. The template is either the Association class, or a clone of the Association class.

The Association class is another clonable class, like the classes for intrinsic data classes, used for creating templates for data storage. An Association template actually consists of two templates; one for the key and one for the data. To create any type of dictionary you need to create an Association template.

To create an Association template

  1. If the key is to be intrinsic data, clone an intrinsic class to create a template for the type and length of intrinsic data of your key.

  2. If the data is to be intrinsic data, clone an intrinsic class to create a template for the type and length of intrinsic data of your data.

  3. Clone the Association class. Send it the "newClass" message, with templates for the key and data part of your association as parameters. If either of these is an object rather than intrinsic data, use an object reference set to null as the template.

    If both the key and data entries in the dictionary are to be objects you can use the Association class itself as a template; you don't need to create a clone.

Having created a template for your dictionary object, there are two methods you can use to create a dictionary itself; "ofValues" or "ofAssociations". A dictionary "ofValues" stores each element as a key data pair. A dictionary "ofAssociations" stores each element as an instance of the Association template you used to create the dictionary.

A dictionary "ofAssociations" in effect stores three items for every entry in the dictionary:

A dictionary "ofValues" stores the key and data directly without wrapping them inside an association object. When would you use a dictionary "ofAssociations" and when would you use a dictionary "ofValues"?

A dictionary "ofValues" is more efficient at run-time in terms of speed and memory if you simply want to store data items against key items. However, if your application uses associations elsewhere to manage key/data pairs, a dictionary "ofAssociations" is a better choice as the actual dictionary only stores the object handles to the associations, and you don't have to extract the key and value from the association before putting it in the dictionary.

The sample code below creates an association template and then uses it to create a dictionary "ofValues":

00001  working-storage section.
00002  01  aKeyTemplate      object reference.
00003  01  aDataTemplate     object reference. 
00004  01  anAssocTemplate   object reference.
00005  01  aDictionary       object reference. 
00006  01  aLength           pic x(4) comp-5.
00007  procedure division.
00008      move 3 to aLength
00009      invoke CobolCompX "newClass" using aLength
00010                               returning aKeyTemplate
00011      move 20 to aLength
00012      invoke CobolPicX "newClass" using aLength 
00013                             returning aDataTemplate 
00014      invoke Association "newClass using aKeyTemplate
00015                                         aDataTemplate
00016                               returning anAssocTemplate
00017      invoke Dictionary "ofValues" using anAssocTemplate
00018                               returning aDictionary 
Lines 1-6 Declares storage for the templates.
Lines 8-9 Creates a template for a PIC X(3) COMP-X numeric key.
Lines 11-12 Creates a template for a PIC X(20) data portion.
Line 14 Creates an association template.
Line 17 Creates a dictionary of values.

In the next part of this section we will animate through some code which uses a dictionary to store account objects. The account objects are the ones which were introduced in the Inheritance Tutorial

Each account object is stored in the dictionary against the customer name. We are going to use a simple program, coll2.cbl to demonstrate the use of the dictionary.

To animate coll2.cbl

  1. Use Infomgr to locate the demonstration programs and transfer them to working directory.

  2. Compile coll2.cbl ready for animation. Enter the following command line:

    cob -a coll2.cbl

  3. Start animating coll2. Enter the following command line:

    anim coll2

    Animator starts with the statement below tag A040 highlighted ready for execution.

  4. Step the two statements below tag A040 (move length of...).

    The dictionary we want to create uses the customer name as the key, and account objects as values. This code clones the intrinsic class CobolPicX to create a class for representing strings the same length as a customer name.

  5. Step the two statements below tag A050 (set wsNull to null).

    This code clones the Association class, to create a template for the dictionary. The key portion represents strings the same length as wsCustomer, the data portion is set to null and represents an object handle.

  6. Step the statements below tag A060 (invoke Dictionary "ofValues"...).

    This creates the new dictionary. It is initialized to store 10 elements, but grows automatically if more elements than this are added.

  7. Perform Step (press the Prfm Step keys) the statements below tag A070 (move spaces to wsCustomer).

    This creates a check account. Using Perform Step saves animating through all the "openAccount" code.

  8. Step the statement below tag A080 (invoke wsDictionary "atPut"...).

    The "atPut" message stores the account object at the key in wsCustomer.

  9. Perform Step the statements below tag A090 (move "Mike" to wsCustomer).

    This creates two more accounts, and stores them in the dictionary.

  10. Step the statements below tag A100 (move spaces to wsCustomer).

    The "at" message retrieves Bob's account from the dictionary.

  11. Perform Step the statement below tag A110 (invoke wsAccount "printStatement").

    The "printStatement" message displays the account details on the console. Press F2=view to switch the display from Animator to see what is on the console. Press any key to return to the Animator view.

    Don't shut down Animator; the next session carries on directly from this one.

This completes this section; in the next section you will use the already running application to look at the iterator methods for collections.

7.4 Iterator Methods

The collection classes all provide iterator methods which enable you to examine all the elements of a collection. There are four iterator methods, and they are supported by all types of collection:

This section shows how coll2.cbl uses the iterator methods to carry out operations on all accounts. The instructions below assume that you are continuing directly from the end of the previous section, and have not stopped animating coll2.cbl.

To see the use of iterators:

  1. Step the statement below tag A120 (invoke EntryCallback "new"...).

    Iterator methods pass elements in the collection to a piece of code. An EntryCallback is an object which contains an entry-point name; in effect it is a piece of code wrapped up inside an object. The class library also includes a Callback class, which contains an object handle and a message name; in effect wrapping a method up inside an object.

  2. Step the statement below tag A130 (invoke wsDictionary "do"...).

    The callback is passed to the "do" method inside dictionary. The "do" method uses the callback to call the entry-point "printAll" for each object in the dictionary. Execution switches to the the statement below tag A160.

  3. Perform step the statements below tag A160 (invoke lnkAccount "printStatement").

    Execution jumps straight back to the top of entry-point, below tag A160. The "do" method in the dictionary has passed its next account object to the entry-point. The entry-point is called once for every single account in the dictionary. All collections respond to the "do" message.

  4. Press the Zoom key to finish running the application.

    The iterator prints statements for the remaining accounts in the dictionary. You can see how the combination of collection iterator methods, and polymorphic methods is a powerful programming technique.

This completes the tutorial.

7.5 Summary

This tutorial covered the following:

Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.

PreviousInheritance Tutorial Exception Handling TutorialNext