Download ISAM System User`s Guide

ISAM Svstem
User's Guide
ALPHA
MICROSYSTEMS
RIGHT'. FROM THESTART.
DWM-00160-06,Rev. C01
O 1977, 1979, 1981, 1982, 1983, 1984, 1992 Alpha Microsystems
REVISIONS INCORPORATED
REVISION
A00
A01
A02
A03
BOO
COO
C01
December 6, 1977
April 1979
April 30, 1981
October 31, 1981
June 1,1982
March 18, 1983
May 21,1984
ISAM System User's Guide
To re-order this document, request part number DWM-00100-06.
This document applies to AMOS/T Versions 5.0 and later
and AMOS Versions 1.1 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 informatior) 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
AlphaBASIC
AlphaLAN
AlphaNET
CASELODE
AMOS
AlphaCALC
AlphaLEDGER
AlphaPASCAL
OmniBASlC
Alpha Micro
AlphaCOBOL
AlphaMAlL
AlphaRJE
VER-A-TEL
AlphaACCOUNTlNG
AlphaFORTRAN 77
AlphaMATE
AlphaWRlTE
VIDEOTRAX
The following are trademarks of Alpha Microsystems, Santa Ana, CA 92799:
AlphaBASIC PLUS
DART
AlphaVUE
ESP
AM-PC
MULTl
ALPHA MICROSYSTEMS
3501 Sunflower
P.O. Box 25059
Santa Ana, CA 92799
AMTEC
Page iii
Table o f Contents
CHAPTER 1
ABOUT THIS BOOK
1.1
1.2
CHAPTER 2
2.3
2.4
.........
......
.........................
........................
............................
...................
...................
................
.......................................
...............
..........
................................
THE INDEXED SEQUENTIAL ACCESS METHOD
2-1
DESCRIPTION OF INDEXED SEQUENTIAL FILES
2-3
2.2.1
The Data F i l e
2-4
2.2.2
The Index F i l e
2-4
I S A M ACCESS MODES
2-5
2.3.1
Counted Update Mode
2-5
2.3.2
Exclusive Open Mode
2-6
2.3.3
H i n t s and R e s t r i c t i o n s
2-7
CONVERTING I S A M FILES FROM AMOS TO AMOS/L
FORMAT
2-8
2..4.1
Using ISMDMP and ISMBLD
2-8
2.4.2
Using a Custom Bui l t Program
2-9
2.4.3
Converting I S A M Access Programs t o Use
2-9
LOKSER
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
3.1
3.2
3.3
3.4
3.5
DWM.00100.06.
.......................... 1-2
......................... 1-2
INTRODUCTION TO I S A M
2.1
2.2
CHAPTER 3
COMPATIBILITY NOTES
GRAPHICS CONVENTIONS
............... 3-1
.........................
....... 3-1
............
3-2
............... 3-2
........... 3-2
....... 3-2
...................
3-3
... 3-3
...................
......... 3-3
3-3
.. 3-3
.......... 3-4
............................
3-4
............................ 3-5
......................................
................... 3-5
3-5
................3-5
........ 3-6
GENERAL OPERATING INSTRUCTIONS
CREATION MODE
3.2.1
S p e c i f y i n g F i l e Parameters
3.2.1.1
"Size o f Key:"
3.2.1.2
" P o s i t i o n o f key:"
3.2.1.3
"Size o f data record:"
3.2.1.4
"Number o f records t o
allocate:"
3.2.1.5
"Entries per index bl-ock:"
3.2.1.6
"Empty index blocks t o
allocate:"
3.2.1.7
"Primary D i r e c t o r y ? "
3.2.1.7.1
"Secondary F i l e "
3.2.1.8
"Data F i l e Device?"
FILE LOADING MODE
3.3.1
Suppressing E x c l u s i v e Open Mode ( t h e
I N Switch)
CHANGING THE DATA FILE DEVICE (THE I D
SWITCH)
OPTIMIZING FILE PARAMETERS
3.5.1
E n t r i e s per Index Block
3.5.2
Empty Index Blocks t o A l l o c a t e
REV COO
Page i v
CHAPTER 4
DUMPING AN I S A M FILE WITH ISMDMP
4.1
4.2
4.3
................4-1
....... 4-2
..............................
4-2
.............. 4-2
.........................4-2
GENERAL OPERATING INSTRUCTIONS
4.1.1
Suppressing E x c l u s i v e Open Mode
FILE WMP MODE
4.2.1
Sample Data F i l e D i s p l a y
INDEX FILE DUMP MODE
4.3.1
Sample Index F i l e D i s p l a y
............. 4-3
CHAPTER 5
COMPRESSING INDEX FILES WITH ISMCOM
CHAPTER 6
FILE LOCKING TECHNIQUES
6.1
6.2
6.3
6.4
........................... 6-1
ABOUT THIS CHAPTER
6.1.1
I f You Want t o Access I S A M through
Assembly Language Programs
6.1 - 2 I f You Want t o Access I S A M through
AlphaBASIC
WHAT I S FILE LOCKING?
THE AMOS AND AMOS/L FILE LOCKING TECHNIQUES
6.3.1
XLOCK
6.3.1.1
E x c l u s i v e Access
6.3.1.2
Shared Access
6.3.2
FLOCK
6.3.2.1
E x c l u s i v e Access
6.3.2.2
Shared Access
6.3.3
LOKSER
RECOMMENDED FILE LOCKING TECHNIQUES
6.4.1
General H i n t s
6.4.2
Using ISAH w i t h a S i n g l e Key
6.4.2.1
Example 1
Creating a
Record
6.4.2.2
Example 2 .D e l e t i n g a
Record
6.4.2.3
Example 3
Updating a
Record
6.4.3
Using I S A M w i t h M u l t i p l e Keys
6.4.3.1
Example 1
Creating a
Record
6.4.3.2
Example 2
Deleting a
Record
6.4.3.3
Example 3
Updating a
Record
............ 6-1
............................ 6-2
........................ .. 6-2
6-3
.................................
6-4
.............
6-4
................
6-5
.................................
6-5
.............
................ 6-6
6-6
................................
6-7
.......... 6-7
......................... 6-10
-
.......... 6-11
........................6-11
.......................
6-12
.......................
......... 6-13
6-13
.......................
6-14
.......................
6-14
....................... 6-15
CHAPTER 7
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
7.1
7.2
7.3
7.4
DWM.00100.06.
..................... 7-1
......... 7-2
.................
7-3
7-3
...........
....... 7-4
GENERAL CALLING SEQUENCE
INITIALIZING THE I S A M SYSTEM (.INIT)
7.2.1
User Supplied A l l o c a t i o n and
D e a l l o c a t i o n Routines
FINALIZING I S A M PROCESSING (.IFIN)
OPENING A FILE FOR PROCESSING (.IOPNR)
REV COO
Page v
... 7-5
7-5
.........
.............. 7-6
.............................. 7-7
..............................
7-8
.................... 7-9
7.5
7.6
7.7
7.8
CLOSING THE F I L E AFTER PROCESSING (.ICLOS)
LOCATING A FREE DATA RECORD (.IGTFR)
DELETING A DATA RECORD (.IDLFR)
READING A DATA RECORD BY RELATIVE RECORD
NUMBER (.IRLRD)
7.9
WRITING A DATA RECORD BY RELATIVE RECORD
NUMBER (.IRLWT)
7.10 FINDING A RECORD (.IREDR)
7.11 ADDING A SYMBOLIC KEY (.IWRTR)
7.12 DELETING A KEY (.IDELK)
7.13 FINDING THE NEXT SEQUENTIAL KEY (.SREDR)
............... 7-10
......................
..... 7-10
7-11
CHAPTER 8
WRITING AMOSIL ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS ISAM
8.1
8.2
8.3
8.4
8.5
8.6
8.7
8.8
8.9
8.10
8.11
8.12
8.13
CHAPTER 9
......... 8-2
.................
8-3
...........
....... 8-3
8-4
...
8-5
.........
8-5
.............. 8-6
.............................. 8-6
.............................
8-7
8-7
....................
............... 8-8
......................
..... 8-8
8-9
STANDARD ISAM SYMBOLS FOR ASSEMBLY LANGUAGE PROGRAMMERS
9.1
9.2
9.3
CHAPTER 10
..................... 8-1
GENERAL CALLING SEQUENCE
I N I T I A L I Z I N G THE ISAM SYSTEM (.INIT)
8.2.1
User S u p p l i e d A l l o c a t i o n and
Deallocation Routines
F I N A L I Z I N G ISAM PROCESSING (.IFIN)
OPENING A F I L E FOR PROCESSING (.IOPNR)
CLOSING THE F I L E AFTER PROCESSING (.ICLOS)
LOCATING A FREE DATA RECORD (.IGTFR)
DELETING A DATA RECORD (.IDLFR)
READING A DATA RECORD BY RELATIVE RECORD
NUMBER (.IRLRD)
WRITING A DATA RECORD BY RELATIVE RECORD
NUMBER (.IRLWT)
FINDING A RECORD (.IREDR)
ADDING A SYMBOLIC KEY (.IWRTR)
DELETING A KEY (.IDELK)
FINDING THE NEXT SEQUENTIAL KEY (.SREDR)
USING ISAM FROM WITHIN ALPHABASIC
10.1
10.2
10.3
10.4
10.5
10.6
10.7
DWM.00100.06.
.............................. 9-1
.................................
...................... 9-2
9-2
CALLING SYMBOLS
CALLING FLAGS
COMPLETION CODE SYMBOLS
REV COO
.......... 10-1
.......................... 10-3
OPENING AN INDEXED SEQUENTIAL F I L E
THE ISAM STATEMENT
10.2.1
ISAM S t a t e m e n t Codes
READING AND WRITING DATA I N AN ISAM DATA
FILE
CLOSING FILES
LOCKING AND UNLOCKING STATEMENTS
ERROR PROCESSING
USING THE ISAM FUNCTIONS WITHIN AN
ALPHABASIC PROGRAM
10.7.1
Adding Data t o an Indexed
Sequential F i l e
................ 1 0 - 4
.......................................
10-6
...............................
10-7
10-7
............
............................ 10-8
.......................... 10-9
..................... 10-9
Page v i
10.7.2
10.8
Reading Data Records i n Symbolic
Key Order
10.7.3
Reading Data Records Randomly by
Symbolic Key
Updating Data Records
10.7.4
10.7.5
Deleting a Data Record
SAMPLE ALPHABASIC I S A M PROGRAM
10.8.1
Sample ISMBLD Use on an AMOS
System
Sample ISMBLD Use on an AMOS/L
10.8.2
System
Sample AlphaBASIC Program
10.8.3
........................... 10-11
........................
10-12
............... 10-12
.............. 10-13
.............. 10-15
.............................. 10-15
..............................
10-16
........... 10-17
DOCUMENT HISTORY
INDEX
DWM-00100-06,
REV COO
CHAPTER 1
ABOUT THIS BOOK
T h i s manual i s aimed a t t h e experienced assembly language o r AlphaBASIC
programmer who wants t o make use o f t h e Alpha Micro I S A M system w i t h i n h i s
I f you are not f a m i l i a r w i t h Alpha M i c r o Assembly
o r her own programs.
Language, please r e f e r t o the AMOS Assembly Language Programmer's Manual,
AMOS/L
Assembly
Language
Programmer ' s
Manua 1,
DWM-00100-43
or
DSS-10007-00.
I f you want i n f o r m a t i o n on AlphaBASIC,
refer t o
the
A lphaBASIC User's Manual, DWM-00100-01.
The purpose o f t h i s manual i s t h r e e f o l d :
1.
To g i v e you an i n t r o d u c t i o n t o ISAM;
2.
To discuss how you can create and access I S A M f i l e s using t h e
v a r i o u s programs o f t h e I S A M system;
3.
And, t o g i v e i n f o r m a t i o n on how t o w r i t e programs
assembly language o r AlphaBASIC t o locate, update, add,
data i n I S A M f i l e s .
To t h a t end,
i n either
and d e l e t e
we have organized t h i s manual i n t o t h e f o l l o w i n g areas:
CHAPTER 2
- INTRODUCTION TO
ISAM
This chapter gives a basic i n t r o d u c t i o n t o t h e concepts behind the
Indexed Sequential Access Method, ISAM, and provides some basic
i n f o r m a t i o n on the components o f the Alpha Micro I S A M system. We
a l s o discuss how t o t r a n s p o r t and convert I S A M f i l e s from an AMOS
system t o an AMOS/L system f o r programmers who are upgrading from
one Alpha Micro computer system f a m i l y t o another.
-
PART I THE I S A M UTILITY PROGRAMS
ISMDMP,
and ISMCOM
Chapters 3 through 5 discuss t h e ISMBLD,
u t i l i t y programs t h a t a l l o w you to, r e s p e c t i v e l y : 1) Create and
load an I S A M f i l e , 2) I n s p e c t and debug an I S A M f i le,
and 3)
Compress an I S A M index f i l e .
DWM-00100-06,
REV COO
Page 1-2
ABOUT THIS BOOK
Part I1
-
PROGRAMMING WITH ISAM
Chapter 6 c o n t a i n s i n f o r m a t i o n on p e r f o r m i n g f i l e l o c k i n g w i t h i n
We d i s c u s s t h e b a s i c
y o u r programs t h a t access I S A M f i l e s .
concept o f f i l e locking,
and show s e v e r a l sample AlphaBASIC
program e x c e r p t s t h a t demonstrate t h e p r o p e r
file
locking
procedures.
Chapters 7 and 8 d i s c u s s t h e AMOS and AMOSIL ( r e s p e c t i v e l y )
assembly language c a l l s your assembly language programs must use
t o access I S A M f i l e s .
Chapter 9 p r o v i d e s t h e s t a n d a r d I S A M
assembly language symbols used by AMOS and AMOS/L assembly
language programmers.
Chapter 10 c o n t a i n s i n f o r m a t i o n on u s i n g AlphaBASIC t o c o n s t r u c t
programs t h a t access I S A M f iles.
1.1
COMPATIBILITY NOTES
Ifyour system has t h e o p t i o n a l LOKSER F i l e L o c k i n g S e r v i c e System
installed,
n o t e t h a t t h e I S A M on your system assumes t h a t your
AlphaBASIC o r assembly language I S A M access programs a r e u s i n g LOKSER
t o perform f i l e locking; such programs must f o l l o w t h e I S A M f i l e update
procedures i n t h e proper o r d e r o r t h e y w i l l r e c e i v e an " ? I l l e g a l I S A M
sequence" e r r o r .
Please see Chapter 6 o f t h i s manual f o r d e t a i l s .
1.2
GRAPHICS CONVENTIONS
T h i s book conforms t o o t h e r Alpha M i c r o p u b l i c a t i o n s i n i t s use o f a
s t a n d a r d s e t o f g r a p h i c s conventions.
We hope these g r a p h i c s s i m p l i f y
o u r examples and make them e a s i e r f o r you t o use.
Filespec
A f i l e specification.
Such a s p e c i f i c a t i o n
I t u s u a l l y has these elements:
file.
identifies
a
Devn: F i lename. ExtensionEp,pnl
O p t i o n a l elements o f a command l i n e .
When these symbols
appear i n a sample command line,
t h e y i n d i c a t e elements
t h a t you may o m i t from t h e command line, depending on t h e
e f f e c t you want t o achieve.
U n d e r l i n e d c h a r a c t e r s i n d i c a t e those c h a r a c t e r s t h a t t h e
m o n i t o r p r i n t s on your t e r m i n a l d i s p l a y .
For example,
whenever you see an u n d e r l i n e d d o t , ,
t h i s indicates the
prompt symbol t h a t t h e o p e r a t i n g system d i s p l a y s on your
t e r m i n a l when you a r e a t m o n i t o r command l e v e l .
(RETI
DWM-00100-06,
C a r r i a g e r e t u r n symbol.
The RET symbols marks t h e p l a c e i n
y o u r keyboard e n t r y f o r you t o p r e s s t h e RETURN key.
REV COO
CHAPTER 2
INTRODUCTION TO I S A M
I S A M i s a method f o r o r g a n i z i n g and r e t r i e v i n g data.
The name o f t h e method
(Indexed Sequential Access Method) r e f e r s t o the manner i n which t h e data i s
organized.
The i n f o r m a t i o n i n the I S A M data f i l e i s accessed by searching a
separate index f i l e t h a t contains a group o f symbolic keys and p o i n t e r s t o
records i n the data f i l e w i t h which those keys are associated.
By searching
s e v e r a l l e v e l s o f i n d i c e s w i t h i n the index f i l e , we can l o c a t e records i n a
separate f i l e much more. q u i c k l y and e f f i c i e n t l y than i f we had t o search t h e
a c t u a l data f i l e i t s e l f .
Some examples o f data f o r which symbolic keys can
be s p e c i f i e d are:
Customer information-t h e name o f t h e customer i s the key ( t h a t
is, an element o f t h e data record) on which you base your search.
Payroll--
t h e key i s an employee number.
I n v e n t o r y control--
2.1
t h e key i s a p a r t number.
THE INDEXED SEQUENTIAL ACCESS METHOD
F i n d i n g a convenient and e f f i c i e n t way t o access i n f o r m a t i o n i n a f i l e
i s an important problem f o r a programmer.
Suppose, f o r example, t h a t
you have a phone book o f f i v e thousand names and phone numbers.
I f you
need t o f i n d a s p e c i f i c person's phone number, you can s t a r t w i t h page
number one and scan every e n t r y i n t h e book u n t i l you f i n d the proper
name. That process i s very slow and i n e f f i c i e n t , however, because you
have t o deal w i t h so many e n t r i e s .
A more e f f i c i e n t method would
i n v o l v e d i v i d i n g the phone book i n t o sections, and searching o n l y those
s e c t i o n s t h a t might c o n t a i n t h e data you need i n s t e a d o f searching t h e
ent ir e data base.
Organizing your data so t h a t i t i s e a s i e r and q u i c k e r t o search i s t h e
main idea behind ISAM.
I f we were t o organize t h e phone book i n
somewhat the same way as I S A M would do it, we might do t h i s :
DWM-00100-06,
REV COO
Page 2-2
INTRODUCTION TO I S A M
A.
F i r s t we b u i l d a f i l e c o n t a i n i n g one l o g i c a l record f o r each
e n t r y i n t h e phone book; each r e c o r d c o n s i s t s o f a person's
name,
an address, and a phone number. We a s s i g n each e n t r y a
number ( c a l l e d t h e r e l a t i v e record number o r t h e r e l a t i v e key)
t h a t marks i t s p o s i t i o n i n t h e f i l e .
For example,
the f i v e
hundredth e n t r y i s number 499 ( t h e f i r s t record i s number 0,
not 1).
(The record number i s c a l l e d " r e l a t i v e "
because i t
marks t h e p o s i t i o n o f t h e record from t h e f r o n t o f the f i l e ;
i t i s not an absolute d i s k address.) T h i s f i l e t h a t contains
a l l o f our data corresponds t o t h e I S A M data f i l e .
B.
Next we c o n s t r u c t a f i l e t h a t contains i n f o r m a t i o n about t h e
data f i l e t h a t helps us search t h e data f i l e .
(The f i l e we
are c o n s t r u c t i n g corresponds t o t h e I S A M index f i l e . ) When you
open a phone book,
you n o t i c e t h a t t h e t o p o f each page
contains two words; t h e f i r s t and the l a s t names t h a t appear
on t h a t page.
These two names g i v e you an "index" i n t o t h e
data on t h a t page. So, i f t h e two words a t t h e t o p o f a
p a r t i c u l a r page a r e "PENDERGRASS-PENNINGTON,"
you know t h a t
t h e names associated w i t h a l l e n t r i e s on t h a t page f a l l
somewhere i n t h a t range.
Suppose, then, t h a t t h i s second f i l e
we a r e c r e a t i n g contains t h e words a t t h e t o p o f t h e phone
book pages, along w i t h t h e r e l a t i v e r e c o r d numbers o f t h e
e n t r i e s t h a t f a l l on each page.
'
I n s t e a d o f searching the e n t i r e data f i l e , we can search t h i s
I f we want t o f i n d t h e e n t r y f o r
much smaller "index" f i l e .
t h e name PENHALL, we can search t h e page i n d i c e s i n our index
f i l e u n t i l we f i n d two names t h a t PENHALL f a l l s between. Then
we can search j u s t t h e data f i l e records associated w i t h t h a t
range o f names u n t i 1 we f i n d PENHALL.
Uhen we b u i l d an index f i l e , we say t h a t t h e f i l e contains
symbolic keys. A symbolic key i s an element o f a l o g i c a l
r e c o r d on which we base our search.
I n t h i s example, t h e
symbolic key we are using i s the name associated w i t h each
phone book entry.
We might j u s t as e a s i l y have set up t h e
f i l e s so t h a t we can base our search on phone numbers o r c i t y
names.
C.
We have improved our o r i g i n a l f i l e - s e a r c h procedure, b u t i t
can be improved upon s t i l l f u r t h e r . We now have a data f i l e
and an index f i l e .
The index f i l e contains one l e v e l o f
i n d i c e s ( t h e words a t t h e t o p o f each page i n the phone book).
The next step i s t o p r o v i d e another l e v e l o f i n d i c e s w i t h i n
t h e index f i l e .
When you look f o r a name i n a phone book, you f i r s t f i n d the
proper page by g l a n c i n g a t the names a t the t o p o f each page.
Then you might look a t t h e f i r s t and l a s t names o f each column
on t h e page t o narrow your search s t i l l f u r t h e r .
I f t h e name
f o r which you are searching f a l l s between the names a t the t o p
DWM-00100-06,
REV COO
INTRODUCTION TO I S A M
Page 2-3
and bottom o f t h e column, you b e g i n t o search each e n t r y i n
t h a t column;
otherwise,
you move t o t h e n e x t column on t h e
page.
I n t h e same way, o u r index f i l e c o n t a i n s a f i r s t - l e v e l
i n d e x ( t h e names a t t h e t o p o f t h e page); t h e n i t f u r t h e r
d i v i d e s t h e data on t h e page by g i v i n g i n d i c e s i n t o subgroups
o f e n t r i e s on t h e page ( t h e f i r s t and l a s t names i n each
column make up the second-level index).
The f i n a l l e v e l o f
i n d i c e s ( t h e t h i r d - l e v e l ) i n t h e index f i l e c o n s i s t s o f l i s t s
o f names f o r each column i n t h e book a l o n g w i t h t h e a c t u a l
r e c o r d number i n o u r o r i g i n a l d a t a f i l e t h a t c o n t a i n s t h e
e n t r y a s s o c i a t e d w i t h t h a t name.
D.
Journeying t h r o u g h t h e l e v e l s o f i n d i c e s i n o u r i n d e x f i l e ,
then,
we f i r s t f i n d t h e page on which t h e name appears, t h e n
we f i n d t h e column i n which t h e name appears, t h e n we f i n d . t h e
a c t u a l r e c o r d number o f t h e f i l e i n which t h e e n t i r e e n t r y
a s s o c i a t e d w i t h t h a t name appears.
A t no t i m e do we e v e r need
t o search t h e a c t u a l data f i l e i t s e l f .
Note
that
the
keys
in
t h e i n d e x f i l e a r e grouped
alphabetically.
Since we f i n d a data r e c o r d by s e a r c h i n g t h e
index f i l e ,
t h e data r e c o r d s i n t h e data f i l e do n o t need t o
be arranged i n any p a r t i c u l a r order.
An index f i l e may n o t
c o n t a i n d u p l i c a t e keys;
t h a t is, no two d a t a r e c o r d s i n t h e
d a t a f i l e may have t h e same symbolic key.
The example above discusses a d a t a f i l e t h a t has one index f i l e ( c a l l e d
A d a t a f i l e always has one p r i m a r y i n d e x
t h e p r i m a r y index f i l e ) .
i t may a l s o have one o r more secondary index f i l e s .
A secondary
file;
i n d e x f i l e i s s t r u c t u r e d i n t h e same way as t h e p r i m a r y i n d e x f i l e
For example, i f we
except t h a t i t c o n t a i n s d i f f e r e n t symbolic keys.
want t o base our search o f phone book e n t r i e s on phone numbers as w e l l
as names, we might c o n s t r u c t a secondary i n d e x f i l e t h a t c o n t a i n s phone
numbers.
Although we c o n s t r u c t e d t h e example above ourselves, t h e I S A M program
a u t o m a t i c a l l y c r e a t e s a l l d a t a f i l e s and i n d e x f i l e s f o r you i n
response t o i n f o r m a t i o n and f i l e s p e c i f i c a t i o n s t h a t you supply.
DESCRIPTION OF INDEXED SEQUENTIAL FILES
I n summary, an indexed s e q u e n t i a l f i l e c o n s i s t s o f two random f i l e s : 1.
t h e data f i l e ,
c o n t a i n i n g t h e a c t u a l data; and 2. t h e index f i l e ,
c o n t a i n i n g p o i n t e r s t o symbolic keys w i t h i n t h e data f i l e .
You s p e c i f y
t h e l o c a t i o n o f t h e symbolic key w i t h i n each r e c o r d when you b u i l d an
indexed s e q u e n t i a l f i l e u s i n g t h e ISMBLD program ( d i s c u s s e d i n Chapter
3, " C r e a t i n g and Loading an ISAN F i l e w i t h ISMBLD")
To b u i I d an
indexed s e q u e n t i a l f i l e ,
you s u p p l y c e r t a i n parameters t o t h e ISMBLD
program; ISMBLD t h e n produces an empty f i l e .
.
DWM-00100-06,
REV COO
INTRODUCTION TO I S A M
Page 2-4
To Load t h e f i l e w i t h data, you may w r i t e your own program o r you may
use t h e ISMBLD program t o copy t h e data from an o r d i n a r y s e q u e n t i a l
f i l e i n t o t h e data f i l e ( u p d a t i n g t h e index f i l e i n t h e process).
The I S A M program does a l l r e a d i n g and w r i t i n g o f t h e i n d e x f i l e ;
you
w i l l n o t have t o handle these f u n c t i o n s y o u r s e l f . Your AlphaBASIC o r
assembly language program w i l l add, delete, o r update d a t a i n t h e I S A M
d a t a f i l e based on t h e r e l a t i v e r e c o r d number r e t u r n e d t o your program
by ISAM.
2.2.1
The Data F i l e
The data i n your data f i Le may be i n any d a t a format;
however,
the
i n d e x f i l e o r d e r s keys i n ASCII c o l l a t i n g sequence (i.e.,
ascending
b i n a r y o r d e r ) which may a f f e c t o p e r a t i o n o f t h e I S A M program when
When you b u i l d an indexed
d a t a i s recorded i n o t h e r t h a n A S C I I form.
s e q u e n t i a l f i l e ( v i a t h e ISMBLD program), you s u p p l y v a r i o u s i t e m s o f
i n f o r m a t i o n about your data f i l e (egg., t h e s i z e o f t h e data records,
t h e l o c a t i o n o f t h e symbolic key w i t h i n t h e data record, and so on);
ISMBLD t h e n b u i l d s b o t h t h e data f i l e and i t s p r i m a r y index f i l e .
Your programs use t h e I S A M f u n c t i o n s t o add and d e l e t e d a t a r e c o r d s
i n t h e data file. When you add a record, I S A M i n s e r t s i t i n t o t h e
f i r s t f r e e space i n your data f i l e .
When you d e l e t e a record,
ISAM
does so by r e c o v e r i n g t h e space i n t h e data f i l e used by t h a t record,
and r e t u r n i n g t h a t area t o t h e f r e e
r e c o r d l i s t so t h a t i t i s
a v a i l a b l e f o r new records. Because t h e Alpha M i c r o o p e r a t i n g systems
(AMOS and AMOSIL) r e q u i r e t h a t contiguous f i Les (e.g.,
an I S A M d a t a
f i l e ) be p r e a l l o c a t e d ,
once t h e data f i l e i s f u l l i t must be
For t h i s reason, b e
r e o r g a n i z e d b e f o r e i t can be used f u r t h e r .
c a r e f u l t o a l l o c a t e as many r e c o r d s as you w i l l need f o r t h e f i l e .
A l l I S A M d a t a f i l e s MUST have t h e e x t e n s i o n .IDA.
2.2.2
The I n d e x F i l e
The ISMBLD program a u t o m a t i c a l l y c r e a t e s t h e i n d e x f i l e f r o m a
d e s c r i p t i o n o f t h e data f i l e .
The index f i l e c o n t a i n s t h r e e l e v e l s
o f indices, t h e lowest o f which c o n t a i n s p o i n t e r s t o t h e r e c o r d s i n
t h e data f i l e .
Each successive index l e v e l p o i n t s t o a l l t h e b l o c k s
c o n t a i n i n g t h e n e x t Lower l e v e l index.
Index l e v e l s a r e p r o v i d e d so
t h a t t h e e n t i r e index need n o t be searched each t i m e a symbolic key
i s accessed.
When a symbolic key i s accessed, ISAM reads t h e h i g h e s t
l e v e l index t o f i n d which Lower l e v e l index c o n t a i n s a p o i n t e r t o t h e
ISAH t h e n searches t h e b l o c k o f
approximate l o c a t i o n o f t h a t key.
t h a t lower l e v e l index; t h a t index b l o c k i n t u r n p o i n t s t o a Lower
index b l o c k which p o i n t s t o t h e data r e c o r d i n which t h e key i s
stored.
DWM-00100-06,
REV COO
INTRODUCTION TO I S A M
Page 2-5
I n a d d i t i o n t o t h e index blocks, t h e index f i l e c o n t a i n s another
b l o c k named t h e D i r e c t o r y Rock, so c a l l e d because i t never moves.
T h i s b l o c k c o n t a i n s i n f o r m a t i o n d e s c r i b i n g t h e index and data f i l e s
as w e l l as maintenance i n f o r m a t i o n (e.g.,
f r e e record links,
access
counts, etc.).
Each d a t a f i l e must have a p r i m a r y i n d e x f i l e ; i n a d d i t i o n t o t h i s ,
i t may have s e v e r a l secondary index f i l e s .
A t y p i c a l example of t h e
use o f t h i s f e a t u r e would be a m a i l i n g l i s t maintenance program,
where t h e data i s keyed on b o t h a hashed r e t r i e v a l code f o r unique
r e f e r e n c e and a l s o keyed on t h e person's name.
(For an example o f
t h i s k i n d o f program, see t h e sample AlphaBASIC I S A M program i n
Chapter 10, "Using I S A M From W i t h i n AlphaBASIC.")
Your programs use t h e ISAN f u n c t i o n s t o add and d e l e t e keys from t h e
i n d e x f i les, and t o l o c a t e data r e c o r d s i n t h e corresponding d a t a
files.
The e x t e n s i o n o f an I S A M i n d e x f i l e MUST be .IDX.
2.3
I S A M ACCESS MODES
Two access modes,
Counted Update mode and E x c l u s i v e Open mode,
I S A M t o a v o i d unnecessary p r o c e s s i n g o f your i n d e x f i l e s .
allow
Counted Update mode i s t h e normal access mode f o r assembly language o r
A lphaBASIC programs.
( I n A lphaBASIC programs, you w i 11 s e l e c t Counted
Update mode by opening t h e I S A M f i l e i n INDEXED mode; you w i l l s e l e c t
E x c l u s i v e mode by opening t h e I S A M f i l e i n INDEXED'EXCLUSIVE mode.)
E x c l u s i v e Open mode i s t h e normal access mode f o r t h e ISMDMP and ISMBLD
programs and i s t h e o n l y mode f o r t h e ISMCOM program.
I S A M always
processes indexed s e q u e n t i a l f i l e s i n one o r t h e o t h e r o f these modes.
The n e x t two s e c t i o n s d i s c u s s b o t h o f these modes.
It
NOTE: The paragraphs below mention t h e need f o r f i l e i n t e r l o c k i n g .
i s most i m p o r t a n t t h a t your programs guard a g a i n s t t h e p o s s i b i l i t y o f
more t h a n one user t r y i n g t o update t h e same d a t a f i l e a t t h e same
I f s e v e r a l users were t o t r y t o w r i t e t o t h e same f i l e r e c o r d a t
time.
t h e same time,
severe damage t o y o u r data f i l e c o u l d r e s u l t .
For
i n f o r m a t i o n on f i l e i n t e r l o c k i n g procedures,
see Chapter 6 i n t h i s
manual, " F i l e L o c k i n g Techniques."
2.3.1
Counted Update Mode
Counted Update mode a l l o w s I S A M t o i n c r e a s e i t s speed by a v o i d i n g any
unnecessary processing.
Every t i m e ISAM updates a f i l e i n any way,
i t increments a counter i n t h e Rock p o r t i o n o f t h e i n d e x f i l e .
At
t h e t i m e o f f i l e access, I S A M checks t h i s counter t o see i f t h e f i l e
I f t h e f i l e has n o t been
has been updated s i n c e t h e l a s t access.
I S A M can s k i p f u r t h e r access i n i t i a l i z a t i o n and t a k e
updated,
DWM-00100-06,
REV COO
Page 2-6
INTRODUCTION TO I S A M
advantage o f i t s p r i o r knowledge about t h e f i l e .
These a c t i o n s a r e
completely transparent t o t h e user and t h e speed gains (3 t o 70 times
f a s t e r access times) a r e free.
-
IMPORTANT NOTE: The Counted Update mode does NOT e l i m i n a t e f i l e
I f anyone might p o s s i b l y
i n t e r l o c k requirements from your programs.
be updating t h e f i l e ,
your program must continue t o use f i l e
i n t e r l o c k programs such as LOKSER,
XLOCK o r FLOCK t o prevent
simultaneous updates o r accesses. See Chapter 6 f o r more i n f o r m a t i o n
on f i l e locking.
Note t h a t i t i s not necessary t o open and c l o s e t h e I S A M f i l e w i t h
It i s
each m a n i p u l a t i o n even though t h e FLOCK commands are so named.
acceptable t o leave t h e f i l e open d u r i n g t h e whole i n t e r l o c k i n g and
release process and is,
i n fact,
t h e o n l y way t o g a i n t h e speed
increase made p o s s i b l e by t h e Counted Update mode.
See S e c t i o n
6.4.1,
"General Hints,"
f o r a d i s c u s s i o n o f f a c t o r s t o consider when
designing your f il e l o c k i n g procedures.
E x c l u s i v e Open Mode
When a program opens a f i l e exclusively, I S A M renames the . I D X
file
extension.
I S A M a l s o s e t s a f l a g i n the Rock t h a t
t o a .IDY
i d e n t i f i e s t h e f i l e as an e x c l u s i v e f i l e .
I f any o t h e r j o b t r i e s t o
open t h a t f i l e , i t receives a " ? F i l e not found" error; i f another j o b
t r i e s t o access t h e f i l e once i t i s open, t h e job r e c e i v e s a "?Link
s t r u c t u r e smashed" e r r o r (IS.LSS>.
As a r e s u l t o f the e x c l u s i v e open, I S A M knows t h a t no o t h e r program
w i l l be updating o r accessing t h e f i l e .
I t can t h e r e f o r e take f u l l
advantage o f the single-process
s i t u a t i o n f o r i n i t i a l i z a t i o n and
change posting.
Except f o r the process o f opening t h e f i l e and the
need t o p r o p e r l y close t h e f i l e , use o f I S A M i s t h e same as i n
p r e v i o u s versions.
The use o f t h i s mode r e s u l t s i n an extremely
l a r g e g a i n i n access speed.
The o n l y f i l e i n t e r l o c k problem occurs a t the moment o f t h e I S A M OPEN
c a l l ; no one may update the f i l e w h i l e you are opening i t . You MUST
prevent t h i s s i t u a t i o n from o c c u r r i n g by u s i n g one o f t h e f i l e
i n t e r l o c k programs, FLOCK o r XLOCK ( i f LOKSER i s n o t i n s t a l l e d on
your system), o r by simply making sure t h a t no o t h e r user i s running
a program t h a t can update t h a t f i l e .
Once your program has executed
t h e I S A M OPEN c a l l ,
your program needs no i n t e r l o c k s since no one
e l s e can access the f i l e .
Invoke the E x c l u s i v e Open mode from w i t h i n AlphaBASIC by u s i n g t h e
f i l e mode o f INDEXED'EXCLUSIVE i n the f i l e OPEN statement i n your
program.
Your assembly language program may s e l e c t t h e E x c l u s i v e
Open mode by s e t t i n g t h e IS.EXC f l a g i n RO ( f o r AMOS systems) o r DO
( f o r AMOS/L systems) f o r t h e .IOPNR c a l l . You MUST c l o s e t h e f i l e
when you are completely done w i t h m a n i p u l a t i n g that f i l e so t h a t I S A M
DWM-00100-06,
REV COO
INTRODUCTION TO I S A M
Page 2-7
can post t h e f i n a l updates and remove t h e E x c l u s i v e Open c o n d i t i o n s
I f an e r r o r occurs d u r i n g processing,
you should
from t h a t f i l e .
c l o s e t h e f i l e t o remove t h e E x c l u s i v e Open c o n d i t i o n s ( a l t h o u g h you
A f i l e i n which an e r r o r occurred
can a l s o remove them manually).
d u r i n g updating i s probably b a d l y damaged.
Use o f t h e E x c l u s i v e Open mode can r e s u l t i n s i g n i f i c a n t gains when
p r i n t i n g r e p o r t s and o t h e r such batch-type operations.
I t does have
t h e drawback t h a t no one e l s e can access t h e f i l e f o r any reason
w h i l e i t i s exclusive^ opened.
Be warned t h a t any attempts t o
circumvent t h e e x c l u s i v e p r o p e r t i e s o f such a f i l e by c l e v e r
I f s e v e r a l people
manipulations w i 11 probably meet w i t h d i s a s t e r .
need t o access t h e f i l e a t t h e same time, use t h e normal mode,
Counted Update mode; i f no one updates t h e f i l e , you w i l l Lose very
l i t t l e speed i n changing t o t h a t mode.
The ISMBLD, ISMDMP, and ISMCOM programs use t h e E x c l u s i v e Open mode.
To prevent ISMBLD (when l o a d i n g o r cross-indexing an e x i s t i n g f i l e )
The /N
o r ISNDMP from u s i n g E x c l u s i v e Open mode, use t h e /N switch.
s w i t c h must appear a t the very end o f the command l i n e t h a t invokes
t h e program.
For example:
ISMBLD (when c r e a t i n g / l o a d i n g o r creating/cross-indexing)
always use t h e E x c l u s i v e Open mode.
2.3.3
and ISMCOM
H i n t s and R e s t r i c t i o n s
The two access modes make p o s s i b l e a dramatic increase i n t h e speed
They a l s o may r e s u l t i n s l i g h t l y p e c u l i a r
o f I S A M data accesses.
s i t u a t i o n s o f which you should be aware:
1.
I f t h e Counted Update mode counter has n o t changed,
ISAM
assumes t h a t no updates have been made t o t h e f i l e s i n c e t h e
l a s t t i m e an access was made, and t h a t i t may t h e r e f o r e make
c e r t a i n assumptions about f i l e s t a t u s and contents.
The
I f by some v e r y
counter cycles on a count o f 16,777,216.
u n l i k e l y chance t h e f i l e were t o remain open f o r an
i n c r e d i b l y Long t i m e and e x a c t l y 16,777,216
updates were
made between accesses, I S A M would access and/or u ~ d a t et h e
f i l e u s i n g out-of-date ;nformation.
Although not s t r i c t l y impossible, i t i s very u n l i k e l y
t h i s s i t u a t i o n w i l l occur.
We e s t i m a t e t h a t you would
t o Leave your machine up and running f o r s e v e r a l weeks
t h e I S A M f i l e open w i t h o u t making any accesses t o t h a t
i n order t o see t h i s happen.
2.
DWM-00100-06,
that
have
with
file
When you open a f i l e i n E x c l u s i v e Open mode,
I S A M must be
a b l e t o w r i t e t o t h e d i s k t h a t contains t h e f i l e .
This
REV COO
INTRODUCTION To I S A M
Page 2-8
means t h a t you must make sure t h a t t h e d i s k i s n o t
w r i t e - p r o t e c t e d even i f a l l accesses t o t h a t f i l e are going
t o be read operations.
3.
The most v i s i b l e q u i r k o f the E x c l u s i v e Open mode i s t h a t i t
causes I S A M t o rename t h e extension o f t h e f i l e being opened
from . I D X t o .IDY.
I f such a f i l e i s n o t p r o p e r l y closed
( f o r whatever reason), then the name o f t h a t f i l e w i 11 not
be c o r r e c t i n the d i s k d i r e c t o r y .
You can cure t h i s problem
v e r y e a s i l y by u s i n g t h e RENAME command.
For example:
A f i l e OPEN a l s o changes a f l a g i n t h e Rock o f t h e I S A M
index f i l e .
You d o n o t need t o w o r r y a b o u t changing the
f l a g y o u r s e l f i n the event o f an i m p r o p e r l y closed f i l e ,
since the s i t u a t i o n i s automatically self-correcting the
next t i m e the f i l e i s opened ( i n e i t h e r E x c l u s i v e Open o r
Counted Update mode).
4.
2.4
If you open a f i l e i n Counted Update mode b u t the f i l e was
l a s t used i n E x c l u s i v e Open mode and was never closed,
the
f i l e OPEN w i 11 cause I S A M t o w r i t e t o the f i Le t o c o r r e c t
I f t h i s s i t u a t i o n i s going t o occur,
the exclusive flag.
make sure t h a t the d i s k i s write-enabled.
CONVERTING I S A M FILES FROM AMOS TO AMOS/L FORMAT
T h i s s e c t i o n contains i n f o r m a t i o n on t r a n s f e r r i n g I S A M f i l e s from AMOS
systems t o AMOS/L systems, and v i c e versa.
Because t h e format o f I S A M
f i l e s i s d i f f e r e n t on AMOS systems (AM-100 o r AM-100IT CPU based
systems) t h a n on AMOSIL systems (AM-100/L
CPU and AM-1000 based
systems),
moving
ISAM
f i l e s between these systems r e q u i r e s a
t r a n s l a t i o n process.
Note t h a t you o n l y need t o use these procedures
when t r a n s f e r r i n g I S A M f i l e s between systems t h a t a r e based on
d i f f e r e n t processors; you may move I S A M f i l e s between systems based on
t h e same processor w i t h o u t u s i n g any s p e c i a l procedures.
2.4.1
Using ISMDMP and ISMBLD
The simplest method o f t r a n s f e r r i n g I S A M f i l e s i n v o l v e s the use o f
t h e ISMDMP and ISMBLD programs. However, t h i s method imposes some
The
r e s t r i c t i o n s on the way data w i t h i n t h e I S A M f i l e i s s t r u c t u r e d .
records i n t h e data f i l e may c o n t a i n o n l y A S C I I data, and the key
must be contained w i t h i n t h e data record. These r e s t r i c t i o n s a c t u a l l y
f o l l o w recommended g u i d e l i n e s since they g r e a t l y s i m p l i f y r e b u i Lding
and recovery o f I S A M f i l e s i n case o f catastrophe.
DWM-00100-06,
REV COO
INTRODUCTION TO I S A M
Page 2-9
To t r a n s f e r an I S A M f i l e using t h i s method, f i r s t use ISMDMP on the
system you a r e moving data from t o dump t h e contents o f the I S A M f i l e
t o a .SEQ f i l e .
(See Chapter 4 f o r f u r t h e r i n f o r m a t i o n on ISMDMP.)
Once these sequential data f i l e s have been created, move them t o the
new system u s i n g any o f the standard t r a n s f e r media (removable d i s k
pack,
f l o p p y disk,
VCR cassette, etc.).
Once the sequential f i l e s
a r e on the new system, you must create new I S A M f i l e s u s i n g t h e
ISMBLD program on the new system. Use ISMBLD t o load the sequential
f i l e s i n t o the I S A M f i l e s . You can load each o f t h e secondary index
f i l e s i n the same fashion.
2.4.2
Using a Custom B u i l t Program
Because the I S A M system i s so f l e x i b l e , i t allows t h e c r e a t i o n o f
f i l e s t h a t cannot be t r a n s f e r r e d by the standard method o u t l i n e d
above.
The most common type o f f i l e i n t h i s category w i l l be the
f i l e whose symbolic keys are not stored w i t h i n the data record.
(One
o f the many reasons why c o n s t r u c t i n g f i l e s o f t h i s type i s poor
p r a c t i c e i s t h a t i t makes t h e t r a n s f e r r i n g o f I S A M f i l e s more
cumbersome.)
To t r a n s f e r these non-standard I S A M f i l e s , you must create a custom
AlphaBASIC program t h a t outputs the contents o f the I S A M f i l e t o a
random f i l e t h a t can then be t r a n s f e r r e d t o the new system.
Another
custom program on the new system must then load t h i s random f i l e i n t o
t h e new I S A M f i l e .
To get the key associated w i t h a data record, i f t h a t symbolic key i s
n o t contained w i t h i n the data record,
you must use the I S A M 7 c a l l
w i t h i n AlphaBASIC.
2.4.3
Converting I S A M Access Programs t o Use LOKSER
See Chapter 6 f o r i n f o r m a t i o n on the F i l e Locking Service System,
LOKSER,
a v a i l a b l e w i t h AMOS 5.0 and AROSIL 1.1 releases and l a t e r .
I f you want t o convert your programs from performing f i l e l o c k i n g
u s i n g XLOCK and FLOCK t o t h e format used by LOKSER, r e f e r t o the
AMOS LOKSER User's Manual,
DSS-10022-00,
o r t h e AMOSIL LOKSER
User's Manua 1, DSS-10034-00.
DWM-00100-06,
REV COO
I S A M SYSTEM USER'S GUIDE
PART I
THE I S A M UTILITY PROGRAMS
The next few chapters discuss the I S A M u t i l i t y programs.
These programs: 1.
create and ( o p t i o n a l l y )
load an indexed sequential f i l e ; 2. d i s p l a y the
contents o f your data and index f i l e s ; and, 3. a l l o w more e f f i c i e n t use of
your index f i l e s by compressing index block e n t r i e s .
DWM-00100-06,
REV COO
CHAPTER 3
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
The ISMBLD program p r o v i d e s a convenient method f o r c r e a t i n g and l o a d i n g
I t g i v e s you t h e a b i l i t y t o c r e a t e a new indexed
indexed s e q u e n t i a l f i l e s .
s e q u e n t i a l f i l e , t o add r e c o r d s t o t h e data f i l e from an o r d i n a r y s e q u e n t i a l
data f i l e ,
and t o c r e a t e a secondary i n d e x f i l e t h a t cross-indexes t o a
p r i m a r y index f i l e .
3.1
GENERAL OPERATING INSTRUCTIONS
add
ISMBLD has t h r e e o p e r a t i n g modes: 1. c r e a t e a new indexed f i l e ; 2.
d a t a t o t h e new f i l e o r t o an e x i s t i n g f i l e ; and, 3. change t h e d e v i c e
A l l modes a r e c a l l e d v i a t h e g e n e r a l
s p e c i f i c a t i o n o f a data f i l e .
command:
If t h e indexed s e q u e n t i a l f i l e s p e c i f i e d by f i l e s p e c
I f the f i l e already
ISMBLD e n t e r s t h e c r e a t i o n mode.
e n t e r s t h e data l o a d i n g mode u n l e s s you have s p e c i f i e d
maintenance switch.
(NOTE: I f t h e f i l e a l r e a d y e x i s t s ,
Counted Update mode by u s i n g t h e I N switch.
See
"Suppressing E x c l u s i v e Open Mode.")
3.2
does n o t e x i s t ,
exists,
ISMBLD
the optional I D
you may s p e c i f y
S e c t i o n 3.3.1,
CREATION MODE
The c r e a t i o n mode i s t h e most commonly used mode. I n t h i s mode you
i n p u t s e r i e s o f parameters t h a t d e s c r i b e t h e d e s i r e d indexed s e q u e n t i a l
file.
From these parameters t h e ISMBLD program generates a d a t a
f i l e / p r i m a r y i n d e x f i l e combination o r a secondary i n d e x f i l e t h a t
cross-indexes t o an e x i s t i n g p r i m a r y i n d e x f i le.
DWM-00100-06,
REV COO
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
Page 3-2
S p e c i f y i n g F i l e Parameters
Before a c t u a l l y c r e a t i n g t h e f i l e ,
ISMBLD asks you a number o f
questions about your data f i l e .
I n response t o each o f t h e
questions, you are expected t o enter a v a l i d answer. Because o f t h e
myriad ways t h a t you can s e t up an indexed s e q u e n t i a l f i le, v e r y
I t i s therefore
l i t t l e v a l i d i t y checking i s done on your answers.
p o s s i b l e t o c r e a t e t o t a l l y useless f i l e s .
Be c a r e f u l .
For an
example o f t h e ISMBLD dialog, t u r n t o Chapter 10,
"Using I S A M From
W i t h i n AlphaBASIC."
The f o l l o w i n g sections describe t h e questions asked and the expected
responses:
3.2.1.1
"Size o f Key:"
Enter t h e s i z e o f t h e d e s i r e d key i n decimal bytes.
To minimize
index search time,
keep t h i s s i z e as s m a l l as possible. The
maximum key s i z e i s 256.
When you l a t e r access t h e I S A M f i l e s you
are now creating,
you must remember t o pad w i t h blanks o r o t h e r
Pad
characters keys t h a t are smaller than t h i s s p e c i f i e d size.
numeric f i e l d s i n the f r o n t o f t h e f i e l d ; pad symbolic keys a t the
end. One s i d e e f f e c t o f t h i s i s t h a t both b i n a r y and f l o a t i n g
p o i n t keys may be used.
'
3.2.1.2
" P o s i t i o n o f key:"
T h i s parameter s p e c i f i e s t h e l o c a t i o n o f t h e key w i t h i n t h e data
record. The symbolic key p o s i t i o n i s used when l o a d i n g indexed
s e q u e n t i a l f i l e s from s e q u e n t i a l f i l e s as the means o f determining
t h e symbolic key. Enter the number o f the f i r s t c h a r a c t e r - p o s i t i o n
i n t h e record which t h e key occupies; t h e f i r s t p o s i t i o n w i t h i n a
r e c o r d i s p o s i t i o n number one.
3.2.1.3
"Size o f data record:"
T h i s parameter d e f i n e s t h e s i z e o f the records i n the data f i l e o r
t h e maximum data record s i z e i n t h e case o f v a r i a b l e l e n g t h
records.
Specify t h i s s i z e i n bytes (decimal).
The data record
s i z e must be g r e a t e r than o r equal t o t h e key s i z e p l u s t h e key
position.
DWM-00100-06,
REV COO
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
3.2.1.4
Page 3-3
"Number o f records t o a l l o c a t e : "
T h i s parameter d e f i n e s t h e number o f records t h a t t h e data f i l e i s
t o contain.
(NOTE:
On AMOSIL systems,
a f t e r you answer t h i s
question,
ISMBLD
tells
you
how many index b l o c k s i t i s
If this
number
is
not
a u t o m a t i c a l l y a l l o c a t i n g f o r you.
sufficient,
you may s p e c i f y a d d i t i o n a l b l o c k s i n response t o the
q u e s t i o n "Empty index b l o c k s t o allocate:"-see S e c t i o n 3.2.1.6.)
3.2.1 .5
" E n t r i e s p e r index block:"
T h i s parameter a l l o w s you t o s p e c i f y t h e number o f e n t r i e s
contained i n an index block;
t h i s value can g r e a t l y a f f e c t t h e
e f f i c i e n c y o f searches and i n s e r t s w i t h i n t h e f i l e .
See S e c t i o n
3.5,
"Optimizing F i l e Parameters," f o r more i n f o r m a t i o n .
NOTE: On AMOSIL systems, ISMBLD does not ask t h i s question, s i n c e
i t a u t o m a t i c a l l y c a l c u l a t e s the e n t r i e s per index b l o c k f o r you,
3.2.1.6
"Empty index b l o c k s t o a l l o c a t e : "
ISMBLD a l l o c a t e s f o r you t h e bare minimum number o f index b l o c k s
you w i 11 need t o c o n t a i n keys f o r the s p e c i f i e d number o f data
records. This c a l c u l a t i o n i s based on t h e assumption t h a t t h e
index f i l e t r e e s t r u c t u r e w i l l be p e r f e c t l y balanced.
Since t h i s
i s r a r e l y t h e case, you w i 11 probably need t o s p e c i f y an a d d i t i o n a l
number o f index blocks,
3.2.1.7
"Primary D i r e c t o r y ? "
Ifyou a r e c r e a t i n g a p r i m a r y index and data f i l e combination,
e n t e r Y; ifyou are c r e a t i n g a secondary index f i l e , e n t e r N.
3.2.1.7.1
"Secondary F i l e "
I f you are b u i l d i n g a secondary index f i l e , ISMBLD prompts you
f o r the f i l e s p e c i f i c a t i o n o f the p r i m a r y index f i l e :
Secondary index t o f i l e :
Enter t h e s p e c i f i c a t i o n o f t h e p r i m a r y index f i l e t o which t h i s
secondary f i l e cross-indexes.
Type j u s t a RETURN t o e x i t ISMBLD.
You may create as many secondary index f i l e s as you want t h a t
cross-index t o a p a r t i c u l a r primary index f i l e by r e - i n v o k i n g
ISMBLD w i t h t h e s p e c i f i c a t i o n o f t h a t p r i m a r y index f i l e and
s p e c i f y i n g a new secondary index f i l e .
DWM-00100-06,
REV COO
Page 3-4
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
I f you have created a secondary index f i l e ,
your d i a l o g w i t h
ISMBLD i s now over. ,ISMELD r e t u r n s you t o monitor command l e v e l .
I f you are c r e a t i n g a data f i l e / p r i m a r y index f i l e combination,
ISMBLD asks you f o r more i n f o r m a t i o n (see below).
3.2.1.8
"Data F i l e Device?"
ISMBLD now asks you:
Data F i l e Device?
I f the data f i l e i s t o be on a d i f f e r e n t device than t h e index
I f they are t o
file,
e n t e r t h e name (and number) o f t h a t device.
i f t h e data
be on the same device, e n t e r a RETURN.
For example,
enter:
f i l e i s t o be on u n i t 1 o f device "DSK,"
Data F i l e Device? DSK1:3.3
FILE LOADING MODE
A f t e r an indexed s e q u e n t i a l f i l e has been created,
i t i s often
d e s i r a b l e t o load the data and index f i l e s w i t h data from an o r d i n a r y
s e q u e n t i a l data f i l e .
To a l l o w t h i s , ISMBLD e n t e r s t h e data l o a d i n g
mode once i t creates the indexed s e q u e n t i a l f i l e .
I f you want t o load data i n t o an e x i s t i n g data f i l e ,
ISMBLD t h e n responds:
t h e name o f t h a t f i le.
invoke ISMBLD w i t h
[Processina e x i s t i n a f i l e 1
T h i s n o t i f i e s you t h a t you a r e i n t h e f i l e loading
c r e a t i o n mode.
mode
and
not
the
ISMBLD now prompts you f o r a s e q u e n t i a l f i l e s p e c i f i c a t i o n by t y p i n g :
Load from f ile:
You may now e n t e r t h e f i l e s p e c i f i c a t i o n t h a t s e l e c t s t h e s e q u e n t i a l
data f i l e from which you want t o load.
A d e f a u l t extension o f .SEQ i s
assumed by ISMBLD. ( I f you do not want ISMBLD t o load t h e new f i l e f o r
you o r i f you have made an e r r o r i n the f i l e s p e c i f i c a t i o n you gave t o
ISMBLD, type a RETURN a f t e r the "Load from f i l e : " prompt; no data w i l l
be added t o the data f i l e . )
DWM-00100-06,
REV COO
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
3.3.1
Page 3-5
Suppressing E x c l u s i v e Open Mode ( t h e /N Switch)
When loading an e x i s t i n g f i l e , ISMBLD n o r m a l l y uses E x c l u s i v e Open
mode. I f you wish i t t o use Counted Update mode instead, i n c l u d e t h e
/N s w i t c h a t the end o f t h e ISMBLD command l i n e .
For example:
-.ISMBLD
3.4
MAIL/N [RETI
CHANGING THE DATA FILE DEVICE (THE /D SWITCH)
The o n l y c r e a t i o n data t h a t you can change i s t h e data f i l e device.
The /D s w i t c h provides t h i s f i e l d f o r examination and change. Simply
e n t e r the new d e v i c e name o r a RETURN ( t o leave t h e device unchanged).
To change the device t o the same device t h a t the index f i l e uses, e n t e r
a period
only.
I t i s your r e p o n s i b l i t y t o move t h e f i l e t o the
s p e c i f i e d device.
.
3.5
OPTIMIZING FILE PARAMETERS
T h i s s e c t i o n provides some h i n t s on
s e q u e n t i a l f i l e f o r maximum e f f i c i e n c y .
how
to
organize
an
indexed
Once your f i l e has s t a b i l i z e d and you a r e n ' t changing i t much,
I f your e v a l u a t i o n so
re-evaluate the o r i g i n a l f i l e parameters.
indicates, r e b u i l d the f i l e w i t h d i f f e r e n t parameters.
3.5.1
E n t r i e s p e r Index Block
NOTE TO AMOS/L USERS: ISMBLD a u t o m a t i c a l l y c a l c u l a t e s t h i s value f o r
you. T h i s s e c t i o n does not apply t o your system-s k i p down t o
S e c t i o n 3.5.2, "Empty Index Blocks t o Allocate."
A s m a l l value means f a s t e r
T h i s parameter i s a two-edged sword.
in-core searches, b u t more d i s k accesses and more b l o c k s p l i t s d u r i n g
A l a r g e value reduces t h e number o f d i s k accesses
record additions.
and block s p l i t s , b u t increases in-core search time and increases t h e
( A b l o c k s p l i t occurs i f you add
amount o f memory used f o r b u f f e r s .
a key t o an index block, b u t t h e r e i s no more room i n t h a t block;
ISAM automatically " s p l i t s "
t h a t b l o c k and r e d i s t r i b u t e s the keys
among the two new blocks.)
Since the index s t r u c t u r e i s f i x e d a t t h r e e l e v e l s deep, t h e maximum
number o f keys t h a t you may add t o an index w i t h o u t t h e t o p index
b l o c k s p l i t t i n g i s n-3, where n i s the number o f e n t r i e s p e r index
block.
When the t o p index b l o c k s p l i t s , t h e search t i m e through t h e
index increases due t o the p o s s i b i l i t y o f having t o do more d i s k
reads.
DWM-00100-06,
REV COO
CREATING AND LOADING AN I S A M FILE WITH ISMBLD
Page 3-6
When you use a f l o p p y disk,
t h e in-core search t i m e i s so small
compared t o a d i s k s e e k / t r a n s f e r t h a t any increase/decrease w i l l n o t
be apparent.
When you use a f a s t e r d i s k t h e t r a d e - o f f becomes
t r i c k i e r . As a rule,
keep t h e number o f e n t r i e s as l a r g e as
possible, c o n s i s t e n t w i t h t h e user memory p a r t i t i o n size.
The amount
o f index b u f f e r space r e q u i r e d i s :
5
*
*
((entries-per-block
(keysize
+ 4))+2)
where key s i z e i s rounded t o an even number o f bytes. Given this,
you should be able t o determine a reasonable value f o r the number o f
entries-per-block MUST be l e s s than
entries.
(NOTE: ( k e y s i z e + 4)
t h e more memory you
o r equal t o 510.) The more e n t r i e s per block,
use.
I t i s sometimesmoreefficient t o h a v e t h e t o p b l o c k s p l i t a
few times r a t h e r than t o eat up a l a r g e amount o f memory.
*
Empty Index Blocks t o A l l o c a t e
During creation, enough index b l o c k s are a l l o c a t e d t o support a
balanced index f i l e t r e e w i t h s u f f i c i e n t nodes f o r t h e number o f data
records a l l o c a t e d .
I n practice,
t h e index f i l e t r e e i s r a r e l y
balanced (unless you add records i n a t r u l y random number w i t h an
even d i s t r i b u t i o n o f key values).
Because o f t h i s , you should
a l l o c a t e empty index blocks.
For AMOS systems, a good number o f empty index b l o c k s t o a l l o c a t e i s
t h e t o t a l number o f data records d i v i d e d by t h e number o f e n t r i e s i n
an index block.
For AMOS/L systems, d o u b l i n g t h e number o f index b l o c k s a l l o c a t e d
a u t o m a t i c a l l y by I S A M i s a good number t o use. To do t h i s , simply
respond t o the "Empty index blocks t o a l l o c a t e " q u e s t i o n w i t h t h e
number ISMBLD d i s p l a y e d a f t e r you entered t h e number o f records t o
aL Locate.
DWM-00100-06,
REV COO
CHAPTER 4
DUMPING AN I S A M FILE WITH ISMDMP
The ISMDMP program p r o v i d e s a convenient method f o r u n l o a d i n g an indexed
I t a l s o p r o v i d e s a means o f
s e q u e n t i a l fil e i n t o a s e q u e n t i a l f i le.
examining t h e index f i l e s t r u c t u r e t o determine how balanced t h a t s t r u c t u r e
is.
NOTE: ISMDMP works the same on AMOS and AMOS/L systems.
4.1
GENERAL OPERATING INSTRUCTIONS
ISMDMP has two o p e r a t i n g modes: t h e f i r s t a l l o w s you t o output t h e
contents o f an indexed s e q u e n t i a l f i l e t o an o r d i n a r y s e q u e n t i a l f i l e ;
t h e second a l l o w s you t o d i s p l a y t h e index f i l e s t r u c t u r e on a t e r m i n a l
t o a l l o w a n a l y s i s thereof.
Both are invoked v i a the general command
form:
where f i lespec s p e c i f i e s an indexed s e q u e n t i a l f i l e and the o p t i o n a l /N
s w i t c h suppresses E x c l u s i v e Open mode.
(See below.)
A f t e r performing
some i n i t i a l i z a t i o n procedures, ISMDMP asks:
Output to:
Supply another f i l e s p e c i f i c a t i o n ;
t h i s one s e l e c t s t h e s e q u e n t i a l
ISMDMP assumes a d e f a u l t f i l e e x t e n s i o n o f .SEQ.
I f you
output f i le.
want t o e n t e r t h e index f i l e dump mode,
e n t e r TTY: as t h e f i l e
specification.
For example:
Output to: T T Y : m
DWM-00100-06,
REV COO
DUMPING AN I S A M FILE WITH ISMDMP
4.1.1
Page 4-2
Suppressing E x c l u s i v e Open Mode
ISMDMP n o r m a l l y uses E x c l u s i v e Open mode when performing i t s f i l e
I f you wish i t t o use Counted Update mode instead, use t h e
accesses.
/N s w i t c h a t the end o f the ISMDMP command l i n e .
For example:
-.ISMDMP STATINIRETJ
4.2
FILE DUMP MODE
I n t h i s mode, ISMDMP o u t p u t s t h e records o f t h e indexed s e q u e n t i a l f i l e
t o an o r d i n a r y s e q u e n t i a l f i l e i n ascending key order.
ISMDMP does no
t r a n s l a t i o n o f the records; i t outputs the records i n e x a c t l y t h e same
form as they were i n p u t a t some e a r l i e r date.
4.2.1
Sample Data F i l e D i s p l a y
We used ISMBLD t o c r e a t e a s m a l l I S A M data f i l e named LABELS. Then
we used t h e sample program i n Chapter 10,
"Using I S A M From W i t h i n
AlphaBASIC,"
t o place f i v e records i n the f i l e .
We then asked ISMDMP
t o place the data i n t h a t f i l e i n t o a f i l e named DATDMP:
5 records dumped
I f we use
DATDMP.SEQ),
t h e TYPE
we see:
FILMORE SUSAN
HINCHEY EDSEL
LAWRENCE T.E.
MUKLUK, H.
SAVOY JOHN
command
to
d i s p l a y t h e new f i l e (egg.,
TYPE
230 STILUOOD LOWELLMA15673200
6712 V I A MALAGA TUSTINCA90245102
1023 W. SANDS PANGUITCHUT98344100
345 PRAIRIE DOG LN BAKERCA98766120
891 E. DECATUR LAS VEGASNE89023103
Each record contains: 1. Customer name; 2. s t r e e t address;
3.
city;
4.
s t a t e (two l e t t e r s ) ; 5. z i p code; and, 6. t h r e e - d i g i t i d e n t i f y i n g
number ( c a l l e d a hash number).
4.3
INDEX FILE DUMP MODE
The dump mode i s intended p r i m a r i l y as a debugging tool, and w i l l not
f i n d much use among general users.
Therefore we p r o v i d e l i t t l e
documentation on i t s use.
Those o f you who understand t h e b a s i c
s t r u c t u r e o f t h e index f i l e should be able t o f i g u r e out t h e d i s p l a y
q u i t e easi ly.
DWM-001 00-06,
REV COO
Page 4-4
DUMPING AN I S A M FILE WITH ISMDMP
000003: FILMORE SUSAN
HINCHEY EDSEL
LAWRENCE T.E.
- - MUKLUK H.
SAVOY JOHN
000000000414 [ p o i n t s t o data record1
000000177777 L f ir s t record entered1
000000000206
00000000031I
000000000103
177777177776 Cindi cates l a s t record]
000000000000
-
...........................
000000
044506
000000
000005
DWM-00100-06,
REV COO
[ i n used blocks, t h i s number i s
junk-- ignore it.]
000000000000
Cin unused blocks,
free index block1
p o i n t s t o next
CHAPTER 5
COMPRESSING INDEX FILES WITH ISMCOM
NOTE: This command i s not used on AMOSIL systems.
1SMCOM.PRG compresses the upper l e v e l o f I S A M index f i l e s :
t h i s increases
access speed and may recover some storage room i n the index f i l e .
To use
ISMCOM, enter:
.
-I S M C O M
F i lespec
where f i l e s p e c s e l e c t s t h e index f i l e you want t o compress.
The program now
r e p o r t s i t s intended compression f a c t o r ( i n i t i a l l y based on 95%).
I f you
wish denser o r looser compression, e n t e r t h e percentage o f compression you
want I S M C O M t o use.
I f t h a t value i s v a l i d f o r the f i l e (based on t h e
number o f e n t r i e s per index block), t h e program proceeds: otherwise, i t
r e p o r t s the a c t u a l e f f e c t i v e value and a l l o w s you t o enter a new value.
The
o n l y way t o get 100% compression i s t o enter 100.
The program w i l l n o t
accept i n p u t o f a percentage o f less than 50%. ( I n a c t u a l practice, 50% can
47% i n some cases.)
Below i s a sample I S M C O M
be rounded down to,
say,
dialog:
NOBODY e l s e may use t h i s f i l e w h i l e I ' m p r o c e s s i n g i t .
Iam p l a n n i n g t o compress each b l o c k t o a t l e a s t 90 percent f u l l
I f t h a t i s n o t acceptable, e n t e r t h e percentage you d e s i r e : 7 6 m
I t w i l l a c t u a l l y work o u t t o be 80% f u l l
I f t h a t i s n o t acceptable, e n t e r t h e percentage you d e s i r e : m
No b l o c k s unchanged.
No b l o c k s freed.
No b l o c k s compressed.
Note t h a t a compression f a c t o r o f 100% u i 11 cause a b l o c k s p l i t t h e next
t i m e a t o p l e v e l index i s created.
The number 95% was chosen as the optimum
compression f a c t o r f o r most f i l e s .
A t t h e end o f compression, I S M C O M p r i n t s
some s t a t i s t i c s t h a t t e l l you how much compression was done and how much
good i t should do.
DWM-00100-06,
REV COO
I S A M SYSTEM USER'S GUIDE
PART I 1
PROGRAMMING WITH I S A M
T h i s s e c t i o n contains i n f o r m a t i o n on w r i t i n g assembly language programs and
AlphaBASIC programs t h a t use the I S A M f u n c t i o n s t o access and update I S A M
files.
The f i r s t chapter discusses general f i l e l o c k i n g techniques,
on AlphaBASIC programming.
with
emphasis
For i n f o r m a t i o n on w r i t i n g assembly language programs on t h e AMOS and AMOSIL
systems, r e f e r to:
AMOS Assembly Language Programmer's Manual, DWM-00100-43
AMOS M o n i t o r Calls, DWM-00100-42
AMOSIL Assembly Language Programmer's Manual, DSS-10007-00
AMOSIL M o n i t o r Calls, DSS-10003-00
For i n f o r m a t i o n on AlphaBASIC,
r e f e r to:
A lphaBASIC User1s Manua 1, DWM-00100-01
For i n f o r m a t i o n on the LOKSER F i l e Locking S e r v i c e System on AMOS and AMOSIL
systems,
and f o r i n s t r u c t i o n s on c o n v e r t i n g AlphaBASIC programs t o use t h e
LOKSER method o f f il e locking, r e f e r to:
AMOS LOKSER User's Manual, DSS-10022-00
AMOSIL LOKSER User's Manual, DSS-10034-00
DWM-00100-06,
REV COO
CHAPTER 6
FILE LOCKING TECHNIQUES
6.1
ABOUT THIS CHAPTER
T h i s chapter c o n t a i n s i n f o r m a t i o n on t h e f o l l o w i n g t o p i c s :
*
*
*
What i s f i l e l o c k i n g and why i s i t i m p o r t a n t ?
What a r e t h e f i l e l o c k i n g a l t e r n a t i v e s ?
What a r e t h e recommended procedures f o r l o c k i n g I S A M
f i l e s and u p d a t i n g data?
Because most programmers w i 11 be u s i n g LOKSER f r o m w i t h i n AlphaBASIC
programs t o c o n t r o l I S A M f i l e access,
t h i s c h a p t e r uses sample
AlphaBASIC programs t h a t use LOKSER t o i l l u s t r a t e t h e recommended
procedures f o r l o c k i n g I S A M f i l e s and p e r f o r m i n g data updates.
6.1.1
I f You Want t o Access I S A M t h r o u g h Assembly Language Programs
If you a r e n o t experienced w i t h u s i n g I S A M f r o m w i t h i n assembly
language programs, you may want t o read Chapters 7 and 8 o f t h i s
manual t o f a m i l i a r i z e y o u r s e l f w i t h t h e assembly LanguageIISAM
programming i n t e r f a c e f o r AMOS and AMOSIL systems b e f o r e c o n t i n u i n g
on w i t h t h i s chapter.
Ifyou access I S A M t h r o u g h assembly Language programs, t h e t e c h n i q u e s
discussed i n t h i s chapter a p p l y t o you, even though a l l examples a r e
i l l u s t r a t e d w i t h AlphaBASIC programs-- Use t h e AMOS o r AMOSIL m o n i t o r
c a l l s t h a t a r e e q u i v a l e n t t o t h e AlphaBASIC statements discussed
below t o p e r f o r m t h e same procedures.
For example, t h e AMOS INPUTL
m o n i t o r c a l l performs t h e same f u n c t i o n as t h e AlphaBASIC READL
statement-- i t i n p u t s and l o c k s a r e c o r d t h a t w i 11 l a t e r be updated.
Chapters 7 and 8 d i s c u s s t h e assembly language c a l l s t h a t a r e
creating,
e q u i v a l e n t t o t h e AlphaBASIC I S A M statements f o r l o c a t i n g ,
For i n f o r m a t i o n on t h e f i l e
and d e l e t i n g r e c o r d s i n an I S A M f i le.
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
Page 6-2
l o c k i n g monitor calls, see the s e c t i o n " F i l e I R e c o r d L o c k i n g S e r v i c e
(LOKSER) Monitor Calls,"
i n Chapter 6, "The F i l e S e r v i c e System,"
in
DWM-00100-42,
or the
AMOSIL
Monitor
t h e AMOS Monitor Calls,
DSS-10003 00.
-
I f your system does not have LOKSER i n s t a l l e d , you w i 11 want t o w r i t e
your own f i l e l o c k i n g r o u t i n e s t o prevent simultaneous update o f I S A M
files.
The s e c t i o n s below, however, w i l l g i v e you g u i d e l i n e s on t h e
proper order i n which t o perform f i l e l o c k i n g and data update steps.
6.1.2
I f You Want t o Access I S A M through AlphaBASIC
Ifyou a r e n o t already experienced i n u s i n g I S A M from w i t h i n
AlphaBASIC programs,
you may want t o read Chapter 10 o f t h i s manual
the
AlphaBASICIISAM
programming
t o fami l i a r i ze y o u r s e l f w i t h
i n t e r f a c e b e f o r e c o n t i n u i n g w i t h t h i s chapter.
I f your system does not have LOKSER i n s t a l l e d , then you w i l l want t o
t o perform f i l e
use XLOCK o r FLOCK (discussed i n S e c t i o n 6.3)
however,
locking.
You w i l l want t o read t h e examples i n s e c t i o n 6.4,
f o r i n f o r m a t i o n on the c o r r e c t order i n which t o ~ e r f o r mf i l e l o c k i n n
and data updates steps.
For i n f o r m a t i o n on c b n v e r t i n g A ~ ~ ~ ~ B A S
programs t h a t use FLOCK o r XLOCK t o use LOKSER,
r e f e r t o t h e AMOS
LOKSER User's Manual,
DSS-10022-00,
o r t h e AMOSIL LOKSER u s e r ' s
Manual, DSS-10034-00.
6.2
WHAT I S FILE LOCKING?
One p o t e n t i a l problem f o r m u l t i - u s e r systems i s t h e p o s s i b i l i t y t h a t
two users w i l l access t h e same f i l e a t t h e same t i m e and t r y t o
simultaneously update i n f o r m a t i o n i n t h a t f i le, causing data loss.
For
example:
1.
Iread a data record;
2.
You read t h e same data record;
3.
I change the data i n one f i e l d o f t h a t record,
and
write
the
r e c o r d out;
4.
You change data i n t h e same record and w r i t e t h e record out;
fly change disappears when you w r i t e out your copy o f t h e record because
when you o r i g i n a l l y read t h e record, my change had not y e t been made.
O f course,
we are n o t aware t h a t we a r e both u s i n g t h e same data
record-- keeping t r a c k o f e x a c t l y what records t o update i s an i n t e r n a l
procedure performed by t h e programs we a r e using.
DMM-00100-06,
REV COO
IC
FILE LOCKING TECHNIQUES
Page 6-3
I n o r d e r t o p r e v e n t t h i s k i n d o f simultaneous update problem,
it i s
necessary t o p e r f o r m " f i l e locking."
That is, when I need t o update a
record, t h e program Iam u s i n g l o c k s t h e e n t i r e f i l e o r j u s t t h e r e c o r d
so t h a t nobody e l s e can access i t u n t i 1 I am done.
When another
program t r i e s t o access t h e f i l e w h i l e i t i s locked, t h e program i s
t o l d t h a t t h e f i l e i s a l r e a d y i n use.
T h i s chapter discusses t h e v a r i o u s methods a v a i l a b l e t o
on AMOS and AMOS/L systems f o r p e r f o r m i n g f i l e locking.
6.3
your
programs
THE AMOS AND AMOS/L FILE LOCKING TECHNIQUES
For AMOS Versions 4.6A and AMOS/L Versions 1.OA and e a r l i e r , we p r o v i d e
two techniques f o r f i l e l o c k i n g from w i t h i n AlphaBASIC programs: u s i n g
t h e ALphaBASIC XLOCK o r FLOCK assembly language s u b r o u t i n e s .
As of AMOS V e r s i o n s 5.0 and AMOS/L Versions 1.1 and l a t e r ,
a third
a l t e r n a t i v e i s available:
LOKSER,
t h e F i l e L o c k i n g S e r v i c e System,
which p r o v i d e s automatic f i l e l o c k i n g n o t o n l y from w i t h i n AlphaBASIC
programs, b u t a t a system l e v e l as well.
To see why t h i s i s important,
c o n s i d e r t h e f a c t t h a t FLOCK and XLOCK a r e n o t t r u e s e c u r i t y devices,
b u t r e l y upon a l l programs accessing data f i l e s t o " f o l l o w t h e r u l e s "
i n checking t o see i f a f i l e i s i n use. A u s e r program can easi l y
circumvent t h e f i l e l o c k i n g by s i m p l y n o t u s i n g FLOCK o r XLOCK t o see
i f someone e l s e i s u s i n g t h e f i l e .
I n a d d i t i o n , FLOCK and XLOCK cannot
check f o r deadlock (a s i t u a t i o n i n which two programs come t o a
s t a n d s t i 11 because each needs t o access a f i l e t h e o t h e r has a l r e a d y
locked. 1
LOKSER, on t h e o t h e r hand, p r o v i d e s a system l e v e l f i l e l o c k i n g system.
ALphaBASIC, AlphaVUE, o r any o t h e r program r u n n i n g on an AMOS o r AMOS/L
system goes t h r o u g h t h e o p e r a t i n g system when i t wants t o access a
file.
On a system on which LOKSER i s i n s t a l l e d , t h e o p e r a t i n g system
always checks w i t h LOKSER b e f o r e accessing a f i l e t o see i f t h e f i l e i s
available.
I f LOKSER k n o w s t h a t a f i l e i s i n u s e , i t w i l l n o t a l l o u
another program o r user t o access i t . I f t h e System Operator r e q u e s t s
it,
LOKSER w i 11 even check t o make sure t h a t a l l programs and u s e r s
access s p e c i f i c f i l e s i n a s p e c i f i c o r d e r t o e l i m i n a t e t h e p o s s i b i l i t y
o f deadlock.
Note t h a t even i f your v e r s i o n o f AMOS o r AMOS/L s u p p o r t s LOKSER,
I f you wish, you may c o n t i n u e t o use
i n s t a l l i n g LOKSER i s o p t i o n a l .
XLOCK o r FLOCK i n s t e a d o f i n s t a l l i n g LOKSER.
However, LOKSER p r o v i d e s
a much s i m p l e r and more e r r o r r e s i s t a n t t e c h n i q u e f o r f i l e locking.
For complete i n f o r m a t i o n on u s i n g XLOCK, FLOCK, and LOKSER, r e f e r t o
t h e AMOS- LOKSER U s e r ' s Manua 1,
DSS-10022-00,
o r t h e AMOS/L LOKSER
U s e r ' s Manual,
DSS-10034-00.
Those manuals a l s o c o n t a i n a comparison
of t h e t h r e e methods and examples o f t h e i r use.
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
6.3.1
Page 6-4
XLOCK
XLOCK i s an assembly language s u b r o u t i n e c a l l a b l e from an AlphaBASIC
program.
Although i t has t h e disadvantage t h a t i t s use i s v o l u n t a r y
( t h a t is, i t c o n t r o l s f i l e access o n l y i f a l l p a r t i e s i n v o l v e d use i t
t o see whether o r n o t a f i l e i s i n use),
XLOCK does o f f e r t h e
advantages o f low overhead and h i g h speed.
XLOCK has a major
weakness-- i t l o c k s on a f i l e channel r a t h e r t h a n on an a c t u a l f i l e
specification.
That means t h a t o t h e r programs u s i n g XLOCK t o access
a locked f i l e can indeed access t h e f i l e i f t h e y open i t on a f i l e
channel o t h e r t h a n t h e one i t was o r i g i n a l l y l o c k e d on.
Or, i f a
program a c c i d e n t l y opens another f i l e on a f i l e channel t h a t was
p r e v i o u s l y locked, t h e new f i l e becomes locked.
XLOCK has another l i m i t a t i o n - - XLOCK does n o t t e c h n i c a l l y a l l o w you
t o l o c k an e n t i r e f i l e f o r E x c l u s i v e access,
a l t h o u g h you can
s i m u l a t e such a l o c k by l o c k i n g a l l r e c o r d s i n t h e f i l e .
6.3.1
.I E x c l u s i v e Access
Below i s an example o f u s i n g XLOCK w i t h i n an AlphaBASIC program t o
l o c k a f i l e f o r E x c l u s i v e access.
Because a l l r e c o r d s i n t h e f i l e
a r e locked, no i n d i v i d u a l r e c o r d l o c k s a r e necessary.
10
20
30
40
! XLOCK Parameters
!
Mode/status r e t u r n
!
F i l e channe 1 number
! B l o c k number
MAP1 XLOCK' PARS
MAP2 XLOCK1MODE,B,2
MAP2 XLOCK' FILE,B,2
MAP2 XLOCK'BLOCK,B,Z
C Set up code 3
XLOCK'MODE = 0
XLOCK'FILE = FILE'NO
XLOCK'BLOCK = 0
!
!
!
!
!
XCALL XLOCK, XLOCK'MODE,
I F XLOCK'MODE 0 0 &
THEN GOT0 XLOCK'ERROR
OPEN #FILEINO, FILE'NAME,
REC'SIZE, REC'NUM
C Get,
DWH-00100-06,
REV COO
process,
Lock o r r e t u r n e r r o r
F i l e channel number
W i l d card
lock e n t i r e f i l e
by l o c k i n g a l l r e c o r d s
Lock t h e f i l e f o r E x c l u s i v e use.
XLOCK'FILE, XLOCK'BLOCK
-
! Other user a l r e a d y has i t ?
! Nobody's g o t it-- OK t o open.
INDEXED'EXCLUSIVE, &
and o u t p u t r e c o r d 3
FILE LOCKING TECHNIQUES
300
310
320
330
Page 6-5
! Close and update l a s t record
! Clear the lock
! Release t h e f i l e .
CLOSE #FILEINO
XLOCK'MODE = 2
XCALL XLOCK,
XLOCK'MODE,
XLOCK'FILE,
XLOCK'BLOCK
C F i n i s h up 3
500 XLOCK'ERROR:
C E r r o r processing 3
6.3.1.2
Shared Access
Below i s an example of u s i n g XLOCK from w i t h i n an AlphaBASIC
program t o l o c k a f i l e f o r Shared use.
I n t h i s case you l o c k t h e
e n t i r e index f i l e v i a XLOCK, then READ t h e record, modify t h e data,
WRITE t h e record, and unlock t h e index f i l e .
10
MAP1 XLOCK'PARS
! XLOCK Parameters
20
MAP2 XLOCK1MODE,B,2
!
Mode/status r e t u r n
!
F i l e channel number
30
MAP2 XLOCK1FILE,B,2
!
B l o c k number
40
MAP2 XLOCK1BLOCK,B,2
50
XLOCK'FILE = FILE'NO
! F i l e channel number
60
! Open the f i l e .
OPEN #FILEINO, FILE'NAME, INDEXED, REC'SIZE, REC'NUM
70
80 RECORD'LOOP:
! Wildcard t o p r o t e c t index
90
XLOCK'BLOCK = 0
100
XLOCK'MODE = 0
! Mode = Lock o r r e t u r n
110
!
i f error.
115
! Lock t h e index.
XCALL XLOCK, XLOCK'MODE, XLOCK'FILE, XLOCK'BLOCK
120
I F XLOCK'MODE <> 0 &
130
THEN GOT0 XLOCK' ERROR
! I s index a v a i l a b l e ?
C
Get,
process,
and output record 3
200
XLOCK'MODE = 2
210
XCALL XLOCK, XLOCK'MODE,
220
GOT0 RECORD' LOOP
230
240 XLOCK'ERROR:
C E r r o r processing 3
6.3.2
! Mode = Clear l o c k
! Clear t h e index lock
XLOCK'FILE, XLOCK'BLOCK
! Get next record.
FLOCK
FLOCK i s an improved v e r s i o n o f XLOCK.
I t a l l o w s you t o lock a f i l e
f o r E x c l u s i v e and Shared access, and a l s o a l l o w s r e c o r d locks. As
w i t h XLOCK, i t s use by AlphaBASIC programs i s voluntary, and i t locks
on a fil e channel r a t h e r than on a f i l e s p e c i f i c a t i o n .
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
6.3.2.1
Page 6-6
E x c l u s i v e Access
No record locks are required,
10
s i n c e t h e e n t i r e f i l e i s locked.
! FLOCK r e t u r n code
MAP1 FLOCK' RETURN, F
€ Set up code 3
100
110
120
130
140
150
160
! Lock t h e f i l e f o r
! E x c l u s i v e access
XCALL FLOCK, 0, 6, FLOCK'RETURN, FILE'NO, 0
I F FLOCK/RETURN <> 0 &
THEN GOT0 FLOCK' ERROR
! Already i n use?
! Nobody's got it-! OK t o open.
OPEN #FILEINO, FILE'NAME, INDEXED'EXCLUSIVE, REC'SIZE,
REC'NUM
€ Process records 3
200
210
220
! Close and update l a s t record
! Release t h e f i l e
CLOSE #FILEINO
XCALL FLOCK,
1, 0, FLOCK'RETURN,
FILE'NO,
0
€ F i n i s h up 3
400 FLOCK'ERROR:
€ E r r o r processing 3
6.3.2.2
Shared Access
10
20
30
! FLOCK r e t u r n code
! Request shared f i l e
MAP1 FLOCKIRETURN,F
XCALL FLOCK, 0, 0, FLOCK'RETURN, FILE'NO, 0
I F FLOCK/RETURN <> 0 &
THEN GOT0 FLOCK' ERROR
! Already i n use?
50
! Nobody's got it-60
! OK t o open.
70
OPEN #FILEINO, FILE'NAME, INDEXED, REC'SIZE, REC'NUM
80 RECORD'LOOP:
90
! Lock the record
100
XCALL FLOCK, 3, 6, FLOCK'RETURN, FILE'NO, REC'NUM
110
I F FLOCK'MODE <> 0 &
THEN GOT0 FLOCK'ERROR
! I s record i n use?
120
READ #FILEINO, DATA'MAP
! Record i s free-- read i t
40
€ Process data i n record 3
200
210
220
! Lock a l l records
!
i n the f i l e
XCALL FLOCK,
4,
6,
FLOCK'RETURN,
€ Update index e n t r i e s 3
DWM-00100-06,
REV COO
FILE'NO,
REC'NUM
Page 6-7
FILE LOCKING TECHNIQUES
! Release a l l t h e records
0, FLOCK'RETURN, FILE'NO, REC'NUM
DATA'MAP
! Output t h e new data record
! Clear the data record lock
XCALL FLOCK, 5, 0, FLOCK'RETURN, FILE'NO, REC'NUM
GOT0 RECORD' LOOP
! Get n e x t record
ALL' DONE:
C F i n i s h processing 3
XCALL FLOCK, 6,
WRITE #FILEINO,
CLOSE #FILE 'NO
XCALL FLOCK,
1, 0,
! Close the f i l e
! Unlock t h e f i l e
FLOCK'RETURN, FILE'NO, 0
€ F i n i s h up 3
FLOCK'ERROR:
C E r r o r processing 3
6.3.3
LOKSER
As o f AMOS Version 5.0 and AMOSIL Version 1.1 and later,
another
technique f o r f i l e l o c k i n g i s a v a i l a b l e : LOKSER, t h e F i l e L o c k i n g
Service System. The o p t i o n a l LOKSER system p r o v i d e s automatic f i l e
l o c k i n g f o r a l l f i l e s on t h e system o r f o r o n l y those f i l e s
designated by t h e System Operator.
LOKSER a l s o a l l o w s you t o customize t h e f i l e access r u l e s f o r your
system.
For example, t h e System Operator can c o n f i g u r e LOKSER to:
prevent users from renaming o r d e l e t i n g c e r t a i n f i l e s , f o r c e programs
and users t o open c e r t a i n f i l e s i n a c e r t a i n order t o prevent
deadlock,
prevent users and programs from reading f i l e s o u t s i d e o f
t h e u s e r ' s p r o j e c t accounts except f o r the system accounts,
perform
automatic f i l e l o c k i n g on a l l f i l e s on the system o r f o r o n l y c e r t a i n
AMOS LOKSER User's Manual,
files,
etc.
Please
see
the
DSS-10022-00,
o r the AMOSIL LOKSER User's Manual,
DSS-10034-00,
for
d e t a i 1s on LOKSER's f e a t u r e s and operation.
6.4
RECOMMENDED FILE LOCKING TECHNIQUES
Because most users w i 11 be u s i n g LOKSER t o c o n t r o l I S A M f i l e access
from w i t h i n AlphaBASIC, t h i s s e c t i o n uses sample AlphaBASIC programs
t h a t i n t e r f a c e w i t h LOKSER t o i l l u s t r a t e t h e recommended procedures f o r
However the procedures o u t l i n e d below a l s o apply
locking I S A M f i l e s .
t o assembly language programs-- use t h e f i l e l o c k i n g monitor c a l l s t h a t
a r e e q u i v a l e n t t o the AlphaBASIC statements discussed below.
IMPORTANT NOTE: Under AMOS Versions 5.0 and AMOSIL Versions 1.1 and
later,
when LOKSER i s i n s t a l l e d , t h e l e v e l o f e r r o r checking performed
i s s i g n i f i c a n t l y more
by t h e monitor, AlphaBASIC, ISAM, and LOKSER,
thorough than i n previous system software releases. Because o f this,
some AlphaBASIC programs t h a t appeared t o execute c o r r e c t l y under
DWN-00100-06,
REV COO
FILE LOCKING TECHNIQUES
previous
releases.
following
AlphaBASIC
Page 6-8
releases w i l l produce e r r o r s under t h e l a t e r software
I n order t o understand t h e problems t h a t you may face,
the
d i s c u s s i o n describes the l o c k i n g l u n l o c k i n g performed by t h e
statements used t o access I S A M f i l e s .
I f your system does not have LOKSER i n s t a l l e d ,
a l l o f your e x i s t i n g
A lphaBASIC programs w r i t t e n under p r e v i o u s software releases w i 11
execute under AMOS 5.0 and AMOSIL 1.1 w i t h o u t any changes.
Without
LOKSER,
no checking i s done f o r simultaneous use o f a f i l e by m u l t i p l e
users o r c o r r e c t use o f the f i l e by a s i n g l e user.
However,
even i f
LOKSER i s not i n s t a l l e d , we recommend t h a t you f o l l o w t h e procedures
discussed below (using READL and WRITEL statements where appropriate)-your
even though automatic f i l e l o c k i n g w i 11 not be performed f o r you,
programs w i l l be i n t h e proper form so t h a t l a t e r conversion t o a
LOKSER system w i 11 be easy.
IfLOKSER i s i n s t a l l e d , you must f o l l o w t h e procedures o u t l i n e d below;
i.em, each step must be executed i n the proper sequence o r e l s e you
w i l l get an " ? I l l e g a l I S A M sequence" e r r o r .
You
must f o l l o w t h i s
sequence whether o r not you a r e u s i n g INDEXED o r INDEXED'EXCLUSIVE
modes.
The b a s i c concept t h a t LOKSER and I S A M use t o prevent m u l t i p l e users
from i n t e r f e r i n g w i t h each o t h e r d u r i n g I S A M f i l e accesses i s t o
a u t o m a t i c a l l y l o c k t h e p r i m a r y index ( . I D X I f i l e f o r E x c l u s i v e use a t
t h e s t a r t o f a c r i t i c a l procedure and t o unlock i t a t the end of t h e
procedure.
I n t e r m e d i a t e steps i n the procedure check t o make sure t h a t
t h e index f i l e i s locked.
The
following
table
shows
the
l o c k i n g l u n l o c k i n g operations performed by t h e i n d i v i d u a l steps:
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
AlphaBASIC
STATEMENT
OPERATION
Page 6-9
PRIMARY INDEX FILE
SECONDARY INDEX FILE
Locate record
Locked
Locked a t s t a r t ;
at finish
unlocked
Add key
Must be locked
Unlocked a t f i n i s h
Locked a t s t a r t ;
at finish
unlocked
Delete key
Must be locked
Locked a t s t a r t ;
at finish
unlocked
Get data record
Must be locked
I l l e g a l operation
Release data
record
Must be locked;
unlocked a t f i n i s h
I l l e g a l operation
READ
Input record
Must be locked;
unlocked a t f i n i s h
I l l e g a l operation
READL
I n p u t record
f o r update
(Data record
remains locked)
Must be locked
I l l e g a l operation
WRITE
Output m o d i f i e d
r e c o r d (Unlocks
data record)
Must be locked;
unlocked a t f i n i s h
I l l e g a l operation
WRITEL
Output new
r e c o r d (Unlocks
data record)
Must be locked
I 1l e g a l o p e r a t i o n
LOCK
Lock p r i m a r y
index
Locked
I 1lega 1 o p e r a t i o n
UNLOKR
Unlock record
Unlocked
I 1lega 1 o p e r a t i o n
(When we say "Locked"
o r "Unlocked"
i n t h e t a b l e above, we a r e
d e s c r i b i n g t h e a c t i o n s I S A M a u t o m a t i c a l l y performs on t h e index f i l e .
When we say "Must be locked," we mean t h a t t h e i n d i c a t e d statement may
n o t e x p l i c i t l y perform t h i s action, b u t t h a t t h i s c o n d i t i o n must e x i s t
i n order f o r successful completion o f the operation. Usually, i f you
f o l l o w t h e procedures discussed below, these necessary c o n d i t i o n s w i l l
a l r e a d y have been set up by p r e v i o u s operations.
But, sometimes you
must e x p l i c i t l y l o c k t h e p r i m a r y index f i l e y o u r s e l f .
See S e c t i o n
6.4.1,
"General Hints,"
below, f o r more information.)
The l o c k i n g and u n l o c k i n g are designed t o occur a t t h e proper places t o
a l l o w t h e procedures shown below ( c r e a t e a record, d e l e t e a record,
update a record) t o execute c o r r e c t l y .
Whether o r n o t LOKSER i s
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
Page 6-10
i n s t a l l e d on your system,
i t i s good programming p r a c t i c e f o r your
programs t o perform t h e procedures discussed below i n t h e o r d e r shown-I f LOSKER i s i n s t a l l e d on your system,
your programs MUST use t h e
recommender procedures i n t h e o r d e r shown, o r your programs w i 11 n o t
execute c o r r e c t l y .
6.4.1
General H i n t s
There a r e a couple o f s i t u a t i o n s t h a t a r i s e because o f t h e automatic
l o c k i n g procedures t h a t you must understand i n o r d e r t o c o r r e c t l y use
t h e automatic l o c k i n g and unlocking.
Since I S A M a l l o w s you t o have more than one r e c o r d i n a p h y s i c a l d i s k
block,
and LOKSER l o c k s p h y s i c a l d i s k b l o c k s r a t h e r t h a n l o g i c a l
records, l o c k i n g a r e c o r d w i 11 l o c k a l l l o g i c a l r e c o r d s i n t h e same
p r e v e n t i n g o t h e r u s e r s from accessing l o g i ca 1
p h y s i ca 1 d i s k block,
r e c o r d s w i t h i n t h e b l o c k you have locked.
So,
try
not
to
u n n e c e s s a r i l y l o c k a r e c o r d any l o n g e r t h a n you have to.
I n o r d e r t o understand how LOKSER and I S A M work together, you must
understand what resources a r e a c t u a l l y locked.
When you i n i t i a t e a
sequence o f s t e p s t o access an I S A M f i l e , I S A M r e q u e s t s LOKSER t o
l o c k t h e index ( . I D X I f i l e f o r e x c l u s i v e use and w a i t i f i t i s n o t
available e . ,
w a i t i f i t i s locked by another user).
By u s i n g
e x c l u s i v e locks, I S A M o b v i a t e s t h e need t o keep r e c o r d l o c k s on t h e
i n d e x f i l e , t h e r e b y r e d u c i n g t o a minimum t h e overhead t o access I S A M
files.
As t h e t a b l e above shows, those statements which b e g i n an
I S A M access sequence l o c k t h e index f i l e ; t h o s e statements t h a t occur
i n t h e middle o f an I S A M access sequence check t o make sure t h e index
i s locked and those statements t h a t t e r m i n a t e an I S A M sequence u n l o c k
t h e index f i l e .
I n a l l cases, when you access a secondary i n d e x
f i l e , i t i s locked and unlocked by each statement.
I n general, when an I S A M access statement f a i l s because o f an error,
I S A M w i l l u n l o c k t h e index f i l e b e f o r e i t r e t u r n s t o t h e user w i t h an
e r r o r code.
There a r e s e v e r a l e x c e p t i o n s t o t h i s rule,
however.
First,
when you i s s u e an I S A M 1 c a l l t o seek a record, I S A M w i 11
l e a v e t h e p r i m a r y i n d e x f i l e locked i f i t d e t e c t s an e r r o r 33,
"?Record n o t found."
T h i s i s so you can add t h e r e c o r d w i t h o u t
l e t t i n g another user p o t e n t i a l l y add i t between t h e t i m e you seek i t
and t h e t i m e you a c t u a l l y a t t e m p t t o add t h e key ( I S A M statement 3).
I f you a r e n o t going t o add t h e record, you must u n l o c k t h e p r i m a r y
i n d e x v i a an UNLOKR statement.
The second e x c e p t i o n o c c u r s when an
I S A M cannot access
e r r o r i s d e t e c t e d w h i l e u s i n g a secondary key.
t h e p r i m a r y i n d e x and t h u s you must always e x p l i c i t l y UNLOKR t h e
p r i m a r y index f i l e i n t h i s case.
You w i l l n o t i c e i n a l l o f t h e examples below t h a t e r r o r p r o c e s s i n g i s
an i m p o r t a n t p a r t o f your I S A M access program.
Two main t y p e s of
e r r o r s must be d e t e c t e d and handled: "hard"
e r r o r s d e t e c t e d by
AlphaBASIC (e.g.,
a "?record i n use" e r r o r ) ,
and " s o f t "
errors
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
Page 6-11
detected by I S A M (egg.,
"?Index i s f u l l " ) .
The main d i f f e r e n c e
between the AlphaBASIC hard e r r o r s and the I S A M s o f t e r r o r s i s t h a t
i f your program does not i n t e r c e p t and handle a hard error,
AlphaBASIC i n t e r r u p t s your program and r e t u r n s i t s user t o monitor
I f your program does not i n t e r c e p t and handle a s o f t
command l e v e l .
error, AlphaBASIC does not r e p o r t the e r r o r o r i n t e r r u p t the program,
You can see t h a t i t
but severe damage can r e s u l t t o your I S A M f i l e s .
i s v e r y important f o r your programs t o look f o r and handle both hard
and s o f t e r r o r s .
Note t h a t you use ERF(#file-channel) f u n c t i o n t o d e t e c t I S A M e r r o r s .
Ifyou want t o PRINT out the value o f the ERF function, do so b e f o r e
p e r f o r m i n g an UNLOKR statement;
UNLOKR causes t h e ERF f u n c t i o n t o
r e t u r n a zero.
You use the ERR(x) f u n c t i o n t o d e t e c t hard e r r o r s .
of this
For a l i s t o f a l l I S A M s o f t e r r o r codes, see S e c t i o n 10.6
manual.
For a l i s t o f a l l hard (AlphaBASIC) e r r o r codes, and f o r
i n f o r m a t i o n on the ERR(x1 f u n c t i o n and the ON ERROR GOT0 and RESUME
hard e r r o r t r a p p i n g statements,
see Chapter 17 o f t h e AlphaBASIC
User's Manual. You w i l l n o t i c e t h a t t h e ERF and ERR f u n c t i o n s can
r e t u r n t h e same e r r o r codes-- these do r e ~ r e s e n td i f f e r e n t errors,
however! For example, an ERR e r r o r #36 i s " ? I n v a l i d s u b r o u t i n e
version,"
while. an ERF e r r o r #36 i s "?Index f i l e i s f u l l . "
Your
i n t e r p r e t a t i o n o f t h e e r r o r code depends on whether t h e e r r o r code
whether i t i s a s o f t I S A M o r hard
was r e t u r n e d by ERF o r ERR; i.e.,
AlphaBASIC e r r o r .
6.4.2
Using I S A M w i t h a S i n g l e Key
The f o l l o w i n g examples show t h e c o r r e c t use o f I S A M f i l e s t h a t have
o n l y a s i n g l e index f i l e .
Note t h a t t h e procedures show below have
always been required; however, i t i s o n l y w i t h the release o f LOKSER
t h a t they are being enforced.
Thus, some programs which may have
seemed t o work c o r r e c t l y i n t h e past w i l l now generate e r r o r s when
LOKSER i s i n s t a l l e d on your system.
6.4.2.1
Example 1
-
C r e a t i n g a Record
T h i s example shows t h e proper techique f o r c r e a t i n g a new record i n
an I S A M f i l e .
20
30
40
50
60
100
DWM-00100-06,
MAP1
DATA'MAP
MAP2 SYM1KEY,S,16
OPEN #FILEINO, FILE'NAME,
NEXT' RECORD:
€ Create t h e record 3
I S A M #FILEINO,
REV COO
1, SYM'KEY
! Primary key
! Open the f i l e f o r Shared use
INDEXED,
REC'SIZE,
REC'NUM
! I s i t t h e r e already?
FILE LOCKING TECHNIQUES
110
120
130
140
150
160
170
180
190
200
210
6.4.2.2
Page 6-12
I F ERF(FILEINO) <> 33 &
THEN GOT0 ISAM'ERROR
ADD'RECORD:
I S A M #FILE'NO, 5, SYM'KEY
I F ERF(FILEINO) <> 0 &
THEN GOT0 I S A M ' ERROR
WRITEL #FILE'NO, DATA'MAP
I S A M #FILE'NO, 3, SYM'KEY
I F ERF(FILE'N0) <> 0 &
THEN GOT0 ISAM'ERROR
GOT0 NEXT'RECORD
ISAM'ERROR:
UNLOKR #FILE1NO
GOT0 NEXT'RECORD
E x a m ~ l e2
-
! I f record exists,
t r y again.
! F i n d next f r e e record
! Check f o r e r r o r
! Output t h e record
! Add key t o index
! Check f o r e r r o r
! Get another record
! Release r e c o r d and
!
p r i m a r y index f i l e
D e l e t i n a a Record
T h i s example shows t h e proper technique f o r d e l e t i n g a record from
an I S A M f i l e .
The main d i f f e r e n c e between t h i s technique and t h e
technique used by p r e v i o u s I S A M releases i s t h a t you must use a
READL statement t o lock the data r e c o r d being deleted.
10
20
30
40
50
60
70
MAP1
DATA ' MAP
MAP2 SYM1KEY,S,16
MAP2 RECORD1DATA,S,48
! Open t h e f i l e f o r
! Shared use:
OPEN #FILEUNO, FILE'NAME, INDEXED,
NEXT'RECORD:
C S e l e c t r e c o r d t o be d e l e t e d 3
LOOKUP'RECORD:
ISAN #FILE'NO, 1, SYM'KEY
I F ERF(FILE'N0) 0 0 &
THEN GOT0 ISAM'ERROR
READL #FILEINO, DATA'MAP
I S A M #FILEINO, 4, SYM'KEY
I F ERF(FILE'N0) O 0 &
THEN GOT0 ISAM'ERROR
I S A M #FILEINO, 6, SYM'KEY
I F ERF(FILEnNO) <> 0 &
THEN GOT0 ISAM'ERROR
GOT0 NEXT'RECORD
ISAM'ERROR:
UNLOKR #FILE'NO
GOT0 NEXT'RECORD
DWM-00100-06,
! Primary key
REV COO
REC'SIZE,
REC'NUM
! I s i t t h e r e already?
! I f r e c o r d does not exist,
!
t r y again
! Read and l o c k t h e record.
! D e l e t e key from index
! Check f o r e r r o r
! D e l e t e data r e c o r d
! Check f o r e r r o r
! Get another r e c o r d
! Release r e c o r d and p r i m a r y
! index f i l e
FILE LOCKING TECHNIQUES
6.4.2.3
Examole 3
- Uodatina
Page 6-13
a Record
T h i s example shows t h e proper technique f o r updating a record i n an
I S A M f i le.
Note t h a t i f you are changing the key, you MUST do so
and
by f i r s t d e l e t i n g the record (as described i n S e c t i o n 6.4.2.2)
then adding t h e m o d i f i e d record back (as described i n S e c t i o n
6.4.2.1).
You must use READL t o read and lock t h e data record.
READL p r o h i b i t s anyone from changing t h e record by l o c k i n g t h e d i s k
b l o c k t h a t contains the data record. You should t r y t o minimize
t h e amount o f processing between the READL and WRITE statements
(WRITE unlocks the record and the index f i l e ) .
10
20
30
35
40
50
100
110
120
MAP1
DATA 'MAP
MAP2 SYM8KEY,S,16
OPEN #FILEINO, FILE'NAME,
REC'SIZE, REC'NUM
NEXT'RECORD:
C S e l e c t record 3
I S A M #FILEINO, 1, SYM'KEY
I F ERF(FILE8NO) <> 0 &
THEN GOT0 I S A M 1 ERROR
READL #FILEINO, DATA'MAP
! Primary key
! Open the f i l e f o r
!
E x c l u s i v e use.
INDEXED'EXCLUSIVE, &
! I s i t t h e r e already?
-
! Record n o t e x i s t ?
t r y again
! Read and lock t h e record.
C Process data i n record 3
200
210
220
23 0
240
WRITE #FILEINO, DATA'MAP
GOT0 NEXT'RECORD
ISAM'ERROR:
UNLOKR #FILEINO
GOT0 NEXT'RECORD
! Output and unlock t h e record
! Release r e c o r d and p r i m a r y
!
index f i l e
Using I S A M w i t h M u l t i p l e Keys
The o n l y change from pre-LOKSER releases f o r u s i n g m u l t i p l e keys
e . ,
secondary index f i l e s ) i s t h a t you must ensure t h a t t h e
I f you l o c a t e t h e record u s i n g t h e
p r i m a r y index f i l e i s locked.
I S A M w i l l lock t h e index f o r you a u t o m a t i c a l l y
p r i m a r y index f i l e ,
(as w i t h s i n g l e key accesses).
However, i f you l o c a t e a record based
on a secondary key, you must use t h e LOCK statement t o e x p l i c i t l y
l o c k the primary index f i l e .
The f o l l o w i n g examples show t h e c o r r e c t
use o f I S A M f i l e s w i t h m u l t i p l e keys. Note t h a t the procedures shown
i t i s only w i t h the
below have always been required.
However,
release o f LOKSER t h a t these procedures are being enforced.
Thus,
some programs which may have seemed t o work i n t h e past w i l l generate
e r r o r s when run on a system w i t h LOKSER i n s t a l l e d .
DWM-00100-06,
REV COO
FILE LOCKING TECHNIQUES
6.4.3.1
Example 1
-
Page 6-14
C r e a t i n g a Record
Note t h a t t h e example shows the secondary key being added b e f o r e
index f i l e locked
t h e p r i m a r y key; t h i s keeps the p r i m a r y . I D X
u n t i l t h e e n t i r e process i s completed.
MAP1 DATA ' MAP
MAP2 SYM1KEY,S,16
MAP2 SEC1KEY,S,16
OPEN #FILEINO,
FILE'NAME,
! Primary key
! Secondary key
! Open the p r i m a r y index
!
f i l e f o r Shared use
INDEXED,
REC'SIZE,
REC'NUM
! Open the secondary index
!
f i l e f o r Shared use
OPEN #SEC'FILEINO,
NEXT'RECORD:
C Create r e c o r d 3
200
210
220
230
240
250
260
270
280
290
300
310
320
330
340
350
6.4.3.2
SEC'FILE'NAME,
I S A M #FILEINO, 1, SYM'KEY
I F ERF(FILEINO) 0 33 &
THEN GOT0 I S A M ' ERROR
I S A M #SECIFILE'NO, 1, SEC'KEY
I F ERF(SEC'FILEINO) <> 33 &
THEN GOT0 ISAM'ERROR
ADD 'RECORD:
I S A M #FILEINO, 5, SYM'KEY
I F ERF(FILEINO) 0 0 J%
THEN GOT0 I S A M ' ERROR
WRITEL #FILEINO, DATA'MAP
I S A M #SECIFILE'NO, 3, SEC'KEY
I F ERF(SECIFILE'NO) 0 0 &
THEN GOT0 ISAM'ERROR
I S A M #FILEINO, 3, SYM'KEY
I F ERF(FILEINO) O 0 &
THEN GOT0 ISAM'ERROR
GOT0 NEXT' RECORD
I S A M ' ERROR:
UNLOKR #FILEINO
GOT0 NEXT'RECORD
Example 2
- Deleting a
INDEXED,
REC'SIZE,
REC'NUM
! I s t h e r e c o r d t h e r e already?
! Record exists?-process e r r o r
! Record i n secondary index?
! Record exists?-process e r r o r
! F i n d next f r e e record
! Check f o r e r r o r
! Output t h e record
! Add t h e secondary key
! Check f o r e r r o r
! Add t h e p r i m a r y key
! Check f o r e r r o r
! Get t h e next r e c o r d
! Release t h e r e c o r d and
!
t h e p r i m a r y index f i l e
Record
T h i s example shows t h e proper technique f o r d e l e t i n g a record from
I f you o r i g i n a l l y l o c a t e
an I S A M f i l e w i t h m u l t i p l e index f i l e s .
t h e record ( v i a an I S A M 1 statement) based on t h e p r i m a r y key, the
should be used w i t h an e x t r a
technique shown i n S e c t i o n 5.4.2.2
s t e p t o d e l e t e the secondary key.
The example below shows t h e
processing t h a t i s r e q u i r e d i f you o r i g i n a l l y l o c a t e t h e record on
a secondary key.
DWM-001 00-06,
REV COO
Page 6-15
FILE LOCKING TECHNIQUES
MAPl DATA 'MAP
MAP2 SYVsKEY,S,16
MAP2 SECaKEY,S,16
OPEN #FILEINO,
! P r i m a r y key
! Secondary key
! Open the p r i m a r y index f i l e
!
f o r E x c l u s i v e use
FILE'NAME,
INDEXED'EXCLUSIVE, REC'SIZE, REC'NUM
! Open the secondary index f i l e
!
f o r E x c l u s i v e use
SEC'FILE'NAME, INDEXED'EXCLUSIVE, 8
OPEN #SECIFILE'NO,
REC 'SIZE, REC'NUM
NEXT'RECORD:
C S e l e c t record t o d e l e t e 3
LOCK #FILEINO
I S A M #SECIFILE'NO, 1, SEC'KEY
I F ERF(SECIFILE'NO) <> 0 &
THEN GOT0 ISAM'ERROR
DELETE'RECORD:
READL #FILEBNO, DATA'MAP
I S A M #SECIFILE'NO,
4, SEC'KEY
I F ERF(SECIFILE'NO) <> 0 &
THEN GOT0 ISAM'ERROR
I S A M #FILEINO, 4, SYM'KEY
I F ERF(FILEINO) <> 0 8
THEN GOT0 SI AM' ERROR
I S A M #FILEINO, 6, SYM'KEY
I F ERF(FILEINO) <> 0 &
THEN GOT0 ISAM'ERROR
GOT0 NEXT'RECORD
ISAM'ERROR:
UNLOKR #FILEBNO
GOT0 NEXT'RECORD
6.4.3.3
Example 3
- Updating
! Lock p r i m a r y index f i l e
! I s t h e r e c o r d there?
!
- process e r r o r
Yes - read and lock
No
!
record
! D e l e t e key from secondary
! index.
! Check f o r e r r o r
! D e l e t e key from p r i m a r y index
! Check f o r e r r o r
! D e l e t e data record
! Check f o r e r r o r
! Get another record
! Release t h e record and the
!
p r i m a r y index f i l e
a Record
Remember t h a t i f t h e m o d i f i c a t i o n s t o the record i n c l u d e d changing
t h e primary key, you must f i r s t d e l e t e the o l d record (as discussed
and then add the new r e c o r d (Section 6.4.3.1).
i n S e c t i o n 6.4.3.2)
MAPl
DATA'MAP
MAP2 SYM1KEY,S,16
MAP2 SECBKEY,S,16
OPEN #FILEaNO, FILE'NAME,
! Primary key
! Secondary key
! Open the p r i m a r y index f i l e
!
f o r Shared use
INDEXED,
REC'SIZE,
REC'NUM
! Open the secondary index f i l e
!
f o r Shared use
SEC'FILE'NAME, INDEXED, &
OPEN #SECIFILE'NO,
REC'SIZE, REC'NUM
DWM-00100-06,
REV COO
F I L E LOCKING TECHNIQUES
Page 6-16
NEXT'RECORD:
C Select a record f o r updating 3
LOCK #FILE1NO
ISAM #SECIFILE'NO,
1, SEC'KEY
C> 0 &
I F ERF(SEC'FILEINO)
THEN GOT0 ISAM'ERROR
READL #FILEINO,
DATA'MAP
OLDISECIKEY = SEC'KEY
C Update data i n r e c o r d 3
I F OLDISECIKEY = SECIKEY
THEN GOT0 OUT'RECORD
! Lock p r i m a r y index f i l e .
! Find the record
! I s record there?
!
Yes
g e t and l o c k it.
-
&
! D i d s e c o n d a r y k e y change?
! Secondary k e y changed
!
remove o l d i n d e x e n t r y
ISAM #SEC'FILEINO,
4, OLD'SEC'KEY
I F ERF(SEC1FILE'NO) C> 0 &
THEN GOT0 ISAM'ERROR
!
ISAM #SEC'FILEINO,
3, SEC'KEY
!
I F ERF(SECIFILE'NO) C> 0 &
THEN GOT0 IS9M1 ERROR
!
!
OUT'RECORD:
WRITE #FILEINO,
DATA'MAP
GOT0 NEXT'RECORD
ISAM'ERROR:
!
UNLOKR #FILEINO
!
GOT0 NEXT'RECORD
DWM-00100-06,
REV COO
--
Check f o r e r r o r
Add new k e y
Check f o r e r r o r
O u t p u t and u n l o c k t h e r e c o r d
Release t h e r e c o r d and
unlock primary index f i l e
CHAPTER 7
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
NOTE: T h i s s e c t i o n assumes t h a t you are an experienced assembly
language programmer and t h a t you are f a m i l i a r w i t h t h e Alpha Micro CPU
For i n f o r m a t i o n on these
i n s t r u c t i o n set and t h e AMOS monitor c a l l s .
the
topics, r e f e r t o t h e AMOS Assembly Language Programmer's Manual,
WD16 Microcomputer Programmer's Reference Manual, DWM-00100-04,
and
t h e AMOS M o n i t o r C a l l s Manual.
The I S A M program i s implemented as a FETCHable memory module which a l l o w s
t h e assembly language programmer easy access t o t h e f e a t u r e s o f indexed
Refer t o t h e AMOS
sequential f i l e s .
(NOTE: FETCH i s an AMOS monitor c a l l .
M o n i t o r C a l l s Manual f o r i n f o r m a t i o n on the r o u t i n e s w i t h i n t h e o p e r a t i n g
system ( c a l l e d "monitor c a l l s " )
t h a t have been made a v a i l a b l e t o your
assembly language programs.) I t i s through t h e I S A M module t h a t h i g h l e v e l
The
languages such as AlphaBASIC g a i n access t o indexed s e q u e n t i a l f i l e s .
I S A M program i s f u l l y re-entrant, and could t h e r e f o r e be made r e s i d e n t i n
system memory i f more than one user a t a t i m e i s going t o be u s i n g indexed
sequent ia 1 f iles.
-
In
The I S A M program i t s e l f takes up approximately 4K b y t e s o f memory.
a d d i t i o n t o t h i s space, another 1 t o 4K bytes i s r e q u i r e d f o r each indexed
s e q u e n t i a l f i l e t h a t you a r e processing.
T h i s memory space i s u s u a l l y
you may,
a l l o c a t e d by t h e I S A M system u s i n g the GETMEM m o n i t o r c a l l ;
however, a l l o c a t e your own b u f f e r areas (see S e c t i o n 7.2.2).
GENERAL CALLING SEQUENCE
The v a r i o u s I S A M subroutines are c a l l e d v i a a d i s p a t c h t a b l e a t t h e
To make t h i n g s easier,
the
file
s t a r t o f t h e I S A M program.
DSKO:ISUSYM.MACC7,73
defines the t a b l e offsets.
This f i l e also
contains symbols f o r t h e v a r i o u s r e t u r n codes.
A l l t a b l e o f f s e t s begin
w i t h a p e r i o d (egg., .ICLOS, t h e close r o u t i n e ) .
A l l r e t u r n codes have
IS.xxx
(e.g.,
IS.EOF,
t
h
e
e
n
d
o
f
f
i l e r e t u r n code).
t h e general form
DWM-00100-06,
REV COO
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
NOTE: 1SUSYM.MAC
program.
i s designed t o be COPYed
by
your
Page 7-2
assembly
language
To c a l l t h e close r o u t i n e (.ICLOS) w i t h the base o f t h e 1SAM.SYS module
contained i n r e g i s t e r R4, use t h e f o l l o w i n g code:
.ICLOS (R4)
CALL
A l l arguments a r e passed i n r e g i s t e r s .
NOTE: As o f AMOS Versions 5.0
and later, t h e contents o f RO a r e s i g n i f i c a n t when making some o f t h e
c a l l s discussed below-- see t h e c a l l d e s c r i p t i o n s f o r more i n f o r m a t i o n .
For i n f o r m a t i o n on t h e f l a g s you can set i n RO f o r some of t h e c a l l s
discussed below, see Chapter 9, "Standard I S A M Symbols f o r Assembly
Language Programmers."
Each c a l l r e t u r n s w i t h a completion code i n RO.
A successful r e t u r n
(1S.SUC) i s i n d i c a t e d by a zero i n RO; t h e i n d i c a t o r s ( a l s o known as
c o n d i t i o n codes o r c o n d i t i o n f l a g s ) on r e t u r n r e f l e c t success o r e r r o r
status.
The 2 - b i t i s set i f successful (BNE branches on e r r o r ) .
INITIALIZING THE I S A M SYSTEM (.INIT)
Before your program can access an indexed s e q u e n t i a l f i l e ,
you must
t e l l t h e I S A M system t h a t you exist; t h i s i s done v i a t h e .INIT c a l l .
The .INIT c a l l a l l o c a t e s space f o r the u s e r ' s impure v a r i a b l e s and does
minor housekeeping chores.
NOTE: Your program c a l l s .INIT o n l y once
regardless o f the number o f XSAM f i l e s t h a t are t o be opened.
C a l l i n g Sequence:
Parameters:
R4,
Returns :
R2
R3
R5
User a l l o c a t i o n r o u t i n e address ( o p t i o n a l )
User d e a l l o c a t i o n r o u t i n e address ( o p t i o n a l )
Used t o pass i n f o r m a t i o n t o user memory
a l l o c a t i o n routines (optional).
CALL
.INIT(Rn)
RO
R5
Indicators
Completion code
User memory p o i n t e r
Z i f no e r r o r
The user memory p o i n t e r t h a t i s returned i n R5 i s a p o i n t e r t o your
impure area.
This p o i n t e r i s needed by a l l o t h e r I S A M calls;
if
convenient, leave i t i n R5 s i n c e a l l c a l l s look f o r i t there.
DWM-00100-06,
REV COO
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
Page 7-3
User Supplied A l l o c a t i o n and D e a l l o c a t i o n Routines
I n many cases, the program c a l l i n g t h e I S A M program w i l l do i t s own
memory management, and not want I S A M t o use GETMEMs t o do so.
To
a l l o w you t o do your own a l l o c a t i o n ,
t h e .INIT c a l l a l l o w s t h e
.INIT uses
passing o f a l l o c a t i o n and d e a l l o c a t i o n r o u t i n e addresses.
i t s own r o u t i n e s (which use GETMEMs) i f you pass a zero i n s t e a d o f an
address.
The user a l l o c a t i o n r o u t i n e i s c a l l e d w i t h t h e d e s i r e d module s i z e i n
R1. The .INIT c a l l expects the address o f t h e assigned module t o be
r e t u r n e d i n R1. You may not modify any o t h e r r e g i s t e r s .
The user d e a l l o c a t i o n r o u t i n e i s c a l l e d w i t h the address o f t h e
Do n o t modify any o t h e r r e g i s t e r s .
If
module t o be d e l e t e d i n R1.
you pass a zero t o .INIT i n R3, no d e a l l o c a t i o n occurs.
The c u r r e n t v e r s i o n o f I S A M a l l o w s you t o move any o f the modules
ISAM i s
t h a t I S A M requests as w e l l as the I S A M program i t s e l f .
immune t o such movement as long as the user memory p o i n t e r ( i n R 5 )
and the FPN ( f i l e p a i r number, see S e c t i o n 7.6.1)
associated w i t h a
g i v e n f i l e are updated t o show any movement.
(The FPN i s u s u a l l y i n
R 1 .)
7.3
FINALIZING I S A M PROCESSING (.IFIN)
When you are through processing indexed s e q u e n t i a l f i l e s , you must c a l l
t h e .IFIN r o u t i n e . T h i s c a l l d e a l l o c a t e s any space used by I S A M i f a
user dea l l o c a t i o n r o u t i n e has been provided; o t h e r w i s e t h e modules are
n o t d e l e t e d u n t i l t h e j o b EXITS. (EXIT i s an AMOS m o ~ n i t o r c a l l . )
C a l l i n g Sequence:
Parameters:
Returns :
R5
User memory p o i n t e r
CALL
.IFIN(Rn)
RO
Indicators
.
I S SUC
Z i f no e r r o r
The .IFIN r o u t i n e cannot f a i l ,
s u c c e s s f u l completion code i n RO.
DWM-00100-06,
REV COO
therefore
it
always
returns
the
WRITING AVOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A Y
Page 7-4
OPENING A FILE FOR PROCESSING (.IOPNR)
You must open an indexed s e q u e n t i a l f i l e v i a t h i s c a l l b e f o r e you can
process the f i l e i n any way.
Also use t h i s c a l l when opening a
If
secondary index f i l e f o r processing a p r e v i o u s l y opened data f i l e .
you execute t h i s c a l l on a p r i m a r y index f i l e , t h e c a l l a l s o opens t h e
i f you execute t h e c a l l on a secondary index
associated data f i l e ;
f i l e , t h e c a l l opens t h e index f i l e only.
Thus t o process a data f i l e
w i t h a secondary index f i l e , you must execute two .IOPNR c a l l s : once t o
and once t o open the
open the data fil e and p r i m a r y index f i le,
secondary index f i le.
C a l l i n g Sequence:
RO
Parameters:
R5
You may set the f o l l o w i n g f l a g s :
IS.EXC
Open i n E x c l u s i v e mode; o t h e r wise Counted Update mode i s used.
IS.ERP
P r i n t e r r o r messages b e f o r e returning.
1S.FWT
Wait f o r f i l e i f i t i s i n use.
P o i n t e r t o A S C I I f ilespec s t r i n g describi n g t h e index f i l e t o be opened.
I f the
index f i l e i s a primary index, t h e data
f i l e must have t h e same name.
User memory p o i n t e r
CALL
.IOPNR (Rn)
-
-
R2
Returns :
RO
R1
Indicators
-
Completion code
Unique F i l e Pai r Number (FPN)
Z i f no e r r o r
The f i l e p a i r number (FPN) i s a p o i n t e r t o the memory module t h a t has
been a l l o c a t e d f o r t h e storage needed by t h i s p a r t i c u l a r indexed
sequential f i l e .
The read, write, and d e l e t e r o u t i n e s use t h e FPN t o
t e l l t h e I S A Y program which indexed s e q u e n t i a l f i l e s t o process o f t h e
ones you may have open.
Ifyou must move t h e module a l l o c a t e d by .IOPNR,
as you a l s o update the FPN.
DWM-00100-06,
REV COO
you may do so as
long
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
7.5
Page 7-5
CLOSING THE FILE AFTER PROCESSING (.ICLOS)
The .ICLOS c a l l t o I S A M performs one o f t h r e e separate functions.
The
standard c a l l i s used t o i n f o r m I S A M t h a t you a r e f i n i s h e d w i t h t h e
file.
I n t h i s mode, I S A M performs t h e necessary housekeeping f u n c t i o n s
and d e a l l o c a t e s any memory used by t h e f i l e i f a user d e a l l o c a t i o n
r o u t i n e has not been provided.
The o t h e r two modes are used t o l o c k
and unlock t h e p r i m a r y index f i l e .
(See the d e f i n i t i o n o f t h e RO
flags, be low.
C a l l i n g Sequence:
R5
You may set t h e f o l l o w i n g f l a g s :
.IS.LOK
Lock
IS-UNL
Unlock
(If
both are set, performs lock;
if both are zero, j u s t closes.)
F i l e p a i r number (FPN)
User memory p o i n t e r
CALL
.ICLOS(Rn)
RO
Parameters :
Returns:
R1
RO
Indicators
-
Completion code
Z i f no e r r o r
The f i l e p a i r number used i n R 1 i s t h a t value r e t u r n e d by .IOPNR.
7.6
LOCATING A FREE DATA RECORD (.IGTFR)
Use t h i s c a l l t o get the r e l a t i v e record number o f the next a v a i l a b l e
data record i n the data f i l e .
The primary index f i Le must already be
Locked when you make t h i s c a l l .
C a l l i n g Sequence:
Parameters:
Returns:
R1
R5
F i l e p a i r number (FPN) o f p r i m a r y index f i l e
User memory p o i n t e r
CALL
.IGTFR (Rn)
RO
R1
R2
Indicators
Completion code
Low-order r e l a t i v e r e c o r d number o f the data
record
High-order r e l a t i v e record number o f t h e
d a t a record
Z i f no e r r o r
The FPN s u p p l i e d i n R 1 must r e f e r t o the p r i m a r y index f i l e associated
w i t h t h e data f i l e from which a f r e e record i s t o be obtained.
DWM-00100-06,
REV COO
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
7.7
Page 7-6
DELETING A DATA RECORD (.IDLFR)
Use t h i s c a l l t o r e t u r n a data record t o the f r e e r e c o r d l i s t .
p r i m a r y index f i l e must already be locked when you make t h i s c a l l .
.IDLFR c a l l unlocks the primary index f i l e a t t h e completion o f
call.
The
The
the
C a l l i n a Seauence:
R1
Parameters:
R5
F i l e p a i r number (FPN) o f p r i m a r y index f i l e
Low-order r e l a t i v e r e c o r d number o f t h e
data record
High-order r e l a t i v e record number o f the
data record
User memory p o i n t e r
CALL
.IDLFR (Rn)
R2
R3
Returns :
RO
Indicators
Completion code
Z i f no e r r o r
The FPN s u p p l i e d i n R 1 must r e f e r t o a p r i m a r y index f i l e .
DWM-00100-06,
REV COO
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
7.8
Page 7-7
READING A DATA RECORD BY RELATIVE RECORD NUMBER (-IRLRD)
Use t h i s c a l l t o read the data record p o i n t e d t o by t h e r e l a t i v e r e c o r d
number.
The primary index f i l e must already be locked when you make
I f t h e E x c l u s i v e f l a g i s not set (i.e.,
INPUT was used, n o t
t h i s call.
INPUTL), t h i s c a l l unlocks the index f i l e .
C a l l i n g Sequence:
Parameters :
R0
R3
R4
R5
You may set the f o l l o w i n g f l a g s :
IS.REX
Read E x c l u s i v e
IS.RWT
Wait f o r record i f i t i s i n
use.
Low-order r e l a t i v e record number o f t h e
data record
High-order r e l a t i v e record number o f the
data record
F i l e p a i r number (FPN)
B u f f e r address
User memory p o i n t e r
CALL
.IRLRD(Rn)
-
-
R1
R2
Returns :
RO
Indicators
Completion code
Z i f no e r r o r
The FPN s u p p l i e d i n R3 must r e f e r t o the p r i m a r y index f i l e
w i t h the data f i l e .
DWM-00100-06,
REV COO
associated
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
Page 7-8
WRITING A DATA RECORD BY RELATIVE RECORD NUMBER (.IRLWT)
Use t h i s c a l l t o w r i t e o r update t h e data r e c o r d p o i n t e d t o by t h e
r e l a t i v e r e c o r d number.
The p r i m a r y index f i l e must a l r e a d y be l o c k e d
I f t h e E x c l u s i v e f l a g i s n o t s e t (an OUTPUT
when you make t h i s c a l l .
has been used i n s t e a d o f an OUTPTL), t h e c a l l u n l o c k s t h e index f i l e .
Ca 1l i n g Sequence:
RO
Parameters:
R3
R4
R5
You may s e t t h e f o l l o w i n g f l a g s :
IS.REX
Lock and w r i t e
1S.RWT
Wait f o r r e c o r d i f i t i s i n
use.
Low-order r e l a t i v e r e c o r d r~umber of t h e
data record
High-order r e l a t i v e r e c o r d number o f t h e
data record
F i l e p a i r number (FPN)
B u f f e r address
User memory p o i n t e r
CALL
.IRLWT(Rn1
-
-
R1
R2
Returns :
DWM-00100-06,
RO
Indicators
REV COO
Completion code
Z i f no e r r o r
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
7.10
Page 7-9
FINDING A RECORD (.IREDR)
Use t h i s c a l l t o use a symbolic key t o f i n d t h e r e l a t i i v e r e c o r d number
I f t h e index f i l e i s a p r i m a r y i n d e x f i l e , t h i s c a l l
o f a data record.
locks it.
C a l l i n g Sequence:
R1
Parameters:
R5
F i l e p a i r number (FPN) o f t h e d e s i r e d index
file
P o i n t e r t o symbolic key
User memory p o i n t e r
CALL
.IREDR (Rn)
R3
Returns :
RO
R1
R2
Indicators
Completion code
Low-order r e l a t i v e r e c o r d number o f data
record
High-order r e l a t i v e r e c o r d number o f data
record
Z i f no e r r o r
The FPN s u p p l i e d i n R 1 may r e f e r t o any open index f i le.
DWM-00100-06,
REV COO
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
7.11
Page 7-10
ADDING A SYMBOLIC KEY (.IWRTR)
Use t h i s c a l l t o add a key e n t r y t o an index f i l e g i v e n a user s u p p l i e d
d a t a r e c o r d number. The p r i m a r y index f i l e must a l r e a d y be l o c k e d when
you make t h i s c a l l .
This c a l l unlocks the primary index f i l e .
C a l l i n g Sequence:
R1
Parameters:
R5
F i l e p a i r number (FPN) o f d e s i r e d i n d e x
file
P o i n t e r t o symbolic key
Low-order r e l a t i v e r e c o r d number of t h e
data record
High-order r e l a t i v e r e c o r d number of t h e
data record
User memory p o i n t e r
CALL
.IWRTR (Rn)
R2
R3
R4
Returns :
RO
Indicators
Completion code
Z i f no e r r o r
The FPN s u p p l i e d i n R 1 may r e f e r t o any open index file.
The r e l a t i v e
r e c o r d number i n R3 and R4 w i 11 u s u a l l y be a r e c o r d n~umber r e t u r n e d by
t h e .IGTFR c a l l .
7.12
DELETING A KEY (.IDELK)
Use t h i s c a l l t o d e l e t e a key from an index f i l e .
f i l e must a l r e a d y be locked when you make t h i s c a l l .
The p r i m a r y i n d e x
C a l l i n g Sequence:
Parameters:
F i l e p a i r number (FPN) o f d e s i r e d index
file
P o i n t e r t o symbolic key
User memory p o i n t e r
CALL
Returns :
Indicators
DWM-00100-06,
REV COO
Completion code
Low-order r e l a t i v e r e c o r d number o f d e l e t e d
key
High-order r e l a t i v e r e c o r d number o f
d e l e t e d key
Z i f no e r r o r
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
Page 7-11
The r e l a t i v e record number i n R1 and R2 r e f e r s t o t h e data record
associated w i t h t h e d e l e t e d key w i t h i n t h e index f i l e r e f e r r e d t o by
t h e supplied FPN. The data record i s not d e l e t e d i n the data f i Le;
do
t h i s by u s i n g t h e .IDLFR c a l l when you are sure t h a t t h e r e are no keys
l e f t i n the index f i l e t h a t r e f e r t o t h a t data record.
7.13
FINDING THE NEXT SEQUENTIAL KEY (.SREDR)
When p r i n t i n g r e p o r t s o r p o s t i n g data, i t i s o f t e n uselful t o be able t o
go through t h e records i n the indexed s e q u e n t i a l f i l e i n ascending key
order.
The .SREDR c a l l makes t h i s possible; i t r e t u r n s t h e r e l a t i v e
r e c o r d number o f t h e record t h a t immediately f o l l o w s the one r e t u r n e d
I t thus makes i t p o s s i b l e t o s t a r t
by t h e l a s t c a l l t o ISAM.
s e q u e n t i a l processing by key anywhere i n the f i l e .
To do so,
use t h e
.IREDR c a l l t o get the f i r s t key you wish t o use. Then c a l l .SREDR t o
get t h e key f o l l o w i n g t h e ' o n e read by .IREDR.
You can get t h e next key
I f .IREDR does not f i n d t h e key
by doing another .SREDR, ad i n f i n i t u m .
specified, t h e f o l l o w i n g .SREDR r e t u r n s t h e record w i t h t h e key c l o s e s t
t o (but g r e a t e r than) t h e one not found.
Thus, t o read t h e f i l e from
This c a l l
t h e very beginning, t r y t o do a .IREDR w i t h a key o f zero.
w i l l almost always f a i l , b u t t h e f o l l o w i n g .SREDR grabs t h e very f i r s t
r e c o r d i n the f i l e .
Ifthe f i l e contains a key o f a l l zero, the i n i t i a l .IREDR w i l l succeed
and t h a t record should be processed as t h e f i r s t record b e f o r e doing
any .SREDRs.
When the f i l e i s i n i t i a l l y opened by .IOPNR, i t i s set up
so t h a t .SREDR g e t s t h e f i r s t key, unless t h e f i r s t key i s a l l zero.
Therefore i t i s almost always p o s s i b l e t o open the f i l e and read i t
sequentially.
Since keys are expected t o be A S C I I , and an a l l - n u l l key
i s n o t v e r y sensible, t h e v a r i o u s u t i l i t i e s assume t h a t t h e f i r s t key
i s not zero.
When the end o f t h e f i l e i s reached by t h e l a s t .SREDR,
t h e end-of-f il e (IS-EOF) completion code i s returned.
T h i s c a l l locks the index f i l e i f i t i s not t h e p r i m a ~ r yindex f i l e .
DWM-00100-06,
REV COO
WRITING AMOS ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
Page 7-12
C a l l i n g Sequence:
R1
R3
Parameters:
Returns :
R5
F i Le p a i r number (FPN) o f d e s i r e d index
Contains 0 i f symbolic key i s not t o be
returned; otherwise, R3 c o n t a i n s a p o i n t e r
t o t h e Location i n memory t h a t t h e r e t u r n e d
symbolic key i s t o be pLaced in.
User memory p o i n t e r
CALL
.SREDR(Rn)
RO
R1
Completion code
Low-order r e l a t i v e r e c o r d number o f data
record
High-order r e l a t i v e record number o f t h e
data record
Z i f no e r r o r
R2
Indicators
NOTE: I f you do not want t h e symbolic key returned, be sure t h a t R3 i s
Remember t h a t i f R3
c l e a r e d t o zero b e f o r e your program c a l l s .SREDR.
i s nonzero, I S A M w i L l r e t u r n t h e symbolic key t o t h e memory Location
s p e c i f i e d by t h e contents o f R3-- i f R3 happens t o c o n t a i n i n v a l i d
data, I S A M may damage important data i n memory.
DWM-00100-06,
REV COO
CHAPTER 8
WRITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
NOTE: T h i s s e c t i o n assumes t h a t you are an experienced assembly
language programmer and t h a t you are f a m i l i a r w i t h t h e Alpha M i c r o
AM-100IL CPU i n s t r u c t i o n set and t h e AMOSIL m o n i t o r c a l l s .
For
i n f o r m a t i o n on these topics,
r e f e r t o the AMOS/L Assembl:y Language
Programmer ' s Manua 1, DSS-10007-00,
t h e AM-- )O/L I n s t r u c t i o n Set,
D S S ~ I0 0 0 6 - 0 0 , = ,
AMOSIL Moni t o r Ca 1ls, DSS-10003-00.
The I S A M program i s implemented as a FETCHable memory module which a l l o w s
t h e assembly language programmer easy access t o t h e f e a t u r e s o f indexed
(NOTE:
FETCH i s an AMOS/L monitor c a l l .
Refer t o the
seauent ia 1 f il e s
AMOS/L Monitor C a l l s f o r i n f o r m a t i o n on the r o u t i n e s w i t h i n t h e o p e r a t i n g
system ( c a l l e d "monitor c a l l s " )
t h a t have been made a v a i l a b l e t o your
assembly language programs.) I t i s through t h e I S A M module t h a t h i g h l e v e l
languages such as AlphaBASIC g a i n access t o indexed s e q u e n t i a l f i l e s .
The
I S A M program i s f u l l y re-entrant, and c o u l d t h e r e f o r e be made r e s i d e n t i n
system memory i f more than one user a t a t i m e i s going t o be u s i n g indexed
sequent ia 1 f il e s
.
.
The I S A M program i t s e l f takes up approximately 4K b y t e s o f memory.
In
a d d i t i o n t o t h i s space, another 1 t o 4K bytes i s r e q u i r e d f o r each indexed
s e q u e n t i a l f i l e t h a t you a r e processing.
T h i s memory space i s u s u a l l y
a l l o c a t e d by t h e I S A M system u s i n g t h e GETMEM m o n i t o r c a l l ; you may,
however, a l l o c a t e your own b u f f e r areas (see S e c t i o n 8.2.2).
8.1
GENERAL CALLING SEQUENCE
The various I S A M subroutines are c a l l e d v i a a d i s p a t c h t a b l e a t t h e
s t a r t of the I S A M program. To make t h i n g s easier, t h e f i l e ISUSYM.M68
d e f i n e s t h e t a b l e o f f s e t s . T h i s f i l e a l s o contains symbols f o r t h e
v a r i o u s r e t u r n codes.
A l l t a b l e o f f s e t s begin w i t h a p e r i o d (e.g.,
.ICLOS, t h e close r o u t i n e ) .
A l l r e t u r n codes have t h e general form
IS.xxx (e.g.,
IS.EOF,
the end-of-fi l e r e t u r n code).
DWM-00100-06,
REV COO
WRITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
NOTE: ISUSYM.M68
program.
is
designed
t o be COPYed by your assembly language
To c a l l the close r o u t i n e (.ICLOS) w i t h the base o f t h e 1SAM.SYS
contained i n r e g i s t e r A4, use the f o l l o w i n g code:
CALL
Page 8-2
module
.ICLOS(A4)
A l l arguments are passed i n r e g i s t e r s .
NOTE: As o f AMOS/L Versions 1.1
and later, t h e contents o f DO a r e s i g n i f i c a n t when making some o f t h e
c a l l s discussed below-- see the c a l l d e s c r i p t i o n s f o r more i n f o r m a t i o n .
For i n f o r m a t i o n on t h e f l a g s you can set i n DO f o r some of the c a l l s
discussed below, see Chapter 9, "Standard I S A M Symbols f o r Assembly
Language Programmers."
A successful r e t u r n
Each c a l l r e t u r n s w i t h a completion code i n DO.
(1S.SUC) i s i n d i c a t e d by a zero i n DO; t h e i n d i c a t o r s ( a l s o known as
c o n d i t i o n codes o r c o n d i t i o n f l a g s ) on r e t u r n r e f l e c t success o r e r r o r
status.
The Z - b i t i s set i f successful (BNE branches on e r r o r ) .
8.2
INITIALIZING THE I S A M SYSTEM (.INIT)
Before your program can access an indexed s e q u e n t i a l f i l e ,
you must
t e l l the I S A M system t h a t you exist; t h i s i s done v i a t h e .INIT c a l l .
The .INIT c a l l a l l o c a t e s space f o r the u s e r ' s impure v a r i a b l e s and does
minor housekeeping chores.
NOTE: Your program c a l l s .INIT o n l y once
regardless o f t h e number o f I S A M f i l e s t h a t are t o be opened.
C a l l i n g Sequence:
Parameters:
A4,
A2
A3
A5
CALL
Returns :
DO
A5
Indicators
User a1l o c a t i o n r o u t i n e address ( o p t i o n a 1)
User d e a l l o c a t i o n r o u t i n e address ( o p t i o n a l )
Used t o pass i n f o r m a t i o n t o user memory
a l l o c a t i o n routines (optional).
.I N I T (An)
Complet ion code
User memory p o i n t e r
Z i f no e r r o r
The user memory p o i n t e r t h a t i s r e t u r n e d i n A5 i s a p o i n t e r t o your
if
impure area.
T h i s p o i n t e r i s needed by a l l o t h e r I S A M calls;
convenient, l e a v e i t i n A5 s i n c e a l l c a l l s look f o r i t there.
DWM-00100-06,
REV COO
URITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
Page 8-3
User Supplied A l l o c a t i o n and D e a l l o c a t i o n Routines
I n many cases, t h e program c a l l i n g t h e I S A M program w i l l do i t s own
To
memory management,
and n o t want I S A M t o use GETMEMs t o do so.
.INIT
c
a
l
l
a
l
l
o
w
s
t
h
e
a l l o w you t o do your own a l l o c a t i o n ,
the
passing o f a l l o c a t i o n and d e a l l o c a t i o n r o u t i n e addresses.
.INIT uses
i t s own r o u t i n e s (which use GETMEMs) i f you pass a zero i n s t e a d o f an
address.
The user a l l o c a t i o n r o u t i n e i s c a l l e d w i t h t h e d e s i r e d module s i z e i n
The .INIT c a l l expects the address o f t h e assigned module t o be
You may n o t modify any o t h e r r e g i s t e r s .
returned i n A l .
Dl.
The user d e a l l o c a t i o n r o u t i n e i s c a l l e d w i t h t h e address o f
module t o be d e l e t e d i n A l .
Do n o t modify any o t h e r r e g i s t e r s .
you pass a zero t o .INIT i n A3, no d e a l l o c a t i o n occurs.
the
If
The c u r r e n t v e r s i o n o f I S A M a l l o w s you t o move any o f t h e modules
ISAM i s
t h a t I S A M requests as w e l l as t h e I S A M program i t s e l f .
immune t o such movement as long as the user memory p o i n t e r ( i n AS)
and t h e FPN ( f i l e p a i r number, see S e c t i o n 8.6.1)
associated w i t h a
g i v e n f i l e are updated t o show any movement.
(The FPN i s u s u a l l y i n
A 1 .)
8.3
FINALIZING I S A M PROCESSING (.IFIN)
When you are through processing indexed s e q u e n t i a l f i l e s , you must c a l l
t h e .IFIN r o u t i n e . T h i s c a l l d e a l l o c a t e s any space used by I S A M i f a
user d e a l l o c a t i o n r o u t i n e has been provided; o t h e r w i s e t h e modules a r e
n o t d e l e t e d u n t i l t h e job EXITS. (EXIT i s an AMOS/L m o n i t o r call.)
C a l l i n g Sequence:
Parameters:
Returns :
A5
User memory p o i n t e r
CALL
.IFIN(An)
DO
Indicators
I S . SUC
Z i f no e r r o r
The .IFIN r o u t i n e cannot f a i l ,
s u c c e s s f u l completion code i n DO.
DUM-00100-06,
REV C01
therefore
it
always
returns
the
WRITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
8.4
Page 8-4
OPENING A FILE FOR PROCESSING (.IOPNR)
You must open an indexed s e q u e n t i a l f i l e v i a t h i s c a l l b e f o r e you can
process t h e f i l e i n any way.
Also use t h i s call1 when opening a
If
secondary index f i l e f o r processing a p r e v i o u s l y opened data f i l e .
you execute t h i s c a l l on a p r i m a r y index f i l e , t h e c a l l a l s o opens t h e
associated data f i l e ; i f you execute t h e c a l l on a secondary index
file,
t h e c a l l opens t h e index f i l e only.
Thus t o process a data f i l e
w i t h a secondary index f i l e , you must execute two .IOPNR c a l l s : once t o
open t h e data f i l e and p r i m a r y index f i l e ,
and once t o open t h e
secondary index f i le.
C a l l i n g Sequence:
Parameters :
A5
You may set t h e f o l l o w i n g f l a g s :
IS.EXC
Open i n E x c l u s i v e mode;
otherwise Counted Update mode i s used.
IS.ERP
P r i n t e r r o r messages b e f o r e returning.
IS.FWT
Wait f o r f i l e i f i t i s i n use.
Pointer t o A S C I I f i l e s p e c s t r i n g describi n g t h e index f i l e t o be opened.
I f the
index f i l e i s a p r i m a r y index, t h e data
f i l e must have t h e same name.
User memory p o i n t e r
CALL
.IOPNR (An)
DO
A2
Returns:
DO
A1
Indicators
-
Completion code
Unique F i l e P a i r Number (FPN)
Z i f no e r r o r
The f i l e p a i r number (FPN) i s a p o i n t e r t o t h e memory module t h a t has
been a l l o c a t e d f o r t h e storage needed by t h i s p a r t i c u l a r indexed
The read, write, and d e l e t e r o u t i n e s use t h e FPN t o
s e q u e n t i a l f i le.
t e l l t h e I S A M program which indexed s e q u e n t i a l f i l e s t o process o f t h e
ones you may have open.
I f you must move t h e module a l l o c a t e d by .IOPNR,
as you a l s o update t h e FPN.
DWM-00100-06,
REV C01
you may do so as long
WRITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
Page 8-5
CLOSING THE FILE AFTER PROCESSING (.ICLOS)
The .ICLOS c a l l t o I S A M performs one o f t h r e e separate f u n c t i o n s .
The
standard c a l l i s used t o i n f o r m I S A V t h a t you a r e f i n i s h e d w i t h t h e
file;
i n t h i s mode, I S A M performs t h e necessary housekeeping f u n c t i o n s
and d e a l l o c a t e s any memory used by t h e f i l e i f a user d e a l l o c a t i o n
r o u t i n e has been provided.
The o t h e r two modes a r e used t o l o c k and
unlock t h e p r i m a r y index f i l e .
C a l l i n g Sequence:
Parameters:
DO
Returns :
A1
A5
You may se the f o l l o w i n g f l a g s :
IS-LOK
Lock
IS-UNL
Unlock
(If
both are set, performs lock;
if both are zero, j u s t closes.)
F i l e p a i r number (FPN)
User memory p o i n t e r
CALL
.ICLOS (An)
DO
Indicators
-
Completion code
Z i f no e r r o r
The f i l e p a i r number used i n A1 i s t h a t value r e t u r n e d by .IOPNR.
LOCATING A FREE DATA RECORD (.IGTFR)
Use t h i s c a l l t o get the r e l a t i v e record number o f t h e n e x t a v a i l a b l e
data record i n the data f i l e .
The primary index f i l e must already be
locked when you make t h i s c a l l .
C a l l i n g Sequence:
Parameters:
Returns :
A1
A5
F i l e p a i r number (FPN) o f p r i m a r y index f i l e
User memory p o i n t e r
CALL
.IGTFR (An)
DO
D1
Indicators
Completion code
R e l a t i v e record number o f t h e data record
Z i f no e r r o r
The FPN s u p p l i e d i n A 1 must r e f e r t o the p r i m a r y index f i l e associated
w i t h t h e data f i l e from which a f r e e record i s t o be obtained.
DWM-00100-06,
REV COO
WRITING AMOS/L ASSEI,IBLY
LANGUAGE
PROGRAIJIS
THAT ACCESSISA]'I
8.7
Page 8-6
.IDLFR)
D E L E T I NAG D A T AR E C O R(D
Use this catl to return a data record to the free record List. The
p r i m a r y i n d e x f i L e m . r s ta L r e a d yb e L o c k e d w h e n y o u m a k e t h i s c a l t .
T h i s c a l [ u n o c k st h e p r i m a r y i n d e x f i L e a t t h e c o m p t e t i o no f t h e c a t [ .
Ca[[ing Sequence:
Parameters:
Returns:
A1
D1
A5
F i [ e p a i r n u m b e r( F P N )o f p r i m a r y i n d e x f i L e
R e t a t i v e r e c o r d n u m b e ro f the data record
U s e r m e m o r yp o i n t e r
CALL
(An)
. IDLFR
DO
Indi cators
Completion code
Z if no error
T h e F P Ns u p p l i e d i n A 1 m u s t r e f e r t o a p r i m a r y i n d e x f i [ e .
8.8
.IRLRD)
R E A D I NA
G D A T AR E C O RBDY R E L A T I V R
E E C O RNDU I ' I B E(R
Use this caL[ to read the data record pointed to by the relative record
number.
T h e p r i m a r y i n d e x f i L e m u s t a l r e a d y b e L o c k e dw h e n y o u m a k e
this catt. If the Exc[usive ftag is not set (that is, an INPUT hras
u s e d i n s t e a d o f a n I N P U T L ) ,t h e c a t l u n l o c k s t h e p r i m a r y i n d e x f i [ e .
Parameters:
DO
Returns:
D1
A3
A4
A5
You may set the fottouing ftags:
I S . R E X- R e a dE x c l u s i v e
I S . R b , T- b l a i t f o r r e c o r d i f i t i s l n u s e .
R e l a t i v e r e c o r d n u m b e ro f t h e d a t a r e c o r d
F i t e p a i r n u m b e r( F P N )
Buffer address
U s e r m e m o r yp o i n t e r
CALL
(An)
. IRLRD
DO
Indicators
C o m p t e t i o nc o d e
Z if no error
T h e F P N s u p p L i e di n A 3 m u s t r e f e r t o t h e p r i m a r y i n d e x f i [ e
with the data fi Le.
Dl'rM-00100-06,REVC00t
associated
WRITINGAltlOS/LASSEIIIBLY
LANGUAGE
PROGRAHS
THAT ACCESSISA]{
8.9
Page 8-7
I . , R I T I N GA D A T AR E C O R B
DY R E L A T I V ER E C O R N
D U I ' I B E (R. I R L } ' T )
Use this catl to write or updatethe data record pointed to by the
r e L a t i v e r e c o r d n u m b e r . T h e p r i m a r y i n d e x f i t e n r u s ta L r e a d yb e t o c k e d
w h e ny o u m a k et h i s c a t t . I f t h e E x c l u s i v e f L a g i s n o t s e t ( a n O U T P U T
w a s d o n e i n s t e a d o f a n O U T P T L )t,h e c a L L u n L o c k st h e i n d e x .
Catting Sequence:
Parameters:
D0
Returns:
.*,/
D1
A3
A4
A5
Youmayset the fotLowingflags:
I S . R E X- L o c k a n d w r i t e
I S . R h , T- t r J a i tf o r r e c o r d i f i t i s i n u s e .
R e l a t i v e r e c o r d n u m b e ro f t h e d a t a r e c o r d
F i l . e p a i r n u m b e n( F P N )
Buffer address
U s e r m e m o r yp o i n t e r
CALL
.IRLUT(An)
D0
Indicators
CompLetion
code
Z if no error
.IREDR)
8.10 FINDING
A R E C O R(D
U s e t h i s c a L L t o u s e a s y m b o L i ck e y t o f i n d t h e r e t a t i v e r e c o r d n u m b e r
of a daia record. If the index fiLe is a primaryindex fite, this caLL
Iocks it.
C a L L i n gS e q u e n c e :
Parameters:
Returns:
A3
A5
F i t e p a i r n u m b e r( F P N )o f t h e d e s j r e d j n d e x
fi Le
Pointer to symbotic key
U s e r m e m o r yp o i n t e r
CALL
.IREDR(An)
A1
D0
D1
Indicators
C o m p t e t i o nc o d e
R e L a t i v e r e c o r d n u m b e ro f d a t a r e c o r d
Z if no error
T h e F P Ns u p p t i e d i n A 1 m a y r e f e r t o a n y o p e n i n d e x f i L e .
DWl'l-00100-06,
. REVC0O
WRITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
8.11
Page 8-8
ADDING A SYMBOLIC KEY (.IWRTR)
Use t h i s c a l l t o add a key e n t r y t o an index f i l e g i v e n a user supplied
data record number. The primary index f i l e must already be locked when
you make t h i s c a l l .
This c a l l unlocks t h e p r i m a r y index f i l e when i t
i s done.
C a l l i n g Sequence:
A1
Parameters:
A2
03
A5
F i l e p a i r number (FPN) o f d e s i r e d index
file
P o i n t e r t o symbolic key
R e l a t i v e record number o f t h e data record
User memory p o i n t e r
CALL
.IWRTR (An)
DO
Indicators
Returns:
Completion code
Z i f no e r r o r
The r e l a t i v e
The FPN s u p p l i e d i n A 1 may r e f e r t o any open index f i l e .
r e c o r d number i n D w i l l u s u a l l y be a record number returned by t h e
.IGTFR c a l l .
8.12
DELETING A KEY ( .IDELK)
Use t h i s c a l l t o d e l e t e a key from an index f i l e .
The
f il e must already be locked when you make t h i s c a l l .
primary
index
C a l l i n g Sequence:
A1
Parameters:
A5
F i l e p a i r number (FPN) o f d e s i r e d index
file
P o i n t e r t o symbolic key
User memory p o i n t e r
CALL
.IDELKcAn)
A3
Returns:
DO
D1
Indicators
Completion code
R e l a t i v e record number o f d e l e t e d key
Z i f no e r r o r
The r e l a t i v e record number i n D l r e f e r s t o t h e data record associated
w i t h t h e deleted key w i t h i n t h e index f i l e r e f e r r e d t:o by t h e s u p p l i e d
FPN.
The data record i s not d e l e t e d i n t h e data f i l e ; do t h i s by using
t h e .IDLFR c a l l when you are sure t h a t t h e r e are no keys l e f t i n t h e
index f i l e t h a t r e f e r t o t h a t data record.
DWM-00100-06,
REV C01
WRITING AMOS/L ASSEMBLY LANGUAGE PROGRAMS THAT ACCESS I S A M
8.13
Page 8-9
FINDING THE NEXT SEQUENTIAL KEY (.SREDR)
When p r i n t i n g r e p o r t s o r p o s t i n g data, i t i s o f t e n u s e f u l t o be able t o
go through t h e records i n the indexed s e q u e n t i a l f i l e i n ascending key
order.
The .SREDR c a l l makes t h i s possible; i t r e t u r n s t h e r e l a t i v e
r e c o r d number o f t h e record t h a t immediately f o l l o w s t h e one r e t u r n e d
I t thus makes i t p o s s i b l e t o s t a r t
by the l a s t c a l l t o ISAM.
s e q u e n t i a l processing by key anywhere i n the f i l e .
To do so, use the
.IREDR c a l l t o get the f i r s t key you wish t o use. Then c a l l .SREDR t o
You can get the next key
get the key f o l l o w i n g t h e one read by .IREDR.
by doing another .SREDR, ad i n f i n i t u m .
I f .IREDR does not f i n d the key
specified, t h e f o l l o w i n g .SREDR r e t u r n s the record w i t h t h e key c l o s e s t
t o (but g r e a t e r than) t h e one not found.
Thus, t o read the f i l e from
t h e very beginning, t r y t o do a .IREDR w i t h a key o f zero.
This c a l l
w i l l almost always f a i l , b u t t h e f o l l o w i n g .SREDR grabs t h e very f i r s t
record i n the f i l e .
Ifthe f i l e contains a key of a l l zero, t h e i n i t i a l .ZREDR w i l l succeed
and t h a t record should be processed as the f i r s t record b e f o r e doing
any ,SREDRs.
When the f i l e i s i n i t i a l l y opened by .IOPNR, i t i s set up
so t h a t .SREDR g e t s t h e f i r s t key, unless t h e f i r s t key i s a l l zero.
Therefore i t i s almost always p o s s i b l e t o open the f i l e and read i t
sequentially.
Since keys are expected t o be A S C I I , and an a l l - n u l l key
i s n o t v e r y sensible, t h e v a r i o u s u t i l i t i e s assume t h a t the f i r s t key
i s not zero.
When t h e end o f t h e f i l e i s reached by t h e l a s t .SREDR,
t h e end-of-f il e (1S.EOF) completion code i s returned.
I f t h e index f i l e i s the p r i m a r y index f i l e ,
t h i s c a l l locks it.
C a l l i n g Sequence:
AI
A3
Parameters:
Returns :
A5
F i l e p a i r number (FPN) o f d e s i r e d index
Contains 0 i f symbolic key i s not t o be
returned; otherwise, A3 c o n t a i n s a p o i n t e r
t o t h e l o c a t i o n i n memory t h a t t h e r e t u r n e d
symbolic key i s t o be placed in.
User memory p o i n t e r
CALL
.SREDR (An)
DO
Dl
Indicators
Completion code
R e l a t i v e record number o f data record
Z i f no e r r o r
NOTE: I f you do n o t want t h e symbolic key returned, be sure t h a t A3 i s
Remember t h a t i f A3
c l e a r e d t o zero b e f o r e your program c a l l s .SREDR.
i s nonzero,
I S A M w i l l r e t u r n the symbolic key t o the memory l o c a t i o n
s p e c i f i e d by t h e contents o f A3-- i f A3 happens t o c o n t a i n i n v a l i d
data, I S A M may damage important data i n memory.
DWM-00100-06,
REV COO
CHAPTER 9
STANDARD I S A M SYMBOLS FOR ASSEMBLY LANGUAGE PROGRAMMERS
We have p r o v i d e d a symbols f i l e (1SUSYM.MAC on AMOS systems; ISUSYM.M68 on
AMOS/L systems) t o make l i f e e a s i e r f o r t h e assembly language programmer.
T h i s chapter describes t h e contents o f t h a t f i l e .
We have broken t h i s
i n f o r m a t i o n i n t o t h r e e sections: 1. those o f f s e t s used when i n v o k i n g ISAM;
2. t h e f l a g s you can set when making t h e calls; and, 3. t h e completion codes
r e t u r n e d by t h e v a r i o u s I S A M f u n c t i o n s .
9.1
CALLING SYMBOLS
The f o l l o w i n g symbols d e f i n e e n t r y o f f s e t s i n t h e TSAM package.
Sections 7.1 and 8.1 o f t h i s manual f o r more i n f o r m a t i o n .
.I N I T
.IFIN
.IOPNR
.ICLOS
..IGTFR
IDLFR
.IRLRD
.IRLWT
.IREDR
.IWRTR
..SREDR
IDELK
DWM-00100-06,
Call
Call
Cal L
Call
Call
See
the i n i t i a l i z a t i o n r o u t i n e
the f i n a l i z a t i o n routine
t h e f i l e open r o u t i n e
the f i l e close r o u t i n e
the get f r e e record r o u t i n e .
C a l l the data record d e l e t i o n r o u t i n e .
C a l l the read data record v i a r e l a t i v e r e c o r d
number r o u t i n e .
C a l l t h e w r i t e data record v i a r e l a t i v e record
number r o u t i n e .
C a l l the read r e t u r n i n g r e l a t i v e r e c o r d number
routine.
C a l l the w r i t e u s i n g r e l a t i v e record number routine.
C a l l the key d e l e t i o n r o u t i n e .
C a l l the read s e q u e n t i a l r e l a t i v e record number r o u t i n e .
REV COO
STANDARD I S A M SYMBOLS FOR ASSEMBLY LANGUAGE PROGRAMMERS
9.2
Page 9-2
CALLING FLAGS
The f o l l o w i n g symbols are the f l a g s you can set i n RO (on AMOS systems)
o r DO (on AMOSIL systems) when making some o f the I S A M c a l l s discussed
i n Chapters 7 and 8.
Always use these symbols r a t h e r than t h e i r values
o r ISUSYM.M68
s i n c e those values could change i n the
i n 1SUSYM.MAC
future.
I S . EXC
9.3
IS.ERP
(10 o c t a l )
(1000octaL~
IS.LOK
IS.UNL
IS.REX
(2000 o c t a l )
(4000 o c t a l )
(10000 o c t a l )
IS.RWT
1S.FWT
(40000 o c t a l )
(100000 o c t a l )
Open D i r e c t o r y f o r E x c l u s i v e access.
P r i n t any e r r o r messages ( o n l y f o r f i l e
open c a l l s)
Lock index f i l e ( o n l y f o r f i l e close c a l l s ) .
Unlock index f i l e ( o n l y f o r f i l e close c a l l s ) .
Read record E x c l u s i v e l y ( f o r read o r w r i t e
operations).
Wait f o r record i f i t i s i n use.
Wait f o r f i l e i f i t i s i n use.
.
COMPLETION CODE SYMBOLS
The f o l l o w i n g symbols name t h e completion codes r e t u r n e d i n RO (on AMOS
systems) o r DO (on AMOSIL systems) upon completion o f an I S A M c a l l .
Always use these symbols r a t h e r than t h e i r values i n 1SUSYM.MAC o r
ISUSYM.M68,
since those values could change i n the f u t u r e .
The successful completion code ( w i l l always be zero).
Parameters s u p p l i e d do not match th~ose i n t h e
D i r e c t o r y Rock.
Record not found.
Attempt t o add d u p l i c a t e key.
Index f i l e l i n k s t r u c t u r e i s smashed.
Index f i l e i s f u l l .
Data f i l e i s f u l l .
End o f f i l e encountered on s e q u e n t i a l read.
I l l e g a l o p e r a t i o n sequence
I S . SUC
I S . DNR
IS.RNF
I S . DPK
I S . LSS
I S . XFL
1S.AFL
I S . EOF
I S . ILP
which i s
An e r r o r code o f 2 (handled by AlphaBASIC as a SYSTEM ERROR;
why t h i s code was chosen) means e i t h e r t h a t something i n I S A M o r t h e
I S A M f i l e s t r u c t u r e i s i n e r r o r (as i n a bug) o r t h a t you used an
obsolete I S A M c a l l .
DWM-00100-06,
REV COO
CHAPTER 10
USING I S A M FROM WITHIN ALPHABASIC
The f o l l o w i n g pages are a b r i e f summary o f t h e AlphaBASIC I S A M commands t h a t
your AlphaBASIC programs can use t o access I S A M indexed s e q u e n t i a l f i l e s .
(Remember t h a t an indexed s e q u e n t i a l f i l e i s made up o f both an I S A M data
f i l e and a t l e a s t one I S A M index f i l e , a l l o f which a r e random f i l e s . ) For
more i n f o r m a t i o n on AlphaBASIC i t s e l f ,
r e f e r t o t h e AlphaBASIC User's
Manual,
DWM-00100-01.
The f o l l o w i n g discussions assume t h a t you a r e
a l r e a d y fami l i a r u i t h opening and c l o s i n g random f i l e s ,
and t h a t you
understand t h e AlphaBASIC READ and WRITE statements.
For more i n f o r m a t i o n
on u s i n g f i l e s , r e f e r t o the AlphaBASIC User's Manual.
For i n f o r m a t i o n on the LOKSER F i l e Locking S e r v i c e System, see Chapter 6 o f
t h i s manual-- t h a t chapter contains examples o f t h e proper procedures t o use
when l o c k i n g ISAN f i l e s .
You must use t h e I S A M u t i l i t y program ISMBLD t o c r e a t e an indexed s e q u e n t i a l
f i l e before your AlphaBASIC program can access i t . Although no f e a t u r e s
e x i s t w i t h i n AlphaBASIC t o c r e a t e an indexed s e q u e n t i a l f i l e ,
your
AlphaBASIC program can create and execute a command f i l e t h a t invokes ISMBLD
A l l data f i l e s must have an extension o f
w i t h a l i s t o f f i l e parameters.
. I D A and a l l index f i l e s must have t h e . I D X extension.
has been
Before you r u n your AlphaBASIC program, make sure t h a t 1SAM.SYS
loaded i n t o memory i f the System Operator has n o t arranged t o have I S A M - S Y S
r e s i d e n t i n system memory.
10.1
OPENING AN INDEXED SEQUENTIAL FILE
To open an I S A M indexed s e q u e n t i a l index f i l e , use t h e AlphaBASIC OPEN
command. Your program must i n c l u d e an OPEN statement t h a t assigns a
f i l e channel t o t h e indexed s e q u e n t i a l f i l e b e f o r e t h e program makes
any o t h e r references t o t h a t f i l e .
T h i s statement takes t h e same form as t h e OPEN statement f o r o r d i n a r y
random
files
except t h a t you must s p e c i f y e i t h e r INDEXED o r
INDEXEDIEXCLUSIVE mode r a t h e r than RANDOM mode. (Remember t h a t your
DWM-001 00-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-2
I S A V f i l e s a r e random data f i l e s .
For i n f o r m a t i o n on u s i n g random
f i l e s , see Chapter 15 o f t h e AlphaBASIC User's Marlual.)
The OPEN
statement takes t h i s form:
OPEN #file-channel,filespec,mode,record-size,relative-record-number€,wait~
1.
-
# f i le-channel
s p e c i f i e s t h e f i l e channel you want t o assign
t o t h e indexed s e q u e n t i a l f i l e .
Any numeric expression t h a t
evaluates t o an i n t e g e r from 0-65535
(0 i s t h e
user
terminal).
T h i s i s t h e number you reference when u s i n g t h e
ISAM, READ, READL, WRITE, and WRITEL statements.
-
The f i l e s p e c i s any s t r i n g expression t h a t
Filespec
( I t may
evaluates t o a l e g a l AMOS f i l e s p e c i f i c a t i o n .
It
o p t i o n a l l y i n c l u d e account and device s p e c i f i c a t i o n s . )
s p e c i f i e s the name o f t h e indexed s e q u e n t i a l f i l e you created
u s i n g ISMBLD ( t h a t is,
t h e data f i l e / p r i m a r y index f i l e
combination you b u i l t ) o r s p e c i f i e s t h e name o f a secondary
index f i l e created w i t h ISMBLD.
( I f t h e OPEN statement
r e f e r s t o a secondary index f i l e , you must have p r e v i o u s l y
opened t h e corresponding data f i l e / p r i m a r y index f i l e on
another f il e channe 1.1
Note t h a t the p r i m a r y index f i l e always has t h e same name as
t h e data f i l e , b u t has a . I D X extension; t h e data f i l e has a
. I D A extension.
-
3.
Mode
I f you wish I S A M t o access t h e indexed s e q u e n t i a l f i l e
i n Counted Update mode, use the INDEXED keyword as t h e f i l e
i f you want I S A M t o access the f i l e i n E x c l u s i v e Open
mode;
mode, use the keyword INDEXED'EXCLUSIVE.
(For i n f o r m a t i o n on
Counted Update mode and on E x c l u s i v e Open mode,
see S e c t i o n
1.3,
"ISAM
Access Modes.")
I f t h e LOKSER F i l e L o c k i n g
Service System i s i n s t a l l e d on your system, opening an I S A M
f i l e i n INDEXED mode w i 11 open i t f o r Shared use; opening i t
i n INDEXED'EXCLUSIVE mode w i l l open i t f o r E x c l u s i v e use.
4.
Record-size
An expression t h a t s p e c i f i e s t h e l o g i c a l record
s i z e f o r read/wri t e operations.
5.
A f l o a t i n g point variable that w i l l
R e l a t i v e record number
h o l d the r e l a t i v e r e c o r d number r e t u r n e d by an I S A M f u n c t i o n .
(See S e c t i o n 10.2, "The I S A M Statement.")
6.
€,wait3
You may use
i n s t a l l e d on your system.
WAIT'RECORD o r WAIT'FILE.
-
-
-
t h i s o p t i o n a l clause i f LOKSER i s
The clause may t a k e two forms:
I f you do not use t h e €,wait)
clause, and LOKSER i s i n s t a l l e d
on your system, i f you t r y t o access a record i n a f i l e o r i f
you t r y t o access a f i l e and the resource you need i s already
locked, LOKSER w i 11 prevent you from accessing i t .
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-3
What happens then depends on your program-- i f your program
has e r r o r t r a p p i n g enabled, t h e a c t i o n s s p e c i f i e d by your
e r r o r h a n d l i n g r o u t i n e w i 11 be performed; i f your program
does not have e r r o r t r a p p i n g enabled, your program w i l l be
i n t e r r u p t e d and t h e user o f your program w i l l r e t u r n t o
monitor command l e v e l . (For i n f o r m a t i o n on d e a l i n g w i t h t h e
u s u a l system e r r o r s (egg., " ? F i l e not found" o r "?Disk n o t
mountedWj r e f e r t o t h e - A L ~ ~ ~ B A S I C User's
Manual,
in
p a r t i c u l a r Chapter 17,
which g i v e s i n f o r m a t i o n on e r r o r
trapping.)
Ifyou s p e c i f y WAIT'FILE, LOKSER w i l l not r e p o r t an e r r o r i f
t h e program t r i e s t o access a f i l e t h a t i s already locked,
b u t w i 11 i n s t e a d p u t the job u s i n g the program t o sleep u n t i 1
the f i l e i s available.
Ifyou s p e c i f y WAIT'RECORD, LOKSER w i 11 not r e p o r t an e r r o r
i f t h e program t r i e s t o access a record t h a t i s already
locked, b u t w i 11 i n s t e a d put the job u s i n g t h e program t o
s l e e p u n t i 1 t h e record i s a v a i l a b l e .
For an example o f the use o f the OPEN statement,
AlphaBASIC program a t the end o f t h i s chapter.
sample OPEN statements:
220
230
OPEN #100,
OPEN #200,
100
OPEN #300, "MAIL",
INDEXED'EXCLUSIVE,
REL'KEY, WAIT'FILE
r e f e r t o the sample
Below a r e s e v e r a l
"LABELS",
INDEXED, RECSIZE, RELKEYl
"HASH",
INDEXED, RECSIZE, RELKEYI
REC'SIZ,
&
The f i r s t two program l i n e s above assume t h a t t h e r e e x i s t s a data f i l e
L i n e 220
named LABELS-IDA and a p r i m a r y index f i l e named LABIELS.IDX.
opens t h a t indexed s e q u e n t i a l f i l e g L i n e 230 opens a secondary index
f i l e associated w i t h LABELS-IDA. Note t h a t RECSIZE and RELKEYI a r e
i d e n t i c a l f o r both OPEN statements;
t h i s i s because both OPEN
statements r e f e r t o the SAME data f i l e , LABELS-IDA.
The RECSIZE and
RELKEYI a r e used by subsequent READ and WRITE commands t o access t h e
data f i l e .
10.2
THE I S A M STATEMENT
The purpose of t h e I S A M statement i s t o a l l o w you t o use the I S A M
program from w i t h i n your AlphaBASIC program to: 1. f i n d a r e c o r d i n
t h e data f i l e by symbolic key ( r e t u r n i n g the r e l a t i v e r e c o r d number i n
t h e v a r i a b l e s p e c i f i e d by t h e indexed s e q u e n t i a l f i l e OPEN statement);
2. f i n d t h e next data record (by t h e order i n which t h e symbolic keys
occur i n the index f i l e ) ; 3. add a symbolic key t o aln index f i l e ;
4.
d e l e t e a symbolic key from an index f i l e ; 5. l o c a t e next f r e e data
r e c o r d i n data f i l e ( r e t u r n i n g r e l a t i v e record number i n t h e v a r i a b l e
s p e c i f i e d by t h e a p p r o p r i a t e OPEN statement); 6. d e l e t e a record from
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-4
a data f i l e , and r e t u r n t h a t record t o the f r e e l i s t ; and, 7. f i n d t h e
next data record (by t h e order i n which the symbolic keys occur i n t h e
index f i l e ) and r e t u r n t h e symbolic key.
The I S A M statement f o l l o w s t h i s form:
I S A M #file-channel,
code,
symbolic-key
-
1.
# f i le-channel
S p e c i f i e s t h e f i l e channel assigned by an
OPEN statement t o e i t h e r the data f i l e / p r i m a r y index f i l e o r
t h e secondary index f i l e (depending on which set of symbolic
keys you want t o access).
2.
Code
A numeric value t h a t s e l e c t s one o f t h e f u n c t i o n s
mentioned above. May be any l e g a l numeric expression which
i s resolved a t runtime.
3.
Symbolic-key
S p e c i f i e s t h e symbolic key t o be used i n
l o c a t i n g a data record. You must always s p e c i f y a symbolic
key even i f a f u n c t i o n does not r e q u i r e t h e use o f one.
(This s i m p l i f i e s syntax checking.) I f you wish, you may use a
dummy s t r i n g v a r i a b l e i n such cases.
-
-
I S A M Statement Codes
The I S A M statement can perform seven d i f f e r e n t functions.
You may
s e l e c t one o f these f u n c t i o n s by s u p p l y i n g the a p p r o p r i a t e code
number (see below) t o t h e I S A M statement.
An e r r o r w i l l r e s u l t i f
you do not supply a v a l i d code number.
Some o f the f u n c t i o n s below r e q u i r e a r e l a t i v e r e c o r d number as
input; o t h e r s r e t u r n a r e l a t i v e record number t o be used when your
READ and WRITE statements access t h e data f i l e .
I n e i t h e r case, t h e
I S A M f u n c t i o n s pass the r e l a t i v e record number i n the v a r i a b l e
s p e c i f i e d i n t h e OPEN statement f o r t h e data f i l e / p r i m a r y index
file.
READ and WRITE statements a l s o use t h a t v a r i a b l e f o r l o c a t i n g
t h e data f i l e record t h a t they are going t o access.
Remember t h a t
file.
t h e I S A M statement does not d i r e c t l y access t h e data
i t g i v e s you t h e i n f o r m a t i o n you need t o access the data
Instead,
f i l e y o u r s e l f u s i n g the r e l a t i v e record number r e t u r n e d by ISAM.
-
CODE 1 - Searches t h e index f i l e s e l e c t e d by # f i l e - c h a n n e l f o r
I f i t f i n d s a match,
t h e key t h a t matches t h e symbolic-key.
i t r e t u r n s t h e r e l a t i v e record number o f t h e data f i l e record
c o n t a i n i n g t h a t key. I f i t does not f i n d a match, i t r e t u r n s
an e r r o r code 33 i n ERF(X1, where X i s t h e f i l e channel number
o f t h e f i l e you want t o check.
(See S e c t i o n 10.5,
"Error
Processing").
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-5
-
Accesses t h e index f i l e s e l e c t e d by # f i l e - c h a n n e l and
CODE 2
f i n d s t h e next symbolic key.
Returns t h e r e l a t i v e r e c o r d
number o f t h e data f i l e record associated w i t h t h a t symbolic
If
key i n p r e p a r a t i o n f o r a READ o r a WRITE t o t h e data f i l e .
t h i s i s t h e f i r s t access t o the f i l e a f t e r t h e OPEN statement,
i t f i n d s the f i r s t symbolic key i n the index f i l e .
I f this
f u n c t i o n f o l l o w s a p r e v i o u s code 1 statement, t h e f u n c t i o n
f i n d s t h e next symbolic key a f t e r t h e code 1 symbolic key.
If
t h e r e are no more keys i n the index f i l e , t h e f u n c t i o n r e t u r n s
an e n d - o f - i n d e x - f i l e e r r o r (38): make no f u r t h e r accesses t o
t h e data f i l e u n t i 1 you make another I S A M c a l l t h a t r e t u r n s a
v a l i d r e l a t i v e record number.
-
Adds the s p e c i f i e d symbolic key t o t h e index f i l e
CODE 3
Also adds t h e r e l a t i v e record
s e l e c t e d by # f i le-channel.
number s p e c i f i e d by t h e v a r i a b l e i n t h e OPEN statement.
You
w i l l u s u a l l y s e t t h i s r e l a t i v e record number j u s t p r i o r t o the
code 3 c a l l by u s i n g a code 5 I S A M statement.
( A code 5 c a l l
r e t u r n s t h e r e l a t i v e record number o f t h e next f r e e data
record.)
-
CODE 4
Delete the s p e c i f i e d symbolic key from t h e index f i l e
selected
by
# f i le-channel.
This f u n c t i o n returns the
corresponding r e l a t i v e record number so t h a t you can use a
code 6 I S A M statement t o d e l e t e the data record and r e t u r n i t
t o the free l i s t .
I f t h e f u n c t i o n cannot f i n d t h e symbolic
key i n t h e index f i le, i t r e t u r n s a "?Record n o t found" e r r o r
(33).
-
CODE 5
Finds t h e next a v a i l a b l e data r e c o r d on t h e f r e e
list.
(The f r e e l i s t i s a l i n k e d l i s t t h a t keeps t r a c k o f a l l
a v a i l a b l e records i n t h e data f i l e .
ISMBLD i n i t i a l l y b u i l d s
t h e f r e e l i s t . ) Returns the r e l a t i v e r e c o r d number of t h a t
r e c o r d so t h a t you can use a code 3 I S A M statement t o add a
symbolic k e y / r e l a t i v e r e c o r d number p a i r t o t h e index f i l e .
I f no more data records a r e f r e e i n t h e data f i l e , t h e
f u n c t i o n r e t u r n s a "?Data f i l e f u l l " e r r o r .
A code 5 I S A M
statement does not modify t h e index f i l e ; i t simply l o c a t e s
t h e next f r e e record i n the data f i l e .
The f u n c t i o n ignores
t h e symbolic key i n the I S A M statement. The # f i l e - c h a n n e l i n
t h e code 5 I S A M statement must be t h e f i l e channel assigned t o
t h e p r i m a r y index f i l e .
-
Returns t o the free l i s t the data record s p e c i f i e d by
CODE 6
t h e r e l a t i v e record number i n the OPEN statement.
Does n o t
modify t h e index f i l e .
The # f i l e - c h a n n e l i n the code 6 I S A M
statement must be t h e f i l e channel assigned t o t h e p r i m a r y
index f i l e .
A code 6 c a l l i g n o r e s the symbolic key i n the
I S A M statement.
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-6
-
CODE 7
Accesses t h e index f i l e s e l e c t e d by # f i l e - c h a n n e l and
f i n d s t h e next symbolic key.
Returns t h e r e l a t i v e r e c o r d
number o f t h e data f i l e record associated w i t h t h a t symbolic
key i n p r e p a r a t i o n f o r a READ o r a WRITE t o t h e data f i l e .
If
t h i s i s t h e f i r s t access t o the f i l e a f t e r t h e OPEN statement,
i t f i n d s t h e f i r s t symbolic key i n the index f i l e .
I f this
f u n c t i o n f o l l o w s a p r e v i o u s code 1 statement, t h e f u n c t i o n
f i n d s t h e next symbolic key a f t e r t h e code 1 symbolic key. I f
t h e r e are no more keys i n the index f i l e , t h e f u n c t i o n r e t u r n s
an end-of-index-file
e r r o r (38): make no f u r t h e r accesses t o
t h e data f i l e u n t i 1 you make another I S A M c a l l t h a t r e t u r n s a
v a l i d r e l a t i v e record number.
NOTE: T h i s code performs e x a c t l y t h e same f u n c t i o n as code 2
above,
except t h a t i t r e t u r n s the symbolic key as w e l l as the
r e l a t i v e record number.
I t i s v e r y important t h a t the symbolic key v a r i a b l e t h a t
appears i n your code 7 I S A M statement be the same s i z e as o r
l a r g e r than t h e key defined i n the I S A M index f i l e .
I f the
v a r i a b l e i s smaller than the key, data f o l l o w i n g the symbolic
key i n memory w i 11 be overwritten,
damaging your running
program.
10.3
READING AND WRITING DATA I N AN I S A M DATA FILE
I S A M statements do not access data records, b u t i n s t e a d r e t u r n t h e i r
r e l a t i v e record numbers. To a c t u a l l y read o r w r i t e data records,
you
must use the AlphaBASIC READ, READL, WRITE, and WRITEL commands. When
you read o r w r i t e data i n a s p e c i f i c I S A M d a t a f i l e , AlphaBASIC
s e l e c t s t h e record t o be accessed by r e f e r r i n g t o the r e l a t i v e r e c o r d
number v a r i a b l e i n the OPEN statement f o r t h a t f i l e .
READ # f i le-channel, v a r i a b l e l , variable2,.
READL #file-channel, v a r i a b l e l , variable2,
WRITE #file-channel, v a r i a b l e l , variable2,
WRITEL #file-channel, v a r i a b l e l , variable2,
.. v a r i a b l e N
...
... vv aa rr ii aa bb ll ee NN
... v a r i a b l e N
The # f i l e - c h a n n e l i n the READ, READL, WRITE, o r WRITEL statements MUST
be the f i l e channel t h a t appears i n the OPEN statement f o r the p r i m a r y
index f i l e you want t o access.
The r e l a t i v e record number v a r i a b l e i n
t h e OPEN statement must c o n t a i n a v a l i d r e l a t i v e r e c o r d number o r an
e r r o r w i 11 r e s u l t .
READL and WRITEL o n l y l o c k t h e record i f LOKSER i s i n s t a l l e d on your
system;
on a non-LOKSER system, they perform t h e same a c t i o n s as READ
and WRITE.
However, even i f your system does n o t use LOKSER,
we
recommend t h a t you use READL and WRITEL, s i n c e t h i s w i l l promote
program s t a n d a r d i z a t i o n and w i l l make i t simple f o r you t o t r a n s f e r
your programs t o a LOKSER system a t a l a t e r date.
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-7
READL l o c k s the c u r r e n t record u n t i l you use the UNLOKR statement (see
S e c t i o n 10.5, below) o r u n t i l you use a WRITE statement t o output the
record.
WRITEL l o c k s t h e c u r r e n t
record.
10.4
record
unti1
it
finishes
outputting
the
CLOSING FILES
To ensure t h a t I S A M has r e w r i t t e n a l l data records t o the data f i l e
it i s
and t h a t i t has p r o p e r l y updated a l l l i n k s i n the index f i l e ,
VERY important t h a t you c l o s e a l l index f i l e s ( p r i m a r y and secondary)
v i a the normal CLOSE statement.
F a i l i n g t o close t h e f i l e when you
a r e through w i t h i t may d e s t r o y t h e l i n k i n g s t r u c t u r e o f the indexed
sequential f i l e .
The CLOSE statement takes the form:
CLOSE # f i l e - c h a n n e l
where # f i l e - c h a n n e l i s t h e f i l e channel assigned t o the f i l e you
t o close.
For example:
want
CLOSE #200
where f il e channel #200 was assigned t o an indexed sequenti a 1 f il e by
a p r e v i o u s OPEN statement.
Remember t o c l o s e b o t h primary and
secondary index f i l e s .
NOTE: The order i n which you close the I S A M
f i l e s makes no difference; however, remember t h a t you cannot access a
secondary index f i l e i f you have already closed t h e primary index
f i l e l d a t a f i le.
LOCKING AND UNLOCKING STATEMENTS
I f LOKSER i s i n s t a l l e d on your system, t h e OPEN statement t h a t opens
an I S A M f i l e a u t o m a t i c a l l y l o c k s the I S A M f i l e f o r Shared o r E x c l u s i v e
use (depending on t h e type o f f i l e mode you s p e c i f y ) .
This section
discusses the v a r i o u s o p t i o n s open t o you i f you wa~nt t o e x p l i c i t l y
l o c k and unlock f i l e s and records.
When a c t u a l l y accessing the data i n a f i l e opened f o r Shared use, you
A
can lock t h e data records u s i n g t h e READL o r WRITEL statements.
WRITE o p e r a t i o n a u t o m a t i c a l l y unlocks the record locked by t h e READL
statement.
The WRITEL statement unlocks t h e record i t i s o u t p u t t i n g
when i t i s f i n i s h e d .
You can e x p l i c i t l y
statement:
lock
LOCK #File-channel
DWM-00100-06,
REV COO
the
primary
index f i l e by u s i n g t h e LOCK
USING I S A M FROM WITHIN ALPHABASIC
Page 10-8
If you Locate a record u s i n g t h e p r i m a r y index f i l e ,
LOKSER
a u t o m a t i c a l l y locks t h e primary index f i l e f o r you.
However, i f you
l o c a t e a record u s i n g t h e secondary index f i l e , you must use the LOCK
statement t o e x p l i c i t l y l o c k t h e p r i m a r y index f i l e .
Whether o r not
you have the WAIT'FILE clause set i n your I S A M f i l e OPEN statement,
t h e LOCK statement w i 11 always cause your program t o w a i t f o r the
p r i m a r y index f i l e i f i t i s already i n use.
The statement :
UNLOKR # F i le-channel
unlocks the p r i m a r y index f i l e and any record c u r r e n t l y locked
READL statement.
10.6
via
a
ERROR PROCESSING
I f the e r r o r i s
Any I S A M o p e r a t i o n can r e s u l t i n some k i n d o f error.,
a system e r r o r ( f o r example, t h e d i s k i s n o t mounted),
AlphaBASIC
i n t e r r u p t s your program and a b o r t s t o the monitor.
(Or, i f e r r o r
t r a p p i n g i s enabled,
AlphaBASIC t r a n s f e r s c o n t r o l t o your e r r o r
h a n d l i n g routine.)
To check f o r hard system errors, use the ERR(X)
function.
S p e c i a l I S A M e r r o r s can a l s o occur as a r e s u l t o f an I S A M operation.
These e r r o r s do n o t generate an e r r o r message o r r e s u l t i n an e r r o r
trap.
I t i s t h e r e f o r e very important t h a t your plrogram check f o r
these e r r o r s a f t e r every I S A M statement; otherwise, you have no way o f
knowing whether o r not the I S A M f u n c t i o n was performed s u c c e s s f u l l y .
To do so, use the ERF(X) function, where X i s the f i l e channel number
(The ERF(X) f u n c t i o n operates
used by t h e preceding I S A M statement.
i n much the same way as the EOF(X) function.)
I f ERF(X) r e t u r n s a zero, t h e preceding I S A M statement was successful.
I f ERF(X) r e t u r n s a nonzero value, then an e r r o r was detected. I f an
e r r o r occurred,
your program should c o r r e c t t h e problem b e f o r e going
on t o access t h e f i l e .
The nonzero value r e t u r n e d t e l l s you which
e r r o r occurred.
For example:
! I f a "Record n o t found" e r r o r (#33),
!
a s k s f o r new key.
go t o r o u t i n e t h a t
100 I F ERF(2)=33 &
THEN PRINT "RECORD NOT FOUND" : GOT0 PROMPT
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
Page 10-9
The current I S A M e r r o r codes are:
32
33
34
35
36
37
38
39
- I l l e g a l I S A M statement code.
- Record not found i n index f i l e
search.
D u p l i c a t e key found i n index f i l e d u r i n g att:empted key a d d i t i o n .
L i n k s t r u c t u r e i s smashed and must be re-created.
Index f i l e i s f u l l .
Data f i l e i s f u l l ( f r e e l i s t i s empty).
End o f f i l e during sequential key read.
I l l e g a l I S A M sequence
-
-
-
The l a s t message occurs i f LOKSER i s i n s t a l l e d on your system and you
do not perform the I S A M f i l e access procedures i n the order given i n
Section 10.7.
REMEMBER: Always check a f t e r performing an I S A M f u n c t i o n t o see i f an
I f you do detect an error,
your program must take
e r r o r occurred.
c o r r e c t i v e a c t i o n before c o n t i n u i n g on.
For complete examples o f performing e r r o r checking and handling from
w i t h i n an AlphaBASIC program t h a t uses ISAM,
r e f e r t o t h e program
examples i n Chapter 6.
10.7
USING THE I S A M FUNCTIONS WITHIN AN ALPHABASIC PROGRAM
Below are some examples o f the ways you can combine t h e I S A M
statements and other AlphaBASIC commands t o access and use indexed
sequential f i l e s .
For a look a t a sample I S A M program, t u r n t o
Section 10.8.
Also see the program examples i n Chap,ter 6.
10.7.1
Adding Data t o an Indexed Sequential F i l e
A t t h e time t h a t you use ISMBLD
t o create an indexed s e q u e n t i a l
file,
you have t h e o p t i o n o f loading data i n t o the I S A M data and
primary index f i l e from an o r d i n a r y s e q u e n t i a l data f i l e .
Your
AlphaBASIC programs may a l s o add data t o the indexed sequential f i l e
For each new data
by using code 5 and code 3 I S A M statements.
record t o be added:
1.
Open the indexed sequential f i l e w i t h an OPEN
s p e c i f y i n g INDEXED mode. For example:
statement,
OPEN #100,"PHONES",INDEXED,RECSIZE,RELKEY
Remember t o open any secondary index f i l e s t h a t you might
want t o use v i a separate OPEN statements on d i f f e r e n t f i l e
I f LOKSER i s i n s t a l l e d on your system, the OPEN
channels.
statement above w i l l open the I S A M f i l e f o r Shared use.
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
2.
Page 10-10
Use a code 1 statement t o see i f t h e index e n t r y
t o add already e x i s t s .
For example:
I S A M #100,
1,
you
want
NAME
Check t o see i f an e r r o r was returned.
= 0 &
THEN PRINT " D u p l i c a t e Name."
For example:
I F ERF(100)
(Ifno e r r o r
and you can't
files,
also
don't a l r e a d y
3.
: UNLOKR # I 0 0 : GOT0 GET'NAME
occurred, then t h e index e n t r y a l r e a d y e x i s t s
add it.) I f you a r e u s i n g secondary index
check t o see t h a t t h e seconclary index e n t r i e s
exist.
R e t r i e v e t h e next f r e e
statement).
For example:
5,
I S A M #loo,
data
record
(a
code
5
ISAM
DUMMY
-
Check t o make sure t h a t an e r r o r (e.g.,
37
"?Data f i l e i s
f u l l ( f r e e l i s t i s empty)" d i d n o t occur.
For example:
I F ERF(100) O 0 THEN GOT0 ISAM'ERROR
4.
I f no e r r o r occurred, t h e record number o f t h e next f r e e
r e c o r d i s i n t h e r e l a t i v e record number vlariable d e f i n e d by
t h e OPEN statement f o r t h e indexed s e q u e n t i a l f i l e .
Now
you can w r i t e t h e data i n t o t h e record by u s i n g a WRITEL
statement.
For example:
WRITEL #100,INFO
(Note: Even i f LOKSER i s n o t i n s t a l l e d on your system,
proper coding techniques r e q u i r e t h a t you use WRITEL. O f
course, since LOKSER is not i n s t a 1 led, WRITEL w i 11 not l o c k
t h e record.)
5.
Now you must add t h e symbolic keys f o r t h a t data record t o
t h e index f i l e s , u s i n g a code 3 statement.
(Those symbolic
Be sure t o check
keys w i 11 then l i n k t o t h a t data record.)
For example:
f o r an I S A M e r r o r a f t e r each a d d i t i o n .
I S A M #100, 3, NAME
I F ERF(100) <> 0 THEN GOT0 ISAM'ERROR
6.
A f t e r adding
example:
a l l data records,
CLOSE # I 0 0
CLOSE #200
DWM-00100-06,
REV COO
close the I S A M f i l e s .
For
! Close p r i m a r y index f i l e / d a t a f i l e
! Close secondary irrdex f il e
USING I S A M FROM WITHIN ALPHABASIC
7.
Page 10-1 1
Your e r r o r t r a p p i n g r o u t i n e should c o n t a i n t h e UNLOKR
statement t o unlock t h e primary index f i l e and release t h e
c u r r e n t record i f an e r r o r occurs.
For example:
ISAM'ERROR:
UNLOKR # I 0 0
10.7.2
Reading Data Records i n Symbolic Key Order
I S A M s t o r e s symbolic keys i n t h e index f i l e i n A S C I I c o l l a t i n g
sequence.
To r e t r i e v e records i n t h e order i n which t h e i r keys
appear i n an index f i l e :
1.
Open the indexed s e q u e n t i a l f i l e w i t h an OPEN statement.
(If
you a l s o wish t o open one o r more secondary index f i l e s
t h a t cross-index t o t h e p r i m a r y index f i l e , use one OPEN
statement f o r each secondary index f i l e . )
2.
Execute a code 2 I S A M statement t o f i n d the
key.
3.
Check t o make sure t h a t the I S A M statement d i d n ' t r e t u r n an
error.
For example:
I F ERF(100) = 38 THEN PRINT "End o f f i l e . "
I F ERF(100) 0 0 THEN GOT0 ISAM'ERROR
4.
next
symbolic
: GOT0 PROMPT
The proper record number i s now i n t:he r e l a t i v e record
number d e f i n e d by t h e OPEN statement f o r t h e f i l e ,
so you
can use a READ statement t o read i n the data. For example:
READ # I 00,
INFO
Remember t h a t t h e READ statement must i n c l u d e t h e f i l e
channel assigned t o the p r i m a r y index f i l e even i f the code
2 I S A M statement i n c l u d e d a symbolic key contained i n a
secondary index f i l e ; t h i s i s because the data you want t o
read i s i n the data f i l e .
Also,
you must use t h e LOCK
statement t o lock t h e p r i m a r y index f i l e i f you l o c a t e d t h e
r e c o r d v i a a key i n the secondary index f i l e .
DWM-00100-06,
5.
Check
for
function.
6.
Repeat these procedures t o step through t h e data records i n
t h e order o f t h e symbolic keys i n the index f i l e s u n t i l you
reach the end of t h e f i l e , o r u n t i 1 you have accessed a l l
t h e records you need. Be sure t o check f o r an I S A M e r r o r
a f t e r each access.
REV COO
an
end-of-file
error
by
using
the
ERFCX)
Page 10-12
USING I S A M FROM WITHIN ALPHABASIC
7.
10.7.3
Close a l l f i l e s when you are done.
Reading Data Records Randomly by Symbolic Key
1.
Open the indexed s e q u e n t i a l f i l e w i t h an OPEN statement.
You
must
include
one OPEN statement f o r t h e data
f i l e l p r i m a r y index f i l e .
You must a l s o i n c l u d e one OPEN
statement f o r each secondary index f i l e you want t o access.
2.
Locate each data record by u s i n g a code 1 I S A M statement.
The statement must c o n t a i n t h e symbolic key associated w i t h
t h e record f o r which you are searching and t h e f i l e channel
associated w i t h the index f i l e c o n t a i n i n g t h e symbolic key.
3.
Check f o r a "record not found" error; t h i s i n d i c a t e s t h a t
t h e symbolic key was n o t l o c a t e d i n the s p e c i f i e d index
file.
4.
I f t h e record was found, use a READ statement t o read i n
t h e data record.
The READ statement i n c l u d e s the f i l e
channel associated w i t h the data f i l e / p r i m a r y index f i l e ,
even i f the symbolic key used belonged t o a secondary index
file.
I f t h e symbolic key belonged t o a secondary index
f i l e , remember t h a t you must lock t h e p r i m a r y index f i l e
b e f o r e u s i n g t h e READ statement.
5.
Repeat steps 2 through 4 f o r each r e c o r d you want t o f i n d .
6.
Close a l l f i l e s .
Updating Data Records
1.
Open t h e indexed s e q u e n t i a l f i l e w i t h an OPEN statement.
2.
Locate t h e data record you want t o update v i a one o f t h e
by u s i n g a code 1 o r code 2 I S A M
methods above (i.e.,
statement).
3.
Check t o make sure t h a t the record was found.
function.)
4.
Read t h e data record from t h e I S A M d a t a f i l e ,
t h e f i l e channel o f the p r i m a r y index fi1.e.
READL # I 00,
DVN-00100-06,
REV COO
DATA 'MAP
(Use t h e ERF
specifying
USING I S A M FROM WITHIN ALPHABASIC
Page 10-13
(NOTE: Even i f LOKSER i s n o t i n s t a l l e d on your system,
proper coding techniques r e q u i r e t h a t you use READL. O f
course, i f LOKSER i s not i n s t a l l e d , a READL w i l l n o t l o c k
t h e record and p r i m a r y index f i l e . )
5.
Make a copy o f the r e l a t i v e key.
For example:
OLD'KEY = NEW'KEY
6.
Get the new
t h e program.
data t o put i n t o the record from t h e user o f
7.
Check t h e key t o see i f i t changed:
I F OLD'KEY
= NEW'KEY THEN GOT0 SAME'RECORD
8.
Ift h e key d i d not change,
use t h e WRITE statement t o
(Th~e WRITE statement
update (and unlock) t h e data record.
i n c l u d e s t h e f i l e channel associated w i t h
the
data
f i l e l p r i m a r y index f i l e , even i f t h e symbolic key used t o
f i n d the record belonged t o a secondary index f i l e . )
9.
I f t h e . k e y d i d change,
files.
First,
you w i l l need t o
change
the
index
make sure the key i s unique:
I S A M #loo, 1, NEW'KEY
I F ERF(100) = 0 THEN GOT0 ISAM'ERROR
Next,
you must d e l e t e t h e o l d record (as discussed i n
S e c t i o n 10.7.5)
and add the new record (Section 10.7.1).
10.7.5
10.
Close a l l f i l e s .
11.
Your e r r o r t r a p p i n g r o u t i n e should c o n t a i n t h e UNLOKR
statement t o unlock t h e primary index f i l e and release t h e
c u r r e n t record i f an e r r o r occurs.
D e l e t i n g a Data Record
D e l e t i n g a data record from an indexed s e q u e n t i a l f i l e e n t a i 1s n o t
o n l y d e l e t i n g the record i t s e l f b u t a l s o d e l e t i n g a l l symbolic keys
associated w i t h t h a t data record from a l l index f i l e s .
DWM-00100-06,
1.
Open the p r i m a r y index f i l e and a l l secondary
needed.
2.
Locate t h e data record v i a one o f the symblolic keys (a code
1 I S A M statement).
REV COO
index
files
USING I S A M FROM WITHIN ALPHABASIC
3.
Check t o make sure
error.
For example:
Page 10-14
that
the statement executed w i t h o u t
I F ERF(2OO) = 33 THEM PRINT "Record not found."
I F ERF(200) <> 0 THEN GOT0 ISAM'ERROR
DWM-00100-06,
: GOT0 PROMPT
4.
Read t h e data record w i t h a READL statement
(whose
# f i l e - c h a n n e l i s t h e f i l e channel number associated w i t h
t h e primary index f i l e ) .
(Use READL even i f LOKSER i s n o t
i n s t a l l e d on your system.) I f you l o c a t e d t h e data record
u s i n g a symbolic key i n a secondary index f i l e ,
you must
f i r s t LOCK t h e p r i m a r y index f i l e b e f o r e doing t h e READL.
5.
E x t r a c t each symbolic key from t h a t data record. Use each
symbolic key t o d e l e t e each key from i t s associated index
f i l e w i t h code 4 I S A M statements.
6.
A f t e r a l l symbolic keys have been d e l e t e d from a l l index
ISAM
files,
d e l e t e t h e record i t s e l f v i a a code 6
statement.
7.
Close a l l f i l e s .
8.
Your e r r o r t r a p p i n g r o u t i n e should c o n t a i n t h e UNLOKR
statement t o unlock t h e primary index f i l e and release t h e
c u r r e n t record i f an e r r o r occurs.
REV COO
USING I S A M FROM WITHIN ALPHABASIC
10.8
Page 10-15
SAMPLE ALPHABASIC I S A M PROGRAM
The sample program i n the s e c t i o n below w i 11 make c l e a r e r the use o f
t h e commands discussed above.
For more i n f o r m a t i o n on u s i n g I S A M from
w i t h i n an AlphaBASIC program, c o n s u l t t h e manual AlphaBASIC User's
Manua l.
Before we can begin t o use ISAM, we must load i t i n t o memory i f i t i s
not already r e s i d e n t i n system memory:
Before we run the sample AlphaBASIC program, we f i r s t use the program
ISMBLD t o b u i l d t h e I S A M f i l e s LABELS-IDA ( t h e data f i l e ) , LABELS-IDX
( t h e primary index f i l e ) , and HASH-IDX ( t h e secondary index f i le).
Note t h a t we b u i l d an empty f i l e (i
.em, we t y p e a RETURN a f t e r t h e
"Load from f i l e : " prompt).
We use t h e AlphaBASIC program below t o
p l a c e data i n t o t h e f i l e .
10.8.1
Sample ISMBLD Use on an AMOS System
-.ISMBLD
LABELS @El
S i z e o f key: 2 5 m
P o s i t i o n o f key: I=
Size o f data record: 6 7 m
Number o f records t o a l l o c a t e :
E n t r i e s p e r index block: 1 0 m
Empty index b l o c k s t o a l l o c a t e :
Primary D i r e c t o r y : Y[REtl
Data f il e device: rRErl
Load from f il e :
-s.ISMBLD
i z e of
HASH -
key: 10P o s i t i o n o f key: 581RET]
S i z e o f d a t a record: 6 7 m
Number o f records t o a l l o c a t e : 50(RETI
E n t r i e s p e r index block: 10[RETI
Empty index b l o c k s t o a l l o c a t e : 2 0 m
Primary D i r e c t o r y ? N(RETJ
Secondary index t o f i l e : L A B E L S m
End o f b r i m a r v f i l e
No records loaded
DWM-00100-06,
REV COO
USING I S A M FROM WITHIN ALPHABASIC
10.8.2
Page 10-1 6
Sample ISMBLD Use on an AMOS/L System
-.ISMBLD
LABELS [REII
S i z e o f key: 2 5 m
P o s i t i o n o f key: I(RET1
S i z e o f d a t a record: 6 7 m
Number o f r e c o r d s t o a l l o c a t e : SOLRETI
6 i n d e x b l o c k s w i l l be a l l o c a t e d
Empty i n d e x b l o c k s t o a l l o c a t e : 6
m
Primary Directory:
Data f i l e device:-
-
~m
Load f r o m file:rRET)
HASH rREr)
-S.ISMBLD
i z e o f key: 10[RET)
P o s i t i o n o f key: 5 8 m
S i z e o f d a t a record: 6 7 m
Number o f r e c o r d s t o a l l o c a t e : 50 rREil
4 i n d e x b l o c k s w.. i l l b e a 1l o c at e d
Empty i n d e x b l o c k s t o a l l o c a t e : 4 a
P r i m a r y D i r e c t o r y ? N[RETI
-
-
-
-
~
Secondary i n d e x t o f i l e :
End o f ~ r i r n a r vf i l e
No r e c o r d s loaded
DWM-00100-06,
REV COO
-
-
~-
-
LABELS-
-
-
-
-
-
USING I S A M FROM WITHIN ALPHABASIC
10.8.3
Page 10-17
Sample AlphaBASIC Program
Once you have performed t h e procedures above,
v e r s i o n o f t h e program below:
-.RUN
you can r u n t h e .RUN
MAIL
THE SAMPLE ALPHABASIC PROGRAM
10 !
20 !
30 !
40 !
50 !
60 !
70 !
90 !
110
120
130
140
150
160
170
180
190
200
210
220
230
240
250
260
270
280
290
300
310
I S A M Sample Program.
T h i s program i s a simple example o f how t o handle I S A M f i les, b o t h
p r i m a r y and secondary.
I t simulates a very simple-minded m a i l i n g
l i s t program, w i t h the addresses keyed by both name and user
d e f i n e d hash code.
MAP1 LABEL
MAP2 NAME,S,25
MAP2 ADDRESS,S,25
MAP2 STATE,S,2
MAP2 ZIP,S,5
MAP2 HASH,S,lO
MAPl FIELDS
MAP2 NEWUADDRESS,S,25
MAP2 NEWUSTATE,S,2
MAP2 NEW'ZIP,S,5
MAP1 RECSIZE,F,6,67
OPEN #loo,
OPEN #200,
! Define the M a i l i n g L i s t f i l e
!
record.
! S i z e o f data record.
! Open the p r i m a r y and secondary
!
index f i l e s .
"LABELS",
INDEXED, RECSIZE, RELKEYl
"HASH",
INDEXED, RECSIZE, RELKEYl
PROMPT:
PRINT
INPUT "ENTER FUNCTION &
(l=ADD,2=DELETE,3=INQUIRE,4=PRINT,5=CHANGE,99=EN:
";FUNCTION
ON FUNCTION GOT0 ADDURECORD,DELETE'RECORD,INQU1RE'RECORD,&
PRINTILABELS,CHANGE'RECORD
I F FUNCTION=99 &
THEN GOT0 END' I T
GOT0 PROMPT
ADD'RECORD:
INPUT "ENTER NAME: 'I; NAVE
INPUT "ENTER ADDRESS: ";ADDRESS
INPUT "ENTER STATE: ";STATE
INPUT "ENTER ZIP: ";ZIP
INPUT "ENTER HASH: ";HASH
NAME = NAME + SPACE(25-LEN(NAME1)
HASH = HASH + SPACE(10-LEN(HASH1)
DWM-00100-06,
REV COO
! Add t r a i l i n g blanks t o keys
USING I S A M FROM WITHIN ALPHABASIC
I S A M #loo,
1,
NAME
Page 10-18
! Look up name t o v e r i f y t h a t
!
i t i s not a d u p l i c a t e .
I F ERF(100) = 0 &
THEN PRINT "DUPLICATE NAME" : UNLOKR # I 0 0 : GOT0 ADD'RECORD
! I f ERF(100)=0, then I S A M
!
found the key i n data f i l e
I S A M #200, 1, HASH
! V e r i f y t h a t hash i s not
!
duplica~te.
I F ERF(2OO) = 0 &
THEN PRINT "DUPLICATE HASH" : UNLOKR # I 0 0 : GOT0 ADD'RECORD
! Get f r e e data record from
I S A M #loo, 5, NAME
!
primary index
I F ERF(100) <> 0 &
THEN GOT0 ISAM'ERROR
WRITEL #loo, LABEL
! W r i t e out record.
I S A M #200, 3, HASH
! Add key t o secondary index
I F ERF(2OO) <> 0 &
THEN GOT0 ISAM'ERROR
! Add key t o primary index.
I S A M #loo, 3, NAME
I F ERF(100) <> 0 &
THEN GOT0 ISAM'ERROR
GOT0 PROMPT
DELETE ' RECORD :
INPUT "ENTER NAME: ";NAME
NAME = NAME + SPACE(25-LEN(NAME1)
I S A M #loo, 1, NAME
! V e r i f y t h a t the key e x i s t s
I F ERF(100) = 33 &
THEN PRINT "RECORD NOT FOUND" : UNLOKR # I 0 0 : GOT0 PROMPT
I F ERF(100) <> 0 &
THEN GOT0 ISAM'ERROR
READL #loo, LABEL
I S A M #200, 4, HASH
! D e l e t e key from secondary
I F ERF(2OO) <> 0 &
THEN GOT0 I S A M ' ERROR
I S A M #loo, 4, NAME
! D e l e t e key from p r i m a r y
I F ERF(100) <> 0 &
THEN GOT0 I S A M ' ERROR
I S A M #loo, 6, NAME
! D e l e t e data r e c o r d from
!
data f i l e .
I F ERF(100) <> 0 &
THEN GOT0 I S A M ' ERROR
GOT0 PROMPT
INQUIRE'RECORD:
INPUT "BY NAME (1) OR HASH (2): ";FUNCTION
I F FUNCTION = 2 &
THEN GOT0 BY'HASH
INPUT "NAME: ";NAME
NAME = NAME + SPACE(25-LEN(NAME1)
I S A M #loo, 1, NAME
! Locate t h e record
DWM-00100-06,
REV COO
Page 10-19
USING ISAM FROM WITHIN ALPHABASIC
800
810
820
830
840
850
860
870
880
890
900
910
920
930
940
950
960
970
975
980
990
1000
1010
1020
1030
1040
1050
1060
1070
1080
I F ERF(100) = 33 &
THEN PRINT "RECORD NOT FOUND" : UNLOKR # I 0 0 : GOT0 PROMPT
I F ERF(100) <> 0 &
THEN GOT0 ISAM' ERROR
READ'RECORD:
READ MOO, LABEL
PRINT NAME, HASH
PRINT ADDRESS, STATE,
GOT0 PROMPT
! Read t h e r e c o r d
ZIP
! L o c a t e r e c o r d b y hash
BY'HASH:
INPUT "HASH: ";HASH
HASH = HASH + SPACE(10-LEN(HASH1)
LOCK # I 0 0
! L o c k p r i m a r y i n d e x f il e
ISAM #200, 1, HASH
I F ERF(2OO) = 33 &
THEN PRINT "RECORD NOT FOUND" : UNLOKR # I 0 0 : GOT0 PROMPT
I F ERF(2OO) <> 0 8
THEN GOT0 ISAM'ERROR
GOT0 READ'RECORD
PRINT'LABELS :
NAME = SPACE(25)
ISAM #loo, 1, NAME
UNLOKR # I 0 0
LOOP:
! Read n u l l k e y t o g e t t o
!
f r o n t of f i l e .
! Release t h e index.
! Loop t h r o u g h f i l e d o i n g
!
s e q u e n t ia 1 r e a d s u n t i 1
!
ISAM #loo, 2, NAME
IFERF(100) = 3 8 &
THEN GOT0 PROMPT
I F ERF(100) <> 0 &
THEN GOT0 ISAM' ERROR
READ #loo, LABEL
PRINT
PRINT NAME, HASH
PRINT ADDRESS, STATE, Z I P
GOT0 LOOP
we h i t e n d o f f i l e .
! We h i t e n d - o f - f i l e .
1090 CHANGE'RECORD:
1100
INPUT "BY NAME (1 OR HASH (2) : ";FUNCTION
1110
I F FUNCTION = 2 &
1120
1130
1140
1150
1160
THEN GOT0 BY'HASH'CHANGE
INPUT "NAME: ";NAME
NAME = NAME + SPACE(25-LEN(NAME1)
ISAM #loo, 1, NAME
! Locate the record
ERF(100)
=
33
&
IF
THEN PRINT "RECORD NOT FOUND" : UNLOKR # I 0 0 : GOT0 PROMPT
ERF(100)
<> 0 &
IF
THEN GOT0 ISAM'ERROR
DWM-00100-06,
REV COO
USING ISAM FROM WITHIN ALPHABASIC
Page 1 0 - 2 0
1170 READ'RECORD'CHANGE:
1180
1190
1200
1210
1220
1230
1240
1250
1260
1270
1280
1290
1300
READL #loo, LABEL
PRINT NAME, HASH
PRINT "ADDRESS = "+ADDRESS
INPUT "NEW ADDRESS: ";NEW'ADDRESS
I F LEN(NEWIADDRESS) > 0 &
THEN ADDRESS = NEW'ADDRESS
PRINT "STATE ="+STATE
INPUT "NEW STATE =I1;NEW'STATE
I F LEN(NEWISTATE) > 0 &
THEN STATE = NEW'STATE
PRINT " Z I P = "+ZIP
INPUT "NEW Z I P ="; NEW'ZIP
I F LEN(NEWIZIP) > 0 &
THEN ZIP=NEW'ZIP
WRITE #loo, LABEL
GOT0 PROMPT
1310 BY'HASH'CHANGE:
1320
1330
1340
1350
1360
1370
1380
1390
INPUT "HASH: ";HASH
HASH = HASH + SPACE(10-LEN(HASH1)
LOCK # I 0 0
ISAM #200, 1, HASH
IFERF(2OO) = 3 3 &
THEN PRINT "RECORD NOT FOUND" : UNLOKR # l o 0 : GOT0 PROMPT
I F ERF(2OO) < > O &
THEN GOT0 ISAM' ERROR
GOT0 READ'RECORD'CHANGE
1 4 0 0 END'IT:
1410
CLOSE # I 0 0
1420
CLOSE # 2 0 0
1430
END
! B e s u r e t o c l o s e f il e s
!
b e f o r e we e x i t !
1 4 4 0 ISAM'ERROR:
1450
PRINT "?FATAL ISAM ERROR"
1460
PRINT "ISAM ERROR "+ERF(100)+";
1470
UNLOKR # I 0 0
1480
END
! ERF(X) r e t u r n e d ISAM e r r o r
! o t h e r t h a n RECORD NOT FOUND.
DWM-00100-06,
REV COO
SECONDARY: "+ERF(200)
I S A M SYSTEM USER'S GUIDE
.INDEX
Page Index-1
Index
. . . . . . . 710-9
. . . . . . .10.
.
. . . . . . . .. .. .. .. .. .. 7-1
7-2
. . . . . . . . . . . . . 7-3
7-1
. .. .. .. .. .. .. .. .. .. .. .. .. 7-1.
. . . . . . 8-1
.. .. .. .. .. .. .. .. .. .. .. .. .. 8-1
8-3
. .. .. .. .. .. .. .. .. .. .. .. .. 8-1
8-1.
Adding data records
Adding symbolic keys
AMOS monitor c a l l s
COPY
EXIT
FETCH
GETMEM
AMOS/L monitor c a l l s
COPY
EXIT
FETCH
GETMEM
BAS1C
Adding data records
Closing f i l e s
D e l e t i n g data records
ERF(X)
E r r o r processing
I S A M codes
I S A M e r r o r codes
I S A M statement
OPEN statement
Opening an I S A M f i l e
READ statement
Reading data records
READL statement
Sample I S A M program
Updating data records
WRITE statement
WRITEL statement
Block s p l i t
. . . .. ... ... ... ... ...
. . . . . .. .. .. .. .. .. ..
. . . .. .. .. .. .. .. ..
........
. . . .. .. .. .. ..
. . . .. .. .. .. ..
. . .. .. .. .. .. ..
.....
. .. .. .. .. .. .. ..
...........
CLOSE
Closing I S A M f i l e s . . . . . . .
Code . . . . . . . . . . . . . .
Completion codes . . . . . . . .
1S.EOF
.. .. .. .. .. .. .. .. .. .. .. ..
IS.SUC
C o n d i t i o n codes . . . . . . . . .
Condition f l a g s . . . . . . . . .
Contiguous f i l e . . . . . . . . .
m . . . . . . . . . . . . .
DWM.00100.06.
REV COO
88
..
7-3
8-3
10-5
I S A M SYSTEM USER'S GUIDE
Counted update mode
Creating I S A M f i l e s
.INDEX
.......
.......
Page Index-2
25..
31..
74
..
84..
10-1
. . . . . . .. .. .. .. .. .. 72-2
t o 2-4
6..
86..
10.5.
. . . . . 7.10. 88.. 10-5
. . . . . .. .. .. .. 2-5
4-2
. . . . 4-2
ERF . . . . . . . . . . . . . . . 6-11
ERF f u n c t i o n . . . . . . . . . . 10-4
E r r o r processing . . . . . . . . 10-8
E x c l u s i v e open mode . . . . . . . 2-5 t o 26..
74..
F i l e channel . . . . . . . . . .
F i l e interlocking . . . . . . . .
F i l e Locking . . . . . . . . . .
F i l e p a i r number . . . . . . . .
F i l e parameters . . . . . . . . .
Filespec . . . . . . . . . . . .
F i n a l i z i n g I S A M processing . . .
F i n d i n g data records . . . . . .
F i n d i n g f r e e data records . . . .
F i n d i n g symbolic keys . . . . . .
F i n d i n g t h e next key . . . . . .
Flags . . . . . . . . . . . . . .
FLOCK . . . . . . . . . . . . . .
Index f i l e . . . . . . . . . . .
Index Levels . . . . . . . . . .
INDEXED . . . . . . . . . . . . .
Indexed s e q u e n t i a l f i l e . . . . .
Data f i l e . . . . . . . . . . .
Index f i l e . . . . . . . . . .
INDEXED'EXCLUSIVE . . . . . . . .
Indicators . . . . . . . . . . .
Initializing ISAM . . . . . . . .
ISAM . . . . . . . . . . . . . .
I S A M access modes . . . . . . . .
ISAM calls . . . . . . . . . . .
ICLOS . . . . . . . . . . . .
...IIDELK
............
DLFR . . . . . . . . . . . .
..II GF TI FNR . .. .. .. .. .. .. .. .. .. .. .. ..
.I N I T . . . . . . . . . . . . .
..IREDR
IOPNR . . . . . . . . . . . .
.. .. .. .. .. .. .. .. .. .. .. ..
..IRLRD
IRLWT . . . . . . . . . . . .
.IWRTR . . . . . . . . . . . .
Data f i l e
D e l e t i n g data records
D e l e t i n g symbolic keys
D i r e c t o r y Rock
D i s p l a y i n g the data f i l e
D i s p l a y i n g t h e index f i l e
DWM.00100.06.
REV COO
10-2
10-13
84..
10-2
ISAM
SYSTEM .USER'S GUIDE
.INDEX
Page Index-3
.
............
...........
........
.............
. .............
. .............
.........
ISMBLD . . . . . . . . . . . . .
ISMDMP . . . . . . . . . . . . .
ISUSYM.M68 . . . . . . . . . . .
ISUSYM-MAC . . . . . . . . . . .
Loading I S A M f i l e s . . . . . . . 3-1
LOCK . . . . . . . . . . . . . . 69..
LOKSER . . . . . . . . . . . . . 63..
SREDR
I S A M codes
I S A M e r r o r codes
I S A M f i l e extensions
.IDA
IDX
IDY
I S A M statement
....
...
.......
..............
Memory a l l o c a t i o n r o u t i n e
Memory d e a l l o c a t i o n r o u t i n e
Memory requirements
Mode
.......
Primary index f i l e . . . . . . .
READ . . . . . . . . . . . . . .
Reading data records . . . . . .
READL . . . . . . . . . . . . . .
Record s i z e . . . . . . . . . . .
R e l a t i v e key . . . . . . . . . .
R e l a t i v e r e c o r d number . . . . .
Opening I S A M f i l e s
..........
Sample BASIC I S A M program . . . .
Sample ISMBLD d i a l o g . . . . . .
Secondary index f i l e . . . . . .
Suppressing E x c l u s i v e Open mode .
Symbolic key . . . . . . . . . .
Table o f f s e t s . . . . . . . . . .
Return codes
......
.............
......
WAIT'FILE . . . . . . . . . . . .
WAIT'RECORD . . . . . . . . . . .
WRITE . . . . . . . . . . . . . .
WRITEL . . . . . . . . . . . . .
W r i t i n g data records . . . . . .
Unloading I S A M f i l e s
UNLOKR
Updating data records
DWM.00100.06.
REV COO
6.13.
67..
10-7
10-2
73..
8-3
73..
8-3
71..
8-1
10-2
74..
84..
23..
2-5
10-1
10-6
7.
86..
10-11 t o 10-12
10-6
10-2
2-2
22..
10-2
71.
8-1
10-15
10-15
23..
2-5
27..
35..
10-4
71..
4-2
8-1
4-1
6-9 t o 6.10.
10-8
78..
87..
10-12
10-2
10-2
10-6
10-6
78..
8-7
- -
I S A M SYSTEM U S E R ' S G U I D E
XLOCK
- INDEX
..............
I
I
I
I
DUN-00100-06,
REV COO
Page Index-4
6-2 t o 6-4