When using selection criteria (CHOOSE=BYCRITERIA), your program must provide a storage area initialized with data describing which notes are to be selected (CRITERIA). The mappings for the selection criteria are defined in the IXCYNOTE macro. The selection criteria, which is mapped by ixcynote_tSelectionCriteria, contains a type field, a count field, and an array of records.

• The type field indicates the test to be used to determine whether a note is to be processed.
• The count field indicates the number of selection criteria records in the array. The count must be greater than or equal to one. The maximum count value depends on the level of the XCF Note Pad Services that is running on the system that processes the request. See Note pad related limits.
• Within each array entry, the 32 byte selection criteria record contains parameters appropriate for the indicated type of test. Thus the type field also determines how each of the selection criteria records is mapped. When the array contains more than one record, a given note is processed if it can pass the indicated test using the test parameters from any of the selection criteria records in the array. In other words, if each selection criteria record defines a set of notes, the union of those sets would be the set of notes selected for processing.

You can specify any one of the following types of selection criteria.

• Use Tag Range criteria to select any note whose tag value satisfies the inequality:
  • mintag ≤ tag value ≤ maxtag.
  The selection criteria record contains two 16 byte tag values, mintag and maxtag. mintag must be less than or equal to maxtag. You can use tag range selection criteria with any note pad, including note pads where user assigned tags can be arbitrary values. Tag range criteria are mapped by ixcynote_tSelectByTagRange.
• Use Tag Mask criteria to select any note whose tag value, when masked with a given bit mask, equals a given filter tag value. The selection criteria record contains two 16 byte values, tagmask and tagfilter. tagmask determines which bits in the note tag are to be compared to bits in the tagfilter. The note is selected if for every bit that is ON (B'1') in tagmask, both of the corresponding bits in the note tag and the tagfilter have the same value. If a mask bit is OFF (B'0'), the corresponding bits in the note tag and filter will not be compared. A tagmask where all the bits are OFF implies that all notes will be selected. A tagmask where all the bits are ON implies that any note whose tag value equals tagfilter will be selected. Tag mask criteria are mapped by ixcynote_tSelectByTagMask.
• Use Connection Identifier criteria to select notes associated either with a given note pad connection or with a given system. A note is associated with a given system if its associated connection was created on that system. The selection criteria record either contains a 12 byte connection identifier, or a 4 byte XCF System ID, or a 1 byte XCF system slot number. The selection criteria record must also indicate whether you want to include persistent notes, nonpersistent notes, or both. If neither persistent notes nor nonpersistent notes are indicated, the request is rejected. Recall that a nonpersistent note is automatically deleted by XCF when the associated connection terminates, but a persistent note is not. Connection identifier criteria are mapped by ixcynote_tSelectByConnectionID.

  The 12 byte connection identifier for a given connection is returned in the answer area (if any) provided when a connection is created. The connection identifier for the connection associated with a note is returned as part of the metadata for the note. Selecting notes associated with a given connection identifier might be useful, for example, when performing cleanup for the connection.

  The connection identifier criteria can also be used to select notes associated with a given system in the sysplex. The system can be identified either by its XCF System ID or by its XCF System Slot Number. If the XCF System ID is specified, only those notes associated with a connection that was created on that specific system instance will be selected. If the XCF System Slot Number is specified, the note is selected if its associated connection resided on some instance of a system that was assigned to the indicated slot number. Selecting notes associated with a given system might be useful, for example, when performing cleanup for a system.

The storage area containing the selection criteria should not be modified while in use by the XCF Note Pad Services. Changing the selection criteria while XCF is processing the request could produce inconsistent or unintended results.

If the specified selection criteria do not have a valid content, XCF rejects the multi-note request. If an answer area is provided, XCF stores detailed information describing the specific problem that was encountered. This information is mapped by ixcynote_tDetailsCriteria. Without this information, it will be difficult to determine why the selection criteria were deemed unsuitable. An answer area is required for a read notes request. An answer area is optional for a delete notes request, but desirable given the potential need for the detailed diagnostic data.