TRANSFER Reference Manual

SCAN-FOLDER-BY-KEY
TISERV UOW Descriptions
069139, Update 1 to 40969 Tandem Computers Incorporated 2–475
NUM-RETURNED
is the number of items retrieved from the folder. The number of items retrieved
might be less than the number of items requested (NUM-REQUESTED) because of
one of the following reasons:
The folder contains fewer items in the range specified by the passed starting
key information.
The folder contains fewer items in the subset specified for generic matching.
If the number of items retrieved is less than the number of items requested, the
warning W-EOF is returned in the RETN-CODE field.
ITEMS-RETURNED
is an array containing the item ID (ITEM-ID), item type (ITEM-TYPE), ordering
key length (ORDERING-KEY-LEN), and ordering key (ORDERING-KEY) of the
items returned. The size of this array must be consistent with the number of items
requested, as defined in NUM-REQUESTED. To refer to an item produced by a
previous UOW within the same IPC, you can replace ITEM-ID with ITEM-
HANDLE, which is defined in the “Commonly Used Fields” subsection of this
manual.
UNSAVE-TIME
is the time when the item is automatically removed from the folder. The date and
time returned is in absolute format. If the item has no unsave date and time, all
fields of UNSAVE-TIME are set to 0.
SCAN-FOLDER-BY-KEY Operation
SCAN-FOLDER-BY-KEY retrieves the item IDs, item types, unsave time, and the
corresponding ordering key and key length of the items in the range denoted by
STARTING-KEY, STARTING-DUPLICATE, and NUM-REQUESTED. These values
are placed in the array named ITEMS-RETURNED. Items are returned in application
ordering key sequence.
This UOW is restricted to folders with APPLIC-DEFINED ordering disciplines. If this
UOW is attempted with a folder that has an ordering discipline other than APPLIC-
DEFINED, the error E-INCORRECT-FLD-ORDER is returned.
The OPTIONS structure allows you to selectively retrieve only items of a particular
type. The structure also allows you to retrieve either the first matching item or the
item immediately following.
The SCAN-FOLDER-BY-KEY UOW allows you to use the response definition to build
the next request. VALUE clauses are appropriately set to allow this usage. You must
set NUM-RETURNED to 0 when the request is issued; otherwise, the request is the
wrong length. Note that the actual value of NUM-RETURNED does not matter; the
length of the UOW sent, however, must be correct.