Home

ISAM PLUS User`s Manual

1. IF STATUS VAR lt HE amp PRI ERROR PREFIX amp FILE NUMBER INDEXED STATS FORM FAILURE amp STATUS STATUS VAR IF STAT STATS MAP lt gt STAD STATS MAP amp PRI ERROR PREFIX INDEXED STATS RESULTS MISMATCH DEVRAD50 STAD DATA DEVICE EMP INT DEVRAD50 40 DEVICES RAD50CHAR DEVRAD50 TEMP 40 1 1 DEVRAD50 TEMP EMP INT DEVRAD50 40 DEVICES RAD50CHAR DEVRAD50 TEMP 40 1 1 DEVICES EMP INT DEVRAD50 40 DEVICES RAD50OCHAR TEMP 1 1 DEVICES STRS STAD DATA UNIT PRINT Data Device DEVICES PRINT Record size STAD RECORD SIZE IF RECORD SIZE lt gt STAD RECORD SIZE THEN amp PRI ERROR PREFIX RECORD SIZE MISMATCH PRINT Free records STAD FREE RECORDS IF UMBER RECORDS lt gt STAD FREE RECORDS THEN amp PRI ERROR PREFIX RECORD COUNT MISMATCH PRINT Free index blocks STAD FREE INDEX PRINT Total index blocks STAD TOTAL INDE PRINT T
2. IF SKEY11 CHNG lt gt KEYO1 CHNG THEN amp PRINT ERROR PREFIX KEY CHANGE FLAG MISMATCH PRINT Key size SKEY11 SIZE IF SKEY11 SIZE lt gt KEYO1 SIZE HEN amp PRI ERROR PREFIX KEY SIZE ISMATCH PRINT Verifying Secondary Key PRINT Key index SKEY12 INDEX IF SKEY12 INDEX lt gt 1 THEN amp PRI ERROR PREFIX INDEX MISMATCH PRINT Key type KEY TYPE SKEY12 TYPE IF SKEY12 TYPE lt gt KEYO2 TYPE THEN amp PRI ERROR PREFIX KEY TYPE ISMATCH PRINT Key name SKEY12 NAME IF SKEY12 NULL lt gt 0 THEN amp PRI ERROR PREFIX KEY NAME NULL NOT NULL PRINT Key dup flag SKEY12 DUP IF SKEY12 DUP lt gt KEYO2 DUP THEN amp PRI ERROR PREFIX KEY DUP FLAG MISMATCH PRINT Key change flag SKEY12 CHNG IF SKEY12 CHNG lt gt KEYO2 CHNG THEN amp PRI ERROR PREFIX KEY CHANGE FLAG MISMATCH PRINT Key position segment 1 SKEY12 POS11 IF SKEY12 POS11 lt gt KEYO2 POSO1 THEN amp PRI ERROR PREFIX KEY POSITION MISMATCH PRINT Key size segment 1 SKEY12 SIZE11 IF SKEY12 SIZE lt gt KEYO2 SIZE HEN amp PRI ERROR PREFIX KEY SIZE MISMATCH PRINT Key position segment 2 SKEY12 POS12 IF SKEY12 POS12 lt gt KEYO2 POSO2 THEN amp PRI ERROR PREFIX KEY POSITION MISMATCH PRINT Key size segment 2 SKEY
3. DEVICES RADSOCHAR DEVRAD50 TEMP 40 1 1 DEVICES TEMP INT DEVRAD50 40 DEVICES RAD5O0CHAR TEMP 1 1 DEVICES RS STAT DATA UNIT PRINT Data Device DEVICES Tg PRINT Record size STAT RECORD SIZE IF RECORD SIZE lt gt STAT RECORD SIZE THEN amp PRI ERROR PREFIX RECORD SIZE MISMATCH PRINT Free records STAT FREE RECORDS IF UMBER RECORDS lt gt STAT FREE RECORDS THEN amp PRINT ERROR PREFIX RECORD COUNT MISMATCH PRINT Free index blocks STAT FREE INDEX PRINT Total index blocks STAT TOTAL INDE PRINT Total records STAT TOTAL RECORDS PRINT Total loaded records STAT TOTAL LOADE PRINT in free index blocks STAT MIN FREE IDX PRINT Extra index block STAT EXTRA PERCENT IF EXTRA PERCENT lt gt STAT EXTRA PERCENT THEN PRINT ERROR PREFIX EXTRA PERCENT ISMATCH PRINT Creation date STAT CREATE MONTH PRINT STAT CREATE DAY PRINT STAT CREATE YEAR PRINT DOW STAT CREATE DOW 1 PRINT Rebuild date STAT REBUILD MONTH PRINT STAT REBUILD DAY PRINT STAT REBUILD YEAR PRINT DOW STAT REBUILD DOW 1 SYSTEM BINDATE DATE IF SYSTEM DATE lt gt STAT CREATE DATE THE amp PRI ERROR PREFIX DATE IS INCORRECT PRINT Verifying Primary Key PRINT Key index SKEYOL INDEX IF SKEYO1L INDEX lt gt 0 THE amp PRI ERROR PREFIX
4. E SYSTEM BINDATE pope Tia E HWM 0 CHR 7 ISAM PLUS file Allocation map template MAP 1 P2 P2 P2 P2 P2 P2 P2 AP 3 AP 3 AP 3 blank filled P3 P3 P3 P3 P3 PPP PP PP N ES D PP Pupp Yr YY P3 P3 P3 qd P3 P3 P3 P3 P3 BS P3 P3 P3 P3 MAP 2 blank fill o D Dpp ppp D ISAM PLUS User s Manual Rev 02 2I 0 Wp OO Ae amp Se KKKOKKKKK TO OGOGO 44 DHAVHADYD AAKRONKAAN AE Aomowmgna oO 0 z 6 2 B 2 02 4 0 l 2 P ROR OFFSET B 2 1 B 4 1000 1 1 E B 2 78 T B 2 200 i 1 1 1 i B 1 75 13 B 1 pe B 1 1 10 Ji 1 I Secondary O Primary K File Creation amp Verification Test for ISAM PLUS testing EFGHIJKLMNOPORSTUVWXYZS 70123456789 ap for ISAM PLUS file creation Offset if error in allocate aximum number of records Record size in bytes 4 64k Extra idx blks to alloc 0 900 KSMUTL loading factor 50 100 Reserved for future expansion Primary key definition Type of key Alphanumeric type Reserved for future expansion ey 0 Name of key 20 char Null terminator for key name Duplicate keys permitted flag 0 1 Key change permitted flag 0 1
5. GOSUB YESNO IF ANSWER R TAT O A ECNO lt gt R D U D B Scan greater record in the PRINT Scan records in K instead of yn to record found by KEYNAM to index 0 main index Save record number amp EYNAME 1 E IDX 1 KEYNAM TH EN G ET 1 ISAM K first GET 0 1 EL DIS S PLAY E ET ETU A SWE A S E B T B KI eG pb SWE EXT ND RI RN ES ER INQ EC FOUND O wy 1 LABI SCAN ira Ee 0 ECNO T ISAM NF THE PRINT T HEN GET NEXT 1 LABEL T GOTO INQ NOT FOUND Examine next GOTO INQ NOT FOUND No KEYNAME IDX 1 keys greater or Get EST SW Sh Al HHS SW RN R R lt gt F ja Y N nn UCS ANSWER syn AND ANSWER lt gt qual found Y N input CR Y ANSWER THEN ANSWE R y N E IDX 1 order EY 0 gt LAST NAM amp index is amp E LAB GOTO INQ POS THEN GOTO YESNO ISAM PLUS User s Manual Rev 02 Sample BASIC Programs Using LABEL DISPLAY STRING LAST NAME Ww ISAM PLUS
6. ERROR PROCESSING This section discusses the AlphaBASIC methods for reporting errors from ISAM PLUS and FILSER the AMOS File Service System and for locating line numbers in the application program where errors occur The reporting mechanisms should help you write routines for handling errors terminating abnormal conditions or re trying an operation Error Codes and Status Values If the condition code returned by ISAM PLUS indicates a serious error occurred during the function call the AlphaBASIC interface traps the error code and sets the variable you specified in the OPEN statement You should check the returned value in this variable and take appropriate action The list below gives the decimal form of the ISAM PLUS error codes ISAM PLUS User s Manual Rev 02 Page 8 12 Chapter Eight Decimal Code Meaning Incompatible ISAM file ISAMP SYS not found Warning free index blocks is less than minimum requirement Data file full Index file full Cannot change key Index structure is smashed Duplicate key Can t add not enough free index blocks Invalid number Maximum extra percentage exceeded Too many index blocks Invalid record size Too many concatenated keys Primary key information must be entered Maximum key size exceeded Invalid key type Maximum binary type size exceeded Key range is outside record Overlap keys must be alphanumeric type Too many data file blocks Exceeds maximum number of 2 key
7. IF ERR 0 lt gt 17 THE ON ERROR GOTO 0 RESUME RESUME ALLOCATE FILE ALLOCATE FILE ERROR GOTO ERROR T RINT Allocating new Otherwise RAP2 file FILENAME 1 RIN RINT Allocation com GOTO START uu P UO LLOCATE INDEXED FILENAME ISAM ALLOCATE MAP plete ISAM PLUS User s Manual Rev 02 Page B 11 Page B 12 Appendix B ERROR TRAP2 PRINT ERRORBELL S ERROR DURING A FILE ALLOCATION PRINT FILE ERROR ERF 1 PRINT STATUS VAR FSTATUS PRINT ERROR OFFSET ISAM ERROR OFFSET ON ERROR GOTO f1 ISAM PLUS User s Manual Rev 02 Appendix C Conversion Hints for ISAM Users This appendix contains information for ISAM users who want to convert their AlphaBASIC AlphaC or assembly language programs that make use of ISAM to ISAM PLUS format ISAM files must first be converted to ISAM PLUS format before they can be accessed under the new system ISAM files do not run under the ISAM PLUS system and vice versa The new ISAM PLUS file has a completely different structure Please follow the conversion steps given in the next section CONVERTING ISAM FILES TO ISAM PLUS FORMAT 1 Dump your ISAM file into a sequential file using ISMDMP 2 Create anew ISAM PLUS file using ISMUTL as described in this book 3 Load the newly c
8. B 1 B 1 B 6 C 1 C 1 ISAM PLUS User s Manual Rev 02 Chapter 1 About This Book This book is aimed at the experienced assembly language or AlphaBASIC programmer who wants to use the Alpha Micro ISAM PLUS system within programs If you are not familiar with Alpha Micro assembly language or AlphaBASIC programming see the documents listed in the Related Documentation section below for reference material For information on using ISAM PLUS from AlphaC programs see your AlphaC User s Manual ISAM not ISAM PLUS refer to the ISAM System User s Guide DWM 00100 06 v This book discusses the use of ISAM PLUS for AMOS versions 2 3A and later If you are using The purpose of this book is to e Introduce you to ISAM PLUS e Discuss how to create and access ISAM PLUS files using the various programs of the ISAM PLUS system e Show you how to write programs in assembly language AlphaBASIC or AlphaBASIC PLUS to locate update add and delete data in ISAM PLUS files To that end this book is organized into the following sections Chapter 2 Chapter 3 Chapter 4 Chapter 5 Chapter 6 Chapter 7 Chapter 8 Chapter 9 Appendix A Appendix B Introduces the concept of an indexed sequential access method Discusses Alpha Micro s ISAM PLUS system components and features It provides information about keys multi level indexing index blocks index and data file maintenance and file locking Shows you how to use the
9. NEW FIRST NAME INPUT LINE Enter Address NEW ADDRESS INPUT LINE Enter City NEW CITY INPUT LINE Enter State 2 letters NEW STATE INPUT LINE Enter Zip Code NEW ZIP INPUT LINE Enter Status NEW STATUS GOSUB UPPERCASE Check for duplicate entry GET 1 ISAM KEY 0 NEW LAST NAME LABEL DUP FOUND 0 IF FSTATUS ISAM NEF THEN GOTO PUT REC DUP SCAN F LAST NAME lt gt NEW LAST NAME GOTO PUT REC F FIRST NAME lt gt EW FIRST NAME GOTO DUP SCAN NEXT OSUB LABEL DISPLAY UP FOUND 1 DUP SCAN NEXT I I PRINT Name duplication G D GET NEXT 1 LABEL IF FSTATUS lt gt ISAM NF THEN GOTO DUP SCAN PUT REC IF DUP FOUND THEN QUEST Name duplicated in list write anyway amp GOSUB YESNO IF ANSWER N THEN RETURN CREATE RECORD 1 NEW LABEL RETUR DELETE REC Delete Record from file PUT LINE Enter Last Name NEW LAST NAME I GOSUB UPPERCASE REC FOUND 0 Check for duplicate entry GET LOCKED 1 ISAM KEY 0 NEW LAST NAME LABEL ISAM PLUS User s Manual Rev 02 Page B 10 EL SC INQUIR A I R I G Q G I R G G F FSTATUS EC FOU D ISAM NE 1 THEN GOTO DEL NOT FOUND Appendix B NAME B LABEL DISPLAY Last name matc B YES SWER lt gt N E
10. terminal Al gt Size of field Size 2 bytes Repeat 0 to Position of field 2 bytes m times Null terminator 2 bytes If the file was flagged with IS NOX when set up with BSET the file is opened non exclusively BADDX Add Index Blocks INPUT AO A2 D1 OUTPUT DO CC ISMUTL impure area pointer Pointer to device name for new IDX file in ASCIZ format 0 if none Number of blocks to add Condition code Z set if success BSTAT Get Statistical Information INPUT AO ISMUTL impure area pointer Pointer to statistic area A2 buffer size in bytes OUTPUT A2 Pointer to statistic area Condition code Z set if success ISAM PLUS User s Manual Rev 02 Assembly Language Programming Interface to ISMUTL Output register A2 points to the data structure that contains A2 gt Data device unit number Record size Free record count Free index blocks count Total index blocks allocated Records allocated Records loaded Minimum empty index blocks Extra index block percentage Date created Number of 2nd dir Number of active 2nd dir Date rebuilt Reserved Key specifier number Type of key Reserved Key name description Null terminator Allow duplicate keys flag May change key flag Size of key Position of key Null terminator If type of key K CONC Key specifier number Type of key Reserved Key name description Null
11. 2 bytes null Source address Destination address Move word by word Repeat till null Return to caller ISAM PLUS User s Manual Rev 02 Page 5 12 Chapter Five NOCOMM TYPECR lt Error no filename entered gt EXIT CUSNUM ASCII Customer number 20 bytes of characters BYTE 0 0 2 bytes null CUSNAM ASCII Customer name s BYTE 0 0 7 SPACES ASCII All spaces BYTE 0 0 i EVE ISMUTL RAD50 ISMUTLLIT ISMUTL LIT in RAD50 EVE END ISAM PLUS User s Manual Rev 02 Chapter 6 Definitions of Standard Update Operations This chapter defines the ISAM PLUS update operations so everyone interfacing to ISAM PLUS from different languages and database applications has a standard way of performing these operations on records For the assembly language calls and AlphaBASIC statements which implement these operations see Chapters 7 and 8 ROOT MEANINGS ISAM PLUS lets you add and remove records from the file and examine and modify these records When reading a file a program requests records from the file When writing to a file a program builds records and passes them to ISAM PLUS for storage in the file When adding or removing a record ISAM PLUS maintains all the indices to the data file Here is a list of the root meanings of the ISAM PLUS calls detailed in the next section e GET Read a record from the file into a buffer For random access specify the
12. ADDIDX Add Extra Index Blocks ADDIDxX lets you add extra index blocks ADDIDX is very convenient to use and doesn t take much time to execute It copies the old IDX file to a new IDX file In the process it adds index blocks and updates the freelist pointer and other fields Here are the questions and answers Enter device name for new IDX file Enter the new device don t forget the colon if you want the new IDX file to reside on a different device Otherwise just press RETURN Enter number of index blocks to add Enter any positive integer number After you have entered the information it needs ADDIDX rotates the to indicate that it is processing the call unless you used NOP If there is an error your old IDX file is still there ISMUTL renames it to SDX Rename the SDX file to IDX and repeat the ADDIDX procedure after you have corrected the problem New IDX file created ISMUTL verifies the new IDX file was created without error DESCRP Change Key Description The DESCRP command lets you change or display descriptive information about a particular key These are the questions and suggested responses Enter key number Enter the number of the key directory whose key description you want to display or change Type 0 for the primary key directory Current key description ISMUTL displays the current key description for the key directory ISAM PLUS User s Manual Rev 02 Page 4
13. BSET Set up File 5 2 BCRET Create an ISAM PLUS File 5 2 BLOAD Load Records 5 4 BADD2 Add Secondary Key Directory 5 4 BDEL2 Delete Existing Secondary Key Directory 5 5 BCHNG Change IDA File Device Name 5 5 BDUMP Dump ISAM PLUS File 5 6 BADDX Add Index Blocks 5 6 BSTAT Get Statistical Information 5 6 BERR Display ISAM PLUS Related Error Message 5 8 REBLD Rebuild Primary and Secondary Keys 5 8 BFIN Finalize ISMUTL 5 8 SAMPLE ASSEMBLY LANGUAGE PROGRAM 5 8 CHAPTER 6 DEFINITIONS OF STANDARD UPDATE OPERATIONS 6 1 ROOT MEANINGS 6 1 DETAILED DEFINITIONS 6 1 Open ISAM PLUS File for Processing 6 1 Get Record Specified by a Key 6 2 Get Next Previous Record 6 3 Find Key Specified by a Key 6 3 Find Next Previous Key 6 3 Update Existing Record 6 4 Add a New Record to a File 6 4 ISAM PLUS User s Manual Rev 02 Table of Contents Page iii Delete Existing Record 6 4 Unlock Record 6 4 Get Statistical Information 6 4 Close ISAM PLUS File 6 4 CHAPTER 7 THE ISAMP SYS INTERFACE 7 1 PREPARATIONS 7 1 THE SPECIFICATIONS 7 1 SINT Initialize ISAMP SYS 7 1 ISOPN Open File for Processing 7 2 GTREC Get a Record Specified by a Key 7 3 GTNXT Get Next Previous Record 7 3 FDKEY Find Key Specified by a Key 7 4 FDNXT Find Next Previous Key 7 5 UPREC Update Existing Record 7 5 PTREC Add a New Record to File 7 5 DLREC Delete Existing Record 7 6 RELSE Unlock Record Latest Record Accessed 7 6
14. DO Condition code D1 Relative record number deleted CC Z set if success Use this call to delete a record from a file You must also lock this record prior to the call You may position to the record by using the GETREC or GETNXT call and then delete it ISAM PLUS deletes all keys associated with this record from the IDX file RELSE Unlock Record Latest Record Accessed INPUT Al FPN pointer A5 ISAM PLUS impure area pointer OUTPUT All registers preserved except DO Condition code D1 Relative record number released CC Z set if success Use this call to release the last record that you accessed The last record must be already locked RELRC Unlock Record Specific Relative Record Number INPUT Al FPN pointer A5 ISAM PLUS impure area pointer D1 Relative record number OUTPUT All registers preserved except DO Condition code CC Z set if success Use this call to release a particular record number ISAM PLUS User s Manual Rev 02 The ISAMP SYS Interface RELAL Unlock All Records OUTPUT INPUT Al A5 FPN pointer All registers preserved except DO Condition code CC Z set if success Use this call to release all the locked records STATS Get Statistical Information OUTPUT INPUT ISAM PLUS impure area pointer Al FPN pointer A5 ISAM PLUS impure area poi
15. INDEX MISMATCH PRINT Key type KEY TYPE SKEYO1L TYPE IF SKEYO1 TYPE lt gt KEYO1 TYPE THEN amp PRI ERROR PREFIX KEY TYPE ISMATCH PRINT Key name SKEYO1 NAME IF SKEYO1 NULL lt gt 0 THEN amp PRI ERROR PREFIX KEY NAME NULL NOT NULL PRINT Key dup flag SKEYO1L DUP IF SKEYO1 DUP lt gt KEYO1 DUP THEN amp PRINT ERROR PREFIX KEY DUP FLAG MISMATCH PRINT Key change flag SKEYO1 CHNG IF SKEYO1 CHNG lt gt KEYO1 CHNG THEN amp PRI ERROR PREFIX KEY CHANGE FLAG MISMATCH PRINT Key size y SKEYO1 SIZE IF SKEYO1 SIZE lt gt KEYO1 SIZE HEN amp PRI ERROR PREFIX KEY SIZE ISMATCH PRINT Verifying Secondary Key PRINT Key index SKEY02 INDEX IF SKEYO2 INDEX lt gt 1 THEN amp PRI ERROR PREFIX INDEX MISMATCH PRINT Key type KEY TYPE SKEYO02 TYPE IF SKEYO2 TYPE lt gt KEYO2 TYPE THEN amp PRI ERROR PREFIX KEY TYPE ISMATCH PRINT Key name SKEY02 NAME IF SKEYO2 NULL lt gt 0 THEN amp PRI ERROR PREFIX KEY NAME NULL NOT NULL PRINT Key dup flag SKEY02 DUP IF SKEYO2 DUP lt gt KEYO2 DUP THEN amp PRI ERROR PREFIX KEY DUP FLAG MISMATCH PRINT Key change flag SKEY02 CHNG IF SKEYO2 CHNG lt gt KEYO2 CHNG THEN amp PRI ERROR PREFIX KEY CHANGE FLAG MISMATCH PRINT Key position segment 1 SKEY02 POS01 IF SKEYO02 POSO1 lt gt KEYO2 POSO1 THEN amp PRINT ERROR PREFIX KEY POSITION MISMATCH PRINT Key size segment
16. Press the RETURN key to continue Secondary key number 3 Type of key 2 Key description Duplicate keys are allowed for this directory index Key may change during updating Size of key 6 Position of key 92 Press the RETURN key to continue The information reported is self explanatory in most cases Total index blocks allocated is the number of index blocks allocated for indexing excluding the key directory header blocks Each key directory uses one header block Number of records allocated is the maximum number of records this ISAM PLUS file can hold You entered this number when you created the file Number of secondary key directories is the total number of secondary key directories including the deleted key directories ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 15 Number of active secondary key directories is the number of secondary key directories currently active Minimum empty index blocks isthe number of empty index blocks you must have in order to add records This number is very important to ISAM PLUS which has to make sure your IDX file is in good shape if there is a shortage of blocks the index file could be destroyed The minimum number is calculated internally based upon the number of records size of key and number of directory keys If the number of free index blocks available is close to the minimum number required we suggest you add more using the ADDIDX command
17. index into the data on that page So if the two words at the top of a particular page are PENDERGRASS PENNINGTON you know the names associated with all entries on that page fall somewhere in that range Suppose then this second file we are creating contains the words at the top of the phone book pages along with the relative record numbers of the entries that fall on each page Instead of searching the entire data file we can search this much smaller index file If we want to find the entry for the name PENHALL we can search the page indices in our index file until we find two names PENHALL falls between When we build an index file we say the file contains symbolic keys A symbolic key is an element of a logical record on which we base our search In this example the symbolic key we are using is the name associated with each phone book entry We might just as easily set up the files so we base our search on phone numbers or city names Adding Another Level of Indices We have improved our original file search procedure but it can be improved further We now have a data file and an index file The index file has one level of indices the words at the top of each page in the phone book The next step is to provide another level of indices within the index file When you look for a name in a phone book you first find the proper page by glancing at the names at the top of each page Then you might look at the first and last names of e
18. AP 3 SKEY11 DUP B 1 0 Duplicate keys permitted flag 0 1 AP 3 SKEY11 CHNG B 1 0 Key change permitted flag 0 1 AP3 SKEY11 SIZE B 2 0 Size of key characters AP3 SKEY11 POS B 2 0 Position of key in record 1 based MAP2 SCONCATKEY12 Secondary Key Concat AP3 SKEY12 INDEX B 2 0 Index number for this key AP 3 SKEY12 TYPE B 1 3 Type of key Concatenated type AP3 SKEY12 RESV 3 B Reserved for future expansion AP3 SKEY12 NAME S 20 Name of key 20 char blank filled AP3 SKEY12 NULL B 2 0 Null terminator for key name AP 3 SKEY12 DUP B 1 0 Duplicate keys permitted flag AP 3 SKEY12 CHNG B 1 0 Key change permitted flag AP3 SKEY12 SIZE11 B 2 0 Size of sub key characters AP3 SKEY12 POS11 B 2 0 Position of sub key in record 1 based AP3 SKEY12 SIZE12 B 2 0 Size of sub key characters AP3 SKEY12 POS12 B 2 0 Position of sub key in record 1 based AP3 SKEY12 SIZE13 B 2 0 Size of sub key characters AP3 SKEY12 POS13 B 2 0 Position of sub key in record 1 based AP3 SKEY12 TRM B 2 0 Terminate list of 1 16 sub keys MAP 2 STAD TRM B 2 0 Terminate key stats PRINT PRI TEST1O BAS File Creation Test for ISAM PLUS testing PRINT FILENAME TESTFL DOW 1 Monday DOW 2 Tuesday DOW 3 Wednesday DOW 4 Thursday DOW 5 Friday DOW 6 Saturday DOW 7 Sunday KEY TYPE 1 Alphanumeric Key KEY TYPE 2 Binary byte string Key KEY TYPE 3 Concatenated Key PRINT Deletin
19. B 1 Reserved for future expansion AP3 CITY NAME S 20 City Name of key blank filled AP3 CITY NULL B 2 0 Null terminator for key name AP3 CITY DUP B 1 1 Duplicate keys permitted flag Yes AP 3 CITY CHNG B 1 1 Key change permitted flag Yes AP3 CITY SIZE B 2 20 Size of key characters AP3 CITY POS B 2 81 Position of key in record 1 based Secondary key MAP2 State field ISAM KEY 4 AP 3 ST TYPE B 1 1 Type of key Alphanumeric type AP3 ST RESV 3 B 1 Reserved for future expansion AP3 ST NAME S 20 State Name of key blank filled AP3 ST NULL B 2 0 Null terminator for key name AP3 ST DUP B 1 1 Duplicate keys permitted flag Yes AP 3 ST CHNG B 1 1 Key change permitted flag Yes AP3 ST SIZE B 2 2 Size of key characters AP3 ST POS B 2 101 Position of key in record 1 based l Secondary key l MAP2 ZIP code ISAM KEY 5 AP3 ZIP TYPE B 1 1 Type of key Alphanumeric type AP3 ZIP RESV 3 B 1 Reserved for future expansion AP3 ZIP NAME S 20 Zip code Name of key blank filled AP3 ZIP NULL B 2 0 Null terminator for key name AP 3 ZIP DUP B 1 1 Duplicate keys permitted flag Yes AP 3 ZIP CHNG B 1 1 Key change permitted flag Yes AP3 ZIP SIZE B 2 5 Size of key characters AP3 ZIP POS B 2 103 Position of key in record 1 based Secondary key MAP 2 Status ISAM KEY 6 AP3 STAT TYPE B 1 1 Type of key Alphanumeric type AP3 STAT RESV 3 B 1 Reserved for future expans
20. Display all record fields GOSUB PRINT STRIPPED PRINT STRING FIRST NAME GOSUB PRINT STRIPPED PRINT PRINT ADDRESS STRING CITY GOSUB PRINT STRIPPED PRINT 7 STRING STATE GOSUB PRINT STRIPPED PRINT STRING ZIP GOSUB PRINT STRIPPED PRINT PRI STATUS TAB 12 PRI LAST NAME 1 1 STATE LAST NAME 3 1 ZIP 3 3 FIRST NAME 1 1 RETURN LABEL PRINT Print labels STRING FIRST NAME GOSUB PRINT STRIPPED PRINT wow s STRING LAST NAME GOSUB PRINT STRIPPED PRINT PRI ADDRESS STRING CITY GOSUB PRINT STRIPPED PRINT 7 STRING STATE GOSUB PRINT STRIPPED PRINT STRING ZIP GOSUB PRINT STRIPPED PRINT PRINT RETUR Print with trailing blanks stripped PRI STRIPPED FOR I LEN STRING TO 1 STEP 1 IF STRING I 1 lt gt GOTO PRINT STRIPP NEXT I PRI STRIPPED OUT PRINT STRING 1 1 RETUR UPPERCASE Force all letters to upper case amp pad blanks NEW LAST NAME UCS NEW LAST NAME SPACE 40 NEW FIRST NAME UCS NEW FIRST NAME SPACE 40 NEW ADDRESS UCS NEW ADDRESS SPACE 40 NEW STATE UCS NEW STATE SPACE 40 NEW CITY UCS NEW CITY SPACE 40 NEW ZIP UCS NEW ZIP SPACE 40 NEW STATUS UCS NEW STATUS SPACE 40 RETURN SHUTDOWN CLOSE 1 END ERROR TRAPI1 If error is not fi le not found then error
21. ISAM EQ 0 Found key with value equal to that specified in kval ISAM GT 1 Found key with value greater than that specified in kval If the key is found the relative record number variable is updated For example GET 3 WAIT RECORD ISAM KEY 0 gt ABCD varlist gets the record whose primary key is ABCD from the file opened on channel 3 and stores it in varlist If no record in the file has the key ABCD the GET operation returns the record with the next highest key ABCE for example The status variable specified in the OPEN is set to e ISAM NF if no key was found greater than or equal e ISAM EQ if a key ABCD was found e ISAM GT if key ABCE or greater was found ISAM PLUS User s Manual Rev 02 Page 8 4 Chapter Eight GET NEXT and GET NEXT LOCKED GET NEXT performs sequential access It reads the next record in key order into the record buffer The key number used is that of the last GET or FIND operation The format is GET NEXT file channel WAIT RECORD varlist file channel Channel number specified in the OPEN WAIT RECORD Lets you wait for locked records varlist List of variables to store the record in The key number used is the last referenced in a GET or FIND statement If no GET or FIND was executed on this file since the OPEN the primary key is used GET NEXT and GET NEXT LOCKED return these status values in the status variable ISAM NF 3 Key not found
22. ISAM NA 2 Record not available locked ISAM EQ 0 Key found If the key is found the relative record number variable is updated GET PREV and GET PREV LOCKED GET PREV performs reverse sequential access It reads the previous record in key order into the record buffer The key number used is from the last GET or FIND The format is GET PREV file channel WAIT RECORD varlist file channel Channel number specified in the OPEN WAIT RECORD Lets you wait for locked records varlist List of variables to store the record in The key number used is the last referenced in a GET or FIND statement If no GET or FIND was executed on this file since the OPEN the primary key is used GET PREV and GET PREV LOCKED return these status values in the status variable ISAM NF 3 Key not found ISAM NA 2 Record not available locked ISAM EQ 0 Key found If the key is found the relative record number variable is updated FIND FIND NEXT and FIND PREV These statements are similar to GET and GET NEXT statements The difference is FIND does not transfer data from the file to memory It positions the current record pointer so a GET NEXT retrieves the record ISAM PLUS User s Manual Rev 02 ISAM PLUS and BASIC Page 8 5 specified by the FIND FIND NEXT or FIND PREV statement The FIND statements may also be used to obtain the relative record number associated with a given key The format is FIND file channe
23. Open an ISAM file 6 2 Set key specified by a key 6 2 Unlock record 6 4 Update existing record 6 4 STAT 4 1 4 13 Statistical information 4 13 5 7 6 4 7 7 8 9 STATS call 7 7 Status value 8 5 Status values 8 11 8 12 Status variable 8 3 Symbolic key 2 1 2 2 Symbolic pointer 3 6 SYSMSG 5 8 SYSMSG monitor call 7 9 T Template ALLOCATE INDEXED 8 8 INDEXED STATS 8 9 U Unlock Record by number 8 7 Unlocking All records 7 7 8 6 Record 6 4 8 6 Record by number 7 6 Record last accessed 7 6 UNLOKR statement 8 7 Update Mode 4 7 4 8 UPDATE statement 6 1 8 5 UPDATE RECORD statement 8 5 Updating a record 3 6 7 5 8 1 8 5 Updating existing record 6 4 UPREC call 7 5 ISAM PLUS User s Manual Rev 02 Index Page 5 WwW WAIT FILE keyword 8 2 WAIT RECORD keyword 8 2 ISAM PLUS User s Manual Rev 02
24. s Manual Rev 02 Page 4 4 Chapter Four numeric binary data For alphanumeric and concatenated keys ISAM uses the collating sequence of the language definition LDF file in use for your job to determine ordering For a binary key ISAM compares the high order byte first Do not use byte swap format for your data 3 Defining the Primary Key Directory Primary key ISAM displays this message to let you know it s ready to gather information about the primary key directory you chose for the index file The internal identification number of the primary key directory is Key Number 0 Type of key Enter the numeric code See the ISAM code display in item 3 above Key description This field lets you describe the key for future reference The description is limited to 20 characters Whenever you use the ISMUTL STAT command your description is displayed along with the statistical information about your ISAM file If you prefer not to record any information just press RETURN Are duplicate keys allowed for this directory index Y N This question lets you specify whether this key directory can contain duplicate keys Answer Y for Yes N for No The default is N Are keys allowed to change during updating Y N This question lets you specify whether the keys in a record can be modified when the record itself is modified Answer Y for Yes N for No The default is N Size of key Enter the length of the record field you chose as the p
25. you specified duplicate keys are not allowed for this file Cannot add record not enough free index blocks You previously received a warning message that the supply of free index blocks is less than the minimum required but did not take corrective action You must correct the problem before you can add more records Use the ADDIDX utility to add extra index blocks or delete some records Cannot change key You are trying to change a key but when the ISAM PLUS file was created you specified the keys in this file cannot be modified Unless you request this option at the time the index is created modifying keys is not allowed Cannot create existing ISAM PLUS file An ISAM PLUS file of the same name already exists This message only appears if you interface your assembly language program to ISMUTL Cannot delete primary key You may not delete a primary key for any reason Data file full You are trying to add more records than you allowed room for when you created the file Either enlarge the file or create a new file Data file smashed An IDA free list chain is no longer accessible or the index file is corrupted Try to rebuild the data free list CISAMP chain and or rebuild the key indexes ISMUTL ISAM PLUS User s Manual Rev 02 Page A 2 Appendix A Incompatible ISAM file You are trying to execute an ISAM file under ISAM PLUS See Appendix C for information on converting an ISAM 1 0 file to ISAM PLUS form
26. 1 SKEYO2 SIZEO1 IF SKEYO2 SIZE lt gt KEYO2 SIZE HEN amp PRINT ERROR PREFIX KEY SIZE MISMATCH PRINT Key position segment 2 SKEY02 POSO2 ISAM PLUS User s Manual Rev 02 Sample BASIC Programs Using ISAM PLUS Page B 5 IF SKEYO2 POSO2 lt gt KEYO2 POSO2 THEN amp PRINT ERROR PREFIX KEY POSITION MISMATCH PRINT Key size segment 2 SKEY0O2 SIZEO2 IF SKEYO2 SIZE lt gt KEYO2 SIZE THEN amp PRI ERROR PREFIX KEY SIZE MISMATCH PRINT Key position segment 3 SKEY02 POSO3 IF SKEY02 POS03 lt gt KEY02 POS03 THEN amp PRI ERROR PREFIX KEY POSITION MISMATCH PRINT Key size segment 3 SKEY02 SIZEO3 IF SKEYO2 SIZE lt gt KEYO2 SIZE THEN amp PRI ERROR PREFIX KEY SIZE MISMATCH IF SKEYO2 TRM lt gt 0 THE amp PRI ERROR PREFIX KEY STRUCTURE ERMINATOR MISMATCH IF STAT TRM lt gt 0 THE amp PRI ERROR PREFIX STAT STRUCTURE TERMINATOR MISMATCH PRI VERIFYING OPEN 1 FILENAME INDEXED STATS 1 gt A RNATE INDEXED STATS FORM INDEXED STATUS VAR RECNO S T 0 STATS MAP
27. 1 A TERMINAL SESSION WITH ISMUTL Alpha Micro Indexed Sequential Access Method Version X X xxx 1 Number of records to allocate 2000 Size of Data Record 120 2 Type of key Enter 1 for Alphanumeric type Enter 2 for Integer type Enter 3 for Concatenated keys type Enter 4 for Binary type 3 Primary key Type of key 1 Key description Customer number Are duplicate keys allowed for this directory index Y N N Are keys allowed to change during updating Y N N Size of key 6 Position of key 5 4 Secondary key number Type of key 1 Key description Customer name Are duplicate keys allowed for this directory index Y N Y Are keys allowed to change during updating Y N N Size of key 25 Position of key 15 5 Secondary key number 2 Type of key 3 Key description Are duplicate keys allowed for this directory index Y N Y Are keys allowed to change during updating Y N Y Size of key 3 Position of key 1 Size of key 10 Position of key 100 Size of key 5 Position of key 75 Size of key 2 Position of key 20 Size of key ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 3 SAMPLE 4 1 continued Secondary key number 3 Type of key 2 Key description Are duplicate keys allowed for this directory index Y N Y RETURN Are keys allowed to change during updating Y N Y Size of key 4 Position of key 92 6 Sec
28. 16 Chapter Four Enter new key description Enter the new key description Remember the descriptive information is limited to 20 characters If you don t want to change the description just press RETURN If you want to erase the key description completely press the SPACE BAR once then press RETURN Enter key number If you want to change another key directory or display its key description enter the key number If not press to stop EXIT Return to AMOS EXIT returns you to AMOS command level ISAM PLUS User s Manual Rev 02 Chapter 5 Assembly Language Programming Interface to ISMUTL You can use the ISMUTL program both interactively and as an interface between your assembly language programs and ISAM PLUS This chapter shows how assembly language programs can call ISMUTL routines A sample program is given at the end of this chapter For more information on the purpose of these routines see the discussion in Chapter 4 on using ISMUTL interactively PREPARATION Copy the module DSKO ISMUSR M68 7 7 into your assembly language program using the COPY statement ISMUTL LIT and ISAMP SYS must be loaded into MEM or RES You may use the FETCH instruction to load them for you ISMUTL LIT and ISAMP SYS always save all the registers except those registers that contain output information and register D7 THE ENTRY POINTS This section describes what each routine does and the parameters used in calling the routine
29. 2 bytes 16 times Null terminator 2 bytes Note Key specifier negative if key has been deleted uses 32 bytes This call lets you examine the status of a particular ISAM PLUS file Some offsets are defined in ISMUSR M68 for your convenience Use D1 for the size of the buffer in bytes that you want ISAM PLUS to fill for you ISCLS Close ISAM PLUS File INPUT Al FPN pointer A5 ISAM PLUS impure area pointer DO Flag IS LOC Used in COBOL S KEP Close file but keep it locked OUTPUT All registers preserved except DO Condition code CC 0 if success IS LOC is used to lock the IDX file only This flag is meaningful only if you opened the file for exclusive use n You must close all ISAM PLUS files opened for processing ISFIN Finalize ISAM PLUS INPUT A5 ISAM PLUS impure area pointer OUTPUT None ISFIN is the last call It de allocates the ISAM PLUS impure area ISAM PLUS User s Manual Rev 02 The ISAMP SYS Interface Page 7 9 ISERR Display ISAM related Error Message INPUT DO Error code D6 Flag OTSLDQ Display leading OTSTR Output to Terminal OTSDDB Output through DDB indexed by A2 OTSMEM Output into buffer indexed by A2 OTSCR Append CR LF OTSBEL Ring a bell A2 DDB or Buffer address depending on flag Zero if outputting to a terminal OUTPUT None This call is used to print ISA
30. 2 which you have locked either party may use C to resolve the situation ISAM PLUS prints Record in use updates the pointer and proceeds as if you made a FIND call Get Next Previous Record A Find Key or Find Next Previous Key call is used with the Get call to read the record whose key was found with the Find call You may use the Get Next Previous Record call to read the next previous data record in key order without you specifying a key If you have just opened a file you may use this call to scan all the records in the file You may set the file pointer to the last record in the file in an Open call and issue a series of Get Previous calls to scan the file in descending order If you have positioned to a key by using the Find call stating the EQ relation and if the record associated with this key is deleted by another user before you do a GET call the Get Next Previous Record call returns the message record not found If you had stated another relation this call would have located the next previous record If the record is in use by another user and you don t want to wait the position points to this record as if you are using a Find Next Previous call This lets you try again If you want to skip this record use a Find Next Previous call Find Key Specified by a Key This call is similar to the Get Record call only the Find Key call positions within an ISAM PLUS file It returns the key and relative record number it finds If yo
31. 5 Hints for users C 1 INDEXED STATS 8 9 MAP statements for ISAM files 8 8 OPEN 8 2 8 3 RELEASE ALL 8 6 RELEASE RECORD 8 6 Status value 8 5 Status values 8 11 8 12 Status variable 8 3 UNLORR 8 7 UPDATE 8 5 UPDATE RECORD 8 5 AlphaBASIC Plus 8 1 ISAM PLUS User s Manual Rev 02 index Alphanumeric key 3 3 Ascending order 3 6 4 7 Assembly language interface 5 1 B BADD call 5 4 BADDxX call 5 6 BCHNG call 5 5 BCRET call 5 2 BDEL2 call 5 5 BDUMP call 5 6 BERR call 5 8 BFIN call 5 8 Binary key 3 3 BINIT call 5 1 BLDTRE LIT 3 1 BLOAD call 5 4 BSET call 5 7 BSTAT call 5 7 C Carriage return line feed 4 8 CHANGE 4 1 4 9 Changing IDA file device 4 9 Changing device assignment 4 9 Changing IDA file device 5 5 CISAMP 2 1 CISAMPLIT 3 1 CLOSE statement 8 7 CLOSEK statement 8 7 Closing an ISAM file 7 8 8 7 Keeping locked 8 7 Closing ISAM PLUS file 6 4 Collating sequence 3 3 4 4 Concatenated key 3 3 4 5 5 3 Control characters 1 3 CRILF 4 7 4 8 4 13 CREATE RECORD statement 8 6 Creating a record 8 1 8 6 Creating an ISAM file 8 7 Creating an ISAM file 4 1 4 6 5 2 D Data file 2 2 Changing device 4 9 5 5 Page 2 Defining 4 3 Device assignment 4 5 DELETE 4 6 4 11 DELETE RECORD statement 8 6 Deleting Record 3 6 6 4 7 6 Secondary key directory 4 11 5 5 Descend
32. Manual Rev 02 Document History Revision A00 AMOS T 3 4 Printed 12 77 New document part number DWM 00100 06 Revision A01 AMOS T 4 1 Printed 4 79 Added introductory chapter discussing basic concept of ISAM files Added chapter on using ISAM from within AlphaBASIC and added a chapter on ISMCOM the ISAM file compression program Revision A02 AMOS T 4 5 Printed 4 81 Added information on new access modes Counted Update mode and Exclusive Open mode Also added conversion hints for users going from ISAM versions 4 2 to later versions Documented the Suppress Exclusive Open Mode switch for ISMBLD and ISMDMP Revision A03 AMOS T 4 6 Printed 10 81 Documented new feature of ISAM ability to return symbolic key as well as relative record number when searching a data file sequentially by symbolic key Revision B00 AMOS L 1 0 Printed 6 82 Added information for AMOS L systems Added information to Chapter 1 on transferring ISAM files from AMOS T to AMOS L systems and vice versa Included a new chapter on writing assembly language programs on AMOS L systems to access ISAM files Revision C00 AMOS T 5 0 and AMOS L 1 1 Printed 3 83 Added information on file locking using LOKSER Two new chapters added About This Book and File Locking Techniques Revision C01 AMOS T 5 0 and AMOS L 1 1 Printed 5 84 Corrected typographic error in Section 8 4 and documented IS UNL flag in Section 8 9 Revi
33. No problem FSPEC of IDX file FSPEC of IDA file OPENR of IDX file INPUT of IDX file Not able to change memory size OPENIO of IDA file FSPEC of SEQ file INIT of SEQ file LOOKUP failed for SEQ file OPENI failed for SEQ file INPUT failed for IDX file FSPEC of output file INIT of output file Not able to OPENO DSKDEL output file PUT of IDA failed or INPUT of SEQ file FILOTx of output file Incomplete record processed Not used Not able to write primary rock Keys and records don t match CLOSE of IDX file CLOSE of IDA file CLOSE of SEQ file CLOSE of output file GETXX of IDX file failed Primary Key GETXX of IDX file failed Secondary Key GETXX of IDX file failed Primary Key Insufficient index block to build Page A 6 Appendix A If the error reported is T PFAIL Ax 2 the error was found in the SORTKY LIT program The table below describes the error conditions in the SORTKY LIT program Error Code T CFAIL Ax 0 T CFAIL Ax 1 T CFAIL Ax 2 T CFAIL Ax 3 T CFAIL Ax 4 T CFAIL Ax 5 T CFAIL Ax 6 T CFAIL Ax 7 Error Code T CFAIL Ax 0 T CFAIL Ax 1 T CFAIL Ax 2 T CFAIL Ax 3 T CFAIL Ax 4 T CFAIL Ax 5 T CFAIL Ax 6 T CFAIL Ax 7 T CFAIL Ax 8 T CFAIL Ax 9 T CFAIL Ax 10 T CFAIL Ax 11 T CFAIL Ax 12 T CFAIL Ax 13 T CFAIL Ax 14 T CFAIL Ax 15 Meaning No problem Not able to
34. Points to key number assigned CC Z set if success Input A1 points to the data structure that must contain Al gt Extra percentage Loading factor Reserved Type of key Reserved Key name description Null Flag allow dup keys Flag key may change Size of key Position of key Null terminator 2 bytes 1 byte 1 byte 3 bytes 20 bytes ASCIZ 2 bytes 1 byte 1 byte 2 bytes 2 bytes 2 bytes in decimal in decimal 0 900 50 100 13 bytes Repeat 0 ton times to terminate end of key information ISAM PLUS User s Manual Rev 02 Assembly Language Programming Interface to ISMUTL Page 5 5 If type of key K CONC Type of key 1 byte Reserved 3 bytes Key name description 20 bytes ASCIZ Null 2 bytes Flag allow dup keys 1 byte Flag key may change 1 byte Size of key 2 bytes Repeat 1 Position of key 2 bytes 4 t to 16 times Null terminator 2 bytes to terminate end of concatenated field Output A4 points to the data structure that contains A4 gt Key number assigned 1 byte Repeat 0 to n times Null terminator 1 byte n number of existing secondary key directories must be less than or equal to 64 BDEL2 Delete Existing Secondary Key Directory INPUT AO ISMUTL impure area pointer Al Key number s pointer OUTPUT DO Condition code D1 Number of index blocks freed D2 Offset within block po
35. Secondary key 3 Type Description Duplicate key Change key Size Position To execute this program St Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Se SEARCH SYS SEARCH SYSSYM COPY ISMUSR M68 Alphanumeric Customer name Yes No 25 bytes iS Concatenated key None Yes Yes 3 bytes 1 10 bytes 100 5 bytes ADS 2 bytes 20 Binary None Yes Yes 6 bytes 92 type after the AMOS prompt prg name is the name of this program that you re created and filename is the ISAM PLUS file name that you chose i Offset for our impure memory area sORL I Start from 0 OFDEF E Z OFDE OFSI BEGIN GETIMP SIZE A5 BYP TRM JEQ NOCOMM Locate ISMUTL LIT LEA Al ISMUTL SRCH A1 A4 F USR BEQ 10 SRCH A1 A4 BEQ 10 TYPECR lt Can not locate ISMUTL LIT gt EXIT Note 10 OV A4 SYSADR A5 ISAM PLUS User s Manual Rev 02 you may use the FETCH instruction to Ne Ne Ne Ne Ne Ne Ne load ISMUTL LIT prg name filename wher ISAM PLUS user symbol definition file Storage for ISMUTL LIT address Record parameter area Total size Get impure memory use A5 as base Skip spaces on command line Do we have a command line no Al points to ISMUTLLIT in RAD50 Search in user memory first Save address if found Search system memory next Found it Not found Exit output message
36. WORK 2 1 Building the Data File 2 2 INDEXED SEQUENTIAL FILES 2 3 ISAM PLUS AS A PROGRAMMING TOOL 2 3 CHAPTER 3 ISAM PLUS FEATURES AND CAPABILITIES 3 1 THE ISAM PLUS MODULES 3 1 THE PAIR OF ISAM PLUS FILES 3 2 File Extensions 3 2 Loading 3 3 Key Types 3 3 Duplicate Keys 3 3 Collating Sequence 3 3 Distributed Free Space 3 4 Growth of a Data or Index File 3 4 THE INDEX STRUCTURE 3 4 Multiple Key Directories 3 4 Multilevel Index 3 4 Inventory of Index Blocks 3 5 Key Directory Header 3 6 OPERATIONS ON RECORDS 3 6 Symbolic Pointer Vs Relative Record Number 3 6 Search Key Relations 3 6 Read Sequential Reverse Function 3 6 ISAM PLUS ACCESS MODES AND LOCKS 3 6 Share Mode 3 7 Exclusive Mode 3 7 ISAM PLUS User s Manual Rev 02 Page ii Table of Contents CHAPTER 4 USING ISMUTL IN INTERACTIVE MODE 4 1 RUNNING ISMUTL 4 1 CREATING THE DATA AND INDEX FILES 4 2 The ISMUTL Display 4 3 THE ISMUTL MENU COMMANDS 4 6 LOAD Load an ISAM PLUS File 4 6 CHANGE Change Data File Device 4 9 ADD2ND Add a Secondary Key Directory 4 9 REBUILD Rebuild an Index File 4 11 DELETE Delete an Existing Secondary Key Directory 4 11 DUMP Dump an ISAM PLUS File 4 12 STAT Display Statistical Information 4 13 ADDIDxX Add Extra Index Blocks 4 15 DESCRP Change Key Description 4 15 EXIT Return to AMOS 4 16 CHAPTER 5 ASSEMBLY LANGUAGE PROGRAMMING INTERFACE TO ISMUTL 5 1 PREPARATION 5 1 THE ENTRY POINTS 5 1 BINIT Initialize ISMUTL 5 1
37. You specify the type of key you want associated with the index and the location of the key within each record when you use ISMUTL to create the file A concatenated key is formed by combining up to 16 ASCII fields which may or may not be adjacent to each other You may concatenate only alphanumeric keys When you create the index file you can specify whether updating a record is allowed to change the key within the record Duplicate Keys Duplicate primary as well as secondary keys are allowed if you request this feature at the time you create the index If duplicate keys are allowed for an index the first identical key found by ISAM PLUS is always returned or referenced For more information on duplicate keys and search key relations see Chapter 6 Collating Sequence If the key type is alphanumeric or concatenated ISAM PLUS uses the collating sequence contained in the active LDF language definition file of the job running ISMUTL This sequence is stored in the file itself and remains with this file forever To change the collating sequence to another sequence use ISMUTL to dump the old file delete it create a new file with the correct LDF and load the file For binary key type ISAM PLUS uses the standard ASCII collating sequence For additional information on changing language definition files see the System Operator s Guide ISAM PLUS User s Manual Rev 02 Page 3 4 Chapter Three Distributed Free Space After the initial lo
38. files You may also use this mode In exclusive mode no one else may access the ISAM PLUS file you are accessing Exclusive mode runs faster than share mode Note you must properly close the ISAM PLUS file after using this mode because it will not update any change to the key directory headers until you close the file ISAM PLUS User s Manual Rev 02 Chapter 4 Using ISMUTL in Interactive Mode ISMUTL the ISAM PLUS utility program includes various routines that create an ISAM PLUS file load records into it reformat it rebuild the index structure and make adjustments to it as requirements change You can either use ISMUTL by having your assembly language program call its functions see next chapter or you can use it interactively from AMOS command level In this chapter we discuss using the ISMUTL interactive menu from AMOS command level You choose the function you want to perform by selecting the appropriate command from the ISMUTL menu In this chapter we show a sample terminal session for creating an ISAM PLUS file and discuss how to answer the questions displayed We also give information on these ISMUTL menu commands LOAD REBUILD ADDIDX CHANGE DUMP DESCRP ADD2ND STAT EXIT DELETE RUNNING ISMUTL At AMOS command level type ISMUTL and a file name of your choice The format is ISMUTL filename switch If the file specified does not exist ISMUTL assumes you want to create a new ISAM PLUS index and data file com
39. index block count AP2 STAT TOTAL RECORDS B 4 0 Total allocated record count AP2 STAT TOTAL LOADED B 4 0 Total records loaded in line AP2 STAT MIN FREE IDX B 2 0 inimum free index blocks AP2 STAT EXTRA PERCENT B 2 0 Extra idx blks to alloc 0 900 AP2 STAT CREATE DATA Creation date AP3 STAT CREATE MONTH B 1 0 Creation month AP3 STAT CREATE DAY B 1 0 Creation day AP3 STAT CREATE YEAR B 1 0 Creation year AP3 STAT CREATE DOW B 1 0 Creation day of week AP2 STAT 2ND DIR B 1 0 Number of secondary directories AP 2 STAT REBUILD DATA Rebuild date AP 3 STAT REBUILD MONTH B 1 0 Rebuild month AP 3 STAT REBUILD DAY B 1 0 Rebuild day AP3 STAT REBUILD YEAR B 1 0 Rebuild year AP3 STAT REBUILD DOW B 1 0 Rebuild day of week AP2 STAT STATS RSERV 8 B 1 Reserved for future use MAP2 Primary key stats Selected from 3 types below MAP2 Secondary key stats Selected from 3 types below 0 64 AP2 STAT TRM B 2 0 Terminate key stats ISAM PLUS User s Manual Rev 02 ISAM PLUS and BASIC Page 8 11 Alphanumeric Key Stats Template AP2 SALPHAKEYO1 AP3 SKEYO1 INDEX B 2 0 Index number for this key AAP3 SKEYO1 TYPE B 1 1 Type of key Alphanumeric type AAP3 SKEYO1 RESV 3 B 1 Reserved for future expansion AP3 SKEYO1 NAME S 20 Name of key 20 char blank filled AP3 SKEYO1 NULL B 2 0 Null t
40. index blocks percentage see Creating the Data File and the Index File in Chapter 4 For more on adding index blocks see the information on the ADDIDX command of ISMUTL in Chapter 4 ISAM PLUS User s Manual Rev 02 Page 3 6 Chapter Three Key Directory Header In addition to the index blocks each key directory contains another block named the key directory header This block contains information describing the key directory and data file as well as maintenance information such as free record links and key size OPERATIONS ON RECORDS Chapters 6 and 7 provide detailed information about operations on records We also discuss some special features in this section Symbolic Pointer Vs Relative Record Number Your program deletes or updates data in the ISAM PLUS data file based on the location where ISAM PLUS positions your program Although most ISAM PLUS calls such as Get Record and Get Next Previous Record return a relative record number to you this number is given for your information only If you specified that duplicate keys are allowed for the particular index a relative record number can be used to distinguish one record from other records with the same key values Search Key Relations In accessing an ISAM PLUS file you state the value of the search key and specify one of two matches exact key match or approximate key match The approximate key search supports the following conditional relations e GE Greater than or
41. interfaces with ISMUTL Check your program key definitions Too many data file blocks You tried to create an IDA file with more than 4 294 967 295 logical records Reduce the number and try again Too many index blocks You tried to create an index file with more than 4 294 967 295 blocks Reduce the number and try again ISAM PLUS User s Manual Rev 02 Page A 4 Appendix A Warning free index blocks is less than minimum requirement Use ADDIDX to add more index blocks or delete some records If you see this message you won t be allowed to add more records ERROR CODES REPORTED IN Filename ERR When ISMUTL is building and loading records ISAM PLUS creates a file filename ERR This ERR file returns any errors encountered during the session If no errors occur during a session the file is erased The information in the ERR file contains these three elements e Program Code Identifies the program where the error condition occurred ISMUTL LIT EXTRAC LIT SORTKY LIT or BLDTRE LIT It is returned as a T PFAIL error code e Failure Code Identifies the location of the error condition within the program It is returned as a T CFAIL error code e DDB Failure Code Identifies the contents of the DDB error code that may have failed It is returned as an I DDBFAIL error code To find out the status of your processing at the assembly level ISMUSR M68 gives you access to these variables in both TMPMEM TMP and ISMUTL LIT A
42. key for sequential access ISAM PLUS reads the next record based on key sequence A GET operation modifies the current pointer if the operation is successful A GET after a FIND reads the record previously located by the FIND operation e PUT Add anew record from a buffer to the file e UPDATE Update an existing record e FIND Locate a specific key in the file and point to it If the key is found FIND updates the current pointer to that record DETAILED DEFINITIONS In this section we discuss the calls you use to update the contents of an indexed sequential file Open ISAM PLUS File for Processing As with any file each ISAM PLUS file pair IDA and DX must be opened before it can be processed You may open as many unique ISAM PLUS files as needed at one time limited by the memory resources available You may open an ISAM PLUS file in either exclusive or share mode If the file is opened for shared use ISAM PLUS uses Record 0 of the IDX file as a semaphore On attending to each call ISAM PLUS locks Record 0 and releases it before returning to the caller This record is locked only during the call and not between calls ISAM PLUS User s Manual Rev 02 Page 6 2 Chapter Six When opening a file you can direct ISAM PLUS to print any error messages on the screen by specifying the IS PRN flag You can set the file pointer to the last record of your file for the primary key if you want Normally you set a file pointer
43. multi purpose ISAM PLUS utility program ISMUTL from AMOS command level It includes a sample interactive session that creates an ISAM PLUS data file and index file This chapter also discusses file operations such as loading a file Shows you how assembly language programs call the ISMUTL program A sample assembly language program illustrates how to use these calls to create an ISAM PLUS file Describes the standard ISAM PLUS file update functions so everyone interfacing to ISAM PLUS from different languages and database applications has a standard way of working with records Describes the assembly language functions callable from the ISAMP SYS library Describes the AlphaBASIC ISAM PLUS statements Describes the ISAM PLUS diagnostic tool CISAMP Lists the ISAM PLUS error messages and ISMUTL s filename ERR error codes Gives sample AlphaBASIC programs that use ISAM PLUS ISAM PLUS User s Manual Rev 02 Page 1 2 Chapter One Appendix C Gives important conversion and compatibility information for programmers who wish to convert their files from ISAM to ISAM PLUS format RELATED DOCUMENTATION Alpha Micro publishes language and system reference books for the Alpha Micro operating system The following books related to ISAM PLUS are available from your Alpha Micro reseller e Assembly Language Instruction Set e Assembly Language Programmer s Reference Guide DSO 00052 00 e Monitor Calls Manual DSO 00040 00 e AMOS File Lo
44. slow and inefficient however because you have to deal with so many entries A better method would involve dividing the phone book into sections and searching only those sections that might contain the data you need instead of searching the entire database Automatically organizing your data so it is easier and quicker to search is the main idea behind ISAM If we were to organize the phone book in somewhat the same way as ISAM would do it we might do this ISAM PLUS User s Manual Rev 02 Page 2 2 Chapter Two Building the Data File First we build a file containing one logical record for each entry in the phone book each record consists of a person s name an address and a phone number We assign each entry a number called the relative record number that marks its position in the file For example the 500 entry is number 499 the first record is number 0 not 1 The record number is called relative because it marks the position of the record from the front of the file it is not an absolute disk address This file which contains all of our data corresponds to the ISAM data IDA file Building the Index File Next we construct a file that contains information about the data file that helps us search that file This file corresponds to the ISAM index IDX file When you open a phone book you notice there are two words at the top of each page the first and the last names that appear on that page These two names give you an
45. terminate end of key information 1 byte 3 bytes 20 bytes 2 bytes 1 byte byte bytes bytes bytes NNN E 1 Repeat 1 t to 16 times to terminate end of concatenated field Key name description use this 20 character field for your information only A1 must be even The BCRET routine is called to create anew ISAM PLUS file Creating an existing ISAM file causes an error ISAM PLUS User s Manual Rev 02 Page 5 4 BLOAD Load Records OUTPUT INPUT Chapter Five memory pointer ASCIZ Input file contains CR LF as record But ISAM PLUS does not separator support variable length records Fast load mode loaded AQ ISMUTL impure A2 Pointer to input file spec DO Flag IS CRL IS FST DO Condition code D1 Number of records D2 CC Z set if success BADD2 Add Secondary Key Directory OUTPUT INPUT Negative if last record loaded is in the middle AO ISMUTL impure memory pointer Al Record parameters pointer A2 Pointer to intermediate sequential file device name in ASCIZ format 0 if none devn A3 Pointer to new IDX device name in ASCIZ format 0 if none same as old one devn A4 Key number assigned storage DO Condition code D1 Total index blocks allocated exclude key directory headers D2 Relative pointer in Al where error is detected A4
46. the number assigned to the file by a previous OPEN statement CREATING AN ISAM PLUS FILE This section shows how to create indexed files from within AlphaBASIC programs using the ALLOCATETNDEXED statement and the ALLOCATE MAP structure It also shows how you construct the map structure using the templates provided in the file BAS CREATE BAS or BP CREATE BPI ALLOCATE INDEXED This statement tells ISAM PLUS to create the named file using the parameters stored in the ALLOCATE MAP structure you have prepared The format is ALLOCATE INDEXED fspec ALLOCATE MAP device fspec File specification giving the device name ALLOCATE MAP Map structure to specify ISAM PLUS file parameters See subsection below for details of structure device Optional string parameter indicating the device and drive that you want the data file IDA created on if not your current account ISAM PLUS User s Manual Rev 02 Page 8 8 Chapter Eight Any error is trapped and the error code is available through ERRO For example ALLOCATE INDEXED CUSMAS ALLOCATE MAP DSK3 will create the index CUSMAS IDX file in your current PPN device and the data CUSMAS IDA file in the same PPN of DSK3 Note that any information specified beyond the device and drive will be ignored y You must have ISAMP SYS loaded into system or user memory to use this statement W Templates for ALLOCATE INDE
47. the record size is not correct you must recreate the ISAM PLUS file n records loaded n records allocated ISMUTL tells you the number of records loaded and the number of records allocated ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 9 If you see the error message Index file full you must erase the file and rebuild the ISAM file with a larger IDX file You should not continue using this file CHANGE Change Data File Device You use the CHANGE command to change the name of the device the IDA file resides on This selection only changes the device specification for the file It does not copy the file over to the new device you must copy the IDA file to the new device yourself The current device name is displayed first If NOX is used the ISAM file is opened non exclusively Here are the questions and suggested responses for the CHANGE command Enter new device nam Enter the new device name in the form devn for example DSK1 If you enter a space as the new drive name it will default the IDA file to the device of the IDX file Warning IDA file does not exist in new device Press the RETURN key to continue If the IDA file does not exist on the new device you changed to ISAM PLUS displays this message Press RETURN When back at the ISMUTL menu exit to AMOS command level and copy the IDA file to the new device since most ISMUTL commands need the IDA file ADD
48. to correct the problem and rebuild the files from the beginning n records loaded n records allocated ISMUTL displays the number of records loaded and the number of records allocated If you see the error message Index file full you must erase the file and rebuild the ISAM file with a larger IDX file You should not continue using this file Update Mode ISMUTL uses update mode when the ISAM PLUS file is already loaded with data and you want to add new data to the file Don t load a sequential file if any of the keys are sorted in descending order doing so uses up a lot of index blocks If the sequential file you are going to load happens to be in exact descending order on any key use a sort program to sort the list of records out of descending order before using LOAD Here are the questions LOAD displays in update mode Load from file Enter the name of the sequential file The default file extension is SEQ Is CR LF used as record separator Y N Answer Y if each record contains a CR LF appended at the end of the record N if not o Make sure you answer correctly or the positions of the keys in the record will be wrong Each record length is fixed The default answer is N End of input file ISMUTL displays this message when all the records have been loaded If there is an error in record size you might see End of input file in the middle of record Make sure you investigate what caused this to happen If
49. 12 SIZE12 IF SKEY12 SIZE lt gt KEYO2 SIZE THEN amp PRI ERROR PREFIX KEY SIZE MISMATCH PRINT Key position segment 3 SKEY12 POS13 IF SKEY12 POS13 lt gt KEY02 POS03 THEN amp PRI ERROR PREFIX KEY POSITION MISMATCH PRINT Key size segment 3 SKEY12 SIZE13 IF SKEY12 STIZE13 lt gt KEYO2 STZE03 THEN amp PRI ERROR PREFIX KEY SIZE MISMATCH IF SKEY12 TRM lt gt 0 THEN amp PRI ERROR PREFIX KEY STRUCTURE ERMINATOR MISMATCH IF STAD TRM lt gt 0 THE amp PRI ERROR PREFIX STAT STRUCTURE TERMINATOR MISMATCH CLOSE 1 PRINT PRI VERIFICATION COMPLETE GOTO THE END PRI ERROR OFFSET ISA I ERROR OFFSET ON ERROR GOTO ON ERROR GOTO ACCESS ISAM PLUS RECORDS ISAM PLUS sample program This program is an example of how to handle ISAM PLUS files in AlphaBASIC versions 1 4 and later It uses a primary index and 7 secondary indexes It simulates a simple minded mailing program that allows inquiry by any of the eight indexes into the mailing list file ISAM PLUS User s Manual Rev 02 Sample BASIC Programs Using ISAM PLUS Page B 7 INCLUDE ISAMP Get standard ISAM PLU
50. 2 1 Position of key in record 1 based Secondary key MAP2 First Name ISAM KEY 1 AP3 FN TYPE B 1 1 Type of key Alphanumeric type AP3 FN RESV 3 B 1 Reserved for future expansion AP3 FN NAME S 20 First Name Name of key blank filled AP3 FN NULL B 2 0 Null terminator for key name AAP3 FN DUP B 1 1 Duplicate keys permitted flag Yes AP 3 FN CHNG B 1 1 Key change permitted flag Yes AP3 FN SIZE B 2 20 Size of key characters AP3 FN POS B 2 21 Position of key in record 1 based l Secondary key Selected from 3 types below 0 64 MAP2 Address field ISAM KEY 2 AP3 ADR TYPE B 1 1 Type of key Alphanumeric type AP3 ADR RESV 3 B 1 Reserved for future expansion AP3 ADR NAME S 20 Address Name of key blank filled AP3 ADR NULL B 2 0 Null terminator for key name AP3 ADR DUP B 1 1 Duplicate keys permitted flag Yes AP3 ADR CHNG B 1 1 Key change permitted flag Yes AP3 ADR SIZE B 2 40 Size of key characters AP3 ADR POS B 2 41 Position of key in record 1 based ISAM PLUS User s Manual Rev 02 Page B 8 Appendix B l Secondary key Selected from 3 types below 0 64 MAP2 City TSAM KEY 3 APS CITY TYPE B 1 1 Type of key Alphanumeric type AP3 CITY RESV 3
51. 200 S KEY zzzzzz a key that is the last possible key 250 GET 1000 WAIT RECORD ISAM KEY 0 lt S KEY AnEntry stat ISAM EQ DO WHILE stat ISAM EQ AnEntry GET PREV 1000 WAIT RECORD AnEntry LOOP CLOSE 1000 999 END The above listing shows a program using this technique In line 100 we see the S KEY variable set to the first possible key Then FIND and GET are executed The loop following sequentially gets all keys in the file Line 200 sets the search key to the last possible key i e the greatest Then FIND and GET are executed Notice the change in the relational operators to lt in line 250 The following loop sequentially gets the keys in reverse order ISAM PLUS User s Manual Rev 02 Chapter 9 Using CISAMP in Interactive Mode CISAMP is an ISAM PLUS diagnostic tool which checks your ISAM PLUS files for errors To check a file enter CISAMP A filename Do not include the extension with the file name CISAMP automatically analyzes both the IDA data file and the IDX index file Depending on the size of the file you re analyzing CISAMP could take some time to run and the file is not available to any other user while CISAMP is running For this reason you may want to include CISAMP as part of the command file or task manager control file you use for overnight processing such as backups or reports When it starts CISAM
52. 2ND Add a Secondary Key Directory The ADD2ND command lets you add a secondary key directory as long as the total number of secondary key directories is less than 64 It creates a new IDX file for you Here are the questions and answers for ADD2ND Enter device name for new IDX file Enter the new device name if you want the new IDX file to reside on a different device Press if you want it to reside on the same device Enter device name for intermediate fil ISMUTL uses an intermediate file ADD2ND SEQ to code which record is used and which record is not It stores this information in bitmap form One block of this file contains information for 4 064 records so this file is not large Enter the device name if you want the intermediate file to reside on a device other than the one you are logged into Press if you want it to reside on the same device Type of key Enter 1 for Alphanumeric type Enter 2 for Integer type Enter 3 for Concatenated keys type Enter 4 for Binary type After displaying the menu of key types ISMUTL begins displaying questions about each secondary key directory you may want to add ISAM PLUS User s Manual Rev 02 Page 4 10 Chapter Four Type of key Enter the numeric code for the type of key as shown in the menu display Key description Enter descriptive information about this secondary key for your own reference The description is limited to 20 characters If y
53. 4 You also specify the fields you want ISAM PLUS to base its record searches on that is you define the keys File Extensions The same filename with different extensions identifies the data file and its index file ISMUTL creates the data file with the extension IDA and creates the index file with the extension IDX There is always a single pair of files no matter how many secondary key directories are created All key directories reside in ISAM PLUS User s Manual Rev 02 ISAM PLUS Features and Capabilities Page 3 3 one index file See Multiple Key Directories in this chapter for information on the internal identification of the directories When we speak of an ISAM PLUS file we mean the DX and IDA file pair Loading To load the file with data you may write your own program or you may use ISMUTL s LOAD command This loads the data from an ordinary sequential file into the data file and adds all keys into the index file Although the data records themselves may be stored on the disk in any order ISAM PLUS references them in sequential order through use of the keys in the index file Key Types The data type and maximum length of ISAM PLUS keys are Number Key Type Encoding Maximum Length Alphanumeric ASCII string 161 bytes Integer BASIC PLUS integer 4 bytes Concatenated Upto 16 ASCII fields joined to form one Maximum of 161 key bytes Binary Numeric BASIC BASIC PLUS integer 1 to 5 bytes ISAM PLUS Key Types
54. 6 Al MOVW 92 Al End of key information CLRW Al Ready to call LEA Al RECPRM A5 SUB A2 A2 MOV SYSADR A5 A6 CALL BCRET A6 BEQ 50 7 Error TYPE lt Error at relative position MOV D2 D1 6 gt Size of key Position of key Size of key 7 Position of key Size of key Position of key Size of key Position of key Null terminator Type of key binary Skip reserved area of 3 bytes None use spaces Call the routine to transfer key description and 2 bytes null Flag duplicate keys are allowed Flag can change key during updating Size of key Position of key Ne Ne Ne Ne Ne Ne Ne Null terminator ake sure Al points to start of record parameter Same device name for ISMUTL LIT address Create it Ok IDA as IDX file Ne Ne Ne Ne Ne te Output the message adda O Move correct register BR OS Output the number in decimal File is successfully created 50S YPE lt File created gt Output the message CRLF YPE lt Number of index blocks allocated gt Output the message 60S DCVT 0 2 Output the number in decimal CRLF i Finalize it DONE OV SYSADR A5 A6 CALL BFIN A6 EXIT MOVDES This routine transfers key description Input A6 Al L MOVDES MOVW A6 Al BNE MOVDES RT ISMUTL LIT address Call the routine Exit to AMOS
55. 8 1 8 4 GET PREV LOCKED statement 8 4 8 5 GETREC call 7 3 Getting statistical information 6 4 7 7 Graphics conventions 1 2 GT operator 3 6 6 2 GTNXT call 7 4 H Hints for AlphaBASIC users C 1 I IDA file 2 2 4 1 4 2 IDX file 2 2 3 4 4 1 4 2 IMSUTL Interactive Menu 4 1 Index Percentage of extra blocks 4 10 Index blocks 3 5 Adding blocks 4 15 5 6 A 1 Inventory 3 5 Loading factor 4 5 Percentage of extra blocks 4 5 Index file 2 2 4 9 4 15 Multi level indices 2 2 Multilevel indices 3 4 Structure 3 4 4 1 INDEXED keyword 8 2 INDEXEDEXCLUSIVE keyword 8 2 INDEXED STATS statement 8 9 Integer key 3 3 Intermediate file 4 9 ISAM 1 1 ISAM PLUS User s Manual Rev 02 Index BLDTRE LIT 3 1 CISAMP LIT 3 1 Defined 2 1 Documentation 1 2 Error messages 5 8 EXTRACLLIT 3 1 File conversion to ISAM PLUS C 1 ISAMP SYS 3 1 ISMUSR M68 3 1 5 7 ISMUTL LIT 3 1 SORTKY LIT 3 1 ISAM PLUS 1 1 Error messages A 1 Features C 1 Modules 3 1 Routines 8 1 ISAMP SYS 3 1 ISCLS call 7 8 ISERR call 7 9 ISFIN call 7 8 ISINT call 7 1 7 2 ISMKEY REL file 4 7 ISMUSR M68 3 1 5 7 7 1 7 8 ISMUTL 2 1 3 4 4 1 ADD2ND 4 9 ADDIDX 4 15 A 1 Adding index blocks 4 13 5 6 Adding secondary key directory 4 9 5 4 BADD call 5 4 BADDxX call 5 6 BCHNG call 5 5 BCRET call 5 2 BDEL2 call 5 5 BDUMP call 5 6 BERR call 5 8 B
56. A PERCENT B 2 0 Extra idx blks to alloc 0 900 AP2 STAD CREATE DATE Creation date MAP3 STAD CREATE MONTH B 1 0 Creation month MAP3 STAD CREATE DAY B 1 0 Creation day MAP3 STAD CREATE YEAR B 1 0 Creation year MAP3 STAD CREATE DOW B 1 0 Creation day of week MAP2 STAD 2ND DIR B 1 0 Number of secondary directories ISAM PLUS User s Manual Rev 02 Sample BASIC Programs Using ISAM PLUS Page B 3 MAP2 STAD ACT 2ND DIR B 1 0 Active secondary directories MAP2 STAD REBUILD DATE Creation date AP3 STAD REBUILD MONTH B 1 0 Creation month AP3 STAD REBUILD DAY B 1 0 Creation day AP3 STAD REBUILD YEAR B 1 0 Creation year AP3 STAD REBUILD DOW B 1 0 Creation day of week MAP2 STAD RESERVE 8 B 1 Reserved for future use MAP 2 SALPHAKEY11 Primary key Alpha AP3 SKEY11 INDEX B 2 0 Index number for this key AP 3 SKEY11 TYPE B 1 1 Type of key Alphanumeric type AP3 SKEY11 RESV 3 B Reserved for future expansion AP3 SKEY11 NAME S 20 Name of key 20 char blank filled AP3 SKEY11 NULL B 2 0 Null terminator for key name
57. FIN call 5 8 BINIT call 5 1 BLOAD call 5 4 BSET call 5 7 BSTAT call 5 7 CHANGE 4 1 4 9 Creating an ISAM file 4 1 5 2 DELETE 4 6 4 11 Deleting secondary key directory 5 5 DESCRP 4 1 4 15 DUMP 4 1 4 12 Dumping an ISAM file 5 6 EXIT 4 16 Features 3 2 Finalizing 5 8 Getting statistical information 4 13 5 7 LOAD 4 6 4 8 Loading records 5 4 Menu 4 6 Options 4 6 REBLD call 5 8 REBUILD 4 11 STAT 4 1 4 13 ISMUTL LIT 3 1 8 9 ISOPN call 7 2 ISAM PLUS User s Manual Rev 02 Page 3 Key Alphanumeric 3 3 Binary 3 3 Concatenated 3 3 4 5 5 3 Directories 4 3 Directory 2 3 Directory header 3 6 3 7 Duplicate 2 3 3 6 4 4 Integer 3 3 Length of key fields 3 3 Primary key directory 3 7 4 4 Search key relations 3 6 Secondary key directory 4 4 Size 3 3 3 5 4 4 Symbolic 2 1 2 2 Types 4 3 Key directory 2 3 Key types 3 3 L Language definition file 3 3 LDF file 3 3 4 4 4 7 LE operator 3 6 6 2 LOAD 3 3 4 6 4 8 Loading factor 4 5 4 10 Loading a file 4 8 Loading factor 4 3 4 5 4 10 Loading records 5 4 Locking a file 3 6 6 1 6 4 Access modes 3 6 Deadlock 6 3 Exclusive mode 3 6 Share mode 3 6 Logical record 3 4 LST file 8 14 LT operator 3 6 6 2 M MAP statements for ISAM files 8 8 Memory 5 1 Allocation de allocation 5 1 ISINT call 7 1 Multilevel index 3 4 Multip
58. ISAM PLUS User s Manual RIGHT FROM THE START 1997 Alpha Microsystems REVISIONS INCORPORATED REVISION DATE 00 March 1988 01 April 1991 02 October 1997 ISAM PLUS User s Manual To re order this document request part number DSO 00012 00 This document applies to AMOS versions 2 3A PR 12 97 and later The information contained in this manual is believed to be accurate and reliable However no responsibility for the accuracy completeness or use of this information is assumed by Alpha Microsystems This document may contain references to products covered under U S Patent Number 4 530 048 The following are registered trademarks of Alpha Microsystems Santa Ana CA 92799 AMIGOS AMOS Alpha Micro AlphaBASIC AlphaCALC AlphaCOBOL AlphaFORTRAN 77 AlphaLAN AlphaLEDGER AlphaMATE AlphaNET AlphaPASCAL AlphaWRITE CASELODE OmniBASIC VIDEOTRAX The following are trademarks of Alpha Microsystems Santa Ana CA 92799 AlphaBASIC PLUS AlphaVUE AM PC AlphaDDE AlphaConnect DART inFront am ESP MULTI All other copyrights and trademarks are the property of their respective holders ALPHA MICROSYSTEMS 2722 S Fairview St P O Box 25059 Santa Ana CA 92799 AlphaACCOUNTING AlphaDDE AlphaMAIL AlphaRJE VER A TEL AMTEC inSight am Table of Contents CHAPTER 1 ABOUT THIS BOOK 1 1 RELATED DOCUMENTATION 1 2 GRAPHICS CONVENTIONS 1 2 CHAPTER 2 INTRODUCTION TO ISAM PLUS 2 1 WHAT IS ISAM PLUS 2 1 HOW DOES ISAM PLUS
59. ISAM PLUS impure area pointer DO Flag IS LOC Lock Record IS WAT Wait for record if it is in use IS RON Read Only mode D1 Key index specifier 0 is primary key D2 Relation IS EQ Equal IS GT Greater IS GE or IS GT IS EQ Greater or Equal IS LT Less than IS LE or IS LT IS EQ Less than or Equal OUTPUT All registers preserved except A3 Contains record pointer if success DO Condition code D1 Relative record number D2 Found code IS EQ Found with equal key value IS GT Found with greater key value IS LT Found with lesser key value IS NF Not found file is empty or unable to find key with the relation given CC Z is set if success Use this call to get a specific record from your ISAM PLUS file If the record is in use by another user and the IS WAT flag is not used GETREC still updates your current pointer and returns one of the three relations in D2 The relative record number returned to you is for your information only You may not access an ISAM PLUS file using this record number You may however use it to release a record GTNXT Get Next Previous Record INPUT Al FPN pointer A3 Pointer to record buffer where record is returned A5 ISAM PLUS impure area pointer DO Flag IS LOC Lock Record IS WAT Wait for record if it is in use IS BAK Descending get previous Ascending get n
60. In each synopsis the label INPUT refers to the register contents on entering the routine and OUTPUT refers to the return values CC stands for Condition Code BINIT Initialize ISMUTL INPUT A3 Pointer to user memory allocation routine optional A4 Pointer to user memory de allocation routine optional OUTPUT AO ISMUTL impure area pointer Exit to AMOS if memory allocation fails This is the first routine you must call to use ISMUTL It tells ISMUTL to create memory for its own internal use If you want ISMUTL to use GETMEM to allocate memory set A3 and A4 to 0 If you have your own allocation routine ISMUTL always calls your routine when it needs memory Upon entry into your allocation routine ISMUTL stores the number of memory bytes requested in register D1 and expects your allocation routine to return the base of the memory pointer in A1 Set the condition code before returning to ISMUTL set the Z bit ON if the allocation was successful and OFF if it failed fr ISMUTL exits to the AMOS monitor if the Z bit is not set If you are using your own de allocation routine ISMUTL passes the memory base in A1 Set the condition code upon returning to ISMUTL as discussed in the paragraph above Don t change any registers for the allocation or the de allocation routine ISAM PLUS User s Manual Rev 02 Page 5 2 Chapter Five If you have an allocation routine you must also have a de allocation routine you can t have one wi
61. M related error messages Use the SYSMSG monitor call if you wish to display FILSER errors The Error Codes These are the error codes used with ISERR The error messages are discussed in Appendix A Mnemonic Octal Code ISAM PLUS User s Manual Rev 02 Message Success Incompatible ISAM file ISAMP SYS not found Warning free index blocks is less than minimum requirement Data file full Index file full Cannot change key Index structure smashed Duplicate key Can t add not enough free index blocks Invalid number Maximum extra percentage exceeded Too many index blocks Invalid record size Too many concatenated keys Primary key information must be entered Maximum key size allowed exceeded Invalid key type Maximum binary type size exceeded Page 7 10 Mnemonic Octal Code Chapter Seven Message Key range is outside record Overlap keys must be alphanumeric type Too many data file blocks Exceeds maximum number of 2 key directory No such secondary key number This secondary key has been deleted Number of records dumped is mismatched with number of records in the file Key information must be entered Cannot create existing ISAM PLUS file Data file smashed System error ISAM file must be rebuilt Index block out of range End of table ISAM PLUS User s Manual Rev 02 Chapter 8 Using ISAM PLUS and AlphaBASIC The BASIC interface to ISAMP SYS allows the use of ISAM PLUS
62. MUTL Allocates Index Blocks nn index blocks will be allocated nn is the minimum number of index blocks allocated excluding the key directories headers Enter extra index blocks percentage Enter the percentage of extra index blocks you want ISMUTL to allocate You may enter 0 to 900 The value 0 means no extra index block is needed If you enter 100 ISMUTL doubles the minimum number allocated If you just press RETURN it will use the default of 100 percent and we suggest you use at least this percentage mm total index blocks will be allocated mm is the total number of index blocks allocated including the percentage of extra blocks Enter loading factor The loading factor is used in loading a sequential file through the LOAD menu command It s a percentage that specifies how densely to fill the index block with keys If you just press RETURN ISMUTL uses the default of 50 and each index block is half filled If you enter 100 each index block is filled to the maximum capacity There are advantages and disadvantages to either extreme If you fill each index block to the maximum capacity you use less index blocks overall but this may cause a lot of splitting when you update your ISAM file You must specify a number between 50 and 100 if you enter a number less than 50 ISMUTL uses 50 and if you enter a number greater than 100 ISMUTL uses 100 Data file Device You have three options to respond to this prompt
63. NT 1 BOMB 3A END Here is an example of a RUN or RUNP error display TEST5 test of a runtime error IO to unopened file in line at location counter 2B in TEST5 RUN Getting the First or Last Key in a File In ISAM PLUS there is no direct method of getting either the first or last key in a file However using this sequence will achieve either extreme 1 Execute a FIND on a key which is the smallest or largest possible key The key varies depending on type and collating sequence 2 Execute a GET This will get the first or last key and return ISAM LT or ISAM GT in the status variable For example INCLUDE ISAMP MAP1 red F 6 MAP1 stat f 6 MAP1 AnEntry AP2 FIRST NAME S 6 AP2 LAST NAME S 6 AP2 EXT NAME S 6 AP2 FILL DATA S 76 FILEBASE 1 MAP1 S KEY S 6 opening file OPEN 1000 DSK2 BOB indexed rec stat stat rec finding from the beginning of file 100 S KEY SPACE 6 a key that is the first possible key FIND 1000 ISAM KEY 0 gt S KEY S KEY 150 GET 1000 WAIT RECORD ISAM KEY 0 gt S KEY AnEntry stat ISAM EQ DO WHILE stat ISAM EQ gt AnEntry GET NEXT 1000 WAIT RECORD AnEntry LOOP ISAM PLUS User s Manual Rev 02 ISAM PLUS and BASIC Page 8 15 find from the end of file
64. P displays this message Pass Fail Diagnostic request for file filename IDX IDA If the file passes the test no errors are found CISAMP displays ISAMP file filename IDX IDA PASSED If CISAMP does find errors in the file you see ISAMP file filename IDX IDA FAILED Number of errors xx S the file filename LSE for information on error found If your ISAMP file fails the CISAMP testing please contact your Alpha Micro dealer or Alpha Micro s Technical Assistance Center at 800 487 7877 for further analysis information If you use CISAMP without the A switch you see a menu of analysis options You should not need to use any of these features unless advised to do so by Alpha Micro or your Alpha Micro dealer ISAM PLUS User s Manual Rev 02 Appendix A Error Messages ISAM PLUS lets you know an error occurred by displaying an error message The next section lists ISAM PLUS related messages and their meanings AMOS FILSER errors are not listed for those see your AMOS Monitor Calls Manual ISMUTL also alerts you to error conditions while it is building and loading records by creating a file filename ERR For a listing of the error messages in the ERR file and their meaning refer to the latter section in this Appendix ERROR MESSAGES REPORTED BY ISAM PLUS Attempt to add duplicate key You are trying to add a duplicate key but when the ISAM PLUS file was created
65. RELRC Unlock Record Specific Relative Record Number 7 6 RELAL Unlock All Records 7 7 STATS Get Statistical Information 7 7 ISCLS Close ISAM PLUS File 7 8 ISFIN Finalize ISAM PLUS 7 8 ISERR Display ISAM related Error Message 7 9 The Error Codes 7 9 CHAPTER 8 USING ISAM PLUS AND ALPHABASIC 8 1 UPDATING THE RECORDS OF AN ISAM PLUS FILE 8 1 OPEN Statement 8 2 GET and GET LOCKED 8 3 GET NEXT and GET NEXT LOCKED 8 4 GET PREV and GET PREV LOCKED 8 4 FIND FIND NEXT and FIND PREV 8 4 UPDATE RECORD 8 5 CREATE RECORD 8 6 DELETE RECORD 8 6 RELEASE RECORD 8 6 RELEASE ALL 8 6 CLOSE 8 7 CLOSEK 8 7 UNLOKR 8 7 CREATING AN ISAM PLUS FILE 8 7 ALLOCATEINDEXED 8 7 Templates for ALLOCATE INDEXED 8 8 ISAM PLUS User s Manual Rev 02 Page iv GETTING STATISTICAL INFORMATION INDEXED STATS Templates for INDEXED STATS ERROR PROCESSING Error Codes and Status Values FILSER Error Codes Error Location Getting the First or Last Key in a File CHAPTER 9 USING CISAMP IN INTERACTIVE MODE APPENDIX A ERROR MESSAGES ERROR MESSAGES REPORTED BY ISAM PLUS ERROR CODES REPORTED IN Filename ERR APPENDIX B PROGRAMS USING ISAM PLUS CREATE AND VERIFY AN ISAM PLUS FILE ACCESS ISAM PLUS RECORDS APPENDIX C CONVERSION HINTS FOR ISAM USERS CONVERTING ISAM FILES TO ISAM PLUS FORMAT DIFFERENCES BETWEEN ISAM AND ISAM PLUS DOCUMENT HISTORY INDEX Table of Contents 8 9 8 9 8 10 8 11 8 11 8 13 8 13 8 14 9 1 A 1 A 4
66. S file Recorded below is a STAT display showing an example of the kinds of information the ISAM PLUS system maintains on each file SAMPLE SCREEN DISPLAY Data device name DSKO Record size 120 Free records count 2000 Free index blocks count 698 Total index blocks allocated 702 Number of records allocated 2000 Number of records loaded 0 inimum empty index blocks 6 Extra index blocks percentage 100 Date file created Friday June 13 1997 Rebuilt 10 20 1997 Number of secondary key directories 3 Number of active secondary key directories 3 ISAM PLUS User s Manual Rev 02 Page 4 14 Chapter Four Primary key Type of key 1 Key description Customer number Duplicate keys are NOT allowed for this directory index Key may NOT change during updating Size of key 6 Position of key 5 Press the RETURN key to continue Secondary key number 1 Type of key 1 Key description Customer name Duplicate keys are allowed for this directory index Key may NOT change during updating Size of key 25 Position of key 15 Press the RETURN key to continue Secondary key number 2 Type of key 3 Key description Duplicate keys are allowed for this directory index Key may change during updating Total size of key 20 Size of key 3 Position of key Size of key 10 Position of key 100 Size of key 5 Position of key 75 Size of key 2 Position of key 20
67. S status values AP1 FILENAME S 10 MLIST AP 1 FSTATUS F AP1 STRING S 80 AP1 QUEST S 60 AP1 ANSWER S 1 AP1 ERRORBELLS S 20 CHRS 7 AP 1 KEYNAMES 8 Key names array AP2 KEYNAME S 20 AP1 LABEL Define the Mailing List file record AP2 LAST NAME S 20 AP2 FIRST NAME S 20 AP2 ADDRESS S 40 AP2 CITY S 20 AP2 STATE S 2 AP2 ZIP S 5 AP2 STATUS S 9 MAP 1 NEW LABEL Define the Mailing List file record AP2 NEW LAST NAME S 20 AP2 NEW FIRST NAME S 20 AP2 NEW ADDRESS S 40 AP2 NEW CITY S 20 AP2 NEW STATE S 2 AP2 NEW ZIP S 5 AP2 NEW STATUS S 9 ISAM PLUS file Allocation map template for Mailing List file MAP1 ISAM ALLOCATE MAP ap for ISAM PLUS file creation AP2 ISAM ERROR OFFSET B 2 1 Offset if error in allocate AP2 UMBER RECORDS B 4 200 Maximum number of records AP2 RECORD SIZE B 2 116 Record size in bytes AP2 EXTRA PERCENT B 2 150 Extra idx blks to alloc 0 900 AP2 LOADING FACTOR B 1 100 KSMUTL loading factor 50 100 AP2 RESERVEDO 13 B 1 Reserved for future expansion Primary key definition AP2 Last Name TSAM KEY 0 AP3 LN TYPE B 1 1 Type of key Alphanumeric type AP3 LN RESV 3 B 1 Reserved for future expansion AP3 LN NAME S 20 Last Name Name of key blank filled AP3 LN NULL B 2 0 Null terminator for key name AP3 LN DUP B 1 1 Duplicate keys permitted flag Yes AP3 LN CHNG B 1 1 Key change permitted flag Yes AP3 LN SIZE B 2 20 Size of key characters AP3 LN POS B
68. Size of key characters Position of key in record 1 based Secondary key definition Type of key Concatenated type Reserved for future expansion Key 1 Name of key 20 char Null terminator for key name Duplicate keys permitted flag 0 1 Key change permitted flag 0 1 Size of sub key characters Position of sub key in record 1 based Size of sub key characters Position of sub key in record 1 based Size of sub key characters Position of sub key in record 1 based Terminate list of 1 16 sub keys Terminate key definitions Page B 2 Appendix B ISAM PLUS stats return structure MAP 1 STAT STATS MAP Map for ISAM PLUS file stats AP2 STAT DATA DEVICE B 2 0 RAD50 device name of IDA device AP2 STAT DATA UNIT B 2 0 Device unit number of IDA device AP2 STAT RECORD SIZE B 2 0 Record size in bytes 4 64k AP2 STAT FREE RECORDS B 4 0 Free record count AP2 STAT FREE INDEX B 4 0 Free index block count AP2 STAT TOTAL INDEX B 4 0 Total allocated inde
69. The default file extension is SEQ Is CR LF used as record separator Y N Answer Y if each record contains a CR LF carriage return line feed appended at the end of the record N if not v Make sure you answer correctly or the positions of the keys in the record will be incorrect Each record length is fixed The default answer is N Enter device name for intermediate fil ISMUTL uses an intermediate file ISMKEY REL to store keys in Enter a device name if you want the intermediate file to reside on a device other than the one you are logged into Press if you want the file to reside on the device you are logged into If you do specify a device an account with the same number as the account you are logged into must reside on that particular device If this account does not exist you will get an error trying to open ISMKEY REL Primary key Extracting keys Sorting keys Building index tree Secondary key number 1 Extracting keys Sorting keys Building index tree ISMUTL gives you information on the loading process as it builds the ISAM PLUS index and data files First it extracts keys from the sequential data file then sorts the keys in ascending order Finally it builds the IDX file based on these sorted keys It does this sequence for each key directory you build Make sure ISAM PLUS User s Manual Rev 02 Page 4 8 Chapter Four no error message appears if you see an error you need
70. The example above discusses a data file with one group of keys called a key directory A data file always has one index file containing one or more key directories The first key directory is called the primary key directory additional key directories are called secondary key directories A secondary key directory is structured in the same way as the primary key directory except it contains different symbolic keys For example if we want to base our search of phone book entries on phone numbers as well as names we might construct a secondary key directory that contains phone numbers Primary and secondary key directories are contained within the single index file for a particular data file Although we constructed the previous example ourselves ISAM automatically creates the data file and index file for you in response to information and file specifications you supply In summary an indexed sequential file consists of two random files e The data IDA file containing the actual data records e The index IDX file containing pointers to the data records and symbolic keys for the data file records Your programs search for records by asking for keys in the index Your programs can update individual data records on a random basis and can process a group of records sequentially by key from anywhere in the file You can keep and use several different key directories depending on the needs of your program For example you can access empl
71. W LAS O T NAME THEN GOTO D h found Delete y TH EN DELETE RD 1 R ECO EAS E R ECORD 1 T XT LOCK O VE O DEL OUND SCA ELE E R ECORD 1 AS REC UR EC RI y F ANSWE IDX IDX FO AN PRINT IDX TA UND 0 TO 7 LI R E Index gt 0 A RORB INQUIR INQ RI IF IDX lt gt UIR ELLS E REC 0 PRINT B 5 K ANSWER D ANSWER lt OT a valid index ED 1 LABEL EL NOT FOUND No such last name in file Inquire into file records KYNAM E IDX 1 7 THEN IDX ter index number to initiate inquiry with ANSWER amp GOTO INQUIRE G ET K RY number ter K AM E IDX 1 INQ POS IF INQ REC FOU INQ SCA INQ NOT FOU ESNO I R DWH PHH QAAHAOCADH OMAFAOCOHAS r A A PRI ISAM KEY US US ECNO QU Bhs yS TH RI wu UCS ST GHK G IDX gt STRING LA RING GOTO INQUIRE G ET K BEL ISAM NE HEN GOTO INQ NOT FO ISAM GT T Next UND HEN PRINT PRINT J xact match not found Force access RECNO 0 HE EST
72. X B 2 0 Index number for this key AP 3 SKEYO2 TYPE B 1 3 Type of key Concatenated type AP3 SKEYO02 RESV 3 B Reserved for future expansion AP3 SKEYO2 NAME S 20 Name of key 20 char blank filled AP3 SKEY02 NULL B 2 0 Null terminator for key name AP 3 SKEYO02 DUP B 1 0 Duplicate keys permitted flag AP 3 SKEY02 CHNG B 1 0 Key change permitted flag AP3 SKEY02 SIZE01 B 2 0 Size of sub key characters AP3 SKEY02 POSO01 B 2 0 Position of sub key in record 1 based AP3 SKEY02 SIZE02 B 2 0 Size of sub key characters AP3 SKEY02 POSO02 B 2 0 Position of sub key in record 1 based AP3 SKEY02 SIZE03 B 2 0 Size of sub key characters AP3 SKEY02 POS03 B 2 0 Position of sub key in record 1 based AP3 SKEY02 TRM B 2 0 Terminate list of 1 16 sub keys AP2 STAT TRM B 2 0 Terminate key stats ISAM PLUS stats return structure Duplicate MAP1 STAD STATS MAP Map for ISAM PLUS file stats AP2 STAD DATA DEVICE B 2 0 RAD50 device name of IDA device AP2 STAD DATA UNIT B 2 0 Device unit number of IDA device AP2 STAD RECORD SIZE B 2 0 Record size in bytes 4 64k AP2 STAD FREE RECORDS B 4 0 Free record count AP2 STAD FREE INDEX B 4 0 Free index block count AP2 STAD TOTAL INDEX B 4 0 Total allocated index block count AP2 STAD TOTAL RECORDS B 4 0 Total allocated records count AP2 STAD TOTAL LOADED B 4 0 Total records loaded in use AP2 STAD MIN FREE IDX B 2 0 inimum free index blocks AP2 STAD EXTR
73. XED The templates for the ALLOCATE MAP structure let you set up your parameters in a data structure and then pass them to ISAM PLUS with ALLOCATE INDEXED as follows 1 Make a copy of the templates provided in the file BAS CREATE BAS or BP CREATE BPI 2 Using AlphaVUE paste the templates together and edit them to describe the ISAM PLUS file you wish to create Ensure all the are filled in 3 Specify the name of your file described by the MAP structure in the ALLOCATE INDEXED statement Below is a copy of the templates from BAS CREATE BAS If you want to know more about the MAP statement see your AlphaBASIC or AlphaBASIC PLUS User s Manual ISAM PLUS File Allocation Map Template AP1 ISAM ALLOCATE MAP ap for ISAM PLUS file creation AP2 ISAM ERROR OFFSET B 2 1 Offset if error in allocate AP 2 UMBER RECORDS B 4 Maximum number of records AP2 RECORD SIZE B 2 Record size in bytes 4 64K AP2 EXTRA PERCENT B 2 Extra idx blks to alloc 0 900 AP2 LOADING FACTOR B 1 100 ISMUTL loading factor 50 100 AP2 RESERVEDO 13 B 1 Reserved for future expansion MAP2 Primary key definition Selected from 3 types below MAP2 Secondary key def s Selected from 3 types below 0 64 AP2 ALLOCATE TRM B 2 0 Terminate key definitions Alphanumeric Key Definition Template AP2 ALPHAKEYO1 AAP3 KEYOI1 TYPE B 1 1 Ty
74. YO1 CHNG B 1 Key change permitted flag 0 1 KEYOL SIZEO1 B 2 Size of sub key characters KEYO1 POSO1 B 2 Position of sub key in record KEYO1 TRM B 2 0 Terminate list of 1 16 sub keys GETTING STATISTICAL INFORMATION This section shows how to retrieve information about a file using the INDEXED STATS statement and the STATS MAP structure It also shows how you construct the MAP structure using the templates provided in the file BAS STATS BAS or BP STATS BPI INDEXED STATS There are two different formats for the INDEXED STATS statement Each format causes the statistical information to be gathered in a different way The first format is INDEX This format cau ED STATS f ile channel STATS MAP ses the file statistics to be received from ISAMP SYS It assumes an ISAM PLUS file is open The second format is INDEX ED STATS fspec STATS MAP The second format causes the file stats to be received from ISMUTL LIT The parts of the statements are file channel Channel number on which to open the ISAM PLUS file Fspec File specification giving the device name STATS MAP Map structure to receive the ISAM PLUS file stats See the subsection below for details of structure If the memory area defined by the STATS MAP is too small to hold the stats information the information is truncated to fit ISAM PLUS User s Manual Rev 02 Page 8 10 Chapter Eigh
75. a records in the IDA file If the primary key does not allow duplicate entries ISMUTL will read all the data IDA records clear out the index IDX file and recreate all the index key records When the primary key of the file allows duplicate entries the following message appears Note This file has a primary key which allows for duplicate entries The adding and deleting of records can cause the file to get out of sequence but ISAMP handles this problem by always inserting new duplicate keys at the end of the duplicate key chain Rebuild will rebuild the keys according to the layout of the data file therefore primary duplicate key sequences may get out of order We suggest you use DUMP amp LOAD to rebuild your file Enter C RETURN to continue with the Rebuild or any other key RETURN to Abort Type C to rebuild the file Note that the file may reflect a different primary key sequence than the original database 4 If you want to rebuild the file with the primary key in the same sequence as the original database press any key to abort and then use the DUMP and LOAD commands to accomplish this DELETE Delete an Existing Secondary Key Directory The DELETE command lets you delete an existing secondary key directory The Primary key cannot be deleted Here are the questions and suggested answers ISAM PLUS User s Manual Rev 02 Page 4 12 Chapter Four Enter second
76. ach column on the page to narrow your search further If the name you are searching for falls between the names at the top and bottom of the column you begin to search each entry in that column otherwise you move to the next column on the page In the same way our index file contains a first level index the names at the top of the page then it further divides the data on the page by dividing indices into subgroups of entries on the page the first and last names in each column make up the second level index The final level of indices in the index file consists of lists of names for each column in the book along with the actual record number in our original data file that contains the entry associated with that name Moving through the levels of indices in our index file then we first find the page on which the name appears then we find the column in which the name appears then we find the actual record number for the entry for that name We never need to search the data file itself ISAM PLUS User s Manual Rev 02 Introduction to ISAM PLUS Page 2 3 INDEXED SEQUENTIAL FILES The keys in the index file are grouped in sequence The data records in a file are not arranged in any particular order since we find a data record by searching the index file An ISAM file may contain duplicate keys if you request that feature at the time the file is created that is two or more data records in the data file may have the same symbolic key
77. ading ISAM PLUS inserts new data records on an individual basis When adding a record ISAM PLUS inserts it into the first free record in the data file When deleting a record ISAM PLUS recovers the space in the data file used by that record and returns that area to the free record list so it is available for new records For information on how ISAM PLUS inserts keys into index blocks see the section Inventory of Index Blocks in this chapter Growth of a Data or Index File Because the AMOS operating system requires contiguous files to be pre allocated once an index or data file is full it must be re organized before it can be used further Re organization is very time consuming For this reason allocate as many records as you will need taking into account the growth potential of this file For information on reorganizing files see the discussion of the DUMP and LOAD commands of ISMUTL in Chapter 4 THE INDEX STRUCTURE The ISMUTL program creates the index file from your description of the data file This section discusses the structure of the index file Don t directly modify any data in the index file doing so could damage the structure of your ISAM PLUS file When you use the ISAM PLUS calls and features ISAM PLUS changes the index file for you Multiple Key Directories Each data file must have an index file that has a primary key directory In addition it may have several secondary key directories All key directories for a data f
78. ading factor is used in loading a sequential file through the LOAD menu command It s a percentage that specifies how densely to fill the index block with keys If you press RETURN ISMUTL uses the default of 50 and each index block is half filled If you enter 100 each index block is filled to the maximum capacity There are advantages and disadvantages to either extreme If you fill each index block to the maximum capacity you use less index blocks overall but this may cause a lot of splitting when you update your ISAM PLUS file You must specify a number between 50 and 100 if you enter a number less than 50 ISMUTL uses 50 and if you enter a number greater than 100 ISMUTL uses 100 ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 11 ISMUTL displays the rotating while processing the call unless you used NOP New IDX file created If there is an error your old IDX file still exists renamed to SDX Exit to the AMOS monitor correct the problem rename the SDX file to IDX and then repeat this command You may have to erase an IDX file if one was created If an error occurred during index file creation the new IDX file is incorrect The key sequence may change if you have a duplicate key directory o Make sure you see the message New IDX file created so you know no errors occurred REBUILD Rebuild an Index File The REBUILD command lets you rebuild all primary and secondary keys based on the dat
79. an find records in a different file much more quickly and efficiently than if we had to search the actual data file itself Examples of data for which symbolic keys can be specified are e Customer information the name of the customer is the key that is an element of the data record on which you base your search e Payroll the key is an employee number e Inventory control the key is a part number WHAT IS ISAM PLUS ISAM PLUS is included with AMOS Versions 2 3A and later If you have an older ISAM system see Appendix C for conversion hints and more technical information on how ISAM PLUS differs from ISAM The most notable capabilities of ISAM PLUS are e Compatibility with AMOS 2 3A and later allows larger files and more efficient record locking e Simplified user interface lets you access records with multiple keys in a single instruction e The interactive ISMUTL program lets you create load rebuild change display and analyze ISAM PLUS files e The diagnostic program CISAMP lets you analyze and verify the integrity of ISAM PLUS files HOW DOES ISAM PLUS WORK Finding a convenient and efficient way to access information in a file is an important problem for a programmer Suppose for example you have a phone book of five thousand names and phone numbers If you need to find a specific person s phone number you can start with page one and scan every entry in the book until you find the proper name That process is very
80. ary key number to be deleted Enter the Key Number of the secondary key directory you want deleted ISMUTL displays a rotating while processing the call unless you used NOP Secondary key number n has been deleted m index blocks freed After all index blocks used for this secondary key directory have been deleted ISMUTL tells you how many blocks were freed The key directory header associated with this secondary Key Number is also freed Enter secondary key number to be deleted If you have other secondary key directories you want deleted enter the next key number when prompted Press to stop DUMP Dump an ISAM PLUS File The DUMP command lets you dump an ISAM PLUS file into a sequential file or display it on the terminal If NOX is used the ISAM file is opened non exclusively Here are the questions and suggested answers Output to Enter a file name if you want the output to go to a file the default extension is SEQ Enter TTY if you want the output to go to a terminal don t forget the colon Append CR LF Y N You only see this if you ask to dump the data to a file Answer Y if you want ISMUTL to append a carriage return line feed to each record The default is N The next section covers the message and prompts ISMUTL displays only if you ask to display the data on a terminal The purpose of these questions is to find out if there is a binary number in any non key field because displaying a binary number on t
81. as follows e Enter a device name if you want the data IDA file to reside on a device other than the one you mon are logged into Don t forget to include the after the device name ISAM PLUS User s Manual Rev 02 Page 4 6 Chapter Four e Type if you want the data IDA file to default to the same location as the index IDX file This option allows you the flexibility of moving and copying the ISAM PLUS file from one device to another e Press if you want the data file to reside on the same device you are logged into Use the CHANGE menu option to move or copy either file to a different device later 8 ISMUTL Creates Your File After you have entered all the information ISMUTL creates an empty ISAM file While creating the file ISMUTL displays a rotating bar in a box on the screen to let you know it s running If you used NOP this display is skipped ISMUTL Has Completed Creating Your Files Press the RETURN key to continue Press RETURN ISMUTL then displays the command menu The choices you are given are discussed next THE ISMUTL MENU COMMANDS The ISMUTL menu lists the operations available Alpha Micro Indexed Sequential Access Method Version X X xxx Enter LOAD load a file CHANGE change data device name ADD2ND add secondary key directory DELETE delete existing secondary key directory REBUILD rebuild primary and secondary key indexes DUMP
82. at Index file full The number of free index blocks is down to 0 If this happens during the splitting of an index block your index file may be destroyed It s always a good idea to add extra empty index blocks when you create the file Add extra index blocks and then rebuild the key indexes SMUTL Index structure is smashed Indicates serious structural damage to your index file You may need to rebuild your ISAM PLUS file or rebuild key indexes ISMUTL Invalid key type Type e 1 for alphanumeric e 2 for integer e 3 for concatenated key e 4 for binary key Other key types are invalid Invalid number This is a general message for any invalid number you enter Check your input for errors and try again Invalid record size Enter a number between 4 and 65 535 bytes ISAMP SYS not found You must load ISAMP SYS in MEM or RES before using ISMUTL s functions Key information must be entered Enter the necessary information about a key Key outside record The key is outside the record boundary All keys must be within a record Re enter the key Maximum binary type size 4 Re enter the number making sure it is less than five Maximum extra percentage 900 You can only request up to tenfold the number of index blocks allocated ISAM PLUS User s Manual Rev 02 Error Messages Page A 3 Maximum key size 161 Enter a correct value Maximum number of 2nd key directories 64 Check your a
83. bination ISMUTL creates both files with the name you specified but the data file is created with the extension IDA and the index file is created with the extension IDX If the file already exists ISMUTL does not create a new ISAM PLUS IDX and IDA file but instead displays a menu from which you select the operation you want to apply to the specified ISAM PLUS file The switches are e NOP skips the display of the rotating on the screen e Dis used when loading a file that has keys that don t allow duplicates and you suspect there may be duplicates If this switch is not used when loading such a file an error will occur and LOAD will terminate not completing the task e NOX opens the ISAM file for shared used when using the functions DUMP CHANGE STAT and DESCRP In the following sections we discuss ISMUTL s create function first then each menu command ISAM PLUS User s Manual Rev 02 Page 4 2 Chapter Four CREATING THE DATA AND INDEX FILES Below is a sample terminal session in which ISMUTL creates the ISAM data and index files We have placed the markers 1 to 8 in the margin of Sample 4 1 to make it easier for you to follow the discussion below Please refer to these markers and the sample page as we discuss the prompts the valid data values and the defaults The collating sequence in the current job s language definition file is used for the file being collated and will stay with the file forever SAMPLE 4
84. cking User s Manual DSO 00044 00 e AlphaBASIC PLUS User s Manual DSO 00045 00 e AlphaBASIC User s Manual e AlphaC User s Guide DSO 00205 00 GRAPHICS CONVENTIONS This manual uses Alpha Micro s standard graphics conventions to organize and highlight information and examples Unless stated otherwise all examples of commands are assumed to be entered at AMOS command level 66 Device Name dev is the three letter physical device code and n is the logical unit number Examples of device names are DSKO DSKS WIN1 MTUO Usually device names indicate disk drives but they can also refer to magnetic tape drives and CD ROM drives filespec Identifies a specific file in an account The format is devn filnam ext account For example DSKO SYSTEM INI 1 4 Command and option names are printed in capital letters For example SEARCH Braces indicate optional elements of a command line In the example DIR switch the braces tell you switch is not required ISAM PLUS User s Manual Rev 02 About This Book CTRL REY o Page 1 3 Bold text in an example of user computer communication represents the characters you type Text like this in an example of user computer communication represents characters the computer displays on the screen We also use this typeface for programming samples In our examples the key symbol appears whenever you need to press a key on yo
85. directory No such secondary key number This secondary key has been deleted Number of records dumped don t match number of records in file Key information must be entered Cannot create existing ISAM PLUS file Data file smashed System error ISAM file must be rebuilt For some function calls ISAM PLUS returns status values to let you know the results of an operation They are not errors These are some typical status values ISAM PLUS User s Manual Rev 02 ISAM PLUS and BASIC Page 8 13 Variable Code Meaning Key not found Record not available locked Found key with lesser value Found key with equal value Update succeeded Found key with greater value As mentioned earlier in this chapter the above variables are defined in the include file BAS ISAMP BSI or BP ISAMP BPI you should include in your program with the INCLUDE ISAMP statement After making a request through the appropriate AlphaBASIC statement check the status variable and use the information for program control FILSER Error Codes The AlphaBASIC interface traps error codes returned by the AMOS File Service System in the error byte of the DDB Dataset Driver Block After making a function call for a file or record operation use an ERR O call or the ERF X call to check whether an exceptional condition occurred during the file operation ERR X FUNCTION X is a variable which specifies what type of return value you desire ERR O Ret
86. dition code D1 Number of index blocks allocated excludes key directory headers D2 Offset within record parameter block where error is detected CC 0 if success Input register Al points to the data structure that must contain the following information Al gt Number of records 4 bytes Record size 2 bytes 4 to 64K 1 bytes Extra percentage 2 bytes 0 to 900 in decimal Loading factor 1 byte 50 to 100 in decimal Reserved 13 bytes ISAM PLUS User s Manual Rev 02 Assembly Language Programming Interface to ISMUTL x k k k If type Type of key Reserved Key name description Null Flag allow dup keys Flag key may change Size of key Position of key Type of key Reserved Key name description Null Flag allow dup keys Flag key may change Size of key Position of key Null terminator of key K CONC Type of key Reserved Key name description Null Flag allow dup keys Flag key may change Size of key Position of key Null terminator FE Flag set to nonzero if yes Set type of key to e K ALP for alphanumeric e K BIN for binary e K BBIN for integer K CONC for concatenated 1 byte 3 bytes 20 bytes ASCI 2 bytes 1 byte 1 byte 2 bytes 2 bytes 1 byte 3 bytes 20 bytes ASCI 2 bytes 1 byte 1 byte 2 bytes 2 bytes 2 bytes Page 5 3 Primary key Secondary key Repeat 0 to 64 times to
87. dump ISAM file STAT display statistical information ADDIDX add index block DESCRP change key description EXIT exit to AMOS Enter choice Choose the appropriate command You can type it in lower or upper case ISMUTL recognizes command abbreviations if there is no conflict between command names For example you may type DEL or DELE or DELETE for the DELETE command The next several sections describe what each command does what the prompts are and how you may respond LOAD Load an ISAM PLUS File The LOAD command loads the contents of a sequential file into the ISAM PLUS file Depending on the ISAM PLUS file ISMUTL uses one of two modes to load a file Update mode and New File mode Update mode is used to add new data to an existing ISAM PLUS file without deleting existing data New File mode ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 7 is used when the ISAM PLUS file is empty New File mode is faster than Update mode ISMUTL determines which mode to use These are the questions and answers for the two modes ol In New File mode the collating sequence for the file will be set for the file s lifetime from the gt gt collating sequence defined in your job s active language definition file In Update mode your LDF file is ignored and the collating sequence in the ISAM PLUS file is used instead New File Mode Load from file Enter the name of the sequential file
88. e you must also have a de allocation routine you can t have one P gt without the other The contents of the registers when you call ISAMP SYS and the contents of the registers when ISAMP SYS in turn calls your allocation or de allocation routine are not guaranteed to be the same You must save register A5 and pass it to ISAM PLUS each time you call an ISAM PLUS routine The size of the impure area is approximately 2 700 bytes ISOPN Open File for Processing INPUT A2 Pointer to file spec ASCII A5 ISAM PLUS impure area pointer DO Flag IS EXC Open file in exclusive mode IS PRN Print error messages before returning IS WAT Wait for file if it is in use IS BAK Set file pointer to last record in the file IS RON Read Only mode OUTPUT Al FPN pointer DO Condition code CC 0 if success Following initialization the next routine to call is I SOPN which opens an ISAM PLUS file both IDX and IDA files Open as many ISAM PLUS files as you need Call this routine for each ISAM PLUS file you want opened On a successful open the FPN file pair number assigned to the ISAM PLUS file is returned in Al Do not change the contents of Al Each ISAM PLUS file is referenced by its associated FPN pointer Pass this FPN pointer in Al so ISAM PLUS knows which ISAM PLUS file you are working with The IS EXC flag is used to open the pair of IDX and IDA files exclusively T
89. ely filled and does not include the ROCK block in the calculation each key directory needs 1 ROCK block KSIZ Size of key Greater than or equal to 1 and less than or equal to 161 RECCNT Number of records Greater than or equal to 1 and less than or equal to 2 1 Calculate blocking factor BF ali if KSIZ ODD then BF else BF int 500 KSIZ 5 int 500 KSIZ 6 TOTIDX 0 Total index blocks REPEAT if RECCNT lt BF then goto DONE X Y RECCNT BF X quotient Y remainder if Y lt gt 0 then X X 1 TOTIDX TOTIDX X RECCNT X goto REPEAT 7 DONE TOTIDX TOTIDX 1 end The record size multiplied by the RECCNT divided by 512 must be less than or equal to 2 1 Inventory of Index Blocks ISAM PLUS stores keys and pointers in index blocks Initially the index file is set up with extra index blocks As ISAM PLUS loads the file it spreads free space throughout the file so it can add new keys in the proper sequential order When an index block is full ISAM PLUS splits up the group moving some keys into the next block and inserting the new key in the right place ISAM PLUS checks the supply of extra key locations available If index blocks are running low because of the unexpected demand to add more records ISAM PLUS warns you to replenish the stock For information about
90. equal to e GT Greater than e LE Less than or equal to e LT Less than If the requested key does not exist the record that contains the next higher or lower key value depending on the relation used is returned This capability allows record retrieval without knowing the exact key See Chapter 6 for a more detailed explanation of how to use these operators Read Sequential Reverse Function The default order in a sequential read is ascending To read sequentially in reverse a flag is set which controls the retrieval of a previous record or key instead of the next record or key when the Get Next or Find Next call is issued ISAM PLUS ACCESS MODES AND LOCKS The two access modes share and exclusive allow you access to ISAM PLUS files with or without file locking For efficiency ISAM PLUS locks both the index and data files ISAM PLUS User s Manual Rev 02 ISAM PLUS Features and Capabilities Page 3 7 Share Mode Share mode is the normal mode for assembly language or AlphaBASIC PLUS programs In this mode the same ISAM PLUS file is shared among users of the system In share mode ISAM PLUS always locks the primary key directory or Record 0 at the beginning of each ISAM PLUS call and releases it before returning to you ISAM PLUS will NOT lock it between calls This block is read with the wait flag ON causing your program to pause until the block is available Exclusive Mode Exclusive mode is used by ISMUTL itself to update index
91. erminator for key name AP3 SKEYO1 DUP B 1 0 Duplicate keys permitted flag 0 1 AP3 SKEYO1 CHNG B 1 0 Key change permitted flag 0 1 AP3 SKEYO1 SIZE B 2 0 Size of key characters AP3 SKEYO1 POS B 2 0 Position of key in record 1 based Unsigned Binary Key Stats Template AP 2 BINARYKEYO1 AP2 SKEYO1 INDEX B 2 0 Index number for this key APS SKEYOL1 TYPE B 1 2 Type of key Unsigned binary type AP3 SKEYO1 RESV 3 B 1 Reserved for future expansion AP3 SKEYO1 NAME S 20 Name of key 20 char blank filled AP3 SKEYO1 NULL B 2 0 Null terminator for key name AP3 SKEYO1 DUP B 1 0 Duplicate keys permitted flag 0 1 AP3 SKEYO1 CHNG B 1 0 Key change permitted flag 0 1 AP3 SKEYO1 SIZE B 2 0 Size of key in bytes 1 8 AP3 SKEYO1 POS B 2 0 Position of key in record 1 based Concatenated Key Stats Template AP2 SCONCATKEYO1 AP2 SKEYO1 INDEX B 2 0 Index number for this key APS SKEYO1 TYPE B 1 3 Type of key Concatenated key type AAP3 SKEYO1 RESV 3 B 1 Reserved for future expansion AP3 SKEYO1 NAME S 20 Name of key 20 char blank filled AP3 SKEYO1 NULL B 2 0 Null terminator for key name AP3 SKEYO1 DUP B 1 0 Duplicate keys permitted flag 0 1 AP3 SKEYO1 CHNG B 1 0 Key change permitted flag 0 1 AP3 SKEYO1 SIZEO1 B 2 0 Size of sub key characters AP3 SKEYO1 POSO1 B 2 0 Position of sub key in record AP3 SKEYO1 TRM B 2 0 Terminate list of 1 16 sub keys
92. ext is default IS RON Read Only mode ISAM PLUS User s Manual Rev 02 Page 7 4 Chapter Seven OUTPUT All registers preserved except A3 Contains record pointer if successful DO Condition code D1 Relative record number D2 Found code 0 Found or Not found CC Z set if success This call lets you get the next previous record in key order If the previous call was the FDKEY or FDNXT call GTNXT returns the record whose key you found with FDKEY or FDNXT Right after opening a file you may use this call to scan all the records in the file You can set the file pointer to the last record in the file using the SOPN call then issue a series of Get Previous calls to scan the file in descending order GTNXT updates your current pointer if it finds the record otherwise your current pointer stays the same If you accessed a key with the FDKEY call with an EQ relation and if this record is deleted by another user GTNXT returns the record not found code If you use another relation it locates the next previous record If the record is in use by another user and you don t want to wait your position points to this record as if you are using the FDKEY call This lets you try again If you want to skip this record use the KDNXT call FDKEY Find Key Specified by a Key INPUT Al FPN pointer A2 Symbolic key pointer search key A3 Pointer to key buffer where found key is retu
93. g Find Key or Find Next Previous call and then delete it ISAM PLUS deletes all keys associated with this record from the IDX file Unlock Record Use this call to release a record you locked previously There are three release calls 1 Release the last record locked 2 Release specific record 3 Release all the records Get Statistical Information This call lets you examine the status of a particular ISAM PLUS file Close ISAM PLUS File You must close all ISAM PLUS files opened for processing You may choose to keep the DX file locked after you close it as long as you opened it exclusively at the beginning ISAM PLUS User s Manual Rev 02 Chapter 7 The ISAMP SYS Interface This chapter describes the routines you call and use in your assembly language program to update ISAM PLUS files For more information on when to use these calls see Chapter 6 PREPARATIONS Copy the module DSKO ISMUSR M68 7 7 into your assembly language program using the COPY statement ISAMP SYS must be loaded into MEM or RES You may use the FETCH instruction to load it into user memory ISAMP SYS saves all the registers except those registers that contain output information and D7 THE SPECIFICATIONS This section describes what each routine does and the parameters used in calling the routine In each synopsis the label INPUT refers to the contents of the registers upon entry into the routine The label OUTPUT refers to the registers re
94. g any previous FILENAME file LOOKUP FILENAME IDX FOUND IF FOUND lt gt 0 THEN KILL FILENAME IDX LOOKUP FILENAME IDA FOUND IF FOUND lt gt 0 THEN KILL FILENAME IDA ON ERROR GOTO PRI DELETION COMPLETE ON ERROR GOTO ERROR TRAP PRINT ALLOCATING NEW FILE FILENAME ALLOCATE INDEXED FILENAME ISAM ALLOCATE MAP PRINT PRINT ALLOCATION COMPLETE ON ERROR GOTO ERROR TRAP1 PRI VERIFYING ALLOCATED FILE INDEXED STATS FILENAME STAT STATS MAP DEVRAD50 STAT DATA DEVICE EMP INT DEVRAD50 40 DEVICES RAD5OCHAR DEVRAD50 TEMP 40 1 1 DEVRAD50 TEMP EMP INT DEVRAD50 40 ISAM PLUS User s Manual Rev 02 Page B 4 Appendix B
95. get impure area out of memory FSPEC of REL file INIT of REL file OPENI of REL file SORT failed CLOSE of SW FIL file DSKDEL of scratch file If the error reported is T PFAIL Ax 3 the error was found in the BLDTRE LIT program The table below describes the error conditions in the BLDTRE LIT program Meaning No problem FSPEC of IDX file INIT of IDX file OPENR of IDX file INPUT of IDX file INPUT of IDX file FSPEC of REL file INIT of REL file OPENI of REL file INPUT of REL file OUTPUT of IDX file EOF before this block is filled INPUT failed for IDX file OUTPUT failed for IDX file OUTPUT failed for IDX file OUTPUT chain failed for IDX file ISAM PLUS User s Manual Rev 02 Error Messages Page A 7 Error Code Meaning T CFAIL Ax 16 Numbers of keys does not match records T CFAIL Ax 17 OUTPUT failed for IDX file T CFAIL Ax 18 DSKDEL of REL file ISAM PLUS User s Manual Rev 02 Appendix B Programs Using ISAM PLUS This appendix contains two sample AlphaBASIC programs The first program TEST10 BAS creates and verifies an ISAM PLUS file The second program shows the use of AlphaBASIC statements to access and modify ISAM PLUS records CREATE AND VERIFY AN ISAM PLUS FILE TEST10 BAS INCLUDE ISAMP MAP 1 MAP1 MAP1 MAP1 MAP1 MAP 2 MAP 2 MAP2 MAP 2 MAP1 MAP1 MAP1 MAP 1 ABCD E B 4 0 a ON
96. he IS PRN flag is used to let ISAM PLUS print error messages on the screen The IS WAT flag is used for an IDX and IDA file only during the open call Set this flag ON e To open the file exclusively and you want to wait for the file if it is in use or e To open the file in share mode and you want to wait for the file if it is being used exclusively Individual IDA file records have their own flag which is supplied when you access a record GTREC and GTNXT IS BAK lets you set the file pointer to the last record of the file so you may access records in descending order by issuing Get Previous calls This only applies to the primary key directory For positioning to the last record in a secondary key directory use FDKEY with the highest key and with the LE relation then use a series of Get Previous calls to access the records sequentially in descending order All ISAM PLUS calls except ISINT always return the condition code in DO and set the status code accordingly So you may use the BNE instruction after each call The size of FPN is approximately 3 300 ISAM PLUS User s Manual Rev 02 The ISAMP SYS Interface Page 7 3 bytes If your logical record size is greater than 512 bytes the size of FPN is approximately 2 700 the logical record size GTREC Get a Record Specified by a Key INPUT Al FPN pointer A2 Symbolic key pointer search key A3 Pointer to record buffer where record is returned A5
97. he screen may cause a problem You don t need to enter a binary field that is a directory key ISMUTL already knows that All binary numbers are displayed in either OCTAL or HEX depending on the display mode set for your job Enter non key binary fields This is ISMUTL s opening message to get you ready for the prompts Size of field Enter the size of the non key binary number ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 13 Position of field Enter the position of this binary number Size of field Press RETURN to stop We return now to the DUMP command questions asked for both file and terminal output Enter key number Enter which key directory you want to use Enter 0 for the primary key directory Enter 1 to dump record in ascending order 2 to dump record in descending order Enter choice Type 1 if you want the output in ascending order and 2 if in descending order The default is ascending order n records dumped If you asked to display the data on the terminal you see each record displayed on the terminal DUMP appends a CR LF to the end of each record If you asked to dump the data into a file you see the rotating indicating it is processing the call unless you used NOP After all the records have been dumped ISMUTL tells you how many there are STAT Display Statistical Information STAT lets you view the statistical information about a particular ISAM PLU
98. ile are in the index file ISAM PLUS supports from 0 to 64 secondary key directories Each key directory is given a unique identifying number ISAM PLUS refers to the primary key directory as Key Number 0 The secondary key directories are named Key Number 1 for the first secondary directory Key Number 2 for the second directory and so on up to the 65th directory allowed ISMUTL assigns the Key Numbers for you when you build your ISAM PLUS file You use them to access the ISAM PLUS file For information on adding a secondary key directory to an existing ISAM PLUS file see the information on the ADD2ND command of ISMUTL in the next chapter Multilevel Index ISMUTL structures the index in levels based on two pieces of information you supply the number of data records and the size of the key The logical record size supported under ISAM PLUS is 4 to 65 535 bytes the number of records supported is from 1 up to approximately 2 000 million ISAM PLUS deals with fixed length records ISAM PLUS User s Manual Rev 02 ISAM PLUS Features and Capabilities Page 3 5 Depending on the number of records and the key size ISMUTL formulates the number of levels most efficient for searching the index tree ISAM PLUS may use from 1 to 65 levels the lowest of which contains pointers to the records in the data file The number of index blocks needed is calculated using the formula in the program below This is based on the assumption each block is complet
99. iles for processing The format is OPEN file channel filespec mode relrecno status END F L E WAIT RECORD WAIT FILE READ ONLY file channel Filespec mode relrecno filstat END FILE WAIT FILE WAIT RECORD READ ONLY This is a number you assign to identify the ISAM PLUS file and to reference it from your program for example 1 The file specification names the ISAM PLUS file it may include account and device specifications For example DSKO MASTER 100 1 The access mode may be either INDEXED normal shared access INDEXED EXCLUSIVE exclusive file access A floating point variable that holds the relative record number returned by an ISAM PLUS statement The relative record number may not be used to access a record its purpose is for distinguishing records with duplicate keys and for releasing records A floating point variable that holds the resulting status condition returned after an ISAM PLUS statement Use this option to open the file with the file pointer positioned past the last record based on the primary key When used with GET PREV it allows reverse scanning of an indexed file Use this option to tell the job to wait until access to the file in the mode requested is granted If the record is in use all GET calls will wait until the record is no longer in use by another user If not specified on the OPEN the prog
100. ing order 3 6 4 8 Read sequential reverse 3 6 DESCRP 4 1 4 15 Device name 1 2 devn 1 2 Displaying ISAM file 4 8 Distributed free space 3 4 DLREC call 7 6 Documentation 1 2 DUMP 4 1 4 12 CR LF 4 13 Dumping an ISAM file 5 6 Duplicate key 3 3 4 4 Duplicate keys 2 3 3 6 E END FILE keyword 8 2 EQ operator 6 2 6 3 ERF X function 8 13 ERR X function 8 13 Error messages A 1 Error processing 8 6 8 11 8 13 ERF X function 8 6 Error codes 7 9 8 11 Error Location 8 13 FILSER error codes 8 13 Location 8 13 Trapped error condition codes 8 1 8 11 Exclusive mode 3 6 6 1 EXIT 4 16 Exiting ISMUTL 4 16 EXTRACLLIT 3 1 F FDKEY call 7 4 7 5 FDNXT call 7 4 7 5 File extensions ERR file A 1 A 4 ADA 2 2 LST 8 14 SDX 4 11 IDA file 3 2 4 1 IDX file 2 2 4 1 filespec 1 2 FILSER 5 8 7 9 Error codes 7 9 Errors 8 11 Index FILSER error codes 8 13 Finalizing ISMUTL 5 8 FIND statement 6 1 8 5 Finding next previous key 6 3 FIND NEXT statement 8 5 FIND PREV statement 8 5 G GE operator 3 6 6 2 Get a record by a key 6 2 Get next record 6 3 Get previous record 6 3 GET statement 6 1 8 3 8 5 LOCKED qualifier 8 1 Get statistical information 5 7 8 9 GET LOCKED statement 8 3 8 5 GETMEM 5 1 GET NEXT statement 8 1 8 4 GET NEXT LOCKED statement 8 4 8 5 GETNXT call 6 3 GET PREV statement
101. inted at by Al where error is detected CE Z set if success Input register A1 points to the data structure that must contain Al gt Key number 1 byte Repeat 1 to n times Null terminator 1 byte BCHNG Change IDA File Device Name INPUT AO ISMUTL impure area pointer A2 Pointer to new device name pointer devn in ASCIZ format OUTPUT DO Condition code D1 Negative if IDA file doesn t exist on new device CC Z set if success If the file was flagged with IS NOX when set up with BSET the file is opened non exclusively ISAM PLUS User s Manual Rev 02 Page 5 6 Chapter Five BDUMP Dump ISAM PLUS File INPUT AO A1 A2 DO D1 D2 OUTPUT DO ISMUTL impure area pointer Points to non key field other than alphanumeric if dumping to a terminal otherwise ignore it Pointer to output file spec in ASCIZ format if dumping into a file Set to zero if dumping to a terminal Flag IS CRL Append CR LF after each record ignored if dumping to a terminal a CR LF is always appended if dumping to a terminal Key number or specifier Direction or 0 Ascending Descending Condition code Number of records dumped Where error is detected Z set if success offset within non key field information block Input register A1 points to the data structure that must contain this information if you re dumping to a
102. into MEM Save ISMUTL LIT address Page 5 9 Page 5 10 Now we are ready to initialize ISMUTL SUB A3 A3 SUB A4 A4 MOV SYSADR A5 A6 CALL BINIT A6 Setting up file Note A2 points to the file name from the MOVB IS PRN DO MOV SYSADR A5 A6 CALL BSET A6 BNE 20 TYPECR lt Error File already exist gt JMP DONE Now set up record parameter 20 LEA Al RECPRM A5 MOV 2000 Al MOVW 120 Al MOVW 100 Al MOVB 90 Al ADD 13 5 pA Primary key MOVB K ALP Al ADD 3 Al key description LEA A6 CUSNUM CALL MOVDES CLRB Al CLRB Al OVW 6 Al OVW 5 Al Secondary key 1 OVB K ALP Al ADD 3 Al key description EA A6 CUSNAM CALL MOVDES OVB 1 Al CLRB Al OVW 25 Al OVW 15 Al Secondary key 2 OVB K CONC Al ADD 3 Al key description EA A6 SPACES CALL MOVDES MOVB 1 A1 MOVB 1 A1 Ne Ne Ne Ne Ne Ne Chapter Five No allocation routine No de allocation routine Get ISMUTL LIT address Call the initialization routine ISMUTL returns its memory base in AO Do not change the content of AO command line Ne Ne Ne Ne Ne Ne NE Ne Ne Ne Ne Ne SNe e Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Flag Print error message if it occurs ISMUTL LIT address Call the set u
103. ion AP3 STAT NAME S 20 Status Name of key blank filled AP3 STAT NULL B 2 0 Null terminator for key name AP3 STAT DUP B 1 1 Duplicate keys permitted flag Yes AP3 STAT CHNG B 1 1 Key change permitted flag Yes AP3 STAT SIZE B 2 9 Size of key characters AP3 STAT POS B 2 108 Position of key in record 1 based Secondary key Concatenated MAP2 Hash TSAM KEY 7 AP3 HASH TYPE B 1 3 Type of key Concatenated type AP3 HASH RESV 3 B 1 Reserved for future expansion AP3 HASH NAME S 20 Hash Name of key blank filled AP3 HASH NULL B 2 0 Null terminator for key name AP 3 HASH DUP B 1 1 Duplicate keys permitted flag Yes AP 3 HASH CHNG B 1 1 Key change permitted flag Yes AP3 HASH SIZEO1 B 2 1 Size First letter of last name AP3 HASH POSO1 B 2 01 Position of sub key in record 1 based AP3 HASH SIZE02 B 2 2 Size State abbr AP3 HASH POS02 B 2 101 Position of sub key in record 1 based AP3 HASH SIZE03 B 2 1 Size Third letter of last name AP3 HASH POS03 B 2 03 Position of sub key in record 1 based AP3 HASH SIZE04 B 2 3 Size Last 3 digits of zip AP3 HASH POS04 B 2 105 Position of sub key in record 1 based AP3 HASH SIZE05 B 2 1 Size First letter of first name AP3 HASH POS05 B 2 21 Position of sub key in record 1 based AP3 HASH TRM B 2 0 Terminate list of 1 16 sub keys MAP2 ALLOCATE TRM B 2 0 Terminate key definitions START Check if file exists if not create i
104. l ISAM KEY knum rel kval retkey or FIND NEXT file channel retkey or FIND PREV file channel retkey retkey is the variable to contain the key of the located record It is assumed retkey is of the correct type and size to receive the key The status value assigned to the file s status variable is one of ISAM NF 3 Key not found ISAM LT 1 Found key with lesser value ISAM EQ 0 Found key with equal value ISAM GT 1 Found key with greater value If the key is found the relative record number variable is updated FIND NEXT and FIND PREV return these values in the status variable ISAM NF 3 Key not found ISAM EQ 0 Found key with equal value Examples D 1 ISAM KEY 1 gt JONES FOUND KEY D NEXT 2 NEXT KEY D PREV 3 PREV KEY rr 222 UPDATE RECORD The UPDATE RECORD statement is used to update the file by writing to the current record All of the indices are automatically updated based on the file s knowledge of where each key is located within the record The format is UPDATE RECORD file channel varlist Because the UPDATE statement updates the last record successfully obtained by a GET or located by a FIND and because failure of a GET or FIND operation doesn t update the current relative record number you should rigorously check the status after these operations Failure to do so may result in the update going to
105. le key directories 3 4 N New File Mode 4 7 NOX 5 7 Page 4 O OPEN statement 8 2 8 3 END FILE keyword 8 2 INDEXED keyword 8 2 INDEXEDEXCLUSIVE keyword 8 2 READ ONLY keyword 8 2 WAITFILE keyword 8 2 WAIT RECORD keyword 8 2 Opening an ISAM file 7 2 P Primary key Rebuild 5 8 Primary key directory 2 3 3 4 3 7 4 4 PTREC call 7 6 PUT statement 6 1 R Read Ascending order 3 6 Descending order 3 6 Record 6 1 Sequential Reverse 3 6 READ ONLY keyword 8 2 REBLD call 5 8 REBUILD 4 11 Rebuild key 5 8 Record Fixed length 3 4 4 7 Size 4 3 Record size 3 4 RELAL call 7 7 Relational operators EQ 6 2 GE 6 2 GT 6 2 LE 6 2 LT 6 2 Relative record number 2 2 3 6 RELEASE ALL statement 8 6 RELEASE RECORD statement 8 6 RELRC call 7 6 RELSE call 7 6 S S KEY variable 8 15 Sample assembly language program 5 8 Sample ISMUTL terminal session 4 2 Sample screen display 4 13 SDX file 4 11 Search key relations 3 6 Index Secondary key Rebuild 5 8 Secondary key directory 2 3 3 4 Adding 4 9 5 4 Deleting 5 5 Key number 3 4 Multiple 3 4 Share mode 3 6 6 1 SORTKY LIT 3 1 Standard definitions 6 1 Add new record to a file 6 4 Close ISAM PLUS file 6 4 Delete existing record 6 4 Find next previous key 6 3 Get next previous key 6 3 Get record specified by a key 6 2 Get statistical information 6 4
106. ll variables are 1 byte long n All the error code numbers returned in the following error messages are decimals If the error reported is T PFAIL Ax 0 the error was found in the ISMUTL LIT program The table below describes the error conditions in the ISMUTL LIT program Error Code Meaning LCFAIL Ax 0 No problem LCFAIL Ax 1 Problem in load file I DDBERR Ax DDB error code L CFAIL Ax 2 Problem in device name for temporary file I DDBERR Ax DDB error code L CFAIL Ax 3 Problem reading key rock block I DDBERR Ax DDB error code o For the following cases T DDBERR Ax will be set with the DDB error when appropriate ISAM PLUS User s Manual Rev 02 Error Messages Page A 5 If the error reported is T PFAIL Ax 1 the error was found in the EXTRAC LIT program The table below describes the error conditions in the EXTRAC LIT program Error Code T CFAIL Ax 0 T CFAIL Ax 1 T CFAIL Ax 2 T CFAIL Ax 3 T CFAIL Ax 4 T CFAIL Ax 5 T CFAIL Ax 6 T CFAIL Ax 7 T CFAIL Ax 8 T CFAIL Ax 9 T CFAIL Ax 10 T CFAIL Ax 11 T CFAIL Ax 12 T CFAIL Ax 13 T CFAIL Ax 14 T CFAIL Ax 15 T CFAIL Ax 16 T CFAIL Ax 17 T CFAIL Ax 18 T CFAIL Ax 19 T CFAIL Ax 20 T CFAIL Ax 21 T CFAIL Ax 22 T CFAIL Ax 23 T CFAIL Ax 24 T CFAIL Ax 25 T CFAIL Ax 26 T CFAIL Ax 27 T CFAIL Ax 28 ISAM PLUS User s Manual Rev 02 Meaning
107. ms that creates and maintains indexed sequential files and a set of assembly language subroutines that lets you access and modify data records This chapter introduces the modules that make up the ISAM PLUS system and discusses the following concepts The pair of ISAM files The index structure Operations on records ISAM PLUS access modes and file locking We also discuss some of the techniques ISAM PLUS uses to achieve overall system efficiency One index file per data file for effective memory use Multilevel index structure to speed up searching Multiple keys provide alternate paths to a single record Distributed free space for insertion of new records TO locking to control concurrent sharing of a file preventing damage to data caused by simultaneous record updates THE ISAM PLUS MODULES ISAM PLUS consists of seven modules ISAMP SYS ISMUTL LIT CISAMP LIT BLDTRE LIT EXTRAC LIT SORTKY LIT ISMUSR M68 Following is a brief description of each module ISAM PLUS User s Manual Rev 02 Page 3 2 Chapter Three ISAMP SYS ISAMP SYS is the library of functions which perform the various record operations This program is in account DSKO 1 4 but must be loaded into MEM or RES before you process an ISAM PLUS file ISMUTL LIT ISMUTL LIT provides various file access services Some of ISMUTL s abilities include building an ISAM PLUS data file and its index file moving the initial group of records into the data file and a
108. nter A2 Pointer to statistics area D1 A2 buffer size in bytes DO z set if success A2 Pointer to statistics area CC 0 if success Output A2 points to the data structure that contains A2 gt Data device name siz Data device unit number Record size Free record count Free index blocks count Total index blocks allocated Records allocated Records loaded Minimum empty index blocks Extra index block percentage Date created Number of 2nd dir A Number of active 2nd dir Date rebuilt Reserved Key specifier number Type of key Reserved Key name description Null terminator Allow duplicate keys flag May change key flag Size of key Position of key Null terminator ISAM PLUS User s Manual Rev 02 aAANNN aNNARA oe NMOWF DN NONE t bytes bytes bytes bytes bytes bytes bytes bytes bytes bytes bytes 1 byte byte bytes bytes bytes byte bytes bytes bytes byte byte bytes bytes bytes Page 7 7 packed form exclude header blocks Separated format include deleted key directories Repeat Page 7 8 Chapter Seven If type of key K CONC Key specifier number 2 bytes Type of key 1 byte K CONC Reserved 3 bytes Key name description 20 bytes Null terminator 2 bytes Allow duplicate keys flag 1 byte May change key flag 1 byte Size of key 2 bytes Repeat 1 to Position of key
109. o a terminal A2 Pointer to DDB or buffer address depending on flag zero if outputting to a terminal OUTPUT None Updated A2 if outputting to memory This routine enables you to display ISAM related error messages Use the SYSMSG monitor call to display a FILSER error REBLD Rebuild Primary and Secondary Keys INPUT DO FLAGS PF NDSPL Don t display box and rotating bar OUTPUT DO Condition code CC Z set if success BFIN Finalize ISMUTL INPUT AQ ISMUTL impure area pointer OUTPUT CC z set if success This routine to de allocate memory is the last routine you call SAMPLE ASSEMBLY LANGUAGE PROGRAM SAMPLE 5 1 Sample program to create an ISAM PLUS file This program creates an ISAM PLUS file with the following information aximum number of records 2000 Logical record size 120 bytes Extra index blocks 100 double it Loading factor 90 Primary key Type Alphanumeric Description Customer number Duplicate key No Change key No Size 6 bytes Position 5 NE NE NE Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Ne Se ISAM PLUS User s Manual Rev 02 Assembly Language Programming Interface to ISMUTL Secondary key 1 Type Description Duplicate key Change key Size Position Secondary key 2 Type Description Duplicate key Change key Field 1 Size Position Field 2 Size Position Field 3 Size Position Field 4 Size Position
110. of key CC Z set if success You may use this call to position within an ISAM PLUS file UPREC Update Existing Record INPUT Al FPN pointer A3 Pointer to record buffer where new record is stored A5 ISAM PLUS impure area pointer DO Flag IS LOC Leave record locked if fail IS EXC Leave record locked if success OUTPUT All registers preserved except DO Condition code D1 Relative record number updated CC Z set if success This call lets you update a record You must lock the record you want to update You may use the ADKEY or FDNXT call to position the record and then update it as long as it is locked UPREC updates all the keys which are allowed to change as specified by the new record data PTREC Add a New Record to File INPUT Al FPN pointer A3 Pointer to record buffer A5 ISAM PLUS impure area pointer OUTPUT All registers preserved except DO Condition code D1 Relative record number used CC Z set if success ISAM PLUS User s Manual Rev 02 Page 7 6 Chapter Seven Use this call to add a record to a file ISAM PLUS adds every key into the IDX file Duplicate keys are added at the end of a set of identical values Your current position is not changed by this call DLREC Delete Existing Record INPUT Al FPN pointer A5 ISAM PLUS impure area pointer OUTPUT All registers preserved except
111. ondary key number 4 Type of key 7 351 index blocks will be allocated Enter extra index blocks percentage 100 702 total index blocks will be allocated Enter loading factor 90 Data file Device 8 Press the RETURN key to continue The ISMUTL Display The following paragraphs discuss the ISMUTL file creation display Each numbered section below refers to the correspondingly numbered section in the display above 1 Defining Your Data File Number of records to allocate Enter the number of records you want to create taking into consideration the growth potential of this file We suggest you enter the maximum number of records you think you might need because expanding a data file is time consuming Size of Data Record Enter the record size ISAM does not support variable length records The minimum record size is 4 bytes and the maximum is 65 535 bytes 2 Key Code Display ISMUTL displays codes for the four types of keys Type of key Enter 1 for Alphanumeric type Enter 2 for Integer type Enter 3 for Concatenated keys type Enter 4 for Binary type These descriptions tell you which numeric code to enter when specifying the type of key for key directories Alphanumeric is an ASCII character string Integer is for AlphaBASIC PLUS integer data types only Concatenated key is a combination of multiple ASCII fields from within the record Binary means ISAM PLUS User
112. or the offset of the program line where the error occurred depending on the switch used to compile the program The error reporting mechanisms are discussed in the section Error Processing See Chapter 4 for other file maintenance services provided by the ISMUTL program See Appendix B for a sample AlphaBASIC program that creates and tests an ISAM PLUS file That appendix also contains a sample AlphaBASIC program that shows the use of the ISAM PLUS statements to access and modify ISAM PLUS records UPDATING THE RECORDS OF AN ISAM PLUS FILE This section describes the statements for positioning the file pointer reading writing adding deleting locking and unlocking the records of an ISAM PLUS file Each description includes a particular statement explaining the parameters variables trapped errors and status values The GET GET NEXT and GET PREV verbs with the qualifier LOCKED let you locate read and lock a record all in a single statement True I O record locking is done That is when a record is locked there is no impact on the ability of another user to access the file or lock different records ISAM PLUS User s Manual Rev 02 Page 8 2 Chapter Eight Variables used to hold status conditions returned by ISAM PLUS are defined in the file BAS ISAMP BSI or BP ISAMP BPI Your programs should have a INCLUDE ISAMP statement to include this definition file OPEN Statement The OPEN statement opens a pair of ISAM PLUS f
113. otal records STAD TOTAL RECORDS PRINT Total loaded records STAD TOTAL LOADE PRINT in free index blocks STAD MIN FREE IDX PRINT Extra index block STAD EXTRA PERCENT IF EXTRA PERCENT lt gt STAD EXTRA PERCENT THEN amp PRINT ERROR PREFIX EXTRA PERCENT ISMATCH PRINT Creation date STAD CREATE MONTH PRINT STAD CREATE DAY PRINT STAD CREATE YEAR PRINT DOW STAD CREATE DOW 1 SYSTEM BINDATE DATE IF SYSTEM DATE lt gt STAD CREATE DATE THEN amp PRI ERROR PREFIX DATE IS INCORRECT PRINT Verifying Primary Key PRINT Key index SKEY11 INDEX IF SKEY11 INDEX lt gt 0 THEN amp PRI ERROR PREFIX INDEX MISMATCH PRINT Key type KEY TYPE SKEY11 TYPE IF SKEY11 TYPE lt gt KEYOI1 TYPE THEN amp PRINT ERROR PREFIX KEY TYPE MISMATCH PRINT Key name SKEY11 NAME IF SKEY11 NULL lt gt 0 THEN amp PRI ERROR PREFIX KEY NAME NULL NOT NULL PRINT Key dup flag SKEY11 DUP IF SKEY11 DUP lt gt KEYO1 DUP THEN amp PRI ERROR PREFIX KEY DUP FLAG MISMATCH PRINT Key change flag SKEY11 CHNG ISAM PLUS User s Manual Rev 02 Page B 6 Appendix B
114. ou don t want to record any information press RETURN Are duplicate keys allowed for this directory index Y N Type Y for Yes N for No The default is N Are keys allowed to change during updating Y N This question lets you specify whether the keys in a record can be modified when the record itself is modified Type Y for Yes N for No The default is N Size of key Enter the length of the field you chose as the secondary key The maximum size for an alphanumeric or concatenated key is 161 The maximum size for a binary key is five and four for an integer key Position of key Enter starting key position The first byte of a record is Position 1 ISMUTL keeps asking questions about the secondary key directories you want created until you terminate by pressing to the prompt Type of key The next set of questions and messages is similar to group 7 under the section Creating a Pair of ISAM PLUS Files in this chapter The only difference here is ISMUTL does not request the Data file Device because it uses the existing IDA file Here are the questions and answers Enter extra index blocks percentage Enter the percentage of extra index blocks you want ISMUTL to allocate You may enter 0 to 900 The value 0 means you don t need an extra index block If you enter 100 ISMUTL doubles the minimum number allocated The default is 100 we suggest you enter at least this percentage Enter loading factor The lo
115. oyee records by employee name by employee number or by social security number If you want to access the records by all of these keys the primary key directory might consist of the employee names and the secondary key directories might consist of employee and social security numbers ISAM PLUS AS A PROGRAMMING TOOL Alpha Micro s ISAM PLUS expands upon the basic index method by providing extended features for using search keys maintaining the index file and concurrent updating of a shared database The ISAM PLUS system is supplied with AMOS It is a set of programs you can call and use in your application programs to create and access indexed sequential files in a multi user environment ISAM PLUS performs these commonly needed data management tasks e Allocates disk storage for the number of records specified and defined for an ISAM PLUS file e Creates the primary key and secondary key directories for selected record fields e Loads data into the data file and adds keys and pointers into the index file e Manages record operations retrieval insertion deletion and modification ISAM PLUS User s Manual Rev 02 Page 2 4 Chapter Two e Controls the exclusive or shared use of ISAM PLUS files In the next chapter we discuss Alpha Micro s implementation of the indexed sequential access method ISAM PLUS User s Manual Rev 02 Chapter 3 ISAM PLUS Features and Capabilities Alpha Micro s ISAM PLUS system is a set of progra
116. p routine Ok file not found Output message Close the file and exit Record parameter address umber of records Size of records Extra index block percentage Loading factor Skip reserved area of 13 bytes Type of key alphanumeric Skip reserved area of 3 bytes A6 points to Customer number Call the routine to transfer key description and 2 bytes null Flag no duplicate keys are allowed Flag can t change key during updating Size of key Position of key Type of key alphanumeric Skip reserved area of 3 bytes A6 points to Customer name Call the routine to transfer key description and 2 bytes null Flag duplicate keys are allowed Use any non zero value Flag can t change key during updating Size of key Position of key Type of key concatenated key Skip reserved area of 3 bytes None use spaces Call the routine to transfer key description and 2 bytes null Flag duplicate keys are allowed Flag can change key during updating ISAM PLUS User s Manual Rev 02 Page 5 11 Assembly Language Programming Interface to ISMUTL Field 1 OVW 3 Al OVW 1 Al Field 2 OVW 10 Al OVW 100 Al Field 3 OVW 5 Al OVW 75 A1 Field 4 OVW 2 A1 OVW 20 A1 End of concatenated key CLRW Al Secondary key 3 MOVB ADD K BIN Al 3 Al key description LEA A6 SPACES CALL MOVDES MOVB 1 Al MOVB 1 Al MOVW
117. pe of key Alphanumeric type AP3 KEYO1 RESV 3 B 1 Reserved for future expansion AP3 KEYO1 NAME S 20 Name of key 20 char blank filled AP3 KEYO1 NULL B 2 0 Null terminator for key name AP3 KEYO1 DUP B 1 Duplicate keys permitted flag 0 1 AP3 KEYO1 CHNG B 1 Key change permitted flag 0 1 AP3 KEYO1 SIZE B 2 Size of key characters AP3 KEYO1 POS B 2 Position of key in record 1 based ISAM PLUS User s Manual Rev 02 ISAM PLUS an P2 P3 P3 P3 PS P3 P3 P3 PS Ppp pp ppp P2 P3 P3 P3 P3 P3 P3 P3 P3 P3 D Dp ppp ppp D d BASIC Page 8 9 Unsigned Binary Key Definition Template BINARYKEYO1 KEYOL TYPE B 1 2 Type of key Unsigned binary type KEYOL RESV 3 B 1 Reserved for future expansion KEYO1 NAME S 20 Name of key 20 char blank filled KEYO1 NULL B 2 0 Null terminator for key name KEYO1L DUP B 1 Duplicate keys permitted flag 0 1 KEYO1 CHNG B 1 Key change permitted flag 0 1 KEYO1 SIZE B 2 Size of key in bytes 1 8 KEYO1 POS B 2 Position of key in record 1 based Concatenated Key Definition Template CONCATKEYO1 KEYO1 TYPE B 1 3 Type of key Concatenated key type KEYOL RESV 3 B 1 Reserved for future expansion KEYO1 NAME S 20 Name of key 20 char blank filled KEYO1 NULL B 2 0 Null terminator for key name KEYO1L DUP B 1 Duplicate keys permitted flag 0 1 KE
118. ram may request this option each time you access the record This option lets you open a file for read only access You cannot change any data but you can read it whether it s locked or not The above four optional parameters may be specified in any order ISAM PLUS User s Manual Rev 02 ISAM PLUS and BASIC Page 8 3 GET and GET LOCKED The GET statement permits random access by key value This and other random access statements return status values and if the access is successful the associated relative record numbers GET LOCKED locks the record for update and has the same syntax as GET The format is GET file channel WAIT RECORD ISAM KEY knum rel kval varlist file channel Channel number specified in the OPEN WAIT RECORD Waits for locked records knum The key specifier assigned by ISAM PLUS when you created the file primary key is 0 secondary keys are identified starting with Key Number 1 rel The search key relation between the specified key and the record in the file Can be Equal to gt Greater than lt Less than lt Less than or equal gt Greater than or equal kval The value of the key to search for varlist List of variables to store the record in The status value returned in the status variable specified in the OPEN statement is one of ISAM NF 3 Key not found ISAM NA 2 Record not available locked ISAM LT 1 Found key with value less than that specified in kval
119. reated ISAM PLUS file with the sequential file you created in Step 1 again using ISMUTL 4 Change your program to use the ISAM PLUS calls as described in this manual DIFFERENCES BETWEEN ISAM AND ISAM PLUS Under ISAM there was a separate index file for each key directory Under ISAM PLUS all directories reside in one index file Under ISAM the utility programs were invoked separately from AMOS command level Under ISAM PLUS all utility programs reside in one module named ISMUTL and are operated from a menu system ISAM PLUS has many features not available in ISAM They are e Compatibility with AMOS extended file format e True record I O locking e A fixed two file format that is one IDX and one IDA file e Duplicate keys for primary directory as well as secondary key directories e Binary key ranging from 1 to 5 bytes e Alphanumeric key size ranging from 1 to 161 bytes e Concatenated keys formed by joining up to 16 fields total size of 161 bytes e Logical record size ranging from 4 to 65 535 bytes e Secondary directories from 0 to 64 in number ISAM PLUS User s Manual Rev 02 Page C 2 Appendix C e Reverse sequential retrieval of records based on key value e Five relational operators LE EQ LT GT GE used with the search key e Interfacing to ISMUTL through an assembly language program e Use of a language table for defining the collating sequence e Easy to use calling sequence ISAM PLUS User s
120. rimary key The maximum key size for an alphanumeric or concatenated key is 161 The maximum size for a binary key is 5 for an integer key it is 4 Position of key Enter the column number of the position of this field in the record The first byte of a record is Position 1 4 Defining the Secondary Key Directories Secondary key number n ISAM displays this message to tell you it s ready to gather information about each of the secondary keys where n is the internal Key Number of the secondary key directory beginning with 1 and incrementing up to a maximum of 64 until you indicate you have no more secondary keys ISAM PLUS User s Manual Rev 02 Using ISMUTL in Interactive Mode Page 4 5 ISMUTL displays the same questions for every secondary key directory as it did for the primary key directory See Item 3 above for information on each of the questions 5 Questions for Concatenated Key Type If you have selected the concatenated key type ISMUTL repeats the questions Size of key and Position of key for each field forming the key Press to indicate you have no more fields to enter to go on to the next question The maximum number of repetitions is 16 letting you combine up to 16 subkeys 6 Signaling the End of Secondary Key Directories When you have entered all the information about all the secondary key directories press when ISMUTL asks for Type of key This finishes secondary key directory definition 7 IS
121. rned A5 ISAM PLUS impure area pointer D1 Key index specifier D2 Relation IS EQ Equal IS GT Greater S GE or IS GT IS EQ Greater or Equal IS LT Less than IS LE or IS LT IS EQ Less than or Equal OUTPUT All registers preserved except A3 Contains key found pointer if success DO Condition code D1 Relative record number D2 Found code IS EQ Found with equal key value IS GT Found with greater key value IS LT Found with lesser key value IS NF Not found file is empty or unable to find key with the relation given D6 Size of key CC Z set if success ISAM PLUS User s Manual Rev 02 The ISAMP SYS Interface Page 7 5 Use this call to position the pointer in a file It returns the key it finds The relative record number returned is for your information only If you want to read the record use the GTNXT call If FDKEY finds the key it updates your current position FDNXT Find Next Previous Key INPUT Al FPN pointer A3 Pointer to key buffer where found key is returned A5 ISAM PLUS impure area pointer DO Flag S BAK Descending Ascending is default IS RON Read Only mode OUTPUT All registers preserved except A3 Contains found key pointer if success DO Condition code D1 Relative record number D2 Found code 0 Found it S350 oe Not found D6 Size
122. rors are trapped RELEASE RECORD Use this call to release the last record accessed or to release a specific record using its relative record number The format is RELEASE RECORD file channel recno The optional parameter recno specifies the relative record number to be released The default record number is the record last accessed successfully from the file using GET or FIND Releasing an unlocked record is not an error All errors are trapped RELEASE ALL This call releases all the locked records The format is RELEASE ALL file channel RELEASE ALL normally does not produce errors Any errors returned by ISAM PLUS are trapped ISAM PLUS User s Manual Rev 02 ISAM PLUS and BASIC Page 8 7 CLOSE You must close all ISAM PLUS files opened for processing The format is CLOSE file channel The file channel is the number assigned to the file by a previous OPEN statement CLOSEK This call closes the ISAM PLUS file but keeps it locked so the next program in the process can access it The format is CLOSEK file channel The file channel is the number assigned to the file by a previous OPEN statement UNLOKR This statement explicitly unlocks the last successfully accessed record It is functionally equivalent to a RELEASE RECORD file channel statement and is included for compatibility reasons The format is UNLOKR file channel The file channel is
123. routines in a convenient way through AlphaBASIC or AlphaBASIC PLUS statements ISAM PLUS BASIC statements are supported only in AlphaBASIC Versions 1 4 and later available under AMOS Versions 2 3A and later ISAM PLUS works with all versions of AlphaBASIC PLUS Throughout this chapter we ll use the term AlphaBASIC to mean either AlphaBASIC or AlphaBASIC PLUS ISAM PLUS files may be created interactively as shown in Chapter 4 of this manual If you want to create ISAM PLUS files from within AlphaBASIC programs the interface to the ISMUTL program provides a method using a parameter passing device called a map structure You can learn how to construct this structure from templates supplied with the AlphaBASIC compiler We also show a map structure you can include in your AlphaBASIC program to gather statistical information about an ISAM PLUS file for examination This chapter defines the AlphaBASIC statements you can use for doing these tasks e Updating the records of an ISAM PLUS file e Creating an ISAM PLUS file e Retrieving statistical information We also discuss how errors and the results of an operation can be reported back to the calling program The AlphaBASIC interface traps error codes returned by ISAM PLUS functions letting you check the status after each function call and take appropriate action During file creation the interface also traps condition codes from the AMOS file service system The RUN command reports the line number
124. sion 00 AMOS 2 0 Printed 3 88 A new part number was assigned to this book DSO 00012 00 and it was re written and re organized The user interface was completely changed for this version of ISAM so the book contains all new information on AlphaBASIC statements assembly language calls and interactive programs The product was renamed from ISAM to ISAM PLUS Revision 01 AMOS 2 2 Printed 4 91 Reprinted the manual to include new information about file locking Revision XX AMOS 2 3A Printed 10 97 Reprinted the manual to include new information about the use of CISAMP Reformatted manual ISAM PLUS User s Manual Rev 02 A Access modes 3 6 Exclusive 3 6 6 1 Share 3 6 6 1 Accessing records 3 6 ADD2ND 4 9 ADDIDX 4 15 A 1 Adding Index blocks 4 5 4 13 4 15 5 6 A 1 New record 3 4 6 1 6 4 7 6 Secondary key directory 4 4 4 9 5 4 ALLOCATE INDEXED statement 8 7 8 8 Allocating memory 5 1 Allocation de allocation routines 5 1 7 8 Alpha C 1 1 AlphaBASIC 8 1 ALLOCATE TINDEXED 8 8 ALLOCATE INDEXED statement 8 7 CLOSE 8 7 CLOSEK 8 7 CREATE RECORD 8 6 DELETE RECORD 8 6 ERF X function 8 13 ERR X function 8 13 Error codes 8 11 Error processing 8 6 8 11 FILSER error codes 8 13 FIND 8 5 FIND NEXT 8 5 FIND PREV 8 5 GET 8 1 8 3 8 5 GET LOCKED 8 3 8 5 GET NEXT 8 1 8 4 GET NEXT LOCKED 8 4 8 5 GET PREV 8 1 8 4 GET PREV LOCKED 8 4 8
125. ssembly language program This message only appears in an assembly language interfacing with ISMUTL 2No such secondary key number Either create the secondary key number or change your reference Number of records dumped is mismatched with the number of records in the file There is an inconsistency between the number of records dumped and the number of the records in the file This usually means your index file is damaged You may see this message if you are dumping the file and you use CTRLYC before the task is done Overlap keys must be alphanumeric type You may not define any byte in the record as both binary and alphanumeric type You may define any byte as alphanumeric and concatenated key since a concatenated key is an alphanumeric key which is formed by combining alphanumeric fields into one key Primary key information must be entered ISAM PLUS must have a primary key enter the necessary information System error Indicates a serious error If you see this contact your Alpha Micro representative with information on the conditions under which the error occurred This secondary key has been deleted You are trying to access a secondary key directory which was deleted This message also appears when you re trying to get statistical information about a deleted directory Too many concatenated fields The number of sections in a concatenated key may not exceed 16 This message only appears if your assembly language program
126. ssigning addresses and keys in the index and performing various operations to maintain and adjust an ISAM PLUS index file such as adding a secondary key directory to the index file You may use ISMUTL LIT at AMOS command level as well as through an assembly language interface If you are interfacing ISMUTL LIT to your assembly language program load ISMUTL LIT into MEM or RES Alternatively you may use the assembly language FETCH instruction to load ISMUTL CISAMP LIT CISAMP LIT provides various diagnostic services It displays the root information of the file reads through the file to check its integrity and reads all data records and verifies each key in the data record EXTRAC LIT SORTKY LIT and BLDTRE LIT EXTRACT LIT SORTKY LIT and BLDTRE LIT are used by ISMUTL LIT to extract sort and build the key structures in the ISAM PLUS index file ISMUSR M68 ISMUSR M68 contains the ISAM PLUS symbol table and entry vectors You use this file to interface assembly language programs to ISAMP SYS or ISMUTL LIT The program is in account DSKO 7 7 Use the assembly language COPY statement to transfer ISMUSR M68 into your program THE PAIR OF ISAM PLUS FILES Every indexed sequential file created for you by ISAM PLUS consists of two contiguous files the data IDA file and the index IDX file To build an ISAM PLUS file you define your data file giving the number of records to allocate and the record size as shown in Chapter
127. t Any errors in INDEXED STATS are trapped Use ERR to get the error code It is not an error for STATS MAP to be too small uv The second format above requires ISMUTL LIT to be loaded in system or user memory Templates for INDEXED STATS The templates for the STATS MAP structure let you gather and examine the statistics of an ISAM PLUS file To properly construct a MAP you must already know the number of keys and their types Follow these steps 1 Make a copy of the templates provided in the file BAS STATS BAS or BP STATS BPI 2 Using AlphaVUE paste the templates together and edit them to describe the data structure to contain the information gathered about the ISAM PLUS file 3 Specify the name of your file or file number and the map structure in the INDEXED STATS statement Here is a copy of the templates from the file BAS STATS BAS ISAM PLUS File Stats Map Template AP1 STAT STATS MAP Map for ISAM PLUS file statistics AP2 STAT DATA DEVICE B 2 0 RAD50 device name of IDA device AP2 STAT DATA UNIT B 2 0 Device unit number of IDA device AP2 STAT RECORD SIZE B 2 0 Record size in bytes 4 64K AP2 STAT FREE RECORDS B 4 0 Free record count AP2 STAT FREE INDEX B 4 0 Free index block count AP2 STAT TOTAL INDEX B 4 0 Total allocated
128. t ON ERROR GOTO ERROR TRAP1 OPEN 1 FILENAME INDEXED RECNO FSTATUS WAIT FILE PRINT Mail file successfully opened ON ERROR GOTO ISAM PLUS User s Manual Rev 02 Sample BASIC Programs Using ISAM PLUS Page B 9 Set keynames into an array KEYNAME 1 Last Name KEYNAME 2 First Name KEYNAME 3 Address KEYNAME 4 City KEYNAME 5 State KEYNAME 6 ZIP KEYNAME 7 Status KEYNAME 8 Hash Main loop PROMPT PRINT PRI Enter Function Add Delete Inquire Print End INPU LINE ANSWER IF ANSWER THEN GOTO PROMPT FUNCTION INSTR 1 ADIPE UCS ANSWER ON FUNCTION GOSUB ADD REC DELETE REC INQUIRE REC PRINT LABELS amp SHUTDOWN IF FUNCTION 0 THEN PRINT ERRORBELLS Unknown function GOTO PROMPT PRINT LABELS GET 1 ISAM KEY 0 gt LAB PRINT LOOP IF FSTATUS ISAM NF THEN RETURN ti E Position to start of file GOSUB LABEL PRINT GET NEXT 1 LABEL GOTO PRINT LOOP ADD REC Add new record to file PRINT Input new record INPUT LINE Enter Last Name NEW LAST NAME INPUT LINE Enter First Name
129. t record whose key is GE Smiley returns relative record number 100 Get record whose key is GT Smiley returns relative record number 105 Get record whose key is LT Snyder returns relative record number 300 Get record whose key is LE Snyder returns relative record number 345 Get record whose key is EQ Smith returns relative record number 105 You may lock as many records as you re going to need You may supply the wait for record flag if the record is in use If the record is in use and you don t want to wait you still receive a relative record number and a found code that verifies ISAM PLUS found the record Your current position points to this record ISAM PLUS User s Manual Rev 02 Definitions of Standard Update Operations Page 6 3 and is treated as if you made a FIND call This is so you may try again to read the record using a GETNXT call If you want to skip this record you should use the Find Next Previous call ISAM PLUS always updates your current pointer if it finds the record key you are looking for If the record key is not found your current pointer does not change The relative record number returned to you is for your information only You may not access an ISAM PLUS file using this record number You may however use this relative record number to release the record If a deadlock occurs for example you are waiting for Record 1 which is locked by User B and User B is waiting for Record
130. terminator Allow duplicate keys flag May change key flag Size of key Position of key Null terminator Data device name size BB BN DN LD BMON ASA oe NMOWF DN NONE t NMOWF DN KF M DO 1 bytes bytes bytes bytes bytes bytes bytes bytes bytes bytes bytes 1 byte byte bytes bytes bytes byte bytes bytes bytes byte byte bytes bytes bytes bytes byte bytes bytes bytes byte byte bytes Page 5 7 packed RAD50 excludes header blocks separated format include deleted key directories Repeat ASCIZ K CONC Repeat 1 to 16 bytes bytes times Key specifier negative if key has been deleted If key specifier is negative skip over the 32 bytes following it because there is no information to report for a deleted key Offsets for these fields up to the number of active secondary key directories have been defined in ISMUSR M68 for your convenience Use D1 for the size of the buffer you want filled If the file was flagged with IS NOX when set up with BSET the file is opened non exclusively ISAM PLUS User s Manual Rev 02 Page 5 8 Chapter Five BERR Display ISAM PLUS Related Error Message INPUT DO Error code D6 Flag OTSLDQ Display leading OTSTR Output to a Terminal OTSDDB Output through DDB indexed by A2 OTSME Output into buffer indexed by A2 OTSCR Append CR LF OTSBEL Ring a bell if output t
131. the wrong record Records updated must be currently locked by the program An attempt to update an unlocked record results in a trapping error UPDATE RECORD does not affect the lock status of a record Any key including the primary can change during an update The key must be read by a GET LOCKED GET NEXT LOCKED or GET PREV LOCKED statement to lock it before the update ISAM PLUS User s Manual Rev 02 Page 8 6 Chapter Eight An update failure causes an error trap The system DDB error code giving the reason for the error will be in the error status variable You can get this code using the ERF function See the section Error Processing in this chapter CREATE RECORD This statement creates a new record The format is CREATE RECORD file channel varlist The new key s are defined by the record content If a record with the same key exists and duplicate keys are not allowed the CREATE RECORD operation fails All indices are updated on a successful CREATE RECORD operation All errors trap The system DDB error code giving the reason for the error is in the error status variable You can get this error code using the ERF function See the section on Error Processing in this chapter DELETE RECORD Deletes the record last accessed successfully by a GET or FIND The record must be locked The format is DELETE RECORD file channel All of the indices are updated upon a successful delete All er
132. thout the other The contents of the registers at the time you call the ISMUTL routine and the contents of the registers at the time the ISMUTL routine in turn calls your allocation or de allocation routine are not guaranteed to be the same ISMUTL returns its impure memory base in AO You should save this register DO NOT modify its contents You must pass this value in register AO each time you call an ISMUTL routine The size of impure memory is approximately 5 400 bytes BSET Set up File INPUT AQ ISMUTL impure area pointer set by BINIT A2 Pointer to file specification ASCIZ DO Flag IS WAT Wait for file if it is in use IS PRN Print error message before returning IS NOX Open file as non exclusive OUTPUT DO Condition code success if 0 CC Z set if success and file exists Z cleared on error examine DO or file not found This routine must be called next to set up the ISAM PLUS file Set A2 to point to the file name in ASCIZ form ISMUTL returns the condition code to you If the file already exists the Z bit is set otherwise the Z bit is cleared and DO D EFNF The file is opened exclusively BCRET Create an ISAM PLUS File INPUT AO ISMUTL impure area pointer Al Record parameters pointer A2 Data file device nam devn in ASCIZ form must be 0 or null if it uses the same devic name as IDX file DO Flag G OUTPUT DO Con
133. to the last record of your file if you want to scan the file in descending order If you want a secondary key to point to the last record of your file issue a FIND call specifying the relation LE less than or equal with the highest key A wait for file flag is also available for you to specify whether you want to wait if a file is in use Individual IDA records have their own flags which you supply when accessing a record Get Record Specified by a Key Use this call to get a specific record from an ISAM PLUS file You specify the key the directory key number primary key 0 and the relation to the key There are five relations you can use to search for a record EQ LE GE GT and LT Use EQ to tell ISAM PLUS to find the record whose key exactly matches the value you specify If there are duplicate keys ISAM PLUS returns the first identical key it finds Use LE or GE to search for a lesser value or greater value respectively if an exact match can t be found Use LT to find the record whose key is less than the value specified use GT to find the record whose key is greater than the value specified In the case of a group of records containing duplicate key values LT returns the last record having the identical value GT returns the first record having the identical key value For example given these records Relative Record No 100 Main St 730 Broadway 444 Palm Dr 775 Carson St 95 Jackson Blvd Ge
134. turn values on exit from the routine CC stands for Condition Code SINT Initialize ISAMP SYS INPUT A3 User allocation routine optional A4 User de allocation routine optional A5 May be used to pass information to user memory allocation routine optional OUTPUT A5 ISAM PLUS impure area pointer Exit to AMOS if allocation fails This is the first routine you must call to use ISAMP SYS it lets ISAMP SYS create memory for its own use You only call this routine once no matter how many ISAM PLUS files you open If you want ISAMP SYS to use GETMEM to allocate memory set A3 to 0 If you have your own allocation routine ISAMP SYS always calls your allocation routine when it needs memory Upon entry into your allocation routine ISAMP SYS stores the number of memory bytes requested in register D1 and expects your allocation routine to return the base of the memory pointer in A1 Set the condition code before returning to ISAMP SYS set Z bit ON if the allocation succeeded OFF if it failed NI ISAMP SYS exits to AMOS if the Z bit is not set B If you are using your own de allocation routine ISAMP SYS passes the base of memory in A1 Set the condition code upon returning to ISAMP SYS as discussed in the paragraph above Don t change any other registers for the allocation or the de allocation routine ISAM PLUS User s Manual Rev 02 Page 7 2 Chapter Seven Ae if you have an allocation routin
135. u want to read the record use the Get Next Previous call Suppose you locked 10 records and you want to update the first record you locked You can use the Find Key call to locate it and then update the record Find Next Previous Key This call processes the keys of an index in sequence You may use this call to position the pointer within an ISAM PLUS file The record pointer points to the record that corresponds to the current key ISAM PLUS User s Manual Rev 02 Page 6 4 Chapter Six Update Existing Record This call lets you update a record You must lock the record you want to update You may use Find Key or Find Next Previous Key to position it and then update the record as long as the record is locked If you get a Record in use error message this means the record is not available because it is locked by another user the record you last accessed is not the same record as the one you are going to update Of course you see record not locked if you did not lock the record This call updates all the keys which are allowed to change as dictated by the new data Add a New Record to a File This call lets you add a record to a file ISAM PLUS adds every key into the IDX file It adds duplicate keys following the last of a set of entries with the same key value Delete Existing Record Use this call to delete a record from a file You must lock the record you want deleted prior to making the delete call You may position it usin
136. ur terminal keyboard The name of the key you need to press appears inside the key symbol like this RETURN If you need to press the TAB key you would see AB or the ESC key sometimes is labeled ESCAPE Indicates a control sequence you press on the keyboard Press and hold it down while pressing the indicated key This symbol in front of a capital letter means the letter is a control character For example when you press C it appears on your screen as C This symbol means halt It indicates an important note you should read carefully before going further in the documentation Usually the text next to this symbol contains instructions you MUST or MUST NOT do so read it carefully This symbol means hint It indicates a helpful bit of information or a short cut that could save you time and trouble This symbol means remember It indicates something you should keep in mind while you are following a set of instructions ISAM PLUS User s Manual Rev 02 Chapter 2 Introduction to ISAM PLUS ISAM is a method for organizing and retrieving data The name Indexed Sequential Access Method refers to the manner in which the data is organized You access the information in the ISAM data file by searching a separate index file containing a group of symbolic keys and pointers to records in the data file with which those keys are associated By searching several levels of indices within the index file we c
137. urns the number of the type of error detected ERR 1 Returns the last line number encountered before the error ERR 2 Returns the last file number accessed For a listing of the error codes returned by ERR 0 please refer to the AlphaBASIC PLUS User s Manual and AlphaBASIC User s Manual ERF X FUNCTION X is the channel number of the file you are interested in The function returns an error condition code If the returned value is not zero an abnormal condition exists as a result of the preceding file operation The non zero codes are the same as the ERR 0 codes For full details see your AlphaBASIC or AlphaBASIC PLUS User s Manual Error Location If error trapping is not enabled RUN displays an error message and the error line depending on these combinations ISAM PLUS User s Manual Rev 02 Page 8 14 Chapter Eight e If the program has line numbers and is compiled without the O switch the display gives the error description and the line number where the error lies e If the program has no line numbers or is compiled with the O switch the display gives the error description and the internal line offset The internal offsets of the program lines are found by compiling the program with L This switch generates a LST file during the compilation which lists the program source preceded by the line offset in hexadecimal notation Here is an example of an LST file O print TEST5 test of a runtime error 2B PRI
138. x block count AP2 STAT TOTAL RECORDS B 4 0 Total allocated records count AP2 STAT TOTAL LOADED B 4 0 Total records loaded in use AP2 STAT MIN FREE IDX B 2 0 inimum free index blocks AP2 STAT EXTRA PERCENT B 2 0 Extra idx blks to alloc 0 900 AP2 STAT CREATE DATE Creation date AP3 STAT CREATE MONTH B 1 0 Creation month AP3 STAT CREATE DAY B 1 0 Creation day AP3 STAT CREATE YEAR B 1 0 Creation year AP3 STAT CREATE DOW B 1 0 Creation day of week MAP2 STAT 2ND DIR B 1 0 Number of secondary directories MAP2 STAT ACT 2ND DIR B 1 0 Active secondary directories MAP 2 STAT REBUILD DATE Creation date AP3 STAT REBUILD MONTH B 1 0 Creation month AP3 STAT REBUILD DAY B 1 0 Creation day AP3 STAT REBUILD YEAR B 1 0 Creation year AP3 STAT REBUILD DOW B 1 0 Creation day of week MAP2 STAT RESERVE 8 B 1 Reserved for future use MAP2 SALPHAKEYO1 Primary key Alpha AP3 SKEYO1 INDEX B 2 0 Index number for this key AP 3 SKEYOL TYPE B 1 1 Type of key Alphanumeric type AP3 SKEYO1 RESV 3 B Reserved for future expansion AP3 SKEYO1 NAME S 20 Name of key 20 char blank filled AP3 SKEYO1 NULL B 2 0 Null terminator for key name AP 3 SKEYO1 DUP B 1 0 Duplicate keys permitted flag 0 1 AP 3 SKEYO1 CHNG B 1 0 Key change permitted flag 0 1 AP3 SKEYO1 SIZE B 2 0 Size of key characters AP3 SKEY01 POS B 2 0 Position of key in record 1 based MAP2 SCONCATKEY02 Secondary Key Concat AP3 SKEY02 INDE

ISAM PLUS User`s Manual

Contents

Download Pdf Manuals

Related Search

Related Contents