Category : C Source Code
Archive   : LSAM23.ZIP
Filename : LSAM.DOC

0 GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - CONTENTS - - -|
|___________________________________________|


Notice to users .................. 0
New Features ..................... 1
Introduction ..................... 2
System overview .................. 3
System requirements .............. 5
Storage requirements ............. 6
Function summary ................. 7
Header files ..................... 8
Function descriptions ............ 9
Linking programs ................. 14
Support programs ................. 15
Runtime control variables ........ 18
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - NOTICE TO USERS - - -|
|___________________________________________|

page 0H

The LSAM program product of Lydian Software is copyrighted material.

Beginning with Version 2.03, LSAM will be distributed in its full-func-
tion form as shareware. You are granted a temporary license to use
this system for a trial period not to exceed 30 days, after which,
continued use brings with it the obligation to register a permanent
license agreement with Lydian Software to use this product.

AFTER YOU REGISTER, you may distribute the RTL and associated parm
files to any of your friends and/or users without royalty or other
obligation. Periodic upgrades will be available at a modest charge.
The current requested contribution for registration is $49.95, which
will be effective through July 31, 1988. If you wish more information,
you may contact us via regular mail, CompuServe's EasyPlex, or GEnie's
mail:

Craig J. Starr
d/b/a Lydian Software
1 Brook Road, Unit 8
Salem, NH 03079
CompuServe userid 72617,1345
GEnie mail address C.STARR

I will be happy to answer any of your questions.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - NEW FEATURES - - -|
|___________________________________________|

page 1H

Several new features and changes have been incorporated into LSAM
since Version 2.02. They are:

1) Disabled demo approach has been abandoned. Shareware.
2) A trace/debug facility has been added. See ls_trace() and
ls_fn_ret() in section 'FUNCTION DESCRIPTIONS.'
3) Support for release of LSAM's acquired storage (after user
closes all LSAM-controlled files) without having to
exit to DOS, as in V2.02. Processing can continue, using
this freed storage, and LSAM can then be re-activated
later (assuming enough storage is available). See
ls_release() in section 'FUNCTION DESCRIPTIONS.'
4) Support for passing an exit code through ls_exit() (which
in turn calls ls_release() ) to DOS.
5) Improved error trapping:
a) Trace block 'lstat' contains the return code of
the last LSAM function called, including ls_open().
b) User parameter 'base' is now validated on any LSAM
call which uses 'base' pointer argument.
c) User parameter 'ix' is now validated on any LSAM
call which uses 'ix' subscript number argument.
6) Support for Microsoft C release 4.x and below has been
dropped due to insufficient demand.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - INTRODUCTION - - -|
|___________________________________________|

page 2H

LSAM (Lydian Software Access Method) V2.03 is an indexed sequential
(ISAM) file access method implemented as a runtime library accessed
through a set of interface subroutines for users of Microsoft (5.x +)
compilers. Its price is significantly below that of the lowest discoun-
ted-price b+tree indexed file access method packages available up to
now, but its function and ease of use make it formidable competition
for it's higher-priced cousins. It is an ideal choice for the appli-
cation programmer who needs a full-function, high-performance indexed
file access method at a reasonable price.

It features support for multiple indices per base file, insertion,
deletion (logical), retrieval and update by 'key', and full (logical)
sequential processing capability in both directions, including (re-)
positioning of a file's internal current record pointer for sequential
processing of a record (or group of records) beginning at any logical
record location in the file. For a more detailed discussion of the
particulars of the system's function and logic, see the section entitled
'SYSTEM OVERVIEW.'

LSAM is supplied in the form of 4 relocatable object libraries, one for
each of the standard memory models supported by Microsoft C 5.x, 1 exe-
cutable overlay module (referred to as 'the RTL'), several ASCII text
files (some containing required #define statements, some containing sam-
ple source for a typical parameter file generation, one containing this
documentation), and 2 standalone programs which support the generation
and formatted display of the binary image parameter files used to define
the attributes of the base/index file combinations to the runtime system,
all compressed into a '.arc' format file by the program "ARC", which
must be used to extract them.

The files contained in this archive are:

