Parameters for REQUEST=NOTE

,BUFFER=buffer

,NOBUFFER

Use this required input parameter to specify how XCF is to handle the contents of the note.

,BUFFER=buffer

One of a set of mutually exclusive keywords indicating the buffer into/from which the note content is stored/fetched. When creating, replacing or writing a note, the buffer names an input area that contains the data that is to be written as a note in the note pad. When reading or deleting a note, the buffer is an output area into which XCF is to place a copy of the note that was fetched from the note pad. Refer to the description of BUFLEN below for additional details.

The storage containing the BUFFER 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 character field.

,NOBUFFER

One of a set of mutually exclusive keywords indicating that no buffer is being provided for the note request.

When creating a note, the note will have no content (the size of the note will be zero). A note with no content is called a null note. When replacing a note, the current content of the note will not be changed. If writing a note, the content of the note will not be changed if the note exists, and the note will be null if it does not exist. Use BUFFER with a BUFLEN of zero if an existing note is to be replaced or written with null content.

When reading or deleting a note, the request will be processed but the content of the note will not be copied into storage.

,BUFLEN=buflen

When BUFFER=buffer is specified, use this required input parameter to specify a variable containing the size in bytes of the buffer. The specified value must be a multiple of 1024 (1K).

If BUFLEN is zero, then:

When reading or deleting a note, the request is rejected unless the note to be processed is a null note (has no content).
When creating, replacing, or writing a note, the resulting note will be a null note. In particular, note that when writing or replacing an existing note, the existing content of the note (if any) will be lost when the BUFLEN value is zero. Use NOBUFFER if the content of the note is to be preserved.

If BUFLEN is nonzero, then:

When reading or deleting a note, the nonzero BUFLEN must be greater than or equal to the size of the note being processed. The number of bytes stored in the buffer will be the actual note size. If the buffer is larger than the note size, XCF does not update any bytes in the buffer beyond the end of the note. If the buffer is smaller than the actual note size, the request is rejected.
When creating, replacing, or writing a note, the nonzero BUFLEN indicates the size of the note. The nonzero value must be less than or equal to the maximum note size defined by the creator of the note pad. If BUFLEN exceeds the maximum note size defined by the creator of the note pad, the request is rejected.

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

,CONNECTION=connection

Use this required input parameter to specify a variable containing the token representing the connection to the note pad.

This token was returned by a previous invocation of IXCNOTE REQUEST=CONNECTION REQTYPE=CREATE. The connection represented by the token must have been created with an ACCESS specification that is appropriate to the type of note request to be processed (REQTYPE). If created with ACCESS=UPDATE, the connection can create, write, replace, read, or delete a note. If created with ACCESS=READ, the connection can read a note.

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

,INSTANCE#=instance#

,INSTANCE#=IGNORE

Use this optional input/output parameter to specify a variable for the instance number of the note. XCF sets the instance number to a value of its own choosing whenever a note is created, written, or replaced. The exploiter specifies the INSTANCE# keyword to indicate whether instance number comparisons are to be performed when reading, writing, replacing, or deleting a note (such comparisons are not done when creating a note). The instance number allows for a simple compare and swap like serialization that can be used to ensure that the expected copy of the note is being manipulated in the note pad. If the specified (nonzero) instance number equals the current instance number of the note, the request is processed. If not, the request is rejected.

If the creator of the note pad specified INSTCOMP=REQUIRED, a nonzero INSTANCE# must be specified when deleting, replacing, or writing an existing note.

If INSTANCE#=IGNORE is specified, or if the specified instance number equals zero, the request is processed without performing instance number comparisons. That is, the note will be read, written, replaced, or deleted without regard to its current instance number. If the specified instance number is nonzero, the read, write, replace, or delete of the note in the note pad will be performed only if the specified instance number equals the current instance number of the note.

For an INSTANCE# specification other than INSTANCE#=IGNORE, INSTANCE# could be an output variable or an input/output variable.

When creating a note, INSTANCE# is an output variable into which the instance number assigned to the note by XCF is to be stored. Zero might be stored if the request is not successful.
When writing, replacing, reading, or deleting a note, INSTANCE# is an input/output variable. A copy of the variable will be put in the IXCNOTE parameter list. If the note exists and the specified instance number is not zero, the service routine will use it for instance number comparisons. Upon return from the service routine, an instance number is stored in the indicated variable. Typically this value will be the current instance number of the note, regardless of whether the request was successfully processed or whether it failed due to an instance number mismatch. The original input value might be stored if the request is not successful for other reasons. In the case where the request fails due to an instance number mismatch, the output value would be the instance number to specify on a subsequent request in order to pass the instance number comparison check for the note (assuming the note was not updated by some other request in the meantime).

The default is IGNORE.

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

,KEEPNOTE=NO

,KEEPNOTE=YES

Use this optional parameter to indicate whether the note should be kept or deleted when the connection associated with the note is deleted. A note is associated with the connection if the connection created the note and it was never replaced, or if the connection was the last to replace the note (regardless of which connection might have created the note).

The KEEPNOTE specification is an attribute of the note that gets set whenever the note is created, written, or replaced. Thus the KEEPNOTE keyword must not be specified when reading or deleting a note since these operations cannot change the attribute.

Note that the KEEPNOTE attribute is subject to change whenever a note is replaced. Thus if the KEEPNOTE attribute is to be preserved, the connector must take care to code the appropriate KEEPNOTE specification each time the note is replaced. The default is KEEPNOTE=NO.

,KEEPNOTE=NO

The note is to be deleted when the associated connection is deleted.

,KEEPNOTE=YES

