ISAM'PUSH #channel
ISAM'POP #channel
ISAM'PUSH and ISAM'POP are extensions only available in A-Shell (and which require the COMPIL /X:2 switch). They allow you to save, and later restore, the current index cursor context. This is particularly handy when, while traversing an index which includes duplicate keys, you need to make a detour involving some other index operations on the same file, before continuing from where you were. Without these operations, you would instead have to manually reposition yourself within the index, which, if duplicates are involved, would require scanning through the duplicates until you hit the record where you were, based on the record number. (There is no other way to go directly to a particular key among a group of duplicate keys.)
Specifically, the context attributes that are saved and restored are:
| • | The index number (if there are multiple indexes for the file) |
| • | The cursor position within the index |
| • | The value of the recnovar variable. |
Note that ISAM'PUSH and ISAM'POP do not affect record locks. Thus, if you lock a record before using ISAM'PUSH, it remains locked, and will still be locked when you use ISAM'POP. However, the contents of the record data variable (aka varlist) is not saved or restored, so you must take care to either save your own copy, or to make sure that your record data variable contains the desired contents before you update the record.
Note also that ISAM'PUSH uses the current record number according to the record number variable in the open statement, as opposed to the one last saved inside the ISAM library. The problem with the superceded method was if the ISAM'PUSH did not immediately follow another operation on the same file, some intervening ISAM operations to other files could disrupt the state information within the ISAM library, causing the ISAM'PUSH to not push the proper location.
Example:
GET'NEXT'LOCKED #AROPEN'CH, WAIT'RECORD, AROPEN'REC
SAVE'AROPEN'REC = AROPEN'REC ! save copy of locked rec
ISAM'PUSH #AROPEN'CH
CALL SCAN'FOR'OTHER'AROPEN'RECS ! (unknown processing)
ISAM'POP #AROPEN'CH ! restore our index context
AROPEN'REC = SAVE'AROPEN'REC ! restore our saved data rec
AROPEN'UPDATED = 1 ! change some data
UPDATE'RECORD #AROPEN'CH, AROPEN'REC ! update the rec
RELEASE'RECORD #AROPEN'CH ! and release the lock
