Description

The XCF Note Pad macro (IXCNOTE) encapsulates the interfaces that allow an application to interact with the XCF Note Pad Services. With these interfaces, an application can create or delete a note pad. A note pad contains zero or more notes. A note contains 1024 bytes of application data and is identified by an application provided name. An application that is connected to a note pad can create, read, modify, or delete notes in the note pad. Each note has an instance number that is assigned by XCF whenever the note is created or modified. The instance number uniquely identifies an instance of a particular note.

Depending on the various attributes specified when the note pad is created, you can use a note pad for any of the following purposes:

Store data that allows a backup instance of an application to resume processing on some other system in the sysplex after the primary instance fails.
Share data between systems in the sysplex. You can use the instance number of a note to provide a simple "compare and swap" type serialization to ensure the integrity of updates to the shared notes.

To begin using a note pad, you must first create it. Once created, the note pad will persist until one of the following situations occurs:

The exploiter explicitly deletes the note pad by using an IXCNOTE REQUEST=NOTEPAD REQTYPE=DELETE request.
The note pad fails.
The note pad is manually deleted through use of the note pad deletion utility IXCDELNP.

The creator of the note pad determines its attributes. For example, the creator specifies the number of notes that the note pad must hold and indicates whether the note pad can receive updates from multiple connections.

After a note pad is created, a program must connect to the note pad to use it. One or more systems in the sysplex can access a note pad. On any given system, each address space that uses the note pad might need its own connection. In other cases, a single connection from one particular address space might suffice. The design of the exploiting application determines what is needed.

A connection has either task scope or address space scope. In either case, the connector address space is the address space that is home when the connection is created.

Task scope: If the task that creates the connection has its own security environment, meaning that TCBSENV is nonzero, the connection has task scope. For a connection with task scope, the connector is the task itself.
Address space scope: If the connection is created by an SRB or by a task that does not have its own security environment, meaning that TCBSENV is zero, the connection has address space scope. For a connection with address space scope, the connector is any work unit whose home address space is the connector address space, and for which the work unit is either an SRB or a task that does not have its own security environment. Thus, an address space connection can have multiple work units serve as the connector.

A valid user is a work unit that is allowed to use a connection to a note pad. Each IXCNOTE request that requires a connection indicates the conditions under which the requester is deemed a valid user. The creator of the connection specifies the USAGE keyword to indicate the criteria that determine a valid user when accessing notes in the note pad. Notes in a note pad are accessed with an IXCNOTE invocation that specifies REQUEST=NOTE or REQUEST=NOTES.

After a connection is created, the SAF profile of the connector might change. XCF is not typically aware of such changes since SAF checking is not typically performed for a connection that is used by a work unit that is deemed a valid user. To ensure that changes to the SAF profile are observed by XCF and applied to the connector, you must delete the connection and recreate it. In some cases, you might need to bring down the connector address space in order for the changes to become effective.

A note pad resides in a coupling facility. In general, if a coupling facility that contains a note pad fails, the note pad also fails. XCF automatically deletes a failed note pad and all of its connections throughout the sysplex. As needed, the application is responsible for recovering the note pad by recreating it, reestablishing the necessary connections to the new note pad instance, and recreating the notes.

Under normal circumstances, a request to access a note in a note pad is processed as a synchronous coupling facility operation. As needed, the invoking work unit is suspended until the request completes. However, if conditions are such that the duration of the suspension might be significantly longer than normal, the note request is rejected. In such cases, XCF returns with a return and reason code that indicates the situation (IXCNOTERSNQUIESCED). Requests are rejected in this manner when, for example, the coupling facility structure that contains the note pad is quiesced for rebuild processing.

Note: A structure that is engaged in rebuild processing might quiesce for several seconds, perhaps even several minutes.

The connector can issue IXCNOTE REQUEST=CONNECTION REQTYPE=PAUSE to wait for the quiesce conditions to clear. The service routine that processes the PAUSE request might also return if the quiesce conditions change. If the note pad becomes accessible again, the connector try again to use IXCNOTE to manipulate notes in the note pad. If the note pad is still inaccessible, the requester can inspect the quiesce conditions to determine whether to reissue the PAUSE request to continue waiting, or to take some other appropriate recovery action such as disconnecting from or even deleting the note pad. As an alternative to using the PAUSE request, the connector can simply try the request again after allowing some time for the condition to clear (poll).

The IXCNOTE macro completes a parameter list with caller provided data and generates a stacking, space-switch program call to an XCF service routine.

Note: The calling work unit might suspend until the request completes.