When to release a Sequence File

[esmeralda]

(ref. I'm trying to build my own operator interface in C++)
When I get a reference to a SequenceFile object I have to release this object when I'm done.
But If I AddRef the SequenceFile object before releasing it a first call to the ReleaseSequenceFile method should not actually release it, should it, It should do the actual release when I call the function for the second time.
This is my understanding from the teststand activex help reference, however when trying this, it does not work...the sequence file gets released the first time ?
can anybody help me out, maybe I'm doing something wrong here.

here's my code:

tsSequenceFile1.AttachDispatch( m_Engine.GetSequenceFile(strSequenceFile, TS_GetSeqFile_OperatorInterfaceFlags), TRUE);


tsSequenceFile1.m_lpDispatch->AddRef();
tsSequenceFile2.AttachDispatch(tsSequenceFile1.m_lpDispatch, FALSE);

now releasing it twice...

m_Engine.ReleaseSequenceFile(tsSequenceFile1.m_lpDispatch);

// release sequence file
tsSequenceFile1.ReleaseDispatch();

m_Engine.ReleaseSequenceFile(tsSequenceFile2.m_lpDispatch);

// release sequence file
tsSequenceFile2.ReleaseDispatch();

The second releaseSequenceFile, gives me the error message that the specified
sequence file is already been unloaded by the engine.

regards

[James_Grey]

GetSequenceFile returns two "references". The normal "dispatch" reference and a "GetSequenceFile" reference.

Call ReleaseSequenceFile once for each call to GetSequenceFile. This is in addition to releasing your dispatch reference. If you call AddRef, balance it only with ReleaseDispatch, not ReleaseSequenceFile.

Note that after you call ReleaseSequenceFile once for each GetSequenceFile, any sequence file unload callbacks run and you should not call methods other than ReleaseDispatch on references for that sequence file.

Your example has two "Dispatch" references and one GetSequenceFile "reference". However, it balances that with two ReleaseSequenceFiles and two ReleaseDispatches.

You can call GetSequenceFile twice with the same pathname if you want to call
ReleaseSequenceFile twice.

- James

[esmeralda]

thanks james,
I find it strange that adding a new reference to the dispatch interface does not completely make me a a new Sequence File interface.
I thought I read somewhere that ReleaseSequenceFile would know the reference count and only release it when count = 0. According to you this is only valid for the number of GetSequenceFiles you call.

So...how would you go about making a new copy...
Suppose I have a function where I send a sequencefile object as a parameter. In this function I would like to make a copy for own use within the class. As I do not know the lifetime of the sequenceFile object I'm getting as a parameter, I would like to make my own copy and work with that and I can call ReleaseSequenceFile when I'm done with it.

thanks for your re
ply

regards

[KittF]

The following is implied by James' posting.

You cannot rely on the passed sequencefile object remaining valid within your function. The calling code could easily call ReleaseSequenceFile on the object before you are finished using the object within your function. It would then be incorrect to use the object.

For your design you will need to call GetSequenceFile (or GetSequenceFileEx) within your function to pair with the ReleaseSequenceFile (or ReleaseSequenceFileEx) in the function. You can use the passed object to obtain the sequence file path to use in your GetSequenceFile method.

One word of warning. Calling GetSequenceFile and ReleaseSequenceFile are designed to run the SequenceFileLoad and SequenceFileUnload callbacks of your sequence f
ile, if it has them. You may not want this to occur within your function. To avoid calling this callbacks you can set the getSeqFileFlags parameter of the GetSequenceFile method and the options parameter of the ReleaseSequenceFileEx method accordingly. Even if your sequence files do not have these callbacks, you should consider whether it ever makes sense to run the callbacks within your function upon geting and releasing the sequence file.

[James_Grey]

Adding a reference to an ActiveX object never makes a new copy of the object. The ActiveX object must offer some explicit method of duplicating it. In TestStand, this method is PropertyObject.Clone.

Unfortunately, cloning a SequenceFile has a couple of wrinkles that don't arise for other object types.

1) Before TestStand 2.0.1, you could not save a cloned sequence file.

2) You cannot run a cloned file unless you first "load" the clone. Currently, the only way to "load" the clone is to save it or use GetSequenceFile to load it. Since you can't call GetSequenceFile on the clone until you have saved it, either method requires TestStand 2.0.1. I have attached an example 2.0.1 sequence which clones a sequence file object and then saves th
e clone in order to "load" it so it can run. Please read the description of the label step for more information. If you don't have a beta copy of 2.0.1, the only way I can think of to clone a SequenceFile object (and still be able to run the clone) is to call a file system function to copy the disk file to a new name and then load the new file.

- James

PS. You could probably avoid both wrinkles by writing your own sequence file cloning function that creates a new sequence file and inserts clones of the sequences and variables from the original file. It would also have to copy over all the property settings you need. Note that I haven't tried this.

[James_Grey]

Here is an update:

We fixed the cloning problem in TestStand 2.0.1 (post beta). Now, cloning a file implicitly loads it. Thus you can run it without having to save it. You must also call ReleaseSequenceFile on the cloned file. TestStand 2.0.1 will not be available until early 2002.

[esmeralda]

thank you very much for all your replies James.
looking forward for the 2.0.1