Parameters for REQUEST=NOTEPAD

,#NOTES=#notes
When REQTYPE=CREATE is specified, use this required input parameter to specify a variable containing the number of notes that the note pad needs to hold. The specified value must be at least one.

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.

When REQTYPE=MODIFY is specified, use this required input parameter to change the maximum number of notes that a note pad is allowed to hold. The specified value may be greater than (increase) or less than (decrease) the current #NOTES value for the note pad.
The specified value must be at least one (1).

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
,CONDITIONS=YES
When REQTYPE=DELETE is specified, use this required parameter to indicate whether there are any conditions that must be satisfied in order to delete the note pad.
,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.
,DESCRIPTION=description
When REQTYPE=CREATE is specified, use this required input parameter to specify a variable containing a description of the note pad. The string can contain any alphanumeric (A-Z, a-z, 0-9), national (@, #, $), or special (underscore or blank) character. Leading blanks and all blank descriptors are not permitted. Descriptions are case sensitive. The description will appear in various XCF messages and diagnostic data reports. The description is intended to help installations and service personnel understand the function, purpose, or role of the note pad.

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.

,DUPLEX=AVOID
,DUPLEX=FAVOR
When REQTYPE=CREATE is specified, use this optional parameter to indicate a preference as to whether the note pad should be placed in a duplexed coupling facility structure. There is no guarantee that the specified preference can be satisfied. If the preference is satisfied initially, there is no guarantee that the preference will remain in effect for the life of the note pad.

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.
,ETODCREATED=etodcreated
,ETODCREATED=ANY
When REQTYPE=DELETE is specified, use this optional input parameter to specify a variable containing the extended time of day timestamp (ETOD) when the note pad was created. This timestamp identifies a unique instance of the note pad. Specify this keyword to ensure that the intended instance of the note pad is deleted. If not specified, or if the value of the indicated variable is zero, the current instance of the note pad will be processed.

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.

,INFO=info
,INFO=0
When REQTYPE=CREATE is specified, use this optional input parameter to specify a variable which contains information about the note pad. The content and interpretation of this information is determined by the creator of the note pad. XCF associates a copy of the indicated data with the note pad. A copy of the data is visible to other processes in the sysplex via queries that return information about the note pad. The creator might, for example, use INFO to define the protocols that users of the note pad are to follow. Alternatively, INFO could be used to describe the attributes of the note pad.

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
,INSTCOMP=REQUIRED
When REQTYPE=CREATE is specified, use this optional parameter to indicate whether the users of the note pad are required to perform instance number comparisons when replacing or deleting a note (see INSTANCE# keyword for REQUEST=NOTE). The default is INSTCOMP=DISCRETIONARY.
,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.

,LOSSCONNDELETE=NO
,LOSSCONNDELETE=YES

When REQTYPE=CREATE is specified, use this optional parameter to indicate whether XCF can automatically initiate note pad delete processing when all systems with connectors to the note pad have lost connectivity to the coupling facility hosting the note pad. The default is NO.

,LOSSCONNDELETE=NO
XCF will not automatically initiate note pad delete processing when all systems with connectors to the note pad have lost connectivity to the coupling facility hosting the note pad.
,LOSSCONNDELETE=YES

XCF will automatically initiate note pad delete processing when all systems with connectors to the note pad have lost connectivity to the coupling facility hosting the note pad.

As a result of XCF automatically initiating delete processing the following will occur:
  • 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 might have their IXCNOTE requests rejected with a variety of reason codes (including for example, IXCNOTERSNNOTEPADNOTEXIST, IXCNOTERSNCONNECTIONNOTEXIST, and IXCNOTERSNNOTENOTEXIST).
  • Any existing paused connections would be resumed and then deleted as part of deleting the note pad. If an answer area was provided on the PAUSE request, dr_ResumeCode=ixcynote_kResumeBeingDeleted would be set in the date area mapped by ixcynote_tDetailsResumed.
,MULTIWRITE=NO
,MULTIWRITE=YES
When REQTYPE=CREATE is specified, use this required parameter to indicate whether the note pad can be updated by more than one connector at a time.
,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.
,MUSTBE=EMPTY
,MUSTBE=UNUSED
When CONDITIONS=YES and REQTYPE=DELETE are specified, use this required parameter to indicate the conditions that must be true in order for the note pad to be deleted.

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.

If there are competing delete requests with different conditions, or perhaps no conditions at all, the delete will be processed per the request with the least restrictive conditions.
,MUSTBE=EMPTY
The note pad must be empty. If the note pad contains notes, the delete request will be rejected (IXCNOTERSNNOTEPADINUSE).
,MUSTBE=UNUSED
The note pad must not have any users. If the note pad has a connection, the delete request will be rejected (IXCNOTERSNNOTEPADINUSE).

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

,NOTEPAD=notepad
Use this required input parameter to specify a variable containing the name of the note pad to be processed.

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
,REQTYPE=QUERY
,REQTYPE=DELETE
,REQTYPE=MODIFY
Use this required parameter to indicate the type of request to be processed against the note pad.
,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).

,REQTYPE=MODIFY
Increase or decrease the number of notes a note pad is allowed to hold.
,TAGGING=XCF
,TAGGING=USER
When REQTYPE=CREATE is specified, use this optional parameter to indicate whether note tags are to be assigned by the user or by XCF.
Every note has a 16 byte note tag that is to be set (or preserved) whenever the note is manipulated (REQUEST=NOTE). The creator of the note pad determines whether note tags are to be assigned by the user or by XCF. Note tags must be assigned in the same way for the duration of the note pad. Thus all connectors to the note pad must adhere to the note tag assignment protocol specified by the creator of the note pad. The default is TAGGING=XCF.
,TAGGING=XCF
XCF is responsible for assigning tags to notes. XCF tag values are ever increasing. A new tag is assigned whenever a note is successfully created, replaced, or written. XCF does not assign a new tag when deleting a note.
,TAGGING=USER
The user is responsible for assigning tags to notes whenever a note is created, replaced, or written. One can also assign a new note tag when deleting a note.

User defined note tags can be used in any way that the exploiter deems suitable. For example, one could use tags to identify a collection of notes that are to be associated with each other, or one could use tags to assign a logical sequence number to each note. Alternatively, a tag could simply be additional metadata that is associated with the note.

Note that specifying TRACKTAG=CURRENT or TRACKTAG=LIFETIME imposes additional sequencing requirements on user assigned TAG values that are enforced when writing, replacing, or deleting existing notes.

,TIMEOUT=timeout
,TIMEOUT=XCF
Use this optional input parameter to indicate the number of seconds that the caller is willing to allow for the request to complete. The TIMEOUT specification imposes an upper bound on the duration of the request.

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
,TRACKTAG=CURRENT
,TRACKTAG=LIFETIME
When REQTYPE=CREATE is specified, use this optional parameter to indicate whether XCF needs to track the maximum tag value assigned to a note, and if so, how that value should be maintained and reported. The default is TRACKTAG=NO.
,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.