Component Frameworks | Using Other Object Domains (32-bit) |
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.
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.
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.
To save objects during or at the end of an application run, use the statement:
invoke PersistenceManager "saveEverything"
This saves all 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.
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"
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
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
The Class Browser puts all the Phone application files through the Checker.
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.
This opens the Add Record dialog box.
The Phone Book window now displays the first record. The default Phone Book window shows you the Named 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.
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
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.
This version of persistence has the following limitations:
Copyright © 1999 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
Component Frameworks | Using Other Object Domains (32-bit) |