What is a connection

An XCF note pad Connection has the following:

A 32 byte connection token
A 12 byte connection ID
A 32 byte description
A 64 byte static information area
An access scope
A connection scope
A usage classification
A termination scope

To access the notes in a note pad, your program must first create a connection to the note pad. When creating a connection, the application indicates the name of the note pad to which the connection is to be established. It also provides a description of the connection, static information about the connection, and an indication of whether the connection is to be used strictly for reading notes or whether it is to be used to update notes in the note pad.

XCF sets the connection token and connection ID upon successful creation of the connection.

The connection scope is derived by XCF from the security environment that exists when the connection is created. The connection will either have address space scope or task scope.

The usage classification indicates how the application intends to use the connection. The primary purpose of the usage classification is to provide a way for authorized programs to create connections that can be used by a user that is not the connector.

The application specifies the termination scope to bind the connection to a particular task or address space. If the indicated task or space terminates, the connection is deleted by XCF.

In general, an application must create one connection for each address space that needs to access the note pad. XCF limits the number of connections that can be created for a given address space. The limit depends on the installed level of the XCF Note Pad Services. See Note pad related limits for more information.

Note: A connection created for either server usage or client usage needs but one connection from the server address space, even though the note pad can be accessed from work units that originate in an arbitrary address space.

Once created, a note pad connection persists until it is explicitly deleted or fails. A connection is explicitly deleted when a program issues the IXCNOTE macro to delete it. A connection fails and is implicitly deleted when any of the following activities occur:

The note pad is deleted
The note pad fails
The connector address space terminates
The connector task terminates (if the connector has task scope)
The task or address space designated by the termination scope terminates
The connector system terminates

XCF does not provide a programmatic way to get information about peer note pad connections. If an application requires awareness of its connections, it must devise its own means of discovering this information. You might consider using notes in your note pad to do this. For example, create a nonpersistent note to represent your connection. You might establish a convention of using a tag value of zero for these notes alone. A multi-note read request with tag selection criteria for tag value zero would then return a note for each connection. Since a nonpersistent note is automatically deleted by XCF when the connection terminates, the returned notes would only include the current connections.