Options for ReleaseSeqFileEx

[jsiegel2]

The documentation for the options to the Engine.ReleaseSeqFileEx function lists one option as:

"ReleaseSeqFile_DiscardChanges - (Value: 0x1) Use this option to remove a modified sequence file from the Engine internal cache, thus discarding changes to the file..."

My question is: if I use this option when releasing a sequence file, is an unmodified sequence file not removed from the internal Engine cache? If I don't use this option, does a modified sequence file remain in the cache? And is removing a file from the cache the same as releasing it? Basically, I want to release a sequence file, whether or not it has been modified, and be able to load a fresh sequence file in the future.

Also, there are two options in the documentation for Re
leaseSeqFile_UnloadFile and ReleaseSeqFile_UnloadFileIfModified, but they have no specified values. What do these options do and how are they used? What is the difference between unloading, releasing, and removing from the cache?

Thanks.

[Jason F.]

Hi Jeff,

Yes, removing a file from the engine's internal cache is the same thing as releasing it. The main thing to keep in mind is that the file will remain in the cache until all references to it are released. There could be more than one reference to a file at any given time, whether your Operator Interface/Sequence Editor has a reference to it or an executing sequence has a reference to it, etc... Whenever you are editing a file in the Sequence Editor, the editor will maintain a list of changes you've made to the file until you save it. If you use the UnloadFileIfModified option when releasing, it will cause the editor to ignore the fact that it hasn't been saved (once a file has been saved, it is no longer in a "modified" state). You can combine the different options for the release method using the bitwise OR operator in the language you are calling it from since they are simply integer values. Try combining these options until you get the behavior that you would like. As you noted, there are some errors in the documentation for the options, in regards to what values they are, what they do specifically, and which ones are really valid/useful. Follow this guide for the options (notice that the DiscardChanges option is omitted; this option is not intended to be used externally by end-user programmers):

ReleaseSeqFile_DoNotRunUnloadCallback�(Value: 0x2) Use this option to prevent the SequenceFileUnload callback from running if the callback exists and the reference being released is the last reference. If other references exist to the sequence file, TestStand may execute the SequenceFileUnload callback when these references are released using Engine.ReleaseSequenceFileEx.

* Use the SequenceFile.UnloadCallbackEnabled property to prevent the SequenceFileUnload callback from ever being executed.

ReleaseSeqFile_NoOptions�(Value: 0x0) No options.

ReleaseSeqFile_UnloadFile�(Value: 0x4) Use this option to request TestStand to remove a sequence file from the engine's internal cache. When you specify this option, it does not guarantee that TestStand will remove the sequence file from the cache because there may be multiple references to it or it may be executing. If you do not specify this option, TestStand may remove the sequence file from the cache if TestStand no longer needs the file.

ReleaseSeqFile_UnloadFileIfModified�(Value: 0x1) Use this option to remove a modified sequence file from the engine's internal cache.

Jason F.
Applications Engineer
National Instruments
www.ni.com/ask

[jsiegel2]

Jason, thanks for the clarification of the incorrectly documented options. However, my question still remains (it's slightly different now with the new information you gave me):

How is the option ReleaseSeqFile_UnloadFile different from ReleaseSeqFile_NoOptions? I would have thought that the default behavior would be to only truly remove the file from the cache if there are no other references to it? It sounds like if you use the ReleaseSeqFile_NoOptions option, the sequence will be removed from the cache even if it is still in use somewhere else? If this is true, what happens to the other "owners" of the file? Do they immediately return errors?

Also, for the ReleaseSeqFile_UnloadFileIfModified option, will the command be ignored if the specified file is *n
ot* modified (i.e., the file won't be unloaded)? If not, how is the behavior different on an umodified vs modified file?

[RyanR]

Hi Jeff,

To clarify. A sequence file will NEVER be released as long as there are multiple references to the file. Calling ReleaseSequenceFileEx releases your reference to the sequence file. Sequence call steps, executions and other objects need to refer to sequence files at some time or another. Passing the UnloadFile option allows you to remove the sequence file from the engine's cache and notify that the Sequence Editor that this file must be reloaded from disk. If you pass No_Options, then the engine may keep the sequence file in the cache. The important thing to note here is that you can never guarantee when a sequence will be removed from the cache, but you a sequence file will never be unloaded provided that there are external references to th
e file.