After the note pad is created, there can be times when XCF is unable to provide the requested number of notes. For example, the coupling facility structure containing the note pad could be full. In such cases, a request to process a note could be rejected with a return and reason code indicating that the note pad resources are constrained (IXCNOTERSNCONSTRAINED). If the note pad is not constrained, an attempt to create more than the requested number of notes is rejected with an indication that the note pad is full (IXCNOTERSN#NOTESEXCEEDED).

If the note pad is full, it might be necessary to delete one or more notes in order to successfully create a new note or update an existing note.

To code: Specify the RS-type address, or address in register (2)-(12), of a fullword field, or specify a literal decimal value.

,CONDITIONS=NO

The delete of the note pad is to be performed unconditionally. The note pad is to be deleted even if it contains notes. The note pad is to be deleted even if it has connections.

,CONDITIONS=YES

The delete of the note pad is to proceed only if the conditions specified by the MUSTBE keyword are satisfied.

The storage containing the DESCRIPTION must reside in the primary address space of the caller, or in a space addressable via a public entry on the Dispatchable Unit Access List (DU-AL), or in a common area data space. The storage must be accessible using the PSW key of the program making the request.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32 character field.

A duplexed structure will generally provide greater availability since it is generally more resilient to failure than a simplex structure. A simplex structure will generally provide faster request response times than a duplexed structure since the note operations will not incur the overhead needed to replicate the request. The requirements of the exploiting application determine which option is to be preferred. The default is DUPLEX=AVOID.

,DUPLEX=AVOID

XCF should try to avoid placing the note pad in a duplexed structure.

,DUPLEX=FAVOR

XCF should try to place the note pad in a duplexed structure.

The note pad data record contains the relevant ETOD (NPD_ETODWHENCREATED). A note pad data record (IXCYNOTE_TNOTEPADDATA) is stored in the answer area when the note pad is created or queried. The connect data record also contains the relevant ETOD (CD_ETODWHENNPCREATED). A connect data record (IXCYNOTE_TCONNECTDATA) is stored in the answer area when a connection to the note pad is created. The default is ANY.

To code: Specify the RS-type address, or address in register (2)-(12), of a 16-character field.

The storage containing the INFO must reside in the primary address space of the caller, or in a space addressable via a public entry on the Dispatchable Unit Access List (DU-AL), or in a common area data space. The storage must be accessible using the PSW key of the program making the request.

The default is 0.

To code: Specify the RS-type address, or address in register (2)-(12), of a 64-character field.

,INSTCOMP=DISCRETIONARY

Instance number comparisons are not required.

When a note pad connector calls IXCNOTE REQUEST=NOTE to replace, write, or delete an existing note, any INSTANCE# specification is permitted. Instance number comparisons will be performed only if the connector so requests.

,INSTCOMP=REQUIRED

Instance number comparisons are required.

When a note pad connector calls IXCNOTE REQUEST=NOTE to replace, write, or delete an existing note, an instance number comparison must be performed to ensure that the correct instance of the note is being manipulated. For REQTYPE=REPLACE and REQTYPE=DELETE, the request is immediately rejected unless a nonzero INSTANCE# value is specified. For REQTYPE=WRITE, the request proceeds. If the note does not exist, the write request will create a new note (if the request is otherwise valid). If the note already exists, the write request is rejected.

,MULTIWRITE=NO

The note pad is to have at most one connector with write access (ACCESS=UPDATE) connected to the note pad at any one time.

,MULTIWRITE=YES

The note pad can have two or more connectors with write access (ACCESS=UPDATE) connected to the note pad at the same time.

One or more conditions can be specified. Only the specified conditions are considered when determining whether to delete the note pad. For example: Specifying MUSTBE=EMPTY means the delete request is rejected if the note pad contains notes, but the existence of connections is irrelevant. Specifying MUSTBE=UNUSED means the delete request is rejected if the note pad has connections, but the existence of notes is irrelevant. Specifying MUSTBE=(EMPTY,UNUSED) means the delete request is rejected if the note pad has notes or connections or both.

One or more values can be specified for the MUSTBE parameter. If more than one value is specified, group the values within parentheses.

Note pad names are mapped by IXCYNOTE_TNOTEPADNAME. Note pad names consist of four 8 byte sections. The various sections identify the owner of the note pad, the application using the note pad, and its function. Each 8 byte section must be left justified, padded on the right with EBCDIC blanks as needed. Each section can contain any uppercase alphabetic (A-Z), numeric (0-9), national (@, #, $), or underscore (_) character. The first two sections, which identify the owner and application, must not be all blanks. The remaining sections can be all blank.

To avoid names used by IBM®, do not begin note pad names (owner) with the letters A through I or the character string SYS. Names beginning with the string SYSXCF are reserved for use by XCF.

Note that if the installation so chooses, it can define coupling facility structure names of the form IXCNP_ownerxx (where xx is the EBCDIC representation of a two digit hexadecimal number) to have XCF allocate note pads for the indicated owner in one of the designated structures. In the absence of any such definition, the note pad will be allocated in a default note pad structure defined for XCF.

To code: Specify the RS-type address, or address in register (2)-(12), of a 32 character field.

,REQTYPE=CREATE

XCF is to create a new note pad.

,REQTYPE=QUERY

Get information about the note pad.

If an answer area (ANSAREA) is provided, one can for example, obtain the maximum number of notes supported by the note pad, the current number of notes in the note pad, or the maximum note tag value, as well as the INFO that was specified by the creator of the note pad. One can also obtain information about the systems that have connections to the note pad.

If an answer area is provided, it must be large enough to contain at least one note pad data record (IXCYNOTE_TNOTEPADDATA). If not, the request is rejected (IXCNOTERSNANSLENMORE). If the answer area is large enough for the note pad data record but not large enough to hold all of the system connection records (IXCYNOTE_TSYSCONNDATA), the answer area is filled with the note pad data record and as many system connection records as will fit. The request completes with an indication that more storage is needed to obtain all of the records (IXCNOTERSNMOREDATA).

If an answer area is not provided, one is in effect testing for the existence of the note pad.

,REQTYPE=DELETE

Delete the indicated note pad, provided the specified conditions (if any) are satisfied.

Any existing notes will be deleted as part of deleting the note pad.

Any existing connections will be deleted as part of deleting the note pad. Depending on the timing as to when the deletion is recognized, connections that are deleted in this manner can have their IXCNOTE requests rejected with a variety of reason codes (including for example, IXCNOTERSNNOTEPADNOTEXIST, IXCNOTERSNCONNECTIONNOTEXIST, and IXCNOTERSNNOTENOTEXIST).

If the TIMEOUT keyword is not specified, or if TIMEOUT=XCF is specified, or if the specified value is zero, the maximum duration of the request is at the discretion of XCF.

The amount of time needed to complete a given REQTYPE will depend on the nature of the request as well as the state of the system and the note pad. In particular, there is the potential for any given request to be delayed while XCF processes previously accepted requests, some of which could be long running.

For REQUEST=NOTEPAD, XCF might need to access the Couple Data Set that contains the Coupling Facility Resource Manager (CFRM) policy that governs use of coupling facility resources in the sysplex. There can be a variety of conditions for which these accesses might require tens of seconds if not minutes to complete.

Choose TIMEOUT values accordingly.

In general, a REQUEST=NOTEPAD request requires multiple steps in the backend processing. If the request times out, the request might or might not have been processed successfully. Depending on the request and the design of the exploiting application, it might be appropriate to try the request again, perhaps with a longer timeout value. In some cases, one might need to issue a QUERY to determine whether the note pad exists.

The default is XCF.

To code: Specify the RS-type address, or address in register (2)-(12), of a halfword field, or specify a literal decimal value.

,TRACKTAG=NO

XCF need not track the maximum note tag values. When reporting the maximum tag value, XCF will always report zero. Requests to create, replace, write, or delete a note will not incur any additional overhead for tracking of the maximum note tag.

For user assigned tags (TAGGING=USER), any value can be assigned to the tag when writing, replacing, or deleting a note. In particular, the new tag value for the note can be less than, equal to, or greater than the current tag value of the note.

,TRACKTAG=CURRENT

XCF is to track the maximum tag of the notes that currently exist in the note pad. When reporting the maximum note tag value, XCF will report the maximum tag value assigned to any note that exists in the note pad when the query is made. If the note pad is empty, zero will be reported. Requests to create, replace, write, or delete a note will not incur any additional overhead for tracking of the maximum note tag.

For user assigned tags (TAGGING=USER), the tag value assigned when writing, replacing, or deleting a note must be greater than or equal to the current tag value of the note. In effect, TRACKTAG=CURRENT imposes a requirement that the tag values assigned to existing notes be nondecreasing. If the new tag value is less than the current tag value of the note, the request is rejected (IXCNOTERSNNOTELOWTAG). Any tag value can be assigned when creating a note.

,TRACKTAG=LIFETIME

XCF is to track the maximum tag of any note that ever existed in the note pad. When reporting the maximum tag, XCF will report the maximum tag value ever assigned to any note, including deleted notes.

For user assigned tags (TAGGING=USER), the tag value assigned when writing, replacing, or deleting a note must be greater than or equal to the current tag value of the note. In effect, TRACKTAG=LIFETIME imposes a requirement that the tag values assigned to existing notes be nondecreasing. If the new tag value is less than the current tag value of the note, the request is rejected (IXCNOTERSNNOTELOWTAG). Any tag value can be assigned when creating a note.

Tracking the maximum tag value for the life of the note pad is not without cost. When deleting a note, XCF might have to defer deletion of the note until the maximum tag value can be recorded. In such cases, the note is said to be pending delete. XCF will automatically finish deleting the note, but a subsequent request for a note that is still pending delete at the time of the request could be delayed until XCF finishes deleting the prior instance of the note.

In practice, the need to defer delete requests and the additional overhead or delays (if any) encountered by other requests will vary according to the use of the note pad, the tags that are assigned to the notes, the attributes of the note pad, and the dynamics of the system.