The note is to be kept when the associated connection is deleted.

The note will remain in the note pad until it is explicitly deleted by a subsequent IXCNOTE request, or until the note pad is deleted. Also note that the note will be eligible for deletion if KEEPNOTE=NO is specified (possibly as a default) when the note is subsequently replaced.

,REQTYPE=CREATE

,REQTYPE=WRITE

,REQTYPE=REPLACE

,REQTYPE=READ

,REQTYPE=DELETE

Use this required parameter to indicate the type of request to be processed for the indicated note.

,REQTYPE=CREATE

Create a new note in the note pad. The request is rejected if the named note already exists.

,REQTYPE=WRITE

If the named note does not already exist, create it. If the named note does exist, replace it.

,REQTYPE=REPLACE

Replace an existing note in the note pad. The request is rejected if the named note does not already exist.

,REQTYPE=READ

Read an existing note from the note pad. The request is rejected if the named note does not already exist.

,REQTYPE=DELETE

Delete an existing note from the note pad. The request is rejected if the named note does not already exist.

If a buffer area (BUFFER) is provided, a copy of the deleted note will be stored in the buffer if the request is successful.

If the creator of the note pad specified TRACKTAG=LIFETIME, deletion of the note might be deferred so that XCF can ensure that the maximum note tag value is preserved. In such cases the note is said to be pending delete. XCF will automatically complete deletion of the note asynchronously to the caller. Deferring the delete will not directly impact the delete request.

However, notes that are pending delete will continue to consume note pad resources until XCF finishes deleting the note. They could, for example, be included in counts of the number of notes that exist in the note pad. A subsequent request to process a given note can incur additional overhead if the named note is still pending delete when the request is made. In such cases, XCF might need to finish the pending delete before it can proceed with the request.

If the creator of the note pad specified TAGGING=USER and TRACKTAG=LIFETIME, be aware that the likelihood of the delete request being deferred increases if one assigns a new note tag that is greater than the current tag value for the note. Assigning a new tag value that would be the new maximum tag value of the note pad will certainly induce deferral. Consider using TAG=KEEP when deleting notes in order to minimize the potential for deferring of the request.

Note that return code 0 is provided regardless of whether the delete request is performed synchronously or deferred. The answer area (ANSAREA), if any, will indicate whether the delete request was deferred.

,NAME=name

Use this required input parameter to specify a variable containing the name of the note to be processed. The note name uniquely identifies a note in the note pad. There are no restrictions or requirements for the note name other than it be unique for each note in the note pad. Different note pads can use the same note names without conflict.

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

,TAG=tag

,TAG=KEEP

Usage of the TAG parameter depends on the value that is coded for the TAGGING parameter.

When TAGGING=USER is specified, use this optional input/output parameter to specify a variable into/from which the connector assigned note tag is stored/fetched.
- For a TAG specification other than TAG=KEEP
  When reading a note, TAG is an output variable into which the current tag of the note is to be stored. Zero might be stored if the request is not successful.
  
  When creating a note, TAG is an input/output variable. The tag value to be assigned to the note will be fetched from the indicated variable. If the request is rejected because the note already exists (IXCNOTERSNNOTEEXISTS), the current tag value for the note is stored. Otherwise the tag value stored will be the original input value, which for a successful request, would be the tag value that was set for the newly created note.
  
  When replacing, writing, or deleting a note, TAG is an input/output variable. For these requests, the tag value to be assigned to the note will be fetched from the indicated variable. If the request is rejected due to an instance number mismatch (IXCNOTERSNNOTEBADINSTANCE#), or because the specified tag value was less than the current tag value of the note (IXCNOTERSNNOTELOWTAG), the current tag value for the note is stored. Otherwise the tag value stored will be the original input value, which for a successful request, would be the tag value that was set for the note.
  
  When writing a note, the indicated TAG value will be assigned to the note regardless of whether the write request causes the note to be created or replaced.
  
  When deleting a note from a note pad for which the creator of the note pad specified TRACKTAG=LIFETIME, the delete request could be deferred if XCF needs to ensure that the maximum note tag value is preserved.
- For TAG=KEEP
  If TAG=KEEP is specified (or taken as a default), a tag value is neither fetched nor stored. When creating a note, the tag value assigned to the note will be zero. When reading, replacing, or deleting a note, the note tag will not be changed. When writing a note, the note tag will be set to zero if the note is created, but will not be changed if the note is replaced.
The default is KEEP.
When TAGGING=XCF is specified, an optional output parameter variable into which the XCF assigned tag value for the note is to be stored. If TAG is specified and the request is not successful, zero might be stored.

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

,TAGGING=USER

,TAGGING=XCF

Use this required parameter to indicate how the connector expects (or desires) tags to be processed.

Every note has a 16 byte note tag that is set (or preserved) whenever the note is manipulated. If TAGGING=USER was specified by the creator of the note pad, the tags are to be assigned by the connector. If TAGGING=XCF was specified by the creator of the note pad, the tags are assigned by XCF.

,TAGGING=USER: The connector claims to be responsible for assigning tags to the notes. The request is rejected if the creator of the note pad specified TAGGING=XCF.
For user assigned tags (TAGGING=USER) where the creator of the note pad specified TRACKTAG=CURRENT or TRACKTAG=LIFETIME, 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. 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.
,TAGGING=XCF: The connector claims that XCF is responsible for assigning tags to the notes. The request is rejected if the creator of the note pad specified TAGGING=USER.
XCF will assign a new tag when creating, replacing, or writing a note. XCF does not change the note tag when reading or deleting a note. XCF note tags are ever increasing.