G
system files ---------------------------------------------------------
*** files required for compiling, linking and generating ***
*** programs and data which will make use of the LSAM system ***
slsam5.lib system subroutine library - 5.0 small model
clsam5.lib system subroutine library - 5.0 compact model
mlsam5.lib system subroutine library - 5.0 medium model
llsam5.lib system subroutine library - 5.0 large model
lsam.rtl system runtime support library
genparm.exe system parameter file generation utility
parmlist.exe system parameter file display utility
lsam.h required header file (user data structures)
lsrcodes.h required header file (return code #defines)
lslimits.h required header file (key, path length ctl)
lsam.doc this documentation
demo files -----------------------------------------------------------
*** sample programs, plus sample data and parm file inputs ***
*** see comment header in C sources for usage and suggestions ***
source bkup.c sample source (a backup) using LSAM calls
pgm bkup.exe sample executable pgm for bkup.c above
demo bkupdemo.bat batch demo of BKUP
source sample.txt sample parameter file ASCII source
input sample.bin sample generated binary parameter file
input sample.dat sample data file (as specified in sample.txt)
source sampleb.txt sample backup parameter file ASCII source
input sampleb.bin sample backup generated binary parameter file
source dlformat.c CIS data lib. 'sca /des' preformat C source
pgm dlformat.exe CIS data lib. 'sca /des' preformat .exe pgm.
source dlscan.c CIS multi-indexed DL scan demo C source
pgm dlscan.exe CIS multi-indexed DL scan demo .exe pgm.
source dl_clf.h required common header for dl*.c source
source dl3.txt parameter file ASCII text source for DLSCAN
demo dldemo.bat batch demo of DLSCAN
H
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - SYSTEM OVERVIEW - - -|
|___________________________________________|

page 3H

LSAM is composed of two major components, a runtime support 'overlay'
module and a subroutine function-request interface package. The sub-
routines are the only code linked into the application program. The
'runtime' support code is loaded into dynamically allocated storage
on the first 'open' call (ls_open()). It is subsequently called at its
various entry points whenever one of the LSAM subroutines is called,
passing the appropriate request parameters. At system exit time, it
is then called with a request to free any storage it has allocated, and
when this call returns, the storage allocated for loading the runtime
code is returned to DOS. The runtime code is thus technically a 'part-
time' runtime library (RTL), since it occupies storage only from the
application's first ls_open() call until the application calls either
ls_release() or ls_exit() (this is why IT IS IMPERATIVE THAT ANY CALLS
TO EXIT() WHICH WOULD BE ISSUED AFTER THE FIRST OPEN CALL BE REPLACED BY
CALLS TO LS_EXIT() ). The benefits of this approach are that 1) the 20+K
of code in the RTL is NOT LINKED INTO ANY APPLICATION PROGRAM which
uses it, saving on application code disk space requirements, and 2) en-
hancements, updates, and fixes to the RTL do not require recompilation
of existing application programs, but rather shipment of a revised RTL
to application developers, who may in turn ship copies to the licensed
users of their systems.

LSAM is implemented with a 'separate index' philosophy. That is, it
does not intermingle the ind(ex/ices) and the user's data, which remain
as standard sequential binary (fixed-length record - ver. 2.03) files,
capable of being processed as such by any non-LSAM application. Since
LSAM is not 'wired-in' to the user's data, it may easily be fitted to
existing applications with existing user data files with NO CONVERSION
OF DATA REQUIRED, by simply generating the required parm file(s) and re-
placing I/O routine calls with the corresponding LSAM subroutine calls.

LSAM can open (or create, if [it does/they do] not exist) and use any
number of indices for any number of base files (within the confines of
available storage - see 'STORAGE REQUIREMENTS'). Logical record length
may be up to 64K (65536) bytes, but must be of fixed length for rel. 2.03.
Keys are limited to a total of 255 bytes in length, and may be 'split,'
i.e. comprised of multiple non-contiguous fields in the user record.
The b+tree index management internals in the runtime system can support
index entries for files of up to 2 ** 32 (4,294,967,296) user logical
records. However, the multiple base file seeks required for relative
byte offsets greater than the number above have not yet been implemented
in the LSAM functions to which the user has access, so the current
practical upward limit is ((2 ** 32) / (user lrecl)) records. The
system is parameter-file driven in that it uses, for each base/index
file group, a generated binary image file, which tells LSAM the charac-
teristics of the data and index files it will open and process, such as
the file/index pathname, logical record length, location in the logical
record of key field(s), and several other attributes, discussed in full
under the section entitled 'SUPPORT PROGRAMS.' This allows the program-
mer to isolate from the application such details as key field length
and position, file name, path name, and other information which may
change periodically, without being required to recode or recompile
the application program.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - SYSTEM OVERVIEW - - -|
|___________________________________________|

page 4H

