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.
OO COBOL also enables you to store COBOL intrinsic data 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 cannot 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 uses Micro Focus alternatives and extensions to the ISO 2002 OO COBOL syntax.
This tutorial consists of the following sessions:
In this session you will debug 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 OO COBOL class program, but procedural COBOL code which uses the Class Library collection objects.
For an explanation of the different types of collection, see the section Different Categories of Collection in the chapter Collection Frameworks.
To debug coll0.cbl
This is a set of strings the program stores in 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.
Data item i holds the length for the instances of CharacterArray which will be created as elements for the different types of collection.
A CharacterArray is an object for storing strings. The "withLengthValue" message creates a new instance of CharacterArray and initializes it with some data.
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.
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". (If you can't see the Output Window, click View > Debug Windows > Application Output.)
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.
These test the result of the returned value and tell you whether or not the bag contained an object with a matching value.
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.
The "occurrencesOf" message returns the number of elements a collection has that match the specified object in value.
This displays the information that this Bag has two occurrences of the specified string.
This code demonstrates how the Array class 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.
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.
This message always returns 1 or 0 for ValueSet instances.
This displays the result of the "occurrencesOf" message.
The statements below tag A016 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.
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.
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 Base Class Library.
Micro Focus OO COBOL provides a mechanism that enables you to send a message to an intrinsic data item, as though it were an object, using the Invoke ... As statement.
Before you can send messages to intrinsic data, you have to clone an intrinsic class to create a new class for the type and length of intrinsic data you are using. The Base 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.
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 debug coll1.cbl
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.
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.
This executes the entire perform loop to initialize the array.
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.
This completes this part of the tutorial on using intrinsic data. For more information see the chapter Intrinsic Data.
In this session you will debug some code that uses a dictionary to store account objects. The account objects are the ones that were introduced in the Inheritance Tutorial.
For more information about dictionaries, see the section Creating Dictionaries in the chapter Collection Frameworks.
In this section we introduce the Bank application. This provides a GUI front-end for creating and working on Account objects. The Bank application is used for the next few tutorials as it demonstrates many features of object-oriented programming with COBOL. In this part of the tutorial the Bank application is used to demonstrate use of a dictionary. Each account created is stored in the dictionary with the account number as its key. You are going to look at the code in the AccountManager class (accmgrd.cbl), which is responsible for storing and retrieving accounts using a Dictionary object.
To debug dictionary creation code:
You are next going to find the methods in the AccountManager class we want to step through, and set breakpoints on them.
After a pause, the Debugger stops inside the "initialize" method of AccountManager.This method creates an instance of Dictionary, with PIC X(8) intrinsic data as the key and objects as the data.
This sets an object reference data item to null. This will be used to set the data template to hold objects (this is the meaning of a null template).
This clones the CobolPicX class to create a template for strings eight bytes long. This is the key template.
You have now created an Association template for the key-data pairs to be stored in the dictionary.
This creates a dictionary which the AccountManager will use to store the account data.
The rest of this method creates another dictionary, and sets up an ExceptionHandler for the dictionary; exception handling is the subject of a later tutorial.
This is just a check that the method has been passed an object handle.
This stores the account in the dictionary using the account number as the key.
The Debugger stops inside AccountManager instance method "getAccount".
This retrieves the account from the dictionary, and puts the reference in anAccount.
The BankApplication also opens the Account Details dialog box, which shows you the information held in the account object.
You have now completed this session. Don't shut down Debugger as the next session carries on directly from this one.
This session shows how you can use an iterator to search through the dictionary used by the bank application. The instructions below assume that you are continuing directly from the end of the previous section.
For more information about iterator methods, see the section Iterator Methods in the chapter Collection Frameworks.
To see the use of iterators:
This function searches through the accounts looking for those with names that match.
The execution point switches to the first statement of the AccountManager "retrieve" method..
This creates a string object containing the name for which you are going to search.
This passes nameString as a parameter to the "new" message to create the Callback. Every time the method in the Callback ("searchAccounts") is invoked, it will get nameString passed to it ahead of any other parameters sent with the "invoke" message.
Execution jumps to the first statement of the AccountManager "searchAccounts" method. This has been passed the string object with the name we are looking for, and the first account in the collection.
if acName = srchName.
At this point, acName and srchName contain the name from the account and the name you are searching for. Both have been set to upper case to avoid case mismatches. If you double-click on acName, you will see that it contains "FRED".
The test fails.
This sets the level-88 item noMatch to true. When you exit the method, it will return a 0 to the code in the Dictionary "select" method which is performing the iteration.
Execution returns to the top of the "searchAccounts" method, as the collection invokes it with the next account.
The names match this time, as this is the account for Wilma. The method returns a value of 1 to the dictionary, so Wilma is added as an element to the collection of results being created.
When you step the Exit Method statement, execution returns to the statement below tag M052. The result of the "select" is a new Dictionary, which contains only the elements which were marked as true (a value of 1 was returned by the selection Callback).
The "select" and "reject" methods always return a collection of the same type as the original collection, in this case a Dictionary. This message copies the data part of the dictionary into an OrderedCollection. The other statements in this method "finalize" all the objects created by this method which are no longer needed.
The application opens a dialog box with all the matching accounts shown in a list box.
You have now completed this part of the tutorial.
This tutorial covered the following:
Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.