HP 3000 Manuals HP 3000 Manuals
FIND Performs multiple retrievals from a file or data set. Syntax FIND[(modifier)] file-name[,option-list]; FIND executes multiple retrievals from a file or data set and places retrieved data in the data register one entry at a time. It is usually used with a PERFORM= option to execute a block of statements that processes each record retrieved. When using the match register to select records, each record is placed in the data register before it is tested for selection against the match register. At the end of a FIND, the area of the data register specified in the LIST= option contains the last record retrieved. This may not be the last record selected by the match criteria.
NOTE After the first retrieval, Transact uses an asterisk (*) for the call list to optimize subsequent retrievals of that data set.
Statement Parts modifier To specify the type of access to the file or data set, choose one of the following modifiers: none Retrieves an entry from a master set based on the key value in the argument register. This option does not use the match register. CHAIN Retrieves entries from a KSAM file key or a detail chain. The entries must meet any match criteria set up in the match register in order to be selected. The contents of the key and argument registers specify the chain or KSAM key in which the retrieval is to occur. If no match criteria are specified, all entries on the chain are selected. Items used in the match criteria must be included in the LIST= option. CURRENT Retrieves the last entry that was accessed from the file or data set. DIRECT Retrieves the entry stored at a specified record number from an MPE or KSAM file or a data set. Before using this modifier, you must store the record number as a 32-bit integer in the item referenced by the RECNO= option. PRIMARY Retrieves the master set entry stored at the primary address of a synonym chain. The primary address is located through the key value contained in the argument register. RCHAIN Retrieves entries from a detail set in the same manner as the CHAIN option, only in reverse order. For a KSAM file, this operation is identical to CHAIN. RSERIAL Retrieves entries from a data set in the same manner as the SERIAL option, except in reverse order. If an equal match without match characters exists, Transact will convert an RSERIAL option to an RCHAIN option to improve the application's efficiency. For a KSAM or MPE file, this operation is identical to SERIAL. SERIAL Retrieves entries in serial mode from an MPE or KSAM file or a data set that meet any match criteria set up in the match register. If an equal match without match characters exists, Transact will convert an SERIAL option to an CHAIN option to improve the application's efficiency. If no match criteria are specified, all entries are selected. If match criteria are specified, the match items must be included in a LIST= option of the FIND statement. [REV BEG] __________________________________________________ NOTE FIND(SERIAL) or FIND(RSERIAL) with the PERFORM= option on a master set will skip entries if a delete is done within the perform, and a secondary entry migrates to the position of the deleted entry. (Transact/V Only.) __________________________________________________ [REV END] file-name The file or data set to be accessed by the retrieval operation. If the data set is not in the home base as defined in the SYSTEM statement, the base name must be specified in parentheses as follows: set-name(base-name) option-list One or more of the following options, separated by commas: ERROR=label Suppresses the default error [([item-name])] return Transact normally takes. Instead, the program branches to the statement identified by label, and the stack pointer for the list register is set to the data item item-name. Transact generates an error at execution time if the item cannot be found in the list register. The item-name must be a parent. If you do not specify an item-name, as in ERROR=label();, the list register is reset to empty. If you use an "*" instead of item-name, as in ERROR=label(*);, then the list register is not touched. For more information, see "Automatic Error Handling," in Chapter 7. LIST=(range-list) The list of items from the list register to be used for the FIND operation. For data sets, no child items can be specified in the range list. If the LIST= option is omitted with any modifier, all the items named in the list register are used. When the LIST= option is used, only the items specified in a LIST= option have their match conditions applied when the items are included in the match register. When the LIST= option is omitted, items which appear in the list register and the match register have their match conditions applied. Otherwise, the match conditions for an item are ignored. The match register can be used only with the modifiers CHAIN, RCHAIN, SERIAL, or RSERIAL. Each retrieved entry is placed in the area of the data register indicated by LIST= before any PERFORM= is executed, and then the retrieval is performed. For all options of range-list, the data items selected are the result of scanning the data items in the list register from top to bottom, where top is the last or most recent entry. (See Chapter 4 for more information on registers.) The LIST= option has a limit of 64 individually listed item names and a limit of 255 items specified by a range for a TurboIMAGE data set. All item names specified must be parent items. The options for range-list and the data items they cause FIND to access include the following: (item-name) A single data item. (item-nameX: All the item-nameY) data items in the range from item-nameX through item-nameY. In other words, the list register is scanned for the occurrence of item-nameY closest to the top of the list register. From that entry, the list register is scanned for item-nameX. All data items between are selected. An error is returned if item-nameX is between item-nameY and the top of the list register. Duplicate data items can be included or excluded from the range, depending on their position on the list register. For example, if range-list is A:D and the list register is as shown,then data items A, B, C, D, and D are selected. For database files, an error is returned if duplicate entries are selected. If item-nameX and item-nameY are marker items (see the DEFINE(ITEM) verb), and if there are no data items between the two on the list register, no database access is performed. (item-nameX:) All data items in the range from the last entry through the occurrence of item-nameX closest to the top of the list register. (:item-nameY) All data items in the range from the occurrence of item-nameY closest to the top through the bottom of the list register. (item-nameX, The data item-nameY, ... items are item-nameZ) selected from the list register. For databases, data items can be specified in any order. For KSAM and MPE files, data items must be specified in the order of their occurrence in the physical record. This order need not match the order of the data items on the list register. This option incurs some system overhead. (@) Specifies a range of all data items of file-name as defined in the data dictionary. The range-list is defined as item- name1:item-namen for the file. (#) Specifies an enumeration of all data items of file-name as defined in the data dictionary. The data items are specified in the order of their occurrence in the physical record or form as defined in the data dictionary. This order need not match the order of the data items in the list register. () A null data item list. That is, the entry or entries are read, but do not retrieve any data. LOCK Locks the specified file or database. The lock is active the whole time that the FIND executes. If LOCK is not specified and a TurboIMAGE data set is being accessed, no locking is done. For a KSAM or MPE file, if LOCK is not specified on FIND but is specified for the file in the SYSTEM statement, then the file is locked before each entry is retrieved, remains locked while the entry is processed by any PERFORM= statements, but is unlocked briefly before the next entry is retrieved. Including the LOCK option overrides SET(OPTION) NOLOCK for the execution of the FIND verb. For transaction locking, you can use the LOCK option on the LOGTRAN verb instead of the LOCK option on FIND if SET(OPTION) NOLOCK is specified. See "Database and File Locking" in Chapter 6 for more information on locking. NOMATCH Ignores any match criteria set up in the match register. NOMSG Suppresses the standard error message produced as a result of a file or database error. PERFORM=label Executes the code following the specified label for every entry retrieved by FIND. The entries can be optionally selected by MATCH criteria, in which case control is transferred only for the selected entries. This option allows operations to be performed on retrieved entries without the need to code loop-control logic. You can nest up to 10 PERFORM= options. RECNO=item-name The item-name can be [(subscript)] subscripted if an array item is being referenced. (See "Array Subscripting" in Chapter 2.) With the DIRECT modifier, you must define item-name to contain the 32-bit integer number (I(9,,4)) of the record to be retrieved. With other modifiers, Transact returns the record number of the retrieved item in item-name. SINGLE Retrieves only the first selected entry. SOPT Suppresses the optimization of database calls. SOPT forces Transact to re-establish its path, list, and record pointers before each record is used. Use SOPT if you are calling TurboIMAGE through the PROC or CALL verbs within a PERFORM option, or if you use the same FIND verb recursively for TurboIMAGE access. For an example of how SOPT is used, see "Examples" at the end of the FIND verb description. SORT=(item-name1[(ASC)] [,item-name2[(ASC)] [(DES)] [(DES)]]) FIND creates a work file of the records selected when the SORT option is specified. FIND sorts each data entry or record by item-name1 and, optionally, item-name2, and so forth. The key items in the SORT= option must also be included in the LIST= option (they can be child items); the items in the LIST= option are the record definition for the sort file. You can specify ascending (ASC) or descending (DES) sort order for each item. The default is ascending order. The FIND statement only creates and sorts if a PERFORM= option is also included, and it always performs the sort before processing the perform statements. The processing sequence for a sort is: * first, passes each record of data to the data register, * retrieves each selected record, * then writes each selected record to the sort file, * sorts the sort file by any specified items, and * passes each record one by one to the PERFORM= statements. The sort file size is determined by the SYSTEM statement. STATUS Suppresses the actions defined in Chapter 7 under "Automatic Error Handling." You may want to add status checking to your code if you use this option. When STATUS is specified, the effect of a FIND statement is described by the 32-bit integer value in the status register: Status Meaning Register Value 0 The FIND operation was successful. -1 A KSAM or MPE end-of-file condition occurred. >0 For a description of the condition that occurred, refer to database or MPE/KSAM file system error documentation that corresponds to the value. STATUS causes the following with FIND: * Normal multiple accesses become single. * The normal rewind done by the FIND is suppressed, so CLOSE should be used before FIND(SERIAL). * The normal find of the chain head is suppressed, so PATH should be used before FIND(CHAIN). See "Using the STATUS Option" in Chapter 7 for a discussion of how to use STATUS data. WORKFILE FIND creates a work file of the records selected when the WORKFILE option is specified. The FIND statement only creates the work file if a PERFORM option is also included. The processing sequence for a work file is: * first, passes each record of data to the data register, * evaluates each record selecting those that meet the MATCH criteria, * then writes each selected record to the work file, * passes each record one by one to the PERFORM statements. If the SORT and WORKFILE options are both used in a single verb, the work file is sorted according to the SORT option. Suppression of Optimization versus WORKFILE Transact's features resolve issues associated with retaining the correct location in a file or data set on multiple retrieval verbs (OUTPUT, FIND, DELETE, REPLACE) when the PERFORM procedure also operates on the same file or data set. These multiple retrieval verbs are optimized to avoid repositioning them before each record or entry is read. Automatic Optimization Transact tries to optimize the TurboIMAGE/KSAM interface for the set of multiple retrieval verbs. If Transact determines that the current multiple retrieval verb is the only verb accessing the file or data set within a program, optimization can occur. Automatic Suppression of Optimization Transact automatically suppresses the optimization of TurboIMAGE and KSAM calls when more than one verb accesses the same file or data set within a program. On multiple retrieval verbs, automatic suppression allows a different path for each access of the file or data set. This feature is always active. Automatic suppression of optimization occurs when: * both a FIND verb and its PERFORM option access data set X. * both a FIND verb and its PERFORM option access KSAM file Y. Suppression of Optimization Limitations There are situations where the automatic suppression of optimization is limited. It is either not invoked, or optimization is not sufficient to prevent multiple retrieval verbs from losing their location in the file or data set. These situations are described below. The SOPT Option Transact cannot detect the need for suppression of optimization in three specific situations. The SOPT option on multiple retrieval verbs is intended to handle these situations where suppression is needed but is not activated automatically. This can occur under the following situations: * The PERFORM option is a recursive call. * A PROC verb is used within the PERFORM option to call a procedure that accesses the same file or data set as the multiple retrieval verb. * A CALL verb is used within the PERFORM option to call another Transact system that accesses the same file or data set as the multiple retrieval verb. Corrupted Location in the File/Data Set Adding, deleting, updating, or replacing more than one record from within the PERFORM option procedure of a multiple retrieval verb can cause the multiple retrieval verb to lose its location if the current and next/previous logical records in the chain are deleted. Revisiting a Record When records are added, updated, or replaced from within the PERFORM procedure, these new or changed records can be retrieved a second time by the multiple retrieval verb. The specific conditions where an updated or added record can be retrieved a second time depend on the access mode of the multiple retrieval verb. For a multiple retrieval verb using the CHAIN or RCHAIN modifier where the key item is a sorted key, revisiting can occur: * When a PUT verb adds a record between the current record and the last record in the chain. * When a REPLACE verb updates any item, and the TurboIMAGE critical item update is OFF. * When an UPDATE verb updates a sort item or extended sort item, and the TurboIMAGE critical item update is ON. * When a REPLACE verb is used to replace a key value other than the key in the current path. * When multiple PUTs, UPDATEs, REPLACEs, or DELETEs are done within the PERFORM option procedure, and the last operation is not a delete of the current record for the multiple retrieval verb. For a multiple retrieval verb using the SERIAL or RSERIAL modifier, revisiting may occur: * When a PUT verb adds a record to the data set. * When a REPLACE verb update is used to replace a record in the data set.
NOTE With the CHAIN and RCHAIN access method, SORTED keys can cause revisiting of an entry. Transact multiple retrieval verbs retain the original end of chain location and stop processing after this record is read. Therefore, any records added to the chain after the original end of the chain record will not be processed.
Using the WORKFILE Option to Remedy Optimization Limitations The WORKFILE option can be used to remedy these optimization limitations, but other options can yield better performance. In situations where it is undesirable to have new or modified records reread by the multiple retrieval verb, you can use two tactics: * If the access is CHAIN or RCHAIN and the key item is a sorted key, the access direction can be changed to place added/updated records on a part of the chain you have already processed. If the access is SERIAL or RSERIAL, there is no way to control access to eliminate new or updated records. * For either SERIAL or CHAIN access, the MATCH register can be used to filter out records that have already been processed. If the current record is to be deleted by the PERFORM option, do this as the last operation against the data set. Using the WORKFILE Option If none of the above techniques allow the multiple retrieval verb to process the file or data set as desired, you can use the WORKFILE option. In terms of performance, this option is the least desirable of any of the methods mentioned above. This option should be used under the following specific circumstances: * When multiple PUTs, DELETEs, UPDATEs, or REPLACEs done within the PERFORM procedure of a multiple retrieval verb cause the multiple retrieval verb to lose its location. * When no other method for eliminating reprocessing records added to the file or data set via a REPLACE, UPDATE, or PUT can be found and reprocessing would damage the record. * When the PERFORM procedure alters the MATCH register in such a way that the MATCH conditions are no longer valid for the calling multiple retrieval verb. Examples In the following example of FIND, use of the STATUS option suppresses automatic error handling. The STATUS option enables you to perform a routine to control operations when an end of chain or broken chain occurs. SET(KEY) LIST(KEY-ITEM); PATH DETAIL-SET; GET-NEXT: FIND(CHAIN) DETAIL-SET,STATUS, PERFORM=PROCESS-AN-ENTRY; IF STATUS=18 THEN <<Broken chain >> DO PERFORM UNDO-TRANSACTION; EXIT; DOEND; IF STATUS=15 THEN <<End of chain >> END ELSE IF STATUS=0 THEN <<Successful operation >> GO TO GET-NEXT ELSE GO TO ERROR-CLEANUP; Instead of using the STATUS option, (such as using automatic error handling), you could set up a procedure to see if a specific entry exists in a chain. When you test the status register, you would get the number of records found. SET(KEY) LIST(KEY-ITEM); SET(MATCH) LIST(DATA-ITEM3); FIND(CHAIN) DETAIL-SET, LIST=(DATA-ITEM3),SINGLE; IF STATUS=0 <<then no entries found>> : When the STATUS option is not in effect for a FIND(CHAIN) or FIND(RCHAIN) operation on a detail set, the status register contains a -1 when the argument value is not in the master set. The following example uses a PERFORM= option to test data values in each retrieved entry. The routine TEST1 is performed on every record retrieved by FIND(CHAIN). FIND(CHAIN) DET, LIST=(A:H), PERFORM=TEST1; PERFORM GRAND-TOTAL; END; TEST1: IF (A) = "AUGUST" THEN PERFORM PRINT-IT; RETURN; PRINT-IT: LET (SUB) = (SUB) + (AMOUNT); . . DISPLAY ...; RETURN; The following example shows a method for traversing a pair of data sets organized in a tree structure. It uses a recursive routine; that is, the routine NEXT calls itself. Assume that the database TREE has the following structure:LIST PARENT: CHILD; DATA PARENT; MOVE (CHILD) = (PARENT); <<Initially parent and child must have >> <<value entered by user. >> PERFORM NEXT; DISPLAY "Tree Traversal Complete"; EXIT; NEXT: MOVE (PARENT) = (CHILD); <<Child item at this level becomes >> <<parent at next level. >> SET(KEY) LIST(PARENT); <<PARENT is key to search for next level. >> DISPLAY; FIND(CHAIN) TREE-DETAIL, <<Find next level in tree and retrieve >> LIST=(CHILD), <<child (future parent), then call this >> PERFORM=NEXT, <<routine again until there are no more >> SOPT; <<child chains. SOPT is needed to allow >> <<a different path at each level of the >> <<recursion. >> DISPLAY; RETURN; When you use a PERFORM= option in a FIND (or any other file access statement that allows this option), and execute other file access statements within the PERFORM= routine, Transact creates a chain of key/argument registers to keep track of which chain you are following. Each time the program returns from a PERFORM= routine, one set of key/argument values is removed. For example: LIST PROD-NUM: PROD-CODE: DESCRIPTION; DATA(KEY) PROD-NUM; <<Set up 1st key/argument pair. >> FIND(CHAIN) PROD-DETAIL, LIST=(PROD-NUM:DESCRIPTION), SORT=(PROD-NUM,PROD-CODE), PERFORM=TESTIT; EXIT; TESTIT: DISPLAY "In TESTIT routine"; DATA(KEY) PROD-NUM; <<Set up 2nd key/argument pair. >> FIND(CHAIN) PROD-DETAIL, LIST=(PROD-NUM:DESCRIPTION); DISPLAY; RETURN; The next example sorts the entries in data set ORDER-DET in primary sequence by ORD-NO and in secondary sequence by PROD-NO. As it sorts, it passes the sorted entries to the PERFORM= statements at the label DISPLAY-IT to be displayed in sorted order. SORT-FILE: LIST ORD-NO: PROD-NO: DESCRIPTION: QTY-ORD: SHIP-DATE: FIND(SERIAL) ORDER-DET, LIST=(ORD-NO:SHIP-DATE), SORT=(ORD-NO,PROD-NO), PERFORM=DISPLAY-IT; . . DISPLAY-IT: DISPLAY "Order List by Product Number", LINE=2: ORD-NO, NOHEAD, COL=5: PROD-NO, NOHEAD, COL=20: QTY-ORD, NOHEAD, COL=35: SHIP-DATE, NOHEAD, COL=50; This example shows the use of the WORKFILE option. All qualified records have their record number written to a work file. This file will be used to retrieve records instead of the TurboIMAGE chain. This example assumes that SHIP-DATE is a sort or search item within the TurboIMAGE data set ORDER-DET. READ-FILE: LIST ORD-NO: PROD-NO: DESCRIPTION: QTY-ORD: SHIP-DATE: FIND(CHAIN) ORDER-DET, LIST=(ORD-NO:SHIP-DATE), WORKFILE, PERFORM=INCDATE; . . INCDATE: LET (SHIP-DATE)=(SHIP-DATE)+3; UPDATE ORDER-DET, LIST=(ORD-NO:SHIP-DATE);
![[FFN5]](../../pic3k/M017291/FFN5.gif)
![[FFN6]](../../pic3k/M017291/FFN6.gif)