When a single note request is issued, the TAGGING keyword must be specified to confirm who has responsibility for setting the note tag value. The creator of the note pad determines whether the application or XCF is responsible for setting the tag values. If the TAGGING keyword does not match the protocol specified by the creator of the note pad, the note request is rejected.

In general, the TAG keyword identifies a storage area containing a tag value for the note. Depending on the request and its result, XCF might fetch a tag value from this storage area, or store a tag value in this storage area, or both. Upon return from the service routine, the IXCNOTE macro expansion unconditionally stores data in the designated storage area. Depending on the request result, this data might not be a tag value that is valid for use. Some programs might need to preserve and restore the original content of this storage area to ensure correct operation in cases where the data stored is not valid for use as a note tag.

Independently of the TAG keyword specification, note that the metadata stored in the answer area (if any) includes the tag value for the note.

XCF Note Tagging

If XCF is responsible for setting the tag values, the TAG keyword is optional. If specified, the storage area identified by the TAG keyword is always an output area. XCF stores the tag value of the indicated note in this storage area. For a read request or a delete request, the current tag value of the subject note is stored. For a create, write, or replace request, the new tag value set as the result of performing the operation is stored. If the request is rejected due to an instance number mismatch, the current tag value of the note is stored. The tag value is valid for use if the request is either successful or rejected due to an instance number mismatch. Otherwise the stored tag value is not valid for use (normally the stored value will be zero).

User Note Tagging

If the application is responsible for setting the tag values, the TAG keyword can indicate a storage area for the note tag value. Alternatively, TAG=KEEP can be specified.

If TAG=KEEP is specified, or taken as the default, a tag value is neither fetched from nor stored into local storage. Furthermore, the current tag value of the note is not changed as the result of processing the request. If the request causes a new note to be created, the tag value of the new note is set to zero.

If the TAG keyword identifies a storage area, XCF will either fetch a tag value from the indicated storage area, or store the tag value of the note in the indicated storage area, or both.

• For a read note request, the IXCNOTE macro expansion stores the tag value of the note in the designated storage area upon return from the XCF Note Pad Services. The tag value is valid for use if the read request is either successful or rejected due to an instance number mismatch. Otherwise the stored tag value is not valid for use (normally the stored value will be zero).
• For a create note request, the storage identified by the TAG keyword contains the tag value to be set for the newly created note. Upon return from the XCF Note Pad Services, the IXCNOTE macro expansion stores into the designated storage area. In cases where the note exists, regardless of whether it was newly created or already existed, the value stored is the current tag value of the note. Thus the stored tag value is valid for use if the create request is either successful or rejected because the note already exists. Otherwise the stored tag value is not valid for use (normally the stored value will be the same as the original value).
• For a write, replace, or delete note request, the storage identified by the TAG keyword contains the new tag value to be set for the subject note. If the note exists and the request is otherwise successful, the note tag is set to the indicated value. If the note does not exist, a write request causes the note to be created with the indicated tag value. For replace or delete, the request is rejected if the note does not exist.

  If the creator of the note pad indicated that XCF needs to track the maximum tag value assigned to the notes in the note pad, the new tag value must be greater than or equal to the current tag value of the note. If the note exists and this condition is not satisfied, the request is rejected because the specified tag value is too low.

  Upon return from the XCF Note Pad Services, the IXCNOTE macro expansion stores into the designated storage area. If the request is successful, the stored tag value is valid for use and equals the designated new tag value that was assigned to the note (that is, it equals the original input tag value). If the request is rejected due to an instance number mismatch or because the tag value is too low, the stored tag value is valid for use and equals the current tag value of the note. Otherwise the stored tag value is not valid for use (normally the stored value will be the same as the original value).