z/OS MVS Programming: Sysplex Services Guide
Previous topic | Next topic | Contents | Contact z/OS | Library | PDF


Note instance number

z/OS MVS Programming: Sysplex Services Guide
SA23-1400-00

Every note in the note pad has an 8 byte instance number that is managed by XCF. The intended use of the instance number is to provide a simple compare and swap like serialization mechanism that enables note pad connectors to make updates to a given note with integrity. XCF assigns a unique instance number to a note when it is created and every time it is updated. When an application attempts to process a note, it can optionally specify the instance number for the instance of the note that is to be processed. If the specified instance number equals the current instance number assigned to the note, XCF processes the request. If the instance numbers are not equal, XCF rejects the request due to an instance number mismatch. When a request is rejected due to an instance number mismatch, XCF returns the current instance number of the note. However, to preserve the integrity of the note, the application will likely need to issue a new read request to fetch the latest copy of the note content from the note pad.

For example, an application might issue a read note request to get the current content of a note and its instance number. Call this copy1a. The application might then modify the in-storage copy of the note (call this copy1b) and issue a replace request to update the note out in the note pad. However, the content of the note might already have been changed out in the note pad by some other thread. The copy of the note out in the note pad would have a new instance number. Call this copy2. Without an instance number comparison, the new replace request issued for copy1b would unconditionally overwrite copy2 of the note, which likely causes a loss of data (the changes written by the other thread). With instance number comparison, the new replace request issued for copy1b would be rejected due to an instance number mismatch. The application could then read copy2 of the note into local storage and reapply its updates in an appropriate manner.

The creator of the note pad determines whether instance number comparisons are required when updating or deleting a note. If so required, a request to update or delete a note is rejected if the requester fails to ask for an instance number comparison. Thus the creator of the note pad can have XCF enforce a design requirement that all note updates be made with instance number comparisons. However, the application must still take responsibility for appropriately refreshing the local in-store copy of the note content before reissuing the request after an instance number mismatch. Without instance number enforcement by XCF, use of instance number comparisons would be achieved as needed through convention within the application. Since not all applications require the use of instance number comparisons to ensure the integrity of the note when making updates, such conventions and enforcement by XCF might not be needed.

Go to the previous page Go to the next page




Copyright IBM Corporation 1990, 2014