,BUFFER=buffer

One of a set of mutually exclusive keywords indicating the buffer into which the content of the selected notes is to be stored. Only complete notes will be stored in the buffer. When the buffer is filled, the read request returns. In the answer area, the data record for each note (IXCYNOTE_TNOTEDATA) will indicate whether the content of the note was stored in the BUFFER area, and if so, where.

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 the content of the notes are not to be stored. Information about the notes will be stored in the answer area (ANSAREA).

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

,CHOOSE=ALL

All notes in the note pad are to be selected.

,CHOOSE=BYCRITERIA

The notes that meet the indicated selection criteria are to be processed. Various selection criteria can be specified. For example, one can select notes whose tag values are within a particular range.

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 request to be processed (REQTYPE). If created with ACCESS=UPDATE, the connection can read or delete notes. If created with ACCESS=READ, the connection can read notes.

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

The storage containing the CRITERIA 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.

The default is NONE.

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

,REQTYPE=READ

Read one or more notes from the note pad. Metadata for each of the selected notes will be stored in the answer area (ANSAREA). The note content will be stored in the buffer area (BUFFER). An answer area is required. A buffer area is optional. A successful read request returns to the caller when all of the selected notes have been read, or when the storage areas provided for output are filled with as many notes as will fit, whichever comes first.

If a read request completes prematurely because one or both of the provided storage areas are full, the service routine provides a warning return and reason code (IXCNOTERSNMORENOTES). If so, a nonzero resume token (RESUMETOKEN) is also stored. After processing the notes that were read, one can continue reading the remaining notes by reissuing the same request, passing the aforementioned nonzero resume token via the RESUMETOKEN keyword to continue reading from where the prior read request left off. When all of the notes have been read, the service routine sets return code zero. Note that the number of notes returned in this case could be zero. Also note that a nonzero RESUMETOKEN is returned for the return code zero case as well. One could for example, later issue a new read notes request with this token to read subsequently created notes.

XCF inspects the notes in the order in which they were originally created. As a result, be aware of the following:

• If an existing note is replaced one or more times while a read notes request is being processed, at most one of the instances will be returned by the request. A note is created by a create note request, or by a write request when the note does not exist. Replacing the content of an existing note does not cause the note to be created. Thus after a read operation inspects a note, that note will not be inspected again by the ongoing read operation or any subsequent resume of the read request, regardless of how many times the note is replaced.
• If a note is created while a read notes request is being processed, the newly created note might not be returned by the ongoing read operation. In some cases, the timing could be such that a note would not be returned even when the read request is resumed using the RESUMETOKEN returned by the read request that was active when the note was created.
• If a note is deleted and created anew while a read notes request is being processed, there is the potential for the note to be reported multiple times by the read request. For example, the read request could fetch a given note and store it in the user ANSAREA. Meanwhile, some other process could delete the note and create a new instance of the same note (one with the same name). That new instance of the note could be visible to the ongoing read operation, or to a subsequent resume of the read request, and so could be returned again.

An answer area (ANSAREA) must be provided when reading notes. For each of the selected notes, a data record containing information about the note (such as its name and tag) will be stored in the answer area. The data record is mapped by IXCYNOTE_TNOTEDATA.

The answer area must be large enough to allow information for at least one note to be returned. If the answer area is not large enough to allow information for the required minimum number of notes to be returned, the service routine rejects the request (IXCNOTERSNANSLENMORE).

The content of the notes will be returned in the indicated buffer area (BUFFER). The buffer area is optional. If a buffer is not provided, the content of the notes will not be read. If a buffer area is provided, the data record stored in the answer area for each note will indicate the location within the buffer area where the content of the corresponding note was stored (if any).

The BUFFER area must be large enough to allow the content of at least one note to be stored. If the BUFFER area is not large enough for the minimum required number of notes, the service routine rejects the request (IXCNOTERSNBUFLENBADVAL).

,REQTYPE=DELETE

Delete the indicated set of notes from the note pad. The request will not return until all of the selected notes are processed.

If provided, the answer area will indicate how many notes were deleted. No note information is stored for any of the deleted notes.

Note that the note pad itself persists until it is deleted. Deleting all the notes in the note pad does not delete the note pad.

When specifying a nonzero resume token, only use the value that was returned by the previous invocation of a read request initiated by the subject connection for the subject note pad. Otherwise XCF might reject the request with an indication that the resume token is not valid (IXCNOTERSNRESUMETOKENBADVAL), or if the request is in fact processed, the request might not return the expected set of notes.

When passing a nonzero RESUMETOKEN, the caller should in general also pass the same selection criteria as was passed when the request was first initiated, and continue doing so for each iteration of the read request until it is complete. Otherwise the request will likely not return the intended set of notes. For example, the same note could be read twice or a note that meets the selection criteria might not be read at all.

 Set ResumeToken to zero
 Do until all notes have been read (rc=0)
   IXCNOTE REQUEST=NOTES,REQTYPE=READ,
           CHOOSE=ALL,
           RESUMETOKEN=ResumeToken,
           CONNECTION=connect_token,
           ANSAREA=ansarea,ANSLEN=anslen,
           BUFFER=buffer,BUFLEN=buflen,
           RETCODE=rc,RSNCODE=rsn
   If rc/rsn indicate error
     Deal with error
     Terminate loop
   Else (rc=0 or rc=4)
     Process returned notes (if any)
 End Do 

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