Recovery
System

Subsystem
list

Top
level

The RECgroup Class

A recovery object of class RECgroup contains an ordered list of other recovery objects. Its recovery target is the sum of the recovery targets of the recovery objects it contains. Likewise, its base state is the sum of the base states of the recovery objects it contains. This means that when a RECgroup is invoked during one of the four recovery phases, it in turn invokes each recovery object contained in it, in order.

Order

It is important that the script writer be aware of not only the content of the group, but the order of its members. Some orderings of recovery objects can greatly increase the amount of time spent in the recovery system, and in a worst-case scenario, result in a deadlock situation.

Multiple Instances

A given recovery object can only appear once in a given RECgroup. In other words, given a recovery object R1, and two RECgroups G1 and G2, R1 can appear at most once in G1, and at most once in G2.

Declaration

winclass RECgroup : RECbase

Overridden Methods

`boolean`	`IsHappy`	`(RECphase ePhase, boolean logFirstFailure)`
`void`	`BeHappy`	`(RECphase ePhase)`
`list of RECwindowUid`	`VetoWindowClosure`	`(RECphase ePhase, list of RECwindowUid luWindowsToClose)`

New Methods

`boolean`	`MakeHappy`	`(RECphase ePhase, RECobject r)`
`void`	`InsertBefore`	`(RECobject r, RECobject insertBefore optional)`
`void`	`InsertAfter`	`(RECobject r, RECobject insertAfter optional)`
`void`	`Remove`	`(RECobject r)`
`void`	`Replace`	`(RECobject rOld, RECobject rNew)`

New Instance Variables

list of RECobject lrObjects;

RECgroup::IsHappy

Returns TRUE if and only if all of the contained recovery objects are happy. For more information, see RECbase.IsHappy.

RECgroup::BeHappy

Iterates over all of the contained recovery objects, calling their BeHappy methods. Keeps looping as long as there is any contained recovery object that isn't happy, or until nothing changes from one loop iteration to another. Returns when all the contained recovery objects are happy. Raises the exception X_REC_CANT_MAKE_ALL_HAPPY if it determines that one or more contained recovery objects aren't going to become happy. For more information, see RECbase.BeHappy.

RECgroup::VetoWindowClosure

Calls the VetoWindowClosure method of all the contained recovery objects. For more information, see RECbase.VetoWindowClosure.

RECgroup::MakeHappy

This method is called by RECgroup::BeHappy when one of the contained objects' BeHappy methods raises an exception. This method tries to alter the state of the application in such a way that the contained object's BeHappy method can succeed. The exception information can be obtained from the built-in 4Test routines ExceptNum and ExceptData.

If MakeHappy returns TRUE, RECgroup::BeHappy will call the contained object's BeHappy method again. If MakeHappy returns FALSE, RECgroup::BeHappy will assume that the contained object cannot be made happy, at least this time around.

RECgroup::MakeHappy itself always returns FALSE. It is intended to be overridden.

Declaration

boolean MakeHappy (RECphase ePhase, 
					RECobject rObj);

Inputs

ePhase: Identifies the recovery phase during which this method is called.
rObj: The recovery object whose BeHappy method raised an exception.

Outputs

Returns: TRUE if it did something to make rObj happy, in which case rObj.BeHappy will be called again.
FALSE if it can't do anything to make rObj happy.

RECgroup::InsertBefore

Inserts a new recovery object into the group, before a specified object that is already in the group, and calls the WelcomeToGroup method of the inserted object. Adding a new recovery object to the group does not affect the application until the group is invoked (i.e. during recovery). The recovery object must not be already contained in the group.

Declaration

void InsertBefore (RECobject rNew, RECobject rBefore optional);

Inputs

rNew: The new object to be inserted.
rBefore: The object before which the new object will be inserted. If this parameter is missing or NULL, the new object will be inserted at the beginning of the list.

Outputs

none

Example of Usage

window RECgroup g;   // initially empty
RECobject a, b, c, d;

g.InsertBefore(a);
// group now contains: { a }
g.InsertBefore(b, a);
// group now contains: { b a }
g.InsertBefore(c);
// group now contains: { c b a }
g.InsertBefore(d, b);
// group now contains: { c d b a }

RECgroup::InsertAfter

Inserts a new recovery object into the group, after a specified object that is already in the group, and calls the WelcomeToGroup method of the inserted object. Adding a new recovery object to the group does not affect the application until the group is invoked (i.e. during recovery). The recovery object must not be already contained in the group.

Declaration

void InsertAfter (RECobject rNew, RECobject rAfter optional);

Inputs

rNew: The new object to be inserted.
rAfter: The object after which the new object will be inserted. If this parameter is missing or NULL, the new object will be inserted at the end of the list.

Outputs

none

Example of Usage

window RECgroup g;   // initially empty
RECobject a, b, c, d;

g.InsertAfter(a);
// group now contains: { a }
g.InsertAfter(b, a);
// group now contains: { a b }
g.InsertAfter(c);
// group now contains: { a b c}
g.InsertAfter(d, b);
// group now contains: { a b d c }

RECgroup::Remove

Removes a recovery object from the list. Removing a recovery object from the group does not affect the application until the group is invoked (i.e. during recovery).

Declaration

void Remove (RECobject r);

Inputs

r: The new object to be removed.

Outputs

none

RECgroup::Replace

Replaces one recovery object with another, and calls the WelcomeToGroup method of the new object. This operation does not affect the application until the group is invoked (i.e. during recovery).

Declaration

void Replace (RECobject rOld, RECobject rNew);

Inputs

rOld: The recovery object that will be replaced by rNew.
rNew: The new recovery object that will replace rOld.

Outputs

none

RECgroup::lrObjects

You can use this instance variable in the static declaration of an object of class RECgroup to specify the initial set of recovery objects. It is only used the first time the recovery object is invoked (typically during ScriptEnter); changing it during script execution will have no effect, once the recovery object has been used at least once. The first time the RECgroup is used, it calls the WelcomeToGroup method of each object in this list.

Declaration

list of RECobject lrObjects;

Example of Usage

window RECgroup gbMyRecoveryGroup
{
    list of RECobject lrObjects = 
    {
        grPRJrecDefault,
        grTLrecDefault,
        grCMrecDefault,
        grCONrecDefault
    }
}

This page is maintained by (REMOVED).
Last updated 8 March 1999.