LSAM's control blocks are built at base/index file set open time
from binary parameter files (one each per base/index file set). The
open routine returns a pointer to an internal control block, which the
user will pass to the various other interface routines along with other
parameters. The binary parameter files are generated by the standalone
program genparm.exe using ASCII text source input similar in format to
the 'keyword=parm,keyword2=parm2' format characteristic of IBM mainframe
system software generation/configuration macros, although somewhat more
free form. The parameters and their coding requirements are documented
more fully under the section 'SUPPORT PROGRAMS.' Sample text for such a
parameter file (sample.txt) is included in the package.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - SYSTEM REQUIREMENTS - - -|
|___________________________________________|

page 5H

Application developers using LSAM will require (on their own and their
target user systems):

128K RAM Minimum (assuming no add-on memory-resident programs
and a very small LSAMIXALLOC value)
DOS 3.0 or higher
** A hard disk is also preferred but not required

Developers themselves will require:

Microsoft C compiler (release 5.0 or higher) and libraries.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - STORAGE REQUIREMENTS - - -|
|___________________________________________|

page 6H

The user (application programmer) controls the ultimate (potential)
storage requirements of LSAM through the DOS environment variable
LSAMIXALLOC, which (see section entitled 'RUNTIME CONTROL VARIABLES')
specifies the number of index control blocks to allocate at startup
time. The storage required for each control block is, in Version 2.03,
36 bytes. In addition, buffers totaling either 3K, 6K, or 12K are
allocated at open time for each index file opened by the runtime system,
depending on the length of the key (keylengths 1-64 cause 3K of buffers
to be allocated, keylengths 65-128 will use 6K of buffers, and 129-255
will use 12K of buffers). These factors must be considered in planning
the design of any application system which is to make effective use of
LSAM.

