Download ISAM PLUS User`s Manual

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