Issue a delete note request to delete an existing note from the note pad. The request is rejected if the named note does not exist.

If the delete note request is successful, the note is deleted and the count of notes in the note pad is decremented by one. However, if the creator of the note pad requested lifetime tracking of the maximum tag values (TRACKTAG=LIFETIME), the note might be logically deleted. The delete note request still completes with a return code indicating success, but the physical deletion of the note and decrement of the note count could be deferred. See Lifetime tracking (TRACKTAG=LIFETIME) for more information about how the physical existence of a logically deleted note might impact your program.

The delete request is processed as a "read and delete" if either an answer area or a buffer area is provided.

If a suitable answer area is provided, a copy of the note metadata is stored in the answer area. The note metadata includes the note tag, instance number, connection identifier, persistence attribute, and note size.

If a suitable buffer area is provided, a copy of the note content is placed in the buffer. The buffer area must be large enough to hold the content of the largest note supported by the note pad. This buffer length requirement must be met even if the note to be deleted is known to be smaller than the maximum note size.

If the delete request is rejected due to an instance number mismatch, the IXCNOTE macro expansion stores the current value of the instance number for the note in the storage area identified by the INSTANCE# keyword, and stores the current tag value of the note in the storage area identified by the TAG keyword. However, the current content of the note is not returned. Depending on the needs of your application, your program might need to take an action to determine whether this new instance of the note needs to be deleted. For example you might issue a read request to get the current note content, inspect the note to see if it needs to be deleted, and then reissue the delete request as appropriate. If instead your program were to immediately reissue the delete request without refreshing the local copy of the note content, it might well subvert the data integrity protection that the instance number comparison was intended to provide. Reissuing the delete request without first inspecting the note content might be reasonable for some applications if, for example, the tag value contained control data that could be used to determine whether the note was still eligible for deletion. If a read operation is issued to refresh the local copy of the note, the instance number returned by the read request should be used when reissuing the delete request, as opposed to the instance number stored by the IXCNOTE macro expansion as the result of the instance number mismatch (because the note might have been updated yet again before the read is processed).

If the delete request is rejected because the proposed new tag value is less than the current tag value of the note, the IXCNOTE macro expansion stores the current tag value of the note in the storage area designated by the TAG keyword, and stores the current instance number for the note in the storage area identified by the INSTANCE# keyword.

In cases where the request has both an instance number mismatch and a low tag value, XCF reports the failure as an instance number mismatch.