As an example, if the largest application your user will run uses 16 in-
dex files and they will all be open at the same time and have keylengths
less than 65, control blocks will require 16 times 36 bytes = 576 bytes
for internal control blocks (allocated as a block at startup), plus
16 times 3K bytes = 49152 bytes for buffer space, for a total allocation
of 49728 bytes in addition to the requirements (check your program with
Microsoft's EXEMOD utility) of your program and the roughly 30K
bytes required for the load of the runtime system:

16 ctl blocks 576 bytes
16 3K buffers 49152 bytes
runtime stge. 30000 bytes
avg user pgm. 25000 bytes
-----
total required 104728 bytes for this application
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - FUNCTION SUMMARY - - -|
|___________________________________________|

page 7H

The following is a list of the functions available to the user of
the LSAM system. Full descriptions follow in the FUNCTION DESCRIPTION
section.

void ls_bldixkey(); /* build key string service for non-contiguous keys */
int ls_is_ix_new(), /* ret. RIXISNEW if ix created by this run, else NO */
ls_bldindx(), /* build index file for given base file */
ls_startbr(), /* (re)set internal current record pointer for seq read */
ls_read(), /* 'key' read - 'random' retrieval of logical record */
ls_readnext(), /* sequential read (next) logical record, given index */
ls_readprev(), /* sequential read (prev) logical record, given index */
ls_write(), /* write new record */
ls_rewrite(), /* update existing record */
ls_delete(), /* delete existing record */
ls_close(), /* close base/index file set */
ls_trace(), /* sets trace ON/OFF for ALL,BASE,INDEX */
ls_fn_ret(), /* display func, ret. code, desc. for last LSAM call */
ls_release(), /* release RTL memory and RETURN to caller */
ls_exit(), /* release RTL memory and EXIT w/code */
lsam(); /* dummy call to force linker inclusion of lsam module */
LSBFPP ls_open(); /* open base/index file set using generated parm file */
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - HEADER FILES - - -|
|___________________________________________|

page 8H

Three header files are supplied with LSAM: "lsam.h", "lsrcodes.h", and
"lslimits.h", which are to be included via the #include compiler
directive in any source modules which make reference to any LSAM
function or symbolic name (i.e. a manifest constant such as the return
code constant value RGOOD). Since LSAM.H contains '#include's for
LSRCODES.H and LSLIMITS.H, the application programmer need only code the
required '#include' for LSAM.H. Put these files in a subdirectory which
the compiler will search when it compiles your programs.

LSAM.H contains the data structure definitions and symbolic constants
for various request parameter values required to use LSAM, plus the
declarations of all the functions available in the system.

LSRCODES.H contains the symbolic constants (#defines) for the LSAM
system return codes. Since these values may change in a future re-
lease, the user is STRONGLY advised to USE THE NAMES when testing re-
turn codes for specific values. They will not change from release
to release. This will simplify maintenance to your source when
upgrading to a future release.

LSLIMITS.H contains the symbolic constants (#defines) for the LSAM
field size limits: maximum keylength and maximum pathname length. As
with LSRCODES.H above, the user would be well advised to use these
symbolic names rather than hard-code numeric values, for the same
common-sense reasons of maintainability.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - FUNCTION DESCRIPTIONS - - -|
|___________________________________________|

page 9H

By using the interface subroutine oriented approach, most calls to
the LSAM functions simply pass the LSBFPP pointer, an index no., key,
and the system routines take care of the required control block manipu-
lation, thereby simplifying the programmer's task.

Zero return codes are OK for all except ls_open(), which should return
the address of the control block it allocates. Other return codes re-
present error conditions and should be handled appropriately (with the
exception of REOF, which may be ignored if the programmer desires to
"wrap-around" to the logical beginning or end of the file). The trace
facility block 'lstat' contains a pointer to an ASCIIZ string contain-
ing the name of the last LSAM function called, and its return code. See
descriptions for ls_trace(), and ls_fn_ret() for further information.
The 'lstat' structure is typedef-defined (LSSTATUS) in LSAM.H.

Note also that all index searches by LSAM proceed on a case insensitive
basis. That is, "this key" and "This Key" and "THIS KEY" are consider-
ed logically equivalent by LSAM's index search logic.

lsam() /* dummy call */

This function is a do-nothing routine supplied to enable the user to
force the linker to include the lsam.obj module which contains all of
the routines described below. The extern declaration in LSAM.H for this
function is all that is required to force linker inclusion of lsam.obj.

int ls_is_ix_new(base,ix) /* RETURNS RIXISNEW IF INDEX WAS CREATED BY THIS RUN*/
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index selected */

ls_open() sets internal control codes for each index file successfully
opened. Use this routine to check the status of a particular index file
to determine if it was just created. The routine ls_bldindx() also
checks this status and exits if it is not TRUE. Should you wish to re-
build an existing index file, you must delete it from DOS before running
your application program, which should have a call to this routine and
a corresponding conditional call to ls_bldindx() for each index file you
wish to rebuild. Usage example:

if(ls_is_ix_new(base,ix) == RIXISNEW)/*did LSAM just create this ix?*/
ls_bldindx(base,ix); /* then ask LSAM to build it */

** NOTE: This routine in V2.02 returned YES if index was created by
this run. It now returns the manifest constant RIXISNEW.

int ls_bldindx(base,ix) /*CREATES AND BUILDS AN INDEX FILE FOR GIVEN BASE FILE*/
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be built */

Value "ix" is the table subscript of the index to build. Valid values
are 0 through the number of indices you 'genned' in your parameter file
minus 1 (i.e. they are relative subscript numbers) and CORRESPOND DIRECT-
LY to the order in which you specified them in the text of the parm file.

NOTE: ls_open() sets internal control codes for each index file successfully
opened. ls_bldindx() checks one of these before proceeding and exits if
it indicates that the index file is not new/empty.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - FUNCTION DESCRIPTIONS - - -|
|___________________________________________|

page 10H

void ls_bldixkey(base,ix,key) /*BUILD INDEX KEY FIELD FROM RECORD KEY FIELD(S)*/
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */
UCHAR *key; /* pointer to user key work array */

Since the functions which require keys take a single address value for
the key, it is necessary to concatenate any split key sub-fields before
calling a routine which requires a key field address. This routine
uses register pointer variables and is very fast. THIS ROUTINE IS OF
NO USE FOR ANY OF YOUR INDICES FOR WHICH THE RECORD KEY IS ONE CONTI-
GUOUS AREA IN THE RECORD. FOR SUCH KEYS, THE ADDRESS OF THE KEY FIELD
WITHIN THE USER RECORD IS A VALID KEY POINTER, AND YOU WILL SAVE THE
PROCESSING OVERHEAD OF THIS CALL.

NOTE: This special function provides a service to concatenate split
key sub-fields from a user record into a user key work area, the
address of which may then be passed to any LSAM routine requiring
a key field address. User key work area(s) MUST BE LONG ENOUGH
to contain the key length used by the index referenced in the call.
This routine can NOT verify user key work area length, and will write
until all key sub-fields are copied, potentially clobbering adjacent
data. To play it safe, you can make your key field work area(s) 256
bytes long, one byte longer than the maximum key length (255), which
the parameter file generation program 'genparm.exe' dictates.

int ls_startbr(base,ix,key,stype) /* START BROWSE - POSITION IN FILE VIA IX */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */
UCHAR *key; /* pointer to user key work array */
UCHAR stype; /* type of start: GTEQ or EQUAL */

(High-order, i.e. leftmost) Partial keys may be used if stype = GTEQ is
specified. Position will be at logical record with next greater or
equal record key value. Return will be RGOOD regardless of whether
the key found is greater than or equal to the requested key field.
If EQUAL is specified, full key should be supplied because the runtime
searches for an EXACT match. In this case, if an exact match is not
found, the runtime returns RNOTFND and the current record pointer for
the index specified by 'ix' remains where it was.

int ls_read(base,ix,key) /* READ 'RANDOM' BY KEY */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */
UCHAR *key; /* pointer to user key work array */

Return value RNOTFND indicates that the key pointed to by 'key' was
not found in a search of the index specified by 'ix'. The previous
contents of the USER RECORD AREA WILL BE UNCHANGED.

int ls_readnext(base,ix) /* READ NEXT LOGICALLY SEQ. FILE RECORD */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */

Return value REOF may be ignored if desired. The next logical record
in the dataset will be in the user record area on return.

int ls_readprev(base,ix) /* READ PREV LOGICALLY SEQ. FILE RECORD */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */

Return value REOF may be ignored if desired. The previous logical rec-
ord in the dataset will be in the user record area on return.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - FUNCTION DESCRIPTIONS - - -|
|___________________________________________|

page 11H

int ls_write(base) /* WRITE A NEW RECORD */
LSBFPP base; /* pointer to base file info structure */

Appends a new record to the base dataset, and inserts an index entry
into ALL indices for which the UPGRADE=yes option was specified in
its parameter file generation. If UNIQUEKEY=yes was specified in
its parameter file, error RDUPKEY is returned if an entry for the
key is already present in an index for which UPGRADE=yes is in effect.

int ls_rewrite(base,ix,key) /* REWRITE AN EXISTING RECORD */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */
UCHAR *key; /* pointer to user key work array */

int ls_delete(base,ix,key) /* DELETE AN EXISTING (INDEX) RECORD */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */
UCHAR *key; /* pointer to user key work array */

This is a 'logical' delete. ONLY THE SELECTED INDEX RECORD IS DELETED,
thereby allowing a measure of recovery (by rebuilding the index file).

LSBFPP ls_open(parm,env_or_name,mode,recptr) /*OPEN BASE FILE & RELATED INDICES*/
UCHAR *parm; /* pointer to parm file ENV VAR or NAME */
int env_or_name; /* switch (PARM_ENV_VAR/PARM_NAME) is parm ENV or NAME ? */
UCHAR *mode; /* mode same as fopen() - 'BINARY' SEE DOC. */
UCHAR *recptr; /* address of user record area */

If the base file open succeeds, this function attempts to open all
related index files. All buffers required for each index group are
allocated by the runtime system at this time. The user MUST specify
a binary-mode open for this call (e.g. "w+b" "r+b" "wb" "rb" - see
fopen()). If not, base file positioning is NOT guaranteed to be
accurate.

NOTE: ON THE FIRST CALL TO ls_open(), THE RUNTIME CODE IS LOADED. ANY
CALLS TO OTHER INTERFACE ROUTINES BEFORE THIS WILL RESULT IN A
RETURN OF RINITERR (Initialization error, the b+tree runtime
library code has not been loaded).

NOTE: A NULL (ZERO) RETURN FOR ls_open() IS AN ERROR, AS WITH FOPEN().
The LSAM return value which triggered the NULL return can be found in
structure 'lstat' member '_rcode'. See ls_fn_ret() description for
further details.
---------------------------------------------------------------------

int ls_close(base) /* CLOSE BASE FILE AND ITS RELATED INDICES */
LSBFPP base; /* pointer to base file info structure */

This function will close all related index files for a base dataset,
then close the base via fclose(). All buffers allocated by the runtime
system for this index group are de-allocated at this time, as well as
the control blocks associated with 'base'. Return values are the same
as for fclose().
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - FUNCTION DESCRIPTIONS - - -|
|___________________________________________|

page 12H

int ls_trace(on_off,ttype,base,ix)/* set trace ON/OFF for ALL,BASE, or INDEX */
UINT on_off, /* trace ON/OFF(1/0) switch value (#defined)*/
ttype; /* trace type: ALL, BASE, INDEX (#defined) */
LSBFPP base; /* pointer to base file info structure */
UINT ix; /* relative subscript of index to be used */

This function provides a general debugging trace facility, capable of
of tracing LSAM functions calls, depending on the request type(ttype).
It sets a trace flag on for the requested type (ttype). Subsequent
LSAM calls will, immediately prior to return, display trace information
on stdout via ls_fn_ret() (see description below), if the appropriate
internal trace flag is ON.
There are three (3) types of trace ('ttype') requests:
ALL - All LSAM calls, including ls_open()s are traced.
Only arguments 'on_off' and 'ttype' are used for ALL.
User should specify NULL for 'base' and 0 for 'ix',
although these arguments are ignored on an ALL request.
BASE - All LSAM calls for ALL INDICES of 'base' are traced.
ls_open() calls cannot be traced, since there is no
valid LSBFPP type pointer available before the call.
Arguments 'on_off', 'ttype', and 'base' are used.
User should specify 0 for 'ix', although this argument
is ignored on a BASE request.
INDEX - All LSAM calls for the SPECIFIED INDEX of 'base' are
traced. ls_open() calls cannot be traced, since there
is no valid LSBFPP type pointer available before the
call. All arguments are used and required.
Each type of trace may be turned off by a corresponding OFF request for
the requested type (ttype). Note that an OFF request for ALL will NOT
turn tracing off for those explicitly specified BASE or INDEX requests
that the user has turned ON. Instead, the user must issue an OFF re-
quest for each such explicitly specified BASE or INDEX request.

int ls_fn_ret() /* display func, ret. code, desc., etc. for last LSAM call */

This function provides a convenient 'display last function, return
code, and description' service, useful during program testing and
debugging. It makes use of a structure, typedef-defined in LSAM.H,
which is globally accessible, called 'lstat'. Every LSAM function
(with the obvious exception of this one) now updates 'lstat._fn'
immediately upon entry with pointers to 3 ASCIIZ strings containing:
the function's name, the base file pathname (if applicable), the index
file pathname (if applicable), plus the index subscript no. (if appli-
cable). Immediately prior to return, each of these functions
updates 'lstat._rcode' with its return code, except for ls_open(),
which must return a pointer to the open file/index control block.
(ls_open() updates 'lstat._rcode' with the return code of the last
internal LSAM function it called, allowing better trapping of open
errors.) This function displays, on stdout, the name of the LSAM
function last called, the return code (decimal) and a mnemonic, de-
scriptive of the return value, plus the base file pathname (if appli-
cable), the index file pathname (if applicable), and the index sub-
script number (if applicable). The return code mnemonics are derived
from the manifest constant values you should be using to check return
codes, the leading 'R' being omitted in every case except RGOOD, whose
mnemonic is a more descriptive (I hope) 'OK'. As an alternative to
use of this function, the user has access to the 'lstat' structure,
and may use the information contained therein in any way he/she may
choose. The values in 'lstat' trace block are updated regardless of
the status of the current state of any level of trace flag, and there-
fore will be accurate for any ls_fn_ret() call. See also the descrip-
tion of ls_trace() above.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - FUNCTION DESCRIPTIONS - - -|
|___________________________________________|

page 13H

int ls_release() /* release RTL memory and RETURN to caller */

This function performs the LSAM RTL memory release. It is usually
requested by ls_exit(), but may now be called by a user who desires
to continue further processing without LSAM functions. It will be
of particular use to a developer who needs the storage which other-
wise would be owned by LSAM until program exit. CAVEAT: This routine
will NOT do an automatic close of open file/index sets for the user.
It is the USER'S RESPONSIBILITY to call ls_close() for each such file/
index set PRIOR to calling ls_release(). You have been warned.
RGOOD (zero) is the only valid return code. Anything else is an error.

NOTE: The RTL CAN be reloaded again after a call to ls_release().
This will happen automatically on the next call to ls_open().

int ls_exit(code) /* call ls_release(), then exit with user-supplied code */

This function will signal the RTL to release its acquired memory and
release the memory into which the RTL was loaded via a a call to
ls_release(), then call the standard C exit routine exit(), passing it
EITHER the user's exit code OR the return from ls_release() IF it is
NON-ZERO. It does not return. RESULTS ARE UNPREDICTABLE IF THIS ROU-
TINE IS NOT CALLED AS YOUR FINAL EXIT. See the section entitled 'SYS-
TEM OVERVIEW' for additional explanation of this requirement.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - LINKING PROGRAMS - - -|
|___________________________________________|

page 14H

We must assume that the application developer understands the use of
the MS-DOS linker and the concept of object linking in general. It is
beyond the scope of this documentation. Should the user/programmer be
unsure of these, he/she is advised to consult the MS-DOS linker documen-
tation in the MS-DOS reference before reading further under this sec-
tion.

No matter which linking method you may choose, the library name of the
LSAM system must be specified to the linker for the 'libraries' entry
or prompt BEFORE the name(s) of the standard C librar(y/ies), as there
are calls to standard C library functions in the LSAM subroutine package
which must be resolved.

Under NO circumstances should you mix memory model libraries. If you
are using compact model, for instance, you should use the compact model
LSAM library 'clsam.' The naming convention of the libraries, as sup-
plied, follows that of the Microsoft C libraries in its use of the first
character of the library name as an abbreviation for the memory model.
This should help you to avoid potential linking problems resulting from
linking with an incorrect memory model library. If you make such an er-
ror, the linker will respond with a 'segment fixup' error message, which
should clue you in to the problem.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - SUPPORT PROGRAMS - - -|
|___________________________________________|

page 15H

Two 'standalone' support programs are supplied with LSAM. Their purpose
is to perform the generation and formatted display/printout of the para-
meter files which supply LSAM with the required information about impor-
tant attributes of each set of data/index file(s).

GENPARM.EXE accepts an ASCII text file of statements describing the
characteristics of a data (hereafter referred to as 'base') file and its
related index/indices (there may be more than one index per 'base' file)
and generates a binary image file in the format required by LSAM to open
and process the base and its related index/indices. The syntax of these
statements is described in detail below. Usage is:

genparm [d:][\pathname\]filename[.txt]

where d: is drive (optional)
pathname is pathname (optional)
filename is parm filename (required)
.txt is extension (assumed)

Using the syntax rules described below, genparm will
produce the file [d:][\pathname\]filename.bin which
will be used by LSAM at base/index file open time and
in further processing.

GENPARM INPUT TEXT SYNTAX RULES

There is a single macro command recognized by genparm: lsparm.
The 'type' keyword must be specified first for all types. All other
keywords are non-positional (EXCEPT subkeyword 'ixname' for the 'index'
keyword, which must be the 1st subkeyword for each index file entry).
Upper, lower or mixed case input is accepted. Comments may begin any-
where on a line, and are preceded by either an asterisk ('*') or a semi-
colon (';') as a comment indicator. ALL TEXT FOLLOWING A COMMENT INDI-
CATOR IS IGNORED FOR THE REMAINDER OF THE LINE. Use of comments is not
required but is encouraged as a means to simplify maintenance. Equal
signs and commas are accepted as delimiters for those of you with the
IBM (370) macro point of view, but are not required (one or more blanks
will do instead). For type=entry, line continuation is indicated by a
dash ('-'), and is REQUIRED WHEN THE KEYWORDS/PARMS SPILL OVER BEYOND
ONE LINE. Keywords and corresponding parameters (and index subkeywords
and their parms) are signified, for each of its three forms, by the
value specified for the 'type' keyword:
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - SUPPORT PROGRAMS - - -|
|___________________________________________|

page 16H

-------------------------------------------------------------------- parm -
macro command keyword parameter/value reqd?
---------------------------------------------------------------------------
lsparm type 'begin' (marks beginning of source) | Yes
---------------------------------------------------------------------------
lsparm type 'entry' (marks a base/ix entry) | Yes
basename valid DOS filename [xxxxxxxx.xxx] | Yes
drive valid DOS drive designator [x:] | No
path valid DOS pathname [\xxxx[\xxx]\] | No
maxlrecl max logical record length GT 0 & LT 65537 | Yes
reclaim reuse 'deleted' base file space [YES | no] | No
before appending any new data records to |
end of base file |
*** IGNORED IN 2.03 - RECLAIM ALWAYS 'NO' |
recfm base file recd length is [FIXED | variable]| No
*** IGNORED IN 2.03 - RECFM ALWAYS 'FIXED' |
index ( subkeywords valid only for index keyword ) | Yes
*** BEGIN THIS ENTRY/GROUP WITH OPEN PAREN, |
END WITH CLOSE PARENTHESIS. |
-------------------------------------------|
ixname valid DOS filename [xxxxxxxx.xxx]| Yes
('ixname' MARKS BEGINNING OF EACH|
INDEX SPECIFICATION, AND SHOULD |
BE CODED BEFORE OTHER INDEX SUB-|
KEYWORDS) |
ixdrive valid DOS drive designator [x:] | No
ixpath valid DOS pathname [\xxxx[\xxx]\]| No
keys ( offset,len,offset,len ... ) | Yes
uniquekey key is unique [YES | no] | No
'no' allows duplicate keys |
upgrade insert key on write [YES | no] | No
'no' bypasses index update on |
write of record to base file |
---------------------------------------------------------------------------
lsparm type 'end' (marks end of source) | Yes
---------------------------------------------------------------------------
Alternatives/options are indicated in brackets separated by the symbol
'|' with the DEFAULT INDICATED IN UPPER CASE.
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - SUPPORT PROGRAMS - - -|
|___________________________________________|

page 17H

The following is a typical base/(multiple)index file parameter source
coding (coded a la IBM 370 mentality w/equal signs and commas, each of
which could just as easily be replaced by one or more blanks):

***************************************************************
* comment *
* documenting use of the base/index files specified here *
***************************************************************
lsparm type=begin
* either an asterisk (*)
; or a semicolon (;) is a valid comment delimiter
* comments may occupy an entire line
lsparm type=entry, - ; or the final part of a line
* comments need not begin in any particular position
basename=auto.dat, -
* and they may separate 'continued' lines
drive=c:, - * this is a comment
path=\c\demo\, - ; this is also a comment
maxlrecl=143,- ; use comments to document
reclaim=yes, -
recfm=fixed, -
index=(ixname=auto.i00,ixdrive=c:,ixpath=\c\demo\, -
keys=(2,15,18,11,30,1),uniquekey=yes,upgrade=yes, -
ixname=auto.i01,ixdrive=c:,ixpath=\c\demo\, -
keys=(2,15,18,11,30,1),upgrade=yes,uniquekey=yes)
lsparm type=end

Here is the same parm file, without the 370 macro characteristics, but
equally acceptable to genparm:

***************************************************************
* comment *
* documenting use of the base/index files specified here *
***************************************************************
lsparm type begin
* either an asterisk (*)
; or a semicolon (;) is a valid comment delimiter
* comments may occupy an entire line
lsparm type entry - ; or the final part of a line
* comments need not begin in any particular position
basename auto.dat -
* and they may separate 'continued' lines
drive c: - * this is a comment
path \c\demo\ - ; this is also a comment
maxlrecl 143 - ; use comments to document
reclaim yes -
recfm fixed -
index (ixname auto.i00 ixdrive c: ixpath \c\demo\ -
keys (2 15 18 11 30 1) uniquekey yes upgrade yes -
ixname auto.i01 ixdrive c: ixpath \c\demo\ -
keys (2 15 18 11 30 1) upgrade yes uniquekey yes)
lsparm type end

END GENPARM INPUT TEXT SYNTAX RULES


PARMLIST.EXE will display (on stdout) a formatted listing of the various
attributes/parameters in the binary image parameter file generated by
genparm.exe above. It is supplied as a convenient method of verifying
that the attributes/parameters the user specified for a given base/index
set are in fact what was intended. Output may, of course, be redirected
wherever desired, such as to a file or printer. Usage is:

parmlist [d:][\pathname\]filename[.bin]

where d: is drive (optional)
pathname is pathname (optional)
filename is filename (required)
.bin is extension (assumed)
GL S A M
___________________________________________
|- - - Lydian Software Access Method - - -|
|- - - Shareware Version 2.03 - - -|
|- - - USER DOCUMENTATION - - -|
|- - - RUNTIME CONTROL VARIABLES - - -|
|___________________________________________|

page 18H

Two DOS environment variables are supported for control of the LSAM
runtime system. They may be set or reset at any time, due to changing
needs, and do not require any accompanying program changes. They are
most conveniently set in the target user's autoexec.bat or other startup
batch file. (See the SET command in the DOS reference).

1) LSAMRTL should be set to the full path name identifying the
location of the runtime overlay module 'lsam.rtl.' This
variable is REQUIRED. The system will abort the application
program if this variable is not found in the environment.

2) LSAMIXALLOC should be set to the number of index control blocks
for the runtime system to allocate when it is loaded. This
may vary from application to application. For convenience,
set it to the largest number of indices (total) used by any
of your applications. This number must not exceed 1926, and
if it does, you should be running your application under
IDMS or DB2 on an IBM 3090, not with this package on a PC.
This variable is OPTIONAL, but it DEFAULTS TO 10, which may
not be adequate. Therefore, the user is encouraged to set
it to his/her 'reasonable' limit. This variable has a di-
rect bearing on the ultimate storage requirements of this
system. See the section entitled 'STORAGE REQUIREMENTS.'




G**** END ****H