Component Frameworks

Using Other Object Domains (32-bit)

Chapter 33: Persistence

Persistence is a Micro Focus feature which enables you to save the state of all objects in an application during or at the end of a run. This chapter shows you how you can use persistence in an application.

33.1 Overview

Any COBOL program which uses Object COBOL can save the state of all objects during or at the end of an application run. The PersistenceManager class is responsible for saving and restoring the state of objects. When a persistent application is restarted, objects are restored to the state recorded in the persistence file.

Persistence saves all the data declared in the class and instance object-storage sections of the class program. Data declared in working-storage or local-storage is not saved, as this is not considered to be part of the attributes of an object.

33.2 Using Persistence

The PersistenceManager saves object data between runs in a COBOL indexed file. COBOL indexed files consist of two physical files on the disk.

16-bit:
By default, the persistence files are named: trigger.dat and trigger.idx, where trigger is the name of the initial program for your application.

Windows NT and OS/2:
By default, on Object COBOL for 32-bit Windows and OS/2 systems, the persistence files are named: objstore.dat and objstore.idx.

UNIX:
By default, the persistence files are named objstore.dat and objstore.dat.idx.

The persistence files are written to the current directory by default. You can change the default name and location for the persistence files by setting environment variable OODIR. To change just the location, set OODIR to a path and terminate the path-name with a backslash "\" (Windows and OS/2) or a forward slash "/" (UNIX). For example:

Windows and OS/2 : 
set oodir=e:\data\

UNIX: 
OODIR=$HOME/data/
export OODIR

This leaves the persistence files with their default names, but writes them to directory e:\data (Windows and OS/2) or $HOME/data (UNIX). To change the filename, set OODIR to a filename:

Windows and OS/2: 
set oodir=mydata

The persistence files are written to mydata.dat and mydata.idx.

UNIX: 
OODIR=mydata
export OODIR

The persistence files are written to mydata.dat and mydata.dat.idx.

You can change both the path and the filename as well. For example:

Windows and OS/2: 
set oodir=e:\data\mydata

UNIX: 
OODIR=$HOME/mydata
export OODIR

The run-time system also uses environment variable OODIR to locate the persistence files at the start of a run. So when you restart an application, you must ensure that it is set to the same value as it had when the application shut down.

33.2.1 Saving Objects

To save objects during or at the end of an application run, use the statement:

    invoke PersistenceManager "saveEverything"

This saves all objects.

33.2.2 Restoring Objects

The run-time system automatically searches for a file with persistence data at the start of every run of any Object COBOL application. It looks in the location pointed to by environment variable OODIR.

If the run-time system finds a persistence file, it restores the object handles stored in the file. As objects are required by the application, they are restored along with their data.

The class initialization code for any classes restored from a persistence file is not executed; class objects in a persistent application are only initialized on their first run. When you write a persistent application, you will need to write a short program, which is not an Object COBOL class, as a trigger for your application.

The trigger program will not have any persistent data itself, as it is not a class, so it will need to send a message to a class in order to start the application running, or possibly to get an object handle to the object which starts the application running. When it sends the first message, the run-time system starts loading objects from the persistence file as they are required.

The trigger program can determine whether or not this is the first run of the program by sending the message "isFirstSession" to the PersistenceManager class. For example:

 invoke PersistenceManager "isFirstSession" 
                            returning sessionStatus

where sessionStatus is declared as pic 9 comp-x. The PersistenceManager returns 1 if this is the first time the application has been run - that is, there is no persistence file.

33.2.3 Persistence Backup Files

The PersistenceManager provides a function to backup persistence files. The code below creates a backup of the most recent persistence file.

 invoke PersistenceManager "backupPersistenceFile"

Windows and OS/2 :
This renames the current persistence files from:

trigger.dat
trigger.idx

to:

trigger.dtn
trigger.ixn

where trigger is the name of the persistence file and n is a number between 0 and 9. Backups are numbered from 0 to 9, and backup 0 is always the most recent backup.

UNIX:
This renames the current persistence files from:

trigger.dat
trigger.dat.idx

to:

trigger.dtn
trigger.dtn.idx

