Note pad concepts and terminology

To use an XCF note pad, you must understand the following concepts and related terminology:

Note: Application provided data identified by a note name.
Note pad: A collection of notes identified by a note pad name.
Connection: An entity that manipulate notes in a note pad, identified by a connection token.

To use an XCF note pad, you must understand the various functions provided by the XCF Note Pad Services:

Note Pad Services: These services enable your application to create or delete a note pad, and get information about a note pad. The creator of the note pad determines the attributes of the note pad and the number of notes it can hold. Some specifications require users of the note pad (connections) to adhere to certain conventions or protocols. The query service can be used to determine whether a note pad exists. If it does exist, the query service can be used to get information about the note pad. The note pad will generally exist until it is explicitly deleted or fails. A note pad does not survive a sysplex outage. When deleting a note pad, you can optionally specify various conditions that must be satisfied in order for the delete request to go forward. For example, you might want the delete request to be rejected if the note pad still has connections.
Connection Services: The connection services enable your application to create or delete a note pad connection, and pause or resume some particular connection thread. A connection must be created in order for a program to manipulate notes in the note pad. When creating a connection, the program can specify a termination scope to bind the connection to a particular task or address space. When the designated task or space terminates, XCF automatically deletes the connection. Alternatively, a program can explicitly delete the connection when it is no longer needed. XCF implicitly deletes a connection if the system that created the connection terminates. XCF also deletes a connection if the relevant note pad fails or is otherwise deleted.
There might be times when the note pad becomes inaccessible. For example, connectivity to the coupling facility that contains the note pad could be lost, or the CF structure that hosts the note pad could be in rebuild. Such a note pad is said to be in a quiesced state. When quiesced, requests to manipulate notes in the note pad are rejected. To determine when the note pad is once again accessible, the connection can use the connection service to pause a particular work unit. This service suspends the calling work unit until access to the note pad is restored, or until various other conditions are satisfied (such as the expiration of a timeout value). The connection service can also be used to resume the paused work unit at the discretion of the application.
Note Services: The note services enable your application to manipulate one or more notes in a note pad. To use these services, your application must first create a connection to the note pad. Once connected, the note services can be used to create, update, read, or delete one particular note (a single note request). In this case, the note to be processed is identified by its user provided name. The note services can also be used to read or delete a collection of notes (a multi-note request). In this case, the notes to be processed are identified by selection criteria. The selection criteria define the attributes of the notes to be processed. XCF finds the notes in the note pad that satisfy the selection criteria and applies the requested operation to those notes.

To use an XCF note pad, you must understand how to code the IXCNOTE macro to exploit the functions provided by the XCF Note Pad Services and the contexts in which these functions can be used by your program. You must understand how to format the input data areas required for the requested function, how to interpret the request results, and how to use the information stored in various output data areas. These data areas include:

Answer Area: When your program issues the IXCNOTE macro to call the XCF Note Pad Services, it can provide an answer area. The storage for the answer area is obtained by your program. XCF stores data relevant to the result of the request in the answer area. Although an answer area is optional for most requests, you can always provide one if you like. In many cases, XCF will store diagnostic data and other potentially useful details in the answer area if one is provided. If your program needs to use these details or if the diagnostic data is needed to diagnose a problem, an answer area must be provided.
Buffer Area: When your program issues the IXCNOTE macro to process a single note request or a multi-note request, it can provide a buffer area. The storage for the buffer area is obtained by your program. The buffer area is used for note content. When creating or replacing a note, your program stores the desired note content in the buffer area and then issues the IXCNOTE request. XCF fetches the data from the buffer area and stores a copy of it in the designated note out in the note pad. When reading or deleting a note, XCF fetches the note content from the designated note in the note pad and stores a copy of it in the buffer area. When reading a collection of notes, the content of each note in the collection is stored in the buffer area (for as many notes as will fit).
Selection Criteria: When processing a multi-note request, your program can optionally provide an input data area containing selection criteria. The storage for the selection criteria data area is obtained by your program. A multi-note request processes a collection of notes. Your program formats the data area to define the criteria that XCF will used to determine which notes are to be selected for the collection.

Mappings for the data areas related to use of the IXCNOTE macro are declared in the IXCYNOTE macro.