where trigger is the name of the persistence file and n is a number between 0 and 9. Backups are numbered from 0 to 9, and backup 0 is always the most recent backup.

You can also delete all persistence files. Send the following message:

 invoke PersistenceManager "eraseAllPersistenceBackupFiles"

33.2.4 Persistence Example - The Phonebook (Windows and OS/2)

Object COBOL for Windows and OS/2 includes an example of a persistent application, the Phonebook. This is an application which stores a set of names and 'phone numbers. When you suspend the application, it saves itself to a persistence file. When you restart the application, it restores all the names stored, and also the state of the interface, from the persistence file.

>>To browse the Phonebook classes

Set the current directory to \cobol\demo\oops on the drive where your Object COBOL system is installed (this assumes you accepted Setup defaults when you installed the system).
Enter the following command line:
```
browse phone.prj
```
This starts the Class Browser and loads the classes for the Phonebook application. The Phonebook is a GUI application.

The Phonebook application consists of the following classes:

PhoneApplication	Represents the application, and provides a link between the records stored in the PhoneBook, and the viewer classes used to display the information.
PhoneBook	Creates and initializes a PhoneBook object. The PhoneBook object manages a collection of records.
Record	Creates a record object for each entry in the Phonebook.
RecordViewer	Creates the Record Details (View) dialog boxes which enable you to see the details of a record.
RecordEditor	A subclass of RecordViewer. The objects created by this class enable you to change the contents of a record, as well as editing it.
PhoneWindow	Creates the Phonebook windows which display the contents of the PhoneBook.

There is also one procedural COBOL program:

PhoneTrigger

This is a trigger to start the application. It includes a test for whether this is the first run of the application or not; that is whether a persistence file already exists. If no persistence file exists, the trigger sends a message to initialize the application. If a persistence file does exist, then the application has been run before and will already be initialized, in which case the trigger only sends the message "run" to the EventManager to start the interface processing events.

>>To try the Phone application

Select Check all from the Class Browser COBOL menu.
The Class Browser puts all the Phone application files through the Checker.
Select PhoneTrigger in the class/program selector.
Select Run from the COBOL menu.
The Phone Book window appears. Assuming that it has not been run before, there will be no persistence file and no entries in the window.
Push the Add button.
This opens the Add Record dialog box.
Type in an entry and push the OK button.
The Phone Book window now displays the first record. The default Phone Book window shows you the Named List view.
Select Detailed List from the File menu to see the Detailed List view.
This opens a second Phone Book window, which shows all the details in the record. If you can't see the first Phone Book window, move the second window to one side slightly.

The Phone application supports multiple views of your data; you can have any number of Named and Detailed views open at a time. You can also open as many View Record, Add Record or Edit Record dialog boxes at a time as you like.

As soon as you change the data in a record using an Edit Record dialog box and push the OK button, all the other views of that data (in windows or in dialog boxes) are updated automatically. This type of multiple view is much easier to program using OO than with a procedural approach; each view is an object responsible for keeping itself up-to-date with the data.
Experiment with the Phone book for a while. Add some more records and try out the different views.
When you are ready, select Suspend from the File menu.
The Phonebook saves itself to a persistence file and shuts down.

You can now restart the Phonebook. The persistence file will not only restore the data, but also all the views as they were when you did the suspend.

>>To restart the Phonebook

Select PhoneTrigger in the class/program selector.
Select Run from the COBOL menu.
The Phone Book application is restored to its state immediately before shutdown.

32-bit:
Note: On 32-bit systems, rename, delete or move the objstore files before you run any different OO applications from the same directory. If you do not do this, the run-time system will find the persistence files and attempt to use them for the application you are starting. This will cause an unpredictable failure in the application.

33.3 Limitations of Persistence

This version of persistence has the following limitations:

The persistence file is only suitable for single-user applications.
If you make changes to the class or instance data of any of the objects in a persistent application, you must delete the persistence files before running the application again. The persistence data will no longer match the data used by the class and instance objects of your application, and your application will fail unpredictably at some point.
The persistence mechanism does not warn of any such mismatch.

Component Frameworks

Using Other Object Domains (32-bit)