HP KSAM/3000 software, 3000 MPE/iX computers Reference Manual

PDF
Документ
HP 3000 MPE/iX Computer Systems
KSAM/3000 Reference Manual
ABCDE
HP Part No. 30000-90079
Printed in U.S.A.
August 1986
Edition 2
E0886
The information contained in this document is subject to change without notice.
HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD
TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. Hewlett-Packard shall not be liable for errors contained herein or for incidental or
consequential damages in connection with the furnishing, performance or use of this material.
Hewlett-Packard assumes no responsibility for the use or reliability of its software on
equipment that is not furnished by Hewlett-Packard.
This document contains proprietary information which is protected by copyright. All rights
are reserved. No part of this document may be photocopied, reproduced or translated to
another language without the prior written consent of Hewlett-Packard Company.
c 1979,1981,1986
PREFACE
This publication is the reference manual for KSAM/3000. KSAM stands for Keyed Sequential
Access Method, a method of accessing les indexed by keys. KSAM/3000 operates on the HP
3000 Computer System.
The methods used to access a KSAM/3000 le dier depending on the particular language
used. A COBOL user, an RPG user, a BASIC user, and an SPL user each has his own set
of procedures with which to access a KSAM le; a FORTRAN user can choose to access
a KSAM le with either COBOL or SPL procedures. All users can create, copy, purge, or
perform other utility functions with the KSAMUTIL and FCOPY programs.
This manual is organized so that the more general functions available to all users are
described in the rst two sections followed by a section describing KSAM access from each
of the four languages: COBOL, SPL, FORTRAN, and BASIC. Access to KSAM from a
COBOL II program is through COBOL II's indexed I/O Module and is not documented in
this manual. Access to KSAM les from an RPG program is not described in this manual, but
is included as part of the RPG manual:
RPG/3000 Compiler Application &amp; Reference Manual (32104-90001, Second Edition, 2/77)
In order to use this manual eectively, you should be familiar with the MPE Operating
System and with FCOPY. Also, it is assumed that you are familiar with the language in
which you are programming.
SECOND EDITION
The second edition of the KSAM manual provides the following new information:
Full syntax for and description of how to use the new KSAMUTIL commands: KEYSEQ,
KEYDUMP, and KEYINFO. (section II)
Enhancements to the KSAMUTIL utility to allow abbreviated command names, oine
listing of displays, and entry of MPE commands from KSAMUTIL. (section II)
Discussion of record pointer positioning in all languages; with special emphasis on using the
record pointers for shared access. (sections III, IV, VI)
Description of how pointers are set internally. (appendix B)
Discussion of recovery procedures in case of system failure. (appendix E)
In addition, there are minor corrections throughout the manual as well as documentation of
minor enhancements.
This edition covers the version of KSAM number A.02.04 release on the 1918 IT.
iii
Contents
1. INTRODUCING KSAM/3000
OVERVIEW . . . . . . . . . . . . . . . . . .
FILE STRUCTURE . . . . . . . . . . . . . .
FILE ACCESS . . . . . . . . . . . . . . . .
KSAM/3000 FEATURES . . . . . . . . . . . .
MULTIPLE KEYS . . . . . . . . . . . . . .
DUPLICATE KEYS . . . . . . . . . . . . .
GENERIC KEYS . . . . . . . . . . . . . . .
APPROXIMATE MATCH . . . . . . . . . . .
DATA RECORD FORMAT . . . . . . . . . .
HOW TO USE KSAM FILES . . . . . . . . . .
CREATING A KSAM FILE . . . . . . . . . .
WRITING RECORDS TO A KSAM FILE . . . .
RETRIEVING RECORDS FROM A KSAM FILE
UPDATING RECORDS IN A KSAM FILE . . .
POSITIONING IN A KSAM FILE . . . . . . .
DELETING RECORDS FROM A KSAM FILE .
REORGANIZING A KSAM FILE . . . . . . .
SHARED ACCESS TO KSAM FILES . . . . . .
RECOVERY AND ANALYSIS OF KSAM FILES .
USING FILE EQUATIONS WITH KSAM FILES .
HOW TO USE THIS MANUAL . . . . . . . . .
RPG PROGRAMMER . . . . . . . . . . . .
COBOL II PROGRAMMER . . . . . . . . . .
COBOL PROGRAMMER . . . . . . . . . . .
SPL PROGRAMMER . . . . . . . . . . . . .
FORTRAN PROGRAMMER . . . . . . . . .
BASIC PROGRAMMER . . . . . . . . . . .
ALL PROGRAMMERS . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1-1
1-1
1-2
1-2
1-3
1-3
1-3
1-4
1-4
1-5
1-6
1-6
1-6
1-7
1-7
1-7
1-7
1-8
1-8
1-8
1-9
1-9
1-9
1-9
1-10
1-11
1-11
1-12
USING KSAM UTILITIES . . . . . . . . . . . .
OVERVIEW . . . . . . . . . . . . . . . . . . .
KSAMUTIL UTILITY . . . . . . . . . . . . . .
RUNNING KSAMUTIL . . . . . . . . . . . . .
COMMAND ABBREVIATIONS. . . . . . . . . .
RUNNING MPE COMMANDS FROM KSAMUTIL.
OPTION TO LIST DISPLAYS ON LINE PRINTER.
OPTIONAL PARAMETERS. . . . . . . . . . .
EXITING FROM KSAMUTIL . . . . . . . . . .
HELP . . . . . . . . . . . . . . . . . . . . . .
REQUESTING HELP . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-1
2-1
2-3
2-3
2-3
2-3
2-3
2-4
2-4
2-5
2-5
2. USING KSAM UTILITIES
Contents-1
BUILD . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
KEY DESCRIPTION . . . . . . . . . . . . . . .
CREATING A KSAM FILE . . . . . . . . . . . .
ERASE . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
CLEARING A KSAMFILE . . . . . . . . . . . .
PURGE . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
PURGING A KSAM FILE . . . . . . . . . . . . .
RENAME . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
RENAMING A KSAM FILE . . . . . . . . . . . .
SAVE . . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
SAVING A KSAM FILE . . . . . . . . . . . . . .
VERIFY . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
DISPLAY KSAM FILE CHARACTERISTICS . . . .
TERMINATING THE &gt;VERIFY COMMAND . . . .
DIRECTING VERIFY OUTPUT TO LINE PRINTER
USING VERIFY FOR RECOVERY . . . . . . . . .
KEYSEQ . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
VERIFY KEY SEQUENCE . . . . . . . . . . . .
KEYDUMP . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
DUMPING THE KEY FILE . . . . . . . . . . . .
DUMPING A SUBSET OF THE KEY FILE . . . . .
SORTING DUMP BY RECORD POINTER . . . . .
KEYINFO . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
REQUESTING KEY FILE INFORMATION . . . . .
RECOVERING AFTER SYSTEM FAILURE . . . .
USING KSAMUTIL IN BATCH MODE . . . . . . . .
FCOPY UTILITY . . . . . . . . . . . . . . . . .
RUNNING FCOPY . . . . . . . . . . . . . . . .
EXITING FROM FCOPY . . . . . . . . . . . . .
FCOPY FROM COMMAND . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
KSAM OPTIONS . . . . . . . . . . . . . . . . .
USING FCOPY . . . . . . . . . . . . . . . . .
FCOPY WITH KEY = OPTIONS. . . . . . . . . .
COPYING VARIABLE-LENGTH KSAM FILES . . .
:STORE AND :RESTORE COMMANDS . . . . . . .
STORE . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
USING THE :STORE COMMAND . . . . . . . . .
RESTORE . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . .
USING THE :RESTORE COMMAND . . . . . . .
Contents-2
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-7
2-8
2-13
2-15
2-18
2-18
2-18
2-19
2-19
2-19
2-20
2-20
2-20
2-22
2-22
2-22
2-23
2-23
2-23
2-25
2-25
2-25
2-26
2-26
2-27
2-29
2-29
2-31
2-33
2-34
2-35
2-35
2-36
2-38
2-41
2-43
2-43
2-43
2-44
2-44
2-44
2-46
2-49
2-51
2-54
2-54
2-54
2-55
2-56
2-56
2-57
3. USING KSAM FILES IN COBOL PROGRAMS
OVERVIEW . . . . . . . . . . . .
CALLING A KSAM PROCEDURE . .
FILETABLE PARAMETER . . . . .
FILETABLE . . . . . . . . . . . .
EXAMPLE . . . . . . . . . . .
STATUS PARAMETER . . . . . . .
STATUS . . . . . . . . . . . . .
STATUS . . . . . . . . . . . . . .
USING STATUS . . . . . . . . .
KSAM LOGICAL RECORD POINTER
SHARED ACCESS . . . . . . . .
SAMPLE KSAM FILE . . . . . .
CKCLOSE . . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKCLOSE . . . . . . . .
EXAMPLES . . . . . . . . . . .
CKDELETE . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKDELETE . . . . . . .
EXAMPLES . . . . . . . . . . .
CKERROR . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKERROR . . . . . . . .
CKLOCK . . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKLOCK . . . . . . . . .
EXAMPLES . . . . . . . . . . .
CKOPEN . . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKOPEN . . . . . . . . .
EXAMPLES . . . . . . . . . . .
CKOPENSHR . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKOPENSHR . . . . . . .
CKREAD . . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKREAD . . . . . . . . .
EXAMPLE . . . . . . . . . . .
CKREADBYKEY . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKREADBYKEY . . . . .
EXAMPLES . . . . . . . . . . .
CKREWRITE . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKREWRITE . . . . . . .
EXAMPLES . . . . . . . . . . .
CKSTART . . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING CKSTART . . . . . . . .
EXAMPLES . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-1
3-3
3-4
3-5
3-5
3-6
3-7
3-8
3-8
3-8
3-9
3-10
3-11
3-11
3-11
3-11
3-12
3-12
3-12
3-13
3-15
3-15
3-15
3-16
3-16
3-16
3-17
3-17
3-18
3-18
3-21
3-22
3-22
3-22
3-23
3-23
3-23
3-24
3-25
3-25
3-26
3-26
3-27
3-27
3-28
3-29
3-31
3-31
3-32
3-32
Contents-3
CKUNLOCK . . . . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . . . . . . .
USING CKUNLOCK . . . . . . . . . . . . . . . . . . . .
EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . .
CKWRITE . . . . . . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . . . . . . . .
USING CKWRITE . . . . . . . . . . . . . . . . . . . . .
EXAMPLES . . . . . . . . . . . . . . . . . . . . . . . .
EXAMPLES OF KSAM FILE ACCESS FROM COBOL PROGRAM
EXAMP1. SEQUENTIAL WRITE . . . . . . . . . . . . . .
EXAMP2. SEQUENTIAL READ . . . . . . . . . . . . . . .
EXAMP3. RANDOM UPDATE . . . . . . . . . . . . . . .
4. USING KSAM FILES IN SPL PROGRAMS
KSAM FILE SYSTEM INTRINSICS . . .
CALLING INTRINSICS FROM SPL . .
KSAM INTRINSIC SUMMARY . . . .
INTRINSIC FORMAT . . . . . . . .
PASSING PARAMETERS . . . . . .
OPTIONAL PARAMETERS . . . . .
KSAM RECORD POINTERS . . . . . .
SHARED ACCESS . . . . . . . . . .
FCHECK . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . .
CONDITION CODES . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . .
FCLOSE . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . .
CONDITION CODES . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . .
USING FCLOSE . . . . . . . . . . .
CLOSING A NEW KSAM FILE . . .
CLOSING AN EXISTING KSAM FILE
DELETING A KSAM FILE . . . . .
FCONTROL . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . .
CONDITION CODES . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . .
USING FCONTROL . . . . . . . . .
USING CONTROL CODE 2 . . . . .
USING CONTROL CODE 5 . . . . .
USING CONTROL CODE 6 . . . . .
USING CONTROL CODE 7 . . . . .
FERRMSG . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . .
CONDITION CODES . . . . . . . . .
USING FERRMSG . . . . . . . . . .
FFINDBYKEY . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . .
CONDITION CODES . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . .
Contents-4
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3-34
3-34
3-34
3-34
3-35
3-35
3-35
3-36
3-38
3-38
3-41
3-44
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-1
4-4
4-5
4-5
4-5
4-6
4-7
4-9
4-10
4-10
4-11
4-11
4-15
4-15
4-16
4-17
4-17
4-17
4-18
4-18
4-20
4-20
4-20
4-21
4-21
4-21
4-21
4-22
4-22
4-23
4-23
4-23
4-23
4-24
4-24
4-25
4-25
USING FFINDBYKEY . . . . . . . . .
USING APPROXIMATE KEYS . . . .
USING PARTIAL (GENERIC) KEYS . .
SHARED ACCESS . . . . . . . . . .
FFINDN . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . .
USING FFINDN . . . . . . . . . . . .
SHARED ACCESS . . . . . . . . . .
FGETINFO . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
USING FGETINFO . . . . . . . . . . .
FGETKEYINFO . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
USING FGETKEYINFO . . . . . . . .
FLOCK . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . .
USING FLOCK . . . . . . . . . . . .
FOPEN . . . . . . . . . . . . . . . . .
FUNCTIONAL RETURN . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
USING FOPEN . . . . . . . . . . . .
FOPTIONS PARAMETER . . . . . .
AOPTIONS PARAMETER . . . . . .
KEY FILE DEFINITION . . . . . . .
OPENING A NEW FILE . . . . . . . .
DECLARATIONS FOR FOPEN . . . .
DEFINING KSAMPARAM . . . . . .
CALLING FOPEN . . . . . . . . . .
OPENING AN EXISTING FILE . . . . .
OPENING FILE FOR READ ACCESS .
OPENING FILE FOR WRITE ACCESS
OPENING KSAM FILE AS MPE FILE .
OPENING FILE FOR SHARED ACCESS
FPOINT . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . .
USING FPOINT . . . . . . . . . . . .
SHARED ACCESS . . . . . . . . . .
FREAD . . . . . . . . . . . . . . . . .
FUNCTIONAL RETURN . . . . . . . .
PARAMETERS . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-25
4-25
4-25
4-26
4-29
4-29
4-29
4-29
4-29
4-30
4-31
4-31
4-34
4-34
4-38
4-38
4-38
4-38
4-41
4-41
4-41
4-42
4-42
4-44
4-44
4-44
4-47
4-47
4-47
4-49
4-50
4-54
4-54
4-54
4-57
4-58
4-59
4-61
4-61
4-62
4-63
4-63
4-63
4-63
4-64
4-64
4-65
4-65
4-65
4-65
4-66
Contents-5
USING FREAD . . . . . .
SHARED ACCESS . . . .
FREADBYKEY . . . . . . .
FUNCTIONAL RETURN . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
USING FREADBYKEY . . .
SHARED ACCESS . . . .
DUPLICATE KEYS . . .
FREADC . . . . . . . . . .
FUNCTIONAL RETURN . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
USING FREADC . . . . . .
SHARED ACCESS . . . .
FREADDIR . . . . . . . . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
SPECIAL CONSIDERATIONS
USING FREADDIR . . . . .
FREADLABEL . . . . . . . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
SPECIAL CONSIDERATIONS
USING FREADLABEL . . .
FREADSEEK . . . . . . . .
FRELATE . . . . . . . . . .
FREMOVE . . . . . . . . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
SPECIAL CONSIDERATIONS
USING FREMOVE . . . . .
SHARED ACCESS . . . .
FRENAME . . . . . . . . .
FSETMODE . . . . . . . . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
SPECIAL CONSIDERATIONS
USING FSETMODE . . . .
FSPACE . . . . . . . . . . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
SPECIAL CONSIDERATIONS
USING FSPACE . . . . . .
POINTER POSITION . .
SHARED ACCESS . . . .
FUNLOCK . . . . . . . . .
PARAMETERS . . . . . .
CONDITION CODES . . . .
SPECIAL CONSIDERATIONS
USING FUNLOCK . . . . .
Contents-6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-66
4-66
4-71
4-71
4-71
4-72
4-72
4-72
4-73
4-76
4-76
4-76
4-76
4-77
4-77
4-80
4-80
4-81
4-81
4-81
4-85
4-85
4-85
4-85
4-86
4-87
4-88
4-89
4-89
4-90
4-90
4-90
4-91
4-95
4-96
4-96
4-96
4-96
4-97
4-98
4-98
4-98
4-98
4-98
4-99
4-100
4-101
4-101
4-101
4-101
4-101
FUPDATE . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . . . . . .
USING FUPDATE . . . . . . . . . . . . . . .
SHARED ACCESS. . . . . . . . . . . . . . . .
UPDATING RECORDS WITH DUPLICATE KEYS.
FWRITE . . . . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . . . . . .
USING FWRITE . . . . . . . . . . . . . . . .
SHARED ACCESS . . . . . . . . . . . . . .
FWRITEDIR . . . . . . . . . . . . . . . . . .
FWRITELABEL . . . . . . . . . . . . . . . . .
PARAMETERS . . . . . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . . . . . .
SPECIAL CONSIDERATIONS . . . . . . . . . .
USING FWRITELABEL . . . . . . . . . . . .
HP32208 . . . . . . . . . . . . . . . . . . . . .
FUNCTIONAL RETURN . . . . . . . . . . . .
CONDITION CODES . . . . . . . . . . . . . .
USING HP32208 . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
4-102
4-102
4-102
4-103
4-103
4-103
4-104
4-108
4-108
4-109
4-109
4-109
4-109
4-112
4-113
4-113
4-113
4-113
4-113
4-115
4-115
4-115
4-115
OVERVIEW . . . . . . . . . . . . . . . . . . . . .
CALLING FILE SYSTEM INTRINSICS . . . . . . . . .
CALLING COBOL PROCEDURES . . . . . . . . . . .
CREATING A KSAM FILE WITH A CALL TO FOPEN .
DEFINING KSAMPARAM . . . . . . . . . . . . .
CALLING FOPEN . . . . . . . . . . . . . . . . .
CREATING A KSAM FILE WITH KSAMUTIL . . . . .
OPENING A KSAM FILE WITH A COBOL PROCEDURE
WRITING TO A KSAM FILE . . . . . . . . . . . . .
READING A KSAM FILE IN KEY ORDER . . . . . . .
PRIMARY KEY SEQUENCE . . . . . . . . . . . .
ALTERNATE KEY SEQUENCE . . . . . . . . . . .
RANDOM ORDER . . . . . . . . . . . . . . . . .
READING A KSAM FILE IN CHRONOLOGICAL ORDER
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5-1
5-2
5-3
5-4
5-4
5-4
5-7
5-8
5-9
5-10
5-10
5-10
5-10
5-13
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6-1
6-2
6-2
6-4
6-6
6-7
6-7
6-7
6-7
6-8
5. USING KSAM FILES IN FORTRAN PROGRAMS
6. USING KSAM FILES IN BASIC PROGRAMS
OVERVIEW . . . . . . . . . . . .
CALLING A KSAM PROCEDURE . .
OPTIONAL PARAMETERS . . . .
STATUS PARAMETER . . . . . . .
KSAM LOGICAL RECORD POINTER
SHARED ACCESS . . . . . . . .
BKCLOSE . . . . . . . . . . . . .
PARAMETERS . . . . . . . . .
USING BKCLOSE . . . . . . . .
BKDELETE . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents-7
PARAMETERS . . . .
USING BKDELETE . .
Shared Access . . . .
BKERROR . . . . . . .
PARAMETERS . . . .
USING BKERROR . . .
BKLOCK . . . . . . . .
PARAMETERS . . . .
USING BKLOCK . . . .
BKOPEN . . . . . . . .
PARAMETERS . . . .
USING BKOPEN . . . .
Access Modes . . . .
Shared Access . . . .
Dynamic Locking . . .
Sequence Checking . .
BKREAD . . . . . . . .
PARAMETERS . . . .
USING BKREAD . . . .
Shared Access . . . .
BKREADBYKEY . . . .
PARAMETERS . . . .
USING BKREADBYKEY
BKREWRITE . . . . . .
PARAMETERS . . . .
USING BKREWRITE . .
Shared Access . . . .
Duplicate Keys . . . .
BKSTART . . . . . . . .
PARAMETERS . . . .
USING BKSTART . . .
BKUNLOCK . . . . . . .
PARAMETERS . . . .
USING BKUNLOCK . .
BKVERSION . . . . . .
PARAMETERS . . . .
USING BKVERSION . .
BKWRITE . . . . . . .
PARAMETERS . . . .
USING BKWRITE . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
A. ERROR MESSAGES AND RECOVERY PROCEDURES
Contents-8
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
6-9
6-9
6-9
6-11
6-11
6-11
6-12
6-12
6-13
6-14
6-14
6-16
6-16
6-17
6-18
6-18
6-20
6-20
6-20
6-21
6-24
6-24
6-25
6-27
6-27
6-27
6-28
6-28
6-30
6-30
6-31
6-33
6-34
6-34
6-35
6-35
6-35
6-36
6-36
6-36
B. KSAM/3000 INTERNAL STRUCTURE AND TECHNIQUES
OVERVIEW . . . . . . . . . . . . . . . . . . . .
KSAM FILE STRUCTURE . . . . . . . . . . . . .
B-TREE STRUCTURE . . . . . . . . . . . . . .
ADDING OR DELETING KEYS. . . . . . . . .
KSAM KEY FILE STRUCTURE . . . . . . . . . .
CONTROL BLOCK. . . . . . . . . . . . . . .
KEY DESCRIPTOR BLOCK. . . . . . . . . . .
KEY ENTRY BLOCKS. . . . . . . . . . . . . .
RELATION OF KEY TO DATA FILE . . . . . . .
KSAM FILE SIZE . . . . . . . . . . . . . . . . .
KEY BLOCK SIZE . . . . . . . . . . . . . . . .
CALCULATING KEY BLOCK SIZE. . . . . . . .
KEY FILE SIZE . . . . . . . . . . . . . . . . .
KSAM EXTRA DATA SEGMENTS . . . . . . . . .
NUMBER OF EXTRA DATA SEGMENTS . . . . .
EXTRA DATA SEGMENT SIZE . . . . . . . . . .
NUMBER OF KEY BLOCK BUFFERS. . . . . .
EXTRA DATA SEGMENTS WITH SHARED ACCESS
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
B-1
B-1
B-2
B-3
B-6
B-6
B-6
B-8
B-10
B-12
B-12
B-13
B-14
B-18
B-18
B-19
B-21
B-22
USING KSAMUTIL AND FCOPY . . . . . . . . . . . . . . . . . . .
USING RTOKSAM . . . . . . . . . . . . . . . . . . . . . . . . . .
D-1
D-1
C. ASCII CHARACTER SET IN COLLATING SEQUENCE
D. CONVERSION TO KSAM FILES
E. RECOVERY FROM SYSTEM FAILURE
OVERVIEW . . . . . . . . . . . . . . . . . . .
END-OF-FILE ON KSAM FILES . . . . . . . . .
DATA FILE . . . . . . . . . . . . . . . . . .
KEY FILE . . . . . . . . . . . . . . . . . . .
END-OF-FILE AND THE EXTRA DATA SEGMENT
NORMAL OPERATION - FILE IS CLOSED . . .
SYSTEM FAILURE - FILE IS OPEN . . . . . . .
SITUATIONS IN WHICH RECOVERY IS REQUIRED
EXAMPLE OF FILE RECOVERY . . . . . . . .
RELOADING A KSAM FILE . . . . . . . . . . .
EXPAND KEY BLOCK BUFFER AREA . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
E-1
E-2
E-2
E-4
E-6
E-7
E-7
E-8
E-9
E-14
E-15
OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . .
CREATING KSAM FILES WITH KSAMUTIL . . . . . . . . . .
ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . .
CREATING KSAM FILES PROGRAMMATICALLY . . . . . . .
MODIFYING KSAM FILES . . . . . . . . . . . . . . . . . .
GENERIC KEYS . . . . . . . . . . . . . . . . . . . . . . .
USING FCOPY WITH NLS KSAM FILES . . . . . . . . . . .
COPYING FROM A KSAM FILE TO ANOTHER KSAM FILE .
CHANGING THE LANGUAGE ATTRIBUTE OF A KSAM FILE
MOVING NLS KSAM FILES TO PRE-NLS MPE . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
F-1
F-1
F-3
F-4
F-4
F-5
F-9
F-9
F-9
F-9
F. NATIVE LANGUAGE SUPPORT AND KSAM
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Contents-9
Figures
1-1.
2-1.
3-1.
3-2.
3-3.
3-4.
3-5.
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
4-9.
4-10.
4-11.
4-12.
4-13.
4-14.
5-1.
5-2.
5-3.
5-4.
6-1.
6-2.
6-3.
6-4.
6-5.
6-6.
6-7.
6-8.
6-9.
6-10.
6-11.
B-1.
B-2.
B-3.
B-4.
B-5.
B-6.
A Simplied View of the KSAM File Structure . . . . . . . .
EDITOR Listing of Job to be Streamed . . . . . . . . . . .
Filetable Structure . . . . . . . . . . . . . . . . . . . .
Representation of KSAMFILE Used in COBOL Examples . . .
Sequential Write Using COBOL . . . . . . . . . . . . . .
Sequential Read Using COBOL . . . . . . . . . . . . . . .
Random Update with COBOL . . . . . . . . . . . . . . .
FCLOSE Example . . . . . . . . . . . . . . . . . . . .
FFINDBYKEY Example . . . . . . . . . . . . . . . . . .
File Position with FFINDN . . . . . . . . . . . . . . . .
FGETINFO Example . . . . . . . . . . . . . . . . . . .
FOPEN Example|; Building a KSAM le . . . . . . . . . .
FOPEN Example|; Opening an Existing File . . . . . . . .
FREAD Example . . . . . . . . . . . . . . . . . . . . .
FREADBYKEY Example . . . . . . . . . . . . . . . . .
FREADC Example . . . . . . . . . . . . . . . . . . . .
FREADDIR Example . . . . . . . . . . . . . . . . . . .
FREMOVE Example . . . . . . . . . . . . . . . . . . .
File Position with FSPACE . . . . . . . . . . . . . . . .
FUPDATE Example . . . . . . . . . . . . . . . . . . .
FWRITE Example . . . . . . . . . . . . . . . . . . . .
Creating and Writing to KSAM File in FORTRAN . . . . . .
Opening KSAM File with CKOPEN . . . . . . . . . . . . .
Reading KSAM File in Key Sequence Using FORTRAN . . . .
Reading KSAM File in Chronological Sequence Using FORTRAN
Closing a KSAM File with BKCLOSE . . . . . . . . . . . .
Deleting a Record With BKDELETE . . . . . . . . . . . .
Dynamically Locking a KSAM File with BKLOCK . . . . . .
Opening KSAM File with BKOPEN . . . . . . . . . . . . .
Reading From a KSAM File with BKREAD . . . . . . . . .
Reading a Record Located by Key Value with BKREADBYKEY
Rewriting Record in KSAM File with BKREWRITE . . . . .
Positioning Pointer to Least-Valued Record with BKSTART . .
Positioning Pointer to Particular Record with BKSTART . . .
Dynamically Unlocking a KSAM File . . . . . . . . . . . .
Writing to a KSAM File with BKWRITE . . . . . . . . . .
Two-Level B-Tree Structure . . . . . . . . . . . . . . . .
Split Causes New Level in Tree . . . . . . . . . . . . . . .
Tree Growth from Two to Three Levels . . . . . . . . . . .
KSAM Key File Structure With Two Keys . . . . . . . . . .
Control Block and Key Descriptor Block . . . . . . . . . . .
Key Entry Block Structure . . . . . . . . . . . . . . . . .
Contents-10
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
1-5
2-42
3-4
3-10
3-39
3-41
3-44
4-18
4-27
4-30
4-35
4-56
4-60
4-68
4-74
4-78
4-82
4-92
4-99
4-105
4-110
5-5
5-8
5-11
5-13
6-8
6-10
6-13
6-19
6-23
6-26
6-29
6-32
6-33
6-34
6-39
B-2
B-4
B-5
B-7
B-8
B-9
B-7.
B-8.
B-9.
B-10.
B-11.
E-1.
F-1.
F-2.
F-3.
F-4.
F-5.
Data File/Key File Relation . . . . . . . . .
Formula to Determine File Space per Key . . .
Calculation of Total Key File Size with Two Keys
Extra Data Segments for Shared Access . . . .
KSAM Extra Data Segment . . . . . . . . .
KSAM File and an Extra Data Segment . . . .
KSAM File Test Program . . . . . . . . . .
Results Returned By The NLKEYCOMPARE Intrinsic
Generic Key Searches . . . . . . . . . . . .
Generic Key Searches . . . . . . . . . . . .
KSAM Recovery Procedure . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
B-11
B-16
B-17
B-19
B-20
E-6
F-2
F-5
F-7
F-8
F-9
Contents-11
Tables
2-1.
2-2.
2-3.
2-4.
2-5.
3-1.
3-2.
3-3.
3-4.
4-1.
4-2.
4-3.
4-4.
4-5.
4-6.
4-7.
4-8.
6-1.
6-2.
6-3.
6-4.
6-5.
A-1.
A-2.
A-3.
A-4.
A-5.
B-1.
B-2.
B-3.
C-1.
F-1.
F-2.
Summary of KSAM Utilities . . . . . . . . . . . . . . . . . . .
Key Types . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Equivalent to Signed Digit for NUMERIC Keys . . . . . .
FCOPY Functions with KSAM Files . . . . . . . . . . . . . . .
KSAM Options of FCOPY . . . . . . . . . . . . . . . . . . . .
KSAM Procedures for COBOL Interface . . . . . . . . . . . . . .
Valid status Parameter Character Combinations . . . . . . . . . .
Positioning the Logical Record Pointer . . . . . . . . . . . . . . .
Procedures Allowed for Input-Output Type/Access Mode Combinations
KSAM File System Intrinsics . . . . . . . . . . . . . . . . . . .
Positioning the Pointers . . . . . . . . . . . . . . . . . . . . .
FCHECK errorcode Parameter Format . . . . . . . . . . . . . .
FCLOSE disposition Parameter Bit Settings . . . . . . . . . . . .
FGETKEYINFO ksamcontrol Parameter Format . . . . . . . . . .
FOPEN foptions Parameter Format . . . . . . . . . . . . . . . .
FOPEN aoptions Parameter Format . . . . . . . . . . . . . . . .
FOPEN ksamparam Parameter Format . . . . . . . . . . . . . .
KSAM Procedures for BASIC Interface . . . . . . . . . . . . . .
Values Returned to status Parameter . . . . . . . . . . . . . . .
Positioning the Logical Record Pointer . . . . . . . . . . . . . . .
Procedures Allowed by BKOPEN access Parameter . . . . . . . . .
Relation of exclusive Parameter to access Parameter . . . . . . . .
File System Error Codes . . . . . . . . . . . . . . . . . . . . .
COBOL Status Parameter Return Values . . . . . . . . . . . . .
BASIC Status Parameter Return Values . . . . . . . . . . . . . .
KSAMUTIL Error Codes and Messages . . . . . . . . . . . . . .
FCOPY Warning and Error Messages . . . . . . . . . . . . . . .
Number of Key Block Buers Assigned by Default . . . . . . . . .
Pointer Dependence . . . . . . . . . . . . . . . . . . . . . . .
Record Pointer Summary . . . . . . . . . . . . . . . . . . . .
ASCII Characters in Sequence . . . . . . . . . . . . . . . . . .
KSAMUTIL Error Messages . . . . . . . . . . . . . . . . . . .
KSAM File System Error Messages . . . . . . . . . . . . . . . .
Contents-12
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2-2
2-14
2-15
2-45
2-46
3-2
3-6
3-9
3-19
4-2
4-8
4-11
4-16
4-39
4-47
4-49
4-51
6-3
6-4
6-6
6-17
6-17
A-2
A-6
A-8
A-10
A-18
B-21
B-23
B-24
C-2
F-3
F-4
1
INTRODUCING KSAM/3000
OVERVIEW
The Keyed Sequential Access Method (KSAM) is a method of organizing records in a le
according to the content of key elds within each record. As implemented for the HP 3000
computer system, KSAM/3000 is similar to and competitive with other indexed sequential
access methods.
Every record in a KSAM le contains a primary key eld whose contents determine the
primary logical sequence of records in the le. Other key elds can also be dened so that the
le can be sequenced in alternate orders. The order in which records are physically written to
the le, the chronological order, can be the same as the primary key sequence or it can be
unrelated to any logical sequence.
KSAM/3000 les can be accessed by programs written in any of these languages:
RPG/3000
COBOL II/3000
COBOL/3000
SPL/3000
FORTRAN/3000
BASIC/3000
KSAM/3000 les can be copied, listed, and otherwise manipulated with the utility programs:
FCOPY/3000
KSAMUTIL
FILE STRUCTURE
A KSAM/3000 le is organized into two distinct MPE les, a data le and a key le. The key
le contains only key entries, the data le only data. Each record in the data le contains at
least one item that is designated as a key. The value of each key is duplicated in the key le
where all keys are ordered in ascending sequence. This organization allows records in the data
le to be stored in any order since the key le maintains the logical order of records according
to key value.
Although it is not necessary to understand KSAM le structure in order to use a KSAM le,
you may want to refer to appendix B for a detailed discussion of the relation between data
and key les and the structure of the key le.
Note
Each open KSAM le uses three le numbers; two for the data and keys and
one for internal maintenance. The maximum number of KSAM les that can
be opened for a process depends upon the stack of that process.
INTRODUCING KSAM/3000
1-1
FILE ACCESS
Although separate in fact, the two les that comprise a KSAM le are treated as one le by
the procedures that reference the le. The data le is the only le directly referenced by a
user; the key le is updated by the system to reect any changes to the data le and is not
directly accessed by the user. Thus , from the user's point of view , accessing a KSAM le is
very similar to accessing any other MPE le .
KSAM/3000 provides the following ways to store and retrieve data:
You can write records in logical sequence determined by primary key value or you can write
records without regard to key sequence.
You can read records in logical sequence determined by either the primary or an alternate
key value.
You can read a record selected at random by the value of its primary or alternate keys.
You can read records in the order they were written, that is, in chronological sequence,
unless the program is written in COBOL or BASIC.
You can read a record selected by the value of its chronological record number, unless the
program is written in COBOL or BASIC.
You can update all the contents of an existing record including the contents of the primary
key eld.
You can position to a record in the le according to its key value, its chronological record
number, or its record number in key sequence.
Note
KSAM les are sequenced in ascending order only, not in descending order.
Character keys are ordered by the ASCII collating sequence where numbers
precede letters, not in the EBCDIC sequence where letters precede numbers.
Numeric keys are ordered in algebraic order.
KSAM/3000 FEATURES
KSAM/3000 provides a number of features beyond the standard indexed sequential access
method. These include:
Multiple Keys
Duplicate Key Values
Retrieval by Generic Key
Retrieval by Approximate Match
Fixed or Variable Length Data Records
1-2
INTRODUCING KSAM/3000
MULTIPLE KEYS
Each data record can contain from one to sixteen keys. Of these keys, one is required, called
the primary key; any others are alternate keys. For example, in an employee record, the
primary key could be the employee's social security number; alternate keys might be the
employee's name, phone number, or zip code. The values in these key elds determine the
orders in which data records are sequenced.
PRIMARY KEY. One eld in each data record is dened to contain the primary key. The
value in this eld determines the primary sequence of records in the data le. Records
are sequenced according to this primary key unless sequencing by an alternate key or in
chronological order is specically requested.
ALTERNATE KEYS. Other elds within each data record can be designated as alernate keys
to be used for alternate sequencing of records. Up to 15 alternate keys can be designated
for each record, however, each additional alernate key adds to the overhead and can aect
performance when accessing and maintaining a le. The le can be sequenced in a dierent
order for each alternate key dened for the le.
Note that alternate keys bear no hierarchical relation to each other or to the primary key.
Each key is ordered in sequence by its value and type with no relation to other keys. In
KSAM, sequence always means ascending sequence according to the ASCII collating sequence,
(refer to appendix C.)
DUPLICATE KEYS
Sometimes it is essential that key values be unique (for example, a social security number),
and at other times duplicate key values should be allowed (for example, a zip code). To
provide for both cases, KSAM allows you to declare that any key may have a duplicate value
while disallowing duplicate key values as the default condition. Allowing or disallowing
duplicate key values applies to both primary and alternate keys. Duplicates can be allowed for
one or more keys while being disallowed for other keys.
Note
Duplicate keys can greatly increase the time required to load or access a
record with a duplicated key value. This is particularly true when there are
a large number of duplicated key values in a large le. As a result, duplicate
keys should only be used when other methods are not practical. For example,
you should not make a key of an item that can only have two values, as
\MALE&quot; or \FEMALE.&quot;
GENERIC KEYS
During retrieval by key value you can choose to use part of a key rather than the entire key.
Called generic keys, such partial keys allow you to retrieve a set of records whose key values
dier in their entirety but share a common value at the beginning. Generic keys must begin
at the rst character of the dened key held and be shorter, not longer, than the dened
key length; also, the key type must be BYTE, INTEGER, or DOUBLE. Suppose a key eld
containing a zip code is dened as ve characters long. By specifying only the rst three
characters for retrieval it is possible to read all records whose zip code begins with a particular
group of numbers.
INTRODUCING KSAM/3000
1-3
Note
Generic keys cannot be used when accessing KSAM les through RPG.
APPROXIMATE MATCH
When retrieving by key value, you can specify that the key you are looking for have a value
that exactly matches a specied value, or you can specify that it bear a certain relation to
a specied value. The choices are: equal to, equal to or greater than, or greater than. The
last two relations let you search for an approximate match. For example, you can retrieve all
records with a date greater than or equal to a given date:
DATA RECORD FORMAT
Every key entry in the key le contains, in addition to the key value, a pointer to the
corresponding data record in the data le. The data records can be either xed length or
variable length. If they are xed, the data record pointer species a record number relative to
the beginning of the le. If the records are variable length, then the pointer indicates the start
of the data record as a word oset from the beginning of the le.
1-4
INTRODUCING KSAM/3000
Figure 1-1. A Simplified View of the KSAM File Structure
HOW TO USE KSAM FILES
Although a KSAM le consists physically of two separate les, a data and a key le, it is
treated as one le for most purposes. For example, reading from a KSAM le in primary key
sequence is equivalent to reading sequentially from a non-KSAM le. Similarly, creating the
data le portion of a KSAM le is equivalent to creating a non-KSAM le.
INTRODUCING KSAM/3000
1-5
CREATING A KSAM FILE
A KSAM le can be created in two ways: interactively with the &gt; BUILD command of the
utility program KSAMUTIL, or programmatically with a call to the MPE le system intrinsic
FOPEN. (A COBOL or BASIC programmer can create a KSAM le only through the &gt;
BUILD command, not FOPEN.) Whether &gt; BUILD or FOPEN is used, le creation consists
of creating a data le in very much the same way you would create any HP 3000 le. The
name assigned to the data le is the name by which the KSAM le is known. Then, as part of
the le creation procedure, a key le is created and each of its keys dened by type, location
in the data record, and size. If duplicate key values are to be allowed, this is specied as part
of the key denition.
WRITING RECORDS TO A KSAM FILE
You can write records to a KSAM le in either of two ways. In one, records are written in any
order regardless of primary key values. In the other, records are written in order according to
the value of the primary key in each record. In the rst case, the chronological sequence in
which records are written diers from the logical record sequence determined by primary key.
In the second, the chronological and logical record sequence is the same. When you specify
that records are to be written in primary key sequence, KSAM checks to make sure that this
sequence is followed and issues an error message if not.
You can specify that the le be cleared of any existing records before writing new records to
the le, or you can write records following any previously written records. The choice is made
when you open the le.
In any case, when records are written to the data le, the key le structure is modied
automatically in order to place all keys in the new record into their proper sequence.
Records cannot be written directly to a KSAM le according to a relative record number.
RETRIEVING RECORDS FROM A KSAM FILE
Records can be retrieved in a variety of ways:
Sequentially in the order determined by key value; either the primary or an alternate key
can be selected to determine the order.
At random according to the value of a specied key; either the primary or an alternate key
can be selected for the matching process.
Chronologically in the order the data records were written.*
At random by chronological record number.*
*The starred access methods are not available to a COBOL or BASIC programmer.
Whenever duplicate keys are used and retrieval is by key value, the rst key encountered
determines the record read. When generic keys are used, the smallest key value is selected
rst. Again, if there are duplicates in generic key values, the rst key encountered is selected.
1-6
INTRODUCING KSAM/3000
UPDATING RECORDS IN A KSAM FILE
You can change the contents of an existing record by program calls that read the record into
storage where you update it and then write it back to the le. The updated record overwrites
the existing record in its current location if the new record and the old record are the same
length. Otherwise, the new record is written to the end of the le and the old record is
marked for deletion.
POSITIONING IN A KSAM FILE
Record pointers can be positioned:
To a record determined by key value using either the primary or an alternate key.
To a record determined by its record number relative to the rst record in key sequence,
where the key is either primary or an alternate.**
To a record determined by its record number relative to the rst record written to the le
(chronological sequence).**
**Not available in COBOL or BASIC program.
DELETING RECORDS FROM A KSAM FILE
Records are not physically deleted from the data le. In order to delete a record, you call a
procedure that marks the record for deletion by writing a delete code (octal 177777) in the
rst word of the record. Any subsequent access to the le skips such records, treating them
as if they were not there. In addition, the key le is automatically reorganized so that keys in
the deleted record are no longer in the path that denes the key sequence. The space in the
key le created by the deleted entries is reused. However, to maintain the le's chronological
order, the space occupied by deleted entries in the data le is not reused.
Because data records are not physically deleted, you can reconstruct deleted records by
copying the data le using FCOPY with the NOKSAM and SUBSET options. In this way,
you can restore les in which you deleted, records by mistake.
To prevent records from being deleted by mistake, do not place binary or numeric data that
could result in octal 177777 (the deletion code) in the rst word of a data record. The best
practice is to always keep the rst word of each data record blank. Doing so helps you identify
deleted records and prevents KSAM from writing delete codes over recoverable data.
REORGANIZING A KSAM FILE
If many records have been deleted, thereby using a great deal of physical space in the le,
you can compact the le by using FCOPY/3000 to copy only the active records, those not
tagged for deletion, to a new KSAM le. You can also use FCOPY to delete, add, or change
alternate keys by copying the le to a new KSANI le with a dierent key denition. When
the key denition is dierent, you must rst create the new le with the &gt;BUILD command
of KSAMUTIL.
INTRODUCING KSAM/3000
1-7
SHARED ACCESS TO KSAM FILES
Several programs can access the same KSAM le simultaneously. Shared access is assumed
when the le is only being read, exclusive access is assumed when the le is being written to
or updated. Thus, you can choose to make all your access shared or all exclusive. Note that
shared access uses more memory than exclusive access since each open KSAM le requires a
separate extra data segment.
When access to the le is shared, it is each user's responsibility to dynamically lock the le
before changing it in any way. The le must be locked before any records in the le are
written, updated, or deleted, and then unlocked immediately after such action. By requiring
this action, the system makes sure that the most recent values are brought into each user's
buer at each access. Any call to read or position to a record for sake of subsequent access
should be within the locked portion of code that includes the actual update call.
(Refer to appendix E for a full discussion of shared access.)
RECOVERY AND ANALYSIS OF KSAM FILES
The utility program KSAMUTIL provides several commands that can be used to analyze
KSAM les. These commands allow you to check any key sequence to obtain a formatted
dump of the key le, and in the event of a system failure, to check key le structural damage,
determine whether key values are missing, and recover key values and data records by
resetting end-of-le pointers. The command, KEYINFO, that performs these recovery
functions must be run in case of a system failure while a KSAM le is open. (A full discussion
of these commands is found in section II; also refer to appendix E for a discussion of KSAM
le recovery iii the event of system failure.)
USING FILE EQUATIONS WITH KSAM FILES
KSAM opens the key and data le allowing le equations for both. KSAM accesses the les
in a very specic way. Since le equations will override any aoptions that KSAM uses, it
is possible to specify access parameters on the le equation which will cause unpredictable
results. The following should not be used on a le equation which references a KSAM le:
BUF=numbers of buffers
NOMR
WAIT
Refer to \Dynamic Locking&quot; and \Exclusive Access&quot; in Table 4-7, and the section on using
FCOPY to add data to an existing le for further information.
1-8
INTRODUCING KSAM/3000
HOW TO USE THIS MANUAL
There are some dierences in the way in which KSAM les can be accessed depending on the
language in which you are programming. You should read the paragraphs below appropriate
to your programming language and then turn to the last paragraph of this section, For All
Programmers.
RPG PROGRAMMER
This manual does not describe the code required to access a KSAM le using RPG. For this
information, you must refer to:
RPG/3000 Compiler Applications &amp; Reference Manual
COBOL II PROGRAMMER
If you are programming in COBOL II, you can access KSAM les through COBOL II's
Indexed I/O Module. To do so you declare a le's organization to be INDEXED. Refer to the
COBOL II Reference Manual (32233-90001) for documentation of this procedure.
You can optionally access KSAM les using MPE Intrinsics (Section IV) and COBOL
procedures (Section III).It is recommended that you use COBOL procedures only when
compatibility with COBOL is required.
COBOL PROGRAMMER
If you are programming in COBOL, you should read section II in order to learn how to:
Create, purge, rename, clear the contents, display the status of, or save a KSAM le. These
functions are provided by the KSAMUTIL program.
Copy a KSAM le to another KSAM le in any key order.
Display the contents of a KSAM le in any key order on the standard list device. These
functions are provided by the FCOPY program.
You should read section III in order to learn how to:
Open and close the KSAM le.
Open the le for shared access and dynamic locking.
Write the records to the le in sequential key order or in random order.
Read records from the le in sequential order by key value or at random by key value.
Change the key in preparation for a sequential read.
Rewrite or delete an existing record.
Dynamically lock or unlock the le.
Note the following limitations for COBOL:
You cannot programmatically create a KSAM le. You must use the &gt; BUILD command of
the KSAMUTIL utility program in order to create the le.
You cannot read a KSAM le in chronological sequence. You can, however, use FCOPY to
copy the le to a non-KSAM le and then read it in chronological sequence.
INTRODUCING KSAM/3000
1-9
For ANSII standard COBOL, only alternate keys, not primary keys, can be duplicated.
SPL PROGRAMMER
If you are programming in SPL, you should read section II in order to learn how to:
Create, purge, rename, clear the contents, display the status of, or save a KSAM le. These
functions are provided by KSAMUTIL.
Copy a KSAM le to another KSAM le in any key order.
Display the contents of a KSAM le in any key order on the standard list device. These
functions are provided by FCOPY.
You may skip sections III, V, and VI, which apply to programming in COBOL, FORTRAN,
and BASIC respectively. You should read section IV to learn how to:
Create, open, and close a KSAM le.
Write records to the le in sequential primary key order or in random order.
Read records from the le in primary or altenate key order or in chronological order.
Read records at random by key value.
Read records directly according to a record number relative to the rst chronological record.
Position record pointer forward or backward a specied number of records in any specied
key sequence.
Position to a record dened by key value.
Position to a relative record number in key sequence or in chronological sequence.
Update or delete an existing record.
Request access and status information on the KSAM le.
Verify that input/output is completed, and verify that critical output is complete.
Dynamically lock or unlock the le.
Write or read user labels.
In general, SPL programmers can use all the le system intrinsics provided for HP 3000
standard les with the following exceptions:
A KSAM le cannot be renamed with the FRENAME intrinsic.
A KSAM le cannot be positioned to a relative record number with FREADSEEK. (Similar
functions are performed by the KSAM intrinsics FFINDBYKEY and FFINDN).
A record cannot be written to a KSAM le according to relative record number with
FWRITEDIR.
The relation between two les (interactive or duplicative) cannot be determined with
FRELATE.
1-10
INTRODUCING KSAM/3000
FORTRAN PROGRAMMER
If you are programming in FORTRAN, you should read section II in order to learn how to:
Create, purge, rename, clear the contents, display the status of, or save a KSAM le using
KSAMUTIL.
Copy a KSAM le to another KSAM le in any key order with FCOPY.
Display the contents of a KSAM le in any key order on the standard list device using
FCOPY.
As a FORTRAN programmer can call either the COBOL procedures described in section III
(and summarized above) or the intrinsics described in section IV (also summarized above).
You should, therefore, read both these sections. Depending on your program requirements,
you can then choose to use either the COBOL procedures or the le system intrinsics. Since
these methods dier signicantly in how the le is created and accessed, you should not
attempt to combine calls to COBOL procedures with calls to the le system intrinsics. In
general, the intrinsics provide more capabilities than the COBOL procedures.
You should also read section V, which illustrates, by means of annotated examples, how to
access a KSAM le through FORTRAN calls to the le system intrinsics. The examples
illustrate:
Programmatically creating a KSAM le.
Writing records to a new KSAM le.
Reading the records in sequential order by primary key value and then by alternate key
value.
Reading the records in chronological order.
BASIC PROGRAMMER
As a BASIC programmer you should read section II in order to learn how to:
Create, purge, rename, clear the contents, display the status of, or save a KSAM le using
KSAMUTIL.
Copy a KSAM le to another KSAM le in any key order with FCOPY.
Display the contents of a KSAM le in any key order on the standard list device using
FCOPY.
Since a BASIC programmer, like the COBOL programmer, cannot create a KSAM le
programmatically, it is especially important to note how les are created with the BUILD
command of program KSAMUTIL. Note also that BASIC programs cannot read a KSAM
le in chronological sequence. You can, however, use FCOPY to copy the data le to a
non-KSAM le and then read it in chronological sequence.
You can skip sections III, IV, and V, which apply to COBOL, SPL, and FORTRAN
programming respectively, and read section VI, which describes the BASIC procedures to
access KSAM les. These procedures enable you to:
Open and close a KSAM le.
Write records to a KSAM le in primary key or in random order.
Read records from the le in sequential order by key value, or at random by key value.
INTRODUCING KSAM/3000
1-11
Change the key in preparation for a sequential read.
Rewrite or delete an existing record.
Dynamically lock and then unlock the le during shared access.
ALL PROGRAMMERS
Programmers using any of the languages that access KSAM les will probably need to refer
to appendix A. This appendix contains an explanation of the error messages, condition codes,
and status returns that can result from le access.
Appendix B describes the internal structure of KSAM les. It illustrates how key entries are
stored in a special B-Tree structure, and how KSAM le size is determined. It also explains
how les are accessed through the extra data segments allocated to each open le. This
appendix provides information for the sophisticated programmer who wants to know how
KSAM les operate in order to improve performance. For the average user, the information in
appendix B is not needed in order to create and use KSAM les.
Appendix C provides the ASCII collating sequence used by KSAM /3000 to determine
character key sequence; (numeric key sequence is in algebraic order). Note that the KSAM
key sequence is in ascending order only, the order in which the ASCII characters are shown in
appendix C.
Appendix D provides instructions that will help you convert your les to KSAM /3000 les. It
tells you how to convert any serially accessible le to a KSAM le. If you are already using
INDEX les, it describes use of the conversion program RTOKSAM for converting from
INDEX to KSAM. Note that INDEX les were previously called RSAM les.
Appendix E describes the recovery procedures to be used if the system fails when KSAM les
are open. It explains what happens when a le is closed normally as opposed to what happens
when a system failure prevents normal closing, and then tells the user exactly what to do
when a system failure aects open KSAM les.
1-12
INTRODUCING KSAM/3000
2
USING KSAM UTILITIES
USING KSAM UTILITIES
A pair of utility programs and a set of commands allow you to create and manipulate KSAM
les.
OVERVIEW
The program KSAMUTIL provides MPE capabilities that allow you to manipulate KSAM
les. With KSAMUTIL commands, you can create a KSAM le, rename both the data and
key les, save a temporary le as a permanent le, clear all data from a le, purge a le, and
verify the contents and access history of an existing le.
The HP 3000 le copier, FCOPY, is adapted to copy KSAM les. FCOPY allows you to
copy from a KSAM le to another le (KSAM or non-KSAM), in primary or alternate key
sequence; to copy an entire le or a subset of a le, and to copy either the data or key le.
The MPE commands :STORE and :RESTORE can be used with KSAM les to transfer the
les from disc to magnetic tape and vice versa.
The utility functions that can be performed on KSAM les are summarized in Table 2-1.
Both KSAMUTIL and FCOPY are programs resident in the system library that can be
executed with the MPE :RUN command. When run in a session, each program responds
by issuing a greater-than (&gt;) prompt. You may then enter commands to control further
operation of the program. Both programs may be operated in batch mode as well as in a
session. In batch mode, the greater-than prompt is not required. :STORE and :RESTORE
are commands directed to the MPE command interpreter and can be included in either a job
or a session.
USING KSAM UTILITIES
2-1
Table 2-1. Summary of KSAM Utilities
UTILITY
KSAMUTIL
FCOPY
OPTION/COMMAND
FUNCTION
&gt;BUILD or &gt;B
Create KSAM le consisting of a data le and key
le.
&gt;ERASE
Clear contents of KSAM data le and reset key
le pointers.
&gt;PURGE
Remove KSAM le from system.
&gt;RENAME or &gt;R
Change name of KSAM key or data le to a new
name.
&gt;SAVE or &gt;S
Save session/job temporary KSAM le as a
permanent le.
&gt;VERIFY or &gt;V
Display information on current status of data and
keys in KSAM le.
&gt;HELP or &gt;H
Request description of KSAMUTIL commands.
&gt;EXIT or &gt;E
Exit from KSAMUTIL program.
&gt;KEYSEQ or &gt;KS
Check the sequence of any key (primary or
alternate) in key le.
&gt;KEYDUMP or &gt;KD
Display a formatted, structural key le dump.
&gt;KEYINFO or &gt;K1
Display information on current status of key le;
in case of system failure, attempt recovery.
;KEY=keylocation
Copy KSAM le in key sequence by a key specied
by its beginning location in record.
;NOKSAM
Copy contents of key or data le in consecutive
(physical) order.
If both these parameters are omitted, the data le
is copied in sequence by primary key; the key le
is established with all links maintained. Other
FCOPY options apply to KSAM les with minor
exceptions (refer to Table 2-4).
MPE
2-2
:STORE datale, keyle
Store KSAM data and key les from disc to
magnetic tape.
:RESTORE datale, keyle
Restore KSAM data and key les from magnetic tape.
USING KSAM UTILITIES
KSAMUTIL UTILITY
KSAMUTIL provides a number of capabilities, among which is the essential capability
to create KSAM les. For a COBOL, BASIC, or RPG programmer, KSAM les can be
created only through the BUILD command of the program KSAMUTIL. Although SPL and
FORTRAN programmers can create KSAM les with the FOPEN intrinsic (described in
section IV), the BUILD command may still provide these users with the simplest method for
creating a KSAM le.
RUNNING KSAMUTIL
To pass control to KSAMUTlL, use the MPE command:
:RUN KSAMUTIL.PUB.SYS
In a session, KSAMUTIL prompts with the greater-than sign (&gt;) in column 1 to which you
respond with the command you want to execute. In a job, you enter the command in column
1 of the record following the RUN command. No prompt character precedes the KSAMUTIL
commands in batch mode.
Refer to Table 2-1 for a list of the KSAMUTIL commands and their functions.
COMMAND ABBREVIATIONS.
All KSAMUTIL commands, except ERASE and PURGE, can be abbreviated. Most
abbreviations allow the rst letter of the command name. For example, &gt;BUILD can be
specied as &gt;B, and &gt;EXIT can be specied as &gt;E. The three command names beginning
with K (&gt;KEYDUMP, &gt;KEYSEQ, and &gt;KEYINFO) are abbreviated to two letters to
distinguish one from the other. As shown in Table 2-1, these abbreviations are, respectively,
&gt;KD, &gt;KS, and &gt;KI.
RUNNING MPE COMMANDS FROM KSAMUTIL.
Once you are running KSAMUTIL and you want to use an MPE command, you need not
exit from KSAMUTIL and return to MPE; simply type the colon prompt (:) following the
KSAMUTIL prompt (&gt;) and then enter the MPE command. For instance, if you want to list
the les in your account and group from KSAMUTIL, enter the LISTF command as shown:
&gt;:LISTF
OPTION TO LIST DISPLAYS ON LINE PRINTER.
Four KSAMUTIL commands display le information; these are VERIFY, KEYDUMP,
KEYSEQ, and KEYINFO. Each of these has an option that allows you to list the information
on a line printer rather than display it on your terminal. If you include the keyword
OFFLINE as an option in any of these commands, the requested information is sent to
the line printer. If you want the list sent to a particular line printer, you can use a :FILE
command naming the KSAM list le \KSAMLIST&quot; as the formal designator. For example,
suppose you are running KSAMUTIL and want to list the current information on a KSAM le
and you want this information listed on a particular line printer:
&gt;:FILE KSAMLIST; DEV=SLOWLP &lt;---&gt;VERIFY MYFILE; OFFLINE&lt;--------WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)? 4
select particular line printer
specify output to go to an oine device
request all information||USING KSAM UTILITIES
2-3
The resulting output is sent to the line printer identied as SLOWLP.
OPTIONAL PARAMETERS.
Wherever a command parameter is shown with brackets, [], that parameter can be omitted.
For certain commands, SAVE, VERIFY, KEYDUMP, KEYSEQ, and KEYINFO, the
lereference parameter is optional if no other parameters are specied. When this parameter
is omitted, it assumes a prior command has specied a lereference and it uses the last
lereference to identify the selected le. For example, assume you use the VERIFY command
twice in a row, once to list the requested output on the line printer, and then to display it at
your terminal. To do this, you can use the following command sequence:
:RUN KSAMUTIL
&gt;VERIFY MYFILE; OFFLINE
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?4
(output is sent to the line printer)
&gt;V&lt;------------------------------ previous le reference to MYFILE is
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)? 4
assumed
(output appears at your terminal)
Note that you cannot issue these commands in reverse order because the lereference
parameter can be omitted only if there are no other parameters. Thus, it is not legal to use
command &gt;VERIFY MYFILE followed by &gt;VERIFY; OFFLINE.
EXITING FROM KSAMUTIL
When you have nished using KSAMUTIL in a session, you can return to the MPE operating
system with the command:
&gt;EXIT or &gt;E
In a batch job, the EXIT command is specied in column 1 of the record that terminates the
program; the greater-than sign is not included. The keyword EXIT can be abbreviated as E.
2-4
USING KSAM UTILITIES
HELP
Requests help using KSAMUTIL
HELP
&gt;
H
This command returns a summary description of each of the KSAMUTIL commands when
entered at a terminal. The keyword \HELP&quot; can be abbreviated to \H&quot; .
REQUESTING HELP
The HELP command lists all the valid KSAMUTIL commands and then asks if you need
information on a particular command. When you enter the name of a KSAMUTIL command,
HELP displays the command syntax. HELP is terminated by entering N in response to the
prompt MORE (Y/N)?.
The following example illustrates the HELP command.
&gt;H
VALID COMMANDS ARE:
BUILD[B].......TO CREATE A FILE
ERASE..........TO RESET A FILE TO INITIAL CONDITIONS
EXIT[E]........TO LEAVE THIS ROUTINE
PURGE..........TO DELETE A FILE
RENAME[R]......TO RENAME A FILE
SAVE[S]........TO RETAIN A TEMPORARY FILE
VERIFY[V]......TO DESCRIBE FILE CHARACTERISTICS
KEYINFO[KI]....TO OBTAIN KEY FILE INFORMATIONS
KEYDUMB[KD]....TO OBTAIN FORMATTED KEY FILE STRUCTURAL DUMP
KEYSEQ[KS].....TO CHECK THE SEQUENCE OF KEY FILE
MORE (Y/N)?Y
ENTER COMMAND NAME: B
BUILD &lt;DATAFILEREF&gt;
[;DEV= &lt;DEVICE&gt;]
[;DISC=[ &lt;NUMREC&gt;][, &lt;NUMEXTENTS&gt;][, &lt;INITAL-OC&gt;]]]
(REC=[ &lt;RECSIZE&gt;][,[ &lt;BLOCKFACTOP&gt;][,[F \V][,BINARY \,ASCII]]]]
[;TEMP]
[;CODE= &lt;FILECODE&gt;]
;KEY= &lt;TYPE&gt;, &lt;POSITION&gt;[,[ &lt;LENGTH&gt;][,[ &lt;BLOCKING&gt;][,DUPLICATE]]]
[,RDUP]
[;KEY= &lt;TYPE&gt;, &lt;POSITION&gt;[,[ &lt;LENGTH&gt;][,[ &lt;BLOCKING&gt;][,DUPLICATE]]] ...]
[,RDUP]]]...]
[;LABELS= &lt;NUMBERLABELS&gt;]
[;FIRSTREC=0\-1]
[;KEYDEV= &lt;DEVICE&gt;]
;KEYFILE =FILEREFERENCE2
[;KEYENTPIES= &lt;NUMBER&gt;]
&lt;TYPE&gt;::=B\D\I\R\L\N\P\*
MORE (Y/N)?Y
ENTER COMMAND NAME: E
EXIT
MORE (Y/N)?Y
ENTER COMMAND NAME: ERASE
USING KSAM UTILITIES
2-5
ERASE &lt;FTLEREFERENCE&gt;
MORE (Y/N)?Y
ENTER COMMAND NAME: PURGE
PURGE &lt;FILEREFERENCE&gt;[,TEMP]
MORE (Y/N)?Y
ENTER COMMAND NAME: R
RENAME &lt;OLDFILEREF&gt;, &lt;NEWFILEREF&gt;[,TEMP]
MORE (Y/N)?Y
ENTER COMMAND NAME: S
SAVE [ &lt;TEMPFILEREF&gt;]
MORE (Y/N)?Y
ENTER COMMAND NAME: V
VERIFY [ &lt;FILFREFERENCE&gt;]
[;OFFLINE]
[;NOCHECK]
MORE (Y/N)?Y
ENTER COMMAND NAME: KD
KEYDUMP [ &lt;FILEREFERENCE&gt;]
[;SEQ= &lt;KEYSEQUENCE&gt;]
[;SUBSET=[ [ minus;] &lt;POSITION&gt;][, &lt;NUMBER&gt;]]
I
I
[&quot;CHAR-STRING&quot;]
[;FILE = &lt;FILEREFERENCE1&gt;]
I
I
[;OFFLINE
]
[;SORT]
MORE (Y/N)?Y
ENTER COMMAND NAME: KI
KEYINFO [ &lt;FILEREFERENCE&gt;]
[;OFFLINE]
[;RECOVER]
MORE (Y/N)?Y
ENTER COMMAND NAME: KS
KEYSEQ [ &lt;FILEREFERENCE&gt;]
[;SEQ= &lt;KEYSEQENCE&gt;]
(;OFFLINE]
[;NOLIST]
MORE (Y/N)?N &lt;---------------&gt;E
END OF PROGRAM
2-6
USING KSAM UTILITIES
terminate HELP display
BUILD
Creates a KSAM le.
&gt; B
BUILD lereference 1
[;REC=[recsize] [,[blockfactor] [,F ,BINARY
V ,ASCII] ] ]
[;TEMP]
[;DEV=device]
[;CODE=lecode]
[;DISC=[numrec] [,[numextents] [,initialloc] ] ]
;KEYENTITY =lereference 2
,DUPLICATE
,DUP
;KEY=keytype, keylocation, keysize[,[keyblocking] ,RDUPLICATE
,RDUP
,DUPLICATE
;KEY=keytype, keylocation, keysize[,[keyblocking] ,DUP
,RDUPLICATE
,RDUP
[;KEYENTRIES=numentries]
[;LABELS=numlabels]
[;KEYDEV=device]
[;FIRSTREC=recnum]
[;LANG=parameter]
[;NODUPLOCKS]
The BUILD command of the KSAMUTIL utility program is used to create a KSAM le
and allocate the le to a mass storage device. Although this command is similar to the
MPE :BUILD command, it has been modied for KSAM les. You can specify the BUILD
command with the abbreviation, B.
Note
You cannot create a KSAM le with the MPE :BUILD command.
If you are programming in COBOL, BASIC, or RPG, you must use the KSAMUTIL BUILD
command to create a KSAM le; in SPL or FORTRAN, you can create a KSAM le either
with the BUILD command or with the FOPEN intrinsic (described in section IV).
USING KSAM UTILITIES
2-7
PARAMETERS
lereference1
Actual le designator. This is the name that identies the KSAM le
(both data and key les) and also identies the data le when specied
independently of the key le. It has the form:
lename [/lockword] [.groupname [.accountname] ]
All four sub-parameters are names that contain from 1 to 8 alphanumeric
characters, beginning with a letter.
Note
If specied, account name must be that of your log-on account; you cannot
create a le in another account .
If le has no lockword and belongs to your log-on group, only lename is
necessary. You cannot backreference les.
REC=recsize
(Required parameter.)
Size of logical records in le. If a positive number, this represents words;
characters are represented by a negative number, If the records are variable
length, recsize indicates the maximum length allowed for a logical record.
Block size is determined by multiplying the specied recsize by blockfactor .
For binary les or ASCII les with xed-length records, an odd character
count is rounded up to the next highest even number to insure that the
record starts on a word boundary. The rounded number should be used in
calculating block size since a block always starts on a word boundary.
(Optional parameter.)
blockfactor
F
V
2-8
Default: The congured record size of the particular device is used when recsize
is omitted; for disc les, the value used is 256 characters or 128 words .
An integer equal to the number of logical data records in each block. This
integer should result in a data block size smaller than 4096 (4K) words. The
blockfactor is used to calculate the buer size established for transfer of data
to and from the le.
For xed-length records, blockfactor is the actual number of records in a
block. For variable-length records, blockfactor is a multiplier used with recsize
to calculate block size:
block size = ( (recsize +1) * blockfactor )+1
The calculation is performed in words, not characters.
(Optional parameter.)
Default: calculated by dividing the specied recsize into the congured block
size; the result is rounded down to an integer never less than 1.
Data le contains xed-length records.
(Optional parameter.)
Data le contains variable-length records. Since KSAM performs its own
blocking and deblocking, a KSAM data le specied as variablelength is
USING KSAM UTILITIES
treated by MPE as a le with xed-length records, each record the size of
a KSAM block (refer to blockfactor above for calculation of block size).
Although the MPE LISTF command shows the data le as xed-length, the
KSAMUTIL VERIFY command, option 3, shows DATA FIXED as FALSE
when the le is a variable-length KSAM le.
(Optional parameter.)
BINARY
ASCII
TEMP
DEV=device
CODE=
lecode
Default: If both F and V are omitted, records are xed-length .
Data le contains binary-coded records.
(Optional parameter.)
Data le contains ASCII-coded records.
(Optional parameters.)
Default: If both BINARY and ASCH are omitted, records are binary .
File is created as a session/job temporary le; when the session or job
terminates, the le is deleted from the session/job temporary le directory.
(Optional parameter.)
Default: If TEMP is omitted, le is declared permanent and is saved in the
system le domain .
device designates the device on which the data le resides. (The key le
device is specied in the KEYDEV parameter.) device can be specied as a
device class name of up to 8 alphanumeric characters beginning with a letter
and terminated by any non-alphanumeric character such as a blank, or as a
logical device number consisting of a three-character numeric string, or it can
be a remote device identier consisting of the device class name or logical
device number followed by a pound sign (#) and a remote device class name
or logical device number.
Device class names and logical device numbers are assigned to devices during
system conguration. (See System Manager/System Supervisor Reference
Manual ).
For KSAM les, the device must be a random access device such as the disc.
If the le is a newly-created disc le specied as a device class name, then all
extents to the le must be members of the same class. Similarly, if the device
is identied by a logical device number then all extents must have the same
logical device number.
(Optional parameter.)
Default: If omitted, the device class name DISC is used .
Code indicates that the data le is specially formatted. The code is recorded
in the le label and is available to processes through the FGETINFO intrinsic.
It must be specied as a positive integer in the range 0 through 1023.
(Optional parameter.)
Default: If CODE is omitted, the le code is 0 .
USING KSAM UTILITIES
2-9
Note
The CODE parameter applies only to data les; the key le code value is
always 1080.
DISC=numrec Total maximum le capacity, in terms of logical records (for les containing
xed-length records). For les containing variable-length records, this is the
maximum le capacity if all the records are maximum length. Maximum le
capacity allowed is 2,097,120 sectors.
(Optional parameter.)
Default: If omitted, 1024 records is the default .
numextents
Number of extents (continguously-located disc sectors) that can be
dynamically allocated to the le as logical records are written to it. The size
of each extent (in terms of records) is determined by the numrec parameter
value divided by the numextents parameter value. Extents can allocated on
any disc in the device class specied in the device parameter. If you want to
ensure that all extents for a le reside on the same disc, use the logical device
number of that disc or a device class name relating to a single disc device, in
the device parameter. If specied, numextents must be integer value from 1 to
32.
(Optional parameter.)
Default: 8 .
initalloc
Number of extents to be allocated to the le at the time it is opened . Must be
an integer from 1 to 32. If attempt to allocate requested space fails, an error
message appears.
(Optional parameter.)
Default: 1 .
Actual le designator. This is the name that identies the KSAM key le. It
KEYFILE
=lereference2 has the format: lename , which is 1-8 alphanumeric characters beginning with
a letter. Unlike lereference1 (the data lename) lereference2 may not be
qualied by account or group names, nor may it contain a lockword. The key
le contains all the key entries and key control information, whereas the data
le contains the actual data. A KSAM le is always referenced by the data
le name, lereference1 , not the key le name, lereference2 .
(Required parameter.)
KEY=
One KEY specication must be included for each key in the KSAM le. The
rst occurrence of the KEY specication describes the primary key; each
subsequent KEY specication describes an alternate key. There may be up to
15 alternate key descriptions in addition to the primary key description.
(Required parameter.)
keytype
keytype is specied as BYTE,INTEGER, DOUBLE, REAL, LONG,
NUMERIC, PACKED, or *PACKED. The whole word or only the rst letter
need be specied (for example, B is equivalent to BYTE). If more than the
rst letter is used, the word must be spelled correctly. (Refer to Table 2-2 for
a full description of each key type.) (Required parameter.)
2-10
USING KSAM UTILITIES
keylocation
keysize
keyblocking
Location of the rst character of the key within the data record counting from
the rst character in the record. The rst character in the data record is
always numbered 1. Only one key can start at the same location. (Required
parameter.)
Length of the key in characters. The length depends on keytype as follows:
BYTE
1 to 255 characters
INTEGER
1 to 255 characters (default = 2)
DOUBLE
1 to 255 characters (default = 4)
REAL
1 to 255 characters (default = 4)
LONG
1 to 255 characters (default = 8)
NUMERIC
1 to 28 characters
PACKED
1 to 14 characters (odd number of digits)
*PACKED
2 to 14 characters (even number of digits)
(Required parameter for BYTE, NUMERIC, PACKED, and *PACKED key
types: defaults are provided for INTEGER, DOUBLE, REAL, and LONG key
types, as noted above.)
Number of keys per block. The keyblocking value is an even number greater
than or equal to 4. It is used with the key entry size (keysize paramater) to
determine the size of each key block according to the followign formula:
5 + (keysize+1) + 4)keyblocking = key block size in words
2
Five words are used for control information in each block, keysize specied in
characters is divided by 2 to get the key size in words, and 4 words are added
for the pointers in each key entry. This key entry size in words is multiplied
by the keyblocking factor to determine key block size. If the keyblocking value
generates a key block size greater than 2048 (2K) words, the le cannot be
created.
The resulting key block size is rounded up to a multiple of 128 words. If
the le has multiple keys, KSAM forces all key blocks to the same size and
adjusts the number of keys per block accordingly.
Note that the value you specify for keyblocking may be increased (never
decreased) by the system in order to produce a blocking factor that does not
waste disc space. Refer to appendix B for a discussion of how the system
determines the most ecient blocking factor based on the value you enter for
keyblocking .
Key blocking can aect access time in that the smaller the key block, the
more time it may take to retrieve a record using the key le. In many cases,
the default blocking factor produces the most ecient key blocking.
(Optional parameter.)
Default: key blocking is set to a value that produces a key block size of 1024
(1K) words. (Maximum size is 2K.)
USING KSAM UTILITIES
2-11
DUPLICATE In order to allow duplicate key values, this word must be included in the
KEY specication. If DUPLICATE (or DUP) is not specied, records with
DUP
duplicate key values are rejected and an error message issued when such
records are written to the le. DUP is a legal abbreviation of DUPLICATE.
When you use this option to specify duplicate keys, each new duplicate
key is inserted at the end of the duplicate key chain. This maintains the
chronological order of duplicate keys.
RDUPLIThis option species that duplicate keys are allowed and are to be inserted
randomly in the duplicate key chain. This method makes insertion of such
CATE
keys faster, but does not maintain the chronological order of the duplicate key
RDUP
chain.
(Optional parameter.)
KEYENTRIES=
numentries
LABELS=
numlabels
KEYDEV=device
2-12
Default: If omitted, duplicate keys are prohibited .
The value of numentries is used to determine the key le size. The value
specied for numentries should be the maximum number of primary key
entries expected. When there are alternate keys, KSAM automatically adjusts
the key le size to accomodate each key in addition to the primary key.
Normally, this parameter can be omitted since KSAM assigns it the value
of numrec (number of xed-length data records or blocks of variable-length
records). If, however, the data records are variable length and there are many
small records, the value of numrec may be too small. In this case, you should
specify a value for numentries greater than the value of numrec .
The number of key entries determines the size of the key le, the le limit.
When a new KSAM le is created, the MPE end-of-le marker is set to this
le limit rather than to the end-of-data as is normal for MPE les. This
allows any key block to be accessed in case of system failure. To determine
where the actual end-of-data is, use the KSAMUTIL VERIFY command,
option 3, and look at the heading KEY FILE EOF. This shows the record
number of the next available key block (one record past the last used key
block).
(Optional parameter.)
Default: the value of numrec in the DISC= parameter or its default value 1024
if it too is omitted .
The number of user label records to be created for the KSAM data le. Up
to 254 labels (1 less than the MPE maximum) can be specied; COBOL
programmers are restricted to 8 labels.
(Optional parameter.)
Default: if omitted, numlabels is equal 0.
The device on which the key le resides, specied as a device class name or
a logical device number. A device class name indicates the general type of
the device as a string of one to eight alphanumeric characters beginning with
a letter and terminated by a non-alphanumeric character such as a blank.
The logical device number is the threecharacter numeric string identifying a
particular device. If the data le is created on a remote device, the key le
USING KSAM UTILITIES
is assigned to the same machine, and the key le device is specied in the
KEYDEV= parameter.
Device class names and logical device numbers are assigned to devices during
system conguration.
For KSAM les, the device must be a random-access device such as the disc.
(Optional parameter.)
Default: If omitted, the device class name DISC is used .
FIRSTREC= Determines whether record numbers in the data le are to start with zero or
one. If the integer 1 is specied, then records are numbered beginning with 1;
recnum
otherwise they will start with 0. The only acceptable values for recnum are 1
and 0.
Normally, record numbering in MPE les starts with zero, the default value
for recnum . In order to be consistent with most commercial applications, you
can specify FIRSTREC=1 to change the record numbering scheme so that
data records are numbered starting with 1.
(Optional parameter.)
Default: if omitted, record numbering starts with zero .
The name or identication number of the language to use in determining the
LANG=
key sequence. The language specied by parameter must be installed on the
parameter
system. See Appendix F for detailed information on using Native Language
Support (NLS) with KSAM les.
(Optional parameter.)
Default: if omitted, NATIVE-3000 is used .
NODUP
Prevents duplicate le locks ftom the same process. NODUPLOCKS controls
\Lock&quot; access to a KSAM le. Each time a process opens a le more than
LOCKS
once and locks the le through a dierent open path, KSAM checks the le's
lock access. If NODUPLOCKS was specied when the le was created, the
process is not allowed to lock the le more than once. File locks from the
same open path are always allowed.
(Optional parameter)
Default: if omitted, duplicate le locks from the same process are allowed .
KEY DESCRIPTION
Each key is described by specifying key type, key position, key size, and, optionally, the
blocking factor and whether duplicates are allowed. Key type and size are dened in
Table 2-2. Note that default values are provided for keysize when key type is specied as
INTEGER, DOUBLE, REAL, or LONG. Only BYTE,INTEGER, and DOUBLE type keys
can be used as generic keys.
USING KSAM UTILITIES
2-13
Table 2-2. Key Types
keytype
keysize
(In Characters)
Format
BYTE
1-255
Each character requires 8 bits of a computer word. A
character may contain any of the HP ASCII character set
consisting of letters of the alphabet, numbers, and special
characters. (Refer to appendix C.)
INTEGER
1-255 (default = 2)
Single-word xed-point format permits two's complement
representation of positive and negative integers. Bit 0 is a
sign bit and the remaining 15 bits dene a quantity ranging
from 032768 through +32767.
DOUBLE
1-255 (default = 4)
Double-word xed-point format is the same as the integer
format except that two words are linked together to allow a
32-bit quantity with a range between approximately 02
billion and +2 billion.
REAL
1-255 (default = 4)
Floating-point format with bit zero as a sign bit, an
exponent (biased by +256) in bits 1 through 9, and a
positive fraction in the remaining 22 bits of the double word.
This type cannot be used as a generic key.
LONG
1-255 (default = 8)
Long oating-point format uses four words; an exponent
(biased by +256) in bits 1-9, as with the real number, and a
positive fraction in the remaining 54 bits. This type cannot
be used as a generic key.
NUMERIC
1-28
External decimal format in which each decimal digit requires
one 8-bit character and the sign is combined with the least
signicant digit. (Refer to Table 2-3 for the list of characters
representing the digit/sign combinations.) This type cannot
be used as a generic key.
PACKED
1-14
Packed decimal format in which each digit requires only 4
bits and the sign is specied as a hexadecimal number in the
least signicant 4 bits (1100 or C is plus and 1101 or D is
minus). This type cannot be used as a generic key.
*PACKED
2-14
Same as PACKED except this key type contains an even
number of digits. This type cannot be used as a generic key,
2-14
USING KSAM UTILITIES
Table 2-3. Character Equivalent to Signed Digit for NUMERIC Keys
POSITIVE
VALUES
POSITIVE
VALUES
NEGATIVE
VALUES
NEGATIVE
VALUES
SIGNED DIGIT
CHARACTER
SIGNED DIGIT
CHARACTER
+0
f
-0
g
+1
A
-1
J
+2
B
-2
K
+3
C
-3
L
+4
D
-4
M
+5
E
-5
N
+6
F
-6
O
+7
G
-7
P
+8
H
-8
Q
+9
I
-9
R
CREATING A KSAM FILE
Creating a KSAM le with the KSAMUTIL BUILD command is very similar to creating a
standard HP 3000 le with the MPE command :BUILD except that a KSAM le includes a
key le description. As with standard les, the default values can be assumed for many of the
le description parameters.
To create a KSAM le from the KSAMUTIL program, you can start by simply naming the le
as the rst parameter of the BUILD command. The le name denes the data le portion of
the KSAM le with the default options: xed-length, 128-word, binary-coded records, blocked
1 record per block.
To fully dene a KSAM le, you must also:
name the key le
dene at least one key (the primary key) in terms of:
type
location in the data le
size
These parameters provide your minimum KSAM le description from which the le can be
created. To illustrate:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD KSAMFILE;KEYENTITY =KFILE;KEY=I,21,2
This command assigns the name KSAMFILE to the KSAM data le; it names the key le
KFILE, and denes the primary key as an integer that starts in character 21 of the record,
and is two characters long. By default, the blocking factor of the keyle provides key blocks
1024 words long, the maximum number of primary keys is set to 1023 (the same as the
USING KSAM UTILITIES
2-15
maximum number of data records), duplicate keys are prohibited, and record numbering starts
with zero.
File KSAMFILE is now created. Default values were used where possible so that the BUILD
command specication shown above is the minimum needed to create a KSAM le. You
could create the same le, KSAMFILE, with the following BUILD command in which default
parameters are specied.
recsize
|
&gt;BUILD KSAMFILE;REC=128,,F,BINARY&amp; &lt;------ line continuation character
&gt;
;DEV=DISC&amp;
&gt;
;CODE=0&amp;
&gt;
;LABELS=0&amp;
&gt;
;FIRSTREC=0&gt;
;DISC=1023,8,1&amp; &lt;------ numrec,numextents,initialloc
&gt;
&gt;
&gt;
&gt;
;KEYFILE=KFILE&amp;
;KEY= I,21,2&amp; &lt;------ key description
;KEYENTRIES=1023&amp; &lt;----numentries
;KEYDEV=DISC
This specication of the BUILD command, although initially more cumbersome, documents
the default values with which the le is created. Since the default keyblocking factor is a value
calculated from the key size so that each key block is 1K words long, it is not specied here.
You can use the VERIFY command to nd the value KSAM has assigned as a key blocking
factor for any le you create using a default for this value.
Only a primary key is dened for this le. Within the data le, this key is an integer that
occupies characters 21 and 22 (word 11) of each data record.
In the key le, the values in any key are ordered sequentially so that the next higher value can
always be located. The key should not begin in the rst two characters of the data record
since these characters are set to all 1's when the record is deleted. If the key value of deleted
records need never be recovered, then this restriction can be ignored.
For each alternate key in addition to the primary key, another KEY= clause must be
included. Suppose a personnel le with a primary key containing an employee number, an
alternate key containing a name, and another alternate key containing the person's age. The
rst two keys are specied as BYTE keys, the third is an INTEGER. The key le is blocked
with 10 keys per block and the maximum number of primary keys expected is 3000:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD EMPLOYEE;REC=,,,ASCII;KEYENTITY =EMPKEY;KEYENTRIES=3000;&amp;
&gt;
KEY=B,3,11,10;&amp;&lt;---------- primary key (employee number)
2-16
USING KSAM UTILITIES
&gt;
&gt;
KEY=B,15,30,10;&amp;&lt;--------KEY=I,51,2,10&amp;&lt;-----------
alternate key (employee name)
alternate key (employee age)
The keys are located in the data record as follows:
Note that the keys need not be contiguous. In this example, the primary key is located nearer
to the beginning of the record than the other keys. This is not a requirement; the primary key
can physically follow any alternate keys in the record, although the primary key is always the
rst key specied in the BUILD command. For example, in the le FSAMPLE, the primary
key starts in character 21 following a secondary key in character 3:
USING KSAM UTILITIES
2-17
ERASE
Clears the contents of a KSAM le.
&gt;ERASE lereference
The contents of a KSAM le, both the data and key les, can be cleared to an empty state
with the KSAMUTIL ERASE command.
PARAMETERS
lereference
Actual le designator that identies the KSAM data le. It is specied
exactly like lereference1 in the &gt;BUILD command.
(Required parameter.)
CLEARING A KSAMFILE
EXECUTE access is required to erase a KSAM le. If the group in which the KSAM le
resides does not have EXECUTE access, any attempt to erase a le results in an error and the
message, \FSERR 93 SECURITY VIOLATION.&quot;
When ERASE is specied for a KSAM le, the end-of-le pointer that follows all data is reset
to point to the rst record in the data le. This position of the pointer is identical to its
position when the le is created and before any data is written to the le.
All pointers and control words in the key le are reset to indicate that the data le is empty.
Note that the le is still created and new data may be written to it.
For example, to clear the contents from the le identied as KSAMFILE:
&gt;ERASE KSAMFILE
2-18
USING KSAM UTILITIES
PURGE
Purges a KSAM le from the system.
&gt;PURGE lereference [,TEMP]
The KSAMUTIL PURGE command can be used to remove a KSAM le, both data and
key les, from the system. Although the MPE :PURGE command can also be used, it must
be specied twice, once for the data le and once for the key le. If you are programming
in COBOL, BASIC, or RPG, you should use the KSAMUTIL PURGE command to purge
a KSAM le. In SPL or FORTRAN you could also use the FCLOSE intrinsic (described in
section IV) to purge a KSAM le.
PARAMETERS
lereference
TEMP
Actual le designator identifying the KSAM data le. Specied exactly like
lereference1 in the &gt;BUILD command.
(Required parameter.)
Must be specied if le is a temporary le in session/job temporary le
domain. If omitted, a permanent le is assumed.
(Optional parameter.)
PURGING A KSAM FILE
When PURGE is executed, the specied KSAM data le and its associated key le are
removed from the system and can no longer be referenced.
For example, to purge a temporary KSAM le called KTEMP:
&gt;PURGE KTEMP,TEMP
KTEMP.KSAM.DATAMGT &amp; KKEY PURGED.
To purge the permanent le KSAMFILE:
&gt;PURGE KSAMFILE
KSAMFILE.KSAM.DATAMGT &amp; KFILE PURGED.
The system prints the data and key le names of a successfully purged KSAM le. It also
prints the group and account names in which the le was created (in this case KSAM and
DATAMGT).
USING KSAM UTILITIES
2-19
RENAME
Renames either the data or key le of a KSAM le.
&gt;
2
3
RENAME
oldlereference, newlereference ,TEMP
R
The KSAMUTIL RENAME command can be used to change either the KSAM data le name
or the KSAM key le name to a new name. Following execution of RENAME, the data and
key les retain their relation to each other. Note that if the MPE :RENAME command is
used, this relation is severed . The FRENAME intrinsic cannot be used to rename a KSAM
le.
PARAMETERS
oldlereference
newlereference
TEMP
Current actual le designator identifying the KSAM data le or the KSAM
key le, specied exactly like lereference1 or lereference2 in the BUILD
command.
(Required parameter.)
New actual le designator in same format as oldlereference . The le named
by oldlereference will be given the name specied by newlereference .
(Required parameter.)
Indicates that old le was, and new le will be, a temporary le in the
session/job temporary le domain.
(Optional parameter.)
Default: If omitted, permanent le is assumed.
RENAMING A KSAM FILE
You may rename either the data le or the key le, not both, with one &gt;RENAME command.
To rename the entire le, you must specify the RENAME command twice. Thus, to rename
the data le KSAMFILE and its associated key le KFILE:
&gt;RENAME KSAMFILE,NEWDATA
&gt;RENAME KFILE, NEWKEY
The relation between keys and data in the newly named les is the same as that in the les
KSAMFILE and KFILE.
If the data le being renamed was protected by a lockword, then this lockword must be
specied on both the old and new les if it is to be retained. If the lockword is omitted, it is
removed when the le is renamed. Note that a lockword is never specied when renaming the
key le; the keyle is protected automatically by any lockword assigned to its associated data
le. For example, to assign a new lockword to the data le DATAFIL:
&gt;RENAME DATAFIL/LOCKA, DATAFIL/LOCKB &lt;----------- new lockword
Note that the new le name need not be in the same group as the old le name. RENAME
provides a way to move a le from one group to another. For example, to move the KSAM le
DATAFILE with its associated key le KEYFILE from GROUPA to GROUPB:
&gt;RENAME DATAFILE.GROUPA,DATAFILE.GROUPB
2-20
USING KSAM UTILITIES
Note that only one RENAME command is used. This one command insures that both the
data le and the key le are in the same group.
USING KSAM UTILITIES
2-21
SAVE
Saves a temporary KSAM le as a permanent le.
SAVE
&gt;
S
2
lereference
3
A temporary KSAM data le and its associated key le are made permanent with the
KSAMUTIL SAVE command. The keyword \SAVE&quot; can be abbreviated to \S&quot;.
PARAMETERS
lereference
Actual le designator identifying the session/job temporary le to be saved,
specied exactly like lereference1 in the &gt;BUILD command.
(Optional parameter.) Default: If omitted, last lereference is assumed .
SAVING A KSAM FILE
Assume that KSAM data le KDATA and its associated key le was created as a session/job
temporary le; to save this le as a permanent le:
&gt;SAVE KDATA
Both the data and key les are saved.
2-22
USING KSAM UTILITIES
VERIFY
Displays access and status information about KSAM le.
VERIFY
&gt;
V
2
32
32
lereference ;OFFLINE ;NOCHECK
3
With the VERIFY command, you can request a display of the characteristics of a KSAM data
le, both the static information dened at le creation and dynamic le access information.
The abbreviation V can be used instead of the keyword VERIFY.
PARAMETERS
lereference
Actual le designator identifying the le whose characteristics are to be
displayed. The actual designator can be a back reference to a le name in an
MPE :FILE command; in this case, the actual designator must be preceded by
an asterisk (*). Either the data le name or the key le name may be used to
identify the KSAM le.
(Optional parameter only if no parameters.)
OFFLINE
NOCHECK
Default: If omitted, last lereference is assumed.
Display output on line printer. An MPE :FILE command may be used to
specify a particular line printer.
(Optional parameter.)
Default: If omitted, display is sent to terminal.
Allows specied KSAM le to be opened for read-only access by the VERIFY
command; use when a system failure prevents the KSAM le from being
opened.
(Optional parameter.)
Default: If omitted, VERIFY cannot open le that was open when system
failed.
DISPLAY KSAM FILE CHARACTERISTICS
In a session, you will be asked to select one of four possible displays:
1. File information (denitions from le creation plus le access statistics)
2. KSAM parameters (denitions of keys from le creation)
3. KSAM control (key le access statistics)
4. All three of the above displays
In a job, the entire set of displays is printed exactly as if option 4 had been selected in a
session.
To illustrate the interaction, the following VERIFY commands select each of the three
separate displays; if option 4 were selected, these displays would be printed consecutively with
no halt until they were nished. User entries are underlined:
&gt;RUN KSAMUTIL.PUB.SYS
USING KSAM UTILITIES
2-23
HP32208A.2,4 TUE, APR 17, 1979, 11:23 AM
&gt;VERIFY TESTFILE
KSAMUTIL VERSION:A.2.4
select le information only--------------------------|
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?1
TESTFILE,JOAN.MORRIS
CREATOR=JOAN
FOPTIONS(004005)=KSAM, :FILE, NOCCTL, F, FILENAME, ASCII, PERM
AOPTIONS(000400)=DEFAULT, NOBUF, DFFAULT, NO FLOCK, NO MR, IN
RECSIZE:SUB:TYP:LDNUM:DRT:UN.: CODE:LOGICAL PTR: END OF FILE:FILE LIMIT
-128: 9: 0:
2: 4: 1:
0:
0:
5:
1023
LOG. COUNT:PHYS. COUNT:BLK SZ:EXT SZ:NR EXT: LABELS:LDN:
DISCADDR:
1:
1: -128: 129:
8:
0: 2:00000117760:
The infomation returned by selecting le information is the same as that returned by
FGETINFO (described in section IV).
select key le information only-------------------------|
WHICH (1=FILE INFO,
2=KSAM PARAMETERS,
3=KSAM CONTROL,
|
4=ALL)?2
KEY FILE=TESTKEY KEY FILE DEVICE=3
SIZE=
386 KEYS=
FLAGWORD(000000)=RANDOM PRIMARY,
FIRST RECORD=0,
PERMANENT
KEY TY LENGTH
LOC. D KEY BF LEVEL
1 B
20
3 Y
72
1&lt;----- primary key is listed rst,
2 B
8
24 R
126
1&lt;----- alternate keys follow
\______________________/
^
|
|----------------------- random insertion of duplicate
corresponds to KEY= descriptions in BUILD command
2
key
The actual number of keys per block (the blocking factor) is listed in this display under
the heading KEY BF. Note that this number may be greater than the blocking factor you
specied during le creation. This occurs if KSAM adjusts the specied blocking factor
to generate a block size that makes optimum use of disc space, KSAM only increases the
specied blocking factor, it never decreases it. (Refer to appendix B for full particulars on the
calculation of block size and the adjustment of the blocking factor.)
The maximum number of levels in the key le structure for each key is noted under the
heading LEVEL.
select dynamic KSAM le information------------|
|
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3
DATA FILE = TESTFILE
KEY CREATED=107/'79
KEY CHANGED=107/'79
DATA RECS =
DATA BLK SZ=
FOPEN
FREADDIR
FREMOVE
FGETINFO
FWRITELABEL
FWRITE
FLOCK
FSETMODE
KEYBLK READ
KEY FILE EOF
2-24
VERSION= A.2.4
10:58:17.4
KEY ACCESS= 107/'79 11:23:35.9
11:21: 7.7
COUNT START=107/'79 11:21: 8.0
5 DATA BLOCKS=
4 END BLK WDS=
64 DATA REC SZ=
128 ACCESSORS=
1 FREAD
0 FCLOSE
0 FREADC
0 FRFADBYKEY
0 FSPACF
0 FFINDBYKEY
3 FGETKEYINFO
1 FREADLABEL
0 FCHECK
0 FFINDN
5 FUPDATE
0 FPOINT
0 FUNLOCK
0 FCONTROL
0
3 KEYBLK WROTE
2 KEYBLK SPLIT
18 FREE KEY HD
0 SYSTEM FAILURE
USING KSAM UTILITIES
64
0
1
0
0
0
0
0
0
0
0
MIN PRIME
DATA FIXED
FIRST RECNUM
3 MAX PRIME
TRUE DATA B/F
0 MIN PECSIZE
1 RESET DATE
1 TOTAL KFYS
31
2
The dynamic key le information displayed by option 3 together with the static key le
information displayed by option 2 comprise the information displayed by the FGETINFO
intrinsic described in section IV. Note that the version number displayed by VERIFY is the
version of KSAM under which the le was created. The intrinsic HP32208 described in section
IV can be used to determine the current version of KSAM.
TERMINATING THE
&gt;VERIFY COMMAND
In order to terminate the VERIFY command in a session, you must press the RETURN key
(CR) in response prompt:
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?
Any other response either causes a display followed by reiteration of this prompt or else causes
this prompt to be issued. For example:
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?6
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?0
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?CR
|
&gt;EXIT
|
|
END OF PROGRAM
only response to terminate VERIFY.----------|
DIRECTING VERIFY OUTPUT TO LINE PRINTER
If you want a \hard copy&quot; of the information displayed by VERIFY, you should use the
OFFLINE option. When included, OFFLINE directs the VERIFY information to a line
printer. You can use the :FILE command to specify a dierent output device or a particular
line printer.
USING VERIFY FOR RECOVERY
In case of a system failure when a KSAM le is open, the VERIFY command provides the
following useful information:
EOF marker on the data le (END OF FILE header in option 1)
EOF marker on key le (KEY FILE EOF header in option 3)
Flag indicating whether system failure occurred (SYSTEM FAILURE heading in option 3)
Number of processes that had opened the le for non read-only access when the system
failure occurred (ACCESSORS heading in option 3).
Note that you must use the NOCHECK option in order to run VERIFY when a system
failure prevents KSAM les from being opened. This option overrides the restriction on
opening les after a system failure and allows a le to be opened for read-only access in order
to get the VERIFY information. (This access is not counted in the ACCESSORS count.)
(Refer to the KEYINFO command description for an example of how the VERIFY
information can be used for recovery after system failure.)
USING KSAM UTILITIES
2-25
KEYSEQ
Veries sequence of key values in KSAM le.
KEYSEQ
&gt;
KS
2
32
32
32
lereference ;SEQ=keysequence ;OFFLINE ;NOLIST
3
This command compares all the key values in a particular key (primary or alternate) to
determine whether they are in ascending sequence. If any values are out of sequence, a list of
numbers identifying such values is displayed, unless NOLIST is specied. In any case, the
number of outquence values is returned. Note that if key values are out of sequence, the key
le is damaged and the KSAM le must be reloaded.
The abbreviation KS may be used instead of the keyword KEYSEQ.
PARAMETERS
lereference
Actual le designator identifying the KSAM le whose key values are to
be veried. Either the data le name or the key le name can be used to
identify a KSAM le. Also, a back reference to a le named in an MPE :FILE
command may be used.
(Optional parameter if no parameters are specied.)
SEQ=
keysequence
OFFLINE
NOLIST
2-26
Default: If omitted, the last le referenced is assumed .
Identies particular key whose key values are to be checked. Keys are
numbered from 1. The rst key (SEQ=1) is always the primary key;
subsequent keys are alternate keys numbered in the order they appear in the
record, such that the rst alternate key in the record is SEQ=2, the second
alternate key is SEQ=3, and so forth.
(Optional parameter.)
Default: If omitted, the primary key is assumed.
Directs list of out-of-sequence keys to the line printer. An MPE :FILE
command may be used to indicate a dierent output device than the line
printer, or a particular line printer.
(Optional parameter.)
Default: If omitted, the list of out-of-sequence keys is displayed at user's
terminal .
Suppresses display of the particular key numbers whose values are out of
sequence. A count of the out-of-sequence values is displayed even if NOLIST
is specied.
(Optional parameter.)
Default: If omitted, list of key numbers for out-of-sequence key ualues is
displayed.
USING KSAM UTILITIES
VERIFY KEY SEQUENCE
If you suspect that your key le has out of order key values in any key, you can run KEYSEQ.
If any key values are not in ascending sequence, the key numbers associated with those key
values are displayed. Note that the number of a key value refers to its position in the key le.
For example, if the third, fourth, and fth key values of a particular key are out of sequence,
the numbers 3, 4, and 5 are displayed.
If the list of out-of-sequence key numbers is long, you can terminate it by holding down the
CNTL key while typing Y (CNTL/Y). The total number of out-of-sequence key values will be
displayed even if you terminate the list with CNTL/Y or suppress it altogether with NOLIST.
Consider the following partiallist of key values in the primary key of the KSAM le MYFILE:
If you run KSAMUTIL and use the KEYSEQ command, as shown below, you can determine
which keys are out of order:
:RUN KSAMUTIL.PUB.SYS
&gt;KEYSEQ MYFILE ;SEQ=1&lt;----------- test primary key sequence
KEYSEQ displays the following:
KEY VALUE # (FOR VALUE OUT OF SEQUENCE)
3 ------ key number of keys with out-of-sequence values
4 -------|
TOTAL # OF KEY VALUES READ
30
# OF KEY VALUES OUT OF KEY SEQUENCE ORDER
2
KEY FILE STRUCTURE DAMAGED, KSAM FILE HAS TO BE RELOADED
Regardless of the number of key values that are out of sequence, you should reload the KSAM
le to restore its integrity.
Consider a second example. Suppose MYFILE has two alternate keys, one starting in location
11 (11th character of record) and another starting in location 33. To verify the sequence of
key values in the second alternate key, execute KEYSEQ as follows:
&gt;KS MYFILE ;SEQ=3 ;NOLIST &lt;----- suppress list
|
|------ second alternate key
of key numbers
TOTAL # OF KEY VALUES READ 30
#OF KEY VALUES OUT OF KEY SEQUENCE ORDER 0 &lt;---
key values in sequence
In this case all the key values were in correct sequence. Unless other keys in this le have
values that are out of sequence, you need not reload the le.
USING KSAM UTILITIES
2-27
Note that NOLIST was specied. In general this is good practice. If any key values are not in
sequence, the le should be reloaded, so it is seldom important to know which keys are out of
sequence.
2-28
USING KSAM UTILITIES
KEYDUMP
Provides formatted, structural dump of key le.
3
32
KEYDUMP 2
lereference ;SEQ=keysequence
&gt;
KD
33
92
2
82 3
,
number
0
;SUBSET=
position
&quot;string&quot;
2
32
3
;OFFLINE ;SORT
2
;FILE =formaldesignator
3
The key le dump consists of three items of information for each key value:
1. Key Value The actual value of each key in ascending order
The record number (xed-length les) or word oset (variable-length les) of
2. Record
the data record to which the associated key value points.
Pointer
3. Key Block Relative record number of the rst record in the key block containing the
associated key value, followed within parentheses by the number of key values
Address
in the block. The addresses of key blocks at dierent levels are indented.
This dump is very useful for examining the contents of any key le. Since key blocks are
physically scattered throughout the key le, linked by pointers, it is dicult to follow an
unstructured dump of a key le. The KEYDUMP display shows the contents of the key le,
not as they are actually stored, but in a way that makes it much simpler to read than a dump
of the actual le.
One key at a time is dumped by KEYDUMP. If there is more than a primary key, you must
run KEYDUMP for each key in order to dump the entire key le.
Note that you can use CNTL/Y (the CNTL key held down while pressing the Y key) to stop
display of this dump at any time. This is particularly useful if you display the dump at the
terminal. Usually, however, you will use the OFFLINE option to list the dump on a line
printer (see Parameter description, below).
You can choose to dump a subset of the key le contents based on the key number or a key
value. You can send the dump to a particular le and, if so, you can sort the key le contents
by the record number in the data le rather than by key value. You can also send the dump
to a line printer.
PARAMETERS
lereference
Actual le designator identifying the KSAM le whose key le is to be
dumped; either the data le name or the key le name can be specied.
The lereference can be a back reference to a le named in an MPE :FILE
command.
(Optional parameter if no parameters are specied.)
SEQ=
keysequence
Default: If omitted, the last le referenced is assumed.
Specify a particular key whose contents are to be dumped. The primary key,
whatever its location in the data record, is always key number 1 (SEQ=1).
Alternate keys are numbered according to the order in which they are
specied in the BUILD command (or in ksamparam at FOPEN). The rst
alternate key is specied as SEQ=2, the next alternate key as SEQ=3, and so
forth.
USING KSAM UTILITIES
2-29
(Optional parameter.)
SUBSET=
[0]position
\string &quot;
,number
FILE
=lename
Default: If omitted, the primary key is selected.
Select a portion of the key le to dump, based on the numeric position of the
key or the key value, and the number of key values.
Start dump with key whose number is specied. This number is the same as
the key number issued by KEYSEQ. It corresponds to the position of the key
value in the le in ascending sequence. Thus the rst key value is position 1,
the second is position 2, and so forth.
The optional minus sign suppresses the normal indentation by key levels of
the key block address display.
Start dump with rst key value greater than or equal to the specied string.
Indicates the number of key values to be dumped starting with the key at the
indicated position or whose value is indicated by \string &quot;.
(Optional parameter.)
Default: If omitted, all the key ualues for selected keys are dumped.
Direct key le dump to specied disc le. A disc le (lename ) will be
created with a record size equal to the size of a key entry, that is keylength
(rounded up to full words) + four words.
The four words are needed for the record pointer (2 words) plus the key block
address (2 words). Note that a new le is always created, so do not name an
existing le.
The le has a default block size of 1K words. Any of the le characteristics
except the record size can be changed by a :FILE statement. For example:
&gt;:FlLE FILEDUMP ;REC=,100 ;DEV=TAPE
&gt;KEYDUMP MYFILE ;ENTITY =*FILEDUMP
These commands dump the primary key sequence to a tape with 100 records
per block.
(Optional parameter.)
OFFLINE
SORT
2-30
Default: If omitted, key dump is sent to terminal.
Direct output to a line printer. An MPE :FILE command can be used to
indicate a dierent output device or a particular line printer.
(Optional parameter.)
Default: If omitted, the dump is sent to the user's terminal.
Sort dump by record pointers rather than key values. The record pointers
indicate the record number of the records in a data le with xed length
records or the word oset of the records in a data le with variable-length
records.
Note that this option can be used only when the dump is directed to a specic
le with the ENTITY = option.
(Optional parameter.)
USING KSAM UTILITIES
Default: If omitted, key dump is in ascending sequence by key value.
DUMPING THE KEY FILE
The dump produced by KEYDUMP consists of three columns: the rst contains the key
value, the second a pointer to a record number in the data le, and the third contains the key
block address and the number of key values in that block. The key block address is given as
the record number of the rst record in any block.
For example, assume that TESTFILE contains an INTEGER type primary key whose values
we want to see. Run KEYDUMP as follows:
:RUN KSAMUTIL.PUB.SYS
&gt;KEYDUMP TESTFILE
The resulting dump consists essentially of three columns: one contains the key values in
ascending sequence, another contains the record number (or word oset if record size is
variable) of the associated record in the data le, and the third gives the record address of the
key block. A sample dump is shown below:
This dump lists under the heading \KEY&quot; 14 integer key values in ascending order from 0001
through 0014. The next column under \REC.PTR.&quot; lists the record number of the data
record associated with the key value|thus, key value 0001 is in record number 3 of the data
le (the fourth record in chronological sequence), and key value 0006 is in the rst record in
the data le, record number 0. The third column under \KEY BLOCK ADR.&quot; shows the
address of the key block in which each key value resides, The key block address is shown as
the record number of the rst record in the key block. (Note that KSAM key les use xed
USING KSAM UTILITIES
2-31
length records each one sector long|128 words. Thus, the record number is also the sector
number. A keyblock consists of more than one sectors|default is 8 sectors).
Key values are organized into blocks using a B-Tree structure (refer to appendix B for
details). This structure has one or more levels where the rst or highest level, is known as the
\root&quot; and lower level are \leaves&quot;. This dump shows the level structure of the key le by
indenting the key block addresses to correspond to levels. The highest or root level address
is in the rightmost column, lower levels are listed to the left. By looking at the key block
address, we see that the key block starting at record (sector) 6 is the root block, and that
there are three key blocks at a lower level whose addresses start, respectively, at records 2, 18,
and 24. This key le has two levels; a key le with more levels would have correspondingly
more columns under the key block address heading.
The rst time a key block address is listed, it is followed in parentheses by the number of key
values in that block. Looking at the dump, we see that the block starting at record 2 has 4
key values, the block at record 6 has 2 values, the block at record 18 has 5 values, and the
block at record 24 has 3.
With this dump, we can picture the structure of the key le associated with the le
TESTDUMP:
The key values are shown within their key blocks; the dashed lines show the pointers that link
key blocks in ascending sequence.
2-32
USING KSAM UTILITIES
DUMPING A SUBSET OF THE KEY FILE
If you want to dump a selected number of key values rather than all the values in a key,
you can use the SUBSET option of KEYDUMP. The starting key value can be located in
two ways: if you know the key number of the rst key value you want displayed, use the
SUBSET=position format; if you know the actual key value (or a value less than the key
value), then you can use the SUBSET=\string&quot; format. In either case, the second SUBSET
parameter is always an integer that indicates the number of key values you want dumped.
BY KEY NUMBER
The key number is the sequential number associated with each key value in a particular key.
If the KEYSEQ command has listed key numbers that are out of sequence, you may want to
dump only these values. Suppose that TESTFILE has out of sequence values, the following
example runs KEYSEQ rst and then runs KEYDUMP to dump the key values shown as out
of sequence. (ln order to see the last value in correct sequence, the key preceding the rst key
out of sequence is selected as the rst key to dump.)
&gt;KS TESTFlLE
KEY VALUE # (FOR KEY VALUE OUT OF SEQUENCE)
6&lt;-------------------------|
7
|
8
|values used for SUBSET= of KEYDUMP
9
|------------|
TOTAL # OF KEY VALUES READ 14
|
# OF KEY VALUES OUT OF KEY SEQUENCE ORDER 4 -- values used for SUBSET= of KEYDUMP
KEY FILE STRUCTURE DAMAGED, KSAM FILE HAS TO BE RELOADED
&gt;KD TESTFILE ;SUBSET=5,5 &lt;------- number of key ualues out of sequence (Plus 1)
|
|----- key preceding rst key # out of sequence
The following dump shows the last key value in sequence followed by the key values that are
out of sequence:
KEY
1st key out
0005
of sequence---&gt;0008
0007
0009
0006
BY KEY VALUE
REC.PTR.
KEY BLOCK ADR.
3
9
4
7
0
18 (5)
18
18
18
12(2)
The second version of SUBSET= species an actual key value followed by the number of key
values. You need not specify the exact key value; it can be a value less than an actual Integer
or Double type key value (approximate match) or only the rst part of a Byte type key value
(generic match). For example, suppose TESTFILE has an alternate key that contains names
in alphabetic order and you want to look at the ten key values that start \GI&quot; or the next
greater value. Specify the following command:
&gt;KD TESTFILE ;SEQ=2 ;SUBSET=&quot;GI&quot;,10
|
\____/---|
|
|
---------|
|
----- 1st alternate key
dump 1st 10 values
starting with or
greater than &quot;GI&quot;
The dump appears as follows:
USING KSAM UTILITIES
2-33
KEY
REC.PTR.
KEY BLOCK ADR.
GIBBS
GILLESPIE
GLADSTONE
HERTZ
HIGGINS
JONES
LOOMIS
MORRIS
MYERS
NOLAN
3
12
4
8
0
7
13
5
6
1
2 (4)
2
2
2
8(3)
16(4)
16
16
16
8
SORTING DUMP BY RECORD POINTER
If you use the SORT option of KEYDUMP, you must also specify ENTITY =lename , where
the specied le name is that of a disc le. (Note that you must not name an existing le; a
new le is created for the dump.) In this case, you might also want to suppress the indention
of the key block address levels. To do this, enter the following command:
|------ suppress key block address indentation
|
|
&gt;KD TESTFILE;FILE =MYFILE;SUBSET=-1,500;SORT &lt;--- sort by record pointer
|
|---- dump is sent to MYFILE, created with default values
The resulting dump is sent to a disc le MYFILE, created with a default block size of 10
words, one record per key entry. The key entries are sorted by the pointers to the records
in the data le. Indentation of the key block address is suppressed. The key values, record
pointers, and key block addresses are not converted to ASCII but are dumped to the specied
le in binary format. In case of a le with 500 or fewer key values, the entire le is dumped.
The SORT option is useful if you want to look at key values in terms of the data records to
which the key values point. For example, in order to determine whether any key values are
missing, you can dump all the keys in a le using the SORT option, and compare the record
numbers in each dump to make sure each record has the same number of key values pointing
to it.
2-34
USING KSAM UTILITIES
KEYINFO
Displays information about the key le, and attempts recovery of a KSAM le in case of
system failure when the le is open.
KEYINFO
&gt;
K1
2
32
32
lereference ;OFFLINE ;RECOVER
3
KEYINFO performs two operations: it collects and displays information about the key le,
and it takes steps to recover the KSAM le in case a system crash occurred when the le
was open. The second operation is performed only after a system crash or if the RECOVER
parameter is specied.
The key information displayed by KEYINFO consists of:
Number of levels in key block structure:
Number of key blocks
Number of sectors per key block
Number of keys in root block
Number of keys in all blocks of the key le
Percent of each key block used
Largest key block address
The crash recovery performed by KEYINFO depends on the type of damage to the le.
If MPE end-of-le does not match end-of-le for KSAM data le, KEYINFO resets the
MPE end-of-le to match the KSAM end-of-le.
If key le contains values that point to records past the KSAM end-of-le, KEYINFO
deletes these key values.
If the key le end-of-le marker does not match the actual end of the key le, KEYINFO
corrects the key le end-of-le marker.
If records in the data le do not have associated key values in the key le, KEYINFO issues
a warning that key values are missing.
PARAMETERS
lereference
Actual le designator of the KSAM le; either the data le name or the key
le name may be specied. The lereference can be a back reference to a le
named in an MPE :FILE command.
(Optional parameter if no parameters are specied.)
OFFLINE
RECOVER
Default: If omitted, the last le referenced is assumed.
Directs output to the line printer. An MPE :FILE command can be used
to indicate a dierent output device or a particular line printer. (Optional
parameter.)
Default: If omitted, output is sent to user's terminal.
Forces KEYINFO to perform recovery procedures even though no system
crash occurred.
USING KSAM UTILITIES
2-35
(Optional parameter.)
Default: If omitted, recovery performed only if system crashed with le open.
REQUESTING KEY FILE INFORMATION
Information is displayed by KEYINFO for each key in the key le, in key order starting with
the primary key. For example, request KEYINFO for the le DATAFIL which has three keys:
&gt;KI DATAFIL
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
% OF KEY BLOCK UTILIZATION
THE LARGEST KEY BLOCK ADDRESS
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
% OF KEY BLOCK UTILTZATION
THE LARGEST KEY BLOCK ADDRESS
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
% OF KEY BLOCK UTILIZATION
THE LARGEST KEY BLOCK ADDPESS
1 --------1
1
8
20
20
38.4
2
2 --------1
1
8
20
20
9.9
10
3 --------1
1
8
20
20
13.8
18
&gt;EXIT
# OF LEVELS OF B-TREE - Key les are organized in a structure known as a \B-Tree&quot;.
This structure may have one or more levels (for details refer to appendix B). The le
DATAFIL has only one level.
# OF KEY BLOCKS - Key values are stored in blocks; this entry gives the total number of
key blocks in the le. DATAFIL has only one key block .
# OF SECTORS PER KEY BLOCK - A key block may require one or more 128-word sectors.
DATAFIL uses eight sectors for its key block (the default value) .
# OF KEYS IN ROOT BLOCK - This species the number of key values stored in the root
block (in this case the only block). If this number is equal to the key blocking factor (see
KEY BF header in VERIFY output), then the next key block split will increase the number
of levels in the B-Tree by one. DATAFIL has 20 key values in its root block, and the blocking
factor allows 52, 202, or 144 (see VERIFY printout below) .
&gt;VERIFY DATAFIL
WHICH (1=FILE
2-36
INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?2
USING KSAM UTILITIES
KEY ENTITY=KEYFIL
KEY FILE DEVICE=2
SIZE=
50 KEYS=
FLAGWORD(000000)=RANDOM PRIMARY, FIRST RECORD=0, PERMANENT
KEY TY LENGTH
LOC. D
KEY BF LEVEL
|
|----------- blocking factor, keys/block
1 B
30
1 Y
52
1
2 B
2
31 Y
202
1
3 B
6
33 Y
144
1
3
# OF KEYS IN B-TREE - This is the total number of key values in the key le for each
key. This number should be the same for each key and should also be the same as the
number of active records in the data le (to determine this, use the FCOPY command
&gt;FROM=DATAFIL;TO=$NULL ;KEY=O. FCOPY is described later in this section).
DATAFIL has 20 key values in each B-Tree, and this is the same number as the number of
active data records (see FCOPY output below).
:RUN FCOPY.PUB.SYS
HP32212A.3.08 FILE COPTER (C) HEWLETT-PACKARD CO. 1978
&gt;FROM=DATAFIL;TO=$NULL;KEY=0
EOF FOUND IN FROMFILE AFTER RECORD 19 &lt;----
records numbered from 0
20 RECORDS PROCESSED *** 0 ERRORS
% OF KEY BLOCK UTILIZATION - Average percent of use of all key blocks (percent of use
means how much of the block contains key values). Note that the root block of a multi-level
tree is omitted from this average. For multi-level trees the percent is between 50% and 100%,
for single-level trees between 0% and 100%. The higher the percentage, the faster the retrieval
of data. But, also the higher the percentage, the greater the chance of block splits when
records are added. DATAFIL uses 38.4% for its primary hey, 9.9% and 13.8% each for its two
alternate keys.
THE LARGEST KEY BLOCK ADDRESS - This is the largest key block address found for
each key. The key le end-of-le should never be less than the largest block address for the le
plus the number of sectors per key block. The largest block address for DATAFIL is 18 (the
largest block address for DATAFIL is 18 (the largest block address of key 3). Since the number
of sectors per block is 8, the key le end-of-le should be at least 26 (see VERIFY output
below).
WHICH (1=FILE INFO,
DATA FILE = DATAFIL
KEY CREATED=292/'78
KEY CHANGED= 93/'79
DATA RECS =
DATA BLK SZ=
FOPEN
FREADDIR
FREMOVE
FGETINFO
FWRITELABEL
FWRITE
FLOCK
FSETMODE
KEYBLK BEAD
KEY FILE EOF
2=KSAM PARAMETERS,
3=KSAM CONTROL?
4=ALL)?3
VERSION= A.2.1
10:19: 7.4
KEY ACCESS= 107/'79 12: O: 2.9
14:18: 7.6
COUNT START=292/,78 10:19:53.6
20 DATA BLOCKS=
19 END BLK WDS=
19
19 DATA REC SZ=
38 ACCESSORS=
0
2 FREAD
0 FCLOSE
2
0 FREADC
0 FREADBYKEY
0
0 FSPACF
57 F'FINDBYKEY
0
2 FGETKEYINFO
1 FREADLABEL
0
0 FCHECK
0 FFTNDN
3
20 FUPDATF
0 FPOINT
0
0 FUNLOCK
0 FCONTROL
0
0
7 KFYBLK WROTE
0 KEYBLK SPLTT
0
26 FREE KEY HD
0 SYSTEM FAILURE
0
|----------------- le end-of-le for DATAFIL
USING KSAM UTILITIES
2-37
MIN PRIME
DATA FIXED
FIRST PECNUM
11 MAX PRIME
TRUE DATA B/F
0 MIN PECSIZE
5 RESET DATE
1 TOTAL KEYS
38
67/'79
3
RECOVERING AFTER SYSTEM FAILURE
KEYINFO only performs the recovery operations if there has been a system failure or if you
specify the RECOVER parameter.
If there has been a system failure while the KSAM le is open for non-read access, a ag
is set that prevents the le from being opened. Whenever this occurs, KEYINFO must be
used in order to reset this ag so that the le can be opened. KEYINFO also recovers from
any damage done to the le as a result of the system failure. It resets end-of-le markers for
both the data and key les, and deletes any key values that point to records beyond the data
le end-of-le. It also stores in the key le the user, group, account, and home group of the
user who runs KEYINFO to recover the le. (When there has been a system failure or when
KEYINFO is run with the RECOVER option, the KSAM le is opened for exclusive access;
otherwise it is opened for shared access.)
When KEYINFO is run after a system failure, the SYSTEM FAILURE count displayed by
option 3 of VERIFY is incremented by 1. If there was no system failure but KEYINFO was
run with the RECOVER option, this count is not incremented.
When KEYINFO resets the \crash&quot; ag, the date of this reset is saved and can be recovered
through the VERIFY command, option 3 under the heading RESET DATE. Note that the
NOCHECK option of VERIFY allows that command to open a KSAM le for read-only
access even if a system failure prevents the le from being opened for all other access.
For example, assume a le TEST that was open when a system failure occurred. In this case,
KEYINFO must be run. Also, assume the following:
The data le end-of-le (at the end of the data) is beyond the MPE end-of-le (not yet
written to le when system failed).
There are key values beyond the key le end-of-le (internal key le EOF).
There are data values with no associated key values.
Running KEYINFO will correct the end-of-le markers and, if any keys point to data records
beyond the data le end-of-le, it will delete these key values. KEYINFO cannot, however,
restore missing key values. To do this, you must reload the le with FCOPY. To illustrate,
KEYINFO operates as shown below:
2-38
USING KSAM UTILITIES
&gt;KI TEST
RECOVERY BEGINS
DATA FILE EOF DAMAGED
DATA FILE MPE EOF HAS BEEN RESET TO KSAM EOF
reset end-of-le
for data le
-------- INFO FOR KEY
1 ---------
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
# OF KEY BLOCK UTILIZATION
THE LARGEST KEY BLOCK ADDRESS
2
16
8
14
1000&lt;------|
52.1
|
210
|
|
2 --------# of
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
# OF KEY BLOCK UTILIZATION
THE LARGEST KEY BLOCK ADDRESS
keys
should match
2
|
11
|
8
|
9
|
997&lt;------|
68.6
202
WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING
OR KEY VALUE(S) POINTING TO DATA RECORD BEYOND EOF
KEY FILE EOF(INTERNAL) DAMAGED
KEY FILE (INTERNAL)EOF HAS BFEN RESET
reset key le end-of-le
--------- KEY SEQUENCE
# OF INVALID KEY VALUES DELETED
1--------10
--------- KEY SEQUENCE
# OF INVALID KEY VALUES DELETED
2 --------10
keys pointing to non-existent
data records are deleted
RECOVERY ENDS
WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING
THE KSAM FILE HAS TO BE RELOADED
In this case, the le must be reloaded in order to add the missing key values to the key le.
For a full discussion of recovery procedures in case of system failure, including how to reload
your le, refer to appendix E.
USING RECOVER OPTION
Even if a system failure does not occur, you can run KEYINFO with the RECOVER option in
order to check the le structure.
The RECOVER option forces KEYINFO to correct any end-of-le inconsistency, including
the key le end-of-le, and to delete any invalid key values. This option sets the RESET
DATE eld of the VERIFY output to the current date, and saves your user name, account,
USING KSAM UTILITIES
2-39
group, and home group, but does not increment the SYSTEM FAILURE count displayed by
VERIFY.
Note that checking each record and key in a le with a lot of data is very time consuming.
Therefore, you should not use RECOVER unless it is necessary to reconstitute your le.
For example, use KEYINFO with RECOVER to validate le TEST:
&gt;KI TEST;RECOVER
RECOVERY BEGINS
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
% OF KEY BLOCK UTILIZATION
THE LAPGEST KEY BLOCK ADDRESS
--------- KEY SEQUENCE
# OF INVALID KEY VALUES DELETED
1 ---------1
1
8
10
10
4.9
2
1 ---------0
RECOVERY ENDS
If you now run VERIFY, using option 3, you will see that the date of recovery is displayed
following the heading RESET DATE.
&gt;V
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3
DATA FILE = TEST
VERSION= A.2.4
KEY CREATED= 86/'79 13:55:23.6
KEY ACCESS= 114/'79 14: 1:14.9
KEY CHANGED=114/'79 13:55:48.8
COUNT START= 96/'79 13:55:49.2
DATA RECS =
10 DATA BLOCKS=
9 END BLK WDS=
8
DATA BLK SZ=
8 DATA REC SZ=
16 ACCESSORS=
0
FOPEN
2 FREAD
0 FCLOSE
2
FPEADDIR
0 FPEADC
0 FREADBYKEY
0
FPEMOVE
0 FSPACE
9 FFINDBYKEY
0
FGETINFO
2 FGETKEYINFO
1 FREADLABEL
0
FWRITELABEL
0 FCHECK
0 FFINDN
1
FWRITE
10 FUPDATE
0 FPOINT
0
FLOCK
0 FUNLOCK
0 FCONTROL
0
FSETM0DE
0
KEYBLK READ
3 KEYBLK WROTE
1 KEYBLK SPLIT
0
KEY FILE EOF
10 FREE KEY HD
0 SYSTEM FAILURE
0
MIN PRIME
0 MAX PRIME
9 RESET DATE
114/'79
DATA FIXED
TRUE DATA B/F
1 TOTAL KEYS
1
FIRST RECNUM
0 MIN PECSIZE
2
2-40
USING KSAM UTILITIES
USING KSAMUTIL IN BATCH MODE
A batch job can be developed on the text editor (EDITOR) and then executed with the MPE
:STREAM command. In order to distinguish the MPE commands within a streamed batch
job from those external to the job, an exclamation point (!) is used as the command prex
rather than a colon (:). KSAMUTIL commands have no command prex when executed in a
batch job.
In the job illustrated in Figure 2-1, the rst step after job initialization with the !JOB
command is to purge all KSAM and non-KSAM les that will be created within the job. This
insures that there are no les in the account with names duplicating les that will be created
programmatically with the job.
Following initialization, the rst program in the job is run. Since this program uses a KSAM
le, MANPN, this le is created with the KSAMUTIL BUILD command before the program
is executed. Note that the program is purged immediately before calling BUILD to create it.
This is done to make sure that no duplicate key or data le exists in the account.
The newly created KSAM le is used in program MAN1, which was previously compiled and
is input from the le CARDIN; output from the program goes to the le REPORT associated
with the line printer. An !EOD command follows the program. If data is entered here rather
than from the input le, then the !EOD follows the data. Any other programs in the job
stream follow the !EOD each with its own terminating !EOD. The entire job is terminated by
an !EOJ command.
Figure 2-1 is an EDITOR listing of a job entered to a le through the EDITOR program.
This job could also have been punched on cards or any other device that accepts jobs, but
in that case, the standard command prex, the colon (:), would be used. (Refer to the
EDIT/3000 Reference Manual for instructions on using the EDITOR.)
In order to run this job, you can enter the command:
:STREAM lename
where lename identies the EDITOR le where the job was saved.
Batch jobs need not be streamed, but can be entered entirely as a card deck or through some
other input device. Streaming allows you to develop and execute the job interactively at your
terminal. For a full discussion of using the :STREAM command to introduce jobs in a session,
refer to the MPE Commands Reference Manual .
Batch jobs do not support the OFFLINE parameter for the KEYDUMP, KEYINFO,
KEYSEQ, and VERIFY commands.
USING KSAM UTILITIES
2-41
Figure 2-1. EDITOR Listing of Job to be Streamed
2-42
USING KSAM UTILITIES
FCOPY UTILITY
FCOPY/3000 is the standard HP 3000 utility program that allows you to copy data from one
le to another, creating a new KSAM le is desired, to copy selected data, to make multiple
copies of the same le, or to display data in a variety of formats. With some exceptions, the
same FCOPY functions used to copy other HP 3000 les can be used to copy KSAM les.
Table 2-4 contains a summary of the FCOPY function parameters that apply to copying
KSAM les. The function parameters: SKIPEOF,IGNERR, and SUBSET alone, are not
included in this list since they are not applicable to KSAM les. Two functions are included
that apply only to copying from KSAM les: these are KEY= and NOKSAM. Otherwise, this
table includes all the standard FCOPY functions. Note that this summary is meant only to
refresh your memory and that it assumes a knowledge of FCOPY. (For a complete description
of FCOPY and its operation, refer to the FCOPY/ 3000 reference manual .)
RUNNING FCOPY
The FCOPY utility program is executed by the MPE command:
:RUN FCOPY.PUB.SYS
Program FCOPY prompts for command input with a greater-than sign (&gt;) in column 1 of the
next line. You may then enter an FCOPY command in response to the prompt. If you are
executing FCOPY in a batch job rather than in a session, you enter the command (omitting
the prompt) in column 1 of the line following the :RUN FCOPY.PUB.SYS command.
EXITING FROM FCOPY
In order to terminate FCOPY and retum to the MPE Operating System, enter the following
command:
&gt;EXIT or &gt;E
USING KSAM UTILITIES
2-43
FCOPY FROM COMMAND
Copies data from one le to another.
&gt; FROM= [fromle] ;TO= [tole] [;functionlist]
The FROM command species the le from which data is copied and the le to which
it is copied. It optionally includes one or more function specications in the functionlist
parameter.
PARAMETERS
fromle
tole
functionlist
Species the le to be copied. For a KSAM le this should be the actual
le designator. An asterisk (*), indicating the \from&quot; le designated in the
immediately preceding FCOPY command should not be used to copy KSAM
les. If fromle is omitted, the standard input device $STDIN is assumed.
Species the le to receive the data. For a KSAM le this should be the
actual le designator. If tole is specied as (dle,kle ) where dle is a data
le name and kle is a key le name, a new KSAM le is created with the
same characteristics as the fromle . The data and key values are copied from
the existing le to the new le excluding any data records tagged for deletion.
If tole is omitted, the standard list device $STDLIST is assumed. Using this
device as a \tole&quot; is a good way to display the contents of a KSAM le at
your terminal during a session and on the line printer in a batch job.
One or more keyword parameters separated by semicolons that specify
particular FCOPY functions. (Refer to Table 2-4 for a complete list.)
KSAM OPTIONS
Two keyboard options may be used with FCOPY to copy KSAM les: the KEY= option
and the NOKSAM option. These two options are mutually exclusive; they cannot both be
specied in the same FCOPY FROM command. When neither option is specied, the KSAM
fromle is copied to another le in primary key sequence. This is exactly like copying any HP
3000 le to another with FCOPY.
Table 2-5 summarizes the results of using, or omitting, the KSAM options KEY= and
NOKSAM.
KEY= OPTION. KEY= species a key whose value determines the sequence in which the
le is copied. The object of KEY= is a positive integer that identies the key by its starting
character location in the data le. The indicated key may be either the primary or an
alternate key. If the object of KEY= is zero, then the le is copied in chronological sequence
rather than in key sequence.
If KEY= and NOKSAM are both omitted, the KSAM le is copied in primary key sequence.
In this case and in the case where KEY= is specied, only active records, not those tagged for
deletion are copied.
2-44
USING KSAM UTILITIES
Table 2-4. FCOPY Functions with KSAM Files
FUNCTION LIST ENTRY*
ACTION PERFORMED
;KEY=nn
Copy active records from KSAM le in sequence
by key located at nn ; if omitted, copy le in
primary key sequence; if nn is zero, copy le in
chronological order. The KSAM EOF is used.
;NOKSAM
Copy all records, including deleted records, from
data le of KSAM le to any other le. Copy is in
chronological sequence; records must be xed
length. The data le being copied is opened as an
MPE le and the MPE end-of-le is used. Unless
the TO le is an MPE le created with l user
label, specify NOUSER LABELS.
;NEW
Copy active records and associated key values
from KSAM le to new KSAM le specied as
TO= (dle,kle ).
;EBCDICIN
;BCDICIN
;EBCDICOUT
;BCDICOUT
Translate copied data from EBCDIC to BCDIC
code to ASCII. Translate copied data from ASCII
code to EBCDIC or BCDIC.
&quot;string&quot;
;UPSHIFT ;SUBSET=
#pattern#
3 2
3
2
, column
2
3
;SUBSET= rst-record
,EXCLUDE
,#records
:last record
Convert any copied lower-case characters to
uppercase.
Copy from data le only records containing
specied \string&quot; or #pattern# starting search in
specied column or column 1. If EXCLUDE
specied, copy all data le records except those
containing \string&quot; or #pattern#
Copy from data le as many records as are
specied in #records starting with rst-record ; or
copy from rst-record through last-record
inclusive. If rst- record omitted, start at rst
sequential record in le; if #records or last-record
omitted, copy through last sequential record in
le.
;VERIFY =#errors ]
;COMPARE [= #errors ]
Verify accuracy of copy where both les are on
disc; terminate if #errors exceeded;
Compare without copying the fromle to the
tole , terminate if dierences exceed #errors .
Comparison applies only to KSAM data les.
USING KSAM UTILITIES
2-45
Table 2-4. FCOPY Functions with KSAM Files (continued)
FUNCTION LIST ENTRY*
2
32
3
;OCTAL ;CHAR ;NORECNUM
2
3
2
3
;HEX ;CHAR
;TITLE= &quot;title&quot;
3
2
32
;CHAR
;NORECNUM ;TITLE= &quot;title&quot;
2
3
;OCTAL
;NORECNUM
;HEX
3
2
;TITLE= &quot;title&quot;
ACTION PERFORMED
Display contents of \from&quot; le as octal images on
a word-by-word basis.
Display contents of \from&quot; le as hexadecimal
images on a word-by-word basis.
Display contents of \from&quot; le as character images
on a word-by-word basis.
*IGNERR, SKIPEOF, and SUBSET without parameters do not apply to \from&quot; les.
Table 2-5. KSAM Options of FCOPY
OPTION
RESULT
KEY=omitted
Copy KSAM le in primary key sequence.
KEY=n (n &gt;0)
Copy KSAM le in sequence by the key (primary or alternate) located
starting at character n of each data record (counting from rst character =
1).
KEY=0
Copy KSAM le in chronological sequence (the sequence in which records
were actually stored in the le); copy excludes records marked for deletion.
NOKSAM
Copy the data le of a KSAM le to any le in chronological sequence; copy
includes records marked for deletion.
NOKSAM OPTION. NOKSAM allows you to copy the data le of a KSAM le with
xed-length records to any MPE le, including KSAM les. All indicated records of the data
le are copied, including those tagged for deletion. When you copy a le using the NOKSAM
option, you should also specify the NOUSERLABELS option. The only exception to this rule
is if the TO le is an MPE le that you have already created with one user label.
USING FCOPY
FCOPY is useful in order to compact a KSAM le that has many records tagged for deletion.
When a le has been used for a period of time, changes and deletions may result in a high
percentage of inactive records. In order to recover the space occupied by such records, you can
copy the le to a new le with FCOPY. Since FCOPY copies only active records, records that
are not tagged for deletion, the new KSAM le has no unused space embedded among the
data records.
FCOPY can also be used to recover records tagged for deletion in a KSAM le. The FCOPY
NOKSAM option copies all records including those tagged for deletion. The rst two
characters of such records will contain the delete code rather than their original values, but
otherwise are recovered intact. This can be a useful feature in order to recover records deleted
by mistake.
Another use of FCOPY is to reload data from a damaged le to a new le. This may be
required as a result of a system failure. If you decide to reload a KSAM le following a system
2-46
USING KSAM UTILITIES
failure, you should rst run the KEYINFO command of KSAMUTIL to reset the end-of-le
markers and delete any invalid key values. If the le is still damaged and you choose to reload
it, you should use FCOPY to transfer existing records to a new undamaged KSAM le. In
this case, you use the KEY=0 option rather than the NOKSAM option, unless you want to
keep all the deleted records or the key le was lost.
FCOPY WITH NO OPTIONS. Assume a le named KSAMFILE created with one primary
key, an integer located at character 21. Since many records were tagged for deletion in the le,
it is time to copy the active records to a new le, You may either create a new KSAM le
with the BUILD command as shown in example 1, or use FCOPY to create the new KSAM
le as shown in example 2. In either case, you should purge the original le (KSAMFILE in
the examples) and then rename the new le (KSAMFIL2) with the data and key le names of
the original le so that any programmatic references to the le need not be changed.
You may also use FCOPY to create an empty KSAM le with all the characteristics of an
existing le, but with no data. The method for doing this is shown in example 3.
1. Create new le with BUILD:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD KSAMFIL2;KEYENTITY =KFIL2;KEY=I,21,2 &lt;-------- create &quot;to&quot;le
&gt;EXIT
:RUN FCOPY.PUB.SYS
&gt;FROM=KSAMFILE;TO=KSAMFIL2 &lt;----------- copy in primary key sequence
&gt;EXIT
:RUN KSAMUTIL.PUB.SYS
&gt;PURGE KSAMFILE &lt;----------------- purge &quot;from&quot; le after copy
KSAMFILE.KSAM.DATAMGT &amp; KFILE PURGED
&gt;RENAME KSAMFIL2,KSAMFILE|
| &lt;--------- rename copied le with old le names
&gt;RENAME KFIL2,KFILE
|
&gt;EXIT
:
2. Use FCOPY to create new le:
:RUN FCOPY.PUB.SYS
&gt;FROM=KSAMFILE;TO=(KSAMFIL2,KFIILE2)
&gt;EXIT
:RUN KSAMUTIL.PUB.SYS
&gt;PURGE KSAMFILE
KSAMFILE.KSAM,DATAMGT &amp; KFILE PURGED
&gt;RENAME KSAMFIL2,KSAMFILE
&gt;RENAME KFILE2,KFILE
&gt;EXIT
:
You may specify the ;NEW function in the FCOPY FROM command for purposes of
documentation. Its inclusion or omission does not aect the command in any way.
This method not only creates the new KSAM le, but also copies all the data from the
existing le to the new le (except records marked for deletion). Example 3 below, shows
how you can create a KSAM le with exactly the same specications as an existing le but
with no data.
3. Use FCOPY to build a new le with no data:
:RUN FCOPY.PUB.SYS
&gt;FROM=KSAMFILE; TO=(KSAMFIL3,KFILE3); SUBSET=1,0 &lt;---0 RECORDS PROCESSED *** 0 ERRORS
copy 0 records
USING KSAM UTILITIES
2-47
The new le, KSAMFIL3, is created with exactly the same specications as the existing
le KSAMFILE, but with no data. This is easier than building the le with the BUILD
command, but should be used only if the new le is to have keys in the same position and
the same length as the existing le.
Following any of these operations, only active records are contained in the new KSAM
les. These records are stored in primary key sequence in the data le; that is, the new
chronological and the primary key sequences axe the same. If you prefer to maintain the
original chronological sequence, then you can use the KEY=0 option.
4. Use FCOPY to add data to an existing le:
Before running FCOPY to add new records to a le that contains data, make sure that le
(the TO le) is opened for either APPEND or INOUT access. Otherwise, FCOPY will
open the TO le for write-only access causing the end-of-le to be reset to zero and any
existing data to be lost. For example:
:FILE A = KSAMFILE,OLD;ACC = APPEND
or
ACC = INOUT
:RUN FCOPY.PUB.SYS
&gt;FROM = NEWDATA ;TO = *A
The data in the le NEWDATA is appended to the data in the existing le, KSAMFILE,
in primary key sequence (the default).
2-48
USING KSAM UTILITIES
FCOPY WITH KEY = OPTIONS.
1. Assume that a company's employee records have been maintained in sequence by
social-security-number in a KSAM le, EMPLOY, but a new policy requires that they be
maintained in sequence by employee number. FCOPY can be used to transfer the data
to a new le, EMPLOY2, in which all employees are re-ordered by their unique employee
numbers.
Assume EMPLOY was created with the following command:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD EMPLOY;REC=3000;KEYENTITY =EMPKEY;&amp;
&gt;
KEY=B,3,11;&amp; &lt;--------------- primary key (social-security-number)
&gt;
KEY=B,14,5;&amp; &lt;------------ alternate key (employee number)
&gt;
KEY=B,19,30,,DUP &lt;------ alternate key (name)
&gt;EXIT
Before copying and resequencing le EMPLOY, a new KSAM le is built:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD EMPLOY2;REC=3000;KEYENTITY =EMPKEY2;&amp;
&gt;
KEY=B,14,5;&amp; &lt;------------ primary key (employee
&gt;
KEY=B,19,30,,DUP &lt;----- alternate key (name)
&gt;EXIT
number)
There is no need for the new key le to retain the same structure as the key le of the
copied le. The primary key in EMPLOY has been dropped from EMPLOY2; although the
socialsecurity-number remains in the data le, it is no longer a key. An alternate key in
EMPLOY, the employee's identication number, is the primary key in EMPLOY2.
Once the new KSAM le has been created, you can copy the old le EMPLOY to the new
le EMPLOY2 in the new sequence:
:RUN FCOPY.PUB.SYS
&gt;FROM=EMPLOY;TO=EMPLOY2;KEY=14
&gt;EXIT
|
|-----------------------|
|column number of key used to
sequence EMPLOY2
To avoid changing programs that reference the le EMPLOY, you can rename EMPLOY2
with the name EMPLOY, rst purging the old le EMPLOY:
:RUN KSAMUTIL.PUB.SYS
&gt;PURGE EMPLOY
KSAMFILE EMPLOY.KSAM.DATAMGT &amp; EMPKEY PURGED
&gt;RENAME EMPLOY2,EMPLOY &lt;-------------- rename
&gt;RENAME EMPKEY2,EMPKEY &lt;-------------- rename
&gt;EXIT
data le
key le
2. Another use of FCOPY is to copy a selected portion of one KSAM le to another. For
example, using the same le EMPLOY used in previous examples, you can copy all the
employee records whose last names begin with the letter A into a new le sequenced by
employee name:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD EMPLOYA;KEYENTITY =AKEY;KEY=B,19,30,,DUP
&gt;EXIT
:RUN FCOPY.PUB.SYS
&gt;FROM=EMPLOY;TO=EMPLOYA;KEY=19;SUBSET=&quot;A&quot;,19
&gt;EXIT
USING KSAM UTILITIES
2-49
The new le EMPLOY is sequenced by the key starting in column 19 (employee name) and
only contains records for employees whose last names start with A.
3. If you want to copy the KSAM le in chronological sequence, you can use the KEY=0
option. Since this option copies only active records, it can be used to compact a le in
which many records are tagged for deletion while retaining the chronological order in which
the le was created. It is also the preferred option for reloading a KSAM le after a system
failure.
Assume the new le EMPLOYX has the identical structure to the le EMPLOY used in
the previous examples:
:RUN FCOPY.PUB.SYS
&gt;FROM=EMPLOY;TO=EMPLOYX;KEY=0
&gt;EXIT
The new le is identical in its chronological sequence to the old le, but contains only
active records.
4. To nd out how many records are currently active in a KSAM le, you can use FCOPY as
follows:
:RUN FCOPY.PUB.SYS
&gt; FROM=KSAMFILE ;TO=$NULL
N RECORDS PROCESSED *** 0 ERRORS (where N is the number of active records
in the KSAM file)
&gt;EXIT
Only the active records (those not marked for deletion) will be listed as present in the le.
(You can also calculate the number of active records by looking at the VERIFY listing,
option 3, and subtracting the number of FREMOVEs from the FWRITES.)
FCOPY WITH NOKSAM OPTION.
1. Using NOKSAM, you can copy the data le of a KSAM le to another le. The records are
copied in chronological sequence. Since NOKSAM copies records marked for deletion as
well as active records, it provides a method for recovering the data in any records marked
for deletion. For example, if certain records in le EMPLOY were incorrectly marked for
deletion, the NOKSAM option could be used to copy the entire data le to a new le
including the inactive records.
Using the SUBSET parameter of FCOPY, you can copy only those records marked for
deletion. In the following example, all deleted records are listed on the line printer:
pattern of all 1's in 1st 2 characters
|
|
:FILE X; DEV=LP
|
:RUN FCODY.PUB.SYS
ESC/---------/&gt;FROM=EMPLOY;TO=*X;SUBSET=#%377,%377#,1;NOKSAM;OCTAL;CHAR;NORECNUM;&amp;
&gt;TITLE=&quot;RECOPDS DELETED FROM THE FILE, EMPLOY&quot;
When records are deleted from a KSAM data le, a pattern of all 1's is written to the rst
two characters of the deleted record. (ln each character this pattern can be represented as
the octal value %377.) If you want to be able to recover key data from deleted records in
this manner, you should avoid placing key data in the rst two characters of a data record.
Note that you should not use the NOKSAM option to copy a KSAM le with variable-length
records to another KSAM le. Also, if NOKSAM must be used to reload a le after a system
crash (for instance, because the key le was lost), you should use the SUBSET option to copy
2-50
USING KSAM UTILITIES
only valid records. Normally, you use the KEY=0 option to reload KSAM les after a system
failure.
(Refer to appendix E, Recovery From System Failure, for a full discussion of using FCOPY to
reload a KSAM le following a system failure.)
COPYING VARIABLE-LENGTH KSAM FILES
You can copy a variable-length KSAM data le by rst copying it to an MPE le and then
copying the MPE le to a new KSAM le.
First use the MPE :LISTF,2 command to list the attributes of the KSAM data le. Then
use the MPE :BUILD command to build an MPE le with a record length two words less
than that of the KSAM data le, a blocking factor the same as the data le (always 1),
variable-length records, and the same record limit as the KSAM data le.
Copy the KSAM data le to the MPE variable-length le on a block-by-block basis, as follows:
:FILE DATAFILE; NOBUF
:FILE MPEFILE; NOBUF
:FCOPY FROM= *DATAFILE; TO= *MPEFILE; NOKSAM;NOUSERLABELS
Copy the variable-length records from the MPE le to a newly created KSAM le omitting
the deleted records.
FCOPY FROM= MPEFILE;TO= KSAMFILE;SUBSET=
#%377, %377#,,EXCLUDE
DISPLAY COPIED FIIES ON $STDLIST. When you omit the \to&quot; le from the TO=
specication, the standard output device is assumed. This allows you to list the contents of
the KSAM le at your terminal in a session or on the line printer in a job.
Assume the le JNAMES with a primary key (last name) starting in character 11 and three
alternate keys: a phone number starting in character 21, a city name starting in character 53,
and a zip code starting in character 67.
1. If KEY= is omitted, the le is listed in primary key, order:
&gt;FROM=JNAMES:TO=;KEY=)
JEANNE
/ALOGICAL 226-0295 4942 COUSIN CT
POLLY
|CHROMATIC 267-1412 1148 COLORFUL CT
ANNA
|FORA
253-5246 9283 TROCHAIC TRAIL
ANNE
|HOWE
372-4328 6547 EXUBERANCE WY
HY
|KUVERSE
267-8961 650
LOTUS BLOSSOM WY
ANNA |--|LOGUE
224-8934 1707 INVERSE WY
ARTHUR| |MOMITER
443-5346 1554 MERCURY ST.
CLARA | |NETTE
243-4493 2667 GOODMAN DR
RHEA | |PREYSELLE 365-8551 10879 REVIEW ROAD
KURT | |REMARQUE 243-1043 34
BRIEF ST
MIKE | |ROMETER
269-1712 1681 MACHINIST
TRUDY | \TEKTIFF
255-1005 17155 POIROT PL
EOF FOUND IN FROMFILE AFTER RECORD 11
|
|
12 RECORDS PROCESSED *** 0 ERRORS
|
|
|
SUNNYVALE
SAN JOSE
SAN JOSE
CAMPBELL
SAN JOSE
MOUNTAINVIEW
MILPITAS
ALVISO
SAN JOSE
MILPITAS
SUNNYVALE
CAMPBELL
95054
95130
95131
95112
95136
95051
94173
95143
95070
94062
95112
95121
ascending order by primary key
Use SUBSET to list selected portions of the le, for example, to list the rst two records in
primary key sequence:
USING KSAM UTILITIES
2-51
&gt;FROM=JNAMES;TO=;KEY=11;SUBSET=0,2
JEANNE
ALOGICAL 226-0295 4942 COUSIN CT
SUNNYVALE
POLLY
CHROMATIC 267-1413 1148 COLORFUL CT SAN JOSE
95054
95030
2 RECORDS PROCESSED *** 0 ERRORS
2. If KEY=\primary key location&quot;, the le is listed in primary hey order:
&gt;FROM=JNAMES:TO=;KEY=)
JEANNE
ALOGICAL 226-0295 4942 COUSIN CT
SUNNYVALE
POLLY
CHROMATIC 267-1412 1148 COLORFUL CT
SAN JOSE
ANNA
FORA
253-5246 9283 TROCHAIC TRAIL
SAN JOSE
ANNE
HOWE
372-4328 6547 EXUBERANCE WY
CAMPBELL
HY
KUVERSE
267-8961 650
LOTUS BLOSSOM WY SAN JOSE
ANNA
LOGUE
224-8934 1707 INVERSE WY
MOUNTAINVIEW
ARTHUR
MOMITER
443-5346 1554 MERCURY ST.
MILPITAS
CLARA
NETTE
243-4493 2667 GOODMAN DR
ALVISO
RHEA
PREYSELLE 365-8551 10879 REVIEW ROAD
SAN JOSE
KURT
REMARQUE 243-1043 34
BRIEF ST
MILPITAS
MIKE
ROMETER
269-1712 1681 MACHINIST
SUNNYVALE
TRUDY |&gt;TEKTIFF
255-1005 17155 POIROT PL
CAMPBELL
EOF FOUND IN FROMFILE AFTER RECORD 11
|
|
12 RECORDS PROCESSED *** 0 ERRORS
|
|
|
|byte location 11 (same sequence as previous example)
95054
95130
95131
95112
95136
95051
94173
95143
95070
94062
95112
95121
3. If KEY=\alternate key location&quot;, the le is listed in sequence by that key:
&gt;FROM=JNAMES; TO=; KEY=67 /
KURT
REMARQUE 243-1043
ARTHUR MOMITER
443-5346
DOLLY CHROMATIC 267-1413
ANNA
LOGUE
224-9934
JEANNE ALOGICAL 226-0295
RHEA
PREYSELLE 365-9551
ANNE
HOWE
372-4328
MIKE
ROMETER
269-1712
TRUDY TEKTIFF
255-1005
ANNA
FORA
253-5246
HY
KUVERSE
267-8961
CLARA NETTE
243-4493
EOF FOUND IN FROMFILE AFTER
34
BRIEF ST
1554 MERCURY ST
1148 COLORFUL CT
1707 INVERSE WY
4942 COUSIN CT
10879 REVIEW ROAD
6547 EXUBERANCE WY
1681 MACHINIST DR
17155 POIROT PL
9283 TROCHAIC TRAIL
650
LOTUS BLOSSOM WY
2667 GOODMAN DR
RECORD
MILPITAS
/94062
MILPITAS
|94173
SAN JOSE
|95030
MOUNTAIN VIEW |95051
SUNNYVALE
|95054
SAN JOSE
|95070
CAMPBELL
|95112
SUNNYVALE
|95112
CAMPBELL |---|95121
SAN JOSE | |95131
SAN JOSE | |95136
ALVISO
| \95143
|
|
|
|
12 RECORDS PROCESSED *** 0 ERRORS
|
|
|
|
output in ascending order--------|
|
by key in byte location 67--------------|
Use SUBSET= to list all the records with the characters \SUNNYVALE&quot; starting in
column 53; sequence is by alternate key in location 67:
&gt;FROM=JNAMES;TO=;KEY=67;SUBSET=&quot;SUNNYVALE&quot;,53
JEANNE
ALOGICAL 226-0295 4942 COUSIN CT
MIKE
ROMETER 269-1712 1681 MACHINIST DR
EOF FOUND IN FROMFILE AFTER RECORD 11
2 RECORDS PROCESSED *** 0 ERRORS
2-52
USING KSAM UTILITIES
SUNNYVALE
SUNNYVALE
95054
95112
Another example using SUBSET= lists ve records starting with the fourth record;
sequence is by alternate key in location 67:
records numbered from O
|
|
|
&gt;FROM=JNAMES;TO=;KEY=67;SUBSET=3,5
ANNA
LOGUE
224-9934 1707
JEANNE ALOGICAL
226-0295 4942
RHEA
PREYSELLE
365-8551 10789
ANNE
HOWE
372-4328 6547
MIKE
ROMETER
269-1712 1681
5 RECORDS PROCESSED *** 0 ERRORS
INVERSE WY
COUSIN CT
REVIEW ROAD
EXUBERANCE WY
MACHINIST DR
MOUNTAIN VIEW
SUNNYVALE
SAN JOSE
CAMPBELL
SUNNYVALE
95051
95054
95070
95112
95112
4. If KEY=O, the le is copied in chronological order:
&gt;FROM=JNAMES; TO=; KEY=0
ARTHUR
MOMITER 443-5346
TRUDY TEKTIFF
255-1005
ANNA
LOGUE
224-8934
CLARA NETTE
243-4493
ANNE
HOWE
372-4328
JEANNE ALOGICAL 226-0295
HY
KUVERSE
267-8961
MIKE
ROMETER
269-1712
ANNA
FORA
253-5246
POLLY CHROMATIC 267-1413
RHEA
PREYSELLE 365-9551
KURT
REMARQUE 243-1043
EOF FOUND IN FROMFILE AFTER
1554
17155
1707
2667
6547
4942
650
1681
9283
1148
10879
34
RECORD
MERCURY ST
POIROT PL
INVERSE WY
GOODMAN DR
EXUBERANCE WY
COUSIN CT
LOTUS BLOSSOM WY
MACHINIST DR
TROCHAIC TRAIL
COLORFUL CT
REVIEW ROAD
BRIEF ST
11
MILPITAS
CAMPBELL
MOUNTAIN VIEW
ALVISO
CAMPBELL
SUNNYVALE
SAN JOSE
SUNNYVALE
SAN JOSE
SAN JOSE
SAN JOSE
MILPITAS
94173
95121
95051
95143
95112
95054
95136
95112
95131
95130
95070
94262
12 RECORDS PROCESSED *** 0 ERROR
USING KSAM UTILITIES
2-53
:STORE AND :RESTORE COMMANDS
The :STORE and :RESTORE commands are used primarily to provide back-up for user
disc les. The le or set of les is copied to magnetic tape or serial disc by the :STORE
command in a special format that permits the serial device to be read back onto disc with the
:RESTORE command. The use of these two commands for KSAM les is identical to their
use with any HP 3000 les. (Refer to the MPE Commands Reference Manual for a complete
description of the :STORE and :RESTORE commands.)
STORE
Stores KSAM le on magnetic tape or serial disc.
:STORE lereference1,lereference2 [,...] ; storele
[;SHOW] [;FILES=maxles]
This command is used to store one or more disc les onto magnetic tape or serial disc. When
used to store KSAM les, both the data le and the key le must be specied.
PARAMETERS
lereference1
lereference2
storele
SHOW
FILES=
maxles
2-54
Actual le designator of data le; specied in the following format:
lename [/lockword] [.groupname [.accountname] ]
where each subparameter is a name consisting of from 1 to 8 alphanumeric
characters beginning with a letter.
(Required parameter for KSAM les.)
Actual le designator of key le; specied in exactly the same format as
lereference1 .
(Required parameter for KSAM les.)
Name of destination device le onto which the stored les are written. This
can be any magnetic tape or serial disc le from the output set. This le
must be referenced in the back-reference (*) format; this format references a
previous :FILE command that identies the le as a magnetic tape or serial
disc le.
(Required parameter.)
Request to list names of le stored. If SHOW is omitted, total number of les
stored, names of les not stored, and number of les not stored are listed.
(Optional parameter.)
Maximum number of les that may be stored. If omitted, 4000 is specied by
default.
(Optional parameter.)
USING KSAM UTILITIES
USING THE :STORE COMMAND
Before issuing a :STORE command, you must identify the storele as a magnetic tape or as a
serial disc with the :FILE command using the following format:
:FILE formaldesignator [=lereference] ;DEV=device
The device parameter must indicate the device class name or logical unit number of a
magnetic tape or serial disc unit, All other parameters for storele are supplied by the
:STORE command executor; if you attempt to supply any of these yourself, MPE rejects the
:STORE command.
If you press the BREAK key during the store operation, the operation stops after storing the
current le and further output is suppressed.
For example, to copy KSAM le KSAMDATA to a magnetic tape le named SAVE FILE
:FILE T=SAVEFILE;DEV=TAPE
:STORE KSAMDATA,KSAMKEY;*T
^
^
|
|
|
|
data le
key le
Note that both the data and key le must be specied in order to store the entire KSAM le.
If you want to copy this same le to a serial disc, use the following command sequence:
:FILE SD=SAVEFILE;DEV=SDISC
:STORE KSAMDATA, KSAMKEY;*SD
USING KSAM UTILITIES
2-55
RESTORE
Restores KSAM le from magnetic tape or serial disc.
:RESTORE restorele ;lereference1,lereference2[, . . .] [;KEEP]
[;DEV=device] [;SHOW] [;FILES=maxfiles]
Restores to disc, one or more les stored o-line to magnetic tape or serial disc by the
:STORE command. To restore a KSAM le, both the data le and the key le names must be
specied.
PARAMETERS
restorele
lereference1
lereference2
KEEP
DEV=device
2-56
Name of magnetic tape or serial disc le on which les to be retrieved now
reside. This le must be referenced in the backence (*) format; this format
references a previous :FILE command that denes the le as a magnetic tape
or serial disc le. A message is output to the Console Operator requesting
him to mount the magnetic tape or serial disc platter identied by the
lereference parameter in the :FILE command, and allocate the tape unit or
disc platter to you.
(Required parameter.)
Acual le designator identifying the KSAM data le, specied in the format:
lename [/lockword] [.groupname [.accountname] ]
where each subparameter is a name consisting of from 1 to 8 alphanumeric
characters beginning with a letter.
(Required for KSAM les.)
Actual le designator identifying the KSAM key le, specied in the same
format as lereference1 .
(Required for KSAM les.)
Specication that if a le referenced in the :RESTORE command currently
exists on disc, the le on disc is kept and the corresponding le on tape
or serial disc is not copied into the system. If KEEP is omitted, and an
identically-named le exists in the system, that le is replaced with the one on
the tape or serial disc. If KEEP is omitted, and a le on tape or serial disc is
eligible for restoring and a le of the same name exists on disc, and this disc
le is busy, the disc le is kept and the tape or serial disc le is not restored.
(Optional parameter.)
Device class name or logical number of device on which les are to be
restored. (This name is also written on the label of each le restored.) If you
omit this parameter, MPE attempts to replace the les on a device of the
same class (or logical device number) as that of the device on which the le
was created, If this attempt fails, perhaps because the device class specied
does not exist or the tape or serial disc was created on a previous version of
this computer, MPE attempts to replace each le on a disc of the same type
(xed or moving -head) and subtype as that on which it was created. If this
fails, MPE attempts to restore the le to a device of class name DISC. If this
fails, the le is not restored. If the KSAM le was created with the data le
USING KSAM UTILITIES
and the key le on dierent devices, then RESTORE twice using dierent
DEV=device in each RESTORE.
SHOW
(Optional parameter.)
Request to list names of restored les. If you omit SHOW, only total number
of les restored, list of les not restored (and the reason each was not
restored), and count of les not restored, are listed.
FILES=
(Optional parameter.)
Maximum number of les that may be restored. If omitted, 4000 is assigned
by default.
maxles
(Optional parameter.)
USING THE :RESTORE COMMAND
Before issuing a :RESTORE command you must identify tapele as a magnetic tape or serial
disc le with the :FILE command:
:FILE formaldesignator [=lereference] ;DEV=device
The device parameter must indicate the device class name or logical unit number of a
magnetic tape or a serial disc unit. No other parameters than these may be supplied. If you
attempt to supply more, the :RESTORE command is rejected.
To retrieve from the magnetic tape le SAVEFILE, the KSAM le KSAMDATA that includes
data le (KSAMDATA) and key le (KSAMKEY):
:FILE T=SAVEFILE;DEV=TAPE
:RESTORE *T;KSAMDATA,KSAMKEY;KEEP;DEV=DISC;SHOW
To retrieve this same le from the serial disc STORDISC, enter the commands:
:FILE SD=STORDISC; DEV=SDISC
:RESTORE*SD;KSAMDATA,KSAMKEY;KEEP;DEV=DISC;SHOW
Note that both the data le and the key le must be specied in order to restore the entire
KSAMI le.
If the KSAM le currently saved on magnetic tape or serial disc was originally created with
the data le resident on one device and the key le resident on a dierent device, then this
capability can be retained only if you RESTORE twice using dierent DEV= specications in
each command.
For example:
:FILE T:DEV=TAPE
:RESTORE *T;KSAMDATA;DEV=DISCONE
:RESTORE *T;KSAMKEY;DEV=DISCTWO
Upon successful completion, KSAMDATA will be restored from tape le T to a device class
identied as DISCONE, and KSAMKEY will be restored from tape le T to a device class
identied as DISCTWO. You would do this only in the case where the le was originaly
created using the BUILD command specication DEV=DISCONE for the data le, and
KEYDEV=DISCTWO for the key le.
USING KSAM UTILITIES
2-57
3
USING KSAM FILES IN COBOL PROGRAMS
OVERVIEW
KSAM les are accessed from COBOL programs through calls to a set of procedures.
These procedures allow you to open, open for shared access, write records to, read records
from, lock, unlock, update, position, and close a KSAM le. (Refer to Table 3-1 for a list
of the procedures and their associated functions.) The COBOL procedures provided with
KSAM/3000 correspond to the INDEXED I-O module statements in COBOL 74.
Note: The following applies when using KSAM with COBOL.
The KSAM le must be created with KSAMUTIL's &gt;BUILD command.
To access a KSAM le in chronological order, the KSAM le must be copied to a
non-KSAM le.
KSAM permits duplicate primary keys as an extension to the ANSII standards.
In HP COBOL/3000, the procedures that are used to access KSAM les dier in form
from the COBOL input/output statements used to access non-KSAM les. The KSAM
interface procedures use parameters for information that would otherwise be specied in the
FILE-CONTROL paragraph and the FD entry of the DATA DIVISION. These parameters are
themselves dened in the WORKING-STORAGE section of the DATA DIVISION. The main
restriction on the KSAM interface call parameters is that they must start on word boundaries.
USING KSAM FILES IN COBOL PROGRAMS
3-1
Table 3-1. KSAM Procedures for COBOL Interface
PROCEDURE
NAME
PARAMETERS
FUNCTION
PAGE
CKCLOSE
letable
status
Terminates processing of KSAM le identied by
letable .
3-12
CKDELETE
letable
status
Logically removes record from KSAM le; deleted
record is identied by previous read.
3-13
CKERROR
status ,
result
Converts numeric value returned in status to
character string result .
3-17
CKLOCK
letable
status
lockcond
Dynamically locks le opened for shared access,
conditionally depending on lockcond .
3-18
CKOPEN
letable
status
Initiates processing of le named in letable ;
returns le number to rst word of letable .
3-20
CKOPENSHR
letable
status
Initiates processing with dynamic locking and
shared access of le named in letable .
3-25
CKREAD
letable
status
record
recordsize
Reads next sequential record from KSAM le
identied by letable into record .
3-26
CKREADBYKEY
letable
status
record
key
keyloc
recordsize
Reads into record rst record with a key in
location keyloc whose value matches that of key ,
from KSAM le identied by letable .
3-29
CKREWRITE
letable
status
record
recordsize
Replaces last sequential record read by CKREAD,
or replaces record whose primary key matches the
value of key item in record , with the contents of
record .
3-32
CKSTART
letable
status
relop
key
keyloc
keylength
Positions record pointer in preparation for a
sequential read to the rst record with a key in
location keyloc whose value has the relation relop
to the value of key .
3-36
CKUNLOCK
letable
status
Unlocks le dynamically locked by CKLOCK.
3-40
Writes record of length recordsize from record to a
KSAM le identied by letable .
3-42
CKWRITE
3-2
letable
status
record
recordsize
USING KSAM FILES IN COBOL PROGRAMS
CALLING A KSAM PROCEDURE
The KSAM interface procedures (refer to Table 3-1 for a complete list) are called using a
CALL statement of of the following general form:
CALL &quot;name&quot; USING letable,status [,parameter[,. . .] ]
Where:
\name&quot;
letable
status
parameter
identies the procedure to which control is transferred.
an 8-word table that identies the le by name and in which access mode and
input-output type are specied, and to which is returned the le number on
open, and a code identifying the previous operation.
one word to which a two-character code is returned that indicates the status
of the input/output operation performed on the le by the called procedure.
one or more parameters, depending on the particular procedure called, that
further dene operations to be performed on the le.
The rst two parameters, letable and status , are included in every KSAM procedure call
except CKERROR; other parameters may be specied depending on the particular procedure.
If a parameter is included in the procedure format, then it must be included in the procedure
call. All parameters are required.
Another characteristic of KSAM procedure call parameters is that they must always start
on a word boundary. In order to assure this, the parameters should be dened in the
WORKING-STORAGE SECTION as 01 record items, 77 level elementary items, or else the
SYNCHRONIZED clause should be included in their denition.
A literal value cannot be used as a parameter to these procedures. Any value assigned to a
data item used as a parameter is passed to the procedure, but a literal value causes an error.
Depending on the procedure, certain data items may be assigned values as a result of
executing the procedure.
Note
There are no COBOL procedures to read a KSAM le in chronological order
or to access a record by its chronological record number. (Chronological order
is the order in which the data records were written to the le.)
USING KSAM FILES IN COBOL PROGRAMS
3-3
FILETABLE PARAMETER
The rst parameter in every KSAM procedure call must be letable , a table describing the le
and its access. This table is dened in the WORKING-STORAGE SECTION of the COBOL
program. It requires eight words as illustrated in Figure 3-1.
Figure 3-1. Filetable Structure
lenumber
lename
input-output
type
access mode
A number identifying the le returned by the CKOPEN procedure after
the le named in words 2-5 has been successfully opened. After the le is
closed by CKCLOSE, lenumber is reset to 0. (This number should be
set to zero when the le table is initially dened.) It must be dened as a
COMPUTATIONAL item.
The name of the KSAM le. This name is the actual designator assigned to
the le when it is created with the KSAMUTIL BUILD command; lename
may be a formal designator if it is equated to the actual designator in a :FILE
command.
A code that limits the le access to input only, output only, or allows both
input and output:
0 = input only
1 = output only
2 = input-output
It must be dened as a COMPUTATIONAL item.
A code that indicates how the le will be processed: sequentially only,
randomly only, or either (dynamically):
0 = sequential only
1 = random only
2 = dynamic (sequential or random)
It must be dened as a COMPUTATIONAL item.
3-4
USING KSAM FILES IN COBOL PROGRAMS
FILETABLE
previous
operation
lock/unlock
A code in the right byte of word 8 of the le table indicating the previous
successful operation:
0 = previous operation unsuccessful or there has been no previous operation
on this le
1 = CKOPEN successful
2 = CKSTART successful
3 = CKREAD successful
4 = CKREADBYKEY successful
5 = CKDELETE successful
6 = CKWRITE successful
7 = CKREWRITE successful
8 = CKCLOSE successful
9 = CKOPENSHR
This eld should be set to zero when the le table is initially dened and
thereafter should not be altered by the programmer. It must be dened as a
COMPUTATIONAL item.
A code in the left byte of word 8 of the le table that indicates whether
a CKLOCK or CKUNLOCK has been performed successfully since the
operation specied in previous operation:
10 = CKLOCK successful
11 = CKUNLOCK successful
EXAMPLE
A sample le table denition might be:
WORKING-STORAGE SECTION.
01 KSAM FILE.
02 FILENUMBER
02 FILENAME
02 I-O-TYPE
02 A-MODE
02 PREV-0P
PIC
PIC
PIC
PIC
PIC
S9(4) COMP
X(8) VALUE
S9(4) COMP
S9(4) COMP
S9(4) COMP
VALUE 0.
&quot;KSAMFILE&quot;.
VALUE 0.
VALUE 0.
VALUE 0.
The le table identies a le created with the name KSAMFILE as a le to be opened for
sequential input only. The values of I-O-TYPE and A-MODE can be changed following a call
to CKCLOSE for the le.
USING KSAM FILES IN COBOL PROGRAMS
3-5
STATUS PARAMETER
The status parameter is a two-character item to which the status of the input-output
operation is returned. It is always the second parameter in a KSAM procedure call. The
status parameter must be dened in the WORKING-STORAGE SECTION of the COBOL
program.
Status consists of two separate characters: the left character is known as status-key-1, and the
right is known as status-key-2.
/---left character----\/---right character----\
|----------------------|------------------------|
|
|
|
| &quot;status-key-1&quot;
|
&quot;status-key-2&quot;
|&lt;-----status word
|----------------------|------------------------|
The possible combinations of the left and right characters of parameter status are shown in
Table 3-2 The values of status-key-2 (the right character) shown in the table are the only valid
values for status-key-2.
Table 3-2. Valid
status
Parameter Character Combinations
Then right character of status
(status-key-2) may equal:
If left character of status
(status-key-1) equals:
\0&quot; (successful completion)
\0&quot; (no further information)
\2&quot; (duplicate key)
\1&quot; (at end)
\0&quot; (no further information)
\2&quot; (invalid key)
\1&quot; (sequence error)
\2&quot; (duplicate key)
\3&quot; (no record found)
\4&quot; (boundary violation)
\3&quot; (request denied)
\0&quot; (lock denied)
\1&quot; (unlock denied)
\9&quot; (le system error)
\n &quot; where n is the MPE le system error code.
Combining status-key-1 with status-key-2, the following values may be returned to the status
parameter as a whole:
If status =
Successful completion |
\00&quot;
The current input/output operation was completed successfully; no duplicate
keys were read or written.
= \02&quot;
Successful completion ; Duplicate key |
For a CKREAD or a CKREADBYKEY call, the current alternate key has the
same value as the equivalent key in the sequentially following record; duplicate
keys are allowed for the key. For a CKWRITE or CKREWRITE call, the
record just written created a duplicate key value for at least one alternate key
for which duplicates are allowed.
3-6
USING KSAM FILES IN COBOL PROGRAMS
STATUS
If status =
\10&quot;
= \21&quot;
= \22&quot;
= \23&quot;
= \24&quot;
= \30&quot;
= \31&quot;
= \9n &quot;
At End condition |
In a sequential read using CKREAD, no next logical record was in the le.
Invalid key; Sequence error |
A call to CKWRITE attempted to write a record with a key that is not in
sequentially ascending order, to a le opened for sequential access.
A call to CKREWRITE was attempted but the primary key value was
changed by the program since the previous successful call to CKREAD.
Invalid key; Duplicate key |
An attempt was made to write or rewrite a record with CKWRITE or
CKREWRITE and the record would create a duplicate key value for a key
where duplicates are prohibited.
Invalid key; No record found |
An attempt was made with CKSTART or CKREADBYKEY to access a
record identied by key, but no record is found with the specied key value at
the specied location.
Invalid key; Boundary violation |
An attempt was made with a call to CKWRITE to write past the externally
dened boundaries of the le; that is, to write past the end-of-le.
Lock denied |
An attempt was made to lock a le already locked by another process; or le
was not opened with dynamic locking allowed.
Unlock denied |
An attempt was made to unlock a le with CKUNLOCK, but the le had not
been locked by CKLOCK.
File system error |
A call to an input/output procedure was unsuccessful as a result of a le
system error, not one of the error conditions dened for the other status
values. The value of status-key-2 (n ) is a binary number between 0 and 255
that corresponds to an MPE le system error code (refer to appendix A).
To convert this binary value to numeric display format, call the CKERROR
routine (described next in this section).
USING KSAM FILES IN COBOL PROGRAMS
3-7
STATUS
USING STATUS
The value of status can be tested as a whole, or the two characters can be tested separately
as status-key-1 and status-key-2 . In any case, the status of each call should be tested
immediately following execution of the call. Unless the rst character of status = \0&quot;, the call
was not successful.
For example, a sample status parameter denition might be:
WORKING-STORAGE SECTION.
.
.
.
01 STAT.
02 STATUS-KEY-1 PIC X.
02 STATUS-KEY-2 PIC X.
These items can then be referenced in the PROCEDURE DIVISION. For example: to test
only the rst character:
IF STATUS-KEY-1 NOT = &quot;0&quot; THEN
GO TO &quot;ERROR-ROUTINE&quot;.
To test the entire status word:
IF STAT = &quot;23&quot; THEN
DISPLAY &quot;RECORD NOT FOUND&quot;.
Note that the word STATUS is reserved.
KSAM LOGICAL RECORD POINTER
Many of the KSAM procedures use a logical record pointer to indicate the current record in
the le. This pointer points to a key value in the key le that identies the current record in
the data le. The particular key used, if the le has more than one key, is the key specied in
the current procedure or the last procedure that referenced a key.
Procedures that use pointers are either pointer-dependent or pointer-independent . Pointerent
procedures expect the pointer to be positioned at a particular record in order to execute
correctly. Pointer-independent procedures, on the other hand, execute regardless of where the
pointer is positioned and, in most cases, they position the pointer. (Refer to Table 3-3 for a
summary of those procedures that either position the pointer or are dependent on the pointer
position.)
3-8
USING KSAM FILES IN COBOL PROGRAMS
Table 3-3. Positioning the Logical Record Pointer
Procedure
Name
PointerDependent
Position of Pointer After
Execution of Procedure
CKSTART
NO
Points to key whose value was specied in call.
CKREADBYKEY
NO
Points to key whose value was specied in call.
CKWRITE
NO
Points to key whose value is next in key sequence to
key value in record just written.
CKREAD
YES
Pointer remains positioned to key value for record just
read; unless next call is to CKREAD, or to
CKREWRITE followed by CKREAD, in which case,
next CKREAD moves pointer to next key in key
sequence before reading the record.
CKDELETE
YES
Points to next key value in ascending sequence
following key value in record just deleted.
CKREWRITE
YES (sequential
mode)
Pointer remains positioned to key value for record jus
modied; unless any key value in record was changed,
in which case, it points to next key in ascending
seuence after the key in the modied record.
NO (random or
dynamic mode)
SHARED ACCESS
Particular care must be taken when using the logical record pointer during shared access (the
le was opened with CKOPENSHR). Since the record pointer is maintained in a separate
control block for each open le, if more than one user opens the same le, one user may
modify the key le causing the record pointers of other users to point to the wrong key.
To avoid this problem, you should always lock the le in a shared environment before calling
a procedure that sets the pointer and leave the le locked until all procedures that depend
on the pointer have been executed. Thus, if you want to read the le sequentially, delete a
record, or modify a record, you should lock the le, call a procedure that sets the pointer
(such as CKSTART), and then call CKREAD, CKDELETE, or CKREWRITE. When the
operation is complete, you can then unlock the le to give other users access to it.
USING KSAM FILES IN COBOL PROGRAMS
3-9
SAMPLE KSAM FILE
The le KSAMFILE illustrated in Figure 3-2 is used in all subsequent examples associated
with the COBOL procedure calls.
Figure 3-2. Representation of KSAMFILE Used in COBOL Examples
3-10
USING KSAM FILES IN COBOL PROGRAMS
CKCLOSE
A call to CKCLOSE terminates le processing for the specied le.
CALL &quot;CKCLOSE&quot; USING letable, status
When processing is completed, a KSAM le should be closed with a call to CKCLOSE. No
further processing is allowed on the le until a CKOPEN procedure call opens the le.
CKCLOSE can be executed only for a le that is open.
PARAMETERS
letable
status
an 8-word record containing: the name of the le, its input-output type,
access mode, the lenumber given the le when it was last opened, and a code
indicating whether the previous operation on the le was successful and if so
what it was. (Refer to Filetable Parameter discussion earlier in this section.)
one-word (two 8-bit characters) set to a pair of values upon completion of
the call to CKCLOSE. It indicates whether or not the le was successfully
closed and if not, why not. The left character is set to \0&quot; if CKCLOSE is
successful, to \9&quot; if not. The right character is set to \0&quot; if CKCLOSE is
successful, to the le system error code if not. (Refer to Status Parameter
discussion earlier in this section.)
USING CKCLOSE
Upon successful completion of CKCLOSE, the le identied by letable is no longer available
for processing. Note that a KSAM le can be closed and then reopened in order to specify a
dierent access mode or input-output type.
EXAMPLES
Assuming the same letable and status denitions used to dene the sample le in Figure 3-2:
FINISH.
CALL &quot;CKCLOSE&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKCLOSE ERROR NO. &quot;, RESULT;
ELSE DISPLAY&quot;CKCLOSE SUCCESSFUL&quot;.
USING KSAM FILES IN COBOL PROGRAMS
3-11
CKDELETE
This procedure logically deletes a record from a KSAM le.
CALL &quot;CKDELETE&quot; USING leable, status
In order to logically delete records from a KSAM le, you can use the procedure CKDELETE.
A logically deleted record is marked by a code of binary 1's in the rst two characters of the
record, but is not physically removed from the le. The deletion mark makes such a record
inaccessible but does not physically reduce the size of the le. The utility program FCOPY
(described in section II) can be used to compact a KSAM le by copying only active records,
excluding deleted records, to a new KSAM le.
CKDELETE deletes the record at which the logical record pointer is currently positioned.
Therefore, CKDELETE must be preceded by a call that positions the pointer (see Table 3-3).
PARAMETERS
letable
status
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
successful and if so what it was. (Refer to Filetable Parameter discussion
earlier in this section.)
one word (two 8-bit characters) set to a pair of values upon completion of the
call to CKDELETE indicating whether the call was successful and if not, why
not. (Refer to Status Parameter discussion earlier in this section.)
USING CKDELETE
In order to delete a record, you should rst read the record into the working storage section
of your program with a call to CKREAD if in sequential mode, a call to CKREADBYKEY
if in random mode, or a call to either if in dynamic mode. CKDELETE can be called only
if the le is currently open for both input and output (input-output type =2). This allows
the record to be read into your program's data area and then written back to the le with
the delete mark. Following execution of CKDELETE, the deleted record can no longer be
accessed.
SHARED ACCESS. If the le was opened for shared access with CKOPENSHR, you must
lock the le with CKLOCK before you can delete any records with CKDELETE. Because
CKDELETE depends on the logical record pointer, the call to CKLOCK should precede
the call that positions the pointer. The call to CKUNLOCK is then called after the call to
CKDELETE. To illustrate, the sequence of calls in shared access should be:
CKLOCK &lt;----- to lock le
CKSTART or CKREADBYKEY &lt;-------------- to position pointer
.
.
.
CKDELETE&lt;----- to delete record at which pointer is positioned
CKUNLOCK&lt;----- to unlock le
Following the call to CKDELETE, the pointer is positioned to the next key following the key
in the deleted record.
3-12
USING KSAM FILES IN COBOL PROGRAMS
EXAMPLES
The following examples show the use of CKDELETE for sequential access using CKREAD
and for random access using CKREADBYKEY. The WORKING-STORAGE SECTION from
Figure 3-2 and the FINISH procedure from the CKCLOSE example are assumed for these
examples.
1. Sequential Delete.
In order to delete all records whose primary key begins with \P&quot;, rst position the le to
the start of these records with CKSTART and then read each record with CKREAD and
delete it with CKDELETE.
WORKING-STORAGE SECTION.
77 RELOP PIC S9(4) COMP.
77 KEYVAL PIC X(20).
77 KEYLOC PIC S9(4) COMP.
77 KEYLENGTH PIC S9(4) COMP.
.
.
.
PROCEDURE DIVISION.
START.
MOVE 2 TO I-O-TYPE.
MOVE 0 TO A-MODE.
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
.
. &lt;---------- check status
.
FIND-REC.
MOVE 0 TO RELOP.&lt;--------------------
primary key and KEY
test for equality between
MOVE &quot;P&quot; TO KEYVAL.
MOVE 3 TO KEYLOC.
MOVE 1 TO KEYLENGTH.&lt;----- check rst character only
CALL &quot;CKSTART&quot; USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC,
KEYLENGTH.
IF STATUS-KEY-1 = &quot;0&quot; THEN
GO TO READ-REC.
IF STAT = &quot;23&quot; THEN
DISPLAY &quot;NO RECORD FOUND&quot;
GO TO FINISH.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO.=&quot;, RESULT
GO TO FINISH.
READ-REC.
CALL &quot;CKREAD&quot; USING FILETABLE, STAT, REC, RECSIZE.
IF STATUS-KEY-1 = &quot;1&quot; THEN
DISPLAY &quot;END OF FILE REACHED&quot;
GO TO FINISH.
IF STATUS-KEY-1 = &quot;0&quot; THEN
IF NAME OF REC NOT LESS THAN &quot;Q &quot;THEN
DISPLAY &quot;DELETIONS COMPLETED&quot;
GO TO FINISH;
ELSE GO TO DELETE-REC;
ELSE
DISPLAY &quot;CKREAD ERROR, STATUS =&quot;, STAT
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
USING KSAM FILES IN COBOL PROGRAMS
3-13
DISPLAY &quot;CKERROR NO.&quot;, RESULT.
GO TO READ-REC.
DELETE-REC.
CALL &quot;CKDELETE&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 = &quot;0&quot; THEN
DISPLAY &quot;DELETED&quot;
GO TO READ-REC;
ELSE
DISPLAY &quot;CKDELETE ERROR, STATUS = &quot;, STAT
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY&quot;CKERROR NO.=&quot;, RESULT
GO TO READ-REC.
Note
If access is shared, the le must be opened with a call to CKOPENSHR and
then locked before the call to CKSTART that initially sets the pointer. The
le should remain locked while the records to be deleted are read and then
marked for deletion. If the le is not locked before CKSTART is called, other
users can change the le so that the record pointer points to the wrong record.
2. Random Delete.
A le containing the primary keys of those records to be deleted from a KSAM le is read
into the working storage area DAT. These key values are used by CKREADBYKEY to
locate and read the items to be deleted by CKDELETE.
PROCEDURE DIVISION.
START.
MOVE 2 TO I-O-TYPE, A-MODE.
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
.
. check status
.
READ-KEY.
READ DATA-FILE INTO DAT;
AT END GO TO FINISH.
CALL &quot;CKREADBYKEY&quot; USING FILETABLE, STAT, REC, NAME OF DAT, KEYLOC, RECSIZE.
IF STATUS-KEY-1 = &quot;0&quot; THEN
GO TO DELETE-RECORD.
DISPLAY &quot;CKREADBYKEY ERROR, STATUS = &quot;,STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR &quot;, RESULT
GO TO READ-KEY.
DELETE-RECORD.
CALL &quot;CKDELETE&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 = &quot;0&quot; THEN
DISPLAY REC, &quot; DELETED&quot;
GO TO READ-KEY.
DISPLAY &quot;CKDELETE ERROR, STATUS =&quot;,STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO. =&quot;, RESULT.
GO TO READ-KEY.
3-14
USING KSAM FILES IN COBOL PROGRAMS
Note
Note: If access is shared, the le must be opened with a call to
CKOPENSHR; a call to CKLOCK must precede the call to CKREADBYKEY
and a call to CKUNLOCK must follow the CKDELETE error tests and
should precede the return to READ-KEY.
CKERROR
Converts le system error code returned in status to a display format number.
CALL &quot;CKERROR&quot; USING status, result
Whenever a \9&quot; is returned as the left character of the status parameter following any call to
a KSAM procedure, you can call the procedure CKERROR to convert the MPE le system
error code in the right character of status from a binary number to a display format number.
This allows you to display the error code.
PARAMETERS
status
result
is the status parameter to which a value was returned by a previous KSAM
procedure call. The entire status parameter, both left and right characters,
must be specied.
is an item to which the error number is returned right justied in display
format. The item must have a picture of 4 numeric characters (PIC 9(4) ).
USING CKERROR
The following example shows the WORKING-STORAGE SECTION entries needed to check
for errors and a call to CKERROR in the PROCEDURE DIVISION that checks for and
displays the error number if a le system error occurred in a call to process a KSAM le.
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
77 RESULT PIC 9(4) VALUE ZERO.
01 STAT.
03 STATUS-KEY-1 PIC X.
03 STATUS-KEY-2 PIC X.
.
.
.
PROCEDURE DIVISION.
START.
.
.
.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT.
DISPLAY &quot;ERROR NUMBER &quot;,RESULT.
.
.
.
USING KSAM FILES IN COBOL PROGRAMS
3-15
CKLOCK
A call to CKLOCK dynamically locks a KSAM le.
CALL &quot;CKLOCK&quot; USING letable, status, lockcond
When access is shared, you must lock the le before calling CKWRITE, CKREWRITE, or
CKDELETE. This insures that another user cannot attempt to modify the le at the same
time, and it guarantees that the most recent data is available to each user who accesses the
le.
In order to call CKLOCK, the le must have been opened with a call to CKOPENSHR, not
CKOPEN.
PARAMETERS
letable
status
lockcond
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
successful and if so, what it was. (Refer to Filetable Parameter discussion
earlier in this section.)
one-word (two 8-bit characters) set to a pair of values upon completion of the
call to CKLOCK. It indicates whether or not the le was successfully locked
and if not, why not. The status word =\00&quot; if the call was successful. It
=\30&quot; if the le was locked by another process; it = \9n,&quot; where n is a le
system error code, if the call failed for some other reason. (Refer to the Status
Parameter discussion earlier in this section.)
one-word computational item whose value determines the action taken if the
le is locked by another user when CKLOCK is executed. The value is either
zero (0) or one (1).
0
locking is conditional; if the le is already locked, control is
returned to your program immediately with the status word
set to \30&quot;.
1
locking is unconditional; if the le cannot be locked
immediately because another use has locked it, your program
suspends until the le can be locked.
USING CKLOCK
In order to call CKLOCK, the le must be opened with dynamic access enabled. This can
be done only with the CKOPENSHR procedure. CKOPEN will not open the le for shared
access with dynamic locking.
When users are sharing a le, it is essential to lock the le before modifying it. An error is
returned if any user attempts to write, rewrite, or delete records without rst locking the le.
It is also important to avoid situations where one user locks the le and forgets to unlock it. If
the le is already locked when you call CKLOCK with lockcond set to zero, the call will fail
with \30&quot; returned to status , and your process will continue. If, however, lockcond is set to 1,
your process suspends until the other user unlocks the le or logs o.
3-16
USING KSAM FILES IN COBOL PROGRAMS
EXAMPLES
The following example opens le KSAMFILE for shared access with dynamic locking allowed.
It then locks the le unconditionally. If another user has locked the le, the process suspends
until the le is unlocked and then continues by locking your le. The status value is checked
as soon as control returns to your process to insure that the le has been locked before
continuing.
DATA DIVISION.
77
77
01
LOCKCOND
RESULT
STATUSKEY.
02 STATUS-KEY1
02 STATUS-KEY2
01
FILETABLE.
02 FILENUMBER
02 FILENAME
02 I-O-TYPE
02 A-MODE
02 PREV-OP
PICTURE S9(4)
PICTURE 9(4)
COMP
VALUE 1.
VALUE 0.
PICTURE X VALUE &quot; &quot;.
PICTURE X VALUE &quot; &quot;.
PICTURE
PICTURE
PICTURE
PICTURE
PICTURE
S9(4)
X(8)
S9(4)
S9(4)
S9(4)
COMP
COMP
COMP
COMP
VALUE
VALUE
VALUE
VALUE
VALUE
0.
&quot;KSAMFILE&quot;.
0.
0.
0.
PROCEDURE DIVISION.
START.
CALL &quot;CKOPENSHR&quot; USING FILETABLE, STATUSKEY.
IF STATUS-KEY1 = &quot;0&quot; THEN GO TO LOCK-FILE.
IF STATUS-KEY1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;ERROR NO. &quot;,RESULT.
LOCK-FILE.
CALL &quot;CKLOCK&quot; USING FILETABLE, STATUSKEY, LOCKCOND.
IF STATUSKEY=&quot;0&quot;
THEN DISPLAY &quot;CKLOCK IS OK&quot;
ELSE IF STATUSKEY = &quot;30&quot;
THEN DISPLAY&quot;FILE LOCKED BY ANOTHER PROCESS&quot;
ELSE IF STATUS-KEY1=&quot;9&quot;
THEN CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;ERROR NO.&quot;, RESULT.
CKOPEN
A call to procedure CKOPEN initiates le processing.
CALL &quot;CKOPEN&quot; USING letable, status
In order to process a KSAM le, it must be opened with a call to the CKOPEN procedure.
CKOPEN initiates processing, species the type of processing and the access mode; the
le must have been created previously. You can create a KSAM le through the BUILD
command of the KSAMUTIL program (refer to section II).
To open a le means to make it available for processing, to specify the type of processing
(input only, output only, or both), and to specify the access method (sequential, random, or
dynamic). If a dierent type of processing or access method is needed, the le must be closed
and opened again with the parameters set to new values.
USING KSAM FILES IN COBOL PROGRAMS
3-17
If you want to open the le for shared access, you must use a call to
CKOPENSHR, rather than CKOPEN.
Note
PARAMETERS
letable
status
an 8-word record containing the name of the le, its input-output type, and
access mode. When the open is successful, the rst word of this table is set to
the le number that identies the opened le. (Refer to Filetable Parameter
discussion earlier in this section.)
one word (two 8-bit characters) set to a pair of values upon completion of the
call to CKOPEN to indicate whether or not the le was successfully opened
and if not why not. Left character is set to \0&quot; if open is successful, to \9&quot; if
not. Right character is set to \0&quot; if open is successful, to le system error
code if not. (Refer to Status Parameter discussion earlier in this section.)
USING CKOPEN
Upon successful execution of CKOPEN, the le named in letable is available for the type
of processing specied in letable . Before the le is successfully opened with CKOPEN, no
operation can be executed that references the le either explicitly or implicitly.
The input-output procedures that can be called to process the le depend on the value of the
words in letable that specify input-output type and access mode. (Refer to Table 3-4 for the
procedures allowed with the various combinations of input-output type and access mode.)
A le may be opened for input, output, or input-output, and for sequential, random, or
dynamic access in the same program by specifying a dierent call to CKOPEN for each
change in inputoutput type or access mode. Following the initial execution of CKOPEN, each
subsequent call to CKOPEN for the same le must be preceded by a call to CKCLOSE for
that le.
When les are opened for input or input-output, the call to CKOPEN sets the current record
pointer to the rst record in the primary key chain.
3-18
USING KSAM FILES IN COBOL PROGRAMS
Table 3-4.
Procedures Allowed for Input-Output Type/Access Mode Combinations
ALLOWED PROCEDURES
ACCESS MODE
INPUT-OUTPUT
TYPE
CKREAD
CKSTART
0
(sequential)
2
(dynamic)
0
(open for input)
CKREADBYKEY
1
(random)
2
(dynamic)
0
(open for input)
CKWRITE
0
(sequential)
2
(dynamic)
1
(open for output)
1
(random)
2
(dynamic)
1
(open for output)
CKREAD
CKSTART
CKREWRITE
CKDELETE
0
(sequential)
2
(dynamic)
2
(open for input/output)
CKREADBYKEY
CKWRITE
CKREWRITE
CKDELETE
1
(random)
2
(dynamic)
2
(open for input/output)
INPUT-OUTPUT TYPE. Word 6 of letable must be set to one of the following values before
calling CKOPEN:
0
input only
1
output only
2
input-output
Input Only. In general, if you want to allow records to be read or the le to be positioned
without allowing any new records to be written or any existing records to be changed, you
should set the input-output type to 0. This input-output type allows you to call CKREAD or
CKSTART in sequential processing mode, CKREADBYKEY in random mode, or all three in
dynamic mode.
Output Only. If you want to cause all existing records to be deleted when the le is opened
and then allow new records to be written, you should set the input-output type to 1. This
type of open deletes all existing records so that records are written to an empty le. When
a le is opened for output only, you can call CKWRITE in any of the three access modes:
sequential, random, or dynamic, but you cannot call any other of the KSAM procedures.
Input-Output.
If you want unrestricted le access, you should set the input-output type to
2. This access type allows records to be read, positioned, written, rewritten, or deleted. You
may call CKREAD, CKSTART, CKREWRITE, and CKDELETE (but not CKWRITE) when
opened in sequential mode; you may call CKREADBYKEY, CKWRITE, CKREWRITE, or
CKDELETE (but not CKREAD or CKSTART) when opened in random mode. In dynamic
USING KSAM FILES IN COBOL PROGRAMS
3-19
mode, any of the KSAM procedures may be called. With this type of input-output, existing
records are not cleared when you write a record with CKWRITE.
ACCESS MODE. Word 7 of letable must be set to one of the following values before calling
CKOPEN:
0
1
2
sequential access
random access
dynamic access
Sequential Access.
With this type of access, records in the le are read in ascending order
based on the value of a key within each record. The key is the primary key unless an alternate
key was specied with CKSTART. Reading starts with the rst record in sequence unless a
particular record was specied with CKSTART. Each time a call to CKREAD is executed,
the next record in sequence is read from the le. CKREAD and CKSTART are the only
procedures that can be called in input mode. CKREADBYKEY cannot be specied for any
input-output type if the access mode is sequential.
In output mode, CKWRITE is the only procedure that can be called. When access is
sequential, the record to be written must contain a unique primary key that is greater in value
than the key of any previously written record. If it is not in sequence, an invalid key sequence
error \21&quot;, is returned to status .
In input-output mode, CKREWRITE and CKDELETE can be specied as well as CKREAD
and CKSTART, but CKWRITE cannot.
Random Access. This type of access allows you to read, write, replace, or delete a record with
any value for its primary key. To read a record, the CKREADBYKEY procedure must be
called in either input or input-output mode. CKREAD and CKSTART cannot be specied for
any input-output type when access mode is random.
When writing a record with CKWRITE in output or input-output mode, the value of the
primary key in the record need not be greater than the keys of previously written records;
that is, records can be written in any order.
In input-output mode, CKREWRITE can be used to replace any record whose primary key
matches the primary key in the record being written. CKDELETE can be used to delete a
record specied in a previous CKREADBYKEY call.
CKWRITE can be used to write a record following existing records in the le if you position
to follow the last sequential record before writing. Use this input-output type if you want to
save existing data in a le to which you are writing.
Dynamic Access. Dynamic access allows you to use any call to process a le opened for
inputoutput. When the le is opened in dynamic mode, and a call is made to CKREAD or
CKSTART, the le can be read, but not updated, sequentially. For all other calls, dynamic
mode is treated as if the le had been opened in random mode. See Random Mode discussion,
above. The reason to open a le in dynamic mode is to allow both sequential and random
processing on the same le without closing it and then opening it again each time access
switches from sequential to random or vice versa.
3-20
USING KSAM FILES IN COBOL PROGRAMS
EXAMPLES
To open a le initially for sequential read:
WORKING-STORAGE SECTION.
77 RESULT PIC 9(4) VALUE ZERO.
01 FILETABLE.
03 FILENUMBER PIC S9(4) COMP VALUE ZERO.
03 FILENAME PIC X(8) VALUE &quot;KSAMFILE&quot;.
03 I-O-TYPE PIC S9(4) COMP VALUE ZERO.&lt;------ input only
03 A-MODE PIC S9(4) COMP VALUE ZERO.&lt;------ sequential access
03 PREV-OP PIC S9(4) COMP VALUE ZERO.
01 STAT.
03 STATUS-KEY-1 PIC X.
03 STATUS-KEY-2 PIC X.
.
.
.
PROCEDURE DIVISION.
START.
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 =&quot;0&quot; THEN GO TO S-READ.
IF STATUS-KEY-1 =&quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKOPEN FAILED. . .ERROR NO.&quot;, RESULT
STOP RUN.
S-READ.
.
.
.
If you subsequently want to write in sequential order to the same le, you should close the le
with a call to CKCLOSE (described below), move the value 1 (output to I-O-TYPE and then
re-open the le:
CALL &quot;CKCLOSE&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 =&quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKCLOSE FAILED -- ERROR NO.&quot;,
STOP RUN.
MOVE 1 TO I-O-TYPE.&lt;------ output only
CALL &quot;CKOPEN&quot; USlNG FILETABLE, STAT.
.
.
.
Similarly, to update records in random order in the same le, rst close the le, then use the
following MOVE statement to alter the input-output type and access mode in FILETABLE
and reopen the le:
CALL
.
.
.
MOVE
MOVE
CALL
.
.
.
&quot;CKCLOSE&quot; USING FILETABLE, STAT.
2 TO I-O-TYPE.&lt;----------- input-output
1 TO A-MODE.&lt;------------- random access
&quot;CKOPEN&quot; USING FILETABLE, STAT.
USING KSAM FILES IN COBOL PROGRAMS
3-21
CKOPENSHR
A call to CKOPENSHR initiates le processing with dynamic locking and shared access
allowed.
CALL &quot;CKOPENSHR&quot; USING letable, status
In order to process a KSAM le with shared access and dynamic locking, the le must be
opened with a call to CKOPENSHR. CKOPENSHR is exactly like CKOPEN in that it
initiates processing, species the type of processing, and species the access mode. The le
must have been created previously with the BUILD command of program KSAMUTIL (refer
to section II).
To open a le for shared access means to make it available for processing by more than one
user. Shared access allows all users to read or position the le, but only one user at a time
can modify the le by writing new records, or rewriting or deleting existing records. To
insure that more than one user does not attempt to modify the le at the same time, you
must call CKLOCK to dynamically lock the le before calling the procedures CKWRITE,
CKREWRITE, or CKDELETE. After modifying the le, you should call CKUNLOCK so
that it can be accessed by other users.
PARAMETERS
letable
status
an 8-word record containing the name of the le, its input-output type, and
access mode. When the open is successful, the rst word of this table is set to
the le number that identies the opened le. (Refer to Filetable Parameter
discussion earlier in this section.)
one word (two 8-bit characters) set to a pair of values upon completion of
the call to CKOPENSHR to indicate whether or not the le was successfully
opened and if not why not. Left character is set to \0&quot; if open is successful, to
\9&quot; if not. Right character is to\0&quot; if open is successful, to le system error
code if not. (Refer to Status Parameter discussion earlier in this section.)
USING CKOPENSHR
Except that CKOPENSHR allows shared access and dynamic locking, and CKOPEN does
not, a call to CKOPENSHR operates exactly like the call to CKOPEN. Upon successful
execution of CKOPENSHR, the le named in letable is available for the type of processing
specied in le - table . Before the le is opened successfully, no operation can be performed
that references the le either explicitly or implicitly.
A le may be opened by CKOPENSHR for any of the access modes (sequential, random, or
dynamic) and for any input-output type (input only, output only, or input-output) allowed
with CKOPEN.
Refer to the description of using CKOPEN for the specic aects of opening a KSAM le with
the various input-output types and access modes.
3-22
USING KSAM FILES IN COBOL PROGRAMS
CKREAD
A call to procedure CKREAD makes available the next logical record from a le.
CALL &quot;CKREAD&quot; USING letable, status, record, recordsize
In order to read records in sequential order by key value, call procedure CKREAD. The le
must have been opened in input or input-output mode with access mode specied as either
sequential or dynamic.
PARAMETERS
letable
status
record
recordize
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
successful and if so, what it was. (Refer to Filetable Parameter discussion
earlier in this section.)
one-word (two 8-bit characters) set to a pair of values upon completion of
the call to CKREAD to indicate whether or not the record was successfully
read and if not, why not. (Refer to Status Parameter discussion earlier in this
section.)
a record dened in the WORKING-STORAGE SECTION into which the
contents of the next sequential KSAM record is read.
an integer (S9(4)COMP) containing the length in characters of the record
being read. It must not exceed maximum record length established for the le
when it was created.
USING CKREAD
The le from which the record is read must be open for sequential or dynamic access (access
mode = 0 or 2.) It may be opened for input only or input-output (input-output type = 0 or
2), but not for output only.
When the le is opened initially for input or input-output, the logical record pointer is
positioned at the rst sequential record; that is, at the record with the lowest key value. The
key used is the primary key unless a previous call to CKSTART has specied an alternate
key. When a call to CKREAD is executed, the record at which the record pointer is currently
positioned is read into the location specied by record .
If, when CKREAD is executed, there is no next logical record in the le, the at end condition
is returned to status ; that is, status is to\10&quot;. Note that a call to the procedure CKSTART
can be used to reposition the pointer for subsequent sequential access according to primary or
alternate key order.
In order to update records in sequential order, CKREAD must be called before executing
either of the update procedures CKREWRITE and CKDELETE. When access is shared, it
is important to include the call to CKREAD within the same locked portion of code that
includes the call to CKREWRITE or CKDELETE. This insures that the correct record is
modied or deleted.
SHARED ACCESS. Because CKREAD is a pointer-dependent procedure (refer to Table 3-3),
the actual record read depends on the current position of the logical record pointer. When
access is shared, this pointer position can be made incorrect by other users without your
USING KSAM FILES IN COBOL PROGRAMS
3-23
program being aware of it. For this reason, you should lock the le, position the pointer with
a pointerdent procedure, and then call CKREAD. When the last record is read, you should
then unlock the le so other users can access the le. Example 2 below illustrates how you
should read the le sequentially when access is shared.
EXAMPLE
Using the WORKING-STORAGE SECTION from Figure 3-2 and the FINISH procedure in
the CKCLOSE example, the following procedures read records in sequential order from le
KSAMFILE and display them on the standard output device.
1. Example of Sequential Read
PROCEDURE DIVISION.
START.
.
.
.
MOVE 0 TO I-O-TYPE, A-MODE.
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 = &quot;9&quot;
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKOPEN ERROR NO. &quot;, RESULT.
IF STATUS-KEY-1 NOT = &quot;0&quot;
DISPLAY &quot;CKOPEN FAILED&quot;
STOP RUN.
READ-NEXT.
CALL &quot;CKREAD&quot; USING FILETABLE, STAT, REC, RECSIZE.
IF STATUS-KEY-1 = &quot;1&quot; GO TO NEW-POSITION.
IF STATUS-KEY-1 = &quot;0&quot;
DISPLAY REC;
ELSE
DISPLAY &quot;CKREAD ERROR, STATUS =&quot;, STAT.
IF STATUS-KEY-1 =&quot;9&quot;
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;FILE ERROR =&quot;, RESULT.
GO TO READ-NEXT.
NEW-POSITION.
.
.
. see CKSTART example
2. Example of Sequential Read with Shared Access
PROCEDURE DIVISION.
START.
.
.
.
MOVE 0 TO I-O-TYPE, A-MODE.
CALL &quot;CKOPENSHR&quot; USING FILETABLE, STAT &lt;----.
.&lt;----- test status
.
FIND-RECORD.
MOVE 2 TO RELOP.
MOVE &quot;000-0000&quot; TO KEYVAL.
MOVE 23 TO KEYLOC,
MOVE 8 TO KEYLENGTH.
MOVE 1 TO LOCKCOND.
3-24
open le for shared access
USING KSAM FILES IN COBOL PROGRAMS
CALL &quot;CKLOCK&quot; USING FILETABLE, STAT, LOCKCOND.&lt;----- lock le unconditionally
CALL &quot;CKSTART&quot; USING FILETABLE,
STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.&lt;--- position pointer to lowest key value
.
. &lt;----- test status
.
READ-RECORD.
CALL &quot;CKREAD&quot; USING FILETABLE, STAT, REC, RECSIZE&lt;----- read record
IF STATUS-KEY-1 =&quot;1&quot;&lt;------- end of le
GO TO END-OF-READ.
IF STATUS-KEY-1 =&quot;0&quot;&lt;------- if successful, display record read
DISPLAY REC.
.
.&lt;----- test status for errors
.
TO TO READ-RECORD.
END-OF-READ.
CALL &quot;CKUNLOCK&quot; USING FILETABLE, STAT.&lt;----- unlock le
CKREADBYKEY
A call to CKREADBYKEY makes available a record identied by key value from a KSAM
le.
CALL &quot;CKREADBYKEY&quot; USING letable, status, record, key, keyloc, recordsize
Records can be read from a KSAM le in an order determined by key value. This order need
not be sequential; in fact, it can be any order you specify. This type of access is used to access
individual records in random order by key value.
PARAMETERS
letable
status
record
key
keyloc
recordsize
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
successful and if so what it was. (Refer to Filetable Parameter discussion
earlier in this section.)
one word (two 8-bit characters) set to a pair of values upon completion of the
call to CKREADBYKEY indicating whether the call was successful and if not
why not. (Refer to Status Parameter discussion earlier in this section.)
a record dened in the WORKING-STORAGE SECTION into which the
contents of a record located by key value is read.
an item whose value is used by CKREADBYKEY to locate the record to be
read. Key values in the le identied by letable are compared to the value of
key until the rst record with an equal value is found.
one-word integer (S9(4)COMP) set to the starting character position of the
key in the KSAM data record (rst position is character 1). keyloc identies
the le key to be compared with key .
an integer (S9(4)COMP) containing the length in characters of the record
being read; it must be less than or equal to the maximum record length
established for the le at creation.
USING KSAM FILES IN COBOL PROGRAMS
3-25
USING CKREADBYKEY
In order to use the CKREADBYKEY procedure, the le must be opened for either input or
inputoutput. The access mode can be either random or dynamic, but must not be sequential.
Execution of CKREADBYKEY causes the value of key to be compared to the value of the key
at location keyloc in the KSAM le data records. When a key is found whose value is identical
to that of key , the record pointer is moved to the beginning of that record and the record is
read into the location record .
If no record can be found whose key value equals that of key , an invalid key condition is
diagnosed and status is set to the value \23&quot;. Successful execution of CKREADBYKEY is
indicated by the value \0&quot; in the left byte of status , unsuccessful execution is indicated by
either the invalid key return or by a value of \9&quot; in the left byte of status .
In order to delete records in random or dynamic mode, CKREADBYKEY must be called
before executing CKDELETE. It is not required prior to CKREWRITE.
EXAMPLES
In the following examples, update information is read into the area called DAT in the
WORKINGSTORAGE SECTION. (Note that in this as in the preceding examples, the
WORKING-STORAGE SECTION from Figure 3-2 continues to be useful.) In the rst
example, the primary keys of records in KSAMFILE are searched for values matching the
value read into NAME in the DAT record; in the second example, an alternate key at location
23 is searched for values matching the value read into PHONE in the DAT record.
1. Read a record located by its primary key value:
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
77 KEYLOC PIC S9(4) COMP.
.
.
.
PROCEDURE DIVISION.
START.
.
.
.
MOVE 2 TO I-O-TYPE, A-MODE.&lt;--- prepare to open for input-output,
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKOPEN ERROR NO. &quot;, RESULT.
IF STATUS-KEY-1 NOT=&quot;O&quot; THEN
DISPLAY &quot;CKOPEN FAILED&quot;
STOP RUN.
FIND-RECORD.
READ NEW-DATA INTO DAT;&lt;------- read update records
AT END GO TO FINISH.
MOVE 3 TO KEYLOC.
CALL &quot;CKREADBYKEY&quot; USING FILETABLE, STAT, REC, NAME OF DAT,
KEYLOC, RECSIZE.
IF STATUS = &quot;00&quot; THEN
3-26
USING KSAM FILES IN COBOL PROGRAMS
dynamic access
DISPLAY &quot;RECORD FOUND&quot;, REC
GO TO FIND-RECORD
IF STATUS = &quot;23&quot; THEN
DISPLAY &quot;RECORD NOT FOUND,KEY=&quot;, NAME OF DAT
GO TO FIND-RECORD.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;ERROR NO. &quot;, RESULT
GO TO FIND-RECORD.
To nd a record by the value of an alternate key, simply change two statements in the
preceding example so that KEYLOC contains the location of the alternate key and the key
value for comparison is found in item PHONE OF DAT rather than in NAME OF DAT:
FIND RECORD.
READ NEW-DATA INTO DAT;
AT END GO TO FINISH.
MOVE 23 TO KEYLOC.
CALL &quot;CKREADBYKEY&quot; USING FILETABLE, STAT, REC, PHONE OF DAT,
KEYLOC, RECSIZE.
.
.
.
CKREWRITE
The procedure CKREWRITE replaces a record existing in a KSAM le with another record
having a matching primary key.
CALL &quot;CKREWRITE&quot; USING letable, status, record, recordsize
You can replace an existing record in a KSAM le with the procedure CKREWRITE. This
procedure replaces a record previously read from the le with another record whose primary
key matches the primary key of the record being replaced.
PARAMETERS
letable
status
record
recordsize
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
unsuccessful and if so what it was. (Refer to Filetable parameter discussion
earlier in this section.)
one word (two 8-bit characters) set to a pair of values upon the completion of
the call to CKREWRITE indicating whether or not the call was successful
and if not why not. (Refer to Status Parameter discussion earlier in this
section.)
a record dened in the WORKING-STORAGE SECTION containing data to
be written as a logical record to the le replacing the record with a matching
primary key.
an integer (S9(4)COMP) containing the length in characters of the record to
be written. It must not exceed the maximum record length established for the
le creation.
USING KSAM FILES IN COBOL PROGRAMS
3-27
USING CKREWRITE
In order to call procedure CKREWRITE, the le must be open for both input and output
(inputoutput type=2). The access mode can be sequential, random, or dynamic. If access
mode is sequential, CKREAD must have been executed successfully just prior to the call to
CKREWRITE. In random or dynamic mode, no prior read is required; the system searches
the le for the record to be rewritten.
REWRITE IN SEQUENTIAL MODE. When the le is opened in sequential mode (access
mode = 0), CKREAD must be executed before CKREWRITE, The primary key in the
record to be written by CKREWRITE must be identical to the primary key in the record
read by CKREAD. A simple way to insure that the keys match is to read a record into
WORKING-STORAGE, modify it without altering the primary key, and then write it back to
the le using CKREWRITE. Since the primary key is not changed, the sequence of records in
the le is not aected.
Rewriting Records With Duplicate Keys. If you want to rewrite in sequential mode all the
records in a chain of records with duplicate keys, use either CKSTART or CKREADBYKEY
to position to the rst record in the chain. Then call CKREWRITE to update the rst record
in the chain. Subsequent calls depend on whether you are changing any key value in the
record (not necessarily the selected key).
If no key in the record is changed, the record pointer continues to point to the current record.
Only a subsequent CKREAD advances the pointer to the next record in the duplicate key
chain. In this case, you can issue CKREAD and CKREWRITE calls until all records with the
duplicated key value have been rewritten.
If any key in the record is changed, the new key is written to the end of the chain of duplicate
keys in the key le. After the rst call to CKREWRITE, the record pointer points to the
record whose key value follows the changed key. Since this key is now at the end of the
chain of duplicate keys, a subsequent call to CKREWRITE skips all records with keys in the
duplicate key chain and rewrites the record with the next higher key value. In this case, you
must precede each call to CKREWRITE with a call to CKSTART or CKREADBYKEY in
order to update all subsequent records with duplicate keys.
If you are updating a primary key value which is duplicated, it is good practice to use
CKDELETE to delete the selected record and then rewrite it as a new record with
CKWRITE.
REWRITE IN RANDOM MODE. When the le is opened in random or dynamic mode
(access mode = 1 or 2), no prior call to a read procedure is needed. You specify the record to
be written in WORKING-STORAGE and then call CKREWRITE. However, you must use
the primary key to position to the record to be modied. When the procedure is executed, the
le is searched for a record whose primary key matches that of the record to be written. If
such a record is found, it is replaced by the record specied in CKREWRITE. If not found, an
invalid key condition is diagnosed and status is set to the \23&quot;.
A call to CKREWRITE in random mode only updates the rst record with a key in the chain
of duplicate keys.
POSITION OF POINTER. Regardless of the mode, after any call to CKREWRITE that does
not modify a key value, the record pointer is positioned to the key of the record just modied.
However, if any key in the modied record was changed, the record must be deleted and then
rewritten by a write procedure. If the access mode is sequential and a key was modied,
the pointer is moved to the record with the next key value in ascending sequence after the
3-28
USING KSAM FILES IN COBOL PROGRAMS
modied key. If the access mode is random or dynamic, and a key was modied, the pointer
is moved to the record with the next key in ascending sequence after the primary key in the
modied record. This means that in random or dynamic mode the key pointer may change if
it was pointing to an alternate key before the call to CKREWRITE,
REWRITE WITH SHARED ACCESS. If the le was opened for shared access with
CKOPENSHR, then you must lock the le with a call to CKLOCK before rewriting any
records with CKREWRITE. After the records are rewritten, you should unlock the le with
CKUNLOCK.
To insure that you are updating the correct record in sequential mode, you should call
CKLOCK before positioning the pointer with CKSTART or CKREADBYKEY, then
specify the sequential calls to CKREAD and CKREWRITE before unlocking the le with
CKUNLOCK. This insures that no other users change the position of the pointer while you
are sequentially updating the le.
INVALID KEY. In sequential mode, the invalid key condition exists when the record just
read by CKREAD and the record to be written by CKREWRITE do not have the same
primary key value. In random or dynamic mode, an invalid key condition exists if no record
can be found in the le whose primary key matches that of the record to be written by
CKREWRITE. In either case, status is set to the value \23&quot;.
Regardless of mode, an invalid key condition occurs if an alternate key value in the record to
be written duplicates a corresponding alternate key for which duplicates are prohibited. When
rewriting a record, try to avoid specifying an alternate key value that may duplicate a value
existing in the le unless duplicates are allowed for the key. A duplicate key condition where
duplicates are not allowed causes status to be set to \22&quot; and the procedure is not executed.
EXAMPLES
The rst example is of a sequential update that clears the value of an item in each record
of the le. The second example searches the le for a record whose primary key has a
particular value in order to change the alternate key for that record. Both examples assume
the WORKING-STORAGE SECTION from Figure 3-2 and the FINISH procedure from
CKCLOSE.
1. Sequential Update.
Use CKSTART to position the current record pointer to the start of the le. Then read
each record in sequence and set its non-key items to blanks:
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
\
77 RELOP
PICS9(4) COMP.|
77 KEYVAL
PIC X(20).
|--------77 KEYLOC
PIC S9(4) COMP.|
77 KEYLENGTH
PIC S9(4) COMP.|
.
/
.
.
PROCEDURE DIVISION.
START.
MOVE 2 TO I-O-TYPE.
MOVE 0 TO A-MODE.
items required by CKSTART
USING KSAM FILES IN COBOL PROGRAMS
3-29
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
.
.&lt;---------------------------- check status
.
UPDATE-FILE.
MOVE 1 TO RELOP.
MOVE &quot;000-0000&quot; TO KEYVAL.&lt;---------- set up CKSTART parameters to start
MOVE 23 TO KEYLOC.
reading at lowest alternate key value
MOVE 8 TO KEYLENGTH.
CALL &quot;CKSTART&quot; USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.
IF STATUS-KEY-1=&quot;0&quot; THEN
GO TO READ-RECORD;
ELSE
DISPLAY &quot;CKSTART ERROR, STATUS&quot;, STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO.&quot;, RESULT
GO TO FINISH.
READ-RECORD.
CALL &quot;CKREAD&quot; USING FILETABLE, STAT, REC, RECSIZE.
IF STATUS-KEY-1 = &quot;1&quot; THEN
GO TO FINISH. &lt;------------------ end of le
IF STATUS-KEY-1 = &quot;0&quot; THEN
GO TO WRITE-RECORD
ELSE
DISPLAY &quot;CKREAD ERROR,STATUS =&quot;, STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO. &quot;, RESULT
GO TO READ-RECORD.
WRITE-RECORD.
MOVE SPACES TO OTHERDATA OF REC.
CALL &quot;CKREWRITE&quot; USING FILETABLE,
IF STATUS-KEY-1 = &quot;0&quot; THEN
DISPLAY NAME OF&quot;DATA CLEARED&quot;
GO TO READ-RECORD.
DISPLAY &quot;CKREWRITE ERROR, STATUS=&quot;,
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT,
DISPLAY &quot;CKERROR NO.=&quot;,
GO TO READ-RECORD.
Note
If the le was opened for shared access with a call to CKOPENSHR, then the
le should be locked with a call to CKLOCK before the call to CKSTART.
The le should be unlocked with a call to CKUNLOCK only when the nal
record is updated, probably in the FINISH procedure.
2. Random Update. Find the record with the primary key \ECKSTEIN, LEO &quot;and change
the value of the secondary key to \257-5137&quot;:
PROCEDURE DIVISION.
START.
.
.
.
MOVE 2 TO I-O-TYPE, A-MODE.
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1 = &quot;0&quot; THEN
GO TO F-UPDATE.
DISPLAY &quot;CKOPEN ERROR, STA&quot;, STAT.
3-30
USING KSAM FILES IN COBOL PROGRAMS
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO.=&quot;, RESULT
GO TO FINISH.
F-UPDATE.
MOVE &quot;ECKSTEIN, LEO &quot;TO NAME OF REC.
MOVE &quot;257-5137&quot; TO PHONE OF REC.
MOVE SPACES TO OTHERDATA OF REC.
CALL &quot;CKREWRITE&quot; USING FILETABLE, STAT, REC, RECSlZE.
IF STATUS-KEY-1=&quot;0&quot; THEN
DISPLAY REC &quot;UPDATED&quot;
GO TO FINISH.
IF STAT = &quot;23&quot; THEN
DISPLAY NAME OF REC &quot;NOT FOUND&quot;
GO TO FINISH.
DISPLAY &quot;CKREWRITE ERROR, STATUS =&quot;, STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO.=&quot;, RESULT.
GO TO FINISH.
CKSTART
A call to procedure CKSTART allows you to position the record pointer to a particular record
dened by its primary or alternate key value.
CALL &quot;CKSTART&quot; USING letable, status, relop, key, keyloc, keylength
In order to position the current record pointer to a location in the le dened by a key value,
call CKSTART. Since CKSTART is used in preparation for sequential retrieval of records with
CKREAD, the le must be open for sequential or dynamic access, not random, and for input
or input-output, not output only.
PARAMETERS
letable
status
relop
key
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
successful and if so, what it was. (Refer to Filetable Parameter discussion
earlier in this section.)
one word (two 8-bit characters) set to a pair of values upon completion of the
call to CKSTART to indicate whether or not the call was successful and if not
why not. (Refer to Status Parameter discussion earlier in this section.)
one-word integer (S9(4)COMP) code that species a relation between the key
value specied in the call to CKSTART and the key value in the record to
which the record pointer is to be positioned:
0|record key is equal to key
1|record key is greater than key
2|record key is greater than or equal to key
an item whose value is used by CKSTART to locate the record at which to
position the record pointer. The values of a specied le key are compared
in ascending order to the value of key according to the relation specied by
relop .
USING KSAM FILES IN COBOL PROGRAMS
3-31
keyloc
keylength
one-word integer (S9(4)COMP) set to the starting character location of a key
in the KSAM le data record (rst position is character 1). The key at keyloc
is compared to key .
one-word integer (S9(4)COMP) set to the length of key ; the length must be
less than or equal to the length of the key dened by keyloc .
USING CKSTART
When CKSTART is executed, the key le is searched for the rst key in the set of keys at
location keyloc whose value when compared with key satises the comparison specied by
relop . The current record pointer is positioned to the beginning of the record in the data le
associated with the key found by CKSTART.
The specied length of key (key length ) may be less than the length of the key in the le; if so,
the comparison proceeds as if the le key were truncated on the right to the same length as
key length .
If no record can be found whose key value satises the comparison, an invalid key condition is
returned to status ; that is, status is set to \23&quot;.
SHARED ACCESS. If you use CKSTART to position the pointer before reading or updating
the le sequentially in a shared environment, you must lock the le with a call to CKLOCK
before calling CKSTART. Then, after you have completed the sequential operations, you can
unlock the le with a call to CKUNLOCK. If you wait to lock the le until after the call to
CKSTART, another user can change the structure of the key le so that the position of the
pointer becomes invalid for any subsequent call to a procedure that depends on the pointer
position. (Refer to Table 3-3 for a list of the pointer-dependent procedures.)
EXAMPLES
Four new items must be added to the WORKING-STORAGE SECTION in Figure 3-2;
otherwise, the same WORKING-STORAGE SECTION is used. The new items are:
77
77
77
77
RELOP
KEYVAL
KEYLOC
KEYLENGTH
PIC
PIC
PIC
PIC
S9(4). COMP.
X(20).
S9(4) COMP.
S9(4) COMP.
Each of these items is assigned the value appropriate to the operation to be performed by
statements in the PROCEDURE DIVISION. Note that the length of array KEYVAL can be
made shorter by assigning a value less than 20 to KEYLENGTH but it cannot be made longer
than 20 characters. Since there is no key in KSAMFILE longer than 20 characters, this allows
comparison to be made on the longest key.
The following example shows the statements needed to display the records in KSAMFILE in
order by the alternate key PHONE that starts in location 23 and has a length of 8 characters.
It assumes the le is open for input or input-output and that access mode is sequential. It
also assumes the FINISH procedure from the CKCLOSE example.
1. Position by alternate key sequence:
NEW-POSITION.
MOVE 2 TO RELOP.&lt;-------- nd
MOVE &quot;000-0000&quot; TO KEYVAL.
MOVE 23 TO KEYLOC.
3-32
key value greater than or equal to KEYVAL
USING KSAM FILES IN COBOL PROGRAMS
MOVE 8 TO KEYLENGTH.
CALL &quot;CKSTART&quot; USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.
IF STATUS = &quot;23&quot; THEN GO TO FINISH.&lt;-------- no record found
IF STATUS-KEY-1 = &quot;0&quot; THEN GO TO READ-BY-PHONE.&lt;--- lowest key value found
DISPLAY &quot;CKSTART ERROR, STATUS&quot;, STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;ERROR NUM&quot;, RESULT.
GO TO FINISH.
READ-BY-PHONE.
CALL &quot;CKREAD&quot; USING FILETABLE, STAT, REC, RECSIZE,
IF STATUS-KEY-1 = &quot;1&quot; THEN GO TO FINISH.&lt;---- end-of-le
IF STATUS-KEY-1 = &quot;O&quot; THEN
DISPLAY REC;
ELSE DISPLAY &quot;CKREAD ERROR,STATUS=&quot;, STAT
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;ERROR NUMBER&quot;, RESULT.
GO TO READ-BY-PHONE.
.
.
.
In the next example, CKSTART is used to position to the beginning of the series of names
beginning with the letter \T&quot;. The KSAM le key is located at character position 3
(NAME key); the parameter KEYVAL is set to the value \T&quot;; the key length for purposes
of comparison is set to 1; and RELOP is set to 0. Thus the record pointer is positioned at
the rst key found whose value (when the key is truncated to 1 character) is equal to \T&quot;.
Note that this example reads not only all names beginning with \T&quot;, but also reads all
names that begin with letters following \T&quot;. To read only the names beginning with \T&quot;,
the program must add a test for the end of the \T&quot; names.
2. Using a Generic Key
POSITION.
MOVE 0 TO RELOP.&lt;------------ nd key equal to KEY value
MOVE &quot;T&quot; TO KEYVAL.
MOVE 3 TO KEYLOC.
MOVE 1 TO KEYLENGTH.
CALL &quot;CKSTART&quot; USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.
IF STATUS = &quot;23&quot; THEN GO TO FINISH.
IF STATUS-KEY-1 = &quot;0&quot; THEN
GO TO READ-NAMES.
DISPLAY &quot;CKSTART ERROR, STATUS=&quot;,STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;ERROR NUMBER=&quot;, RESULT.
GO TO FINISH.
READ-NAMES.
CALL &quot;CKREAD&quot; USING FILETABLE, STAT, REC, RECSlZE.
IF STATUS-KEY-1 =&quot;1&quot; THEN GO TO FINISH.
IF STATUS-KEY-1 =&quot;0&quot; THEN
DISPLAY REC;
ELSE
DISPLAY &quot;CKREAD ERROR, STATUS&quot;,STAT.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;ERROR NUM&quot;, RESULT.
GO TO READ-NAMES.
USING KSAM FILES IN COBOL PROGRAMS
3-33
CKUNLOCK
A call to CKUNLOCK unlocks a KSAM le dynamically locked by CKLOCK.
CALL &quot;CKUNLOCK&quot; USING letable, status
A le locked by CKLOCK is released for use by other users with a call to CKUNLOCK. (If
you log o from any connection with the system, the le is also unlocked.) Since dynamic
locking takes place during shared access to the same le by more than one user, it is
important that any le locked by CKLOCK be unlocked as soon as possible by CKUNLOCK.
To use CKUNLOCK, the le must be opened for shared access with dynamic locking allowed.
This can only be done by calling CKOPENSHR to open the le, not CKOPEN.
PARAMETERS
letable
status
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation was
successful and if so, what it was. (Refer to Filetable Parameter discussion
earlier in this section.)
one-word (two 8-bit characters) set to a pair of values upon completion of
the call to CKUNLOCK. It indicates whether or not the le was successfully
unlocked and if not, why not. The status word is to\00&quot; if the le was
unlocked successfully; to \31 &quot;if the le was not locked; or to \9n &quot; where n is
a binary le system error code if the call fails for any other reason. (Refer to
Status Parameter discussion earlier in this section.)
USING CKUNLOCK
After calling CKUNLOCK, you should always check the status parameter to make sure that
the procedure was executed successfully. When successful, the le locked by CKLOCK is
again made available for access by other users. If the le was not locked by CKLOCK, when
CKUNLOCK is called, status is set to \31.&quot;
EXAMPLES
The following example unlocks a le previously locked by CKLOCK. (Refer to the CKLOCK
example.)
DATA DIVISION.
.
.
.
77
RESULT
01
STATUSKEY.
02 STATUS-KEY1
02 STATUS-KEY2
01
FILETABLE.
02 FILENUMBER
02 FILENAME
02 I-O-TYPE
02 A-MODE
02 PREV-OP
PICTURE 9(4)
VALUE 0.
PICTURE X
PICTURE X
PICTURE
PICTURE
PICTURE
PICTURE
PICTURE
S9(4)
X(8)
S9(4)
S9(4)
S9(4)
VALUE &quot; &quot;.
VALUE &quot; &quot;.
COMP
COMP
COMP
COMP
VALUE
VALUE
VALUE
VALUE
VALUE
0.
&quot;KSAMFILE&quot;.
0.
0.
0.
PROCEDURE DIVISION.
.
3-34
USING KSAM FILES IN COBOL PROGRAMS
.
.
CALL &quot;CKUNLOCK&quot; USING FILETABLE, STATUSKEY.
IF STATUSKEY =&quot;00&quot;
THEN DISPLAY &quot;CKUNLOCK IS OK&quot;
ELSE IF STATUSKEY =&quot;31&quot;
THEN DISPLAY=&quot;FILE NOT PREVIOUSLY LOCKED BY THIS PROCESS&quot;
ELSE IF STATUS-KEY1 =&quot;9&quot;
THEN CALL&quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;ERROR NO.&quot;, RESULT.
CKWRITE
Procedure CKWRITE copies a logical record from the program's data area to an output or an
input-output le.
CALL &quot;CKWRITE&quot; USING letable, status, record, recordsize
A call to procedure CKWRITE may be used to write records to a KSAM le either in
sequential order or randomly by key value. The le must have been opened for output or for
input-output, but not for input only.
PARAMETERS
letable
status
record
recordsize
an 8-word record containing the number and name of the le, its input-output
type, access mode, and a code indicating whether the previous operation on
the le was successful and if so what it was. (Refer to Filetable Parameter
discussion earlier in this section.)
one-word (two 8-bit characters) set to a pair of values upon completion of
the call to CKWRITE to indicate whether or not the record was successfully
written and if not why not. (Refer to Status Parameter discussion earlier in
this section.)
a record dened in the WORKING-STORAGE SECTION containing data to
be written to the le by CKWRITE.
an interger (S9(4)COMP) containing the length in characters of the record to
be written.lt must not exceed the maximum record length established for the
le when it was created, and it must be long enough to contain all the keys.
USING CKWRITE
The le to which the content of record is written must be open for output only if sequential
mode is specied. It may be opened for output or input-output if the access mode at open is
random or dynamic.
WRITING IN SEQUENTIAL MODE. When the le is opened for sequential access (access
mode = 0) and for output only (I-O type = 1), then records must be written to the le in
ascending sequential order by primary key value. The value of the primary key in the record
to be written must be greater than the value of the primary key in any record previously
written to the le. This insures that the records written to the le are initially in ascending
order physically as well as logically.
USING KSAM FILES IN COBOL PROGRAMS
3-35
When I-O type = 1, CKWRITE writes records starting at the beginning of the le, thereby
eectively clearing any records previously written to the le.
WRITING IN RANDOM MODE. In a le opened for random or dynamic access (access
mode = 1 or 2) and for output only or for input-output (I-O type = 1 or 2), records can be
written in any order; the value of the primary key need not be in any particular relation to
the primary key values of previously written records.
If you want to preserve existing records in the le, you should open the le with the
input-output type equal to 2; when input-output type = 1, all existing records are cleared
prior to the write.
WRITING WHEN ACCESS IS SHARED. If the le was opened for shared access with
CKOPENSHR, then you must lock the le with a call to CKLOCK before writing any
records. After the records are written, you should unlock the le with a call to CKUNLOCK.
INVALID KEY. The invalid key condition (left byte of status =\2&quot;) can occur as a result of
the following circumstances:
File was opened for sequential access in output mode and the value of the primary key in
the record being written is less than or equal to the value of the primary key in the record
just written; status =\21&quot;.
File was opened for sequential or random access in output or input-output mode and the
value of the primary key is equal to the value of the primary key in an existing record;
status =\22&quot;.
File was opened for sequential or random access in output or input-output mode and
the value of an alternate key for which duplicates are prohibited equals the value of a
corresponding key in an existing record; status =\22&quot;.
File was opened for sequential or random access in output or input-output mode and an
attempt was made to write a record beyond the physical bounds of the le; status =\24&quot;.
EXAMPLES
Assume a KSAM le called KSAMFILE with records containing 74 characters (72 characters
of data following two characters reserved for the delete code), one primary key containing a
name, and an alternate key containing a phone number. The data is read from an input le
called DATA-FILE. (Refer to Figure 3-2 for a diagram of the structure of this le.)
The rst example writes data to KSAMFILE in sequential order by the primary key. The
second example, using the same DATA DIVISION and the same FINISH procedure, writes
one record to the le containing the \ADAMSON JOHN&quot; as its primary key value.
1. Example of Sequential Write.
DATA DIVISION
.
.
.
WORKING-STORAGE SECTION.
77 RECSIZE
PIC S9(4)
77 RESULT
PIC 9(4)
01 REC.
03 FILLER
PIC XX
03 NAME
PIC X(20).
03 PHONE
PIC X(8).
3-36
COMP VALUE 74.
VALUE 0.
VALUE SPACES.
USING KSAM FILES IN COBOL PROGRAMS
03 OTHERDATA
PIC X(44).
01 DAT.
03 NAME
PIC X(20).
03 PHONE
PIC X(8).
03 OTHERDATA
PIC X(44).
01 FILETABLE.
03 FILENUMBER PIC S9(4)
COMP VALUE 0.
03 FILENAME
PIC X(8)
VALUE &quot;KSAMFILE&quot;.
03 I-O-TYPE
PIC S9(4)
COMP VALUE 0.
03 A-MODE
PIC S9(4)
COMP VALUE 0.
03 PREV-OP
PIC S9(4)
COMP VALUE 0.
01 STAT.
03 STATUS-KEY-1 PIC X.
03 STATUS-KEY-2 PIC X.
.
.
.
PROCEDURE DIVISION.
START.
.
.
.
MOVE 1 TO I-O-TYPE,&lt;----------------- set type to output
CALL &quot;CKOPEN&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1=&quot;O&quot; THEN GO TO WRITE-F.
DISPLAY &quot;CKOPEN ERROR, STATUS = &quot;, STAT.
IF STATUS-KEY-1= &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKERROR NO. &quot;, RESULT.
STOP RUN.
WRITE-F.
READ DATA-FILE INTO DAT;
AT END GO TO FINISH.
MOVE CORRESPONDING DAT TO REC.
CALL &quot;CKWRITE&quot; USING FILETABLE, STAT, REC, RECSIZE.
IF STATUS-KEY-1=&quot;0&quot; THEN
DISPLAY REC.
GO TO WRITE-F.
IF STAT=&quot;21&quot; THEN
DISPLAY &quot;SEQUENCE ERROR IN&quot;, NAME OF REC
GO TO WRITE-F.
IF STAT = &quot;22&quot; THEN
DISPLAY &quot;DUPLICATE KEY&quot;, NAME OF REC
GO TO WRITE-F.
IF STAT = &quot;24&quot; THEN
DISPLAY &quot;END OF FILE&quot;
GO TO FINISH.
.
.
.
FINISH
CLOSE DATA-FILE.
CALL &quot;CKCLOSE&quot; USING FILETABLE, STAT.
IF STATUS-KEY-1=&quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STAT, RESULT
DISPLAY &quot;CKCLOSE ERROR NO. &quot;, RESULT.
STOP RUN.
only
2. Example of random write.
PROCEDURE DIVISION.
USING KSAM FILES IN COBOL PROGRAMS
3-37
START.
.
.
.
MOVE 1 TO I-O TYPE.&lt;------------- output only
MOVE 2 TO A-MODE.&lt;-------------- random access
CALL &quot;CKOPEN&quot;USING FILETABLE, STAT.
.
. check status
.
FIND-REC.
READ DATA-FILE INTO DAT;
AT END GO TO FINISH.
IF NAME OF DAT = &quot;ADAMSON
JOHN&quot; THEN
GO TO WRlTE-REC;
ELSE GO TO FIND-REC.
WRITE-REC.
MOVE CORRESPONDING DAT TO REC.
CALL &quot;CKWRITE&quot; USING FILETABLE, STAT, REC, RECSIZE.
IF STATUS-KEY-1=&quot;0&quot; THEN
DISPLAY REC,&quot; RECORD WRITTEN&quot;
GO TO FINISH.
IF STAT = &quot;22&quot; THEN
DISPLAY &quot;DUPLICATE KEY&quot;
GO TO FINISH.
IF STAT = &quot;24&quot; THEN
DISPLAY &quot;NO ROOM IN FILE&quot;
GO TO FINISH.
.
.
.
EXAMPLES OF KSAM FILE ACCESS FROM COBOL PROGRAM
The following three examples illustrate KSAM le access from a COBOL program. The le
accessed in each example is called KSAMFILE. It was created previously by the KSAMUTIL
&gt;BUILD command with BYTE type keys: the primary key containing the name of a person
and the alternate key containing his telephone number; the remaining data in each record is
his address.
EXAMP1. SEQUENTIAL WRITE
The rst example reads data from an input le into working storage and then writes it to a
KSAM le. Access mode is sequential so that as each record is written, the keys are linked in
sequential order although the records are not physically written in sequence. Input-output
type is output only, the only type allowed for the procedure CKWRITE. The following
procedures are illustrated:
CKOPEN
CKWRITE
CKCLOSE
3-38
USING KSAM FILES IN COBOL PROGRAMS
Input to EXAMP1:
NOLAN
HOSODA
ECKSTEIN
CARDIN
PASBY
SEELY
ROBERT
TURNEWR
WHITE
WESTER
**END OF
JACK
923-4975
JOE
227-8214
LEO
287-5137
RICK
578-7018
LINDA 295-1187
HENRY 293-4220
GERRY 258-5535
IVAN
984-8498
GORDON 398-0301
ELDER 287-4598
INPUT FOR EXAMP1**
967 REED AVE.
1180 SAINT PETER CT.
5303 STEEVENS CREEK
11100 WOLFE ROAD
TOWN &amp; CNTRY VILLAGE
1144 LEBERTY ST.
12345 TELEGRAPH AVE .
22905 EMERSON ST.
4350 ASHBY AVE.
1256 KINGFISHER ST.
SUNNYVALE
LOS ALTOS
SANTA CLARA
CUPERTINO
SAN JOSE
EL CERRITO
BERKELEY
OAKLAND
BERKELEY
SUNNYVALE
CA.
CA.
CA.
CA.
CA.
CA.
CA.
CA.
CA.
CA.
94087
94022
95050
94053
94012
94053
90871
98234
91234
43098
Program EXAMP1
001000
001100
001200
001300
001400
001500
001600
001700
001800
001900
002000
002100
002200
002300
002400
002500
002600
002700
IDENTIFICATION DIVISION.
PROGRAM-ID. EXAMP1.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTIONS
FILE-CONTROL.
SELECT SEQ-DATA ASSIGN TO &quot;SEQDATA&quot;.
DATA DIVISION.
FILE SECTION.
FD SEQ-DATA
LABEL RECORDS ARE STANDARD.
01 INPUT-REC.
05 REAL-DATA
PIC X(72).
WORKING-STORAGE SECTION.
77 RECSIZE PIC S9(4) COMP VALUE 74.
77 RESULT
PIC 9(4) VALUE ZERO.
01 DATA-REC.
05 FILLER
PIC XX VALUE SPACES.
05 REAL-DATA
PIC X(72). l
Figure 3-3. Sequential Write Using COBOL
USING KSAM FILES IN COBOL PROGRAMS
3-39
002800
002900
003000
003100
003200
003300
003400
003500
003600
003700
003800
003900
004000
004100
004200
004300
004400
004500
004600
004700
004800
004900
005000
005100
005200
005300
005400
005500
005600
005700
005800
005900
006000
006100
006200
006300
006400
006500
006600
006700
006800
006900
007000
01
01
FILETABLE.
02 FILENUMBER
02 FILENAME
02 I-O-TYPE
02 A-MODE
02 PREV-OP
STATUSKEY.
02 STATUS-KEY-1
02 STATUS.KEY-2
PIC
PIC
PIC
PIC
PIC
S9(4)
X(8)
S9(4)
S9(4)
S9(4)
COMP
VALUE
COMP
COMP
COMP
VALUE 0.
&quot;GKSAMFIL&quot;.
VALUE 1.
VALUE 0.
VALUE 0.
PIC X.
PIC X.
PROCEDURE DIVISION.
START.
OPEN INPUT SEQ-DATA@
CALL &quot;CKOPEN&quot; USING FILETABLE, STATUSKEY.
IF STATUS-KEY-1=&quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;CKOPEN ERROR NO.&quot;, RESULT.
IF STATUS-KEY-1 NOT = &quot;0&quot; THEN
DISPLAY &quot;CKOPEN FAILED&quot;
STOP RUN.
LOOP.
READ SEQ-DATA
AT END GO TO FINISH.
MOVE CORP INPUT-REC TO DATA-REC.
CALL &quot;CKWRITE&quot; USING FILETABLE, STATUSKEY, DATA-REC,
RECSIZE.
IF STATUSKEY = &quot;02&quot; THEN
DISPLAY &quot;DUPLICATE KEY&quot;.
IF STATUS-KEY-1 = &quot;0&quot; THEN
DISPLAY DATA-REC
GO TO LOOP.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;CKWRITE ERROR NO.&quot;, RESULT
DISPLAY DATA-REC
GO TO LOOP.
FINISH.
CLOSE SEQ-DATA.
CALL &quot;CKCLOSE&quot; USING FILETABLE, STATUSKEY.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;CKCLOSE ERROR NO. &quot;. RESULT.
STOP RUN.
Output from EXAMP1 Execution:
NOLAN
JACK
HOSODA
JOE
ECKSTEIN LEO
CARDIN
RICK
PASBY
LINDA
SEELY
HENRY
ROBERT
GERRY
TURNEWR IVAN
WHITE
GORDON
WESTER
ELDER
END OF PROGRAM
923-4975
227-8214
287-5137
578-7018
295-1187
293-4220
258-5535
984-8498
398-0301
287-4598
967 REED AVE.
1180 SAINT PETER CT.
5303 STEEVENS CREEK
11100 WOLFE ROAD
TOWN &amp; CNTRY VILLAGE
1144 LEBERTY ST.
12345 TELEGRAPH AVE .
22905 EMERSON ST.
4350 ASHBY AVE.
1256 KINGFISHER ST.
SUNNYVALE
LOS ALTOS
SANTA CLARA
CUPERTINO
SAN JOSE
EL CERRITO
BERKELEY
OAKLAND
BERKELEY
SUNNYVALE
CA.
CA.
CA.
CA.
CA.
CA.
CA.
CA.
CA.
CA.
94087
94022
95050
94053
94012
94053
90871
98234
91234
43098
Figure 3-3. Sequential Write Using COBOL(continued)
3-40
USING KSAM FILES IN COBOL PROGRAMS
EXAMP2. SEQUENTIAL READ
The second example reads the le KSAMFILE in sequential order by primary key (NAME)
and prints each record as it is read. It then repositions the le to the rst sequential record
according to the alternate key (PHONE) and prints each of the records as it is read in this
order. The le is opened in sequential mode for input only. The following procedures are
illustrated:
CKOPEN
CKREAD
CKSTART
CKCLOSE
Program EXAM2:
001000
001100
001200
001300
001400
001500
001600
001700
001800
001900
002000
002100
002200
002300
002400
002500
002600
002700
002800
002900
003000
003100
003200
003300
003400
003500
003600
003700
003800
003900
004000
004100
004200
004300
004400
004500
004600
004700
004800
004900
005000
005100
005200
005300
IDENTIFICATION DIVISION.
PROGRAM-ID. EXAMP2.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT SEQ-DATA ASSIGN TO &quot;SEQDATA&quot;.
DATA DIVISION.
WORKING-STORAGE SECTION.
77 RECSIZE PIC S9(4) COMP VALUE 74.
77 RESULT
PIC 9(4) VALUE ZERO.
77 KEY-LOC
PIC S9(4) COMP VALUE 23.
77 RELOP
PIC S9(4) COMP VALUE 2.
77 KEYLENGTH PIC S9(4) COMP VALUE 8.
77 KEY-VALUE PIC X(8) VALUE &quot;000-0000&quot;.
01 DATA-REC.
05 FILLER
PIC XX.
05 NAME
PIC X(20).
05 PHONE
PIC X(8).
05 OTHER-DATA PIC X(44).
01 FILETABLE.
02 FILENUMBER PIC S9(4) COMP VALUE o.
02 FILENAME PIC X(8) VALUE &quot;GKSAMFIL&quot;.
02 I-O-TYPE PIC S9(4) COMP VALUE o.
02 A-MODE
PIC S9(4) COMP VALUE o.
02 PREV-OP
PIC S9(4) COMP VALUE o.
01 STATUSKEY.
02 STATUS-KEY-l PIC X.
02 STATUS-KEY-2 PIC X.
PROCEDURE DIVISION.
START.
CALL &quot;CKOPEN&quot; USING FILETABLE, STATUSKEY.
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;CKOPEN ERROR NO.&quot;, RESULT.
IF STATUS-KEY-1 NOT = &quot;0&quot; THEN
DISPLAY &quot;CKOPEN FAILED&quot;
STOP RUN.
DISPLAY &quot;ALPHABETICAL ORDER&quot;
DISPLAY &quot; &quot;.
L00P1.
CALL &quot;CKREAD&quot; USING FILETABLE, STATUSKEY, DATA-REC,
RESIZED.
IF STATUS-KEY-1= &quot;1&quot; THEN GO TO PART2.
Figure 3-4. Sequential Read Using COBOL
USING KSAM FILES IN COBOL PROGRAMS
3-41
005400
IF STATUS-KEY-1 = &quot;0&quot; THEN
005500
DISPLAY DATA-REC
005600
ELSE
005700
DISPLAY &quot;CKREAD ERROR, STATUS = &quot;, STATUSKEY
005800
IF STATUS-KEY-1 = &quot;9&quot; THEN
005900
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
006000
DISPLAY &quot;ERROR NO.&quot;, RESULT.
006100
GO TO LOOP.
006200 PART2
006300
DISPLAY &quot; &quot;.
006400
DISPLAY &quot;PHONE NO. ORDER:&quot;
006500
DISPLAY &quot; &quot;.
006600
CALL &quot;CKSTART&quot; USING FILETABLE, STATUSKEY, RELOP,
006700
KEY-VALUE, KEY-LOC, KEYLENGTH.
006800
IF STATUSKEY = &quot;23&quot; THEN GO TO FINISH.
006900
IF STATUS-KEY-1 = &quot;0&quot; THEN GO TO LOOP2.
007000
DISPLAY &quot;CKSTART ERROR, STATUS = &quot;, STATUSKEY.
007100
IF STATUS-KEY-1 = &quot;9&quot; THEN
007200
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
007300
DISPLAY &quot;ERROR NO.&quot;, RESULT.
007400
GO TO FINISH.
007500 LOOP2
007600
CALL &quot;CKREAD&quot; USING FILETABLE, STATUSKEY, DATA-REC,
007700
RECSIZE.
007800
IF STATUS-KEY-1 = &quot;1&quot; THEN GO TO FINISH.
007900
IF STATUS-KEY-1 = &quot;0&quot; THEN
008000
DISPLAY DATA-REC
008100
ELSE
008200
DISPLAY &quot;CKREAD ERROR, STATUS =&quot;, STATUSKEY
008400
IF STATUS-KEY-1 =&quot;9&quot; THEN
008400
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
008500
DISPLAY &quot;ERROR NO. &quot;, RESULT.
008600
GO TO LOOP2.
008700 FINISH.
008800
CALL &quot;CKCLOSE&quot; USING FILETABLE, STATUSKEY.
008900
IF STATUS-KEY-1 = &quot;9&quot; THEN
009000
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
009100
DISPLAY &quot;CKCLOSE ERROR NO.&quot;, RESULT.
009200
STOP RUN.
Figure 3-4. Sequential Read Using COBOL (continued)
3-42
USING KSAM FILES IN COBOL PROGRAMS
Outtput from EXAMP2 Execution:
ALPHABETICAL ORDER:
CARDIN
ECKSTEIN
HOS0DA
NOLAN
PASBY
ROBERT
SEELY
TURNEWR
WESTER
WHITE
RICK
LEO
JOE
JACK
LINDA
GERRY
HENRY
IVAN
ELDER
GORDON
587-7018
287-5137
227-8214
923-4975
295-1187
259-5535
293-4220
984-8498
287-4598
398-0301
11100 WOLFE ROAD
5303 STEVENS CREEK
1180 SAINT PETER CT.
967 REED AVE.
TOWN &amp; CNTRY VILLAGE
12345 TELEGRAPH AVE.
1144 LEBERTY ST.
22905 EMERSON ST.
1256 KINGFISHER ST.
4350 ASHBY AVE.
CUPERTINO CA.
SANTA CLARA CA.
LOS ALTOS CA.
SUNNYVALE CA.
SAN JOSE CA.
BERKELEY CA.
EL CERRITO CA.
OAKLAND CA.
SUNNYVALE CA.
BERKELEY CA.
227-8214
259-5535
287-4598
287-5137
293-4220
295-1187
398-0301
578-7018
923-4975
984-8498
1180 SAINT PETER CT.
12345 TELEGRAPH AVE.
1256 KINGFISHER ST.
5303 STEVENS CREEK
1144 LEBERTY ST.
TOWN &amp; CNTRY VILLAGE
4350 ASHBY AVE.
11100 WOLFE ROAD
967 REED AVE.
22905 EMERSON ST.
LOS ALTOS CA.
BERKELEY CA.
SUNNYVALE CA.
SANTA CLARA CA.
EL CERRITO CA.
SAN JOSE CA.
BERKELEY CA.
CUPERTINO CA.
SUNNYVALE CA.
OAKLAND CA.
94053
95050
94022
94087
94102
90871
94053
98234
43098
91234
PHONE NO. ORDER:
HOSODA
ROBERT
WESTER
ECKSTEIN
SEELY
PASBY
WHITE
CARDIN
NOLAN
TURNEWR
JOE
GERRY
ELDER
LEO
HENRY
LINDA
GORDON
RICK
JACK
IVAN
94022
90871
43098
95050
94053
94102
91234
94053
94087
98234
END OF PROGRAM
Figure 3-4. Sequential Read Using COBOL (continued)
USING KSAM FILES IN COBOL PROGRAMS
3-43
EXAMP3. RANDOM UPDATE
This example reads a set of new data containing update information into the WORKINGSTORAGE SECTION. Each record read is followed by a U for update, a D for delete, or an A
for add. Records to be added are written to the le KSAMFILE using CKWRITE in random
mode. Records to be updated are copied to the appropriate record with CKREWRITE.
Records to be deleted are rst read in the WORKING-STORAGE SECTION with
CKREADBYKEY and then deleted with CKDELETE. The le is opened in random mode for
input-output.
The procedures illustrated by this example are:
CKOPEN
CKREADBYKEY
CKDELETE
CKREWRITE
CKWRITE
CKCLOSE
Program EXAMP3:
001000
001100
001200
001300
001400
001500
001600
001700
001800
001900
002000
002100
002200
002300
002400
002500
002600
002700
002800
002900
003000
003100
003200
003300
003400
003500
003600
003700
003800
003900
004000
004100
004200
004300
004400
IDENTIFICATION DIVISION,
PROGRAM-ID. EXAMP3.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT NEW-DATA ASSIGN TO &quot;NEWDATA&quot;.
DATA DIVISION.
FILE SECTION.
FD NEW-DATA
LABEL RECORDS ARE STANDARD.
01 INPUT-REC PIC X(73),
WORKING-STORAGE SECTION,
77 RECSIZE PIC S9(4) COMP VALUE 74.
77 RESULT
PIC 9(4) VALUE ZERO.
77 KEY-LOC PIC S9(4) COMP VALUE 3.
01 MASTER-REC.
05 FILLER
PIC XX.
05 NAME
PIC X(20).
05 PHONE
PIC X(8).
05 OTHER-DATA
PIC X(44).
01 DATA-REC.
05 NAME
PIC X(20).
05 PHONE
PIC X (8).
05 OTHER-DATA
PIC X(44).
05 TRANSACTION-CODE PIC X.
01 FILETABLE.
02 FILENUMRER PIC S9(4) COMP VALUE o.
O2 FILENAME
PIC X(8) VALUE &quot;GKSAMFIL&quot;.
02 I-O-TYPE
PIC S9(4) COMP VALUE 2.
02 A-MoDE
PIC S9(4) COMP VALUE 1.
02 PHEV-OP
PIC S9(4) COMP VALUE 0.
01 STATUSKEY.
02 STATUS-KEY-1
PIC X.
02 STATUS-KEY-2
PIC X.
Figure 3-5. Random Update with COBOL
3-44
USING KSAM FILES IN COBOL PROGRAMS
004500 PROCEDURE DIVISION.
004600 START.
004700
OPEN INPUT NEW-DATA.
004800
CALL &quot;CKOPEN&quot; USING FILETABLE, STATUSKEY.
004900
IF STATUS-KEY-1 = &quot;9&quot; THEN
005000
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
005100
DISPLAY &quot;CKOPEN ERROR NO.&quot;, RESULT.
005200
IF STATUS-KEY-1 NOT =&quot;0&quot; THEN
005300
DISPLAY &quot;CKOPEN FAILED&quot;
005400
STOP RUN.
005500 LOOP.
005600
READ NEW-DATA INTO DATA-REC;
005700
AT END GO TO FINISH.
005800
IF TRANSACTION-CODE = &quot;A&quot; THEN GO TO ADD.REC,
005900
IF TRANSACTION-CODE NOT = &quot;D&quot; AND &quot;U&quot; THEN
006000
DISPLAY &quot;ILLEGAL TRANSACTION CODE&quot;
006100
DISPLAY DATA-REC
006200
GO TO LOOP.
006300
CALL &quot;CKREADBYKEY&quot; USING FILETABLE, STATUSKEY, MASTER-REC,
006400
NAME OF DATA-REC, KEY-LOC, RECSIZE.
006500
IF STATUS-KEY-1 NOT = &quot;0&quot; THEN
006600
DISPLAY &quot;CKREADBYKEY ERROR, STATUS =&quot;, STATUSKEY,
006700
&quot;1 KEY =&quot;, NAME OF DATA-REC
006800
IF STATUS-KEY-1 = &quot;9&quot; THEN
006900
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
007000
DISPLAY &quot;ERROR NO.&quot;, RESULT
007100
GO TO LOOP
007200
ELSE
007300
GO TO LOOP.
007400
IF TRANSACTION-CODE = &quot;D&quot; THEN GO TO DELETE-REC.
007500
MOVE CORR DATA-REC TO MASTER-REC.
007600
CALL &quot;CKREWRITE&quot; USING FILETABLE, STATUSKEY, MASTER-REC,
007700
RECSIZE.
007800
IF STATUS-KEY-1 = &quot;0&quot; THEN
007900
DISPLAY MASTER-REC, &quot;UPDATED&quot;
008000
GO TO LOOP.
008100
DISPLAY &quot;CKREWRITE ERROR, STATUS =&quot;, STATUSKEY, &quot;1 KEY =&quot;
008200
NAME OF MASTER-REC.
008300
IF STATUS KEY-1= &quot;9&quot; THEN
008400
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
008500
DISPLAY &quot;ERROR NO.&quot;, RESULT
008600
GO TO LOOP.
Figure 3-5. Random Update with COBOL (continued)
USING KSAM FILES IN COBOL PROGRAMS
3-45
008700 DELETE-REC.
008800
CALL &quot;CKDELETE&quot; USING FILETABLE, STATUSKEY.
008900
IF STATUS-KEY-1 = &quot;0&quot; THEN
009000
DISPLAY MASTER-REC, &quot;DELETED&quot;
009100
GO TO LOOP.
009200
DISPLAY &quot;CKDELETE ERROR, STATUS =&quot; STATUSKEY.
009300
IF STATUS-KEY-1 = &quot;9&quot; THEN
009400
CALL &quot;CKERROR&quot;, USING STATUSKEY, RESULT
009500
DISPLAY &quot;ERROR NO.&quot;, RESULT.
009600
GO TO LOOP.
009700 ADD-REC.
009800
MOVE CORR DATA-REC TO MASTER-REC.
009900
CALL &quot;CKWRITE&quot; USING FILETABLE, STATUSKEY, MASTER-REC.
010000
RECSIZE.
010100
IF STATUSKEY = &quot;02&quot; THEN
010200
DISPLAY &quot;DUPLICATE KEY&quot;,
010300
IF STATUS-KEY-1 = &quot;0&quot; THEN
010400
DISPLAY MASTER-REC, &quot;ADDED&quot;
010500
GO TO LOOP.
010600
DISPLAY &quot;CKWRITE ERROR, STATUS = &quot;, STATUSKEY.
010700
IF STATUS-KEY-1 = &quot;9&quot; THEN
010800
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
010900
DISPLAY &quot;ERROR NO. &quot;, RESULT.
Figure 3-5. Random Update with COBOL (continued)
3-46
USING KSAM FILES IN COBOL PROGRAMS
011000
011100
011200
011300
011400
011500
011600
011700
011800
DISPLAY MASTER-REC,
GO TO LOOP.
FINISH.
CLOSE NEW-DATA.
CALL &quot;CKCLOSE&quot; USING FILETABLE, STATUSKEY,
IF STATUS-KEY-1 = &quot;9&quot; THEN
CALL &quot;CKERROR&quot; USING STATUSKEY, RESULT
DISPLAY &quot;CKCLOSE ERROR NO.&quot;, RESULT
STOP RUN.
Input to EXAMP3:
NOLAN
SMITH
ECKSTEIN
CARDIN
PASBY
JANE
ROBERT
TURNEW
FORD
WESTER
JACK
JOHN
LEO
RICK
LINDAL
MARY
GERRY
IVAN
GERALD
ELDER
1 ANY STREET.
SUNNYVALE CA.
OUR TOWN CA.
257-7000 11100 WOLFE ROAD
CUPERTINO CA.
923-4975
555-1212
102 FIRST ST.
565-9090
259-5535
1776 BICENTENNIAL ST.
12345 TELEGRAPH AVE.
555-1976
287-4598
1600 PENNSYLVANIS
1256 KINGFISHER ST.
AMAHEIM CA.
BERKELEY CA.
94O87U
94099A
D
94041U
D
91076A
94704U
D
WASHINGTON DC. 20001U
SUNNYVALE CA.
94309A
Output from Execution of EXAMP3:
NOLAN
JACK
923-4975
1 ANY STREET.
SUNNYVALE CA. 94087
UPDATED
SMITH
JOHN
555-1212 102 FIRST ST.
OUR TOWN
CA. 94099
ADDED
ECKSTEIN LEO
287-5137 5303 STEVENS CREEK
SANTA CLARA CA. 95050
DELETED
CARDIN
RICK
257-7000 11100 WOLFE ROAD
CUPERTINO CA. 94014
UPDATED
PASBY
LINDA
295-1187 TOWN &amp; CNTRY VILLAGE SAN JOSE
CA. 94102
DELETED
JANE
MARY
565-9090 1776 BICENTENNIAL ST. ANAHEIM
CA. 91076
ADDED
ROBERT
GERRY
259-5535 12345 TELEGRAPH AVE. BERKELEY
CA. 94704
UPDATED
CKREADBYKEY ERROR, STATUS = 231 KEY = TURNEW
IVAN
CKREADBYKEY ERROR, STATUS = 231 KEY = FORD
GERALD
CKWRITE ERROR, STATUS = 22
WESTER
ELDER
287-44598 1256 KINGFISHER ST. SUNNYVALE
CA. 9430A
Figure 3-5. Random Update with COBOL (continued)
Note
Note that the input contains data that results in error messages. The name
IVAN TURNEWR is spelled incorrectly and cannot be found. The name
GERALD FORD does not exist in the original le and also cannot be found.
On the other hand, the name ELDER WESTER already exists in the le and
cannot be added since it is a primary key for which duplicates are not allowed.
USING KSAM FILES IN COBOL PROGRAMS
3-47
4
USING KSAM FILES IN SPL PROGRAMS
KSAM FILE SYSTEM INTRINSICS
The Multi-Programming Executive Operating System (MPE) provides a set of procedures,
known as intrinsics. A subset of these intrinsics makes up the le system, a set of procedures
used to manipulate les. KSAM les are processed using these same intrinsics with the
following exceptions: seven new intrinsics are added for KSAM les, and four of the le
system intrinsics do not apply to KSAM les. (Refer to Table 4-1 for a list of the KSAM le
system intrinsics.)
USING KSAM FILES IN SPL PROGRAMS
4-1
Table 4-1. KSAM File System Intrinsics
INTRINSIC
NAME
KSAM
ONLY
NOT USED
BY KSAM
DIFFERENCES IN
FORMAT
FUNCTION
FOPEN
ksamparam replaces formmsg Opens a KSAM le for
as sixth parameter.
access and assign le
number to le.
FCLOSE
none
Closes a KSAM le to
further access.
|
If called for KSAM le,
returns CCL error code.
none
Reads next record in
sequential order by key.
[FRENAME]
X
FREAD
*FREADC
X
all new
Reads next record in
chronological sequence.
*FREADBYKEY
X
all new
Reads record identied
by key value.
none
Reads record identied
by chronological
position.
FREADDIR
[FREADSEEK]
X
If called for KSAM le,
returns CCL error code.
control parameter included
for compatibility only.
Writes record to KSAM
le.
|
If called for KSAM le,
returns CCL error code.
all new
Deletes current record
from KSAM le.
FUPDATE
none
Updates last referenced
record.
FSPACE
none
Spaces forward or
backward in le.
all new
Positions current record
pointer to record
located by key value.
FWRITE
[FWRITEDIR]
*FREMOVE
*FFINDBYKEY
4-2
X
X
X
USING KSAM FILES IN SPL PROGRAMS
Table 4-1. KSAM File System Intrinsics (continued)
INTRINSIC
NAME
*FFINDN
KSAM
ONLY
NOT USED
BY KSAM
FUNCTION
all new
Positions current record
pointer to relative
record number in key
sequence.
FPOINT
none
Positions current record
pointer to relative
record number in
chronological sequence.
FGETINFO
none
Requests le access and
status information.
all new
Requests access and
status information on
KSAM le.
|
If called for KSAM le,
returns CCE and false
condition.
FCHECK
none
Requests details of le
input/output errors.
FERRMSG
none
Prints message
corresponding to
FCHECK error code.
FCONTROL
param parameter included
for compatibility only
Ensures that
input/output is
complete or positions to
rst sequential record
by key value; other
options not available for
KSAM le.
FSETMODE
none
Veries critical output
as part of write
operation; other options
not available for KSAM
le.
FLOCK
none
Dynamically locks le.
FUNLOCK
none
Dynamically unlocks
le.
FREADLABEL
none
Reads user's le label.
FWRITELABEL
none
Writes user's le label.
*FGETKEYINFO
[FRELATE]
X
DIFFERENCES IN
FORMAT
X
X
USING KSAM FILES IN SPL PROGRAMS
4-3
KSAM File System Intrinsics (continued)
INTRINSIC
NAME
*HP32208
KSAM
ONLY
NOT USED
BY KSAM
X
FUNCTION
DIFFERENCES IN
FORMAT
all new
Identies the KSAM
version.
FDELETE
X
Deactivates a RIO
record.
FDEVICECONTROL
X
Provides control
operations to a printer,
Workstation
Congurator, or a
spooled device.
FFILEINFO
none
Provides access to le
information.
FLABELINFO
The information returned
may not match what is
returned from FFILEINFO.
Returns information
from the le label of a
disc le.
FPARSE
none
Passes and validates le
designators.
FREADBACKWARD
X
Reads a logical record
backward from the
current record pointer.
Data is presented to the
user as if read forward.
CALLING INTRINSICS FROM SPL
An intrinsic used in an SPL program must be declared at the beginning of the program
following all other declarations. There are two ways to declare an intrinsic: one is to make an
external procedure declaration, and the other is to use the INTRINSIC declaration. Since
declaring an external procedure is a long process, you can save space and time by using the
INTRINSIC declaration as follows:
INTRINSIC intrinsicname, intrinsicname,..., intrinsicname;
You name all the intrinsics used in your program in the intrinsicname list. When more than
one intrinsic is named, the names must be separated by commas.
You call an intrinsic by writing the intrinsic name followed by a list of parameters enclosed in
parentheses. These parameters must be in the order established for each intrinsic as shown in
the intrinsic formats later in this section. Every parameter that is specied as a variable or
an array must be declared before the intrinsic is called. The formats that describe intrinsics
dene the variable or array type of each parameter; specify whether it can be passed by value
or must be passed by reference; and indicate whether any parameters are optional and if so
which ones.
In summary, to call an intrinsic from an SPL program:
1. Refer to the intrinsic format to determine the parameter type and position.
4-4
USING KSAM FILES IN SPL PROGRAMS
2. Declare any variable or array names to be passed as parameters at the beginning of the
program.
3. Declare the intrinsic name in an INTRINSIC statement.
4. Issue the intrinsic call where appropriate in your program.
KSAM INTRINSIC SUMMARY
Table 4-1 is provided to give an overview of the intrinsics available for accessing KSAM
les. In this table, the intrinsics are organized into functional groupings. In the body of
this section, however, the intrinsic descriptions are in alphabetic order so that they may be
referenced easily.
In Table 4-1, an asterisk (*) preceding an intrinsic name indicates that this intrinsic applies
only to KSAM les. A bracket around an intrinsic name indicates that the intrinsic should
not be used for KSAM les.
INTRINSIC FORMAT
Intrinsic format is illustrated below using FCHECK as an example.
IV
I
I
D
I
FCHECK(lenum,errorcode,tlog,blknum,numrec);
O-V
Optional parameters are indicated by an underline under each option and by the superscript
O-V. The parameter type and whether it is passed by value is shown by the superscript over
each parameter. Possible parameter types are:
BA
Byte array
BP
Byte pointer
D
Double
DA
Double array
DV
Double by value
I
Integer
IA
Integer array
IV
Integer by value
L
Logical
LA
Logical array
LV
Logical by value
R
Real
PASSING PARAMETERS
Integer,logical and double type parameters can be passed by value. This means that the
actual value can be specied in the intrinsic call instead of a variable or array name. When a
parameter is passed by reference (default for all parameter types), the address in the caller's
data area of the named variable or array is made available to the intrinsic. If the variable or
array is modied by execution of the intrinsic, the storage in the caller's data area is updated.
When a parameter is passed by value, the corresponding variable in the calling routine is
unchanged.
USING KSAM FILES IN SPL PROGRAMS
4-5
OPTIONAL PARAMETERS
If any parameters can be omitted, the superscripts that describe individual parameters are
followed by the superscript O-V, option variable. O-V means that at least one parameter
in the list is optional. Since all parameters are recognized by their position in the list, a
parameter may be omitted but its preceding comma must be included. If one or more
parameters are omitted from the end of the list, this is indicated by placing the terminating
parenthesis after the last specied parameter.
For example:
FCHECK(FILEX , , , , REC)
FCHECK(2,ERR)
4-6
only the rst and fth parameters are included
the last three parameters are omitted; note that
lenum is passed by value
USING KSAM FILES IN SPL PROGRAMS
KSAM RECORD POINTERS
Certain KSAM procedures use pointers that indicate the current record position in the le.
Depending on the procedure, either of two pointers may be used:
* Logical Record Pointer
Points to a key in the key file that
identifies a particular record in
the data file.
* Chronological Record
Pointer
Points directly to a record in the data
file based on its chronological record number.
Procedures that use these pointers are either pointer-dependent or pointer-independent .
Pointerdependent procedures expect the pointer to be positioned in order to execute correctly.
Pointerindependent procedures, on the other hand, execute regardless of where the pointer is
positioned, and in most cases, they position the pointer. Because the position of the pointer
is signicant for pointer-dependent procedures, Table 4-2 denes exactly where each pointer
is located following successful execution of those procedures that either depend on or position
the pointer.
USING KSAM FILES IN SPL PROGRAMS
4-7
Table 4-2. Positioning the Pointers
PROCEDURE
NAME
POINTER
TYPE
POINTERDEPENDENT
POSITION OF POINTER AFTER
EXECUTION OF PROCEDURE
FFINDBYKEY
Logical
NO
Points to key whose value was specied in call.
FFINDN
Logical
NO
Points to key whose relative record number was
specied in call.
FREADBYKEY
Logical
NO
Points to key whose value was specied in call.
FWRITE
Logical
NO
Points to key whose value is next in ascending key
sequence to the key value in the record just
written.
FPOINT
Chronological
NO
Points to record whose relative record number was
specied in call.
FREADDIR*
Chronological
NO
Points to record whose relative record number was
specied in call.
FREAD
Logical
YES
Pointer remains positioned to key for the record
just read; unless next call is to FREAD or to
FUPDATE followed by FREAD, in which case,
pointer is advanced to next key in sequence before
the next FREAD reads the record. (This permits
sequential reads and updates.)
FSPACE
Logical
YES
Positioned forward or backward, in key sequence,
the number of records specied in call.
FREMOVE
Logical
YES
Points to next key value, in ascending sequence,
to the key value in the record just deleted.
FUPDATE
Logical
YES
Pointer remains positioned to key of the record
just modied; unless any key value is changed, in
which case, it points to next key in ascending
sequence after the key in the modied record.
FREADC
Chronological
YES
Pointer remains positioned to the record just
read; unless next call is to FREADC, in which
case, it points to next record in ascending
chronological sequence.
* Except for FREADDIR, each of these procedures positions both pointers. That is, all
procedures that position the logical pointer also position the chronological pointer, and all
calls (except FREADDIR) that position the the chronological poiner also position the logical
pointer.
(Refer to appendix B, Extra Data Segments With Shared Access, for details of how KSAM
determines pointer position.)
4-8
USING KSAM FILES IN SPL PROGRAMS
SHARED ACCESS
The position of the record pointers is crucial during shared access because the pointers are
maintained in separate control blocks (extra data segments) for each open le. Thus, if the
same le is opened by dierent users, any user may change the key le structure by adding
or deleting records so that other users' pointers become invalid. To avoid this problem, it is
good practice to lock the le in a shared environment before calling a procedure that positions
the pointer and leave the le locked until any pointer-dependent operation is complete. This
means that you should lock the le, call a procedure that sets the pointer, and then call a
procedure that reads the le sequentially or updates the le, and then unlock the le so other
users may access it. Once the le is unlocked, no user should assume that his pointers will still
be valid. Before using a pointer again, it must be re-established.
USING KSAM FILES IN SPL PROGRAMS
4-9
FCHECK
INTRINSIC NUMBER 10
Requests details about le input/output errors.
IV
I
I
D
I
FCHECK(filenum,errorcode,tlog,blknum,numrecs);
O-V
When a le intrinsic returns a condition code indicating a physical input/output error,
additional details may be obtained by calling FCHECK. This intrinsic applies to les on any
device.
FCHECK accepts zero as a legal lenum parameter value. When zero is specied, the
information returned in errorcode reects the status of the last call to FOPEN. When an
FOPEN fails, there is no le number that can be referenced in lenum . Therefore, when
an FOPEN fails, a lenum of zero can be used in the FCHECK intrinsic call to obtain the
errorcode only. If the tlog , blknum , or numrecs parameters are specied, a zero value is
returned to these parameters. If a lenum of zero is used for a le which has been opened but
not yet closed, the returned errorcode is meaningless.
PARAMETERS
lenum
errorcode
tlog
blknum
numrecs
4-10
integer by value (required)
A word identier supplying the le number of the le for which error
information is to be returned.
integer (optional)
A word to which is returned the error code specifying the type of error that
occurred. If no error occurred errorcode is set to zero. (Refer to Table 4-3 for
the errorcode values.) The intrinsic FERRMSG returns a displayable message
that corresponds to the value of errorcode .
Default: The error code is not returned .
integer (optional)
A word to which is returned the transmission log value recorded when an
erroneous data transfer occurs. This word species the number of words not
read or written (those left over) as the result of an input/ output error.
Default: The transmission log value is not returned.
double (optional)
A double word to which is returned the relative number of the block involved
in the error.
Default: The block number is not returned.
integer (optional)
A word to which is returned the number of logical records in the bad block.
Default: The number of logical records is not returned.
USING KSAM FILES IN SPL PROGRAMS
CONDITION CODES
CCE
CCG
CCL
Request granted.
Not returned by this intrinsic.
Request denied because lenum was invalid and errorcode is 72, or a bounds
violation occurred while processing this request and errorcode is 73.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
Table 4-3. FCHECK
Table 4-3. FCHECK
errorcode
errorcode
Parameter Format
Parameter Format (continued)
USING KSAM FILES IN SPL PROGRAMS
4-11
Table 4-3. FCHECK
4-12
errorcode
USING KSAM FILES IN SPL PROGRAMS
Parameter Format (continued)
Table 4-3. FCHECK
errorcode
Parameter Format (continued)
USING KSAM FILES IN SPL PROGRAMS
4-13
4-14
USING KSAM FILES IN SPL PROGRAMS
FCLOSE
INTRINSIC NUMBER 9
Closes a le.
IV
IV
IV
FCLOSE(lenum,disposition,seccode);
The FCLOSE intrinsic terminates access to a le. This intrinsic applies to les on all devices.
FCLOSE deletes the buers and control blocks through which the user process accessed the
le. It also deallocates the device on which the le resides and it may change the disposition
of the le. If you do not issue FCLOSE calls for all les opened by your process, such calls are
issued automatically by MPE when the process terminates.
PARAMETERS
lenum
disposition
seccode
Note
integer by value (required)
A word identier supplying the le number of the le to be closed.
integer by value (required)
Indicates the disposition of the le, signicant only for les on disc. This
disposition can be overridden by a corresponding parameter in a :FILE
command entered prior to program execution. The disposition options are
dened in Table 4-4
Default: disposition is zero for no change, no return of disc space.
integer by value (required)
Denotes the type of security initially applied to the le, signicant only for
new permanent les. The options are:
0|Unrestricted access|the le can be accessed by any user, unless prohibited
by current MPE provisions.
1|Private le creator security|the le can be accessed only by its creator.
Default: seccode is zero for unrestricted access.
Both parameters are required when FCLOSE is specied in a program; the
default values are used when MPE closes any open les at the end of a job or
session.
USING KSAM FILES IN SPL PROGRAMS
4-15
Table 4-4. FCLOSE
disposition
0 1 3 4 5 6 7 8 9 10 11
Parameter Bit Settings
12
13 14 15
Disc Space Domain
Set shaded areas to zero for KSAM les.
BITS
OPTION
13:3
Domain
12:1
Disc Space
Disposition
SETTINGS
000 = No change. (default) The disposition code remains as it
was before the le was opened. Thus, if the le is new,
it is deleted by FLCOSE: otherwise, the le is assigned
the domain to which it previously belonged.
001 = Permanent le. If a disc le, it is saved in the system
domain. If the le is a new or temporary le, an entry is
created for it in the system le directory. An error code
is returned if a le of the same name already exists in
the directory. This disposition has no eect when the
le is an old permanent le on disc.
010 = Temporary job le. This le is retained in the user's
temporary (job/session) le domain. It can be requested
by any process within the job/session. The uniqueness
of the le name is checked and if a le of the same name
already exists, an error code is returned.
011 = Temporary job le. This option has the same eect as
disposition code 010.
100 = Released le. The le is deleted from the system.
0 = No return. (default) Any disc space allocated to the le
that is beyond the end-of-le indicator is not returned
to the system. This option is recommended for KSAM
les.
1 = Return disc space. Any disc space allocated beyond the
end-of-le indicator is returned to the system. This
option is not recommended for KSAM users since the
returned space cannot be recovered.
CONDITION CODES
CCE
CCG
CCL
4-16
The le was closed successfully.
Not returned by this intrinsic.
The le was not closed, perhaps because an incorrect lenum was specied, or
because another le with the same name and disposition exists in the system.
USING KSAM FILES IN SPL PROGRAMS
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FCLOSE
The FCLOSE intrinsic terminates access to a le so that it cannot be accessed again by the
current program until it is re-opened. FCLOSE can also be used to change the disposition
currently assigned to a le by a previous FOPEN.
Because of the special structure of KSAM les, it is not good practice to set the disc space bit
in the disposition parameter in an attempt to save disc space. For this reason, 4 is the largest
value that should be assigned to the disposition parameter when using FCLOSE to close a
KSAM le.
When a le is opened by the FOPEN intrinsic, a le count maintained by the system is
incremented by one. When the le is closed with FCLOSE, the le count is decremented by
one. If more than one FOPEN is in eect for a particular le, its disposition is recorded by
the FCLOSE call but is not put into eect until the le count is zero. The eective disposition
at that time is the smallest non-zero disposition parameter specied among all the FCLOSE
calls issued against the le. For example, a le XYZ is opened three successive times by a
process. The rst FCLOSE disposition is 1, the second FCLOSE disposition is 4, and the
third and last FCLOSE disposition is 2. The nal disposition of the le XYZ is 1, that is, it is
saved as a permanent le with no return of disc space.
The use of FCLOSE diers slightly in its application to new les or to existing les.
CLOSING A NEW KSAM FILE
When a new le is created by FOPEN, the job temporary and system le domains are not
searched to determine whether a le of the same name exists already. Only when a le is
closed and saved as a permanent or temporary le with FCLOSE, is such a search conducted.
The job temporary le domain is searched if the le is closed with the domain eld of
disposition set to 2 or 3 (save as temporary le); the system le domain is searched if the le
is closed with domain set to 1 (save as permanent le). If a le of the same name is found in
either directory, an error code is returned. Thus it is possible to open a new le with the same
name as an existing le, but an error results if FCLOSE is used to save such a le in the same
domain with a le of the same name.
In general, unless you plan to use the le once and then delete it, a newly created le should
be closed using FCLOSE with the disposition parameter set to 1, 2, or 3. There is no need to
set disposition to 4 in order to delete a new le since a new le is deleted when it is closed
with a disposition of 0.
The security code parameter (seccode ) is set only when the disposition parameter is set to
1. If you want exclusive access to a le being saved as a new permanent le, you should set
seccode to 1 when you close the le for the rst time. Otherwise, the le can be accessed by
any other user.
In Figure 4-1, a new le is closed and saved as a permanent le in the system le domain
(disposition = 1), and access is permitted to the le by other users (seccode = 0).
USING KSAM FILES IN SPL PROGRAMS
4-17
CLOSING AN EXISTING KSAM FILE
Unless you plan to change the domain where a le is saved, you usually close an existing le
with both FCLOSE parameters set to zero. There are two limitations: you cannot change an
existing permanent le to a temporary le, and you cannot change the security code that was
assigned to a permanent le at creation.
&lt;&lt;**************************************&gt;&gt;
&lt;&lt;* READ DATA FROM $STDIN DEVICE
*&gt;&gt;
&lt;&lt;**************************************&gt;&gt;
L1 :
READ(INPUT,-72): &lt;&lt;READ ONE RECORD FROM $STDIN&gt;&gt;
IF &gt;
THEN BEGIN &lt;&lt;END OF FILE ON $STDIN&gt;&gt;
FCLOSE(FILNUM,1,0); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN &lt;&lt;CANNOT CLOSE THE KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;:
PRINT (MESSAGE,-29,0):
FCHECK(FILNUM,ERRORCODE): &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH):&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,-LENGTH,0)1 &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGE,-34,0);
TERMINATE;
END;
PRINT(OUTPUT,-72,0); &lt;&lt;ECHO CHECK&gt;&gt;
Figure 4-1. FCLOSE Example
Assume, for example, that a le was closed as a job temporary le. Should you want to make
the le permanent, close the le with the following call:
FCLOSE(FILENUM,1,0) close job temporary le as permanent le
If, however, you want to maintain this le with its cu ent disposition, you would close it with
the following call:
FCLOSE(FILENUM,0,0) close le with current disposition
Regardless of the value assigned to seccode , the type of security initially applied to the le
when it is closed as a new permanent le is not subsequently changed.
DELETING A KSAM FILE
The FCLOSE intrinsic can be used to delete a KSAM le from the system. If you intend to
use a new le once only, you can delete it at the same time you close it for the rst time by
setting the FCLOSE parameters to zero:
FCLOSE(FILNUM,0,0) delete a new le
In this case, because disposition is zero, the le is returned to its domain before FCLOSE is
executed. Since the le is not assigned a domain until it is closed the rst time, this eectively
deletes the le.
4-18
USING KSAM FILES IN SPL PROGRAMS
A le that has been assigned to a domain by a previous FCLOSE, can be deleted by the call:
FCLOSE(FILNUM,4,0) delete an existing le
Note that the only other methods for deleting a KSAM le are to use the
KSAMUTIL&gt;PURGE command, or to issue two MPE :PURGE commands, one for
the data le and one for the key le.
USING KSAM FILES IN SPL PROGRAMS
4-19
FCONTROL
INTRINSIC NUMBER 13
Performs control operations on a KSAM le.
IV
IV
L
FCONTROL(lenum,controlcode,param);
The FCONTROL intrinsic performs various control operations on a KSAM le. When
specied for a KSAM le, these control operations are limited to the following:
Complete input/output
Rewind the le
PARAMETERS
lenum
controlcode
param
integer by value (required)
A word identier supplying the le number of the le for which the control
operation is to be performed.
integer by value (required)
An integer identifying the operation to be performed:
2 = Complete Output. This insures that requested output has been physically
completed; that is, that the key buers, data buers, and KSAM control
information are all written to disc.
When access is shared, you must lock the le with FLOCK before calling
FCONTROL with control code 2.
5 = Rewind File. This repositions the le at its beginning, so that the next
record read or written is the rst logical record in the le. When this code is
used for KSAM les, the le is not repositioned to the rst physical record
but to the rst logical record. The rst logical record is the record with the
lowest value in the current key (primary or alternate)
[***text removed at this point***]
logical (required)
This parameter may be specied as any variable or word identier; it is
needed by FCONTROL to satisfy internal requirements of the intrinsic, but
serves no other purpose and is not modied by the instrinsic.
CONDITION CODES
CCE
CCG
CCL
4-20
Request granted.
Not returned by this intrinsic.
Request denied because an error occurred. Returned if any control code
other than 2, 5, 6, or 7 is specied for a KSAM le; or the le was opened for
shared access, but was not locked for control code 2 or 6.
USING KSAM FILES IN SPL PROGRAMS
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FCONTROL
FCONTROL provides four control functions for KSAM les. These allow you to write the
key and data buers and all KSAM control information to disc; to position the logical record
pointer to the rst logical record in the le; to write the buers, KSAM control information,
plus the MPE endof-le and the latest extent bit map, to disc; and to clear all the data
buers and the latest control information from disc.
The control functions that write the buers to disc (2 and 6) require that you lock the le
before calling them in a shared access environment.
USING CONTROL CODE 2
When you use control code 2, the data block and key block buers and the KSAM control
information (including the KSAM end-of-le) are written to disc. (The data written is that
contained in the Extra Data Segment for the open le|refer to Figure B-11 for details.)
This control code is particularly useful to make sure the KSAM le reects current changes.
Suppose, for instance, that you open a KSAM le exclusively for a long period of time and
that your data buer holds many records. In this case, you can call FCONTROL with code
2 after writing or updating a certain number of records to insure that no more than that
number of records will be lost in case of a system failure.
For example, you could call FCONTROL every 10 records:
IF COUNT = 10
counter set by each FWRITE or FUPDATE
THEN BEGIN
FCONTROL(FILNUM,2,DUMMY);
END;
Note
Note that the parameter DUMMY has no function. It is supplied because all
FCONTROL parameters are required. It should be declared in the program as
a word variable: LOGICAL DUMMY;
As a result of the call shown above, you can never lose more than 10 records in case of a
system failure. When a system failure occurs with a KSAM le open, you must run the
KSAMUTIL command KEYINFO to allow the le to be reopened. KEYINFO also sets
the MPE end-of-le to the current position of the KSAM end-of-le. Control code 2 of
FCONTROL makes sure that the KSAM end-of-le follows the last record written to your le.
In a shared environment, be sure to lock your le before calling FCONTROL with control
code 2. Otherwise, the call will fail.
USING CONTROL CODE 5
This control code repositions the le to the rst logical record, that is, the record with
the lowest key value. The key that determines this position can be the primary key or an
alternate key, depending on which key was accessed last. Suppose you want to read the
KSAM le in sequence starting with the record containing the lowest primary key value, you
can position to this record using FCONTROL as follows:
USING KSAM FILES IN SPL PROGRAMS
4-21
FCONTROL(FILNUM,5,DUMMY); positions to 1st record in primary key sequence
USING CONTROL CODE 6
This control code performs the same functions as control code 2, except that it also writes
the MPE end-of-les for the KSAM les and the latest extent bit map to disc. Because it
must access the MPE control blocks as well as the KSAM control block, this code takes more
time than code 2. Also, since the MPE end-of-les and the extent bit map are written to disc
automatically whenever a new extent is allocated, this code is useful primarily when a series of
updates changes the buers but does not cause new extents to be allocated, and when access
to the le is exclusive. If access is shared, you must lock the le before using control code 6.
USING CONTROL CODE 7
This control code clears the buers so that the next call to a read instrinsic must get the
record from disc rather than from the buers. It also forces the latest control information to
be read from disc to the buers. Note that a call to FLOCK will also clear the buers. The
advantage of FCONTROL with code 7 over FLOCK is that it saves time|the buers are
cleared without locking and then unlocking the le. Thus, you can call FCONTROL with
code 7 immediately before calling a read instrinsic in a shared environment in order to get the
latest information from disc. However, this does not guarantee that this latest information
is not changed (modied or deleted) by other users while you are calling FCONTROL. The
only complete safeguard is to lock the le before the read. In any case, if you are making
modications, you should lock the le. For example:
FCONTROL(FILNUM,7,DUMMY);
FREAD(FILNUM,DATA,-72);
..
.
FLOCK(FILNUM,TRUE);
FREAD(FILNUM,DATA,-72);
FUPDATE(FILNUM,DATA,-72);
FUNLOCK(FILNUM);
4-22
clear buers
read record from le
lock le
rewrite record just read
unlock le
USING KSAM FILES IN SPL PROGRAMS
FERRMSG
INTRINSIC NUMBER 307
Returns message corresponding to FCHECK error number.
I
LA
I
FERRMSG(errorcode,msgbuf,msglgth);
A call to FERRMSG causes a message to be returned to msgbuf that corresponds to an
FCHECK error or number. This makes it possible to display an error message from your
program. The message describes the error associated with the error number provided in the
parameter errorcode .
PARAMETERS
errorcode
msgbuf
msglgth
integer (required)
A word identier containing the error code for which a message is tobe
returned. It should contain an error number returned by FCHECK.
logical array (required)
A logical array to which the message associated with errorcode is returned by
FERRMSG. In order to contain the message string, msgbuf must be dened
as at least 72 characters (36 words) long.
integer (required)
A word identier to which is returned the length of the msgbuf string. The
length is returned as a positive byte count.
CONDITION CODES
Condition codes are not returned by this procedure.
USING FERRMSG
This intrinsic is called usually following a call to FCHECK. The error code returned in the
call to FCHECK can then be used as a parameter in the call to FERRMSG.
For example, suppose a CCL condition is returned by a call to FCLOSE, a call to FCHECK
requests the particular e or code, then a call to FERRMSG can be used to retrieve a
printable message associated with the code.
FCLOSE(FILNUM,1,0);
IF&lt;
THEN BEGIN
FCHECK(FILNUM,ERRNUM);
FERRMSG(ERRNUM,MESSAGE,LENGTH);
PRINT(MESSAGE,-LENGTH,0);
END
TERMINATE;
The message printed explains the FCHECK code. If the FCHECK code has no assigned
meaning, the following message is returned:
UNDEFINED ERROR errorcode
USING KSAM FILES IN SPL PROGRAMS
4-23
FFINDBYKEY
INTRINSIC NUMBER 302
Positions record pointer to record located by a key value.
IV
BA
IV
IV
FFINDBYKEY(lenum,keyvalue,keylocation,keylength,relop);
IV
When FFINDBYKEY is executed, the logical record pointer is set to the beginning of a
record located by this intrinsic. The particular key is dened by the keylocation parameter,
The pointer is positioned to the rst record containing a key value that bears the relation
specied by relop to the value specied by keyvalue . A partial key can be specied by a
keylength value less than the dened key length. If, however, the key type specied at le
creation was numeric display or packed decimal, a type where the sign is stored in the least
signicant byte, partial keys cannot be specied.
FFINDBYKEY also positions the chronological pointer.
PARAMETERS
lenum
keyvalue
keylocation
keylength
relop
4-24
integer by value (required)
A word identier supplying the le number of the le to be positioned.
byte array (required)
A byte array containing a value that is used to locate the record at which
the pointer is positioned. The key value in the record must be in the relation
specied by relop to the value in array keyvalue .
integer by value (required)
The keylocation parameter species the relative byte location of the key being
used. Bytes are numbered starting with 1. If keylocation is zero, then the
primary key is used.
integer by value (required)
This parameter species the length of the key in bytes. If it equals zero, the
entire key is used. If less than the full key length (generic key), then only the
length specied here is used in the comparison with relop . The keylength
parameter must be equal to or less than the full length of the key when the
le was created. For keys of type numeric display or packed decimal, the full
key length must be used.
integer by value (required)
A relational operator that species the relation of the key value in the le to
the value specied in keyvalue . The record to which the le is positioned will
have this relation to keyvalue following execution of FFINDBYKEY:
0 - equal
1 - greater than
2 - equal to or greater than
When relop is set to 1 or 2, the search is for an approximate key.
USING KSAM FILES IN SPL PROGRAMS
CONDITION CODES
CCE
CCG
CCL
Request granted.
The requested position was beyond the logical end-of-le or beginning of le.
Request denied because an error occurred. The error could be a disc
input/output error; the relational operator (relop ) could not be satised; a
keylength less than the fulllength was specied for a key with numeric display
or packed decimal format; or a key is not found in the key le when the
relational operator is equal.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FFINDBYKEY
The intrinsic FFINDBYKEY allows you to position the le to a record containing a
particular key value. Usually, you will do this in order to read in ascending sequence from
that particular record. If you simply want to locate and read a single record, you should use
FREADBYKEY.
In Figure 4-2, FFINDBYKEY is used to position the le to the record containing the lowest
value of an 8-byte alternate key in which a telephone number is stored. After FFINDBYKEY
positions the le to this record, a series of FREAD statements read the records in ascending
order according to the value of the key specied by FFINDBYKEY. (Refer to shaded portions
of the program for the FFINDBYKEY declarations and statements).
FFINDBYKEY can also be used prior to a call to FREADC in order to position the
chronological pointer to the record located by the specied key.
USING APPROXIMATE KEYS
In order to nd the lowest-valued telephone number, keyvalue is set to the value \000-0000&quot;.
The key to be searched for this value is identied by its position in the record. In this case,
the alternate key containing the telephone number starts in byte position 21, and keylocation
is set to the value 21. The fulllength of the key is specied in keylength as the value 8.
In order to position to the record whose alternate key value is equal to or greater than
\000-0000&quot;, the value of relop is set to 2.
When executed, FFINDBYKEY will locate the record with an 8-byte value starting in byte
21 that is either equ\000-0000&quot; or is the lowest value greater \000-0000&quot;. Since the value
\000-0000&quot; is not a valid telephone number, the value of relop could be set to 1 indicating the
lowest value greater than \000-0000&quot;. An error condition is returned if the value in keyvalue
cannot be located. For this reason, relop should not be set to 0 unless it is expected that the
value being sought exists.
USING PARTIAL (GENERIC) KEYS
If the value of keylength is less than the length of the key at creation, this allows a search for
a partial (generic) key. For example, assume a le with a 20- byte key starting in byte 2 of
each record. This key contains a name entered last name rst. If you want to nd and read
USING KSAM FILES IN SPL PROGRAMS
4-25
all records starting with the letter \R&quot; through the last record in sequence by key, you could
assign the following FFINDBYKEY values:
INTEGER
FILNUM;
BYTE ARRAY
FILNAME(0:9):=&quot;KSAMFILE &quot;;
BYTE ARRAY
KEYVALUE(0:4):=&quot;R&quot;;
INTEGER
KEYLENGTH:=1;
INTEGER
KEYLOCATION:=2;
INTEGER
RELOP:=2;
..
.
INTRINSIC
FOPEN,FCLOSE,FREAD,FWRITE,FFINDBYKEY;
..
.
FFINDBYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP)
When executed, FFINDBYKEY will position to the rst record with a key value whose rst
(leftmost) character is the letter \R&quot;. A subsequent series of FREADs will read that record
and position to the next record in sequence by the same key.
SHARED ACCESS
If you use FFINDBYKEY to position the pointer before calling another procedure to read or
update the le in a shared environment, you must call FLOCK to lock the le before calling
FFINDBYKEY. Then, after performing the read or update operation, you can unlock the
le. If you call FFINDBYKEY and then lock the le before an operation that depends on the
record pointer, another user could move the pointer between the call to FFINDBYKEY and
FLOCK.
4-26
USING KSAM FILES IN SPL PROGRAMS
&lt;&lt;******************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 2
*&gt;&gt;
&lt;&lt;*
READ A KSAM FILE SEQUENTIALLY
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;******************************************************&gt;&gt;
INTEGER FILNUM:
INTEGER ERRORCODE,LENGTH;
BYTE ARRAY FILNAME(0:9)=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
BYTE ARRAY KEYVALUE(0:7):=&quot;000-0000&quot;;
INTEGER KEYLENGTH:=8;
INTEGER KEYLOCATION:21;
INTEGER RELOP:=2;
INTRINSIC FOPEN,FCLOSE,FREAD,FFINDBYKEY,READ,PRINT,
FCHECK,FERRMSG,TERMINATE;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;************************&gt;&gt;
FILNUM:=FOPEN(FILNAME,3); &lt;&lt;OPEN THE KSAM FILE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,-21,0);
FCHECK(FILNUM,ERRORCODE),; &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FEERMSG(ERRORCODE,MESSAGE,LENGTH); &lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,-LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;* READ DATA FROM KSAM FILE IN TELEPHONE # SEQUENCE
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
L2:
FFINDBYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP);
MOVE MESSAGE:=&quot;** LIST IN TELEPHONE NO. SEQUENCE&quot;;
PRINT (MESSAGE,-33,0);
L3:
FREAD(FILNUM,INPUT,-72); &lt;&lt;READ SEQUENTIALLY BY ALTERNATE KEY&gt;&gt;
IF &gt;
THEN BEGIN
&lt;&lt;END OF FILE&gt;&gt;
Figure 4-2. FFINDBYKEY Example
USING KSAM FILES IN SPL PROGRAMS
4-27
FCLOSE(FILNUM,0,0);
&lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt; &gt; THEN
BEGIN &lt;&lt;CLOSE UNSUCCESSFUL&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;;
PRINT(MESSAGE,-29,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH) &lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,-LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE;=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGE,-34,0);
TERMINATE;
END;
PRINT(OUTPUT,-72,0);
&lt;&lt;**********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;**********************************&gt;&gt;
GO TO L3:
Figure 4-2. FFINDBYKEY Example (continued)
4-28
USING KSAM FILES IN SPL PROGRAMS
FFINDN
INTRINSIC NUMBER 301
Positions the logical record pointer to relative record number according to key sequence.
IV
DV
IV
FFINDN(lenum,number,keylocation)
When FFINDN is executed, it positions the KSAM logical record pointer to the record whose
relative record number is specied in the parameter number . Records are numbered from the
record with the lowest key value in the key that starts at keylocation in each record. Record
numbering starts with zero unless the agword in the FOPEN ksamparam parameter species
that record numbering starts with 1, or the FIRSTREC parameter in the &gt;BUILD command
is set to 1.
PARAMETERS
lenum
number
keylocation
integer by value (required)
A word identier supplying the le number of the le to be positioned.
double by value (required)
Relative record number counting from the rst logical record in the le.
Record numbers start with zero or one depending on the record numbering
scheme specied at le creation; the lowest numbered record applies to the
record with the lowest value in the specied key eld. A negative record
number positions the le pointer to the record with the smallest key value.
integer by value (required)
The relative byte location in the record of the key to be used. The rst byte
is byte 1. If keylocation is set to zero, the primary key is assumed.
CONDITION CODES
CCE
CCG
CCL
Request granted.
The requested position was beyond the logical end-of-le.
Request denied because an error occurred.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FFINDN
When you specify the relative record number, it is important not to confuse this number
with the chronological record number, the number of the record as it is stored in the le. To
illustrate, assume a le in which records have been stored in chronological order from the
beginning of the le (BOF). Each record has a key starting in byte 3 that contains a name.
The relative record number is based on the value of this key, not the relative location of the
record in the le.
For example:
USING KSAM FILES IN SPL PROGRAMS
4-29
FFINDN(FILNUM,4D,3)
This call positions the logical record pointer (as shown in Figure 4-3) to record number 4 of
the key at location 3. Note that record number 4 is the fth record in the sequence of key
values:
ABLE
relative record 0D
BAKER
relative record 1D
CHARLIE
relative record 2D
DOG
relative record 3D
EASY
relative record 4D
FOX
relative record 5D
If you want to position the chronological record pointer to the relative record number in
chronological sequence from the beginning of the le, you can use the intrinsic FPOINT,
discussed later in this section. Chronological order is the order in which records are written.
In Figure 4-3, record number 4 in key order, to which FFINDN positioned the le pointer, is
also record number 2 in chronological order.
Figure 4-3. File Position with FFINDN
Note that FFINDN is useful to reset the pointer to an alternate key. For example, when you
open the le, the primary key is selected by default. If you want to select another key starting
in location 23 and position to the rst record in key sequence, you can use the following
command:
FFINDN(FILNUM,-1,23)
SHARED ACCESS
If you use FFINDN to position the pointer before calling another procedure that reads or
updates the le in a shared environment, you must call FLOCK before calling FFINDN.
Then, after performing the read or update operation, you should unlock the le so other users
can access it. If you lock the le after calling FFINDN, another user can change the pointer
position without your program being aware of it.
4-30
USING KSAM FILES IN SPL PROGRAMS
FGETINFO
INTRINSIC NUMBER 11
Requests access and status information about a le.
IV
BA
L
D
D
L
I
I
L
FGETINFO (lenum,lename,foptions,aoptions,recsize,devtype,ldnum,hdaddr,
I
D
D
D
I
lecode,recpt,eof,imit,logcount,physcount,blksize,extsize,
I
I
BA
D
numextents,userlabels,creatorid,labaddr);
L
L
O-V
Once a le is opened on any device, the FGETINFO intrinsic can be used to request access
and status information about that le.
PARAMETERS
lenum
lename
foptions
aoptions
recsize
integer by value (required) A word identier supplying the le number of the
le about which information is requested.
byte array (optional) A byte array to which is returned the actual designator
of the le being referenced, in this format:
f.g.a
where
f = the local le name
g = the group name (supplied or implicit).
a = the account name (supplied or implicit).
The byte array must be 28 bytes long. When the actual designator is
returned, unused bytes in the array are lled with blanks on the right.
Default: The actual designator is not returned .
logical (optional) The foptions parameter returns seven dierent le
characteristics by setting corresponding bit groupings in a 16-bit word.
Correspondence is from right to left. The le characteristics returned are
the same as those specied for foptions in the FOPEN intrinsic (refer to
Table 4-6, in the FOPEN description). Note that bit 4 is set to 1 to indicate a
KSAM le.
Default: Foptions are not returned.
logical (optional) The aoptions parameter returns up to seven dierent access
options represented by bit groupings in a 16-bit word, as described for the
aoptions parameter of FOPEN (refer to Table 4-7 in the FOPEN description).
Default: Aoptions are not returned.
integer (optional) A word to which is returned the logical record size
associated with the le. If the le was created as a binary type, this value is
USING KSAM FILES IN SPL PROGRAMS
4-31
positive and expresses the size in words. If the le was created as an ASCII
type, this value is negative and expresses the size in bytes.
devtype
ldnum
hdaddr
lecode
recpt
eof
4-32
Default: The logical record size is not returned.
integer (optional) A word to which is returned the type and subtype of device
being used for the le, where
bits (0:8) = device subtype, and
bits (8:8) = device type.
If the le is not spooled, which can be determined from hdaddr (0:8), the
returned devtype is actual. The same is true if the le is spooled and was
opened via logical device number. However, if an output le is spooled and
was opened by device class name, devtype contains the type and subtype of
the rst device in its class, which may be dierent from the device actually
used.
Default: The device type and subtype are not returned.
logical (optional) A word to which is returned the logical device number
associated with the device on which the le resides.
If the le is a disc le, then the logical device number will be that of the rst
extent. If the le is spooled, then ldnum will be a virtual device number
which does not correspond to the system conguration I/O device list.
Default: The logical device number is not returned.
logical (optional) A word to which the hardware address of the device is
returned, where
bits (0:8) = the Device Reference Table (DRT) number, and
bits (8:8) = the unit number.
If the device is spooled, the DRT number will be zero and the unit number is
undened.
Default: The hardware address is not returned.
integer (optional) A word to which is returned the value recorded with the le
as its data le code (for disc les only).
Default: The le code is not returned.
double (optional) A double word to which a double integer representing the
current chronological record pointer setting is returned. Following a call to
FREADC for example, recpt would be the chronological record number of
the record just read by the FREADC intrinsic. Remember that chronological
record numbers can begin with 0 or 1, depending on how the le was built.
Default: The chronological record pointer setting is not returned.
double (optional)
A double word to which is returned a double positive integer equal to the
number of logical records currently in the data le. If the le does not reside
on disc, this value is zero.
Default: The number of logical records in the le is not returned.
USING KSAM FILES IN SPL PROGRAMS
imit
logcount
physcount
blksize
extsize
numextent
userlabels
creatorid
labaddr
double (optional) A double word to which is returned a double positive integer
representing the number of the last logical record that could ever exist in the
data le because of the physical limits of the le.
Default: The le limit information is not returned.
double (optional) A double word to which is returned a double positive integer
representing the total number of logical records passed to and from the user
during the current access of the le.
Default: The logical record count is not returned.
double (optional) A double word to which is returned a double positive integer
representing the total number of physical input/output operations performed
within this process against the le since the last FOPEN call.
Default: The number of I/O operations is not returned.
integer (optional) A word to which is returned the block size associated with
the le. If the le was created as a binary type, this value is positive and
expresses the size in words. If the le was created as an ASCII type, this
value is negative and shows the size in bytes.
Default: The block size is not returned.
logical (optional) A word to which is returned the disc extent size associated
with the data le (in sectors).
Default: The disc extent size is not returned.
integer (optional) A word to which is returned the maximum number of disc
extents allowable for the data le.
Default: The maximum allowable number of extents is not returned.
integer (optional) A word to which is returned the number of user header
labels dened for the le when it was created. When an old le is opened for
overwrite output, the value of userlabels is not reset and old user labels are
not destroyed.
Default: The number of user labels is not returned.
byte array (optional) A type array to which is returned the eight-byte name of
the user who created the le. If the le is not a disc le, blanks are returned.
Default: The user name is not returned.
double (optional) A double word to which is returned the sector address of the
label of the le. The high-order eight bits show the logical device number.
The remaining 24 bits show the absolute disc address.
Default: The label address is not returned.
USING KSAM FILES IN SPL PROGRAMS
4-33
CONDITION CODES
CCE
CCG
CCL
Request granted.
Not returned by this intrinsic.
Request denied because an error occurred.
USING FGETINFO
By calling FGETINFO you can return to your program any or all of the items listed as
parameters. Except for the identifying lenumber , each of these parameters is optional. When
omitted, embedded parameters are indicated by commas. Parameters omitted from the end of
the list need not be so indicated. For example, to locate the number of records in the le by
nding the end of le, you can call FGETINFO as follows:
FGETINFO(FILNUM , , , , , , , , , , LSTREC);
\_______________ eof parameter
The value returned to LSTREC is the number of records in the le. The value LSTREC is
also the chronological number of the last record in the le. This number can be used to read
the last chronological record with FREADC or FREADDIR.
Another useful parameter of FGETINFO is recpt . This parameter returns the chronological
record number of the record last read. The example in Figure 4-4 illustrates both these
parameters. First, FGETINFO is used to determine the total number of records in the le
using the parameter eof. Then, each record in the le is read in sequential order by primary
key. Following each sequential read, FGETINFO retrieves the chronological record number of
the record just read.
In the output from the program (refer to Figure 4-4), note that the record number returned
by FGETINFO is the chronological number. For instance, the rst record written to the le
was the record with record number 1. This record, which contains the primary key value
\NOLAN JACK&quot;, is the fourth consecutive record in key sequence.
4-34
USING KSAM FILES IN SPL PROGRAMS
$CONTROL MAIN=JEXAMPLS
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 5
*&gt;&gt;
&lt;&lt;*
FIND NUMBER OF RECORDS &amp; RECORD NUMBER
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
INTEGER FILNUM:
INTEGER ERRORCODE,LENGTH;
BYTE ARRAY FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
DOUBLE EOP,RECPTR;
INTRINSIC FOPEN,FCLOSE,FREAD,FGETINFO,DASCII;
INTRINSIC PRINT,TERMINATE,FCHECK,FERRMSG;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;************************&gt;&gt;
FILNJM:=FOPEN(FILNAME,3); &lt;&lt;OPEN THE KSAM FILE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT (MESSAGE,-21,0);
FCHECK(FILNUM,ERRORCODE): &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH0;&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT (MESSAGE,-LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;****************************************************&gt;&gt;
&lt;&lt;* FIND NUMBER OF RECORDS WRITTEN TO FILE *&gt;&gt;
&lt;&lt;****************************************************&gt;&gt;
FGETINFO(FILNUM,,,,,,,,,,EOF);
IF &lt; &gt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED FINDING NUMBER
OF RECORDS&quot;;
PRINT(MESSAGE,-40,00;
FCHECK(FILNUM,ERRORCODE);
FERRMSG(ERRORCODE,MESSAGE,LENGTH);
PRINT(MESSAGE,-LENGTH,0);
TERMINATE;
END;
Figure 4-4. FGETINFO Example
USING KSAM FILES IN SPL PROGRAMS
4-35
&lt;&lt;****************************************************&gt;&gt;
&lt;&lt;* PRINT NUMBER OF RECORDS IN FILE *&gt;&gt;
&lt;&lt;****************************************************&gt;&gt;
MOVE MESSAGE:=&quot;RECORDS IN ENTITY = &quot;;
DASCII(EOF,10,MESSAGE(9));
PRINT(MESSAGE,-20,0);
L1;
&lt;&lt;****************************************************&gt;&gt;
&lt;&lt;* READ KSAM SEQUENTIALLY *&gt;&gt;
&lt;&lt;****************************************************&gt;&gt;
FREAD(FILNUM,INPUT,-72);
IF &gt;
&lt;&lt;END OF DATA&gt;&gt;
THEN BEGIN
FCLOSE(FILNUM,0,0);
&lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;;
PRINT(MESSAGE,-22,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CINVERT TO STRING&gt;&gt;
PRINT(MESSAGE,-LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
END;
TERMINATE#
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING KSAM FILE&quot;:
PRINT(MESSAGE,037,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMRER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE.LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE#0LENGTH,0): &lt;&lt;PRINTOUT ERRUR MESSAGE&gt;&gt;
TERMINATE;
END#
&lt;&lt;**************************************************&gt;&gt;
&lt;&lt;* WRITE THE DATA JUST READ FROM KSAM FILE *&gt;&gt;
&lt;&lt;**************************************************&gt;&gt;
PRINT(OUTPUT;072,0):
Figure 4-4. FGETINFO Example (continued)
4-36
USING KSAM FILES IN SPL PROGRAMS
&lt;&lt;**********************************************************&gt;&gt;
&lt;&lt;* TO FIND OUT RECORD NUMBER OF THE RECORD JUST READ *&gt;&gt;
&lt;&lt;**********************************************************&gt;&gt;
FGETINFO(FTLENUM,,,,,,,,,RECPTR):
IF &lt; &gt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED FINDING RECORD NUMBER&quot;:
PRINT(MESSAGE,036,0);
FCHECK(FILNUM,ERRORCODE);
FERRMGG(ERRORCODE,MESSAGE,LENGTH);
PRINT(MESSAGE,0LENGTH,0);
TERMINATE;
END;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* PRINT THE RECORD NUMBER OF LAST RECORD READ *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
MOVE MESSAGE:=&quot;RECORD# = &quot;;
DASCII(RECPTR,10,MESSAGE(5) );
PRINT(MESSAGE,012,0);
&lt;&lt;***********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;***********************************&gt;&gt;
GO TO L1;
!EOD;
!EOD
When Executed, the Following Output is Printed:
RECORDS IN FILE= 10
CARDIN RICK 578-7018 11100 WOLFF ROAD CUPERTINO CA. 94053
RECORD# = 4
ECKSTETN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050
RECORD# = 3
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022
RECORD# = 2
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087
RECORD# = 1
PASBY LINDA 295-1187 TOWN &amp; CNTRY VILLAGEF SAN JOSE CA. 94102
RECORD# = 5
ROBERT GERRY 259-5535 12345 TELEGRAPH AVE BERKELEY CA. 90871
RECORD# = 7
SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053
RECORD# = 6
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234
RECORD# = R
WESTEP ELDER 287-4598 1256 KTNGFISHER ST. SUNNYVALE CA. 43098
RECORD# = 10
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234
RECORD# = 9
END OF PROGRAM
Figure 4-4. FGETINFO Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-37
FGETKEYINFO
INTRINSIC NUMBER 303
Requests access and status information about a KSAM le,
IV
A
A
FGETKEYINFO( lenum,ksamparam,ksamcontrol)
PARAMETERS
lenum
ksamparam
ksamcontrol
integer by value (required)
A word identier supplying the lenumber of the le about which information
is requested.
array (required)
An array of the same format and size as the byte array of the same name in
FOPEN (refer to Table 4-8), except that key le size is given as the number of
sectors. The length of the array depends on the number of keys in the KSAM
le; its length is 17 words plus 4 words for each key. Note that the device
(words 6-14) is not returned as a device class name but as an ASCII string
containing the logical device number.
array (required)
An array whose size is 128 words containing control information about the key
le. Refer to Table 4-5 for the denition of the array contents.
CONDITION CODES
CCE
CCG
CCL
Request granted.
(not retuned)
Request denied because an error occurred such as: insucient space declared
for ksamparam or ksamcontrol ; or an illegal le number; or the DB register is
not set to the user stack.
USING FGETKEYINFO
Once a KSAM le is opened, you can request information about the key le through this
intrinsic. The ksamparam return provides static information dened for the key le at the
time it was created. The ksamcontrol parameter provides dynamic information about the use
of the key le from the time it was created. In particular, it provides a count of the number of
times the key le was referenced by various intrinsics, the date and time it was created, closed,
updated or written to, and so forth.
4-38
USING KSAM FILES IN SPL PROGRAMS
Table 4-5. FGETKEYINFO
ksamcontrol
Parameter Format
USING KSAM FILES IN SPL PROGRAMS
4-39
Table 4-5. FGETKEYINFO
4-40
ksamcontrol
USING KSAM FILES IN SPL PROGRAMS
Parameter Format (continued)
FLOCK
INTRINSIC NUMBER 15
Dynamically locks a le.
IV
LV
FLOCK(lenum,lockcond);
The FLOCK intrinsic dynamically locks a le and transfers the latest control information
from disc to the buers. A call to FLOCK is required before any attempt is made to read or
modify a le opened for shared access.
Warning
Always unlock a locked file (refer to FUNLOCK) after reading or modifying it.
Not following this practice may result in corruption of the file.
PARAMETERS
lenum
lockcond
integer by value (required)
A word supplying the le number of the le to be locked.
logical by value (required)
A word specifying conditional or unconditional locking:
TRUE|
Locking will take place unconditionally. If the le cannot be
locked immediately, the calling process suspends until the le
can be locked.
Bit 15 = 1
FALSE|
Locking will take place only if the le's Resource
Identication Number (RIN) is not currently locked. If the
RIN is locked, control returns immediately to the calling
process, with condition code CCG.
Bit 15 = 0
CONDITION CODES
The condition codes possible when lockcond = TRUE are
CCE
Request granted.
CCG
Not returned when lockcond = TRUE.
CCL
Request denied because this le was not opened with the dynamic locking
aoption specied in the FOPEN intrinsic, or the request was to lock more
than one le and the calling process does not possess the Multiple RIN
Capability.
The condition codes possible if lockcond = FALSE are
CCE
Request granted.
CCG
Request denied because the le was locked by another process.
USING KSAM FILES IN SPL PROGRAMS
4-41
Request denied because: this le was not opened with the dynamic locking
aoption specied in the FOPEN intrinsic; or the request was to lock more
than one le and the calling process does not possess the Multiple RIN
Capability.
CCL
SPECIAL CONSIDERATIONS
Split stack calls permitted.
Standard Capability sucient if only one le is to be locked dynamically.
If more than one le is to be locked dynamically, the Multiple RIN Capability is required.
USING FLOCK
The dynamic locking and unlocking capability allows you to complete any update to a le
when it is possible for other users to access the le. When dynamic locking is allowed (bit
10 of FOPEN aoptions parameter is set to allow dynamic locking); then you must use the
FLOCK intrinsic to lock the le before writing, rewriting, or deleting any records. This
requirement insures that another user does not attempt to change the same record at the
same time. FLOCK also insures that the most recent data is available in the le. A locked le
can be unlocked following the update with the FUNLOCK intrinsic.
When FLOCK is executed, it clears all the buers and transfers the latest control information
from the KSAM le to the buers. This insures that any subsequent read of the le retrieves
the latest information from disc rather than from the buers. (Note that FCONTROL control
code 7 also clears the buers.)
If you use the Multiple RIN capability, a sequence of le locking should be agreed upon or
you should use conditional locking (lockcond = FALSE). Otherwise, it is possible to lock
other users from the le. Consider the situation where one program unconditionally locks
le A and then attempts to lock le B. If another program unconditionally locks le B and
then attempts to lock le A, both programs will wait indenitely to lock the second le in
sequence. To avoid this, both programs should agree to lock the les in the sequence A rst,
then B; or both programs should use only conditional locks.
For example, suppose you open a KSAM le called DATA1 for shared access in update mode
and allow dynamic locking and unlocking:
FIL1:=FOPEN(DATA1,7,%345);
The parameters specied are:
lenum
File number of DATA1, which is assigned to FIL1 when the le is opened.
formalName identifying the le contained in DATA1.
designator
foptions
aoptions
The value 7 species that this is an old user le (bits 14,15 = 11) and that it
is coded in ASCII (bit 13 = 1).
The octal value 345 indicates that the le was opened for update (bits 12
through 15 = 0101), that dynamic locking/unlocking is allowed (bit 10 = 1),
and that access is shared (bits 8 and 9 = 11).
This le can then be locked as follows:
4-42
USING KSAM FILES IN SPL PROGRAMS
FLOCK(FIL1,1)
The parameters specied are:
lenum
File number of le DATA1 contained in the variable FIL1.
lockcond
= 1 which means the le is to be locked unconditionally. If the le cannot
be locked immediately, the calling process is suspended until the le can be
locked.
USING KSAM FILES IN SPL PROGRAMS
4-43
FOPEN
INTRINSIC NUMBER 1
Opens a le.
I
BA
LV
LV
IV
BA
lenum:=FOPEN(formaldesignator,foptions,aoptions,recsize,device,ksamparam,
IV
IV
IV
DV
userlabels,blockfactor,numbuers,lesize,numextents,
IV
IV
initialloc,lecode);
BA
IV
O-V
The FOPEN intrinsic makes it possible to access a KSAM le. In the FOPEN intrinsic call, a
particular le may be referenced by its formal le designator . When the FOPEN intrinsic is
executed, it returns to the user's process a le number by which the system uniquely identies
the le. This le number, rather than the le designator, then is used by subsequent intrinsics
in referencing the le.
FUNCTIONAL RETURN
This intrinsic returns an integer le number used to identify the opened le in other intrinsic
calls.
PARAMETERS
formaldesignator
foptions
aoptions
recsize
4-44
byte array (required)
Contains a string of ASCII characters interpreted as a formal le designator.
This string must begin with a letter, contain alphanumeric characters, slashes,
or periods, and terminate with any nonnumeric character except a slash
or a period. If the string names a userpredened le, it can begin with an
asterisk (*). Note: The DEL, SAVE, or TEMP parameters should not be used
to predene a KSAM le in a :FILE command; they will cause deletion or
duplication of the le.
logical by value (optional)
The foptions parameter allows you to specify dierent le characteristics, by
setting corresponding bit groupings in a 16-bit word. If the le is new, bit 4
must be set to 1 to indicate that this is a KSAM le. Refer to Table 4-6 for
the foption bit settings.
Default: All bits are set to zero.
logical by value (optional)
The aoptions parameter permits you to specify the various access options
established by bit groupings in a 16-bit word. These access options are
dened in Table 4-7.
Default: All bits are set to zero.
integer by value (optional)
USING KSAM FILES IN SPL PROGRAMS
An integer indicating the size of the logical records in the data le. If a
positive number, this represents words; bytes are represented by a negative
number. If the le is a newly-created le, this value is recorded permanently
in the le label. If the records in the le are of variable length, this value
indicates the maximum logical record length allowed.
Binary les are word oriented. A record size specifying an odd byte count for
a binary le is rounded up by FOPEN to the next highest even number.
ASCII les may be created with logical records which are an odd number
of bytes in length. Within each block, however, records begin on word
boundaries.
For either ASCII or binary les with xed-length records, the record size is
rounded up to the nearest word boundary. For example, a recsize specied as
0106 for an ASCII le is 106 characters (53 words) in length. A recsize of
0113 for a binary le is 114 characters (57 words) in length. The rounded
sizes should be used in computations for blockfactor or block size.
device
ksamparam
userlabels
Default: The default value is the congured physical record width of the
associated device.
byte array (optional)
Contains a string of ASCII characters terminated by any nonalphanumeric
character (except a slash or period) that designates the device on which the
le is to reside. It may be a device class name of up to eight alphanumeric
characters beginning with a letter; or a logical device number consisting of
a three-byte numeric string; or a remote device identier consisting of the
device class name or logical device number followed by a pound sign (#) and
a remote device class name or logical device number.
Device class names and logical device numbers are assigned to devices during
system conguration.
For KSAM les, the device must be a random access device such as the disc.
If the le is a newly-created disc le specied as a device class name, then all
extents to the le must be members of the same class. Similarly, if the device
is identied by logical device number, then all extents must have the same
logical device number.
Default: Disc.
byte array (optional)
Contains information describing the key le of a KSAM le. It includes the
key le name, size and device plus an entry for the primary key and up to 15
alternate keys. If the le is new (is being created by FOPEN) then this array
must be included. If the le is an old le, it can be omitted. Note that if the
parameter is included and the le is not a KSAM le, an error can result.
Refer to Table 4-8 for a full description of ksamparam .
Default: key le description is omitted.
integer by ualue (optional)
Species the number of user-label records to be written for the data le. If
there are no user labels, this parameter can be omitted.
USING KSAM FILES IN SPL PROGRAMS
4-45
blockfactor
numbuers
Default: The default number of user-label records is zero.
integer by value (optional)
Establishes the size of each block in the data le by specifying the number of
logical records per block. It also establishes the size of the data le buer
in KSAM's extra data segment . For xed-length records, blockfactor is the
actual number of records in a block; for variablelength records, blockfactor is
a multiplier used to compute block size from record size; ( (maximum recsize
+1) * blockfactor ) +1 = blocksize. The value of blockfactor should be an
integer that results in a block size less than 4K words. The blockfactor is
from 1 through 255. If you specify a negative value or zero, the default value
is used. Values greater than 255 are defaulted to the specied blockfactor
modulo 256.
Default: 1
integer by value (optional)
An integer between 1 and 20 that species the number of key block buers in
the extra data segment used by KSAM les for buering data and key blocks.
The number of buers is specied in bits 4-10; the rest of the word must be
set to zeros:
This number should only be specied if the default number assigned by
KSAM aects performance. Refer to appendix B, under KSAM Extra Data
Segments for a discussion of how the key block buers are used.
lesize
numextents
4-46
Default: Between 1 and 20 bUers depending on access type, number of keys,
and number of levels per hey. (Refer to appendix B.)
double by value (optional)
A double-word integer specifying the maximum data le size as the number
of logical records in the le. A zero or negative value results in the default
lesize setting. The maximum le capacity is over two million (221) sectors; a
sector contains 128 words.
Default: 1024 logical records
integer by value (optional)
An integer specifying the number of extents (integral number of
contiguously-located disc sectors) that can be dynamically allocated to the le
as logical records are written to it. The number of extents applies equally
to the data and key les on the assumption that there is a proportional
expansion in each. The size of each extent is determined by the lesize
parameter value divided by the numextents parameter value. If specied,
USING KSAM FILES IN SPL PROGRAMS
numextents must be an integer from 1 to 32. A zero or negative value results
in the default setting.
Default: 8 extents .
Note
initialloc
lecode
Extents are allocated on any disc in the device class specied in the device
parameter when the le was created. If it is necessary to insure that all
extents of a le are on a particular disc, a single disc device class or a logical
device number must be used in the device parameter.
integer by value (optional)
An integer specifying the number of extents to be allocated to the data le
when it is opened. (For a key le, this parameter is forced equal to the value
of numextents .) This must be an integer from 1 to 32. If an attempt to
allocate the requested disc space fails, the FOPEN intrinsic returns an error
condition code to the calling program.
Default: 1 extent.
integer by value (optional)
An integer recorded in the le label and made available for general use to
anyone accessing the le through the FGETINFO intrinsic. This parameter is
used for new data les only. The lecode applies to data les only; the key le
code is always 1080 and need not be specied. For this parameter, any user
can specify a non-negative integer.
Default: 0
CONDITION CODES
CCE
CCG
CCL
Request granted. The le is open.
Not returned by this intrinsic.
Request denied. This may be because another process already has exclusive or
semi-exclusive access for this le, or an initial allocation of disc space cannot
be made due to lack of disc space. The le number value returned by FOPEN
if the le is not opened successfully is zero. The FCHECK intrinsic should be
called for more details.
USING FOPEN
FOPTIONS PARAMETER
Table 4-6. FOPEN
foptions
Parameter Format
USING KSAM FILES IN SPL PROGRAMS
4-47
4-48
USING KSAM FILES IN SPL PROGRAMS
AOPTIONS PARAMETER
Table 4-7. FOPEN
Table 4-7. FOPEN
aoptions
aoptions
Parameter Format
Parameter Format (continued)
USING KSAM FILES IN SPL PROGRAMS
4-49
KEY FILE DEFINITION
The ksamparam array denes the key le for a new KSAM le. If the le has already been
created, this parameter can be set to all zeros or omitted. Otherwise, it must be assigned
values to dene the key le as shown in Table 4-8.
When a new KSAM le is created, the MPE end-of-le for the key le is set to the le limit.
The le limit is based on the key le size (see words 4-5 of ksamparam ). The location of the
key le end-of-le can be determined by executing the VERIFY command of KSAMUTIL and
looking at the heading KEY FILE EOF. A call to FGETKEYINFO returns the key le size as
the number of sectors used by the le.
4-50
USING KSAM FILES IN SPL PROGRAMS
Table 4-8. FOPEN
ksamparam
Parameter Format
This array denes the key le portion of a new KSAM le being created by the FOPEN call.
The values are:
Key File Name 8-byte le name that must be present if this is a new le. Only the name is
specied; the account, group, and security are taken from the data le formal
le designator.
USING KSAM FILES IN SPL PROGRAMS
4-51
Key File Size
Double-word specifying the maximum number of primary keys expected from
which the key le size is derived. If zero, the data le size is used.
(Note that a call to FGETKEYINFO returns the key le size as the number
of sectors in the le.)
Key Device
8-byte array that species the device on which the key le resides. Specied
as a device class name of 1-8 alphanumeric characters beginning with a letter
and terminated by a non-alphanumeric character such as a blank; or it is
specied as a logical device number (3-byte numeric string) identifying a
particular device. If the data le is assigned to a remote device the key le is
automatically allocated to the same machine. Default is DISC.
The number of the language to use in determining the key sequence. Bit 11 in
Language
Identication- the agword must be set to 1 to use any language other than NATIVE-3000.If
bit 11 is set to 0, NATIVE-3000 (the default) is used and the language
Number
identication number in word 10 is ignored. If the language is not congured,
FOPEN returns condition code CCL. For detailed information on using Native
Language Support (NLS) with KSAM les, refer to Appendix F.
Flagword
1-word that species le characteristics as shown below:
------------------------------------------| 0 1 2 3 4 5 6 7 8 9 10 11 12|13|14|15 |
------------------------------------------|
reserved
|DL|NL| |SW|RN|JT |
-------------------------------------------
JT
bit 15:1 = 1 if le is job temporary le
RN
= 0 if le is a permanent le (default )
14:1 = 1 if record numbering starts with 1.
SW
0 if record numbering starts with 0. (default )
13:1 = 1 if only sequential writing by primary key value is
allowed.
= 0 if random writing by primary key value is allowed.
(default )
NL
DL
Number of
Keys
Key
Denitions
4-52
0:9 = 0 all reserved bits must be set to 0.
bit 11:1 = 1 if a congured language is specied.
= 0 if the default language (NATIVE-3000) is to be used.
bit 10:1 = 1 Duplicate le locks from dierent open paths of
the same PIN are not allowed.
= 0 Duplicate le locks from the same PIN are always
allowed.
1 byte providing the total number of keys for the le, specied as a numeric
digit between 1 and 16, (left byte of word must be zero).
Each key in the le requires a 4-word denition. The rst denition is always
of the primary key. Subsequent denitions describe any alternate keys. Up to
USING KSAM FILES IN SPL PROGRAMS
15 alternate keys are allowed in any one key le. The key denitions each
contain the following information:
bits
Key Type
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
-----------------------------------------------------| Key Type |
Key Length
|
|----------------------------------------------------|
| Key Location
|
|----------------------------------------------------|
| D | Minimum (Maximum) Number of Keys per Block
|
|----------------------------------------------------|
| (reserved)
| R | (reserved)
|
------------------------------------------------------
The information for each key has the form shown above starting in word 17 of
ksamparam . It is dened as follows:
4 bits specifying the type of the key by the following code:
bits 0:4 =
0001 (1) = Byte key (1 to 255 bytes)
0010 (2) = Integer key (2 bytes)
0011 (3) = Double Integer key (4 bytes)
0100 (4) = Real key (4 bytes)
0101 (5) = Long key (8 bytes)
0110 (6) = Numeric Display key (1 to 28 bytes)
0111 (7) = Packed Decimal key, odd number of digits (1 to 14
bytes)
1000 (8) = Packed Decimal key, even number of digits (2 to
14 bytes)
Key Length
Key Location
D(Duplicate
Flag)
Minimum
(Maximum)Number of
Keys perBlock
Refer to Table 2-2 in section II for a full description of key type.
12 bits specifying length of the key in bytes. Length is a function of key type
(see key type) but must never exceed 255 bytes.
1 word specifying the location of the rst byte of the key in the record. Bytes
in a record are numbered starting with 1. (Note that it is good practice to
leave the rst two bytes of a record empty of keys since these bytes are used
by FREMOVE for the record delete code.)
1 bit that determines if duplicate values are allowed for this key: = 0 if
duplicate key values are not allowed (default ) = 1 if duplicate key values are
allowed.
15 bits that specify the minimum number of keys allowed per key block. The
value must be an even -numbered integer greater than or equal to 4. The
resulting key block size must be less than 2048 words. If the resulting key
block size is greater than 2048 words, the system will print the error message
\INVALID KEY BLOCKING FACTOR VALUE (FSERR 190)&quot; and will
not open the le. In order to make optimum use of disc space, KSAM may
increase the value specied here. If KSAM increases the number of keys
per block, this new value is the maximum size of the key block. (Refer to
USING KSAM FILES IN SPL PROGRAMS
4-53
R(Random
Insert Flag)
appendix B for particulars on the calculation of block size and the adjustment
of the blocking factor). The default generates a block size of 1K (1024) words .
1 bit (8:1) that determines whether duplicate key is to be inserted randomly
in duplicate key chain or is to be added to the end of the chain; the duplicate
ag (D bit) must be set to 1 in order to use this ag.
= 0 if duplicate key values are to be inserted at the end of the chain
(default )
= 1 if duplicate key values are to be inserted randomly. If inserted
randomly, the chronological order of duplicate keys is no longer maintained,
but the addition of keys is faster.
OPENING A NEW FILE
When FOPEN is used to open a new KSAM le, you must provide all the information needed
to create the two les that make up a KSAM le: the key le and the data le. To inform the
system that this is a KSAM le, the KSAM bit must be set in the foptions parameter; and
the ksamparam parameter must be included to dene the key le.
Figure 4-5 is a short SPL program that builds a KSAM le. The le has two keys; the
primary key starting in column 1 is 20 characters long, and the alternate key starting in
column 21 is 8 characters long. The primary key will contain a name, the alternate a phone
number.
The rst step is to declare all arrays and variables needed by the program followed by the
intrinsic declaration for FOPEN. The shaded declarations in Figure 4-5 show these required to
open the le; others are used in parts of the program not shown in this gure.
The next step is to move the necessary values to ksamparam in order to dene the key le.
The last step is to call the FOPEN intrinsic, passing any previously dened variables or arrays
by reference and passing all others by value.
DECLARATIONS FOR FOPEN
The array ksamparam is dened three dierent ways: as a numeric array containing 25 words
(KSAMPARAMA), as a byte array equivalenced to the numeric array (KSAMPARAM), and
as a double array also equivalenced to the numeric array (KSAMPARAMD). These three
denitions allow the array to be addressed by word, by byte, or by double word as required.
The variable to which the le number is returned is declared to be an integer.
The two arrays that will contain the formal designator and device parameter values are
declared and assigned these values. In this case, the formal designator is assigned the value
JEXAMFIL. This name identies both the KSAM le in its entirety and the data le if
referenced separately. The device class name assigned to the device parameter is DISC.
Finally, the intrinsic itself is declared in an INTRINSIC statement.
DEFINING KSAMPARAM
The ksamparam parameter is assigned a variety of values that, for the sake of clarity, are
assigned in separate statements. The values assigned to ksamparam dene the key le. The
statements that move values to ksamparam (refer to Figure 4-5) tell the system everything it
needs to know in order to build the key le.
4-54
USING KSAM FILES IN SPL PROGRAMS
The rst item moved to ksamparam is the key le name, up to 8 characters enclosed in quotes.
In this case, the key le name is JKEYFILE.
Next, the size of the key le is dened in terms of the maximum number of primary keys
expected. The size is specied as a double word integer and is assigned to the third double
word in the array, specied by an index of 2 counting from double word 0. The maximum
number of primary keys should be the same as the maximum number of records specied
in the lesize parameter of FOPEN. KSAM assigns a key le size based on this value. If
there are alternate keys, the key le size is made proportionately larger. If the key le size is
specied as zero, KSAM uses the value of the FOPEN lesize parameter as the key le size.
The device class name is assigned in the 8 bytes starting in byte 12 that are allocated to
device description. In this case, the device class name is DISC, the same as the device class
name specied in the device parameter of FOPEN for the data le.
USING KSAM FILES IN SPL PROGRAMS
4-55
$CONTROL MAIN-JEXAMPL1
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE l
*&gt;&gt;
&lt;&lt;*
BUILD A KSAM FILE
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
ARRAY KSAMPARAMA(0:25);
BYTE ARRAY KSAMPARAM (*)=KSAMPARAMA;
DOUBLE ARRAY KSAMPARAMD(*)=KSAMPARAMA;
INTEGER FILNUM;
INTEGER ERRORCODE;
INTEGER LENGTH;
BYTE ARRAY FILENAME(0:9):=&quot;JEXAMFIL &quot;;
BYTE ARRAY DEVICE(0:9):=&quot;DISC &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
INTRINSIC FOPEN,FCLOSE,PWRITE,READ,PRINT,TERMINATE;
INTRINSIC FCHECK,FERRMSG;
&lt;&lt;*******************************&gt;&gt;
&lt;&lt;* SETUP KSAMPARAM FOR FOPEN *&gt;&gt;
&lt;&lt;*******************************&gt;&gt;
MOVE KSAMPARAM;=&quot;JKEYFILE&quot;;
&lt;&lt;THE KEY FILE NAME&gt;&gt;
KSAMPARAMD(2):=100D;
&lt;&lt;THE MAX. # OF PRIMARY KEYS&gt;&gt;
MOVE KSAMPARAM(12):=&quot;DISC&quot;;
&lt;&lt;THE KEY FILE DEVICE TYPE&gt;&gt;
KSAMPARAMA(15):=&amp;%(2)000000000000010; &lt;&lt;THE FLAG WORD&gt;&gt;
KSAMPARAMA(16):=2;
&lt;&lt;PRIMARY KEY &amp; ONE ALTERNATE&gt;&gt;
MOVE KSAMPARAMA(17):=([4/1,12/20],
&lt;&lt;TYPE=ASCII; LENGTH=20 BYTES&gt;&gt;
1,
&lt;&lt;KEY LOCATION START FROM COL 1&gt;&gt;
[1/0,15/4], &lt;&lt;DUP NOT ALLOW; 4 KEY/BLOCK&gt;&gt;
0);
&lt;&lt;RESERVED&gt;&gt;
MOVE KSAMPARAMA(21):=([4/1,12/8], &lt;&lt;TYPE=ASCII; LENGTH=20 BYTES&gt;&gt;
21,
&lt;&lt;KEY LOCATION START FROM COL 21&gt;&gt;
[1/0,15/4], &lt;&lt;DUP NOT ALLOW; 4 KEY/BLOCK&gt;&gt;
0);
&lt;&lt;RESERVED&gt;&gt;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;************************&gt;&gt;
FILNJM:=FOPEN(FILENAME,
&lt;&lt;THE DATA FILE NAME&gt;&gt;
&amp;%(2)0000100000000100, &lt;&lt;KSAM,ASCII,NEW FILE&gt;&gt;
&amp;%(2)0000000001000001, &lt;&lt;KSAM ACCESS,EXCLUSIVE,WRITE&gt;&gt;
072,
&lt;&lt;RECORD 72 BYTES LONG&gt;&gt;
DEVICE,
&lt;&lt;DEVICE=DISC&gt;&gt;
KSAMPARAM,
&lt;&lt;THIS DESCRIBES THE KEYS&gt;&gt;
Figure 4-5. FOPEN Example|; Building a KSAM file
4-56
USING KSAM FILES IN SPL PROGRAMS
,
NO USERLABELS
10,
BLOCK 10 RECORDS
,
NUMBUFFERS NOT USED
100D);
THIS FILE CAN HOLD 100 RECORD
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH); &lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
Figure 4-5. FOPEN Example|; Building a KSAM file (continued)
Word 15, the ag word, is set next, It uses bits 13,14, and 15 to dene three conditions of the
key le. In this example, bit 14 is the only bit set. This means that record numbers in the le
start with 1 rather than 0 (bit 14=1), that the le is a permanent le saved in the system
directory (bit 15=0), and that records may be written to the le in random order rather than
being restricted to ascending sequence by primary key (bit 13=0).In Figure 4-5 the ag word
is specied as a binary value for clarity; it could have been specied as octal 2 (2 or %2) for
brevity.
The right byte of the 16th word (byte 33) is set to 2 to specify that two keys are to be used:
the primary key and one alternate.
This completes the general description of the le. Its name, size, device type, special
conditions, and number of keys are now specied. The remainder of ksamparam denes each
key in 4-word entries. The rst entry always describes the primary key. Subsequent entries
dene up to 15 alternate keys. In this case, one primary and one alternate are dened.
Starting in word 17, the primary key is dened as type ASCII, 20 bytes long, its location
starting in the rst character of each record, and duplicate values are not allowed. It is
blocked with four keys per block.
Starting in word 21, the altemate key is dened as type ASCII, 8 bytes long, located starting
in character 21 of the record, duplicate values not allowed, and blocked four keys per block.
Refer to Table 4-8 for an illustration of the bit patterns used to dene the ksamparam entries.
CALLING FOPEN
When all the variables and arrays that pass values by reference have been dened, the
intrinsic FOPEN can be called. In Figure 4-5, each parameter is shown on a separate line and
documented for clarity, but the call could also be specied as:
USING KSAM FILES IN SPL PROGRAMS
4-57
FILNUM:=FOPEN(FILNAME,%4004,%101,--72,DEVICE,KSAMPARAM,,10,0,100D);
This call is identical to the call in Figure 4-5 except that octal values are used for foption and
aoption.
foptions
The value of foptions is set to octal 4004, for which the bit pattern is:
This specication denes the following le options:
New KSAM le (bit 4=1)
Allow: FILE (bit 5=0)
Fixed-Length Records (bits 8,9=00)
ASCII code (bit 13=1)
New le (bits 14,15=00)
aoptions
The value of aoptions is set to octal 101, for which the bit pattern is:
This specication denes the following access options:
KSAM access expected (bit 3=0)
Exclusive access (bits 8,9=01)
Dynamic locking not allowed (bit 10=0)
Access type is write only (bits 12-15=0001)
OPENING AN EXISTING FILE
Once the le has been created, opening it again after it has been closed is a simple process.
The record size, device, blocking, buersize, and le size are all dened for the data le.
Therefore, these parameters need not be repeated. The key le has already been dened
so that ksamparam need not be specied. This leaves the rst three parameters to specify.
Of these, only the formal-designator and the domain and KSAM options of the foptions
parameter are always required. The formal-designator provides the le name in order to
identify the le. The domain option species where to locate the le; if domain is set to zeros,
the system expects a new le. Set the foptions KSAM option (bit 4:1) to 0 to indicate that
4-58
USING KSAM FILES IN SPL PROGRAMS
the le is not new If the le is to be read only, the access mode parameter, aoptions , can be
omitted. For any other type of access, aoptions should be specied.
OPENING FILE FOR READ ACCESS
The example in Figure 4-6 illustrates opening a le for readonly access.
USING KSAM FILES IN SPL PROGRAMS
4-59
%CONTROL MAIN=JEXAMPL2
&lt;&lt;*********************************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*********************************************************************&gt;&gt;
INTEGER FILNUM;
INTEGER ERRORCODE,LENGTH;
BYTE ARRAY FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
BYTE ARRAY KEYVALUE(0:7):=&quot;000-0000&quot;;
INTEGER KEYLENGTH:=8;
INTEGER KEYLOCATION:=21;
INTEGER RELOP:=2;
INTRINSIC FOPEN,FCLOSE,FREAD,FFINDBYKEY,READ,PRINT,
FCHECK,FERRMSG,PRINT'FILE'INFO,TERMINATE;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;************************&gt;&gt;
FFILNUM:=OPEN(FILNAME,3);
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH); &lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
OPEN THE KSAM FILE
Figure 4-6. FOPEN Example|; Opening an Existing File
The le name is specied in the FILNAME array declaration as JEXAMFIL. This is the le
that was created and opened for write-only access in Figure 4-5. It is opened for read-only
access with the call:
FILNUM:=FOPEN(FILNAME,3);
The value of foptions is set to the value 3, for which the bit pattern is:
This specication denes the following le options:
Not a new KSAM le (bit 4=0)
Old user le (bits 14-15=11)
Because this is an existing (old) user le, other foptions settings dened when the le was
created need not be respecied. For example, at creation the le was dened as containing
ASCII code (bit 13=1). In subsequent FOPEN calls this bit can be 0 without changing the
code to binary.
4-60
USING KSAM FILES IN SPL PROGRAMS
When an old user le is opened, the job le domain is searched rst and then the system le
domain is searched for the le specied in the formal designator.
The access parameter, aoptions , is not specied, but by default it species the following access
mode:
KSAM access expected
Share access (default for read-only)
Read-only access
OPENING FILE FOR WRITE ACCESS
To open an existing le for write access, you use the same foptions values as you do to open
the le for read-only access. The dierent access mode is specied in the aoptions parameter.
For example, assuming FILNUM and FILNAME have been declared:
FILNUM:=FOPEN(FILNAME,3,1)
The foptions specication is the same as described above. The aoptions specication is:
This bit pattem denes the following access options:
KSAM access expected (bit 3=0)
Exclusive access (default for all access modes except read-only) (bits 8-9=00)
Disallow dynamic locking (bit 10=0)
Write only access (bits 12-15=0001)
This opens the le for write-only access in which all previous data is deleted. It is the access
mode to use when writing to a le for the rst time. If you want to write to the end of an
existing le then bits 12-15 should equal 0010 and aoptions could be specied as 2 if other
aoptions values are defaulted. To open the le for both reading and writing, bits 12-15 should
be set to 0100, or the value 4. For update, these bits are set to 0101, or the value 5.
OPENING KSAM FILE AS MPE FILE
You may want to open either the key le or the data le as a standard MPE le. To do this,
name the le you want to open in the formaldesignator parameter, set foptions bit 4:1 to 1,
and then set aoptions bit 3:1 to 1. These settings indicate that the le is a KSAM le, but is
to be treated as an MPE le. The remaining parameter settings depend on what you want to
do with the open le. For example, if you want to read the key le, JKEYFILE, as an MPE
le, you call FOPEN as follows:
INTEGER
FILNUM;
BYTE
ARRAY
FILNAME(0:9):=&quot;JKEYFILE &quot;;
.
.
.
INTRINSIC
FOPEN,...;
.
.
.
USING KSAM FILES IN SPL PROGRAMS
4-61
FILNUM:=FOPEN(FILNAME,%4003,%10000);
The value of foptions denes the following le options:
Specied as KSAM le (bit 4=1)
Old user le (bits 14-15=11)
The value of aoptions indicates the following:
Non-KSAM access expected (bit 3=1)
Share access (default for read only bits 8-9=00)
Read-only access (default bits 12-15=0000)
Normally, the only time you need to set bit 4 of foptions to 1 is when you are originally
creating a KSAM le. However, when you are opening an existing KSAM le for non-KSAM
access, you must set this bit to 1 so that the system can distinguish the KSAM data or key
le from an MPE le.
OPENING FILE FOR SHARED ACCESS
When a le is opened for shared access (aoptions bits 8,9=11), and you plan to modify the le
in any way, you must enable dynamic locking (aoptions bit 10=1). This is necessary since you
cannot call FWRITE, FUPDATE, or FREMOVE to modify a shared le without rst calling
FLOCK to lock the le.
Even if you are not planning to modify the le, but only plan to read it sequentially, you
should allow dynamic locking when you open the le. This is because FREAD (as well
as FUPDATE and FREMOVE) is a pointer-dependent procedure. Any time you call a
pointer-dependent procedure (refer to Table 4-2), you must precede it with a call to a
pointer-independent procedure that positions the pointer. It is important to call FLOCK to
lock the le before setting the pointer with the pointer-independent procedure and leave it
locked until you have completed the sequential read or update. This insures that no other user
changes the position of the pointer between the call that positions the pointer and the call
that depends on the pointer.
4-62
USING KSAM FILES IN SPL PROGRAMS
FPOINT
INTRINSIC NUMBER 6
Sets the chronological (and logical) record pointer for a KSAM le.
IV
DV
FPOINT(lenum,recnum);
The FPOINT intrinsic sets the chronological record pointer for a KSAM disc le. The le
may contain either xed-length or variable-length records. When the next FREADC request is
issued for this le, the record to which FPOINT positioned the pointer is read. Note that this
intrinsic positions the logical record pointer as well as the chronological pointer.
PARAMETERS
lenum
recnum
integer by value (required)
A word identier supplying the le number of the le on which the pointer is
to be set.
double by value (required)
A positive double integer representing the record number of a xedlength
le or the word pointer to a variable-length le. Word numbering always
starts with word 0, whereas record numbering starts with 0 or 1 depending
on how the le was created. In either case, the number is in terms of the
chronological (consecutive) order in which the data le records were written.
It has no relation to the logical record pointer that is based on key values.
CONDITION CODES
CCE
CCG
CCL
Request granted.
Request denied. The chronological record pointer position is unchanged.
Positioning was requested at a point beyond the physical end-of-le.
Request denied. The chronological record pointer position is unchanged
because of one of the following:
Invalid lenum parameter.
recnum parameter specied a record marked for deletion.
A key value for specied record not found in key le.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING KSAM FILES IN SPL PROGRAMS
4-63
USING FPOINT
The FPOINT intrinsic is generally used prior to an FREADC intrinsic in order to read a
record without reference to the key le. FPOINT sets the chronological record pointer to the
position in the le specied by recnum . A subsequent FREADC reads the record (or portion
of a record) to which the pointer is positioned. It then sets the pointer to the next record that
was written to the le in chronological order,
For example, in order to read the 39th record written to the le identied by FILENUM:
FPOINT(FILNUM,39D); &lt;&lt;set pointer&gt;&gt;
FREADC(FILNUM,BUFFER,COUNT); &lt;&lt;read record&gt;&gt;
Following execution of FREADC, the contents of the 39th record are transferred to the array
BUFFER and the chronological pointer remains positioned at record 39. A ag is set so that
the next call to FREADC moves the pointer forward to the beginning of record 40, the next
record in chronological order.
Note that the combination of FPOINT followed by an FREADC intrinsic is identical in
eect to the FREADDIR intrinsic that positions to a chronological record number and then
reads that record. The FGETINFO intrinsic can be used to recover the chronological record
number of the record most recently accessed. (Refer to FGETINFO and FREADDIR for more
information on accessing records by chronological record number.)
Since the FPOINT intrinsic positions the logical pointer as well as the chronological pointer, it
can be used prior to an FUPDATE or FREAD intrinsic to identify the record to be updated
or read. FPOINT sets the logical record pointer to a key in the key le that points to the
record it located by record number. The key is by default the primary key for that record,
though an alternate key is used if such a key was selected by a prior call to FFINDBYKEY or
FREADBYKEY.
SHARED ACCESS
When you use FPOINT to position the chronological pointer in a shared access environment,
you must lock the le with a call to FLOCK before calling FPOINT. You should leave the
le locked until you have completed any calls that read or update the le in chronological
sequence, and then call FUNLOCK to unlock the le for the other users. This insures that
the pointer is not moved by other users between the pointer-independent procedure FPOINT
and any subsequent pointer-dependent procedure. (Refer to Table 4-2 for a list of the
pointer-independent and pointer-dependent procedures.)
4-64
USING KSAM FILES IN SPL PROGRAMS
FREAD
INTRINSIC NUMBER 2
Reads a logical record in key sequence from a KSAM le to the user's stack.
I
IV
LA
lgth:=FREAD(lenum,target,tcount);
IV
FREAD reads a logical record in sequential order by key value. The primary key determines
key sequence unless a prior call to FFINDN (or FFINDBYKEY or FREADBYKEY) has
specied an alternate key. If the le is opened without KSAM access (FOPEN aoptions bit
3=1), then FREAD reads the data le as if it were not a KSAM le.
The record read by FREAD depends on the current position of the logical record pointer.
FUNCTIONAL RETURN
The FREAD intrinsic returns a positive integer value to lgth showing the length of the
information transferred. If the tcount parameter in the FREAD call is positive, the positive
value returned represents a word count; if the tcount parameter is negative, the positive value
returned represents a byte count.
PARAMETERS
lenum
target
tcount
integer by value (required)
A word identier supplying the le number of the le to be read.
logical array (required)
An array to which the record is to be transferred. This array should be large
enough to hold all of the information to be transferred.
integer by value (required)
An integer specifying the number of words or bytes to be transferred. If this
value is positive, it signies the length in words ; if it is negative, it signies
the length in bytes ; if it is zero, no transfer occurs.
If tcount is less than the size of the record, only the rst tcount words or
bytes are read from the record. If tcount is larger than the size of the physical
record, transfer is limited to the length of the physical record.
CONDITION CODES
CCE
CCG
CCL
The information was read.
The logical end-of-data was encountered during reading.
The information was not read because an error occurred.
USING KSAM FILES IN SPL PROGRAMS
4-65
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FREAD
The FREAD intrinsic reads the record at which the logical record pointer is currently
positioned. When a le is opened, this pointer is positioned to the beginning of the rst
record in primary key sequence. That is, it is positioned to the record containing the lowest
value in those bytes containing the primary key.
Following each FREAD , the record pointer remains positioned at the record just read. Any
subsequent FREAD call positions the pointer to the next sequential record in ascending key
sequence. Also, if an FREAD call is followed by an FUPDATE and another FREAD, the
pointer is advanced before the second FREAD.
A key other than the primary key can be selected as the basis of the sequential read by
executing FFINDN, FFINDBYKEY, or FREADBYKEY before executing the FREAD
intrinsic.
When the logical end-of-data is encountered during reading, the CCG condition code is
returned to your process. The end-of-data occurs when the last logical record of the le
is passed . Note that the last logical record of a KSAM le is the record containing the
maximum key value in the key on which the key sequence is based.
SHARED ACCESS
In order to be sure that you are reading the record you want, you should call either FLOCK
or FCONTROL with control code 7 before calling FREAD. FLOCK prevents other users from
changing or deleting the record until the le is unlocked with FUNLOCK. FCONTROL with
control code 7 clears the data and key block buers so that the record must be read directly
from the le, and also transfers the latest control information from the le to the extra data
segment. Because the logical pointer is part of this control information, you can be sure that
is is set correctly by calling FCONTROL with code 7.
FCONTROL uses less overhead than FLOCK, but it cannot prevent other users from
modifying the record you want to read while you are calling FCONTROL. FLOCK, on the
other hand, fully protects the information to be read from changes by other users but requires
more time.
Because FREAD is a pointer-dependent procedure, you must call one of the procedures that
position the pointer before calling FREAD. When you are reading the le in sequential
key order, it is important to lock the le before calling the procedure that positions the
pointer, and to leave it locked while you are reading the le. This insures that the pointer
is not moved by another user between the call that positions the pointer and FREAD or
between sequential FREAD calls. (Refer to Table 4-2 for a list of the pointer-independent and
pointer-dependent procedures.)
For example, the following sequence of calls guarantees that you will read the le in sequential
order starting with a specied key:
FLOCK
FFINDBYKEY &lt;&lt;sets logical pointer&gt;&gt;
FREAD loop &lt;&lt;read records in key sequence&gt;&gt;
FUNLOCK
4-66
USING KSAM FILES IN SPL PROGRAMS
Note that FREAD advances the record pointer only if it is followed by another FREAD (or
an FUPDATE followed by another FREAD). A single call to FREAD leaves the pointer at
the record just read; a subsequent call to FREAD causes the pointer to be positioned to
the next record in key sequence. This permits sequential reading of the le without calling
a pointer-independent procedure before each FREAD. Also, in order to allow sequential
updates, the pointer is advanced for each FREAD in an FUPDATE/FREAD sequence with no
other intervening calls (see FUPDATE discussion).
In the example in Figure 4-7, FREAD is used rst to read the KSAM le in sequence by
primary key. When the end of data is reached, the program uses FFINDBYKEY to specify
an alternate key and FREAD then reads the le in sequence by that altemate key. When the
end of data is reached again, the le is closed. (Note that this program is opened for exclusive
access so that locking is not necessary).
USING KSAM FILES IN SPL PROGRAMS
4-67
$CONTROL MAIN=JEXAMPL2
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 2
*&gt;&gt;
&lt;&lt;*
READ A KSAM FILE SEQUENTIALLY
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
INTEGER
FILNUM;
INTEGER ERRORCODE,LENGTH;
BYTE ARRAY FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY
MESSAGE(0:35);
ARRAY
INPUT(0:39);
ARRAY
OUTPUT(*)=INPUT;
BYTE ARRAY
KEYVALUE(0:7:=&quot;000-0000&quot;;
INTEGER
KEYLENGTH&quot;=8;
INTEGER
KEYLOCATION:21;
INTEGER
RELOP:2;
INTRINSIC
FOPEN,FCLOSE, FREAD,FFINDBYKEY ,READ,PRINT,
FCHECK,FERRMSG,PRINT'FILE'INFO,TERMINATE;
&lt;&lt;*************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE
*&gt;&gt;
&lt;&lt;*************************&gt;&gt;
FILENUM:=FOPEN(FILNAME,3,200); &lt;&lt;OPEN KSAM FILE
FOR EXCLUSIVE READ-ONLY ACCESS&gt;&gt;
IF FILNUM=0
THEN BEGIN
&lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCODE);
&lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH); &lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0);
&lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
MOVE MESSAGE:=&quot;LIST IN LAST NAME SEQUENCE&quot;;
PRINT(MESSAGE,026,0);
&lt;&lt;**********************************&gt;&gt;
&lt;&lt;* READ KSAM IN NAME SEQUENCE
*&gt;&gt;
&lt;&lt;**********************************&gt;&gt;
L1:
FREAD(FILNUM,INPUT,072);
IF &gt;
THEN GO TO L2;
Figure 4-7. FREAD Example
4-68
USING KSAM FILES IN SPL PROGRAMS
READ SEQUENTIALLY BY PRIMARY KEY
GO TO ALTERNATE KEY ORDER
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGES,034,0);
TERMINATE;
END;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* WRITE THE DATA JUST READ FROM KSAM FILE
*&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
PRINT(OUTPUT,072,0);
&lt;&lt;***********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD
*&gt;&gt;
&lt;&lt;***********************************&gt;&gt;
GO TO L1;
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;* READ DATA FROM KSAM FILE IN TELEPHONE # SEQUENCE
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
L2:
FFINDNYKEY(FILNUM,KEYVALUE,KEYLOCATION,KEYLENGTH,RELOP);
MOVE MESSAGE:=&quot;LIST IN TELEPHONE NO. SEQUENCE&quot;;
PRINT(MESSAGE, 030,0);
L3:
FREAD(FILNUM,INPUT, 072);
READ SEQUENTIALLY BY ALTERNATE KEY
IF &gt;
THEN BEGIN &lt;&lt;END OF FILE&gt;&gt;
FCLOSE(FILNUM,0,0); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN &lt;&lt;CLOSE UNSUCCESSFUL&gt;&gt;
MOVE MESSAGE:&quot;CANNOT CLOSE THE KSAM FILE&quot;:
PRINT(MESSAGE,029,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENSTH;&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGE,034,0);
TERMINATE;
END;
Figure 4-7. FREAD Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-69
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* WRITE THE DATA JUST READ FROM KSAM FILE
*&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
PRINT(OUTPUT,072,0);
IF &lt;&gt;
THEN BEGIN &lt;&lt;ERROR OCCURRED WHILE PRINTING OUTPUT&gt;&gt;
MOVE MESSAGE,=&quot;ERROR OCCURRED WHILE PRINTING OUTPUT&quot;;
PRINT(MESSAGE,036,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH),&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;************************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD
*&gt;&gt;
&lt;&lt;************************************&gt;&gt;
GO TO L3;
END;
Output from Program Execution:
LIST IN LAST NAME SEQUENCE
CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053
ECKSTEIN LEO 287-5137 5303 STEVENS SANTA CLARA CA. 95050
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087
PASBY LINDA 295-1187 TOWN &amp; CNTRY VILLAGE SAN JOSE CA. 94102
ROBERT GERRY 259-5535 12345 TELEGRAPH BERKELEY CA. 90871
SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234
WESTER ELDER 287-4598 1256 KINGFISHER SUNNYVALE CA. 43098
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234
LIST IN TELEPHONE NO. SEQUENCE
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022
ROBERT GERRY 259-5535 12345 TELEGRAPH BERKELEY CA. 90871
WESTER ELDER 267-4598 1256 KINGFISHER SUNNYVALE CA. 43098
ECKSTEIN LEO 287-5137 5303 STEVENS SANTA CLARA CA. 95050
SEELY HENRY 293-4220 1144 LEBERTY EL CERRITO CA. 94053
PASBY LINDA 295-1187 TOWN &amp; CNTRY VILLAGE SAN JOSE CA. 94102
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234
CARDIN RICK 578-7018 11100 WOLFE CUPERTINO CA. 94O53
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234
END OF PROGRAM
Figure 4-7. FREAD Example (continued)
4-70
USING KSAM FILES IN SPL PROGRAMS
FREADBYKEY
INTRINSIC NUMBER 304
Reads a logical record randomly from a KSAM le to the user's data stack.
I
IV
LA
IV
BA
lgth:=FREADBYKEY(lenum,target,tcount,keyvalue,keylocation);
IV
FREADBYKEY reads a logical record selected by key value. The record to be read must have
the same value as keyvalue in the bytes that start at keylocation . Following execution, the
logical record pointer is still positioned to the record in the le located through the value of
the key at keylocation .
FUNCTIONAL RETURN
The FREADBYKEY intrinsic returns a positive integer value to lgth showing the length of
the information transferred. If the tcount parameter in the FREADBYKEY call is positive,
the positive value returned represents a word count; if the tcount parameter is negative, the
positive value returned represents a byte count.
PARAMETERS
lenum
target
tcount
keyvalue
keylocation
integer by value (required)
A word identier supplying the le number of the le to be read randomly.
logical array (required)
An array to which the record is to be transferred. It should be large enough
to hold all the information read.
integer by value (required)
An integer specifying the number of words or bytes to be transferred. If this
value is positive, it signies the length in words; if negative, it signies the
length in bytes; if zero, no transfer takes place.
If tcount is less than the size of the record, only the rst tcount words are
read from the record. If tcount is larger than the physical record size, transfer
is limited to the length of the physical record.
byte array (required)
A byte array containing the value that will determine which record is read.
The rst record found with this identical value in the key identied by
keylocation is the record read.
integer by value (required)
The relative byte location in the record of the key whose value determines
which record is read. The rst byte is numbered 1; if a value of zero is
specied, the primary key is used.
USING KSAM FILES IN SPL PROGRAMS
4-71
CONDITION CODES
CCE
CCG
CCL
The information specied was read.
The logical end-of-data or beginning-of-data was encountered during the read.
The information was not read because an error occured, such as an
input/output error, or the key could not be located.
USING FREADBYKEY
The intrinsic FREADBYKEY allows you to locate and read a single record according to a
specied key value, Like FFINDBYKEY, it denes the key that is to be used for determining
record sequence and, following execution, remains positioned at the same record. Unlike
FFINDBYKEY , FREADBYKEY cannot specify a key length dierent from the full length of
the key at creation , nor can it search for approximate key values .
In the example in Figure 4-8, the keylocation and keyvalue values are read from the standard
input device. As each is read, it is printed to test the read. The rst set of values read into
the word array INFOW is:
01 ROBERT GERRY
\/\------------/
|
|
%%keylocation%% %%keyvalue%%
The rst two ASCII characters contain the keylocation ; the characters starting in byte 2
contain the keyvalue to be found at the specied keylocation . Since keylocation is an integer
parameter, the rst two bytes of the byte array INFO (equivalenced to the word array
INFOW) must be converted to a binary value. This is done with the statement:
KEYLOCATION:=BINARY(INFO,2);
The value to be used for keyvalue is contained in the byte array INFO starting in the third
byte (byte 2 numbered from byte 0). In the declarations at the beginning of the program, the
byte array KEYVALUE is equivalenced to the portion of the byte array INFO that starts in
byte 2.
The intrinsic FREADBYKEY can be called with the following statement:
FREADBYKEY(FILNUM,INPUT,072,KEYVALUE,KEYLOCATION);
This locates and reads the rst record with the value ROBERT GERRY in the key located
starting in byte 1 of the record. The program prints this record and then returns to get the
next pair of values input for keyvalue and keylocation . When there are no more values in the
input le, the KSAM le is closed and the program terminates.
SHARED ACCESS
If you use FREADBYKEY to position the pointer for subsequent calls that read or
update the specied record, you should lock the le with a call to FLOCK before calling
FREADBYKEY. Then, after calling the read or update procedure, you should unlock the le
so other users can access it. Locking the le before calling FREADBYKEY insures that other
users do not change the position of the pointer between the call to FREADBYKEY and any
subsequent procedure that depends on the pointer position. (Refer to Table 4-2 for a list of
the pointerpendent procedures and also those that set the pointer.)
4-72
USING KSAM FILES IN SPL PROGRAMS
To illustrate, the following sequence of calls makes sure that the correct record is updated:
FLOCK
FREADBYKEY
FUPDATE
FUNLOCK
to lock the le
to position the pointer
to modify the record to which the pointer points
to unlock the le for other users
DUPLICATE KEYS
FREADBYKEY always positions to the rst key in a chain of duplicate keys. If you want
to read or update the remaining keys in a duplicate key chain, you should use FREAD. For
example, to update all the records with a particular key, use the following code sequence:
FREADBYKEY
FUPDATE
FREAD
FUPDATE
to locate 1st key in chain of duplicates
update that record
read next sequential record
test if this is correct key value
update record
return to read next record
USING KSAM FILES IN SPL PROGRAMS
4-73
$CONTROL MAIN=JEXAMPL3
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 3
*&gt;&gt;
&lt;&lt;*
READ A KSAM FILE RANDOMLY
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
INTEGER
FILNUM;
INTEGER
ERRORCODE,LENGTH;
BYTE ARRAY
FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY
MESSAGE(0:35);
ARRAY
INPUT(0:39);
ARRAY
OUTPUT(*)=INPUT;
BYTE ARRAY
INFO(0:35);
ARRAY
INFOW(*)=INFO
BYTE ARRAY
KEYVALUE(*)INFO(2);
INTEGER
KEYLOCATION;
INTRINNSIC FOPEN,FCLOSE,FREAD,FREADBYKEY,READ,PRINT,
FCHECK,FERRMSG,BINARY,TERMINATE;
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
OPEN THE KSAM FILE
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
FILNUM:=FOPEN(FILNAME,3); &lt;&lt;OPEN THE KSAM FILE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:&quot;CANNOT OPEN KSAM FILE&quot;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINTIMESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
READ IN KEYVALUE AND KEYLOCATION INFOMATION
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
L1:
READ(INFOW,036);
IF &gt;
THEN BEGIN
FCLOSE(FILNUM,0,0); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;
PRINT (MESSAGE, 026,0);
Figure 4-8. FREADBYKEY Example
4-74
USING KSAM FILES IN SPL PROGRAMS
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODES;MESSAGE,LENGTH);&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGE,034,0);
TERMINATE;
PRINT(INFOW,036,0); &lt;&lt;TEST READ&gt;&gt;
KEYLOCATION;=BINARY(INFO,2); &lt;&lt;CONVERT FROM ASCII TO BINARY&gt;&gt;
&lt;&lt;*****************************************************&gt;&gt;
&lt;&lt;* READ KSAM ACCORDING TO KEYVALUE AND KEYLOCATION *&gt;&gt;
&lt;&lt;*****************************************************&gt;&gt;
FREADBYKEY(FILNUM,INPUT,072,KEYVALUE,KEYLOCATION);
IF &lt;&gt;
THEN BEGIN &lt;&lt;ERROR OCCURRED IN FREADDBYKEY&gt;&gt;
MOVE MESSAGE:=&quot;ERROR OCCURRED IN FREADBYKEY&quot;;
PRINT(MESSAGE, 028,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE, 0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
GO TO L1;
END;
&lt;&lt;************************************************&gt;&gt;
&lt;&lt;*
WRITE THE DATA JUST READ FROM KSAM FILE *&gt;&gt;
&lt;&lt;************************************************&gt;&gt;
PRINT(OUTPUT,072,0);
&lt;&lt;***********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;***********************************&gt;&gt;
GO TO L1;
END;
Output from Program Execution:
01ROBERT GERRY
ROBERT GERRY 259-5535 12345 TELEGRAPH AVE. BERKELEY CA. 90871
21287-5137
ECKSTEIN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050
END OF PROGRAM
Figure 4-8. FREADBYKEY Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-75
FREADC
INTRINSIC NUMBER 305
Reads a logical record in chronological sequence from KSAM le to user's stack.
I
IV
LA
IV
lgth:=FREADC(lenum,target,tcount);
FREADC reads a logical record in chronological sequence. Chronological sequence means the
sequence in which the records were originally written to the data le.
When FREADC is executed, the key le is not accessed. This read is similar to the standard
FREAD for non-KSAM les except that FREADC skips any data records that are marked
for deletion. Following execution, the chronological pointer remains positioned at the same
record.
FUNCTIONAL RETURN
The FREADC intrinsic returns a positive integer value to lgth showing the length of the
information transferred. If the tcount parameter in the FREADC call is positive, the positive
value returned represents a word count; if the tcount parameter is negative, the positive value
returned is a byte count.
PARAMETERS
lenum
target
tcount
integer by value (required)
A word identier supplying the le number of the le to be read in
chronological sequence.
logical away (required)
An array to which the record is to be transfered. This array should be large
enough to hold all the information to be transferred.
integer by value (required)
An integer specifying the number of words or bytes to be transferred. If this
value is positive, it signies the length in words; if negative, it signies the
length in bytes; if zero, no transfer occurs.
If tcount is less than the size of the record, only the rst tcount words are
transfered from the record. If tcount is larger than the physical record size,
transfer is limited to the length of the physical record.
CONDITION CODES
CCE
CCG
CCL
4-76
The information was read.
The logical end-of-data was encountered during reading.
The information was not read because an error occurred.
USING KSAM FILES IN SPL PROGRAMS
USING FREADC
This intrinsic allows you to read the records in the data le in the order in which they are
physically stored in the le. The end-of-data is encountered following the last record in the
le. If any records have been marked for deletion (refer to the FREMOVE intrinsic), these
records are not read; otherwise, this intrinsic reads the data from the data le exactly as it
was stored.
Following execution of FREADC, the chronological pointer remains positioned at the record
just read, unless it is followed by another call to FREADC. In a series of calls to FREADC,
the pointer is advanced automatically so you can read the le in chronological sequence
without resetting the pointer for each record.
Because FUPDATE only checks the logical pointer, you cannot update a record located by
FREADC or FREADDIR. To update a record located by its chronological record number, you
must precede the call to FUPDATE with a call to FPOINT. Unlike FREADC or FREADDIR,
FPOINT sets the logical pointer as well as the chronological pointer.
In Figure 4-9, the FREADC intrinsic is used to read the data from the KSAM data le in
chronological order. Compare this order to the sequential order by primary key in which the
same le is read by FREAD. (Refer to Figure 4-10 for an example showing the chronological
record number printed in association with each record listed in sequential key order.)
SHARED ACCESS
Because FREADC is a chronological pointer-dependent procedure, you must call one of the
procedures that position the pointer before calling FREADC. (Refer to Table 4-2 for a list
of the pointer-dependent and pointer-independent procedures.) When access is shared, it is
essential that you lock the le before calling the procedure that positions the pointer, and
then leave the le locked while it is being read by FREADC. This insures that no other user
changes the information in the record.
For example, the following sequence of calls guarantees that you will read the le in
chronological sequence starting with a specied record number:
FLOCK &lt;----------- lock le
FPOINT &lt;------------- position the chronological pointer
FREADC loop &lt;----------------- read records in chronological sequence
FUNLOCK &lt;--------------- unlock le
USING KSAM FILES IN SPL PROGRAMS
4-77
$CONTROL MAIN=JEXAMPL4
&lt;&lt;*********************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 4
*&gt;&gt;
&lt;&lt;*
READ A KSAM FILE CHRONOLOGICALLY
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*********************************************************&gt;&gt;
INTEGER FILNUM;
INTEGER LENGTH;
INTEGER ERRORCODE;
BYTE ARRAY FILENAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE (0:35);
ARRAY INPUT(0:39);
ARAY OUTPUT(*)=INPUT;
INTRINSIC FOPEN,FCLOSE,FREADC,FCHECK,FERRMSG,PRINT,TERMINATE;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;************************&gt;&gt;
FILNUMI=FOPEN(FILNAME,3); &lt;&lt;OPEN THE KSAM FILE&gt;&gt;
IF FILNUM=0
THEN BEGIN
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCIDE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH):&lt;&lt;GET MESSAGE STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
L1;
&lt;&lt;****************************************************&gt;&gt;
&lt;&lt;*
READ KSAM ACCORDINGTO CHRONOLOGICAL ORDER
*&gt;&gt;
&lt;&lt;****************************************************&gt;&gt;
FREADC(FILNUM,INPUT, 072);
IF &gt;
THEN BEGIN &lt;&lt;END OF FILE&gt;&gt;
FCLOSE(FILNUM,0,0); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt;
THEN BEGIN
MOVE MESSAGE:=&quot;CANNOT CLOSE KSAM FILE&quot;;
PRINT(MESSAGE,022,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET THE ERROR NUMBER&gt;&gt;
FFERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;GET MESSAGE STRING&gt;&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
Figure 4-9. FREADC Example
4-78
USING KSAM FILES IN SPL PROGRAMS
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING KSAM FILE&quot;;
PRINT(MESSAGE,037,0);
TERMINATE;
END;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* WRITE THE DATA JUST READ FROM KSAM FILE *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
PRINT(OUTPUT,072,0);
&lt;&lt;************************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;************************************&gt;&gt;
GO TO L1;
END;
Output from Program Execution:
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022
ECKSTEIN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050
CARDIN RICK 578-7015 11100 WOLFE ROAD CUPERTINO CA. 94053
PASBY LINDA 295-1187 TOWN &amp; CNTRY VILLAGE SAN JOSE CA. 94102
SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053
ROBERT GERRY 259-5535 12345 TELEGRAPH AVE. BERKELEY CA. 90871
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234
WESTER ELDER 287-4598 1256 KINGFISHER ST. SUNNYVALE CA. 43098
END OF PROGRAM
Figure 4-9. FREADC Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-79
FREADDIR
INTRINSIC NUMBER 7
Reads a logical record located by its chronological record number from a KSAM le to the
user's stack.
IV
LA IV
DV
FREADDIR(lenum,target,tcount,recnum);
The FREADDIR intrinsic reads a specic logical record, or a portion of such a record, from a
KSAM le to the user's data stack. The particular record read is specied by its chronological
record number. This number is determined by the order in which the record was written to
the le; it is not the logical record number determined by ascending key sequence. When the
le has xed-length records, recnum is the actual record number counting from the rst record
in the le. When the le has variable-length records, recnum is a word pointer to the rst
word in the record counting from the rst word in the le, word zero.
After FREADDIR has been executed, the chronological record pointer remains positioned at
the record just read. FREADDIR does not change the position of the logical record pointer.
PARAMETERS
lenum
target
tcount
recnum
4-80
integer by value (required)
A word identier supplying the le number of the le to be read.
logical array (required)
An array to which the record is to be transferred. This array should be large
enough to hold all of the information to be transferred.
integer by value (required)
An integer specifying the number of words or bytes to be transferred. If this
value is positive, it signies words ; if negative, it signies bytes ; and if it is
zero, no transfer occurs.
If tcount is less than the size of the record, only the rst tcount words or
bytes are read from the record. If tcount is larger than the size of the logical
record, the transfer is limited to the length of the logical record.
double by value (required)
A double-word integer indicating the relative chronological record number (or
word number for variable-length records) to which the chronological pointer
is positioned. Chronological record numbering for xed-length records starts
with zero or one, as specied in ksamparam or by FIRSTREC in BUILD.
USING KSAM FILES IN SPL PROGRAMS
CONDITION CODES
CCE
CCG
CCL
The specied information was read.
The end-of-data was encountered during reading.
The information was not read because an error occurred.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FREADDIR
You can use the FREADDIR intrinsic to position to a particular record in chronological
sequence and then read that record. Following execution, the record pointer remains
positioned at the same record. This intrinsic is similar in eect to the pair of intrinsics
FPOINT and FREADC, with one exception: FREADDIR does not skip records marked for
deletion. You might use FREADDIR to read one record and then reposition the pointer;
you might use FPOINT and FREADC to position to a particular record and then continue
reading in chronological order from that position.
You can use the FGETINFO intrinsic to determine the relative chronological number of the
record most recently accessed. This number is returned in the FGETINFO parameter recpt .
The example in Figure 4-10 determines the chronological record of each record as it is read
in sequence by primary key value. The chronological record number is printed, and then
FREADDIR uses this number to read the record to which it points. The output shows the
chronological record number followed by the record to which it points. To see these records
listed in chronological order, refer to the output in example 4-9 illustrating FREADC.
Note that execution of those intrinsics that position the KSAM data le by means of the
chronological record pointer (FPOINT, FREADC, FREADDIR), do not access the key le.
This type of access only aects the data le. It is, therefore, much faster than those intrinsics
that use key sequence to position the data le and must access the key le.
USING KSAM FILES IN SPL PROGRAMS
4-81
$CONTROL MAIN=JEXAMPL6
&lt;&lt;******************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 6
*&gt;&gt;
&lt;&lt;*
READ A KSAM FILE BY CHRONOLOGICAL RECORD NUMBER *&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;******************************************************&gt;&gt;
INTEGER FILNUM;
INTEGER ERRORCODE;
INTEGER LENGTH;
BYTE ARRAY FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
DOUBLE RECPTR;
INTRINSIC FOPEN,FCLOSE,FREAD,FGETINFO,FREADDIR,
PRTNT,TERMINATE,DASCII,FCHECK,FERRMSG;
&lt;&lt;*************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;*************************&gt;&gt;
FILNUM,=FOPEN(FILNAME,3); &lt;&lt;OPEN THE KSAM FILE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRTNTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;*****************************************************&gt;&gt;
&lt;&lt;*
READ KSAM SEQUENTIALLY
*&gt;&gt;
&lt;&lt;****************#************************************&gt;&gt;
L1:
FREAD(FILNUM,INPUT,072);
IF &gt;
THEN BEGIN
FCLOSE(FILNUM,0,0); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;;
PRINT(MESSAGE,022,0);
Figure 4-10. FREADDIR Example
4-82
USING KSAM FILES IN SPL PROGRAMS
FCHECK(FILNUM,ERRORCOOE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FFRRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING KSAM FILE&quot;;
PRINT(MESSAGE,037,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;*****************************************************&gt;&gt;
&lt;&lt;* TO FIND OUT RECORD NUMBER OF THE RECORD JUST READ *&gt;&gt;
&lt;&lt;*****************************************************&gt;&gt;
FGETINFO(FINUM,,,,,,,,RECPTR);
MOVE MESSAGE:=&quot;RECORD# = &quot;;
DASCII(RECPTR,10,MESSAGE(5));
PRINT(MESSAGE,014,0);
&lt;&lt;**********************************************&gt;&gt;
&lt;&lt;* READ THE KSAM FILE BY USING RECORD NUMBER *&gt;&gt;
&lt;&lt;**********************************************&gt;&gt;
FREADDIR(FILNUM,INPUT,072,RECPTR);
IF &lt;&gt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED DURING FREADDIR&quot;;
PRINT(MESSAGE,030,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* WRITE THE DATA JUST READ BY FREADDIR *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
PRINT(OUTPUT,072,0);
&lt;&lt;**********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;**********************************&gt;&gt;
GO TO L1;
END;
Figure 4-10. FREADDIR Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-83
Output from Program Execution:
RECORD# = 4
CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053
RECORD# = 3
ECKSTEIN LEO 287-5137 5303 STEVENS CREEK SANTA CLARA CA. 95050
RECORD# = 2
HOSODA JOE 227-8214 1180 SAINT PETER CT. LOS ALTOS CA. 94022
RECORD# = 1
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087
RECORD# = 5
PASBY LINDA 295-1187 TOWN &amp; CNTRY VILLAGE SAN JOSE CA. 94102
RECORD# = 7
ROBERT GERRY 259-5535 12345 TELEGRAPH AVE. BERKELEY CA. 90871
RECORD# = 6
SEELY HENRY 293-4220 1144 LEBERTY ST. EL CERRITO CA. 94053
RECORD# = 8
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234
RECORD# = 10
WESTER ELDER 287-4598 1256 KINGFISHER ST. SUNNYVALE CA. 43098
RECORD# = 9
WHITE GORDON 398-0301 4350 ASHBY AVE. BERKELEY CA. 91234
END OF PROGRAM
Figure 4-10. FREADDIR Example (continued)
4-84
USING KSAM FILES IN SPL PROGRAMS
FREADLABEL
INTRINSIC NUMBER 19
Reads a user le label.
IV
LA
IV
FREADLABEL(lenum,target,tcount,labelid);
IV
O-V
The FREADLABEL intrinsic reads a user-dened label from a disc le. Before reading
occurs, the user's read-access capability is veried. Note that MPE automatically skips over
any unread user labels when the rst FREAD intrinsic call is issued for a le; therefore the
FREADLABEL intrinsic should be called immediately after the FOPEN intrinsic has opened
the le.
PARAMETERS
lenum
target
tcount
labelid
integer by value (required)
A word identier supplying the le number of the le whose label is to be
read.
logical array (required)
An array in the stack to which the label is to be transferred. This array
should be large enough to hold the number of words specied by tcount .
integer by value (optional)
An integer specifying the number of words to be transferred from the label.
Tcount must not be greater than 128 words.
Default: 128 words.
integer by ualue (optional) An integer specifying the label number where the
rst user label is numbered 0.
Default: A default value of 0 is assigned.
CONDITION CODES
CCE
CCG
CCL
The label was read
The intrinsic referenced a label beyond the last label written on the le.
The label was not read because an error occurred.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING KSAM FILES IN SPL PROGRAMS
4-85
USING FREADLABEL
If the KSAM le contains one or more user labels (written with FWRITELABEL), you
can read these labels with the FREADLABEL intrinsic. During the normal le reads with
FREAD, FREADC, FREADBYKEY, or FREADDIR, any user labels are ignored. The
number of user labels that can be written to the le is specied by the userlabels parameter of
FOPEN, or in the BUILD command of KSAMUTIL.
Since MPE checks to insure that you have opened the le with read access before executing
FREADLABEL, you must open the le with an FOPEN aoptions setting that permits
reading. It must be one of the following:
bits 12:4
= 0000 (octal 0) read only access
= 0100 (octal 4) input/output access
= 0101 (octal 5) update access
In addition, the FOPEN userlabels parameter must be set to a value of 1 or greater depending
on the number of labels that may be written to the le.
Suppose you have opened the le KDATA with the following call:
KFILNUM:=FOPEN(KDATA,3,4,,,,2);
/ ^
\
/ |
\
/ |
number of labels
old user/
|
domain
|
|
|
input/output access
You might read the second label with the following call:
FREADLABEL(KFILNUM,LABELBUF,,1)
This reads the second label into the array LABELBUF. Note that label numbering begins
with 0; if the labelid parameter were zero or omitted, then the rst label would be read. By
default, the number of words read from the label is 128.
4-86
USING KSAM FILES IN SPL PROGRAMS
FREADSEEK
INTRINSIC NUMBER 12
Moves a record from a disc le to a buer in anticipation of a FREADDIR intrinsic call.
Note
This intrinsic may not be used for KSAM les. If called for a le created as a
KSAM le, the intrinsic returns a CCL condition code.
USING KSAM FILES IN SPL PROGRAMS
4-87
FRELATE
INTRINSIC NUMBER 18
Determines whether a le pair is interactive, duplicative, or both interactive and duplicative.
Note
4-88
This intrinsic may not be used for KSAM les. If called for a le created as
a KSAM le, the functional return is set to zero (FALSE) and the condition
code CCE is returned.
USING KSAM FILES IN SPL PROGRAMS
FREMOVE
INTRINSIC NUMBER 306
Marks the current record in KSAM le for deletion.
IV
FREMOVE(lenum);
The intrinsic FREMOVE eectively removes the current record from the KSAM le. When
executed, the rst two characters of the current record in the data le is set to all 1's, and all
key entries pointing to this record are deleted from the key le. Although the space required
by the record remains in the data le, it is no longer possible to access the record through
KSAM intrinsics.
In order to position the le to the record to be deleted, FREMOVE must be preceded by
one of the intrinsics that positions the logical record pointer: FFINDN, FFINDBYKEY,
FREADBYKEY, FREAD, FPOINT, or a previous FREMOVE. Following execution of
FREMOVE, the logical record pointer is positioned at the next record in ascending key
sequence.
FREMOVE checks only the logical record pointer, not the chronological pointer, to locate the
record to be deleted. Therefore, if you want to delete a record located by its chronological
position in the le, precede the call to FREMOVE with a call to FPOINT. FPOINT locates
the record by its record number and sets the logical, as well as the chronological pointer, to
that record. If you try to locate a record for FREMOVE by calling FREADDIR or FREADC,
which only set the chronological pointer, you will delete the wrong record.
When FREMOVE is executed, a check is made to make sure the record to be deleted actually
contains the key value to which the pointer is positioned. If the record does not contain that
value, then a condition code (CCL, error=191) is issued and the record is not deleted.
If the le was opened for shared access (aoptions bits 8,9 = 11) then you must call FLOCK
before calling FREMOVE. Note that the le must also have been opened with dynamic
locking allowed (aoptions bit 10 = 1).
Note
If you want to recover the data in deleted records through nonKSAM access
(using FCOPY with the NOKSAM option), do not place any data in the rst
two bytes since these bytes are overwritten by FREMOVE.
PARAMETERS
lenum
integer by value (required)
A word identier supplying the le number of the le from which the record is
to be deleted.
USING KSAM FILES IN SPL PROGRAMS
4-89
CONDITION CODES
CCE
CCG
CCL
The current record is deleted.
The logical end-of-data was encountered.
An error was encountered or record does not contain requested key value; the
record is not deleted.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FREMOVE
When FREMOVE is executed, it sets the rst word (bytes 1 and 2) of the current record to
all 1's. It does not physically delete the record from the le. When the le is read by any of
the KSAM read intrinsics, the deleted records are skipped as if they were not there. Since all
references to them are deleted from the key le, the speed of execution is not usually aected
by the records physically remaining in the le. However, they do take up space and if a great
many records are deleted, then you might want to build a new KSAM le and copy the old le
to the new le with FCOPY. Since FCOPY does not copy records marked for deletion (except
with the NOKSAM option), the new le will be shorter and have no space used by deleted
records. (Refer to section II for a description of copying KSAM les with FCOPY.)
The example in Figure 4-11 deletes all records with a telephone number in the alternate key
eld that is equal to or greater than \500-0000&quot;. The FFINDBYKEY intrinsic positions
the le to the record containing the lowest alternate key value that is greater than or equal
to \500-0000&quot;. This record is then read and printed prior to being deleted by FREMOVE.
Following FREMOVE, the program loops back to read the next sequential record, print it,
and then delete it. When an end of data is reached, the program terminates. In all, the
program deletes three records. You can check the deleted records against the list of records
printed in telephone number sequence by the program illustrating FREAD in Figure 4-7.
In practice, an FREAD prior to an FREMOVE is useful because it allows you to test the
record contents prior to deleting the record. For example, you might want to delete only those
records with the zip code 90871 in bytes 75 through 79 of the record, assuming the same le
as in Figure 4-11:
4-90
USING KSAM FILES IN SPL PROGRAMS
BYTE ARRAY INPUTB(*)=INPUT; &lt;---- Equate the byte array INPUTB to INPUT
..
.
L1:
FREAD(FILNUM,INPUT,072);
IF&gt;
.
. &lt;----- test for end of data
.
IF&lt;
.
.&lt;------ test for read error
.
IF INPUTB(75)=&quot;90871&quot;
THEN BEGIN
FREMOVE(FILNUM);
IF&lt;
.
. &lt;----- test for delete error
.
END;
GO TO L1; &lt;--------------- return for next record
SHARED ACCESS
In a shared environment, you must always lock the le with a call to FLOCK before calling
FREMOVE. Furthermore, since the logical record pointer must be positioned before the call
to FREMOVE, you should lock the le before calling the procedure that positions the pointer.
This prevents other users from aecting the pointer position by adding or deleting records
between the time you position the pointer and call FREMOVE. The following sequence of
calls illustrates the correct method for deleting a record in a shared environment:
FLOCK &lt;------------- lock the le
FREADBYKEY &lt;------------- position pointer and read record
FREMOVE &lt;-- mark the record for deletion
FUNLOCK &lt;-- unlock le to allow access to other users
Remember to open the le for shared access and allow dynamic locking whenever you plan to
delete records from a le in a shared environment.
USING KSAM FILES IN SPL PROGRAMS
4-91
$CONTROL MAIN=JEXAMPL7
&lt;&lt;******************************************************&gt;&gt;
&lt;&lt;*
EXAMPLE 7
*&gt;&gt;
&lt;&lt;*
DELETE SELECTED RECORDS
*&gt;&gt;
&lt;&lt;******************************************************&gt;&gt;
INTEGER FILNUM;
INTEGER LENGTH;
INTEGER ERRORCODE;
BYTE ARRAY FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
BYTE ARRAY KEYVALUE (0:7):=&quot;500-0000&quot;;
INTEGER KEYLENGTH:=8;
INTEGER KEYLOCATION;=21;
INTEGER RELOP;=2; &lt;&lt; GREATER THAN OR EQUAL TO &gt;&gt;
INTRINSIC FOPEN,FCLOSE,FREAD,FREMOVE,FFINDBYKEY,
READ,PRINT,TERMINATE,CHECK,FERRMSG;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;&lt;************************&gt;&gt;
FILNUM:=FOPEN(FILNAME,3,5); &lt;&lt;OPEN THE KSAM FILE FOR UPDATE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE:= 021,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;********************************************************&gt;&gt;
&lt;&lt;* POSITION KSAM FIL IN TELEPHONE # SEQUENCE *&gt;&gt;
&lt;&lt;********************************************************&gt;&gt;
FFINDBYKEY(FILNUM,KEYVALUE,LEYLOCATION,LEYLENGTH,RELOP);
MOVE MESSAGE:=&quot;DELETE FOLLOWING RECORDS:&quot;;
PRINT(MESSAGE,025,0);
&lt;&lt;**********************************&gt;&gt;
&lt;&lt;* READ RECORD BEFORE DELETING *&gt;&gt;
&lt;&lt;**********************************&gt;&gt;
L2:
FREAD(FILNUM,INPUT,072); &lt;&lt; READ RECORDS TO BE DELETED&gt;&gt;
Figure 4-11. FREMOVE Example
4-92
USING KSAM FILES IN SPL PROGRAMS
IF &gt;
THEN BEGIN &lt;&lt;END OF FILE&gt;&gt;
FCLOSE(FILNUM,0,0) &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN &lt;&lt;CLOSE UNSUCCESSFUL&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KASM FILE&quot;;
PRINT(MESSAGE,029,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MEEAGE,034,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* WRITE THE RECORD JUST READ FROM KSAM FILE *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
PRINT(OUTPUT,072,0);
&lt;&lt;*****************************************&gt;&gt;
&lt;&lt;* REMOVE RECORD JUST READ FROM FILE *&gt;&gt;
&lt;&lt;*****************************************&gt;&gt;
FREMOVE(FILNUM); &lt;&lt;DELETE RECORD&gt;&gt;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=ERORROR OCCURRED DURING DELETE&quot;;
PRINT(MESSAGE,028,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;************************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;************************************&gt;&gt;
GO TO L2;
END,
Figure 4-11. FREMOVE Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-93
Output from Program Execution:
DELETE FOLLOWING RECORDS:
CARDIN RICK 578-7018 11100 WOLFE ROAD CUPERTINO CA. 94053
NOLAN JACK 923-4975 967 REED AVE. SUNNYVALE CA. 94087
TURNEWR IVAN 984-8498 22905 EMERSON ST. OAKLAND CA. 98234
END 0F PROGRAM
Figure 4-11. FREMOVE Example (continued)
4-94
USING KSAM FILES IN SPL PROGRAMS
FRENAME
INTRINSIC NUMBER 17 Renames a disc le.
Note
This intrinsic may not be used for KSAM les. If called for a le created as a
KSAM le, the intrinsic returns a CCL condition code.
To rename a KSAM le, use the KSAMUTIL RENAME command.
USING KSAM FILES IN SPL PROGRAMS
4-95
FSETMODE
INTRINSIC NUMBER 14
Activates or deactivates critical output verication
IV LV
FSETMODE(lenum,modeags);
The FSETMODE intrinsic activates or deactivates the access mode option that permits
critical output verication. This means that all output must be veried as physically complete
before control returns from an output intrinsic (FWRITE,FUPDATE, or FREMOVE) to your
program.
The access mode established by the FSETMODE intrinsic remains in eect until another
FSETMODE call is issued or until the le is closed.
PARAMETERS
lenum
modeags
integer by value (required) A word identier supplying the le number of the
le to which the call applies.
logical by value (required) A 16-bit value that denotes the access mode options
in eect. For KSAM les only bit 14 is used; all the remaining bits are set to
zeros.
Bit 14=1|;
Activate Critical Output Verication When this bit is set, all
output to the le is veried as physically complete before an
FWRITE, FUPDATE, or FREMOVE intrinsic returns control
to the user. As soon as a logical record is written, a CCE
condition is returned to the user.
Bit 14=0|;
Deactivate Critical Output Verication When the bit is
cleared, output is no longer veried.
CONDITION CODES
CCE
CCG
CCL
Request granted.
Not returned by this intrinsic.
Request denied because an error occurred.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
4-96
USING KSAM FILES IN SPL PROGRAMS
USING FSETMODE
When FSETMODE is executed with the modeags parameter equal to 2 (bit 14=1),
then each logical record written by an output intrinsic is physically transferred to the le
immediately. Control is not returned to the user program until the transfer has been made.
At that time a CCE condition code is returned to the program.
When FSETMODE is executed with the modeags parameter equal to zero (bit 14=0),
output is treated in the standard manner. That is, when an output intrinsic writes a logical
record, the record is physically transferred to the le only when the entire physical record
(block) of which it is a part is transferred. (Calls to FWRITE, FUPDATE, and FREMOVE
send output to the KSAM le.)
For example, the following intrinsic call activates critical output verication:
FSETMODE(FILNUM,2);
If you want to return to normal output mode, you can use the call:
FSETMODE(FILNUM,0);
When the le is rst opened and when it is opened subsequently following an FCLOSE call,
the critical output verication mode is deactivated.
USING KSAM FILES IN SPL PROGRAMS
4-97
FSPACE
INTRINSIC NUMBER 5
Spaces forward or backward on a le.
IV
IV
FSPACE(lenum,displacement);
The FPSACE intrinsic allows you to space forward or backward a specied number of records
on a KSAM le. The logical record pointer is repositioned by FSPACE in key sequence. The
spacing is based on primary key sequence unless an alternate key has been specied in a prior
call to FFINDN, FFINDBYKEY, or FREADBYKEY.
PARAMETERS
lenum
displacement
integer by value (required)
A word identier supplying the le number of the le on which spacing is to
be done.
integer by value (required)
An integer indicating the number of logical records to be spaced over, relative
to the current logical record pointer position. Record sequence for spacing is
based on key sequence. A positive value signies forward spacing, a negative
value signies backward spacing; zero signies no spacing, but sets a ag so
that the next call to FREAD does not move the logical record pointer before
reading the record. The maximum positive value is 32767; the maximum
negative value is 032768. The sign is optional for positive values.
CONDITION CODES
CCE
CCG
Request granted.
A logical end-of-le indicator was encountered during spacing. The logical
record pointer is at the beginning-of-le if displacement was negative, to the
end-of-le if displacement was positive.
Request denied because an error occurred.
CCL
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FSPACE
If you want to space back a particular number of records in key sequence, you would specify
a negative value for the displacement parameter in a call to FSPACE. To space forward,
you would use a positive or unsigned integer as the displacement value. In either case, the
displacement indicates the number of records to space over.
For example, suppose the following sequence of primary key values:
ABLE
4-98
USING KSAM FILES IN SPL PROGRAMS
BAKER &lt;---------- (2) pointer after FSPACE(FILNUM,02);
CHARLIE
DOG &lt;------------ (1) current record pointer
EASY
FOX &lt;------------ (3) pointer after FSPACE(FILNUM,4);
Suppose the current record pointer is at the beginning of the record whose primary key
contains the value DOG. To position the pointer to the beginning of the record with a
primary key value BAKER:
FSPACE(FILNUM,02);
To space forward from the beginning of the record with BAKER as the key value to the
beginning of the record with FOX as the key value:
FSPACE(FILNUM,4);
Figure 4-12 shows that the movement of the pointer bears no relation to the physical
placement of records in the le.
Figure 4-12. File Position with FSPACE
POINTER POSITION
FSPACE checks a ag to determine whether to advance the pointer before it moves the
pointer the specied number of records. If FSPACE follows a call that reads the le (FREAD
or FREADBYKEY) then it advances the pointer to the record in key sequence following the
USING KSAM FILES IN SPL PROGRAMS
4-99
record just read. After advancing the pointer, FSPACE positions the pointer as indicated
in the call. If, on the other hand, FSPACE follows FPOINT, FFINDBYKEY, or FFINDN,
the pointer remains positioned to the record specied in one of these calls until FSPACE is
executed.
To illustrate, consider the following calls:
FREAD &lt;------------- read record, set ag to advance pointer
FSPACE(01) &lt;--------------- test ag, advance pointer, then move pointer back 1 record
FREAD &lt;---------------- reread record just read
SHARED ACCESS
Because FSPACE is a pointer-dependent procedure (see Table 4-2), it is essential to lock the
le before the call that determines the original pointer position, then call FSPACE, then call
any other procedures that depend on where FSPACE positioned the pointer. When all the
pointer-dependent procedures are complete, then unlock the le for other users. To illustrate:
FLOCK &lt;-------------- lock le
FFINDBYKEY &lt;---------------- locate a particular key ualue
FSPACE &lt;------------- move pointer relative to that key position
FREAD &lt;-------------- read the record to which pointer is positioned
FUNLOCK &lt;-------------- unlock the le
4-100
USING KSAM FILES IN SPL PROGRAMS
FUNLOCK
INTRINSIC NUMBER 16
Dynamically unlocks a KSAM le.
IV
FUNLOCK(lenum);
The FUNLOCK intrinsic dynamically unlocks a KSAM le (Resource Identication Number)
that has been locked with the FLOCK intrinsic.
PARAMETERS
lenum
integer by value (required)
A word supplying the le number of the le to be unlocked.
CONDITION CODES
CCE
CCG
CCL
Request granted.
Request denied because the le had not been locked by the calling process.
Request denied because the le was not opened with the dynamic locking
aoption of the FOPEN intrinsic, or the lenum parameter is invalid.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FUNLOCK
A le that has been locked with FLOCK in order to allow exclusive updating should be
unlocked with FUNLOCK as soon as the update is complete. Dynamic locking and unlocking
apply to les opened for this capability. In the aoptions parameter of FOPEN, bit 10 must be
set to 1 in order to use either FLOCK or FUNLOCK. (For more discussion of dynamic locking
and unlocking, refer to the FLOCK intrinsic description.)
Suppose a le has been locked to allow update of a record. To unlock the le following
completion of the update, use the call:
FUNLOCK(FILNUM);
When FUNLOCK is executed, all output written while the le was locked is transferred to the
le so that other users have the most recent data.
USING KSAM FILES IN SPL PROGRAMS
4-101
FUPDATE
INTRINSIC NUMBER 4
Updates the contents of a logical record in a KSAM le.
IV
LA
IV
FUPDATE(lenum,target,tcount);
The FUPDATE intrinsic can be used to update a logical record in a KSAM le. The entire
record including primary and any alternate keys can be updated with FUPDATE. The record
to be updated is the record last referenced by the intrinsics FREAD, FREADBYKEY,
FFINDBYKEY, or FPOINT. The new values for the record are moved from the user's
stack into this record. The le containing this record must have been opened with the
aoption parameter of FOPEN set to update access. FUPDATE can be used to update both
xed-length and variable-length records. FUPDATE can be used to modify key values or to
change record size, but if key values or the record size are changed, the update operation
causes the entire record to be deleted and then rewritten. After an update, a subsequent call
to FREAD will read the next record in ascending key sequence after the record just written.
FUPDATE checks only the logical record pointer, not the chronological pointer, in order to
determine which record to update. Therefore, if you want to update a record based on its
chronological position, precede the call to FUPDATE by a call to FPOINT. FPOINT locates
the record by its record number and sets the logical, as well as the chronological, pointer. If
you try to locate a record for FUPDATE by calling FREADDIR or FREADC, which only set
the chronological pointer, the wrong record will be updated.
If the le was opened for shared access (aoptions bits 8,9 = 11), then you must call FLOCK
to lock the, le before calling FUPDATE. Note that the le must also have been opened with
dynamic locking allowed (aoptions bit 10 = 1).
PARAMETERS
lenum
target
tcount
integer by value (required) A word identier supplying the le number of the
le to be updated.
logical array (required) Contains the record to be written in the updating.
integer by value (required) An integer specifying the number of words or bytes
to be written from the record. If this value is positive, it signies words; if
it is negative, it signies bytes. If tcount is less than the recsize parameter
associated with the record, only the rst tcount bytes or words are written.
CONDITION CODES
CCE
CCG
CCL
4-102
Request granted.
An end-of-le condition was encountered during updating.
Request denied because of an error, such as tcount exceeds the record size
dened for the KSAM le; or tcount does not include all the keys; or a disc
input/output error.
USING KSAM FILES IN SPL PROGRAMS
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FUPDATE
In order to update a record in a KSAM le, you must open the le for update. This access
mode is specied by setting bits 12 through 15 of the FOPEN aoptions parameter to the octal
value 5 (binary value 0101). You must then access the record to be updated. Normally, you
would read the record with one of the read intrinsics and then modify the record just read.
The record to be updated by FUPDATE is the last record accessed. FUPDATE writes the
contents of a user buer area (target ) over the existing contents of the last record accessed.
The record written by FUPDATE must contain all the key values expected by the le. If only
a portion of the record is specied by a tcount parameter less than the original record size,
then this portion must contain all primary and alternate key values or a CCL condition is
returned and the update does not take place.
The example in Figure 4-13 shows an update of an alternate key, the telephone number
located in bytes 21 through 28 of the record. In order to locate the record to be updated,
FREADBYKEY is executed before FUPDATE. The data input through the standard input
device contains the keylocation and keyvalue values for FREADBYKEY as well as the new
value for the update:
byte | 0 1 | 2
21 | 22
29 |
|-----|----------------------------------|----------------|
|
|
|
|
|
|
name
| phone number
|
|-----|----------------------------------|----------------|
^
^
^
|
|
|
keylocation
keyvalue
new value
(starting byte)
(primary key)
(alternate key)
Note that bytes are numbered from zero in the standard input or output device, but bytes in
the KSAM record are numbered starting from 1 for the keylocation parameter.
SHARED ACCESS.
When access is shared, it is essential to lock the le with a call to FLOCK before rewriting
any records. After the update, you should unlock the le with FUNLOCK. To make sure
you are updating the correct record, include both the intrinsic that locates the record and
FUPDATE between the same pair of FLOCK and FUNLOCK intrinsics.
For example, suppose you use FREADBYKEY to examine the record to be updated, you
should lock the le before calling the intrinsic that locates the record to be updated and
unlock if after the update:
FLOCK
FREADBYKEY (or FFINDBYKEY) &lt;----------- locate record to be updated
..
.
FUPDATE &lt;------- update record
FUNLOCK &lt;----------- all key buers, data buers and control information written to disc
USING KSAM FILES IN SPL PROGRAMS
4-103
If you perform operations on a record between locating it and updating it, and you do not
want to lock the le during this process (between the read and the update), then you can use
the following code sequence:
FLOCK
FREADBYKEY (or FFINDBYKEY) &lt;----- locate record
FUNLOCK
.
. &lt;----------------- while you decide whether to update record,
. other users can modify or delete it
(decide to update)
FLOCK
FREADBYKEY (or FFINDBYKEY) &lt;----------- reread record
FUPDATE
FUNLOCK
UPDATING RECORDS WITH DUPLICATE KEYS.
If you want to sequentially update all the records in a chain of records with duplicate keys,
locate the rst record in the chain with FFINDBYKEY, FREADBYKEY, or FPOINT. Then
call FUPDATE to modify this record. If no key value (the selected key or any other) is
modied, subsequent calls to FUPDATE will modify the next sequential records in the chain
of records with duplicate keys. If, however, any key has been changed, the modied key is
written to the end of the chain and the next sequential record is one with the next higher key
value. In this case, to update all records with duplicate keys, precede each call to FUPDATE
with a call to FFINDBYKEY, FREADBYKEY, or FPOINT to position to the beginning of
the chain.
If you are in the middle of a duplicate key chain and FUPDATE modies a key value, you can
position back to the next duplicate key in the chain with the following sequence of calls:
FSPACE(FILNUM,1); &lt;-------- position to next sequential record
FGETINFO(FILNUM,,,,,,,,,RECPTR); &lt;--------------- retrieve current record number
FSPACE(FILNUM,01); &lt;--------------- backspace to current record
FUPDATE(FILNUM,OUTPUT,072); &lt;------------ modify key, positioning to end of key chain
.
.
.
FPOINT(FILNUM,RECPTR); &lt;-------- position to next duplicate key using record number
retrieved by FGETINFO
Note that if the KSAM le has xed-length records or if the updated record is the same size
as the old record, the space in the data le is reused. Otherwise, the updated record is written
to the end of the data le.
4-104
USING KSAM FILES IN SPL PROGRAMS
$CONTROL MAIN=JEXAMPL8
&lt;&lt;******************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 8
*&gt;&gt;
&lt;&lt;*
UPDATE A RECORD IN A KSAM FILE
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;******************************************************&gt;&gt;
INTEGER FILUM;
INTEGER ERRORCODE;
INTEGER LENGTH;
BYTE ARRAY FILNAME (0:9);=&quot;JEXAMPLE &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
BYTE ARRAY OUTPUTB(*)=OUTPUT;
BYTE ARRAY INFO(0:35);
ARRAY INFOW(*)=INFO;
BYTE ARRAY KEYVALUE(*)=INFO(2);
INTEGER KEYLOCATION;
INTRINSIC FOPEN,FCLOSE,FUPDATE,FREADBYKEY,READ,PRINT,
BINARY,FCHECK,FERRMSG,TERMINATE;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THF KSAM FILE
*&gt;&gt;
&lt;&lt;************************&gt;&gt;
FILNUM:=FOPEN(FILNAME,3,5); &lt;&lt;OPEN THE KSAM FILE FOR UPDATE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK (FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* READ IN KEYVALUE AND KEYLOCATION INFOMATION *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
L1:
READ(INFOW,036);
Figure 4-13. FUPDATE Example
USING KSAM FILES IN SPL PROGRAMS
4-105
IF &gt;
THEN BEGIN
FCLOSE(FILNUM,0,0,); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;;
PRINT (MESSAGE,026,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
END
TERMINATE;
END;
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGE,034,0);
TERMINATE;
END;
PRINT(INFOW, 036,0); &lt;&lt;TEST READ&gt;&gt;
KEYLOCATION:=BINARY(INFO,2); &lt;&lt;CONVERT FROM ASCII TO BINARY&gt;&gt;
&lt;&lt;*****************************************************&gt;&gt;
&lt;&lt;* READ KSAM ACCORDING TO KEYVALUE AND KEYLOCATION *&gt;&gt;
&lt;&lt;*****************************************************&gt;&gt;
FREADBYKEY(FTLNUM,INPUT,072,KEYVALUE,KEYLOCATION);
IF &lt;&gt;
THEN BEGIN &lt;&lt;ERROR OCCUPRED IN FREADBYKEY&gt;&gt;
MOVE MESSAGE:=&quot;ERROR OCCUPRED IN FREADBYKEY&quot;;
PRINT(MESSAGE,028,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
GO TO L1;
END;
&lt;&lt;**********************************************&gt;&gt;
&lt;&lt;*
UPDATE THE RECORD JUST READ
*&gt;&gt;
&lt;&lt;**********************************************&gt;&gt;
MOVE OUTPUTB(20):=INFO(22),(8);
FUPUATE(FILNUM,OUTPUT,072);
IF &lt;&gt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED DURING UPDATE&quot;;
PRINT(MESSAGE,028,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
Figure 4-13. FUPDATE Example (continued)
4-106
USING KSAM FILES IN SPL PROGRAMS
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* PRINT THE RECORD JUST UPDATED *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
PRINT(OUTPUT,072,0);
&lt;&lt;***********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;***********************************&gt;&gt;
GO TO L1;
END;
Output from Program Execution:
read from $STDIN
/
/
/updated record
/
/
01WHITE GORDON 428-2498
/
WHITE GORDON 428-2498 4350 ASHBY AVE. BERKELEY CA. 91234
01ECKSTEIN LEO 263-2464
ECKSTEIN LEO 263-2464 5303 STEVENS CREEK SANTA CLARA CA. 95050
Figure 4-13. FUPDATE Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-107
FWRITE
INTRINSIC NUMBER 3
Write a logical record from the user's stack to a KSAM le.
IV
LA
IV
LV
FWRITE(lennum,target,tcount,control);
The FWRITE intrinsic writes a logical record from the user's stack to the KSAM le. The
record contents are contained in the array target in the user's program and include all key
values. FWRITE uses the primary key value to update the key le so that the new record is
in sequence by primary key value. Any alternate keys are also entered into their appropriate
positions in the key le. No separate key specication is required since all the key values are
contained in the record to be written.
Following execution of FWRITE, the logical record pointer is positioned at the next sequential
record in key sequence or at the end-of-le if the record is the last in sequence. The particular
key is the current key being used when FWRITE is called.
If sequential processing was specied for the le in the agword of ksamparam when the le
was opened by FOPEN, then the records must be written in ascending order by primary key.
If duplicate keys are not allowed, any record with a key duplicating a key in an existing record
is not written and a CCL condition code is returned.
When the physical bounds of either the data le or the key le prevent further writing (all
allowable extents are lled), an end-of-le condition code (CCG) is returned to the user's
program.
If the le was opened for shared access (aoptions bits 8,9 = 11), then you must dynamically
lock the le with FLOCK before calling FWRITE. Note that the le must also have been
opened for dynamic locking (aoptions bit 10 = 1).
PARAMETERS
lenum
target
tcount
control
4-108
integer by value (required)
A word identier supplying the le number of the le to be written on.
logical array (required)
Contains the record to be written.
integer by value (required)
An integer specifying the number of words or bytes to be written to the
record. If this value is positive, it signies words; if it is negative, it signies
bytes; if it is zero, no transfer occurs. If tcount is less than the recsize
parameter associated with the record, only the rst tcount words or bytes are
written.
If tcount is larger than the recsize value, the write request is refused and
condition code CCL is returned.
logical by value (required)
USING KSAM FILES IN SPL PROGRAMS
A logical value representing a carriage control code. This parameter has no
meaning for KSAM les but must be included for compatibility. Whatever
value is specied will be ignored.
CONDITION CODES
CCE
CCG
CCL
Request granted.
The physical bounds of the le prevented further writing; all disc extents are
lled.
Request denied because an error occurred, such as: an input/output error
occurred; a duplicate key value occurred when duplicates are not allowed;
tcount does not include all keys; or sequential processing was specied in the
agword of ksamparam in FOPEN and the primary key is not the next in
ascending order.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FWRITE
The FWRITE intrinsic writes records from an array in your program to a KSAM le. All the
key information is contained in this target array. The record is written to the data le and the
keyle is updated to reect the primary key and any alternate keys in the new record.
Depending on how the le was opened, you can write records at random regardless of primary
key order, or you may be constrained to write records in sequential order by primary key
value. The examples in this manual use the le JEXAMFIL that is created for writing at
random. If you refer to Figure 4-5, the agword of the ksamparam parameter is set to the
binary value 0000000000000010. Bit 14, indicating that record numbers start with 1, is the
only bit set. If bit 13 had also been set to 1 then all records written to the le would have to
be in ascending order by primary key value. In such a case, the chronological order of records
and the sequential order would be the same.
When you write a record to a KSAM le, FWRITE either overwrites any records previously
written to the le or else writes new records following existing records. The choice is made
when you open the le. If you set bits 12 through 15 of the aoptions parameter of FOPEN to
the binary value 0001 (octal or decimal 1), then all records written to the le before this open
are deleted and FWRITE writes records to a cleared le . If you set bits 12 through 15 of
aoptions to 0010 or 0011 (octal or decimal 2 or 3), then any previously written data is saved.
The example in Figure 4-14 deletes any data written to le JEXAMFIL before it was opened.
The le will have no data other than that written by this program. If, after closing the le,
you want to open it to write more data without deleting existing data, then you must set the
aoptions access type (bits 12-15) to 0010 or 0011.
SHARED ACCESS
When access is shared, it is essential that you lock the le before writing new records. This
means opening the le with dynamic locking allowed and calling FLOCK before calling
FWRITE. You should also unlock the le with FUNLOCK after writing the records.
USING KSAM FILES IN SPL PROGRAMS
4-109
$CONTR0L MAIN=EXAMPLE9
&lt;&lt;******************************************************&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;*
EXAMPLE 9
*&gt;&gt;
&lt;&lt;*
WRITE TO EXISTING KSAM FILE
*&gt;&gt;
&lt;&lt;*
*&gt;&gt;
&lt;&lt;******************************************************&gt;&gt;
INTEGER FILNUM;
INTEGER ERRORCODE;
INTEGER LENGTH;
BYTE ARRAY FILNAME(0:9):=&quot;JEXAMFIL &quot;;
ARRAY MESSAGE(0:35);
ARRAY INPUT(0:39);
ARRAY OUTPUT(*)=INPUT;
INTRINSIC FOPEN,FCLOSE,FWRITE,READ,PRINT,FCHECK,FERRMSG;
INTRINSIC TERMINATE;
&lt;&lt;************************&gt;&gt;
&lt;&lt;* OPEN THE KSAM FILE *&gt;&gt;
&lt;*************************&gt;&gt;
FILNUM:=FOPEN(FILNAME,3,2); &lt;&lt;OPEN FILE FOR WRITE&gt;&gt;
IF FILNUM=0
THEN BEGIN &lt;&lt;CANNOT OPEN KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT OPEN KSAM FILE&quot;;
PRINT(MESSAGE,021,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;**********************************&gt;&gt;
&lt;&lt;* READ DATA FROM $STDIN DEVICE *&gt;&gt;
&lt;&lt;**********************************&gt;&gt;
L1;
READ(INPUT,072); &lt;&lt;READ ONE RECORD FROM $STDIN&gt;&gt;
IF &gt;
THEN BEGIN &lt;&lt;END OF FILE ON $STDIN&gt;&gt;
FCLOSE(FILNUM,1,0); &lt;&lt;CLOSE THE KSAM FILE&gt;&gt;
IF &lt;&gt; THEN
BEGIN &lt;&lt;CANNOT CLOSE THE KSAM FILE&gt;&gt;
MOVE MESSAGE:=&quot;CANNOT CLOSE THE KSAM FILE&quot;;
PRINT(MESSAGE,029,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMRER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
END;
TERMINATE;
END;
Figure 4-14. FWRITE Example
4-110
USING KSAM FILES IN SPL PROGRAMS
IF &lt;
THEN BEGIN
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE READING INPUT&quot;;
PRINT(MESSAGE,034,0);
TERMINATE;
END;
PRINT(OUTPUT,072,0); &lt;&lt;ECHO CHECK&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
&lt;&lt;* WRITE THE DATA JUST READ TO THE KSAM FILE *&gt;&gt;
&lt;&lt;***********************************************&gt;&gt;
FWRITE(FILNUM,OUTPUT,072,0);
IF &lt;&gt;
THEN BEGIN &lt;&lt;ERROR OCCURRED WHILE WRITING KSAM&gt;&gt;
MOVE MESSAGE:=&quot;ERROR OCCURRED WHILE WRITING KSAM FILE&quot;;
PRINT(MESSAGE,038,0);
FCHECK(FILNUM,ERRORCODE); &lt;&lt;GET ERROR NUMBER&gt;&gt;
FERRMSG(ERRORCODE,MESSAGE,LENGTH);&lt;&lt;CONVERT TO STRING&gt;&gt;
PRINT(MESSAGE,0LENGTH,0); &lt;&lt;PRINTOUT ERROR MESSAGE&gt;&gt;
TERMINATE;
END;
&lt;&lt;***********************************&gt;&gt;
&lt;&lt;* GO BACK TO GET ANOTHER RECORD *&gt;&gt;
&lt;&lt;***********************************&gt;&gt;
GO TO L1;
END;
Figure 4-14. FWRITE Example (continued)
USING KSAM FILES IN SPL PROGRAMS
4-111
FWRITEDIR
INTRINSIC NUMBER 8
Writes a specic logical record from the user's stack to a disc le.
Note
4-112
This intrinsic may not be used for KSAM les. If called for a le created as a
KSAM le, the intrinsic returns a CCL condition code.
USING KSAM FILES IN SPL PROGRAMS
FWRITELABEL
INTRINSIC NUMBER 20
Writes a user le label.
IV
LA
IV
FWRITELABEL(lenum,target,tcount,labelid);
IV
O-V
The FWRITE LABEL intrinsic writes a user-dened label onto a disc le. This intrinsic
overwrites old user labels.
PARAMETERS
lenum
target
tcount
labelid
integer by value (required)
A word identier specifying the le number of the le to which the label is to
be written.
logical array (required)
Contains the label to be written to the disc le.
integer by value (optional) An integer specifying the number of words to be
transferred from the array.
Default: 128 words.
integer by value (optional) An integer specifying the number of the label to be
written. The rst label is 0.
Default: A default value of 0 is assigned.
CONDITION CODES
CCE
CCG
CCL
Request granted.
Request denied because the calling process attempted to write a label beyond
the limit specied in FOPEN when the le was opened.
Request denied because an error occurred.
SPECIAL CONSIDERATIONS
Split stack calls permitted.
USING FWRITELABEL
You can write your own labels to a KSAM le with the FWRITELABEL intrinsic. Such
labels are useful to hold information related to the le but not part of it. For example, you
might use a label to contain the date and time of the last update to the le.
The number of labels that are allowed to be written to any le must be specied in the
userlabels parameter of the FOPEN intrinsic when the le was created. If an attempt is made
to write more labels than are specied for the le at creation, a CCG condition is returned.
USING KSAM FILES IN SPL PROGRAMS
4-113
In order to write labels, as with any other write request, the le must be opened for write
access. This means that the aoptions parameter of FOPEN must be set to one of the
following:
bits 12:4 = 0001
0010
0011
= 0100
= 0101
(octal
(octal
(octal
(octal
(octal
1)
2)
3)
4)
5)
\
|- write only access
/
&lt;------ input/output access
&lt;------ update access
Suppose le KDATA has been created as follows:
KFILNUM:=FOPEN(KDATA,%4004,4,,,,2);
/ |
|
/
|
|
/
|
|
new KSAM file,
| number of labels
ASCII coded
|
input/output access
Then a total of two labels, each with a maximum of 128 words, can be written to this le
with FWRITELABEL. To write a second label consisting of 60 words stored in the array
LABELBUF, use the following call:
FWRITELABEL(KFILNUM,LABELBUF,60,1);
Note that label numbering starts with zero, so the second label is identied by the number 1.
4-114
USING KSAM FILES IN SPL PROGRAMS
HP32208
INTRINSIC NUMBER 308
Returns current version, update, and x level of KSAM/3000.
D
version:=HP32208
The double word result returned by HP32208 contains the version number in ASCII, the
update number in binary, and the x-level number in binary of the KSAM/3000 version
currently in use.
FUNCTIONAL RETURN
version
Double word returned by HP32208 in the form:
0
7 8
15
-----------------------------------------| Version, in ASCII | Update #, in binary | word 1
-----------------------------------------| Fix-level #, in binary
| word 2
-----------------------------------------CONDITION CODES
Condition codes are not aected by execution of this intrinsic.
USING HP32208
You may call this intrinsic in order to get the current version, update, and x numbers of the
KSAM/3000 that is currently being used. The intrinsic FGETKEYINFO returns the version,
update, and x number of a KSAM le at the time the le is created (refer to words 16/17
of the ksamcontrol parameter, Table 4-4). The version, update, and x number of a KSAM
le at creation is also returned by the VERIFY command (refer to section II). You can call
HP32208 to get the KSAM version you are using in order to compare it with the version at
le creation of a le you are accessing.
Another reason for calling HP32208 is if you want to convert the version, update, and x
numbers to display values so they can be listed for documentation purposes.
USING KSAM FILES IN SPL PROGRAMS
4-115
5
USING KSAM FILES IN FORTRAN
PROGRAMS
OVERVIEW
The FORTRAN language has no input/output statements that can be used to access or create
a KSAM le directly. In order to reference KSAM les for input or output, the FORTRAN
progammer can choose between using MPE le system intrinsics (as described in section IV)
or using COBOL procedures (described in section III). He can create a KSAM le with the
KSAMUTIL utility program (described in section II) or with a call to the FOPEN intrinsic,
but not with a COBOL procedure.
If you are programming in FORTRAN, you can use the CALL statement to call any of the
COBOL procedures or any of the le system intrinsics that access KSAM les. In order to
determine which to use, you should refer to Table 3-1 for a list of the COBOL procedures that
provide KSAM interface and to Table 4-1 for a similar list of the le system intrinsics used for
KSAM interface. You will note that there are dierences in the functions provided.
Since the COBOL procedures are described in detail in section III and the le system
intrinsics are described in detail in section IV, these descriptions are not repeated here. This
section merely describes how to call the COBOL procedures or the le system intrinsics, and
provides examples of le creation and access along with brief commentaries.
USING KSAM FILES IN FORTRAN
PROGRAMS
5-1
CALLING FILE SYSTEM INTRINSICS
To the FORTRAN user, some of the le system intrinsics are treated as functions and others
as subroutines. A function is called implicitly by being referenced in a FORTRAN statement.
A subroutine is called explicitly with the FORTRAN CALL statement. A further distinction
is that a function can return a value to the calling program as a functional return, whereas a
subroutine can return values only through the parameters (arguments) specied in the call.
To illustrate, the FOPEN intrinsic is called as a function:
FILNUM=FOPEN(FILENAME,%4004L,%101L,072,DEVICE,KSAMPARAM,,10,,100J)
When this statement is executed, a value is returned to the integer variable FILNUM. Note
that the word CALL is not used. On the other hand, the FWRITE intrinsic is a subroutine
that must be called with the CALL statement:
CALL FWRITE(FILNUM,OUTPUT,072,%OL)
In order to determine quickly which is which, look up the intrinsic denition in section III;
if it has a functional return it should be called as a function, if not it should be called as a
subroutine.
MPE/3000 system intrinsics dier from FORTRAN/3000 language procedures: System
intrinsics can have optional parameters (arguments) whereas all parameters must be specied
in a call to a FORTRAN procedure. Another dierence is that parameters can be passed by
value to a system intrinsic but they must be passed by reference to a FORTRAN procedure.
To pass a parameter by value, use the literal value as a parameter (the parameter 072 in the
FOPEN call above); to pass by reference, the value is assigned to a parameter specied as a
variable or array name (FILENAME in the FOPEN call).
In order to take advantage of the capabilities of the system intrinsics, you should declare the
names of any intrinsics you plan to use in a SYSTEM INTRINSIC statement. This statement
must appear as one of the declaration statements that precede executable statements in a
FORTRAN/3000 program. For example, if you plan to call FOPEN, FCLOSE, FWRITE, and
FCHECK then these intrinsics should be declared in the statement:
SYSTEM INTRINSIC FOPEN,FCLOSE,FWRITE,FCHECK
Declared in this way, you can then omit optional parameters from the call and pass
parameters by value. If you do not declare the intrinsics in a SYSTEM INTRINSIC call, then
a function call such as that illustrated above for FOPEN would generate an error because it
omits some parameters and passes others by value.
5-2
USING KSAM FILES IN FORTRAN
PROGRAMS
CALLING COBOL PROCEDURES
Like the FORTRAN/3000 procedures, COBOL/3000 procedures do not allow you to omit
any parameters from the parameter list or to pass parameters by value. Thus no special
provisions need be made in order to call COBOL procedures from a FORTRAN program.
Since the COBOL procedure call diers in format from the FORTRAN procedure call, you
must translate from the COBOL format when calling a COBOL procedure in a FORTRAN
program. The translation is simple:
CALL &quot;CKOPEN&quot; USING letable, status. &lt;-------------- COBOL format
|
| |----|
|
| |
procedure
parameters
name
|
|
|
|
|
|
|
|
CALL CKOPEN (letable, status) &lt;--------------------- FORTRAN format
USING KSAM FILES IN FORTRAN
PROGRAMS
5-3
CREATING A KSAM FILE WITH A CALL TO FOPEN
A KSAM le can be created with the &gt;BUILD command of the KSAMUTIL program or it
can be created programmatically through a call to the le system intrinsic FOPEN. Figure 5-1
contains a FORTRAN program that uses the intrinsic FOPEN to create and open a Ele, and
the intrinsic FWRITE to write to the open le. It checks for errors with the FCHECK and
FERRMSG intrinsics, and closes the le with a call to FCLOSE.
The le is named FEXAMFIL and the associated key le is named FKEYFILE. Two keys are
used, a primary key of 20 characters starting in byte 1 of each data record, and an alternate
key of eight characters starting in byte 21 of the data record. The primary key contains a
name, the alternate key a phone number (refer to the input data in Figure 5-1).
DEFINING KSAMPARAM
The parameter ksamparam describes the key le in an array that contains many dierent
types of data (refer to Table 4-7). Because the data diers, the EQUIVALENCE statement
is used to equate the word-array KSAMPARAMA to the byte-array KSAMPARAM to
the double-word-array KSAMPARAMD. The keyle name is in the rst eight bytes and
this is equivalenced to the beginning of the array. The key device is dened in word 7 of
KSAMPARAMA, and the key descriptions begin in word 18.
The ag word (word 17) has the octal value 2. This means that only bit 14 is set to 1. The
agword denes the following options for the KSAM le:
bit 13 = 0
le is permanently saved in system directory
bit 14 = 1
record numbers in le start with 1, not zero
bit 15 = 0
records can be written in random order
If you compare this ksamparam denition to that in the SPL sample program (Figure 4-5),
you will note that the index values into the array dier. This is because, SPL arrays begin
numbering with zero whereas FORTRAN arrays begin numbering with one.
CALLING FOPEN
In the FOPEN call, the rst parameter is the KSAM le name that identies the data le
and the KSAM le as a whole. The second parameter species the le options (foptions )
parameter as octal 4004:
This denes the following le options:
5-4
USING KSAM FILES IN FORTRAN
PROGRAMS
New KSAM le
Allow :FILE
Fixed-Length Records
ASCII code
New le
(bit 4=1)
(bit 5=0)
(bits 8,9=00)
(bit 13=1)
(bits 14,15=00)
C***********************************************************************
C
*
C
EXAMPLE 1 *
*
C
BUILD A KSAM FILE *
*
C
*
************************************************************************
SYSTEM INTRINSIC FOPEN,FCLOSE,FWRITE,FERRMSG,FCHECK
INTEGER KSAMPARAMA(26)
INTEGER KEYDESCRIPTION(8)
CHARACTER KSAMPARAM(52)
INTEGER*4 KSAMPARAMD(13)
CHARACTER*8 KEYFILENAME
CHARACTER*17 KEYDEVICEE
EQUIVALENCE ((KSAMPARAMA,KSAMPARAM,KSAMPARAMD,KEYFILENAME)
EQUIVALENCE (KEYDEVICE,KSAMPARAMA(7))
EQUIVALENCE (KSAMPARAMA(18),KEYDESCRIPTION)
INTEGER FILNUM
INTEGER LENGTH
CHARACTER FILENAME*10
CHARACTER DEVICE*10
CHARACTER*72 INPUT
LOGICAL OUTPUT(36)
CHARACTER MESSAGE(72)
EQUIVALENCE MESSAGEW(36)
EQUIVALENCE (MESSAGE,MESSAGEW)
EQUIVALENCE (INPUT,OUTPUT)
DATA FILENAME/&quot;FEXAMFIL &quot;/ &lt;---------- lename
DATA DEVICE/&quot;DISC &quot;/ device
DATA KEYDEVICE/&quot;DISC &quot;/ device
DATA KEYFILENAME/&quot;FKEYFILE&quot;
DATA KSAMPARAMD(3)/100J/ &lt;-------------- le size
DATA KSAMPARAMA(16)/2/ &lt;---------------- agword
DATA KSAMPARAMA(17)/2/ &lt;--------------------- no. of keys
DATA KEYDESCRIPTION/%{4/1,12/20], 1,%[1/0,15/4],0, key
1
%[4/1,12/ 8],21,%[1/0,15/4], 0/ descriptions
C***********************************************************************
C
*
C
OPEN THE KSAM FILE
*
C
*
C***********************************************************************
FILNUM=FOPEN(FILENAME,*4004L,%101L,072,DEVICE,KSAMPARAM,M,
1
,10,,100J)
IF (FILNUM .EQ. 0) GO TO 400
Figure 5-1. Creating and Writing to KSAM File in FORTRAN
USING KSAM FILES IN FORTRAN
PROGRAMS
5-5
************************************************************************
C
*
C
READ DATA FROM $STDIN
*
C
*
************************************************************************
20 READ (5,300,END=30,ERR=40) INPUT
************************************************************************
C
*
C
WRITE THE DATA JUST READ TO THE KSAM FILE
*
C
*
C***********************************************************************
50 DISPLAY INPUT
CALL FWRITE(FILNUM,OUTPUT,072,%0L)
IF (.CC.) 70,20,70
Creating and Writing to KSAM File in FORTRAN
************************************************************************
C
*
C
ERROR MESSAGE
*
C
*
C***********************************************************************
70 STOP &quot;ERROR OCCURRED WHILE WRITING KSAM FILE&quot;
100 STOP &quot;END OF JOB&quot;
30 CALL FCLOSE(FILNUM,0,0)
IF (.CC.) 33,100,33
33 STOP &quot;CAN NOT CLOSE THE KSAM FILE&quot;
40 STOP &quot;ERROR OCCURRED WHILE READING INPUT&quot;
400 CALL FCHECK (FILNUM,IERRNUM)
CALL FERRMSG (IERRNUM,MESSAGEW,LENGTH)
WRITE(6,200) (MESSAGE(I),I=1,LENGTH)
STOP &quot;CAN NOT OPEN KSAM FILE&quot;
300 FORMAT(A72)
200 FORMAT(1X,72A1)
END
Output from Program Execution:
NOLAN
HOSODA
ECKSTEIN
CARDIN
PASBY
SEELY
ROBERT
TURNEWR
WHITE
WESTEP
STOP END OF JOP
JACK
JOE
LEO
RICK
LINDA
HENRY
GERRY
IVAN
GORDON
ELDER
923-4975
227-8214
287-5137
578-7018
295-1187
293-4220
259-5535
984-8498
398-0301
387-4598
967 REED AVE.
SUNNYVALE
1180 SAINT PETER CT.
LOS ALTOS
5303 STEVENS CREEK
SANTA CLARA
11100 WOLFE ROAD
CUPERTINO
TOWN &amp; CNTRY VILLAGE SAN JOSE
1144 LEBERTY ST.
EL CERRITO
12345 TELEGRAPH AVE. BERLELEY
22905 EMERSON ST.
OAKLAND
4350 ASHBY AVE.
BERKELEY
1256 KINGFISHER ST.
SUNNYVALE
The next parameter denes the access options (aoptions ) as the octal value 101:
5-6
USING KSAM FILES IN FORTRAN
PROGRAMS
This denes the following access options:
KSAM access expected
Exclusive access
No dynamic locking
Write only access
bit 3=0)
bits 8,9=01)
bit 10=0)
bits 12-15=0001)
A new le contains no information and is always opened for write access. Before accessing the
le for reading or update, it must be reopened. Such an open species that the le is an old
le in the foptions parameter. Depending on the type of access expected, aoptions can be
omitted or can specify a particular access type.
CREATING A KSAM FILE WITH KSAMUTIL
Instead of using the le system intrinsic FOPEN to create the KSAM le, you can create the
le with the &gt;BUILD command of the KSAMUTIL program. Once created, the le can be
opened with a call to FOPEN or CKOPEN. (Note that CKOPEN cannot be used to create a
le.)
The same le created in Figure 5-1 with FOPEN could be created in KSAMUTIL as follows:
:RUN KSAMUTIL.PUB.SYS
&gt;BUILD FEXAMFIL;REC= 072,10,F,ASCII;DEV=DISC;DISC=100;&amp;
KEYFILE =FKEYFILE;KEY=B,1,20;KEY=B,21,8;FIRSTREC=1
USING KSAM FILES IN FORTRAN
PROGRAMS
5-7
OPENING A KSAM FILE WITH A COBOL
PROCEDURE
The CKOPEN procedure requires two parameters: one is a table that identies the le and
species the type of access; the other is a two-byte item to which the status of the call is
returned. When calling this procedure from a FORTRAN program, the letable parameter
must be dened as an eight-word array containing both integer and character values.
Any item that is dened as COMPUTATIONAL or COMP in a COBOL program is declared
as an INTEGER in a FORTRAN program when it contains four bytes or less. Thus, the
following are equivalent:
02 FILENUM PIC S9(4) COMP. &lt;---------------------- COBOL description
INTEGER FILENUM &lt;--------------------------------- FORTRAN description
Any data items dened with a picture of X in COBOL would be declared as CHARACTER
items in FORTRAN. Thus, the following are equivalent:
02 FILENAME PIC X(8). &lt;------------------------- COBOL description
CHARACTER *8 FILENAME &lt;---------------------- FORTRAN description
Assuming that le FEXAMFIL has been created by the &gt;BUILD command, the FORTRAN
statements in Figure 5-2 open that le for output only and sequential access.
INTEGER FILETABLE(8)
CHARACTER FILETABLC(16)
INTEGER FILENUM
CHARACTER*8 FILENAME
CHARACTER*2 FSTAT
INTEGER IOTYPE
INTEGER AMODE
INTEGER PREVOP
EQUIVALENCE (IFSTAT,FSTAT)
EQUIVALENCE (FILETABLE,FILETABLC,FILENUM)
EQUIVALENCE (FILETABLC(3),FILENAME)
EQUIVALENCE (FILETABLE(6),IOTYPE)
EQUIVALENCE (FILETABLE(7),AMODE)
EQUIVALENCE (FILETABLE(8),PREVOP)
DATA FILENAME/&quot;FEXAMFIL&quot;/,PREVOP/0/
C**********************************************************************
C OPEN KSAM FILE FOR SEQUENTIAL INPUT
*
C**********************************************************************
IOTYPE=1
I/O type is output only
AMODE=0
access mode is sequential
CALL CKOPEN(FILETABLE,IFSTAT)
Figure 5-2. Opening KSAM File with CKOPEN
5-8
USING KSAM FILES IN FORTRAN
PROGRAMS
WRITING TO A KSAM FILE
Once a KSAM le has been created and opened for output access, you can write to the le
with a call to FWRITE or a call to CKWRITE. You may choose to write records in primary
key sequence and have that sequence checked. To do this, you can open the le for sequential
access with CKOPEN or else call FOPEN with bit 13 of the agword in ksamparam set to 1.
If the sequence in which records are written doesn't matter, you can open the le for random
access in COBOL or open the le by calling FOPEN with bit 13 of the ksamparam agword
cleared to zero.
The example in Figure 5-1 uses FWRITE to write records to the KSAM le in the order in
which they are read from the standard input device; they are not written in primary key
order.
Since duplicate primary keys are never allowed by the COBOL KSAM procedures, you should
use the le system intrinsics if you want to allow duplicate primary keys. Duplicate alternate
keys are allowed by both the le system and COBOL if so specied when the le was created.
USING KSAM FILES IN FORTRAN
PROGRAMS
5-9
READING A KSAM FILE IN KEY ORDER
PRIMARY KEY SEQUENCE
Reading a le in primary key order requires no other preparation than to open the le (le
system) or to open the le for sequential input (COBOL). In the le system, sequential logical
read is the default and the aoptions parameter can be omitted from the FOPEN call. In
a COBOL procedure, input type and sequential access are indicated by zero values in the
appropriate words of the letable table.
Once opened for input, the le system FREAD intrinsic or the COBOL CKREAD procedure
can be called to read the le in sequence by primary key.
ALTERNATE KEY SEQUENCE
To read a le in sequence by an alternate key, that alternate key must be specied in a
call prior to the call to a read procedure or intrinsic. In COBOL, you would use a call to
CKSTART; with the le system intrinsics you would use FFINDBYKEY.
The example in Figure 5-3 illustrates use of the le system intrinsics FREAD and
FFINDBYKEY to read a KSAM le in sequence rst by primary key and then by alternate
key.
RANDOM ORDER
A particular record in the le can be selected for access according to the value of a key
eld in the record. This can be a primary or alternate key eld. In COBOL, a call to
CKREADBYKEY reads a record specied by the key value parameters. The le system uses
the intrinsic FREADBYKEY for the same purpose. The main dierence here is that the le
must be opened for random access before calling the COBOL procedure; no distinction is
made by the MPE le system between a le opened for sequential access and one opened for
random access.
5-10
USING KSAM FILES IN FORTRAN
PROGRAMS
C*****************************************************
C
EXAMPL2
*
C
READ KSAM FILE SEQUENTIALLY
*
C*****************************************************
SYSTEM INTRINSIC FOPEN,FCLOSE,FWRITE,FERRMSG,FCHECK
SYSTEM INTRINSIC FWREAD,FFINDBYKEY
INTEGER FILNUM
CHARACTER FILENAME*10
CHARACTER OUTPUT*72
CHARACTER MESSAGE(72)
LOGICAL INPUT (36)
LOGICAL MESSAGEW(36)
EQUIVALENCE (MESSAGE,MESSAGEW)
EQUIVALLNCE (OUTPUT,INPUT)
CHARACTER KEYVAL*8
DATA FILENAME/&quot;FEXAMFIL &quot; /
DATA KEYVAL/&quot;000-0000&quot;/
C*****************************************************
C
OPEN KSAM FILE FOR INPUT
*
C*****************************************************
FILNUM=FOPEN(FILENAME,%7L)
IF (FILNUM .EQ. 0) GO TO 200
C*****************************************************
C
READ DATA FROM FILE IN
*
C
SEQUENTIAL ORDER
*
C*****************************************************
DISPLAY &quot;PRINT RECORDS IN NAME ORDER&quot;
20 ILEN=FREAD(FILNUM,TNPUT, 072)
IF (.CC.) 300,30,35
30 DISPLAY OUTPUT
GO TO 20
C*****************************************************
C
READ IN SEQUENCE BY ALTERNATE KEY
*
C*****************************************************
35 DISPLAY &quot;PRINT RECORDS IN PHONE # ORDER&quot;
CALL FFINDBYKEY(FILNUM,KEYVAL,21,8,2)
IF (.CC.) 400,40,400
40 ILEN=FREAD(FILNUM,INPUT, 072)
IF (.CC.) 500,45,500
45 DISPLAY OUTPUT
GO TO 40
C*****************************************************
C
CLOSE FILE
*
C*****************************************************
50 CALL FCLOSE(FILNUM,0,0)
IF (.CC.) 600,55,600
55 STOP &quot;END OF JOB&quot;
Figure 5-3. Reading KSAM File in Key Sequence Using FORTRAN
USING KSAM FILES IN FORTRAN
PROGRAMS
5-11
C*****************************************************
C
ERROR MESSAGES
*
C*****************************************************
200 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot;CANNOT OPEN KSAM FILE&quot;
300 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
400 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRMUN,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot; ERROR OCCURRED WHILE USING FIFINDBYKEY&quot;
500 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot;ERROR OCCURRED READING BY ALTERNATE KEY&quot;
600 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot;CANNOT CLOSE FILE&quot;
250 FORMAT(1X,72A1)
END
Output from Program Execution:
PRINT RECORDS IN
CARDIN
RICK
ECKSTEIN LEO
HOSODA
JOE
NOLAN
JACK
PASBY
LINDA
ROBERT
GERRY
SEELY
HENRY
TURNEWR
IVAN
WESTER
ELDER
WHITE
GORDON
PRINT RECORDS IN
HOSODA
JOE
ROBERT
GERRY
WESTER
ELDER
ECKSTEIN LEO
SEELY
HENRY
PASBY
LINDA
WHITE
GORDON
CAPDIN
RICK
NOLAN
JACK
TURNEWR
IVAN
STOP END OF JOB
NAME ORDER
578-7018 11100 WOLFE ROAD
287-5137 5303 STEVENS CREEK
227-6214 1180 SAINT PETER CT.
923-4975 967 REED AVE.
295-1187 TOWN &amp; CNTRY VILLAGE
259-5535 12345 TELEGRAPH AVE.
293-4220 1144 LEBERTY ST. EL
984-8498 22905 EMERSON ST.
287-4598 1256 KINGFISHER ST.
398-0301 4350 ASHBY AVE.
PHONE # ORDER
227-8214 1180 SAINT PETER CT.
259-5535 12345 TELEGRAPH AVE.
287-4598 1256 KINGFISHER ST.
287-5l37 5303 STEVENS CREEK
293-4220 1144 LEBERTY ST.
295-1187 TOWN &amp; CNTRY VILLAGE
398-0301 4350 ASHBY AVE.
578-7018 11100 WOLFE ROAD
923-4975 967 REED AVE.
984-8498 22905 EMERSON ST.
CUPERTINO
SANTA CLARA
LOS ALTOS
SUNNYVALE
SAN JOSE
BERKELEY
CERRITO
OAKLAND
SUNNYVALE
BERKELEY
LOS ALTOS
BERKELEY
SUNNYVALE
SANTA CLARA
EL CERRITO
SAN JOSE
BERKELEY
CUPERTINO
SUNNYVALE
OAKLAND
Figure 5-3. Reading KSAM File in Key Sequence Using FORTRAN (continued)
5-12
USING KSAM FILES IN FORTRAN
PROGRAMS
READING A KSAM FILE IN CHRONOLOGICAL
ORDER
The order in which records are physically written to a data le is called chronological order.
This order is not necessarily the same as a sequence by key value although it may be. In
particular, if the records were written by a COBOL procedure to a le opened for sequential
access, then the chronological sequence and the primary key sequence are the same. If,
however, these orders dier, then the le system provides an intrinsic that allows you to read
a KSAM le in chronological order.
Figure 5-4 is a program that uses the intrinsic FREADC to read the records in the order they
were stored in the le.
Other le system intrinsics allow you to position the le to a particular record number
in chronological order (FPOINT), to retrieve the current chronological record number
(FGETINFO), and to read a record located by its chronological record number (FREADDIR).
The COBOL procedures for KSAM interface do not provide the means to access records by
chronological record number.
C*************************************************************
C
EXAMPL3
*
C
READ KSAM FILE CHRONOLOGICALLY
*
C ************************************************************
SYSTEM INTRINSIC F0PEN,FCLOSE,FERRMSG,FCHECK
SYSTEM INTRINSIC FREADC
INTEGER FILNUM
CHARACTER FILENAME*10
CHARACTER OUTPUT*72
CHARACTER MESSAGE(72)
LOGICAL INPUT (36)
LOGICAL MESSAGEW(36)
EQUIVALENCE (MESSAGE,MESSAGEW)
EQUIVALENCE (OUTPUT,INPUT)
DATA FILENAME/&quot;FEXAMFIL &quot;/
C**************************************************************
C
OPEN KSAM FILE FOR INPUT
*
C**************************************************************
FILENUM=FOPEN(FILNAME,%7L)
IF (FILNUM .EQ. 0) GO TO 200
C**************************************************************
C
READ DATA FROM FlLE IN
*
C
CHRONOLOGICAL ORDER
*
C**************************************************************
DISPLAY &quot;PRINT RECORDS IN CHRONOLOGICAL ORDER&quot;
20 ILEN=FREADC(FILNUM,INPUT,072)
IF (.CC.) 300,30,50
30 DISPLAY OUTPUT
GO TO 20
C**************************************************************
C
CLOSE FILE
*
C**************************************************************
50 CALL FCLOSE(FILNUM,0,0)
IF (.CC.) 600,55,600
55 STOP &quot;END OF JOB&quot;
Figure 5-4. Reading KSAM File in Chronological Sequence Using FORTRAN
USING KSAM FILES IN FORTRAN
PROGRAMS
5-13
C**************************************************************
C
ERROR MESSAGES
*
C**************************************************************
200 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot;CANNOT OPEN KSAM FILE&quot;
300 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot;ERROR OCCURRED READING IN CHRONOLOGICAL ORDER&quot;
600 CALL FCHECK(FILNUM,IERRNUM)
CALL FERRMSG(IERRNUM,MESSAGEW,LENGTH)
WRITE(6,250)(MESSAGE(I),I=1,LENGTH)
STOP &quot;CANNOT CLOSE FILE&quot;
250 FORMAT(IX,72A1)
END
Output from Program Execution:
PRINT RECORDS IN
NOLAN
JACK
HOSODA
JOE
ECKSTEIN LEO
CARDIN
RICK
PASBY
LINDA
SEELY
HENRY
ROBERT
GERRY
TURNEWR IVAN
WHITE
GORDON
WEBSTER ELDER
STOP END OF JOB
CHRONOLOGICAL ORDER
923-4975 967 REED AVE,
227-8214 1180 SAINT PETER CT.
287-5137 5303 STEVE'S CREEK
578-7018 11100 WOLFE ROAD
295-1187 TOWN &amp; CNTRY VILLAGE
293-4220 1144 LEBERTY ST.
259-5535 12345 TELEGRAPH AVE.
984-8498 22905 EMERSON ST.
398-0301 4350 ASHBY AVE.
287-4598 1256, KINGFIDHER ST.
SUNNYVALE
LOS ALTOS
SANATA CLARA
CUPERTINO
SAN JOSE
EL CERRITO
BERKELEY
OAKLAND
BERKELEY
SUNNYVALE
Figure 5-4. Reading KSAM File in Chronological Sequence Using FORTRAN (continued)
5-14
USING KSAM FILES IN FORTRAN
PROGRAMS
6
USING KSAM FILES IN
BASIC PROGRAMS
OVERVIEW
KSAM les are accessed from BASIC programs through calls to a set of input-output
procedures. These procedures allow you to open, write records to, read records from, update
and delete records, position, lock, unlock, and close KSAM les. (Refer to Table 6-1 for a list
of the procedures and their associated functions.)
A KSAM le must already exist before it can be accessed from a BASIC program. It is
usually created with the KSAMUTIL program BUILD command. (Refer to section II for a
description of BUILD.) The BASIC procedures for accessing KSAM les do not provide a
means to create a KSAM le.
Note
Note
The BASIC procedures to access KSAM les perform input-output activities
dierently from the BASIC input-output commands. The KSAM procedures
read and write records in their entirety. Once part of a record has been read
or written by one of the KSAM le access procedures, the entire record has, in
actuality, been read or written. A subsequent call will access another record.
Character substrings are expressions when used in the BASIC KSAM
procedures. As such, no values can be returned to them. A copy is passed.
USING KSAM FILES IN
BASIC PROGRAMS
6-1
CALLING A KSAM PROCEDURE
The KSAM interface procedures are called from a BASIC program with a CALL statement of
the following general form:
statement label CALL procedure name (lenumber, status [,parameterlist])
Where
statement label
procedure
name
lenumber
status
parameterlist
is the number of the statement in the program.
identies the KSAM access procedure to which control is transferred. (Refer
to Table 6-1 for a complete list of the procedure names.)
is a numeric variable whose value identies an open KSAM le. This
parameter must be present. Its value is assigned by KSAM/3000 when the le
is opened and must not be changed until the le is closed.
is a 4-character string variable to which a code is returned that indicates
whether the current operation was successful or not, and if not, the reason for
failure.
is a set of one or more parameters that, if present, further dene input-output
operations on this le.
The rst two parameters, lenumber and status are included in every KSAM procedure
call, except BKERROR and BKVERSION. The parameters in parameterlist depend on the
procedure in which they are used. Some parameterlist parameters are optional and, if omitted,
default values are assigned by KSAM. Such parameters are indicated by brackets in the
procedure call format. The required parameters lenumber and status are both variables,
the rst numeric, the second string. Other parameters are either variables or expressions.
Expressions being either variables, constants, or a combination of both. The data type of the
parameter depends on its denition in the procedure. The procedure call formats specify the
data type of each parameter.
Depending on the procedure, certain variables can be assigned values as a result of executing
the procedure. The procedure itself is never assigned a value (unlike a function, which may be
assigned a value).
Refer to Table 6-1 for a complete list of the KSAM interface procedures that can be called
from a BASIC program.
OPTIONAL PARAMETERS
When parameters in parameterlist are optional, those parameters are surrounded by brackets,
In a series of optional parameters, the enclosing brackets are nested. For example:
CALL name (lenum,status[,param1[,param2[,param3]]])
This notation tells you that parameters can be omitted only from the end of the optional list;
parameters cannot be omitted from the middle or beginning of the list. For example, if you
want to specify param3 , you must also specify the preceding parameters, param1 and param2 ;
if you specify param2 , you can omit the following parameter param3 , but not the preceding
param1 .
6-2
USING KSAM FILES IN
BASIC PROGRAMS
Table 6-1. KSAM Procedures for BASIC Interface
PROCEDURE
NAME
PARAMETERS
FUNCTION
PAGE
BKCLOSE
lenum,
status
Terminates processing of KSAM le identied by
lenum .
6-8
BKDELETE
lenum,
status
Logically removes record from KSAM le; the
record to be deleted is the record at which the
logical record pointer is currently positioned.
6-10
BKERROR
status,
message
Converts numeric value returned in status
parameter to character string message .
6-12
BKLOCK
lenum,
status
[,condtion ]
Dynamically locks KSAM le during shared
access, conditionally depending on condition .
6-14
BKOPEN
lenum ,
status ,
lename
[,access
[,dynamic lock
[,exclusive
[,sequence ]]]]
Initiates processing of le identied by lenum ,
named by lename . Type of access, whether
dynamic locking is allowed, whether access is
exclusive, and whether primary key sequence is
checked are options of BKOPEN.
6-16
BKREAD
lenum,
status
[,parameter- list ]
Reads data from current sequential record of le
identied by lenum into variables named in
parameterlist .
6-22
BKREADBYKEY lenum,
status,
keyvalue,
keylocation,
parameterlist
Reads data from a record identied by keyvalue in 6-26
the key specied by keylocation of the le
identied by lenum into variables named in
parameterlist .
BKREWRITE
lenum,
status,
parameterlist
Writes data from parameterlist to record at which 6-29
pointer is positioned in le identied by lenum.
BKSTART
lenum,
status
[,keyvalue
[,keylocation
[,relation ]]]
Positions le identied by lenum in preparation 6-32
for a sequential read to the rst record with a key
in keylocation whose value bears the specied
relation to keyvalue .
BKUNLOCK
lenum,
status
Unlocks le identied by lenum that has been
previously locked by BKLOCK.
6-36
BKVERSION
status,
message
Identies version of KSAM/3000 currently being
used returns version number in message .
6-38
BKWRITE
lenum,
status,
parameterlist
Writes data from parameterlist to record in le
identied by lenum .
6-39
USING KSAM FILES IN
BASIC PROGRAMS
6-3
STATUS PARAMETER
The status parameter is a four-character string variable to which the status of the
input-output operation is returned. It is the second parameter in every KSAM procedure
call except BKERROR, in which it is the rst parameter. The rst character of the status
string determines its general type. The other three characters supply specic codes to further
dene the status. The operation of a called procedure is successful only if the rst character
returned in status is zero. Other values returned to status indicate the reason an operation
was not successful. You can convert any status value to a printable message by calling
BKERROR. (Refer to Table 6-2 for possible status values).
Table 6-2. Values Returned to
FIRST CHARACTER
status
Parameter
REMAINING CHARACTERS
\0&quot; successful completion
\0&quot; no further information
\2&quot; duplicate key value
\1&quot; at end or beginning of le
\0&quot; no further information
\2&quot; invalid key
\1&quot; sequence error
\2&quot; duplicate key error
\3&quot; no record found
\4&quot; boundary violation
\7&quot; request denied
\1&quot; le already locked
\8&quot; invalid call
\1&quot; invalid number of parameters
\2&quot; invalid parameter
\3&quot; insucient space for data in
parameterlist
\9&quot; le system error
\0&quot; through \255&quot;
corresponding to le system error codes
(Refer to complete list in Appendix A.)
Combining the two parts of the status code, the following values may be returned to the
status parameter:
if status=\00&quot; Successful completion |; The current input-output operation was completed
successfully; no duplicate keys read or written.
=\02&quot;
Successful completion; Duplicate key |;
In a call to BKREAD or BKREADBYKEY, the current key has the same
value as the equivalent key in the next sequential record; duplicate keys are
allowed for the key.
In a call to BKWRITE or BKREWRITE, the record just written created a
duplicate key value for at least one key for which duplicates are allowed.
=\10&quot;
At end condition |; A sequential read was attempted with BKREAD and
there was no next logical record in ascending sequence according to the
primary key value or the current altemate key value. Or an attempt was
made by BKSTART or BKREADBYKEY to position to a record whose key
value was less than the lowest key value or higher than the highest key value.
6-4
USING KSAM FILES IN
BASIC PROGRAMS
Invalid key; Sequence error |;
In a call to BKWRITE for a le opened with sequence checking, the record
being written contains a primary key that is less than a key in a previously
written record.
In a call to BKREWRITE, the primary key value was changed in the
program since a successful execution of BKREAD dened the record to be
rewritten.
=\22&quot;
Invalid key; Duplicate key error |; An attempt was made to write or rewrite
a record with BKWRITE or BKREWRITE and the record would create a
duplicate key value in a key for which duplicates are not allowed.
=\23&quot;
Invalid key; No record found |; An attempt was made to locate a record by
a key value with BKSTART or BKREADBYKEY and the record cannot be
found.
=\24&quot;
Invalid key; Boundary violation |; An attempt was made with BKWRITE to
write beyond the externally dened boundaries of the le; that is, to write
past the end-of-le.
=\71&quot;
Request denied; File already locked |; An attempt was made to lock a le with
BKLOCK and the le is already locked.
=\81&quot;
Invalid call; Invalid number of parameters |; Too many or too few parameters
were specied in the procedure call just made.
=\82&quot;
Invalid call; Invalid parameter |; The specied parameter is not the correct
type. For example, a string variable was selected where only a numeric
variable or expression is allowed.
=\83&quot;
Invalid call; Insucient internal buer space |; The data specied in the
parameterlist to be read or written will not t into the congured internal
buer space. You may need to have certain operating system parameters
re-valued.
=\9xxx &quot;
File system error |; An MPE le system error occurred for which the
three-character value, xxx is the error code. (Refer to Table A-1 for a list of
these codes.) You can call procedure BKERROR to convert the error code
returned here to a printable message.
The value of status can be tested as a whole, or the rst character can be tested separately
from the remaining characters. For example:
10 DIM S$(4) &lt;-------- dimension status string S$
=\21&quot;
.
. /-------------------- test rst character only
50 IF S$(1;1) = &quot;0&quot; THEN PRINT &quot;SUCCESS&quot;
60 ELSE PRINT &quot;ERRORCODE=&quot;;S$ &lt;--------- print entire string
.
.
. /---------------------------- test rst character
100 IF S$(1;1)= &quot;9&quot; THEN DO
110 PRINT &quot;FILE ERROR=&quot;;S$(2)
120 DOEND \--------------------- print remaining characters
USING KSAM FILES IN
BASIC PROGRAMS
6-5
.
.
.
200
210
220
300
/-------------------- test entire string
IFS$ = &quot;22&quot; THEN DO
PRINT &quot;DUPLICATE KEY ERROR&quot;
DOEND
IF S$(2)= &quot;2&quot; THEN PRINT &quot;DUPLICATE KEY&quot;
\------------------------ test only remaining characters
For any status value, you can call the BKERROR procedure and a message is returned that
gives the meaning of the status code. You can then print this message rather than writing
your own.
KSAM LOGICAL RECORD POINTER
Many of the KSAM procedures use a logical record pointer to indicate the current record in
the le. This pointer points to a key value in the key le that identies the current record
in the data le. The particular key used, if the le has more than one key, is the key last
specied in the current or a previous procedure call; by default it is the primary key.
Procedures that use pointers are either pointer-dependent or pointer-independent .
Pointer-dependent procedures expect the pointer to be positioned at a particular record
in order to execute properly. Pointer-independent procedures, on the other hand, execute
regardless of where the pointer is positioned and, in most cases, they position the pointer.
(Refer to Table 6-3 for a summary of those procedures that either position the pointer or are
dependent on that position.)
Table 6-3. Positioning the Logical Record Pointer
Procedure
Name
PointerDependent
Position of Pointer After
Execution of Procedure
BKSTART
NO
Points to key whose value was specied in call.
BKREADBYKEY
NO
Points to key whose value was specied in call.
BKWRITE
NO
Points to key whose value is next in ascending key
sequence to key value in record just written.
BKREAD
YES
Pointer remains positioned to key value for record just
read; unless next call is to BKREAD, or to BKREWRITE
followed by BKREAD, in which case, the pointer is moved
to the next record in key sequence before the read.
BKDELETE
YES
Points to next key value in ascending sequence following
key value in record just deleted.
BKREWRITE
YES
Pointer remains positioned to key value for record just
modied; unless any key value in record was changed, in
which case, it points to next key in ascending sequence
after the key in the modied record.
6-6
USING KSAM FILES IN
BASIC PROGRAMS
BASIC procedures do not access a KSAM le in chronological sequence or by
record number; they ignore the chronological pointer.
Note
SHARED ACCESS
Particular care must be taken when using the logical record pointer during shared access.
Since the record pointer is maintained in a separate control block for each open le, one user
may cause the record pointer to be inaccurate without other users being aware of it. To
avoid this problem, you should always lock the le in a shared environment before calling
any procedure that sets the pointer and leave the le locked until all procedures that depend
on that pointer have been executed. Thus, if you want to read the le sequentially, delete a
record, or modify a record, you should lock the le, call a procedure that sets the pointer
(such as BKSTART), and then call BKREAD, BKDELETE, or BKREWRITE. When the
operation is complete, you can then unlock the le to give other users access to it.
BKCLOSE
A call to BKCLOSE terminates le processing for the specied le.
CALL BKCLOSE (lenum,status)
When processing is completed, a KSAM le should be closed with a call to BKCLOSE. No
further processing is allowed on the le until a BKOPEN procedure call re-opens the le.
BKCLOSE can be executed only for a le that is open.
PARAMETERS
lenum
status
A numeric variable containing the le number that identies the le; this
number was returned by the last call to BKOPEN. It should not be altered
until the le is closed with a successfull call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the le was successfully closed and if not, why not. The
rst character is set to \0&quot; if the close is successful, to another value if not.
(Refer to the Status Parameter discussion earlier in this section.) (Required
parameter )
USING BKCLOSE
After calling BKCLOSE, you should check the status parameter to determine if the le was
closed successfully. A successfully closed le is no longer available for processing until it is
re-opened. Note that a KSAM le can be closed and then re-opened in order to specify a
dierent access mode or type of processing.
The BKCLOSE procedure does not remove the le from the system. To do this, you should
use the PURGE command of the KSAMUTIL program.
USING KSAM FILES IN
BASIC PROGRAMS
6-7
The example in Figure 6-1, closes a le identied by the lenumber in F. It then checks
the status and prints a message if the status shows any code except the zero for successful
completion.
3610
3620
3630
3640
3650
3660
3670
3680
3690
3700
3710
3720
3730
3740
3750
376O
3770
3780
REM ********************************************************
REM * CLOSE A KSAM FILE *
REM ********************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM DEFINED BY A CALL TO BKOPEN
REM
CALL BKCLOSE(F,S$)
REM
REM NOW DETERMINE WHETHER THTS CALL SUCCEEDED
REM
IF S$[1,1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO CLOSE &quot;;N$;&quot; ERROR &quot;;S$[1;1];&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
DOEND
Figure 6-1. Closing a KSAM File with BKCLOSE
BKDELETE
Logically deletes a record from a KSAM le.
CALL BKDELETE (lenum, status)
A call to BKDELETE logically deletes the record referenced by the logical record pointer.
A logically deleted record is marked by two delete characters (ASCII code 255) in the rst
two character positions in the record. The deletion characters indicate that the record is
inaccessible, although it is not physically removed from the le. The connection between a
data record marked for deletion and the key le is severed.
When a le with deleted records is copied by FCOPY to a new KSAM le, records marked for
deletion by BKDELETE are not copied. This use of FCOPY provides a means to compact a
le in which many records have been marked for deletion but physically use space in the le.
To use BKDELETE, the le must be open in the access mode that allows update. If access is
shared, the le must also be opened with dynamic locking allowed (lock =1), and the le must
be locked by BKLOCK before records are deleted.
6-8
USING KSAM FILES IN
BASIC PROGRAMS
PARAMETERS
lenum
status
A numeric variable containing the le number that identies the le; this
number was returned by the last call to BKOPEN. It should not be altered
unless the le is closed with a successful call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKREWRITE was successful and if not, why not.
The rst character is set to zero if the call succeeds, to another value if not.
(Refer to Status Parameter discussion earlier in this section.)
USING BKDELETE
Before calling BKDELETE, you can read the record to be deleted from the KSAM le into
the BASIC program. Using either BKREAD or BKREADBYKEY, read record into variables
named in the read call. When BKDELETE is successfully executed, the rst two characters of
the record just read are marked for deletion. Then the record is written back to the le. Any
connections between the record and key entries in the key le are severed. The associated key
entries are physically deleted from the key le although the data record remains in the data
le. Data space is not reused in order to maintain the chronological order of the le. Because
BKDELETE requires that the record be both read and written, you must open the le for
update (access = 4) before calling this procedure.
After calling BKDELETE, you should check the status parameter to make sure that the delete
was successful.
In the event that you deleted a record in error, you can recover the information in the data
record by copying the data le with the NOKSAM option of FCOPY. You can copy the data
le to another non-KSAM le or to the list device. With this FCOPY option, the deleted
records as well as active records are copied. In order to make use of this recovery procedure,
you may want to leave the rst two characters of any KSAM record empty of data. In
particular, you should not specify keys in those two characters.
FCOPY can also be used to permanently remove any records that were logically deleted with
BKDELETE. When you use FCOPY to copy your KSAM le to a newly created KSAM le,
only active records are copied. Records marked for deletion are dropped from the data le
during the copy. The new le is more compact, particularly if many records had been deleted
from the old le. (Refer to FCOPY description in section II for more information.)
Shared Access
When access is shared, the call that positions the pointer to the record to be deleted should
be included in the same pair of BKLOCK/BKUNLOCK calls as the call to BKDELETE. This
insures that no other user alters the record position between the call that locates the record
and the call that deletes it. (Refer to Table 6-3 for a list of the procedures that position the
pointer and those that depend on the pointer.)
Figure 6-2 contains an example illustrating the logical deletion of a record from a KSAM le.
USING KSAM FILES IN
BASIC PROGRAMS
6-9
3240
3250
3260
3270
3280
3290
3295
3300
3305
3310
3320
3330
3340
3350
3360
3370
3380
3390
3400
3410
3420
3430
3435
3440
3450
3460
3470
3480
3490
3500
3510
3520
3530
3535
3540
3550
3560
3570
3575
3576
3577
3580
3590
REM ******************************************************
REM * REMOVE A RECORD FROM A KSAM FILE *
REM ******************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE OPENED BY A CALL TO BKOPEN
REM NOTE THAT FOR BKDELETE, BKOPEN ACCESS MODE MUST = 4 FOR UPDATE
REM
REM THE RECORD TO BE DELETED MUST FIRST BE READ...
REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ
REM AND DELETED CONTAINS THE SAME INFORMATION THAT WAS
REM WRITTEN IN THE BKWRITE EXAMPLE.
REM
CALL BKREAD(F,S$,B1$,B2$,A5[*],A3[*],A2[*])
REM
REM NOW DETERMINE WHETHER THF CALL WAS SUCCESSFUL
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO READ &quot;;N$&quot; ERROR &quot;;S$[1;1];&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM
CALL BKDELETE(F,S$)
REM
REM NOW DETERMINE WHETHER THIS CALL SUCCEEDED
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO DELETE RECORD FROM &quot;;N$;
PRINT &quot;ERROR &quot;;S$[1;1];&quot;DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
PRINT &quot;DELETED RECORD CONTAINS &quot;;B1$;B2$;
MAT PRINT A5
MAT PRINT A3,A2
REM
REM THE PROGRAM CONTINUES
Figure 6-2. Deleting a Record With BKDELETE
6-10
USING KSAM FILES IN
BASIC PROGRAMS
BKERROR
A call to BKERROR returns a message corresponding to the status value.
CALL BKERROR (status, message)
Call this procedure in order to get a printable string of characters that describes the condition
that corresponds to the value of the status parameter. The string of ASCII characters
returned in message can be printed as an error message.
PARAMETERS
status
message
is a four-character string variable to which is returned a numeric value in
printable form following execution of any of the procedures described in this
section. The value in status is used to derive the text in message . (Required
parameter )
is a string variable which will contain the text describing the error whose code
has been returned to status . This parameter should be dimensioned to at
least 72 characters in length. If the message length exceeds the dimensioned
length of message , a truncated text is provided. (Required parameter )
USING BKERROR
The following example illustrates the use of BKERROR. Two strings are dimensioned for
message ; one (M$) is suciently long, the other (N$) causes truncation of the message.
Assume that the status code in S$ is the value \22&quot;.
10
20
30
40
50
60
..
.
100
110
120
130
RUN
DIM S$(4),M$(72),N$(24)
REM..S$ IS THE STATUS STRING
REM..M$ IS A SUFFICIENTLY LARGE STRING
REM..N$ IS TOO SMALL FOR THE MESSAGE
REM..ASSUME S$ CONTAINS THE VALUE &quot;22&quot;
REM..
CALL BKERROR (S$,MS)
PRINT &quot;ERROR&quot;;S$(1;1);&quot;DETAIL&quot;;S$(2);&quot;&quot;;M$
CALL BKERROR (S$,M$)
PRINT &quot;ERROR &quot;S$(1;1);&quot;DETAIL&quot;;S$(2);&quot;&quot;;N$
/----------------- full message
/-------------------------------------\
ERROR 2 DETAIL 2 INVALID KEY VALUE. DUPLICATED KEY VALUE
ERROR 2 DETAIL 2 INVALID KEY VALUE. DUPL
\----------------------/
\---------------- truncated message
In another example, BKERROR is called to retrieve the message corresponding to the MPE
le system error code returned when the rst character of status is \9&quot;.
10
.. DIM S$(4),M$(72)
.
50 IF S$(1;1)=&quot;9&quot; THEN DO
USING KSAM FILES IN
BASIC PROGRAMS
6-11
60 CALL BKERROR(S$,M$)
70 PRINT&quot;FILE ERROR&quot;;S$(2);&quot;MEANS&quot;;M$
80 DOEND
Suppose the value returned in status is \9172&quot;, then the routine above prints the following
message when the program is run:
FILE ERROR 172 MEANS KEY NOT FOUND; NO SUCH KEY VALUE
A list of the MPE le system error codes and their meaning is contained in Table A-1 of
appendix A.
BKLOCK
Dynamically locks KSAM le during shared access.
CALL BKLOCK(lenum,status[,condition])
When more than one user accesses the same le, BKLOCK can be used to make access to the
le exclusive for one user while he writes to or updates the le. In order to use BKLOCK, the
le must be opened with dynamic locking allowed by all users who are sharing the le. When
nished with the changes that required exclusive access, the user who has locked the le with
BKLOCK should unlock it with BKUNLOCK.
Note that a le opened for shared access must be locked by BKLOCK before
the le can be modied by BKWRITE, BKREWRITE, or BKDELETE.
Note
PARAMETERS
lenum
status
condition
A numeric variable containing the le number that identies the le; this
number was returned to lenum by the last call to BKOPEN. It should
not be altered unless the le is successfully closed by BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKLOCK was successful and if not, why not. The
rst character is set to zero when the call succeeds, to another value if it fails.
(Refer to the Status Parameter discussion earlier in this section.) (Required
parameter )
A numeric expression whose value determines the action taken if the le is
locked by another user when BKLOCK is executed. If the value of condition
is:
zero-locking is unconditional ; if the le cannot be locked immediately because
another user has locked it, your program suspends execution until the le can
be locked. (default value )
non-zero-locking is conditional ; if the le is already locked, control returns
immediately to your program with status set to \71&quot;.
(Optional parameter ) Default: If omitted, locking is unconditional .
6-12
USING KSAM FILES IN
BASIC PROGRAMS
USING BKLOCK
In order to call BKLOCK, the le must be opened with dynamic locking allowed. That is, the
parameter lock in the BKOPEN procedure must be set to 1. Also, since dynamic locking is
useful only when access is shared, probably the le will have been opened with the exclusive
parameter in BKOPEN set to 3.
Note
All users who share access to the Ele must agree to allow dynamic locking in
order for any user to dynamically lock the le with BKLOCK.
The note above points out that users who share the same le should cooperate on how they
will share the le. Unless they all agree to allow locking, no one will be able to lock the le.
Also, it is important to avoid situations where one user locks the le and forgets to unlock it.
If this occurs when condition is set to a non-zero value, the calling process is not halted. But
if the le is locked already and if you attempt to lock a le with condition omitted or set to
zero your process is halted until the other user either unlocks the le or logs o.
You should always check the status parameter immediately following a call to BKLOCK in
order to determine if the call was completed successfully. If you locked with condition set to
a nonzero value, you should check if the le was locked before continuing. If it was locked,
status will have a \0&quot; in the rst character, but if another user had locked the le preventing
your call to BKLOCK from working, then status contains the value \71&quot;.
Figure 6-3 contains an example of locking a le with BKLOCK.
830
840
850
855
860
870
890
900
910
920
930
940
950
960
970
980
990
1000
1010
1020
1030
REM ********************************************************
REM * LOCK A KSAM FILE *
REM ********************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
REM THE THIRD PARAMETER INDTCATES THAT LOCKING IS
REM TO TAKE PLACE UNCONDITIONALLY
REM
CALL BKLOCK(F,S$,0)
REM
REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO LOCK &quot;;$N;&quot; ERROR &quot;;N$;&quot; &quot;LS$[1;1];&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
DOEND
Figure 6-3. Dynamically Locking a KSAM File with BKLOCK
USING KSAM FILES IN
BASIC PROGRAMS
6-13
BKOPEN
A call to procedure BKOPEN initiates le processing.
CALL BKOPEN (lenum,status,name [;access[,lock[,exclusive[,sequence]]]])
In order to process a KSAM le, it must be opened with a call to the BKOPEN procedure.
BKOPEN initiates processing, and optionally species how the le is to be processed.
BKOPEN does not create the le; it must have been created previously. You can create a
KSAM le through the BUILD command of the KSAMUTIL program (refer to section II).
To open a le means to make it available for processing. You can also specify how the le is
to be accessed (whether for input, output, input and output, or for update), whether dynamic
locking is allowed, whether access to the le can be shared, and whether records written to the
le are to be checked for primary key sequence. Default values are assigned for the optional
parameters. If you want to change the current processing or access method, you must close
the le and then open it again with the parameters set to new values.
PARAMETERS
lenum
status
name
6-14
A numeric variable whose value identies the le opened by the call to
BKOPEN. Since the value of lenum identies the le in other CALL
statements, it must not be changed while the le is open. (Required
parameter )
A four-character string variable to which is returned a code to indicate
whether or not the le was successfully opened and if not, why not. The rst
character is \0&quot; if the open is successful, to another value if not. (Refer to
Status Parameter discussion earlier in this section.) (Required parameter )
A string expression containing the name of the KSAM le to be processed.
This name is the actual designator assigned to the le when it was created,
or else it is a back reference to a formal designator specied in a :FILE
command, in which case, name has the form *formal designator . (Required
parameter )
USING KSAM FILES IN
BASIC PROGRAMS
access
A numeric expression whose value indicates one of the permissible access
types:
0
Read only .
1
Write only .
2
Write only .
3
Read and write .
4
Update access .
Use of procedures BKWRITE, BKREWRITE, and BKDELETE are
prohibited.
Deletes previously written data. Use of the procedures BKREAD,
BKREADBYKEY, BKREWRITE, BKDELETE, and BKSTART are
prohibited.
Saves previously written data . Use of the procedures prohibited by the
access =1, above, are also prohibited by access =2.
Use of procedures BKREWRITE and BKDELETE prohibited.
(Default value.)
Allows all procedures described in this section.
(Optional parameter ) Default: If omitted, or out of range, access is 3, read and
write access .
A numeric expression whose value indicates whether dynamic locking can take
place. Acceptable values are:
lock
0
Disallow dynamic
locking and
unlocking.
Use of procedures BKLOCK and BKUNLOCK prohibited. (Default
value .)
1
Allow dynamic
locking and
unlocking.
Procedures BKLOCK and BKUNLOCK may be used to permit or
restrict concurrent access to the le.
(Optional parameter ) Default: If omitted, or out of range, lock = 0 to disallow
exclusive
dynamic locking
A numeric expression whose value indicates the kind of exclusive access
desired for this le. If this parameter is omitted or is not one of the following
acceptable values, the default is assumed:
0
Depends on access If access = 0 (read only), then users share access to this le as if
exclusive were set to 3. If access is not = 0, then access to this le is
parameter .
exclusive as if exclusive were set to 1.
1
Exclusive .
2
Semi-exclusive .
3
Shared .
Prohibits other access to this le until either the le has been closed or
the process terminated. Only the user who opened the le can access it
while it is currently open.
Other users can access this le, but only for read access. The le
cannot be accessed to write, rewrite, or delete records until it is closed
or the process is terminated. (Default value.)
Once the le is opened, it can be accessed concurrently by any user in
any access mode, subject only to the MPE security provisions in eect.
(Optional parameter ) Default: If omitted, or out of range, exclusive = 2,
semi-exclusive access .
USING KSAM FILES IN
BASIC PROGRAMS
6-15
sequence
0
1
A numeric expression whose value indicates whether records written to the le
will be checked for primary key sequence or not. Acceptable values are:
When records are written to the le, primary key values can be in any
No sequence
order; their sequence is not checked. (Default value .)
checking.
Sequence checking . As each record is written to the le, KSAM checks to insure that its
primary key value is greater than the primary key value of any
previously written records; if duplicates are allowed for this key, then
the primary key can be equal to that of the previously written record.
(Optional parameter ) Default: If omitted, or out of range, sequence = 0, no
sequence checking
USING BKOPEN
After calling BKOPEN, you should always check the status parameter to determine whether
the open was successful. Upon successful execution of BKOPEN, the le named in name
is available for processing; an identication number is assigned to this le and returned to
lenum where it is available to identify the open le in other calls. Until the le is successfully
opened with BKOPEN, no operation can be executed that references the le either explicitly
or implicitly.
If only the rst three parameters are specied, and the le is opened successfully, the le has
the following default characteristics:
Read and Write access; you can read from and write to but not update the le.
Semi-exclusive access; other users can read from but not write to or update the le.
Dynamic locking not allowed; you cannot lock or unlock a le.
No sequence checking; records can be written in any order without checking sequence of
primary key values.
Access Modes
There are two types of write only access: one clears any existing records before writing the
specied records to the le (access = 1); the other saves existing records and writes the new
records after those already written (access = 2). Both these access modes do not permit any
read or update access to the le.
Read-only access (access = 0) can be specied if you want to insure that the le is not
changed. This mode prohibits the writing of new records, and rewriting or deleting of existing
records. In read-only mode, you can position the le, and read records in either sequential or
random order.
The default access mode (access = 3) allows you both to read records from and write records
to a le, but not to change or delete existing records. If you plan to read and write records
during the same process, but do not want to alter existing records, use this access mode.
If you want to rewrite or delete existing records in a KSAM le, you must open with access =
4. This mode allows you to use the BKREWRITE and BKDELETE procedures, as well as all
the other procedures described in this section.
6-16
USING KSAM FILES IN
BASIC PROGRAMS
Table 6-4 summarizes the procedures you may call depending on the access parameter value
you specify in BKOPEN.
Table 6-4. Procedures Allowed by BKOPEN
Write-only
with Clear
(access =1)
Read-only
(access =0)
Write-only
with Save
(access =2)
access
Parameter
Read/Write
(access =3)
Update
(access =4)
BKWRITE
BKREAD
Procedures BKREADBYKEY
Allowed BKSTART
BKWRITE
BKREAD
BKREADBYKEY
BKSTART
BKWRITE
BKREAD
BKREADBYKEY
BKSTART
BKWRITE
BKREWRITE
BKDELETE
BKCLOSE
BKERROR
BKCLOSE
BKERROR
BKCLOSE
BKERROR
BKCLOSE
BKERROR
BKCLOSE
BKERROR
Shared Access
By default in a multi-user envornment, all users whose MPE security restrictions allow them
to access your le can read the le, but they cannot change the le or add new records to it.
This is the default specication of the exclusive parameter in BKOPEN (exclusive =2). It is
independent of the value of the access parameter.
If you want to prevent other users from reading the le as well as writing to it, you must
specify this by setting exclusive =1. This setting allows only you to read from, write to, or
alter the le.
Another alternative is to set exclusive =0, thereby allowing other users access to the le only
when it is opened for read only (access =0). This setting of the exclusive parameter prevents
any access by other users when the le is opened for any form of write or update (accesss 6= 0)
. This means that you and other users share read access to the le, but only you can write to
or change the le.
You can choose to completely share access to the le, reading and/or writing and updating, by
setting the exclusive parameter to 3.
(Refer to Table 6-5 for a summary of the relation between the exclusive parameter and the
access parameter.)
Table 6-5. Relation of
exclusive
Parameter to
access
Parameter
exclusive =0
exclusive =1
exclusive =2
(default)
exclusive =3
access =0
(read only)
shared
exclusive
semi-exclusive
shared
access 6=0
(write only,
read/write,
or update)
exclusive
exclusive
semi-exclusive
shared
USING KSAM FILES IN
BASIC PROGRAMS
6-17
Dynamic Locking
When access is shared, it is good practice to allow dynamic locking so that individual
users can dynamically lock the le while performing any updates to the le. The le can
be unlocked as soon as the update is complete. An update to a le is when you write a
new record, delete a record, or rewrite an existing record. When access is exclusive or
semi-exclusive, there is no need for dynamic locking since only the user who has opened the
le can update the le.
Dynamic locking should also be allowed if access is shared and you plan to read the le
sequentially. This is because the sequential read procedure (BKREAD) is dependent on
the position of the logical record pointer and, in a shared environment, this pointer can
be changed by other users unless the le is locked (Refer to Table 6-3 for a list of the
pointer-dependent procedures.)
Sequence Checking
When sequence checking is specied, you must write records to the le in primary key
sequence. An attempt to write a record out of sequence causes the write to fail and the value
\21&quot; is returned to status following a call to BKWRITE. (Refer to the description of Status
earlier in this section.) As a result of sequence checking, the chronological and the primary
key sequence of records in your le is the same. Since the BASIC KSAM procedures have no
provision to read the le in chronological sequence, you may want to specify sequence checking
for any le that you will want to read in that order. With sequence checking, a le read in
logical order by primary key (the default for BKREAD) is also read in chronological order.
The example in Figure 6-4 shows how to use BKOPEN to open a KSAM le for input and
output (default access ), with dynamic locking (lock =1), for shared access (exclusive =3), and
without sequence checking (default sequence ).
6-18
USING KSAM FILES IN
BASIC PROGRAMS
10
20
30
40
50
55
60
65
70
80
90
100
110
120
130
135
140
145
150
160
170
175
180
190
200
210
220
240
250
260
270
280
290
300
310
320
330
340
350
360
370
380
390
400
410
DIM S$[4] &lt;-------- status \
DIM N$[26] &lt;------------- lename |- variable dimensions
DIM M$[72] &lt;-------- message /
INTEGER A[10]
DIM B$[12]
INTEGER J
DIM B1$[1]
DIM B2$[2]
INTEGER A2[2],A3[3],A5[5]
REM
REM THE KSAM/3000 FILE WAS BUILT WITH:
REM REC=80,16,F,ASCII
REM KEY=B,2,2,,DUP
REM SO,RECORD LENGTH IS 2 BYTES, FIXED, TYPE ASCII, 16 REC/BLOCK.
REM THE KEY IS 2 CHARACTERS LONG,STARTING IN CHARACTER 2 OF RECORD
REM
REM ********************************************************
REM * OPEN A KSAM FILE *
REM ********************************************************
REM
REM THE FILE NAME IS IN N$
REM THE STATUS OF THE CALL IS RETURNED IN S$
REM WHEN SUCCESSFUL, BKOPEN RETURNS A FILE NUMBER IN F
REM INPUT-OUTPUT ACCESS IS SPECIFIED IN J
REM DYNAMIC LOCKING IS ALLOWED IN D
REM SEMI-EXCLUSIVE ACCESS IS INDICATED IN E
REM
N$=&quot;KNAME,ACCOUNT,GROUP&quot; &lt;---------- le name
J=3 &lt;-------- access is read/write
D=1 &lt;------------------------------- dynamic locking allowed
E=3 &lt;-------- access shared
CALL BKOPEN(F,S$,N$,J,D,E)
REM
REM NOW DETERMINE WHETHER THE CALL SUCCEEDED:
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM S$ IS THE STATUS CODE SET BY THE CALL TO BKOPEN
REM N$ IS THE NAME OF THE FILE
PRINT &quot;UNABLE TO OPEN &quot;;N$;&quot; ERROR &quot;;S$[1;1];&quot;DETAIL &quot;LS$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620 &lt;-------- to close the le
DOEND
REM
REM THE PROGRAM CONTINUES
Figure 6-4. Opening KSAM File with BKOPEN
USING KSAM FILES IN
BASIC PROGRAMS
6-19
BKREAD
Transfers the next logical record from a KSAM le to a BASIC program.
CALL BKREAD(lenum,status[,parameterlist])
A call to BKREAD transfers the contents of a record from a KSAM le to a storage area
dened by a list of variables in a BASIC program. The record read is that at which the logical
record pointer is currently positioned. In a series of calls to BKREAD, records are read in
ascending order by key value. The primary key is used unless a previous call to BKSTART or
BKREADBYKEY has positioned the pointer to an alternate key. The le must have been
opened with an access mode that allows reading.
PARAMETERS
lenum
status
parameterlist
A numeric variable containing the le number that identies the le;
this number was returned by the last call to BKOPEN. It should not be
altered unless the le is closed by a successful call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKREAD was successful and if not, why not. The
rst character is set to zero when the call succeeds, to another value if not.
(Refer to the Status Parameter discussion earlier in this section.) (Required
parameter )
A list of variables separated by commas into which the data in the record
is read, The contents of the record are read into the variable (or variables)
until the physical length (or combined physical lengths) of parameterlist is
exhausted, or the end of the record is reached. (Optional parameter ) Default:
If omitted, the logical record pointer is positioned to the beginning of the next
record in key sequence .
USING BKREAD
After calling BKREAD, you should always check the status parameter to determine whether
the read was successful. Upon successful completion of BKREAD, the variables specied in
parameterlist contain data read from the record at which the record pointer was positioned
when BKREAD was called. Note that if parameterlist is omitted, the record pointer is
positioned to the beginning of the next logical record, eectively skipping the current record.
In order to use BKREAD, the le must be opened for input. The BKOPEN access parameter
should be zero if you only plan to read or position a record. To both read from and write to
the same open le, you either omit the access parameter or set it = 3. If you want to rewrite
or update as well as read records, you must set access = 4.
Values are read from the current record into the variables specied in parameterlist according
to the type and length of the variable. For example, consider the following code:
10 DIM G$(3),H$(3),S$(4)
20 INTEGER L,F
30 CALL BKREAD (F,S$,G$,H$,L)
/ | \-----/
/
|
|
6-20
USING KSAM FILES IN
BASIC PROGRAMS
filenum |
|
status
parameterlist
If the record being read contains only the word SCRABBLE, this word is read into the
specied variables as if they were assigned by the statements:
100 G$=&quot;SCR&quot;
110 H$=&quot;ABB&quot;
120 L=NUM(&quot;LE&quot;) &lt;------------ assigns numeric equivalent of string &quot;LE&quot; to L
Each variable in the parameterlist is lled to its current physical length before
proceeding to the next variable.
Note
The following calls omit the parameterlist in order to skip forward two records:
210 CALL BKREAD(F,S$) &lt;-----------------------------------\
--skip two records
220 CALL BKREAD(F,S$) &lt;-----------------------------------/
The records shipped are not the next records physically placed on the le, but are the next two
in logical sequence according to the value of the current key . The particular key used for the
read sequence can be selected with a call to BKSTART or BKREADBYKEY. BKSTART can
also be used to position the le to the beginning of the record with the lowest key value in the
selected key (Refer to BKSTART following BKREAD discussion.)
The example in Figure 6-5 assumes that the record pointer has been positioned to the
beginning of the rst record in primary key sequence. Assume that the le being read
was opened in the example in Figure 6-4, the records read were written in the example in
Figure 6-11.
Each record contains ve integers followed by ve undened words (garbage) followed by a
string of three characters. The record is read into
A5
a 5-word integer array
A2
a 2-word integer array
A3
a 3-word integer array
B1$
a 1-character string
B2$
a 2-character string
The ve integers that were written to the beginning of each record are read into array A5.
The next two arrays A2 and A3 receive the undened values that lled the next ve words of
the record. The rst string character is read into B1$, the next two into B2$.
Shared Access
If you open the le for read-only access (access =0), and the exclusive parameter is allowed
to default to zero, then more than one user can share read access to the le. In this case,
or if you specically indicate shared access, you should also allow dynamic locking in order
to read records from the le in key sequence. This is necessary because BKREAD depends
on the current position of the logical record pointer. (Refer to Table 6-3 for a list of the
pointer-dependent procedures.)
USING KSAM FILES IN
BASIC PROGRAMS
6-21
For example, if you plan to read the le sequentially starting from a particular key value, use
the following sequence of calls:
BKOPEN &lt;-------- open le for read-only, shared access, allow dynamic locking
BKLOCK &lt;-------- lock le
BKSTART &lt;-------- position pointer
BKREAD loop &lt;-------- read le in sequence from original pointer position
BKUNLOCK &lt;-------- unlock le when last record read
6-22
USING KSAM FILES IN
BASIC PROGRAMS
10
20
30
40
50
55
60
65
70
..
.
1310
1320
1330
1340
1350
1360
1370
1380
1390
1400
1410
1420
1430
1440
1450
1460
1470
1480
1490
l500
1510
1520
1530
1540
1550
1560
1570
1580
1590
1600
1610
1620
1622
1630
1650
1660
1670
1680
1690
DIM S$[4]
DIM N$[26]
DIM M$[72]
INTEGER A[10]
DIM B$[12]
INTEGER J
DIM B1$[1]
DIM B2$[2]
INTEGER A2[2],A3[3],A5[5]
REM ******************************************************
REM * READ FROM A KSAM FILE * o
REM ******************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ
REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN TO
REM THE FILE BY THE EXAMPLE TO WRITE A KSAM FILE
REM
CALL BKREAD(F,S$,B1$,B2$,A5[*],A3[*],A2[*])
REM
REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
REM
IF S$(1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO READ &quot;;N$;&quot; ERROR &quot;;S$[1;1];&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
REM
REM TEST FOR END OF FILE
REM AND POSITION TO LEAST VALUED PRIMARY KEY
IF S$[1;1]=&quot;1&quot; THEN 1080
GOTO 3620
DOEND
REM
REM ECHO WHAT WAS READ
REM
PRINT &quot;RECORD CONTAINS&quot;;B1$,B2$
MAT PRINT A5
MAT PRINT A3,A2
REM
REM THE CONTENTS OF B1$=&quot;1&quot;, OF B2$=&quot;23&quot;
REM THE CONTENTS OF A5(1) THROUGH A5(5) ARE 1 THROUGH 5.
REM THE CONTENTS OF A3 AND A2 ARE UNKNOWN.
REM
REM THE PROGRAM CONTINUES
Figure 6-5. Reading From a KSAM File with BKREAD
USING KSAM FILES IN
BASIC PROGRAMS
6-23
BKREADBYKEY
Transfers record identied by particular key value from KSAM le to BASIC program.
CALL BKREADBYKEY(lenum,status,keyvalue,keylocation,parameterlist)
A call to BKREADBYKEY locates and reads a record into a storage area identied by a list
of variables in the BASIC program. The record to be read is located by matching the specied
keyvalue with an identical value stored in the record starting at keylocation . The record value
and the value specied in keyvalue must match exactly, or an error code is returned to status .
To use BKREADBYKEY, the le must be open in an access mode that allows reading.
You cannot use BKREADBYKEY to locate a record by generic or approximate key values.
For this purpose you can call BKSTART followed by a call to BKREAD. (Refer to the
discussion of BKSTART.)
PARAMETERS
lenum
status
keyvalue
keylocation
parameterlist
6-24
A numeric variable containing the le number that identies the le; this
number was returned by the last call to BKOPEN. It should not be altered
unless the le is closed with a successful call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKREADBYKEY was successful and if not, why
not. The rst character is set to zero if the call succeeds, to another value
if not. (Refer to the Status Parameter discussion earlier in this section.)
(Required parameter )
A string or numeric expression whose value is compared to a key value in the
record. The record pointer is positioned to the rst record with a key value at
keylocation that is exactly equal to the specied keyvalue . In order to match
exactly, the record value and keyvalue must have the same logical length.
(Required parameter )
A numeric expression whose value indicates the starting character
position in each record of the key used to locate the record to be read by
BKREADBYKEY. The characters in a record are counted starting with 1. If
the value of keylocation is zero, the primary key is assumed. The primary
key also may be specically indicated by its location in the record. (Required
parameter )
A list of variables separated by commas into which the data in the record
is read. The contents of the record are read into the variable (or variables)
until the physical length (or combined physical lengths) of parameterlist is
exhausted, or until the end of the record is reached. (Required parameter )
USING KSAM FILES IN
BASIC PROGRAMS
USING BKREADBYKEY
After calling BKREADBYKEY, you should always check the status parameter to determine
whether the read was successful. Upon completion of BKREADBYKEY, the variables
specied in parameterlist contain data read from the record located through the keyvalue
andkeylocation parameters.
The key value in there cord to be read must exactly match the specied keyvalue . Unlike
BKSTART, the only relation between the value in the record and the value in the call is that
of equality. If duplicate key values are allowed in the key being sought, then the rst record
with a matching key value is read by BKREADBYKEY. To read the remaining records with
duplicate key values, you should use BKREAD.
Note
Each variable in parameterlist is lled to its current physical length before
proceeding to the next variable.
The example in Figure 6-6 uses BKREADBYKEY to read the rst record found with the
value \23&quot; starting in byte 2. Since this is the le written by BKWRITE in Figure 6-11, the
records in the le are identical including the keys and only the rst record is read.
USING KSAM FILES IN
BASIC PROGRAMS
6-25
2220
2230
2240
2250
2260
2270
2280
2290
2300
2310
2320
2330
2340
2350
2360
2370
2380
2390
2400
2410
2420
2430
2440
2450
2460
2470
2480
2490
2500
2510
2520
2530
2540
2550
2560
2562
2570
2580
REM *****************************************************
REM * READ BY KEY FROM A KSAM FILE *
REM *****************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
REM AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ
REM CONTAINS THE SAME INFORMATION THAT WAS WRITTEN IN THE
REM WRITE EXAMPLE.
REM
REM AN ADDITIONAL ASSUMPTION IS THAT THE DESIRED KEY VALUE
REM STARTS AT CHARACTER 2 AND HAS THE VALUE &quot;23&quot;.
REM
CALL BKREADBYKEY(F,S$,&quot;23&quot;,2,B1$,B2$,A5[*],A3[*],A2[*])
REM
PEM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO READBYKEY &quot;;N$;&quot; ERROR &quot;;S$[1;1];&quot; DETAIL &quot;S$[
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM
REM THE CONTENTS OF B1$=&quot;1&quot;, OF B2$=&quot;23&quot;.
REM THE CONTENTS OF A5(1) THROUGH A5(5) ARE INTEGERS 1 THROUGH 5
REM THE CONTENTS OF A3 AND A2 ARE UNKNOWN.
REM
REM ECHO WHAT WAS READ
REM
PRINT &quot;RECORD READ = &quot;;B1$,B2$
MAT PRINT A5
MAT PRINT A3,A2
REM
REM THE PROGRAM CONTINUES
Figure 6-6. Reading a Record Located by Key Value with BKREADBYKEY
6-26
USING KSAM FILES IN
BASIC PROGRAMS
2]
BKREWRITE
Changes the contents of a record in a KSAM le.
CALL BKREWRITE (lenum, status, parameterlist)
A call to BKREWRITE replaces the contents of an existing record with new values. The
record to be rewritten is the last record accessed by a call to BKREAD, BKREADBYKEY,
or BKSTART. To use BKREWRITE, the le must be open in the access mode that allows
update. If access is shared, it must also be opened with dynamic locking allowed, and the le
locked by BKLOCK before records are rewritten.
PARAMETERS
lenum
status
parameterlist
A numeric variable containing the le number that identies the le; this
number was returned by the last call to BKOPEN. It should not be altered
unless the le is closed with a successful call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKREWRITE was successful and if not, why not.
The rst character is set to zero if the call succeeds, to another value if not.
(Refer to the Status Parameter discussion earlier in this section. (Required
parameter )
A list of variables or constants, separated by commas, that contain the data
to be written to the le replacing the last record read or written. The total
length of the new record is derived from the total number, data type, and
length in characters of each item in parameterlist . Although this length
need not be the same as the record it replaces, it should be long enough to
contain all the keys, but not so long that it exceeds the dened record length.
(Required parameter )
USING BKREWRITE
After calling BKREWRITE, you should always check the status parameter to make sure that
the rewrite was successful. Upon successful completion of BKREWRITE, new values replace
the data in the last record read to or written from the BASIC program. The new data may
change every value in the previously read record including the primary key value.
If you want to replace a record with a particular key value, you should locate and read the
record with BKREADBYKEY or BKSTART. To rewrite a series of records you should read
the records with BKREAD.
When the data in the parameterlist of BKREWRITE is shorter in total length than the data
in the record being rewritten, there is less total data in the rewritten record. In order to
maintain the key sequence of all keys, dened values should be written to the location of all
keys, both the primary key and any alternate keys.
Note
Items written to a KSAM le with the BKREWRITE procedure are
concatenated; rounding to word boundaries does not occur.
USING KSAM FILES IN
BASIC PROGRAMS
6-27
The example in Figure 6-7 writes new values to a record originally written if Figure 6-11 and
read in Figure 6-5. The new values ll an array that had undened values in the last ve
words, now dened as two arrays A3 and A2 by the BKREAD call. The primary key value
\23&quot; in location 2 is unchanged.
The record read by BKREAD contained the following values:
After being rewritten by BKREWRITE, it contains the following values:
Shared Access
When access is shared, the call to BKREAD, BKREADBYKEY, or BKSTART that locates
the record to be rewritten should be included in the same pair of BKLOCK/BKUNLOCK
calls as the call to BKREWRITE. This insures that no other user alters the record pointer
between the call that locates the record and the call that rewrites it.
Duplicate Keys
If you want to sequentially rewrite all records in a chain of records with duplicate keys,
locate the rst record in the chain with BKREADBYKEY. Then call BKREWRITE to
modify this record. If no key value (the selected key or any other) is modied, subsequent
calls to BKREWRITE will modify the next sequential records in the chain of duplicate
keys. If, however, any key has been changed, the modied key is written to the end of the
chain and the next sequential record is one with the next higher key value. In this case,
to rewrite all records with duplicate keys, precede each call to BKREWRITE by a call to
BKREADBYKEY.
6-28
USING KSAM FILES IN
BASIC PROGRAMS
2600
2610
2620
2630
2640
2650
2660
2670
2680
2690
2700
2710
2720
2730
2740
2750
2760
2770
2780
2790
2800
2810
2820
2830
2900
2910
2920
2930
2940
2950
2960
2970
2980
2990
3000
3010
3020
3030
3040
3050
3060
3070
3080
3090
REM
REM
REM
REM
REM
REM
REM
REM
REM
REM
REM
*********************************************************
* REVISE THE CONTENTS OF A RECORD READ FROM A KSAM FILE *
**********************************************************
F IS THE FILE NUMBER OF A KSAM FILE OPENED BY A CALL TO BKOPEN
NOTE THAT FOR BKREWRITE,BKOPEN ACCESS MODE MUST=4 FOR UPDATE.
AN ASSUMPTION HAS BEEN MADE THAT THE RECORD TO BE READ
CONTAINS THE SAME INFORMATION THAT WAS WRITEM TO THE
KSAM FILE IN THE BKWRITE EXAMPLE,,
|------------------ parameterlist
REM /------------------------\
CALL BKREAD(F,S$,B1$,B2$,A5[*],A3[*],A2[*])
REM
REM NOW DETERMINE WHETHER THE CALL HAS SUCCEEDED.
REM
IF S$(1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CALL SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO READ &quot;;N$;&quot; ERROR &quot;;S$[1;1]&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM THE CONTENTS OF B1=1&quot;, OF B2$=&quot;23&quot;
REM THE CONTENTS OF A5(1) THROUGH A5(5) ARE 1 THROUGH 5
REM THE CONTENTS OF A3 AND A2 ARE UNKNOWN
REM
REM STORE VALUES 1 THROUGH 3 INTO A3(1) THROUGH A3(3)
REM STORE VALUES 1 AND 2 INTO A2(1) AND A2(2).
REM
FOR I=1 TO 2
A2[I]=I
A3[I]=I
NEXT I parameterlist
A3[3]=3 |
REM /------------------------\
CALL BKREWRITE(F,S$,B1$,B2$,A5[*],A3[*],A2[*])
REM
REM NOW DETERMINE WHETHER THE CALL HAS SUCCEEDED
REM
IF S$[1;1]&lt;&gt;&quot;0 THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
Figure 6-7. Rewriting Record in KSAM File with BKREWRITE
USING KSAM FILES IN
BASIC PROGRAMS
6-29
3100
3110
3120
3130
3140
3150
3160
3170
3180
3190
3200
3210
PRINT &quot;UNABLE TO REWRITE &quot;;N$;&quot; ERROR &quot;;S$[1;1];&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM
REM ECHO WHAT WAS UPDATED
REM
PRINT &quot;REWRITTEN RECORD = &quot;;B1;B2
MAT PRINT A5,A3,A2
REM
REM THE PROGRAM CONTINUES
Figure 6-7. Rewriting Record in KSAM File with BKREWRITE (continued)
BKSTART
Positions a KSAM le to a particular record based on a key value.
CALL BKSTART(lenum,status[,keyvalue[,keylocation [,relation ]]])
By calling BKSTART, you can position the record pointer to any record in the le based on
the value of a key in that record. The key can be the primary key or any altemate key, since
BKSTART also allows you to select the key for positioning and for subsequent sequential
reads. If you want to read all the keys in a key sequence, you can use BKSTART to position
to the record with the lowest key value in the selected key.
PARAMETERS
lenum
status
keyvalue
6-30
A numeric variable containing the le number that identies the le; this
number was returned by the last call to BKOPEN. It should not be altered
unless the le is closed with a successful call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKSTART was successful and if not, why not. The
rst character is set to zero when the can succeeds, to another value when
it fails. (Refer to the Status Parameter discussion earlier in this section.)
(Required parameter )
A string or numeric expression whose value is compared to a key value in this
record. The record pointer is positioned to the rst record with a key value
that bears the relation specied by relation to the value in keyvalue . If the
value is a string, its logical length is used for the comparison; otherwise, the
physical or dimensioned length is used. The length of this value must be less
than or equal to the length of the key as specied when the le was created.
If keyvalue is a null string (&quot;&quot;), the le is positioned to the beginning of the
rst logical record according to the value of the key in keylocation . (Optional
Parameter )
USING KSAM FILES IN
BASIC PROGRAMS
keylocation
relation
Default: If omitted, the value assumed for keyvalue is the lowest value for the
specied hey type .
A numeric expression whose value indicates the starting character location in
each record of the key used for positioning by BKSTART. The characters in a
record are counted starting with 1. If set to zero, the primary key is assumed.
(Optional parameter )
Default: If omitted, the primary key is assumed .
A numeric expression whose value species the relation between the specied
keyvalue and the value of the key at keylocation . The record pointer is
positioned to the rst record with a key value satisfying this relation:
0|; the value of the record key is equal to keyvalue
1|; the value of the record key is greater than keyvalue
2|; the value of the record key is greater than or equal to keyvalue .
(default )
Any value greater than 2 is treated as if it were 2. (Optional parameter )
Default: If omitted, the relation is assumed to be 2, record key is
greater than or equal to the keyvalue .
USING BKSTART
After calling BKSTART, you should check the status parameter to determine if the procedure
was executed successfully. If successfully executed, the record pointer is positioned at the
beginning of the rst record with a value at keylocation that has the relation specied in
relation to the value specied in keyvalue .
If default values are assumed for all three optional parameters, the pointer is positioned to the
record with the lowest value for its type in the primary key location.
If the relation specied is equality (relation = 0), then a record must be located that has
the exact same key value as that specied in the BKSTART call. When found, the pointer
is positioned to that record. If duplicate values are allowed for the key, then the pointer is
positioned at the rst record with the particular key value.
When the specied relation is greater than (relation = 1), the le is searched until a record is
found with a key value greater than the specied key value. The search passes over any record
with a key value equal to the specied value. This relation allows you to retrieve items by an
approximate key . Thus, if you specify a key value of \R&quot;, a call to BKSTART will position
the pointer to the rst record with a key value that starts with the letter R. A subsequent
series of calls to BKREAD allows you to read the remaining records in the le or, by including
a test, to read only the records beginning with R.
When the specied relation is greater than or equal to (relation = 2), BKSTART looks for a
record containing a value equal to the specied value. If found, it positions the pointer to that
record. If not found, it continues looking and positions the pointer to the rst record that is
greater than the specied value. This type of search can be used to locate records by generic
key . A generic, or partial, key is a value that matches characters at the beginning of the key,
but not necessarily the end. For example, in a key containing a date in the form yymmdd , by
specifying only the rst two characters as keyvalue and a relation = 2, you can position to the
rst record with a key for that year; by specifying the rst four characters, you can position to
the rst record for a particular year and month.
USING KSAM FILES IN
BASIC PROGRAMS
6-31
Whenever a record cannot be found with a key that satises the relation and value specied,
the value \23&quot; for invalid key is returned to status .
BKSTART allows you to specify a key other than the primary key assumed by BKREAD.
Called prior to a series of calls to BKREAD, it prepares for a sequential read of the le in
alternate key order. For example, assuming a le with an alternate key in location 21, the
following call positions the pointer to the rst record in that key sequence:
100
150
160
170
DIM A$(10),S$(4)
A$=&quot; &quot; &lt;------------------- assign null string to keyvalue
L=21 &lt;--------------------------- alternate key location to keylocation
CALL BKSTART(F,S$,A$,21)
The default for relation is 2 (greater than or equal to) and need not be specied except for
documentation purposes.
Figure 6-8 illustrates the use of BKSTART with default values for all optional parameters.
Specied in this minimal form, it positions to the least valued primary key.
1080
1090
1100
1110
1120
1130
1140
1150
1160
1170
1180
1190
1200
1210
1220
1230
1240
1250
1260
1270
1280
1290
1300
REM *******************************************************
REM * POSITION TO LEAST VALUED PRIMARY KEY *
REM *******************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
CALL BKSTART(F,S$)
REM
REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL
PRINT &quot;UNABLE TO POSITION FILE TO LEAST VALUED PRIMARY KEY&quot;
PRINT &quot;ERROR &quot;;S$[1;1],&quot; DETAIL&quot;;S$[2]
CALL BKERROR,(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM
REM THE PROGRAM CONTINUES
REM
Figure 6-8. Positioning Pointer to Least-Valued Record with BKSTART
The example in Figure 6-9 positions the record pointer to a record containing a specic key
value. The value is \23&quot;; it is located starting in the second character of each record. The
value for relation is zero indicating that the key must contain exactly the value \23,&quot; not a
value larger than \23.&quot;
6-32
USING KSAM FILES IN
BASIC PROGRAMS
1920
1930
1940
1950
1960
1970
1989
1990
2000
2010
2020
2060
2070
2080
2090
2100
2110
2120
2130
2140
2150
2160
2170
2180
2190
2200
2210
REM
REM ***************************************
REM * POSITION A KSAM FILE *
REM ***************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
REM AN ASSUMPTION HAS BEEN MADE THAT THE POSITIONING TO BE
REM DONE IS TO THE RECORD WRITTEN IN THE WRITE EXAMPLE,
REM AND THAT THE DESIRED KEY STARTS AT CHARACTER 2.
REM
CALL BKSTART(F,S$,&quot;23&quot;,2,0)
REM
REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE RETURNED BY THE PRECEDING CALL
PRINT &quot;UNABLE TO START &quot;;N$;&quot; ERROR &quot;;S$[1;1];&quot; DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM
REM THE PROGRAM CONTINUES
REM
Figure 6-9. Positioning Pointer to Particular Record with BKSTART
BKUNLOCK
Unlocks a le dynamically locked by BKLOCK
CALL BKUNLOCK(lenum,status)
A le locked by BKLOCK is released for use by other users with a call to BKUNLOCK. (If
you log o from any connection with the system, the le is also unlocked.) Since dynamic
locking takes place during shared access to the same le by more than one user, it is
important that any le locked by BKLOCK be unlocked as soon as possible by BKUNLOCK.
To use BKUNLOCK, the le must be opened with dynamic locking allowed by all users who
share access to the le.
USING KSAM FILES IN
BASIC PROGRAMS
6-33
PARAMETERS
lenum
status
A numeric variable containing the le number that identies the le; this
number was returned to lenum by the last call to BKOPEN. It should not be
altered until the le is successfully closed by BKCLOSE. (Required parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKLOCK was successful and if not, why not. The
rst character is set to zero when the call succeeds, to another value if it
fails. (Refer to Status Parameter discussion earlier in this section.) (Required
parameter )
USING BKUNLOCK
After calling BKUNLOCK, you should always check the status parameter to make sure that
the procedure was successfully executed. When successful, a le locked by BKLOCK is
again made available for access by other users. If the le is not locked by BKLOCK when
BKUNLOCK is called, the le is not aected.
Figure 6-10 illustrates the use of BKUNLOCK to unlock the le after it is updated.
1700
1710
1720
1730
1740
1750
1760
1770
1780
1790
1800
1810
1820
1830
1840
1850
1860
1870
1880
1890
1900
REM *****************************************************
REM * UNLOCK A KSAM FILE *
REM *****************************************************
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
CALL BKUNLOCK(F,S$)
REM
REM NOW DETERHINE WHETHER THE CALL HAS SUCCEEDED
REM
IF S$(1;1)&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL
PRINT &quot;UNABLE TO UNLOCK &quot;;N$;&quot; ERROR &quot;;S$(1;1);&quot;DETAIL &quot;;S$[2]
CALL BKERROR(S$,M$)
PRINT M$
GOTO 3620
DOEND
REM
REM THE PROGRAM CONTINUES
Figure 6-10. Dynamically Unlocking a KSAM File
6-34
USING KSAM FILES IN
BASIC PROGRAMS
BKVERSION
Retrieves the version, update number and x number of the current KSAM/3000.
CALL BKVERSION(status, message).
A call to BKVERSION retrieves a printable string of characters that identies the current
version of the KSAM/3000 procedures used to process KSAM les. The string of characters
returned by BKVERSION can be printed.
PARAMETERS
status
message
A four-character string variable to which is returned the code that indicates
whether or not the call to BKVERSION was successful and if not, why not.
The rst character is set to zero when the call succeeds, to another value if
it fails. (Refer to the Status Parameter discussion earlier in this section.)
(Required parameter )
A string variable to which is returned the identication of the current
KSAM/3000 procedures. It is in the form:
version.update.x
where version is an ASCllletter, update is an ASCII integer, and x is also
an ASCII integer. The three terms are separated by periods. (Required
parameter )
USING BKVERSION
You may call BKVERSION in order to get the version, update, and x numbers of the
KSAM/3000 currently being used. This identication can be compared to the version, update,
and x numbers that identify the version in which a KSAM le was created, as returned by
the VERIFY command of program KSAMUTIL (refer to section II). The following example
illustrates use of BKVERSION. Note that two strings are needed.
10 DIM S$(4) &lt;-------- status
20 DIM V$(72) &lt;---- message
..
.
100 CALL BKVERSION(S$,V$)
110 PRINT &quot;THE CURRENT KSAM/3000 IS HP32208.&quot;;V$
..
.
RUN
THE CURRENT KSAM/3000 IS HP32208.A.1.23
\-----/
|
contents of V$
USING KSAM FILES IN
BASIC PROGRAMS
6-35
BKWRITE
Writes data from a BASIC program to a KSAM le.
CALL BKWRITE (lenum,status,parameterlist)
A call to procedure BKWRITE writes a record to a KSAM le from a BASIC program. This
call provides the only way to create a KSAM record from a BASIC program. The le must
have been opened with an access mode that allows writing. If access is shared, the le also
must be opened for dynamic locking (lock = 1), and the le locked with BKLOCK before any
records are written.
PARAMETERS
lenum
status
parameterlist
A numeric variable containing the le number value that identies the le;
this number was returned by the last call to BKOPEN. It should not be
altered unless the le is closed by a successful call to BKCLOSE. (Required
parameter )
A four-character string variable to which is returned a code that indicates
whether or not the call to BKWRITE was successful and if not, why not. The
rst character is set to zero when the call succeeds, to another value if not.
(Refer to the Status Parameter discussion earlier in this section.) (Required
parameter )
A list of variables or constants, separated by commas, that contain the data
to be written to the le as a record. The total length of the record contents
is derived from the total number, the type, and the length in characters of
the items in parameterlist . The parameterlist must contain a value for each
location dened as a key location in the record. (Required parameter )
USING BKWRITE
After calling BKWRITE, you should always check the status parameter to insure that the
write was successful. Upon successful completion of BKWRITE, one record containing the
values specied in parameterlist is written to the opened KSAM le.
Two parameters that are set when the le is opened aect how BKWRITE operates. These
are the access and sequence parameters.
In order to write to a le, the le must be opened with access greater than 0. If the access
parameter is set to 1, all existing data in the le is cleared before the rst record is written to
the le. If access is set to 2 or greater, the rst record written by BKWRITE immediately
follows any existing records; the le is not cleared.
The sequence parameter determines whether records must be written in primary key sequence,
or not. If sequence is zero, records can be written in any order; no check is made on the
sequence of the primary key eld. If sequence is set to 1, you must write each record with
a value in the primary key eld that is greater than the primary key value in the previous
record. Primary key values may equal the previous primary key value only if the le was
created with duplicate key values permitted. To illustrate, assume that the record illustrated
by the following example was the rst record written to the le. It has the value 1 as its
primary key. If the le was opened with sequence = 1, the next record written must have a
6-36
USING KSAM FILES IN
BASIC PROGRAMS
value of 2 or more in the primary key eld. It may have the same value only if duplicates are
allowed for that key eld, and must not have a value less than the previous primary key.
The values written to the record depend on the type of the items in parameterlist . To
illustrate, consider the following statements:
10
20
30
40
50
DIM D$(20),E$(10),S$(4)
INTEGER I,J
D$=&quot;MITCHELL&quot;&lt;------------------ logical length = 8 characters
E$=&quot;JAMES&quot; &lt;------------------------- logical length = 5 characters
I=0&lt;------------|
each integer requires 2 characters
60 J=1&lt;------------|
70 CALL BKWRITE (F,S$,I,J,D$,E$)
/ | \-------/
/
|
|
filnum
|
parameterlist
status
This set of statements writes one record to the KSAM le. The record has the form:
Assuming a le created with one key starting in the third character, two characters long, the
value 1 is the key value. Each integer requires 2 characters, the two strings use a total of 13
characters, resulting in values that take up 17 characters of the record. The remainder of the
record is undened. Record size is specied at le creation.
When writing from numeric arrays, the dimensioned length is used; when writing from strings
the logical length is used. The logical length of a string variable or string array element, is the
number of characters actually stored in the variable or element. It determines the length of
the item written to the record. A numeric array, on the other hand, uses the dimensioned
length as the length of the item written to the record. For example, suppose a numeric array
A is added to the parameterlist in the previous example:
5
10
20
30
40
50
60
70
80
INTEGER A(10) &lt;------------------------- dimensioned length of A is 10 words
DIM D$(20),E$(10),S$(4)
INTEGER I,J,F
D$=&quot;MARSHALL&quot;
D$=&quot;MILLY&quot;
FOR I=1 TO 5 \
A(I)=1 |--------------------- Move 5 words to array A
NEXT I &amp;/
I=0
USING KSAM FILES IN
BASIC PROGRAMS
6-37
90 J=3
100 CALL BKWRITE(F,S$,I,J,A(*),D$,E$)
This set of statements results in a record with the following values:
Note
Items written to a KSAM le from a BASIC program are concatenated;
rounding to word boundaries does not occur.
Figure 6-11 is an example of writing one string and one integer array to each record of the
KSAM le opened in Figure 6-4. The three records written contain the following data:
6-38
USING KSAM FILES IN
BASIC PROGRAMS
10
20
30
40
50
55
60
65
70
80
90
100
110
120
130
135
..
.
430
440
450
460
470
480
490
500
510
520
530
540
550
560
DIM S$[4]
DIM N$[26]
DIM M$[72]
INTEGER A[10]
DIM B$[12]
INTEGER J
DIM B1$[1]
DIM B2$[2]
INTEGER A2[2],A3[3],A5[5]
REM
REM THE KSAM/3000 FILE WAS BUILT WITH:
REM REC=-80,16,F,ASCII
PEM KEY=B,2,2,DUP
REM SO,RECORD LENGTH IS 2 BYTES, FIXED, TYPE ASCII, 16 REC/BLOCK.
THE KEY IS 2 CHARACTERS LONG,STARTING IN CHARACTER 2 OF RECORD
REM
570
580
620
630
640
650
660
670
680
690
REM NOTE THAT ONLY THREE BYTES &quot;123&quot; ARE WRITTEN FROM B$
REM WHEREAS TEN WORDS ARE WRITTEN FROM NUMERIC ARRAY A.
REM
REM THREE IDENTICAL RECORDS ARE BEING OUTPUT SO THAT
REM SUBSEQUENT EXAMPLES OF THIS PROGRAM WILL EXECUTE
REM .
FOR I=1 TO 3
CALL BKWRITE(F,S$,BS,A[*])
REM
REM NOW DETERMINE WHETHER THIS CALL SUCCEEDED
REM ********************************************************
REM * WRITE TO A KSAM FILE *
REM ********************************************************
REM
PEM ASSIGN VALUES TO OUTPUT VARIABLES
REM
FOR I=1 TO 5
A[I]=I
NEXT I
RS=&quot;123&quot;
REM
REM F IS THE FILE NUMBER OF A KSAM FILE
REM OPENED BY A CALL TO BKOPEN
REM
Figure 6-11. Writing to a KSAM File with BKWRITE
USING KSAM FILES IN
BASIC PROGRAMS
6-39
700
710
720
730
740
750
760
770
780
790
800
810
REM
IF S$[1;1]&lt;&gt;&quot;0&quot; THEN DO
REM N$ CONTAINS THE NAME OF THE KSAM FILE
REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CODE
PRINT &quot;UNABLE TO WRITE TO &quot;;N$;&quot;ERROR &quot;[S$]; DETAIL &quot;;S$[
CALL BKERROR(S&amp;,Ms)
PRINT M$
GOTO 3620
DOEND
NEXT I
REM
REM THE PROGRAM CONTINUES
Figure 6-11. Writing to a KSAM File with BKWRITE (continued)
6-40
USING KSAM FILES IN
BASIC PROGRAMS
2]
A
ERROR MESSAGES AND RECOVERY PROCEDURES
This appendix lists the error messages that may be issued as a result of errors encountered
while accessing KSAM les. The messages are not limited to KSAM errors since other le
system errors or language errors can occur while accessing a KSAM le.
Whenever possible, the reason the message was issued is listed under \Meaning&quot; and any
action that can be taken to correct the error is listed under \Action.&quot;
The messages are contained in the following tables:
Table A-1 File System Error Codes
Table A-2 COBOL Status Returns
Table A-3 BASIC Status Returns
Table A-4 KSAMUTIL Error Codes and Messages
Table A-5 FCOPY Warning and Error Messages
ERROR MESSAGES AND RECOVERY PROCEDURES
A-1
Table A-1. File System Error Codes
CODE
0
1
2
3
4
5
6
7
8
9
20
2l
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
A-2
MEANING
END OF FILE
ILLEGAL DB REGISTER
ILLEGAL CAPABILITY
OMITTED PARAMETER
INCORRECT S REGISTER
PARAMETER ADDRESS VIOLATION
PARAMETER END ADDRESS VIOLATION
ILLEGAL PARAMETER
PARAMETER VALUE INVALID
INCORRECT Q REGISTER
INVALID OPERATION
DATA PARITY ERROR
SOFTWARE TIME-OUT
END OF TAPE
UNIT NOT READY
NO WRITE-RING ON TAPE
TRANSMISSION ERROR
I/O TIME-OUT
TIMING ERROR OR DATA OVERRUN
SIO FAILURE
UNIT FAILURE
END OF LINE
SOFTWARE ABORT
DATA LOST
UNIT NOT ON-LINE
DATA-SET NOT READY
INVALID DISC ADDRESS
INVALID MEMORY ADDRESS
TAPE PARITY ERROR
RECOVERED TAPE ERROR
OPERATION INCONSISTENT WITH ACCESS TYPE
OPERATION INCONSISTENT WITH RECORD TYPE
OPERATION INCONSISTENT WITH DEVICE TYPE
WRITE EXCEEDS RECORD SIZE
UPDATE AT RECORD ZERO
PRIVILEGED FILE VIOLATION
OUT OF DISC SPACE
I/O ERROR ON FILE LABEL
INVALID OPERATION DUE TO MULTIPLE FILE
ACCESS
UNIMPLEMENTED FUNCTION
NONEXISTENT ACCOUNT
ERROR MESSAGES AND RECOVERY PROCEDURES
ACTION
Table A-1. File System Error Codes (continued)
CODE
51
52
53
54
55
56
57
58
59
60
61
62
63
64
71
72
73
80
81
82
83
84
85
86
87
89
90
91
92
93
94
100
101
102
103
104
106
107
108
110
MEANING
NONEXISTENT GROUP
NONEXISTENT PERMANENT FILE
NONEXISTENT TEMPORARY FILE
INVALID FILE REFERENCE
DEVICE UNAVAILABLE
INVALID DEVICE SPECIFICATION
OUT OF VIRTUAL MEMORY
NO PASSED FILE
STANDARD LABEL VIOLATION
GLOBAL RIN UNAVAILABLE
OUT OF GROUP DISC SPACE
OUT OF ACCOUNT DISC SPACE
USER LACKS NON-SHARABLE DEVICE CAPABILITY
USER LACKS MULTI-RIN CAPABILITY
TOO MANY FILES OPEN
INVALID FILE NUMBER
BOUNDS VIOLATION
SPOOFLE SIZE EXCEEDS CONFIGURATION
NO \SPOOL&quot; CLASS IN SYSTEM
INSUFFICIENT SPACE FOR SPOOFLE
I/O ERROR ON SPOOFLE
DEVICE UNAVAILABLE FOR SPOOFLE
OPERATION INCONSISTENT WITH SPOOLING
NONEXISTENT SPOOFLE
BAD SPOOFLE BLOCK
POWER FAILURE
EXCLUSIVE VIOLATION: FILE BEING ACCESSED
EXCLUSIVE VIOLATION: FILE ACCESSED
EXCLUSIVELY
LOCKWORD VIOLATION
SECURITY VIOLATION
USER IS NOT CREATOR
DUPLICATE PERMANENT FILE NAME
DUPLICATE TEMPORARY FILE NAME
I/O ERROR ON DIRECTORY
PERMANENT FILE DIRECTORY OVERFLOW
TEMPORARY FILE DIRECTORY OVERFLOW
EXTENT SIZE EXCEEDS MAXIMUM
INSUFFICIENT SPACE FOR USER LABELS
DEFECTIVE FILE LABEL ON DISC
ATTEMPT TO SAVE PERMANENT FILE AS
TEMPORARY
ACTION
ERROR MESSAGES AND RECOVERY PROCEDURES
A-3
Table A-1. File System Error Codes (continued)
CODE
111
112
..
.
169
170
171
172
173
174
175
176
177
178
179
ACTION
RESERVED FOR FUTURE USE
THE RECORD IS MARKED DELETED. FPOINT
POSITIONED POINTER TO A RECORD THAT WAS
MARKED FOR DELETION.
DUPLICATE KEY VALUE WHEN DUPLICATES NOT
ALLOWED.
KEY NOT FOUND; NO SUCH KEY VALUE.
tcount PARAMETER LARGER THAN RECORD SIZE.
CANNOT GET EXTRA DATA SEGMENT FOR THIS
FILE.
KSAM INTERNAL ERROR. A KEY VALUE (NOT
SEARCH KEY) FOR A RECORD TO BE DELETED IS
NOT IN KEY FILE; RECORD CANNOT BE DELETED.
ILLEGAL EXTRA DATA SEGMENT LENGTH.
TOO MANY EXTRA DATA SEGMENTS FOR THIS
PROCESS
NOT ENOUGH VIRTUAL MEMORY FOR EXTRA DATA
SEGMENT
THE FILE MUST BE LOCKED BEFORE THIS
INTRINSIC ISSUED
INCREASE THE SIZE
OF VIRTUAL MEMORY
USE FLOCK TO LOCK
FILE OR OPEN FILE FOR
EXCLUSIVE ACCESS.
USE FCOPY TO
REBUILD FILE:
&gt;FROM=oldksamle
;TO=(dle,kle )
180
THE KSAM FILE MUST BE REBUILT BECAUSE THIS
VERSION OF KSAM DOES NOT HANDLE THE FILE
BUILT BY PREVIOUS VERSION.
181
182
183
184
INVALID KEY STARTING POSITION.
FILE IS EMPTY.
RECORD DOES NOT CONTAIN ALL THE KEYS.
RECORD NUMBER MUST
INVALID RECORD NUMBER. RECORD NUMBER IS
BE POSITIVE INTEGER.
NEGATIVE, OUT OF RANGE, OR DELETED.
SEQUENCE ERROR IN PRIMARY KEY; ATTEMPT TO
WRITE RECORD WITH PRIMARY KEY LESS THAN
PREVIOUS KEY WHEN ASCENDING SEQUENCE
EXPECTED.
INVALID KEY LENGTH.
INVALID KEY SPECIFICATION; KEYS ILLEGAL.
INVALID DEVICE SPECIFICATION.
INVALID RECORD FORMAT.
185
186
187
188
189
A-4
MEANING
USER LACKS SAVE FILE CAPABILITY
ERROR MESSAGES AND RECOVERY PROCEDURES
Table A-1. File System Error Codes (continued)
CODE
190
191
192
193
194
195
196
197
198
193
..
.
200
201
..
.
255
MEANING
ACTION
INVALID KEY BLOCKING FACTOR VALUE.
RECORD DOES NOT CONTAIN SEARCH KEY FOR
DELETION. SPECIFIED KEY VALUE POINTS TO
RECORD WHICH DOES NOT CONTAIN THAT VALUE.
RUN KEY INFO OF
SYSTEM FAILURE OCCURRED WHILE KSAM FILE
KSAMUTIL TO
WAS OPENED
RESET FLAG.
$STDIN/$STDINX CANNOT BE REDIRECTED TO
KSAM FILES.
KSAM FILES NOT ALLOWED FOR GLOBAL AFT'S.
GLOBAL FILES CANNOT BE REMOTE FILES.
LANGUAGE NOT SUPPORTED.
NATIVE LANGUAGE INTERNAL ERROR.
INVALID VERSION NUMBER IN KSAM FILE.
RESERVED FOR KSAM
RESERVED FOR FUTURE USE
ERROR MESSAGES AND RECOVERY PROCEDURES
A-5
Table A-2. COBOL Status Parameter Return Values
STATUS
VALUE
MEANING
\00&quot;
SUCCESSFUL COMPLETION|I/O operation
was completed successfully.
\02&quot;
None required, returned for
SUCCESSFUL COMPLETION, DUPLICATE
KEY|Read or Readbykey read a record whose information only.
key value was the same as the equivalent key in
the next sequential record; this is not an error
since duplicate alternate keys are allowed. Write
or rewrite operation was successful; a duplicate
key was written for a key that is allowed
duplicates.
\10&quot;
AT END|End-of-le or beginning-of-le reached Usually none. This result is a signal to
close the le or perform another
during sequential or random read. There is no
next logical record in ascending key order.
end-of-le action.
\21&quot;
INVALID KEY, SEQUENCE ERROR|Attempt
was made to write a record with a primary key
that is out of sequence when the le was opened
for sequential access.
Check the primary key value in the
record being written. If you don't
want sequence checking, re-open the
le for random or dynamic access.
\22&quot;
INVALID KEY, DUPLICATE KEY|Attempt
was made to write or rewrite a record with a key
value that duplicates a key value in an existing
record, and duplicates are not allowed.
Check the key values. If possible
change them to avoid the duplication.
If duplicate keys must be written,
create the le again allowing duplicates
for the key and then copy the old le
to the new le with FCOPY.
\23&quot;
INVALID KEY, NO RECORD FOUND|
Attempt to access record identied by a key with
CKSTART or CKR EADBY KEY, but no record
is found with the specied key value at the
specied key location.
Check the keyvalue , keylength , an
keylocation parameters in the call,
Correct if necessary. If record that
cannot be found should be in the le,
you may want to list the data le with
FCOPY.
\24&quot;
INVALID KEY, BOUNDARY VIOLATION|
An attempt was made to write beyond the
externally dened end of le.
\30&quot;
LOCK DENIED|File was locked by another
process.
A-6
ERROR MESSAGES AND RECOVERY PROCEDURES
ACTION
None.
Wait until process locking le unlocks
it|try again or lock le with lockcond
= 1.
Table A-2. COBOL Status Parameter Return Values (continued)
STATUS
VALUE
MEANING
ACTION
\31&quot;
UNLOCK DENIED|File was not locked by
calling process.
Before calling CKUN LOCK to unlock
a shared le it must have been locked
by a call to CK LOCK.
\9n&quot;
FILE SYSTEM ERROR|Where n is a binary
number between 0 and 255 corresponding to a
File System Error code (Refer to Table A-1).
Within your program you can call
CKERROR to convert the number to
a displayable value and then display it.
Look up the value in Table A-1 and
perform any suggested action.
Note that COBOL error messages 752 and 753 are issued for errors processing KSAM les.
(Refer to Table C-2 in the COBOL manual.)
ERROR MESSAGES AND RECOVERY PROCEDURES
A-7
Table A-3. BASIC Status Parameter Return Values
STATUS
A-8
MEANING
ACTION
None.
\00&quot;
SUCCESSFUL COMPLETION|The current
I/O operation was completed successfully.
\02&quot;
None required. Returned for
SUCCESSFUL COMPLETION, DUPLICATE
information only.
KEY|In a call to BKREAD or
BKREADBYKEY, the current key has the same
value as the equivalent key in the next sequential
record; duplicate keys are allowed. Or in a call to
BKWRITE or BKREWRITE, the record just
written created a duplicate key value for at least
one key for which duplicates are allowed.
\10&quot;
AT END|A sequential read was attempted with Usually none. This result is a signal to
BKREAD, but there was no next logical record close the le or perform some other
end-of-le function.
in ascending sequence by key value, or random
read attempted to position to record with key
value less than lowest value or greater than
greatest value.
\21&quot;
INVALID KEY, SEOUENCE ERROR|
BKWRITE attempted; record being written has
primary key that is not in sequential order but
le was opened for sequence checking. BK
REWRITE attempted, but the primary key
value was changed since the record being
rewritten was read.
Check the primary key value in the
record; if you don't want sequence
checking, reopen the le with sequence
= 0. Check the primary key value.
Either change it back to the original
value or read the record again before
calling BKREWRITE.
\22&quot;
INVALID KEY, DUPLICATE KEY ERROR|
BKWRITE or BKREWRITE attempted to write
record that contains a duplicate value for a key
that is not allowed duplicate values.
Check the key value. If possible
change it to a unique value. If
duplicate keys must be written, create
the le again allowing duplicate values
for the key and then copy the old le
to the new le.
\23&quot;
INVALID KEY, NO RECORD FOUND|
BKSTART or BKR EADBYKEY attempted to
locate a record by a key value that could not be
found.
Check the key value, and key location
parameters. Correct if necessary. If
record that cannot be found should be
in le, you may want to list data le
with FCOPY.
\24&quot;
INVALID KEY, BOUNDARY VIOLATION|
BKWRITE attempted to write beyond the
externally dened boundaries of the le.
Re-enter command.
ERROR MESSAGES AND RECOVERY PROCEDURES
Table A-3. BASIC Status Parameter Return Values (continued)
STATUS
MEANING
ACTION
\71&quot;
REQUEST DENIED, FILE ALREADY
LOCKED|BK LOCK was called with
conditional locking and the le was already
locked by another user.
Perform some action that does not
require exclusive access and then try
BK LOCK again. As soon as the other
user unlocks the le BKLOCK will
work.
\81&quot;
INVALID CALL, WRONG NUMBER OF
PARAMETERS|A procedure call had too
many or too few parameters.
Check the call syntax and correct; if
not sure of error, consult manual.
\82&quot;
INVALID CALL, INVALID PARAMETER|
Specied parameter is not the correct type. For
example, a string variable was specied where
only numeric variables or constants are allowed.
Check the parameter and compare it
to the rules specied in this manual for
the parameter format.
\83&quot;
INVALID CALL, INSUFFICIENT INTERNAL
BUFFER SPACE|The data to be written to
the le is too long for the congured internal
buer space.
You can ask the system manager to
recongure the system, or you may be
able to reduce the amount of data
being written from parameterlist
\9xxx &quot;
FILE SYSTEM ERROR|An MPE le system Within your program you can call
error occurred for which the value xxx species a BKER ROR to display a message with
the meaning of the code; you can
3-digit code between \0&quot; and \255&quot;.
consult Table A-1 for the code
meaning.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-9
Table A-4. KSAMUTIL Error Codes and Messages
CODE
MESSAGE
MEANING
ACTION
1000
COMMAND FILE READ
ERROR.
1001
COMMAND FILE END OF
FILE.
1002
UNKNOWN COMMAND.
TYPE HELP.
1003
TOO MANY PARAMETERS More parameters specied
than are allowed.
FOR THIS COMMAND.
1004
COMMAND FILE DATA
TRANSMISSION ERROR.
1005
COMMAND TOO LONG.
1006
FILE NAME TOO LONG OR File name in BUILD
ABSENT.
command incorrect.
1007
'REC' PARAMETER LIST
EXHAUSTED.
Too many parameters
specied after REC= in
BUILD command.
Check syntax and reenter
with correct number of
parameters.
1008
'REC' RECORD SIZE
VALUE INVALID.
Record size in BUILD
command is not valid.
Check syntax and reenter
with correct value for
record size.
1009
'REC' BLOCKING FACTOR Block factor in BUILD
command is not valid.
VALUE INVALID.
Check syntax and reenter
with correct value for
blocking factor.
1010
'REC' RECORD FORMAT
VALUE INVALID.
Record format in BUILD
command is not F or V.
Enter V for variable
length records, F for
xed length, or omit for
xed length.
1011
'REC' RECORD TYPE
VALUE INVALID.
Record code in BUILD
command is not ASCII or
BINARY.
Enter ASCII for
ASCIIcode records;
BINARY or omit for
binary-coded records.
1012
'DEV' DEVICE VALUE
ABSENT.
No device specication after
DEV= in BUILD command.
Enter legal device name
or omit if device class is
DISC.
A-10
Command name not
recognized.
ERROR MESSAGES AND RECOVERY PROCEDURES
Type the correct name if
you know it; else type
HELP.
Check the command
syntax and reenter
correctly.
Enter le name of 8 or
fewer alphanumeric
characters starting with
a letter.
Table A-4. KSAMUTIL Error Codes and Messages (continued)
CODE
MESSAGE
MEANING
ACTION
Device specication in BUILD Enter legal device class
name or legal logical
command is not valid.
device number. Refer to
System Manager/System
Supervisor Manual .
1013
'DEV' DEVICE VALUE
INVALID.
1014
Enter device name that
'DEV' DEVICE VALUE TOO DEV= missing device
LONG OR ABSENT.
specication or one that is too is 1 to 8 alphanumeric
characters, begins with a
long.
letter, terminates with
nonalphanumeric
character; or omit DEV=
for DISC; or enter logical
device number.
1015
'KEY' SPECIFICATIONS
EXCEED LIMIT.
Too many KEY=
specications in BUILD.
1016
'KEY' CONTAINS TOO
MANY PARAMETERS.
More than 5 parameters follow Parameters are: keytype ,
keylocation , keysize , and
KEY= in BUILD.
optionally, keyblocking ,
and DUP or
DUPLICATE.
1017
'KEY' TYPE VALUE
INVALID.
Invalid key type specied after Key types may be: B, I,
D R, L, N, P,*. Enter
KEY= in BUILD.
one of correct types.
1018
'KEY' POSITION VALUE
ABSENT.
The key location is missing
from KEY= in BUILD
command.
1019
'KEY' POSITION VALUE
INVALID.
Invalid keylocation parameter Key location is specied
specied after KEY= in
as integer between 1 and
number of bytes in
BUILD.
record.
1020
'KEY' SIZE VALUE
REQUIRED AND ABSENT.
The key size is missing from
KEY= in BUILD command.
Enter required keysize
parameter after
keylocation in KEY=
specication.
1021
'KEY' SIZE VALUE
INVALID.
Invalid keysize parameter
specied after KEY= in
BUILD.
Key size is specied as
the number of bytes in
the key; refer to table
02-02 for legal sizes for
each key type.
Reduce number of keys
to a total of 16.
Enter required
keylocation parameter
following keytype type in
KEY= specication.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-11
Table A-4. KSAMUTIL Error Codes and Messages (continued)
CODE
MESSAGE
MEANING
ACTION
1022
'KEY' BLOCKING FACTOR Invalid key blocking
parameter specied after
VALUE INVALID.
KEY= in BUILD.
Specify keyblocking as an
even number equal to or
greater than 4; or omit
for key blocks with four
keys per block.
1023
CONFLICTING OPTIONS
Check command syntax
1024
MISSING CLOSING QUOTE
Check command syntax
1025
'KEY' 'DUPLICATE'
EXPECTED.
Key word DUP or
DUPLICATE expected in
KEY= specication.
Enter DUP or
DUPLICATE or remove
terminating commas.
1026
'DISC' MUST BE
FOLLOWED BY '='.
Key word DISC in BUILD
command was specied
without =.
Reenter DISC= followed
by up to 3 parameters
describing disc le, or
omit for defaults.
1027
'DISC' NUMBER OF
RECORDS VALUE
INVALID.
Value of numrecs parameter to Enter maximum number
DISC= not a positive integer. of records as le size, or
omit for default value of
1023 records.
1028
Value of numextents not in
'DISC' NUMBER OF
EXTENTS VALUE INVALID. range 1-32.
1029
'DISC' INITIAL
ALLOCATION VALUE
INVALID.
1030
'LABELS' NOT FOLLOWED Key word LABELS in BUILD
BY '=' OR BY TOO MANY command was specied
without = or had more than 1
PARAMETERS.
parameter.
1031
'LABELS' NUMBER OF
LABELS VALUE INVALID.
A-12
Enter integer between 1
and 32, or omit for
default value of 8 extents.
Value of initalloc not in range Enter integer between 1
and 32, or omit for
1-32.
default value of 1 extent
allocated when le is
opened.
ERROR MESSAGES AND RECOVERY PROCEDURES
Reenter LABELS=
followed by one
parameter to specify
number of user labels, or
omit for default of 0.
Table A-4. KSAMUTIL Error Codes and Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
Reenter
FIRSTREC=followed by
starting record number,
or omit to start
numbering records with
zero.
1032
Key word FIRSTREC in
'FIRSTREC' NOT
FOLLOWED BY '=' OR BY BUILD command was
TOO MANY PARAMETERS. specied without = or had
more than 1 parameter.
1033
'FIRSTREC'STARTING
RECORD NUMBER MUST
BE 0 OR 1.
Value other than 0 or 1
entered for rst record
number.
Enter correct value or
omit for default of 0.
1034
'CODE' NOT FOLLOWED
BY '=' OR BY TOO MANY
PARAMETERS.
Key word CODE in BUILD
command was specied
without = or had more than
one parameter.
Reenter CODE =
followed by lecode , or
omit for le code of zero.
1035
'CODE' FILE NUMBER
VALUE INVALID.
Value not in range 0 through
1023 entered for le code.
Enter positive integer
between 0 and 1023, or
omit for default of 0.
1036
'KEYDEV' FOLLOWED BY Key word KEYDEV= in
TOO MANY PARAMETERS. BUILD command was
specied with more than 1
parameter.
1037
'KEYDEV' MUST BE
FOLLOWED BY'='.
Key word KEYDEV= not
followed by =.
Reenter KEYDEV=, or
omit for default device
class DISC.
1038
'KEYDEV' DEVICE
PARAMETER VALUE TOO
LONG OR ABSENT.
Key word KEYDEV= must
be followed by valid device
parameter.
Reenter with device class
specied as 1 to 8
alphanumeric characters
beginning with letter,
terminated by
non-alphanumeric
character, or reenter with
logical device number, or
omit for default DISC.
1039
Key word KEYFILE in
'KEYFILE' NOT
FOLLOWED BY '=' OR BY BUILD command was
TOO MANY PARAMETERS. specied without = or had
more than 1 parameter.
Reenter KEYENTITY =
followed by actual le
designator of key le.
1040
KEY FILE NAME TOO
LONG OR ABSENT.
Reenter KEYENTITY =
with correct le name
format. (Refer to BUILD
description in manual.)
File name specied as
KEYENTITY = parameter is
more than 8 characters or was
omitted.
Reenter with one
parameter to specify
device class or logical
device number of key le,
or omit for DISC.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-13
Table A-4. KSAMUTIL Error Codes and Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
1041
Keyword KEYENTR IES in
'KEYENTRIES' NOT
FOLLOWED BY '=' OR BY BUILD command was
TOO MANY PARAMETERS. specied without =, or had
more than 1 parameter.
Reenter KEYENTRIES=
followed by the
maximum number of
primary key entries
expected in the key le,
or omit for default of
numrecs value from
REC=parameter.
1042
'KEYENTRIES' NUMBER
OF
ENTRIES VALUE
INVALID.
1043
KEYWORD
SPECIFICATION IN THIS
COMMAND IS INVALID.
A key word specied as a
KSAMUTIL command
parameter is misspelled or not
in syntax.
Check command syntax
for correct key word
and/or spelling; reenter
correctly.
1044
DELIMITER AT THE END
OF A SPECIFICATION IS
INVALID.
A delimiter follows command
specication in KSAMUTIL
command.
Remove delimiter or
follow with rest of
command.
1045
THE NUMBER OF
PARAMETERS IN THIS
COMMAND IS INVALID.
Too many or too few
parameters specied in a
KSAMUTIL command.
Check command syntax
and reenter with the
correct number of
parameters.
A-14
ERROR MESSAGES AND RECOVERY PROCEDURES
Table A-4. KSAMUTIL Error Codes and Messages (Continued)
CODE
MESSAGE
MEANING
The key word TEMP was
expected as a parameter in
PURGE or RENAME
commands.
ACTION
Check command syntax,
reenter with correct
parameter value.
1046
A PARAMETER VALUE IS
INVALID. 'TEMP'WAS
EXPECTED.
1047
LOCKWORD NOT
ALLOWED IN KEY FILE
Check command syntax;
remove lockword from
key le specication.
1048
GROUP AND/OR
ACCOUNT NOT ALLOWED
FOR KEYENTITY =
Check command syntax
of BUILD command.
1049
BACK REFERENCE NOT
ALLOWED ON formaldesignator
1050
SEQ=SEQUENCE NUMBER Non-numeric sequence number Check command syntax
specied for SEQ= parameter. of KEYSEQ or
IS INVALID
KEYDUMP commands.
1051
SUBSET= VALUE INVALID Either the starting position or Check command syntax
the number of key values to be of KEYDUMP command
dumped is invalid.
1052
SEQ= SYNTAX ERROR
1053
SEQ= PARAMETER LIST
EXHAUSTED
Not enough information in
parameter list; key number
missing.
Enter parameter value
for SEQ= in KEYSEQ or
KEYDUMP commands.
1054
ENTITY = PARAMETER
LIST EXHAUSTED
Not enough information in
parameter list; le name
missing.
Enter le name after
ENTITY = in
KEYDUMP command.
1055
ENTITY = SYNTAX
ERROR
1056
SUBSET= PARAMETER
LIST EXHAUSTED
Check command syntax
of KEYSEQ or
KEYINFO
Check command syntax
of KEYDUMP
command.
Not enough information in
parameter list.
Check command syntax
of KEYDUMP; enter
correct number of
parameters.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-15
Table A-4. KSAMUTIL Error Codes and Messages (Continued)
CODE
MESSAGE
1057
SUBSET= SYNTAX ERROR
1058
INVALID KEY SEQUENCE
SPECIFICATION
Key number specied in
SEQ= parameter is greater
than the number of keys in
le.
Key number is 1 for
primary key, 2 for rst
alternate key, etc. Use
VERIFY command to
check number of keys in
le.
1059
FILE SPECIFIED IN FILEALREADY EXISTS
File name specied in
ENTITY = parameter is an
existing permanent le;
KEYDUMP always creates a
new le.
Enter name of
non-existent le, or
rename permanent le.
1060
B-TREE HAS MORE THAN KEYDUMP cannot dump
20 LEVELS
more than 20 levels of the key
le structure.
1061
INVALID DECIMAL DIGIT
OR DIGIT COUNT &gt;28
1062
THE REFERENCED FILE IS File reference in the command Check le name and
correct it.
NOT A KSAM FILE
is not a KSAM le.
1063
RECORD SIZE OF THE
SPECIFIED FILE HAS
BEEN CHANGED
Record size of the le specied
in ENTITY = parameter of
KEYDUMP has been changed
by a : FILE command.
1064
GENERIC OR
APPROXIMATE SEARCH
NOT ALLOWED FOR KEY
TYPE
Generic or approximate keys Use full key value in
can be specied in SUBSET= SUBSET= or do not use
parameter of KEYDUMP only SUBSET= parameter.
if key type is BYTE,
INTEGER, or DOUBLE.
A-16
MEANING
ACTION
Check command syntax
of KEYDUMP
command.
Packed decimal digit is not
0-9, or there are more than 28
digits. Cannot convert to
ASCII for KEYDUMP.
ERROR MESSAGES AND RECOVERY PROCEDURES
Check KEYDUMP
syntax; change : FILE
command so that record
size is not specied.
Table A-4. KSAMUTIL Error Codes and Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
Change position value, or
use quoted string for
SUBSET= parameter.
1065
ILLEGAL OR TOO MANY
CHARACTERS
Position value of
SUBSETparameter in
KEYDUMP contains
non-numeric characters, or is
&gt;9 digits.
1066
REMOTE FILE ACCESS
NOT SUPPORTED
A :FILE command specied a Change : FILE command
remote le, but this command to specify local le.
does not support remote
access.
1067
SORT ON RECORD
POINTERS FAILS
Sort of keydump by record
pointers (SORT option of
KEYDUMP) failed during
sort by SORT/3000 program.
Check the reasons for
failure in SORT error
message.
1068
SYSTEM FAILURE
OCCURRED WHILE THE
KSAM FILE WAS OPEN
KSAM le was open when a
system failure occurred, and
le may be damaged.
Run KEYINFO
command to recover le
and reset ag so le can
be opened, or run
VERIFY with
NOCHECK to examine
le.
1069
UNEXPECTED
CHARACTER IN FILE
NAME; EXPECTED . or /
The only nonmeric characters Check the le name and
allowed in a le name are \.&quot; correct it.
or \/&quot;.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-17
Table A-5. FCOPY Warning and Error Messages
CODE
MESSAGE
None
&lt;CONTROL Y&gt;
None
READ ERROR FROM An error occurred while
reading an FCOPY
COMMAND
command from
INPUTFILE
$STDIN.
None
An error occurred while More than likely nothing
WRITE ERROR TO
serious has occurred and
COMMAND LISTFILE writing an FCOPY
message to $STDLIST. all FCOPY operations have
been performed
successfully. If you want to be
sure, however, do the
following:
In a job :
Re-submit the job.
In a session :
Re-enter the most recent
FCOPY command.
A-18
MEANING
ACTION
Acknowledges receipt of None.
a CONTROL-Y entered
during a session.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
3
SYNTAX ERROR: IN
SUBSET OPTION
The subset function was In a job :
not specied properly. Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
4
SYNTAX ERROR: IN
TITLE OPTION
The title option of the In a job :
display function was not Correct the command and
resubmit the job.
specied properly.
In a session :
Re-enter the command
using the correct format.
5
SYNTAX ERROR: IN
IGNERR OPTION
The ignore errors
function was not
specied properly.
ERROR MESSAGES AND RECOVERY PROCEDURES
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
Table A-5. FCOPY Warning and Error Messages (continued)
CODE
MESSAGE
MEANING
ACTION
6
SYNTAX ERROR: IN
VERIFY OPTION
The verify function was In a job :
not specied properly. Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
7
SYNTAX ERROR: IN
SKIPEOF OPTION
The skip end-of-le
function was not
specied properly
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format
8
SYNTAX ERROR: IN
COMPARE OPTION
The compare function
was not specied
properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
9
SYNTAX ERROR: IN
NEW OPTION
The new le function
was not specied
properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
10
SYNTAX ERROR: IN
HEX OPTION
The display
hexadecimal function
was not specied
properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
11
SYNTAX ERROR: IN The EBCDICOUT
EBCDICOUT OPTION character translate
function was not
specied properly.
12
SYNTAX ERROR: IN
CHAR OPTION
The display character
function was not
specied properly
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-19
Table A-5. FCOPY Warning and Error Messages (continued)
CODE
A-20
MESSAGE
MEANING
ACTION
13
SYNTAX ERROR: IN
OCTAL OPTION
The display octal
function was not
specied properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
14
SYNTAX ERROR: IN
UPSHIFT OPTION
The upshift function
was not specied
properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
15
SYNTAX ERROR: IN
BCDICIN OPTION
The BCDICIN
character translate was
not specied properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
16
SYNTAX ERROR: IN The NORECNUM
NORECNUM OPTION option of the display
function was not
specied properly.
17
SYNTAX ERROR: IN
EBCDICIN OPTION
The EBCDICIN
character translate
function was not
specied properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
18
SYNTAX ERROR: IN
BCDICOUT OPTION
The BCDICOUT
character translate
function was not
specied properly.
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
19
SYNTAX ERROR:
INVALID FORM OF
EXIT COMMAND
The EXIT command
was not specied
properly.
None. FCOPY terminates
ERROR MESSAGES AND RECOVERY PROCEDURES
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
Table A-5. FCOPY Warning and Error Messages (continued)
CODE
MESSAGE
MEANING
ACTION
In a job :
Correct the command and
resubmit the job,
In a session :
Re-enter the command
using the correct format.
51
SYNTAX ERROR: IN
QUOTED STRING
The characterstring
specied for the subset
function is not valid.
52
SYNTAX ERROR: IN
BIT PATTERN
The patternlist specied In a job :
for the subset function Correct the command and
resubmit the job,
is not valid.
In a session :
Re-enter the command
using the correct format.
53
SYNTAX ERROR:
INVALID INTEGER
An integer specied is
outside the range
allowed for the
particular FCOPY
function.
In a job :
Correct the command and
resubmit the job,
In a session :
Re-enter the command
using the correct format.
54
SYNTAX ERROR:
UNKNOWN OPTION
NAME
One of the specied
functions was
unrecognizable.
In a job :
Correct the command and
resubmit the job,
In a session :
Re-enter the command
using the correct format.
55
SYNTAX ERROR: IN
FROMFILE
SPECIFIER
The \from&quot; le was not In a job :
Correct the command and
specied properly.
resubmit the job,
In a session :
Re-enter the command
using the correct format.
56
SYNTAX ERROR: IN
TOFILE SPECIFIER
The \to&quot; le was not
specied properly.
In a job :
Correct the command and
resubmit the job,
In a session :
Re-enter the command
using the correct format.
57
SYNTAX ERROR:
ILLEGAL
COMBINATION OF
OPTIONS
Two or more
functionlist entries
conict with one
another.
In a job :
Correct the command and
resubmit the job,
In a session :
Re-enter the command
using the correct format.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-21
Table A-5. FCOPY Warning and Error Messages (continued)
CODE
MESSAGE
MEANING
ACTION
58
SYNTAX ERROR:
FROMFILE AND
TOFILE NOT BOTH
SPECIFIED
FROM= and TO= were In a job :
not both specied in the Correct the command and
resubmit the job,
FCOPY command.
In a session :
Re-enter the command
using the correct format.
59
SYNTAX ERROR:
ILLEGAL USE OF
NEW
In a job :
The context used to
specify a new \to&quot; le is Correct the command and
resubmit the job,
not valid.
In a session :
Re-enter the command
using the correct format.
60
SYNTAX ERROR:
ILLEGAL USE OF *
In a job :
The context used to
specify* as a \from&quot; le Correct the command and
or \to&quot; le is not valid. resubmit the job,
In a session :
Re-enter the command
using the correct format.
62
SYNTAX ERROR:
FILE NAME TOO
LONG
The \from&quot; or \to&quot; le
name specied is longer
than the 35 characters
allowed in a
fullyqualied le name
with lockword.
102
CAN'T CLOSE
FROMFILE
Look up the error number
MPE can't close the
in Table A-1 and act
\from&quot; le. This
message is followed by accordingly.
an MPE le information
display containing
(among other things) an
error number.
103
CAN'T CLOSE
TOFILE
Look up the error number
MPE can't close the
\to&quot; le. This message in Table A-1 and act
is followed by an MPE accordingly.
le information display
containing (among other
things) an error number.
A-22
ERROR MESSAGES AND RECOVERY PROCEDURES
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
Table A-5. FCOPY Warning and Error Messages (continued)
CODE
MESSAGE
MEANING
ACTION
If you don't have SF
capability, you can't
perform the operation.
If there is not enough le
space, purge some
unneeded les to free some
le space.
104
CAN'T SAVE NEW
TOFILE
MPE can't close the
\to&quot; le as a permanent
le. Either you do not
have SF capability or
there is not enough
group account, or
system le space.
105
CAN'T OPEN
FROMFILE
Look up the error number
MPE can't open the
in Table A-1 and act
\from&quot; le. This
message is followed by accordingly.
an MPE le information
display containing
(among other things) an
error number.
106
Look up the error number
CAN'T OPEN TOFILE MPE can't open the
\to&quot; le. This message in Table A-1 and act
is followed by an MPE accordingly.
le information display
containing (among other
things) an error number.
107
VERIFY OR
COMPARE OPTION:
CAN'T GET READ
ACCESS TO TO FILE
MPE can't get read
access to the \to&quot; le
for a verify or compare
operation. The read
access specied in the
le label has been
overridden by an MPE
:FILE command
containing
ACC=APPEND,
ACC=OUT, or
ACC=OUTKEEP.
108
ERROR IN CALLING
FGETINFO FOR
FROMFILE
Look up the error number
An error prevented
in Table A-1 and act
MPE from obtaining
accordingly.
information from the
\from&quot; le's label. This
message is followed by
an MPE le information
display containing
(among other things) an
error number.
Reset the particular : FILE
command (using the MPE
: RESET command) and
retry the operation.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-23
Table A-5. FCOPY Warning and Error Messages (continued)
CODE
MESSAGE
MEANING
ACTION
109
ERROR IN CALLING
FGETINFOR FOR
TOFILE
Look up the error number
An error prevented
in Table A-1 and act
MPE from obtaining
accordingly.
information from the
\to&quot; le's label. This
message is followed by
an MPE le information
display containing
(among other things) an
error number.
110
IGNERR OPTION:
FROM FILE NOT
TAPE
The \from&quot; le's device The ignore errors function
is not a magnetic tape cannot be used in this case.
unit.
111
CAN'T GET READ
ACCESS TO
FROMFILE
MPE can't get read
access to the \from&quot;
le. The read access
specied in the le label
has been overridden by
an MPE :FILE
command containing
ACC=APPEND,
ACC=OUT, or
ACC=OUTKEEP.
Reset the particular : FILE
command (using the MPE
: RESET command) and
retry the operation.
112
MPE can't get write
CAN'T GET WRITE
ACCESS TO TO FILE access to the \to&quot; le.
The write access
specied in the le label
has been overridden by
an MPE :FILE
command containing
ACC=IN.
Reset the particular : FILE
command (using the MPE
: RESET command) and
retry the operation.
113
SKIPEOF OPTION:
FROM FILE NOT
TAPE
The skip end-of-le
function was specied
for the \from&quot; le and
the \from&quot; le device is
not a magnetic tape
unit.
If the intended \from&quot; or
\to&quot; le is on magnetic
tape, check the associated
MPE :FILE command and
the back reference to it.
114
SKIPEOF OPTION:
TOFILE NOT TAPE
The skip end-of-le
function was specied
for the \to&quot; le and the
\to&quot; le device is not a
magnetic tape unit.
If the intended \from&quot; or
\to&quot; le is on magnetic
tape, check the associated
MPE :FILE command and
the back reference to it.
A-24
ERROR MESSAGES AND RECOVERY PROCEDURES
Table A-5. FCOPY Warning and Error Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
115
SUBSET OPTION:
STRING FALLS
OUTSIDE OF
FROMFILE RECSIZE
The characterstring or Change the specied subset
denition to a valid one
patternlist specied is
greater than the record and try the operation again.
size of the \from&quot; le.
No such subset can exist
in the specied \from&quot;
le.
116
CAN'T GET LARGE
ENOUGH BUFFER
There is not enough
data space for the
buers needed by the
requested operation.
FCOPY uses the
DL-DB area for variable
sized buers.
117
SKIPEOF OPTION:
ERROR WHILE
SKIPPING IN
FROMFILE
An error occurred while Retry the operation.
skipping end-of-le
marks in the \from&quot; le.
118
An error occurred while Retry the operation.
SKIPEOF OPTION:
skipping end-of-le
ERROR WHILE
SKIPPING IN TOFILE marks in the \to&quot; le.
119
SUBSET OPTION:
ERROR WHILE
SPACING IN
FROMFILE
An error occurred while Retry the operation.
spacing through the
\from&quot; le.
120
SUBSET OPTION:
SUBSET STARTS
OVER EOF
BOUNDARY
The subset specied
extends over an
end-of-le mark or a
tape mark boundary.
Change the specied subset
denition to a valid one
and try the operation again.
123
SUBSET OPTION:
THIS INPUT DEVICE
DOES NOT
BACKSPACE
The specied subset
requires backspacing in
the \from&quot; le but the
device for that le is not
a disc or magnetic tape.
Check the MPE :FILE
command associated with the
\from&quot; le and the back
reference to it.
Ask the system manager
what size data area was
specied when FCOPY
was prepared and rerun
FCOPY specifying a larger
MAXDATA= parameter.
Also make sure that the
system conguration will
accommodate your record
size in the maximum
allowed data segment size.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-25
Table A-5. FCOPY Warning and Error Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
An error occurred while Retry the operation.
spacing through the
\from&quot; le in search of
the start of a subset.
124
READ ERROR IN
FROMFILE AT
RECORD recnum
125
Change the specied subset
SUBSET OPTION:
A subset specied by
NUMERIC SUBSET IS starting - record-number , denition to a valid one
and try the operation again.
number-of - records ,
EMPTY
and/or last-record number does not exist
or contains no data.
126
VERIFY OPTION:
ERROR WHILE
REWINDING
FROMFILE
127
An error occurred while Retry the operation.
VERIFY OPTION:
spacing backward to the
ERROR WHILE
REWINDING TOFILE beginning of the \to&quot;
le at the start of a
verify operation.
128
EOF FOUND WHILE
SPACING IN
FROMFILE
An end-of-le mark was
encountered while
spacing through the
\from&quot; le in search of
the start of a subset.
This most often occurs
when the \from&quot; le is a
blocked magnetic tape.
For a blocked magnetic
tape, the record
numbers supplied in the
SUBSET= parameter
are used as block
numbers.
Retry the operation
specifying block numbers instead
of record numbers.
OR
Reblock the tape so each
block contains one record
and then retry the
operation.
129
EOF FOUND WHILE
SPACING IN TOFILE
An end-of-le mark was
encountered while
spacing through the
\to&quot; le in search of the
start of a subset during
a compare or verify
operation
Compare operation :
The \from&quot; and \to&quot; les
are not identical. Display
the \to&quot; le to determine
what it actually contains.
Verify operation :
The copy operation was
not performed correctly.
Retry the operation.
A-26
An error occurred while Retry the operation.
spacing backward to the
beginning of the \from&quot;
le at the start of a
verify operation.
ERROR MESSAGES AND RECOVERY PROCEDURES
Table A-5. FCOPY Warning and Error Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
131
ERROR WHILE
WRITING EOF TO
TOFILE
An error occurred while Retry the operation
writing an end-of-le
mark in the \to&quot; le.
l32
VERIFY OPTION:
ERROR WHILE
SPACING IN THE
FROMFILE
An error occurred while Retry the operation
spacing through the
\from&quot; le during a
verify operation.
133
VERIFY OPTION:
ERROR WHILE
SPACING IN THE
TOFILE
An error occurred while Retry the operation
spacing through the
\to&quot; le during a verify
operation.
134
WARNING: FOUND
EOF IN TOFILE
FCOPY has performed
the specied operation
but has lled the \to&quot;
le before completing
the operation.
135
WRITE ERROR TO
TOFILE
An error occurred while Retry the operation.
writing to the \to&quot; le.
136
READ ERROR FROM An error occurred while
TOFILE
reading from the \to&quot;
le during a compare or
verify operation.
The \to&quot; le was not
large enough. Use the
MPE :LISTF lename ,2
command to determine
the \to&quot; le's size and
then increase its size (using
the MPE :PURGE and
:BUILD commands) and
retry the operation.
Compare operation :
Retry the operation. If
the error persists, you
must try to recreate the
\to&quot; le.
Verify operation :
Retry the operation.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-27
Table A-5. FCOPY Warning and Error Messages (Continued)
CODE
MESSAGE
MEANING
137
WARNING: AN
UNLABELLED TAPE
OPERATION ENDS
ON AN ERROR
An operation involving
a magnetic tape \from&quot;
le was terminated by
reading beyond the end
of valid data rather
than by sensing an
end-of-le mark.
This is not an error. You
can avoid this message by
reading the \from&quot; tape
one le at a time and using
the keyword SUBSET.
138
TITLE OPTION:
TITLE TOO LONG
The title specied for
the list function is
longer than the 70
characters allowed or it
extended over more
than one line (record).
In a job :
Correct the command and
resubmit the job.
In a session :
Re-enter the command
using the correct format.
139
DUMP OPTION:
TOFILE RECSIZE
NOT WITHIN LEGAL
LIMIT
A le display was
directed to an
intermediate storage
device with an incorrect
record size. That record
size must be 60 bytes
(30 words).
Change the record size of
the intermediate storage
le (using the MPE
:PURGE and :BUILD
commands) so that it is
within the allowed range
and then retry the
operation.
140
COMPARE OR
VERIFY OPTION:
OPERATION FAILS;
DIFFERENT FIXED
RECSIZES
The compare or verify
operation was not
attempted because the
record sizes of the \to&quot;
and \from&quot; les are not
identical.
Compare operation :
None. The compare
operation revealed that the
xed record sizes of the
two les are not identical.
Verify operation :
Change the record size of
the \to&quot; le (using the
MPE :PURGE and :BUILD
commands) so that it is
the same as that of the
\from&quot; le and then retry
the operation.
141
COMPARE BEGINS
The comparison phase None.
of a verify operation has
begun.
A-28
ERROR MESSAGES AND RECOVERY PROCEDURES
ACTION
Table A-5. FCOPY Warning and Error Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
None. You may have
accidentally specied the
wrong le as the \from&quot;
le.
143
The \from&quot; le
WARNING:
FROMFILE IS EMPTY contained no data.
Nothing was copied or
compared.
144
NEW OPTION: FILE
ALREADY EXISTS
The \to&quot; le named for Change the name of the
\to&quot; le and try the
the new le function
operation again.
already exists in the
specied (or implied)
group and account.
145
BACKSPACE ERROR
IN FROMFILE
An error occurred while Retry the operation.
spacing backward to the
beginning of the \from&quot;
le or a subset within it.
200
WARNING:
FROMFILE RECSIZE
IS number type ,
TOFILE RECSIZE IS
number type
The record sizes of the
\from&quot; and \to&quot; les
are not identical.
201
The data formats of the
WARNING:
FROMFILE IS ASCII, \from&quot; and \to&quot; les
TOFILE IS BINARY or are not identical.
WARNING:
FROMFILE IS
BINARY, TOFILE IS
ASCII
In a job :
FCOPY performs the
specied operation despite
the conict.
In a session :
You are given the choice
whether or not to continue
the operation.
Note that if the \from&quot;
record size is larger than
the \to&quot; record size, the
\from&quot; records would be
truncated. If the \to&quot;
record size is larger than
the \from&quot; record size, the
content of the excess byte
positions in the \to&quot;
records is unpredictable.
In a job :
FCOPY performs the
operation despite the conict.
In a session :
You are given the choice
whether or not to continue
the operation.
ERROR MESSAGES AND RECOVERY PROCEDURES
A-29
Table A-5. FCOPY Warning and Error Messages (Continued)
CODE
MESSAGE
MEANING
ACTION
Retry the operation. If
the error persists, use the
subset function to copy
all of the le except the
erroneous record.
301
READ ERROR IN
FROMFILE AT
RECORD recnum
An error occurred while
reading from the \from&quot;
le at the record
number displayed
(recnum ).
302
VERIFY OPTION:
RAN OUTOF VERIFY
ERRORS AT
FROMFILE RECORD
recnum
The verify function was Retry the operation
terminated because the specifying a larger number-of errors parameter.
specied maximum
number of errors has
been exceeded at the
record number displayed
(recnum ).
304
COMPARE OPTION:
RAN OUT OF
COMPARE ERRORS
AT FROMFILE
RECORD recnum
Retry the operation
The compare function
was terminated because specifying a larger number-of the specied maximum errors parameter
number of errors has
been exceeded at the
record number displayed
(recnum ).
901
The beginning or end of
KSAM FROMFILE
BOUNDARY (EOF OR the from le was
reached during the copy
BOF)
operation.
902
KSAM FROMFILE
POSITIONING
ERROR
Could not position to
desired place.
Try again.
903
ERROR; WRONG
CONDITIONS FOR
OPENING NEW
KSAM FILE
From le is not a
KSAM le, or NO
KSAM was specied.
Create a KSAM le before
running FCOPY and copy
to that le.
A-30
ERROR MESSAGES AND RECOVERY PROCEDURES
B
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
OVERVIEW
KSAM les can be used eciently without any knowledge of how the les are structured
or how le blocking and size is determined. The default values provided for le capacity,
key blocking, number of key entries, and so forth are eective in many applications. This
appendix provides the sophisticated programming sta with information on how KSAM
les are structured, how disc space is allocated to a KSAM le, and how memory space is
allocated for the Extra Data Segments used when a KSAM le is modied or accessed. Such
information may be useful for improving performance based on the particular application.
KSAM FILE STRUCTURE
A KSAM/3000 le is two physical les: a data le and a key le. The data le portion of a
KSAM le contains all the data in the le and contains nothing but the data. Data records
are written to the data le in the order in which they are received from a program. (The
last record added is always written to the end of the le.) This chronological order is not
necessarily in sequence by key value. At the time the le is opened, you can specify that
records must be written in primary key sequence, but the default mode is to write records in
any order.
The key le portion of a KSAM le contains the key entries that maintain the sequence of
the data records. As a data record is written to the data le, a key entry is added for each
key dened for the le, and the sequential connections between key entries maintained. This
means that if there is a primary key and two alternate keys, three key entries are added with
each new data record, and three sets of pointers are updated to reect the new key sequence
of each key.
The structure of the data le is like that of any MPE le. Data records may be xed or
variable in length. If xed, each record is the size specied when the le is created (default
size is equivalent to one 128-word disc sector). If variable, the actual size of each record is
included in the record itself, and the maximum size of any record is used to determine the
blocking. By default, data records are blocked one record per block.
The structure of the key le is more complex. The key le is organized so that locating
a particular key requires the least number of accesses. For this purpose, the key les are
organized in a particular structure known as a \B-Tree&quot;.1
Described in \Organization and Maintenance of Large Ordered Indexes&quot; Bayer and McCreight,
Acta Informatica, Springer Verlag,1972, pp 173-189.
B-tree structure has two main advantages:
The number of le accesses is limited to the number of levels in the tree. If there are two
levels, no more than two reads of the key le are needed to locate a particular key.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-1
The key le is balanced. This means that each level pointer associated with a particular key
value points to approximately as many higher key values as lower key values at the next
level of the tree.
B-tree structure in general is discussed below, followed by a discussion of how KSAM key les
use this structure.
B-TREE STRUCTURE
In a B-tree, there is always one root level block that points to blocks at a lower level. At the
lowest level, the blocks are called leaves and they do not reference another level. In a two-level
structure (see Figure B-1), the blocks at the second level all \leaves&quot;. If the tree has more
than two levels, intermediate blocks (nodes or branches) are referenced by a higher level and
themselves reference a lower level. Unless this lower level is a leaf, it also references a lower
level. This continues until the lowest (leaf) level is reached.
The notion of higher and lower level does not refer to the key values, The root block key
values are always central and point to blocks with lower values and blocks with higher values.
Thus if there are two entries at the root or a branch level, there will be three pointers to the
next level: one for key values less than the rst key value, one for key values less than the
second key value but greater than the rst, and one for key values greater than the second.
Within each block, values are stored in ascending order. Although not all blocks are lled
with values, each block in a tree is the same size. Figure B-1 illustrates a simple 2-level tree
with one root block and three leaf blocks. The root is a single block and each leaf is a block of
the same size. (This example uses the KSAM minimum key block size consisting of four key
entries per block.)
Figure B-1. Two-Level B-Tree Structure
B-2
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
ADDING OR DELETING KEYS.
When a key block is full and new keys are added, the root level block may need to be split,
causing a new root block to be introduced and adding a new level to the tree. This process is
illustrated in Figure B-2 where the addition of one new key to a partially lled block does not
aect the tree structure, but the addition of a second key to the full block causes the block to
split.
Again, this example assumes the minimum key block size for the sake of simplicity. Note
that all key le maintenance is performed in the KSAM extra data segment where space is
allocated for one more key than the key block size. This allows the addition of a key to a
\full&quot; block. Before the block is read back into the key le, it is split so that the key block
size is maintained.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-3
Figure B-2. Split Causes New Level in Tree
When the root block and all the leaves are full, another split becomes necessary. Figure B-3
illustrates a split caused when a new key is added to a full two-level tree structure, forcing it
to a three-level structure.
B-4
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Figure B-3. Tree Growth from Two to Three Levels
Note that key blocks must always be dened with an even number of keys. As a result, when
a key is added to a full block, there will be a middle value to form a block at a new level.
This maintains the balance essential to B-tree structure.
As records are deleted from the data le, two blocks at the same level (brothers) may be
merged into one block. If sucient records are deleted, the root block may be merged into a
higher level, thereby contracting the number of levels in the key structure.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-5
KSAM KEY FILE STRUCTURE
A KSAM key le consists of three types of information:
Control|contains general control information such as the KSAM lename, and the number
of keys dened for the le,
Key descriptor|contains general key information for each key such as the starting location
in the data record of the key eld, and the location in the key le of the root key entry.
Key entries|Each key entry contains information about a key associated with a data
record. This information consists of:
the key value
a pointer into a data record in the data le with the same key value.
pointers into other records within the key le.
The control and key descriptor information is contained in two blocks (physical records) at the
beginning of each le. Regardless of the number of keys in the le, each block is 128 words
(l sector) long. Thus, every key le is preceded by two sectors of control and key descriptor
information.
The key entries are also organized into blocks of a xed size. However, the exact number of
blocks and the size of each block is based on a variety of factors, such as the key size, the
number of keys in the le, the number of key values for each key, the key blocking factor,
and so forth. (Calculation of key block size is discussed later in this section.) These key
entry blocks are organized into the Btree structure discussed above. A separate key structure
is maintained for each key dened for the le, Thus there may be up to 16 separate tree
structures in a single KSAM le.
Refer to Figure B-4 for a simplilied diagram of a KSAM key le with two keys each organized
into a two level tree structure. For a detailed description of the three types of block, refer to
Figure B-5 and Figure B-6.
CONTROL BLOCK.
This 128-word block contains information on the data le associated with the key le, and
keeps track of the number and type of access to the key le. It also species the number of
keys (primary and alternate) dened for the KSAM le. The name of the data le and the
number of keys are essential for associating the key le with the data le. The number of keys
determines how many entries are in the Key Descriptor Block. (Refer to Figure B-5.)
KEY DESCRIPTOR BLOCK.
This 128-word block contains one 8-word entry for each key dened for the KSAM le. The
rst entry describes the primary key, the next entry describes the rst alternate key (if there
is one), and each subsequent entry describes any additional alternate keys. The rst word of
each entry points to the root block for that key; another important item is the location of the
key in the data le record. (Refer to Figure B-5.)
B-6
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Figure B-4. KSAM Key File Structure With Two Keys
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-7
Figure B-5. Control Block and Key Descriptor Block
KEY ENTRY BLOCKS.
Each block in the key le contains, in addition to the key values, pointers that link the key
blocks to each other and pointers that link each key value to an associated data record.
Preceding these entries, the rst item in every key block is the address of the block on disc;
the next item is the number of keys in the key block.
All key block access for search and modication is performed in the KSAM extra data
segment. The disc address in each key block insures that the block is returned to its correct
location on disc from the extra data segment.
B-8
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Figure B-6 illustrates the general layout of all key entry blocks. Each key value is followed
by a pointer to a data record and a pointer to the block at the next level with higher key
values. The rst, pointer in each block points to a block at the next level with lower key
values. These pointers are set to zero for key blocks that have no next level (the leaves on a
tree structure).
Figure B-6. Key Entry Block Structure
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-9
RELATION OF KEY TO DATA FILE
The purpose of the KSAM key le is to maintain the order of data records in the data le.
In order to maintain sequential order for each key, the keys blocks are connected through
pointers. In addition to these pointers, each key entry must also contain a pointer linking the
key value to the data record containing the corresponding key value.
When the KSAM le is created, each key is dened by its starting location in the data record,
its length, and its type. The location is specied as the character position where the key value
starts; the length is the maximum number of characters used by the key value; its type is the
type of the value such as, an integer, a character string, or a double-word integer.
Thus, if the primary key is dened as a character string that starts in character position 3 and
is 20 characters long, then KSAM expects that each data record will contain such a value in
that location. Whatever is placed in the dened location is treated as the primary key and
determines the order in which data records are sequenced.
The order in which records are physically written to the date le is called chronological
sequence . This sequence may or may not also be a key sequence . If the records were written
to the le in primary key sequence, then this sequence and the chronological sequence are the
same. If there is an alternate key for the le, however, it is very unlikely that alternate key
sequence is the same as the chronological sequence.
Note
Key sequence in KSAM les is always in ascending order by key value.
Refer to Figure B-7 for a simplied diagram of the relation between the primary keys in the
key le and the associated data records in the data le. (A similar diagram could be set up
for the alternate key.) The diagram shows the pointer in each key entry pointing directly to a
record in the data le.
When a data record is to be located by key value, the root block for the appropriate key is
searched rst, using a binary search method. If the key is in the root block, the search is over.
If it is not, the key value is between two root block values or it is less than the lowest value or
greater than the highest. Using the pointer in the appropriate location, a block at the next
level is located. This block is then searched for the selected key. Again, if the key is found,
the search is over. If the key is not found at this level, the appropriate pointer to the next
level is used and the search continues.
When the selected key value is found, the pointer to the data le associated with that key
value is used to locate the record in the data le.
B-10
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Figure B-7. Data File/Key File Relation
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-11
KSAM FILE SIZE
The size of the data le is calculated from the maximum number of data records times the
size of each record (for xed length records). For variable length records, it is calculated from
the maximum number of data blocks times the size of each block. By default, a KSAM data
le contains 1024 records (or blocks) in which each record (or block) is 1024 words long. This
default size ts each block into eight disc sectors (each sector is 128 words long), and results
in a data le of 8192 sectors.
Calculation of key le size is more complex. It is based on the total number of keys in the le
(primary and alternate), the size of each key entry (including overhead), the expected number
of data records specied when the le is built, plus space to allow for block splitting when the
number of key entries increases.
The number of key entries per key is usually exactly the same as the number of data records
expected. By default, KSAM uses the maximum number of data records specied, or the
default value of 1024 records. This number is multiplied by each key in addition to the
primary key to arrive at the total number of key entries in the le.
The size of each key entry and the number of key entries per block (the blocking factor) is
used to determine key block size. Since all blocks in the key le must be the same size, KSAM
adjusts the blocking factor so that all keys, regardless of entry size, use the same block size.
Also, this blocking factor may be adjusted so that disc sector space is not wasted. (A block
always starts on a sector boundary.) By default, the blocking factor is adjusted so that a
block size of 1024 words is used for all key blocks for all keys in the le.
Because of the nature of the B-tree structure, enough room must be left in the key le so that
the le can be increased in a balanced manner. When block splitting occurs as a result of
adding new key values, up to half of each key block may have empty slots. To allow for such
expansion, the key le size is calculated, and then doubled.
The following discussion describes exactly how KSAM calculates the key block size, and then
the total key le size. These calculations are useful primarily if you do not use default values
for the key blocking factor and for the number of key entries. In such a case, they may help
you determine the most eective block size and le size for your application.
KEY BLOCK SIZE
Key block size can aect the complexity of the tree structure and this complexity can aect
access time. In order to understand the relation between block size and access time, consider
the following general rules:
The larger the block, the less often it has to split and the fewer the splits, the fewer levels to
the tree .
The more levels to the tree, the more mass storage retrieval time is needed to locate a
particular y value .
From this it would follow that in order to reduce access time, you should dene large blocks.
This is true only up to a point. Depending on the total number of key values expected in
the le, a large block size may result in a great deal of unused space in each block. Also,
the blocking factor may result in unused disc space since all blocks must start on sector
boundaries.
B-12
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
KSAM provides a default blocking factor that produces a block with 1024(1K) words. This
size has proved to be ecient for many les. You may, however, override this default blocking
by specifying a value in the keyblocking parameter of the ;KEY= option in the BUILD
command, or in word 19 of the FOPEN ksamparam parameter. Note that any blocking factor
you specify is a minimum value since KSAM may increase the blocking factor so that the least
amount of disc space is wasted.
After creating a KSAM le, you can use the VERIFY command of KSAMUTIL to determine
the number of levels needed by the KSAM le. The VERIFY listing will also tell you the
actual blocking factor used in creating the le so you can nd out whether your specied
blocking factor has been increased.
CALCULATING KEY BLOCK SIZE.
Key block size is based on a number of factors:
The key size is bytes (KS)
The key entry size in words (ES).
The number of key entries per block, the blocking factor (BF).
Once the block size is determined, the number of sectors needed to hold one block is
calculated. If this value (NB) wastes sector space, KSAM adjusts the blocking factor to
produce a block size that uses the least number of sectors by lling each sector as completely
as possible. Note that when KSAM uses the default block size of 1024, it calculates a blocking
factor by the same method.
The following steps show how KSAM determines block size based on a specied minimum
blocking factor.
Note
The notation j j means round down the result of the enclosed algorithm to
the next whole number; j j means round it up.
1. Calculate the entry size (ES) in words from the key size (KS) in bytes, and then add
two words for each pointer in the key entry (see Figure B-6). KSAM uses the following
algorithm to perform this calculation:
ES = |_(KS+I)/2_| + 4
2. If the blocking factor (BF) was specied as an odd number, KSAM issues an error message.
Otherwise, it uses the specied blocking factor to continue the calculation of block size.
3. Determine blocksize (BS) by multiplying the key entry size by the blocking factor and
adding 5 words. (The ve words are for the three words of control information at the
beginning of each block, plus two words for the nal pointer in the block. See Figure B-6).
KSAM uses the algorithm:
BS = (ES x BF) + 5
Since blocks always start on sector boundaries, this calculated block size may leave a lot of
unused sector space. The following steps show how KSAM determines the most ecient
block size and, if this size diers from the size calculated from the specied blocking factor,
how KSAM adjusts this blocking factor upwards to produce the optimum block size.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-13
4. Determine the number of sectors required to hold the block at its calculated size. If the
result is not a whole number, round it up to the nearest whole sector. KSAM determines
the number of sectors per block (NB) as follows:
NB = | BS/128 |
5. Multiply the number of sectors per block by 128 to determine the optimum block size:
BS = NB x 128
6. If the optimum block size calculated in step 5 diers from the block size calculated in
step 3, or if the default block size 1024 is used, KSAM adjusts the blocking factor to one
that produces the optimum block size. It uses the following algorithm to determine the
number of key entries that t in the block and, if this is an odd number, reduces it by one.
(Blocking factor must be an even number.)
BF = F | (|_(BS-5)/ES _|
01)/2
|x 2
KEY FILE SIZE
KSAM uses the blocking factor and the number of sectors per block to detenrmine the
maximum le size in sectors to allocate to the key le. In addition, KSAM needs to know the
maximum number of key entries to expect, and the number of keys (primary and alternate)
dened for the key le at creation.
The maximum number of key entries for each key may be specied in the numentries
parameter of the KEYENTRIES= option of the BUILD command, or in the ksamparam
parameter of FOPEN. However, this le limit is usually based on the maximum number of
data records. This value is specited in the numrec parameter of the DISC= option of the
BUlLD command, or in the lesize parameter of FOPEN. If not specied in either of these
places, KSAM assumes a default le limit of 1024 key entries.
Since the number of records in the data le can be used to calculate the maximum number
of keys for only one key, each additional key dened for the le causes the le sizes to be
summed.
When key le size has been calculated, KSAM uses this value to allocate that number of
sectors on disc to the key le whenever the le is opened.
Key le size is based on the following factors:
The number of key entries per block, or the blocking factor (BF).
The number of blocks per sector (NB).
The maximum number of key entries for one key (FL).
The number of keys dened for the key le.
KSAM uses the following formula to determine key le size in sectors for a le with one key:
FBS = (| FL/BF |x 2) x NB
This formula is derived through the following steps:
1. The maximum number of key entries (FL) is divided by the number of key entries per
block (BF) to nd the number of blocks in the le. If not a whole number, it is rounded up
to include all blocks.
B-14
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
2. The resulting number of blocks is multiplied by 2. This doubling of the number of key
blocks is done to allow room for expansion when the number of levels in a key le expands
due to block splitting.
3. Finally, the number of blocks is multiplied by the number of blocks per sector (NB) to nd
the total number of sectors needed to contain all key entries.
Note
The le size (FS) calculated by the above algorithm does not include the two
sectors required for control information.
If the le has only one key, add 2 to the le size (FS+2) to get the total le size. The value
2 represents the two sectors at the beginning of each key le containing control and key
descriptor information.
If the key le has multiple keys, then the optimum block size of each key must be determined.
The largest block size is then selected as the standard block size for all keys in the le (KSAM
does not allow variable-length key blocks). Since the block size of some keys has changed, the
blocking factor (BF) must be recalculated for these keys using the algorithm:
BF = | (|_(BS-5)/ES_|01)/2 |x 2
A separate le size for each key is then calculated based on their various blocking factors. The
total key le size is equal to the sum of all these le size (FS) values plus 2 for the two control
sectors.
Figure B-8 summarizes the steps KSAM uses to calculate le size for one key. Figure B-9
shows how KSAM calculates key le size for a le with two keys. Each key le size (FS) is
calculated separately, and then the blocking factor and le size of the key with the smaller
block size is recalculated.
For a le with one key, KSAM simply adds 2 sectors to the le size (FS) calculated for the
single key.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-15
Figure B-8. Formula to Determine File Space per Key
B-16
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Figure B-9. Calculation of Total Key File Size with Two Keys
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-17
KSAM EXTRA DATA SEGMENTS
Another factor that may aect performance when KSAM les are used, is the number and size
of KSAM extra data segments. An extra data segment (XDS) is an area in memory used as a
buer during KSAM le access. Each extra data segment contains:
Statistical information on le use (listed by VERIFY command);
Control Block and Key Descriptor Block data from the rst two sectors of each KSAM key
le;
A Working Storage area large enough to hold a data record and two key entries;
A data block buer large enough to hold a block from the data le;
At least one, and up to 20, key block buers each large enough to hold one key block.
When the key le is searched for a particular data record, the root block and lower level
blocks, as needed, are moved to key block buers in the extra data segment. Key entries are
compared in the working storage area. When the data block is located, it is moved to the data
block buer of the extra data segment, and when the particular data record is located, it is
moved to the working storage area.
Since each open KSAM le is allocated an extra data segment and each extra data segment
can be up to 32K words long (32,767 words), KSAM les can use a lot of memory. When
there is not enough room in memory for all the extra data segments, they must be swapped
between memory and disc as needed. This swapping can slow access to KSAM les.
In order to minimize swapping, you can reduce the number of KSAM les by combining
several les into one le. This automatically reduces the number of extra data segments, and
it can be a very eective way to improve performance, particularly when les are shared by a
number of users. (Refer to Number of Extra Data Segments, below.)
Decreasing the overall size of the extra data segment may reduce swapping of extra data
segments. However, reducing the number of key block buers in the extra data segment
may increase swapping of key blocks between the key le and the extra segment during a
le search. By default, KSAM allocates key block buers according to a formula that takes
into account the type of access for which the le is opened, the number of levels in the key
le structure, and the number of alternate keys in the le. Since this formula (see Table B-1)
keeps the extra data segment size as small as is compatible with eciency, the default number
of key block buers should be used except in special cases. (For details, refer to Extra Data
Segment Size later in this section.)
NUMBER OF EXTRA DATA SEGMENTS
KSAM assigns an extra data segment to each KSAM le opened by an active process. Since
more than one process can use the same le during shared access, one le may require a
number of extra data segments. Thus, the number of extra data segments depends both
on the number of KSAM les and the number of users concurrently using the le. (Refer to
Figure B-10.)
B-18
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Figure B-10. Extra Data Segments for Shared Access
EXTRA DATA SEGMENT SIZE
The size of each extra data segment associated with an open KSAM le is determined by the
number of key block buers it contains, the size of each key block buer, the size of the data
block buer, and to a lesser extent, the key entry size and the data record size. (Refer to
Figure B-11.)
Initially (when a le is opened), 12K words are allocated to the extra data segment. If less
actual space is needed, the extra space is not used, but remains in virtual memory. If more is
needed, the original extra data segment is released and a new extra data segment is allocated
with the actual size needed.
The maximum size of any extra data segment is 32K words. The actual size is calculated
from:
The total size of the overhead statistics and working storage area;
The size of the data block buer;
The size of each key block buer and the number of buers allocated.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-19
The overhead statistics and working storage area is approximately 1-1/2K bytes long
depending on variables such as the key entry size and the data entry size. The data block
buer size is based on the size of each data block in the data le. Each key block buer must
be large enough to contain all the key entries in a key block plus one key entry used when new
keys are added to a full block (as described earlier, see Figure B-2).
The default key block size is 2K bytes (1024 words) and the maximum size of the key block
buer is 4K bytes (2048 words). If a key block is larger than 4K bytes, KSAM reduces the
block size so that no block is larger than will t in an extra data segment key buer. Thus,
the main variable in extra data segment size is the number of key block buers.
Figure B-11. KSAM Extra Data Segment
B-20
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
NUMBER OF KEY BLOCK BUFFERS.
The number of key block buers depends on the type of access for which the le is opened,
the number of keys in the le, and the number of levels in the tree structure for each key.
(Refer to Table B-1 for details.) The least number of buers is allocated for read only access,
unless the primary key has many levels in its structure. More buers are usually required for
write only, read/write, or update access. The number of buers for read only access increases
with the number of levels used by the key, but is never less than one. The number of buers
for write only access increases with the number of alternate keys in the le, but is never less
than six. The number of buers for all other types of access increases with the number of
alternate keys and with the number of levels for each key, but is never less than four.
Unless you specify a particular number of key block buers, KSAM allocates buers in the
extra data segment according to the le characteristics as shown in Table B-1.
Table B-1. Number of Key Block Buffers Assigned by Default
Access Type
Read Only Access
Buers Assigned
1 buer per level in key with most levels
(minimum of 1 buer up to 20 buers)
Write Only Access
3 buers per primary key + 3 buers per alternate key + 3 buers
(minimum of 3 buers up to 20 buers)
Other Access
(Read/Write or Update)
1 buer per level in primary key structure + 1 buer per level in alternate
key structure + 3 buers
(minimum of 3 buers up to a maximum of 20 buers)
Note that you can determine the number of levels per key with the KSAMUTIL command,
VERIFY.
For example, if the le is opened for read only, and the only key needs two levels, two key
block buers are allocated. If the le is opened for write only, and there is one alternate
key in the le, nine key block buers are allocated. If this same le is opened for update
access, the primary key uses two levels, and the alternate uses three, a total of eight buers is
allocated.
If you want to override the number of key block buers assigned by default, you can use the
MPE :FILE command before opening the le, or set the numbuers parameter of FOPEN
when you open the le programmatically.
The le equation is specied as follows:
:FILE lename; DEV=,,#buers
The KSAM extra data segment will be allocated space for as many key block buers as you
specify, up to a maximum of 20. (Note that the third DEV= parameter is interpreted as the
number of key block buers only when the le name is a KSAM le; for standard MPE les,
this parameter indicates the number of list copies of the le.)
Another way to reduce the number of key block buers is to use fewer alternate keys, or to
adjust the blocking factor so that the key le structure uses fewer levels. Either of these
methods is eective when the le is written to or updated more than it is simply read.
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-21
Note that when you are loading a KSAM le with large amounts of data, you should increase
the number of key buers. The more key buers in the extra data segment, the more likely it
is that, as new data is added, locations for the new key values will be found in memory. This
cuts down on disc access and can signicantly reduce the time it takes to load the le.
For example, if you are reloading a KSAM le after a system failure, you should use the :FILE
command to increase the number of buers to maximum of 20 buers. Then, after the le is
loaded, you can allow it to revert to the default number of buers established by KSAM for
the particular le.
EXTRA DATA SEGMENTS WITH SHARED ACCESS
The extra data segment allocated to each open le acts as a control block for that le. The
extra data segment contains not only the current data block and the current key block buers,
but also the latest control information for the le. This information includes the logical and
chronological record pointers that indicate the current record being accessed. Because the
current pointer position is not in a \common block&quot;, when several programs open the same
le, each can alter the key le structure by adding or deleting records so that the pointers set
by other programs may point to the wrong record without those other programs being aware
of it.
To make sure that the latest pointer position is stored with the le rather than in the separate
extra data segments, programs that share the same KSAM le must use a locking scheme.
Whenever a program locks a KSAM le, the control information is transferred from the
le to the extra data segment; and when a program unlocks the le, the contents of the
extra data segment is written back to the le. Thus, each program should lock a KSAM
le before executing any procedure that positions a record pointer (pointer-independent
procedures), and not unlock the le until all procedures that depend on this pointer position
(pointer-dependent procedures) have completed execution. This is true regardless of whether
the pointer is chronological (points to a record in the data le) or is logical (points to a key in
the key le). Both types of pointer are maintained in the extra data segment for the open le.
Table B-2 lists all the procedures that aect or are aected by the record pointers.
B-22
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
Table B-2. Pointer Dependence
PointerIndependent
Procedures
Pointer
Type
Pointer-Dependent
Procedures
Pointer
Type
FFINDBYKEY
CKSTART
BKSTART
Logical
FREAD
CKREAD
BKREAD
Logical
FFINDN
Logical
FSPACE
Logical
FREADBYKEY
CKREADBYKEY
BKREADBYKEY
Logical
FREMOVE
CKDELETE
BKDELETE
Logical
FWRITE
CKWRITE
BKWRITE
Logical
FUPDATE
CKREWRITE
BKREWRITE
Logical
FPOINT
Chronological
FREADC
Chronological
FREADDIR
Chronological*
FREADC
Chronological
*Each procedure that sets the logical pointer also sets the chronological pointer; but only
FPOINT sets the logical pointer as well as the chronological pointer.
The pointer-independent calls position the pointer regardless of its current position.
Pointerpendent calls, on the other hand, must know to which record the pointer is currently
positioned in order to operate correctly.
All the procedures listed in Table B-2 aect the pointer in some way. In order to use these
procedures correctly, it is important to understand how each moves the pointer, whether it
positions the pointer directly or advances it from its current position.
In general, when access to the le is random, the pointer is positioned directly. For example,
a call to FFINDBYKEY (or CKSTART or BKSTART) positions the logical pointer to a
particular key in the key le based on a key value specied in the call; and a call to FPOINT
positions the chronological pointer to a particular record determined by its chronological
record number.
When access to a le is sequential or the le is being modied, pointer positioning is
not direct but is relative to its previous position. Depending on the sequence in which
procedures are executed, the pointer may or may not be advanced to the next record in key
or chronological sequence. Internally, a ag is used to indicate whether or not to advance
the pointer. This ag, the \Do Not Advance&quot; ag, is set to FALSE if the pointer is to be
advanced sequentially, to TRUE if it is not to be advanced. Some procedures never test the
ag; these are, in general, the pointer-independent procedures that set the pointer directly.
Other procedures test the ag and advance the pointer if the ag is FALSE; generally, these
are procedures that read the le or position the pointer sequentially. Table B-3 summarizes
when the pointer is set or advanced. (Note that only SPL procedures are listed; check
Table B-2 for the equivalent BASIC or COBOL procedures.)
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
B-23
Table B-3. Record Pointer Summary
For example, if you call FREADBYKEY, it positions the pointer to a specied key value.
After the call, the logical pointer remains positioned to this key and the Do Not Advance
ag is set to FALSE. If the next call is to FREAD, FSPACE, or FREADC, then the pointer
is advanced to the next key in key sequence before these procedures perform their other
functions. Thus, after FREADBYKEY, a call toFREAD will read the next record, not reread
the same record, and a call to FSPACE will move the pointer relative to the record following
the record just read.
B-24
KSAM/3000 INTERNAL
STRUCTURE AND TECHNIQUES
C
ASCII CHARACTER SET IN
COLLATING SEQUENCE
In the collating sequence for ASCII characters, unlike EBCDIC, numbers precede letters.
ASCII CHARACTER SET IN
COLLATING SEQUENCE
C-1
Table C-1. ASCII Characters in Sequence
DECIMAL
VALUE
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
C-2
CONTROL
NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
DLE
DC1
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESCj[c
FS
GS
RS
ASCII CHARACTER SET IN
COLLATING SEQUENCE
GRAPHIC
@c
Ac
Bc
Cc
Dc
Ec
Fc
Gc
Hc
Ic
Jc
Kc
Lc
Mc
Nc
Oc
Pc
Qc
Rc
Sc
Tc
Uc
Vc
Wc
Xc
Yc
Zc
Escape
nc
]c
^c
COMMENTS
Null
Start of heading
Start of text
End of text
End of transmission
Enquiry
Acknowledge
Bell
Backspace
Horizontal tabualation
Line feed
Vertical tabulation
Form feed
Carriage return
Shift out
Shift in
Data link escape
Device control 1 (X-ON)
Device control 2
Device control 3 (X-OFF)
Device control 4
Negative acknowledge
Synchronous idle
End of transmission block
Cancel
End of medium
Substitute
File Separator
Group Separator
Record separator
Table C-1. ASCII Characters in Sequence (cont.)
DECIMAL
VALUE
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
CONTROL
US
SP
!
&quot;
#
$
%
&amp;
'
(
)
*
+
,
.
/
0
1
2
3
4
5
6
7
8
9
:
;
&lt;
GRAPHIC
c
`
ac
bc
cc
dc
ec
fc
gc
hc
ic
jc
kc
lc
mc
nc
oc
pc
qc
rc
sc
tc
uc
vc
wc
xc
yc
zc
c
fc
jc
COMMENTS
Unit separator
Space (blank)
Exclamation point
Quotation mark
Number sign
Dollar sign
Percent sign
Ampersand
Apostrophe
Left parenthesis
Right parenthesis
Asterisk
Plus sign
Comma
Minus sign (hyphen)
Decimal point (period)
Slash
Zero
One
Two
Three
Four
Five
Six
Seven
Eight
Nine
Colon
Semicolon
Less than
ASCII CHARACTER SET IN
COLLATING SEQUENCE
C-3
Table C-1. ASCII Characters in Sequence (cont.)
DECIMAL
VALUE
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
C-4
CONTROL
=
&gt;
?
@
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
ASCII CHARACTER SET IN
COLLATING SEQUENCE
GRAPHIC
gc
~
DELc
c
COMMENTS
Equals sign
Greater than
Question mark
Commercial at
Uppercase A
Uppercase B
Uppercase C
Uppercase D
Uppercase E
Uppercase F
Uppercase G
Uppercase H
Uppercase I
Uppercase J
Uppercase K
Uppercase L
Uppercase M
Uppercase N
Uppercase O
Uppercase P
Uppercase Q
Uppercase R
Uppercase S
Uppercase T
Uppercase U
Uppercase V
Uppercase W
Uppercase X
Uppercase Y
Uppercase Z
Table C-1. ASCII Characters in Sequence (cont.)
CONTROL
DECIMAL
VALUE
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
GRAPHIC
[
Opening bracket
Reverse slant
Closing bracket
Circumex
Underscore
Grave accent
Lowercase a
Lowercase b
Lowercase c
Lowercase d
Lowercase e
Lowercase f
Lowercase g
Lowercase h
Lowercase i
Lowercase j
Lowercase k
Lowercase l
Lowercase m
Lowercase n
Lowercase o
Lowercase p
Lowercase q
Lowercase r
Lowercase s
Lowercase t
Lowercase u
Lowercase v
Lowercase w
Lowercase x
Lowercase y
Lowercase z
Left brace
n
]
^
`
a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
w
x
y
z
f
j
g
~
DEL
COMMENTS
Vertical line
Right brace
Tilde
Delete
ASCII CHARACTER SET IN
COLLATING SEQUENCE
C-5
D
CONVERSION TO KSAM FILES
In order to convert from your existing les to KSAM les, you may want to take advantage of
utility programs provided with KSAM/ 3000. If your les are serially accessible, you can use
the KSAMUTIL command BUILD to create a KSAM le and then copy your les to the new
le with FCOPY. Another method only converts HP INDEX les. INDEX is the new name
for RSAM (or R'ISAM) les. This method uses the program RTOKSAM. Finally, if neither of
these methods is useful, you can write your own special purpose conversion program.
USING KSAMUTIL AND FCOPY
This conversion method can be used for any le that is serially accessible. First you create a
KSAM/3000 le using the BUILD command of KSAMUTIL. At this time you can dene your
le with any legitimate specication of the BUILD command. Once the le is built (created),
you can run FCOPY to copy your existing le to the newly created le. No special FCOPY
commands are needed. You simply specify your existing le as the FROM= le and the
newly created KSAM le as the TO= le. All connections between the data le and the key
le are made automatically. (Refer to section II of this manual for a discussion of both the
KSAMUTIL BUILD command and FCOPY as applied to KSAM/3000 les.)
USING RTOKSAM
The RTOKSAM program will create a KSAM/3000 le from an existing INDEX le. The
KSAM le will have the same key structure as the INDEX le. Any number of INDEX les
can be converted to KSAM/3000 les in one RTOKSAM run provided that you have sucient
disc space within your group and account for all the les.
Program RTOKSAM is run as follows:
:RUN RTOKSAM.PUB.SYS.
HP32208.A.0.00 INDEX TO KSAM CONVERTER
ENTER INDEX KEY, KSAM DATA, AND KSAM KEY FILE NAMES
&gt;indexkey,ksamdata,ksamkey
The names of the INDEX key le, the KSAM data le, and the KSAM key le must be
entered in that order. Only the INDEX key le already exists; a new KSAM/3000 le wll be
created with the specied names.
After converting the INDEX le to the KSAM le, the program continues to prompt you
for additional le names for conversion. When you wish to stop processing, simply press the
carriage return key in response to the greater than (&gt;) prompt. Or, if you are in a job, enter
an :EOD record.
CONVERSION TO KSAM FILES
D-1
Record numbering in INDEX les always starts with record number 1. The KSAM le created
by the RTOKSAM conversion program will also have record number starting with 1. Note
that this is not the standard KSAM le default. Key blocking, on the other hand, does follow
the KSAM le defaWt. That is, the number of keys per block is determined by KSAM so that
each key block has 1024 (1K) words.
If errors occur during execution of RTOKSAM, the following error messages may be displayed:
INPUT/OUTPUT ERROR ON $STDIN/$STDLIST
COMMAND TOO LONG
DUPLICATED FILE NAME
INSUFFICIENT PARAMETERS
INDEX OPEN ERROR
INDEX FREADLABEL ERROR
UNABLE TO BUILD KSAM FILE
KSAM FILE WRITE ERROR
INDEX FILE READ ERROR
(detail
(detail
(detail
(detail
(detail
line
line
line
line
line
follows
follows
follows
follows
follows
message)
message)
message)
message)
message)
The detail line that follows certain of the RTOKSAM messages explains in more detail the
input/output error that occurred.
The normal MPE security provisions for les apply when the INDEX le is specied in this
program. The KSAM le that is created must be within the same log on group.
Note
D-2
It is good practice to make a back-up copy of the INDEX le on o-line
storage such as magnetic tape before running RTOKSAM to copy the le to a
KSAM le. This allows you to purge the INDEX le once it is copied.
CONVERSION TO KSAM FILES
E
RECOVERY FROM SYSTEM FAILURE
OVERVIEW
If the system fails when a KSAM le is open for any type of access except read-only, the
le cannot be reopened until it has been recovered. In such a circumstance, any attempt to
reopen the le causes the following message to be issued:
#192 -- SYSTEM FAILURE OCCURRED WHILE THE KSAM FILE WAS OPENED
The le is easily recovered in most cases by running KSAMUTIL.PUB.SYS and then
requesting KEYINFO. This command resets any incorrect end-of-le marks and deletes any
key values that point to non-existent data records. If key values are missing or are out of
sequence, the keys cannot be recovered by KEYINFO and, in this case, the le must be
reloaded. (You can refer to section II for a discussion of KEYINFO; also an example of
le recovery and reloading is provided later in this appendix,) If you want to examine the
le statistics, you can run the VERIFY command of KSAMUTIL using the NOCHECK
option. (If KEYINFO does not complete execution successfully, then the KSAM le must be
reloaded.)
For most purposes, this is all you need to know in order to recover a le when a system failure
prevents you from opening it. This appendix provides internal details that explain why
recovery is necessary and what KEYINFO does in order to recover. It is intended primarily
for the sophisticated programming sta.
RECOVERY FROM SYSTEM FAILURE
E-1
END-OF-FILE ON KSAM FILES
The rst step in understanding what KEYINFO does and why it is needed, is to understand
how KSAM end-of-les are set and maintained. Each of the two les that comprise a KSAM
le (the data Ele and the key le) has two end-of-le marks: an MPE end-of-le and a KSAM
internal end-of-le. Thus, there are four end-of-les to consider. The main characteristics of
each of these end-of-les are shown below:
DATA FILE
MPE End-Of-File:
Number of records in xed-length record le (or number of blocks in variable-length record
le).
Stored in system le label of data le.
Recorded on disc when le is closed (or when an SPL procedure calls FCONTROL with
control code 6) or when a new extent is allocated.
Used by FCOPY with NOKSAM option (KSAM le is treated as an MPE le).
Displayed by LISTF,2:
LISTF DATAFIL,2
ACCOUNT= MORRIS
FILENAME CODE
DATAFIL
KSAM
GROUP= JOAN
------------LOGICAL RECORD----------- ----SPACE---SIZE TYP
EOF
LIMIT R/B SECTORS #X MX
38B
FA
20
^
|----
20
1
23
8
8
MPE end-of-le for data le
KSAM End-of-File:
Address of next available logical record in the data le.
Stored in control block of key le.
Recorded on disc when le is unlocked or closed (or when an SPL procedure calls
FCONTROL with control code 2 or 6).
Used by FCOPY when le is opened as a KSAM le (KEY-option)
Displayed by VERIFY command (option 1) of KSAMUTIL:
:RUN KSAMUTIL.PUB.SYS
HP32208A.2.3 MON, APR 23, 1979, 1:11 PM KSAMUTIL VERSION:A.2.0
VERIFY DATAFIL
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL,)?1
DATAFIL.JOAN.MOPRIS
CREATOR=JOAN
FOPTIONS(004005)=KSAM, :FILE, NOCCTL, F, FILENAME, ASCII, PERM
AOPTIONS(000400)=DEFAULT, NOBUF, DEFAULT, NO FLOCK, NO MR, IN
RECSIZE:SUB:TYP:LDNUM:DRT:UN.: CODE:LOGICAL PTR: END OF FILE:FILE LIMIT
-38: 3: 0:
3: 5: 0:
0:
0:
20:
20
|
E-2
RECOVERY FROM SYSTEM FAILURE
KSAM end-of-le for data le-------------------LOG. COUNT:PHYS. COUNT:BLK SZ:EXT SZ:NR EXT: LABELS:LDN :
DISCARD:
1:
1: -38:
3:
8:
1:
3:00000010135:
Since this is a le that closed successfully, the two end-of-les coincide.
RECOVERY FROM SYSTEM FAILURE
E-3
KEY FILE
MPE End-of-File:
File limit - Number of records (sectors) allocated to le at time of creation
Stored in system le label.
Displayed by LISTF,2:
:LISTF KEYFIL,2
ACCOUNT= MORRIS
FILENAME CODE
KEYFIL
KSAMK
GROUP= JOAN
------------LOGICAL RECORD----------- ----SPACE---SIZE TYP
EOF
LIMIT R/B SECTORS #X MX
128W FB
50
|
|
50
1
30 5
8
MPE end-of-le on key le
(set to le limit)
KSAM End-of-File
Address of 1st record in next available key block.
Stored in Control Block of key le.
Recorded on disc when le is unlocked or closed (or when SPL procedure calls FCONTROL
with control codes 2 or 6).
Used by FCOPY and KSAM procedures.
Displayed by VERIFY command, option 3, of KSAMUTIL:
E-4
RECOVERY FROM SYSTEM FAILURE
WHICH (1=FILE INTO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?3
DATA FILE = DATAFIL
KEY CREATED=292/'78
KEY CHANGED= 93/'79
DATA RECS =
DATA BLK SZ=
FOPEN
FREADDIR
FREMOVE
FGETINFO
FWRITELABEL
FWRITE
FLOCK
FSETMODE
KEYBLK READ
KEY FILE EOF
MIN PRIME
DATA FIXED
FIRST RECNUM
VERSION= A.2.1
10:19: 7.4
KEY ACCESS= 113/'79 13:11:45.8
14:18: 7.6
COUNT START=292/'78 10:19:53.6
20 DATA BLOCKS=
19 END BLK WDS=
19 DATA REC SZ=
38 AZCESSORS=
2 FREAD
0 FCLOSE
0 FREADC
0 FREADBYKEY
0 FSPACE
57 FFINDBYKEY
3 FGETKEYINFO
1 FREADLABEL
0 FCHECK
0 FFINDN
20 FUPDATE
0 FPOINT
0 FUNLOCK
0 FCONTRDL
0
7 KEYBLK WROTE
0 KEYBLK SPLIT
26 FREE KEY HD
0 SYSTEM FAILURE
|
KSAM internal end-of-le on key le
11 MAX PRIME
TRUE DATA B/F
0 MIN RECSIZE
5 RESET DATE
1 TOTAL KEYS
38
19
0
2
0
0
0
3
0
0
0
0
3/'79
3
Since the MPE end-of-le is set to the le limit and the KSAM internal end-of-le to the next
available key block, these values never coincide until the key le is full.
RECOVERY FROM SYSTEM FAILURE
E-5
END-OF-FILE AND THE EXTRA DATA SEGMENT
As described in appendix B, each open KSAM le uses an extra data segment (XDS) to hold
the control information for that particular open le. The extra data segment also contains a
data block buer into which records are read from the le and from which records are written.
Finally, the extra data segment keeps key block buers to hold key entries aected by the data
records being accessed. The control block in each extra data segment also maintains the most
up-to-date KSAM end-of-le markers for each open le.
Whenever a KSAM le is opened, the KSAM end-of-les for the data and key les are moved
(with all other information from the key le control block) to the control block of the extra
data segment for that le. When the le is closed or unlocked, the control block is written
back to disc. (Refer to Figure E-1for a diagram illustrating the end-of-le markers and their
relation to an extra data segment.)
Figure E-1. KSAM File and an Extra Data Segment
E-6
RECOVERY FROM SYSTEM FAILURE
NORMAL OPERATION - FILE IS CLOSED
During normal operation, if a new record is written to the le by any user, the record is
written in the data block buer of the extra data segment and the key entry for the record is
inserted into the key block buer where it belongs. (Refer to appendix B for a discussion of
how new key entries are added.) The appropriate key block buer is brought into the extra
data segment automatically. Then, whenever the data block or key block buers are full or
new blocks must be read into the extra data segment, the key and data blocks are written
back to disc. But the control block from the extra data segment is not written to disc until
the le is closed (or is unlocked, or FCONTROL with code 2 or 6 is called).
Before considering what happens in case of a system failure, let's look at the normal steps
taken when the le is closed:
1. Key block buers are written to the key le
2. Data block buer is written to the data le (and, if a new extent is allocated, the MPE
end-of-le is written to the data le system label).
3. Control block with the KSAM end-of-le marks is written to the key le.
4. MPE end-of-le mark is written to the data le system label.
When a le is unlocked, the rst three steps shown above are taken (except the MPE end of
le is not written). FCONTROL with control code 6 performs all four steps, and control code
2 performs the rst three steps.
SYSTEM FAILURE - FILE IS OPEN
If the system fails when a KSAM le is open, the extent of the damage to the le depends on
when the failure occurred and whether the le was being modied. If all users opened the le
for readonly, then the le is undamaged and can be reopened. If a user had just unlocked the
le and no other user has modied it, the MPE end-of-le may need to be reset but otherwise,
the le is undamaged. But if the le was being modied, then the extent of the damage
depends on whether any of the steps listed above had been completed and, if so, which ones.
In the simplest case, all the steps except step 4 have been performed. This means that the
KSAM end-of-le is up-to-date, but the MPE end-of-le is still at its previous position, In the
most complex case, caused by records being deleted, data records remain in the data le for
which there are no corresponding key entries, (error number 175).
RECOVERY FROM SYSTEM FAILURE
E-7
SITUATIONS IN WHICH RECOVERY IS REQUIRED
Whenever the le cannot be reopened (error #192 is issued), you must run KEYINFO to
recover the le. The following four cases are typical of the reasons for le damage. In each
case, the suggested action is discussed.
1. Records were being added to the data le when the system failed. The KSAM end-of-le
for the data and key les are current, but the MPE end-of-le precedes the KSAM
end-of-le (steps 1-3 completed).
Solution : Run KEYINFO to reset the MPE end-of-le. You can then run the KSAMUTIL
command, VERIFY, to determine where the current KSAM end-of-le for the data le is
positioned, and then run the MPE command :LISTF 2 to compare the MPE end-of-le. If
you run VERIFY before running KEYINFO, use the NOCHECK option so the le can be
opened.
2. Records being added to the KSAM le when the system failed were not written to the data
le, but some key entries for the new records had been written to the key le (key blocks
written to key le because buer space in XDS was needed). This means that the key le
contains key values pointing to records not in the data le.
Solution : Run KEYINFO to delete the key values that point to records that were not
written to the data le.
3. Records being added to the KSAM le when the system failed caused a key block split. As
a result, the key blocks are written, but the new internal KSAM end-of-le for the key le
has not been transferred to disc. This places certain key values past the old KSAM key le
end-of-le.
Solution : Run KEYINFO to reset the key le end-of-le to the correct location following
the existing key values. It still may have to delete any key values pointing to records past
the data le end-of-le.
4. Records were being deleted when the system failed. Some key block buers have been
written to disc, but the data block buer has not. Since some key entries were deleted from
the le on disc, but the deleted records remain, key values appear to be missing.
Solution : You must run KEYINFO to reset the crash ag so the le can be reopened.
When key values are missing, KEYINFO cannot fully recover from the le damage and
issues the following message:
Warning
THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING THE KSAM FILE
HAS TO BE RELOADED
To reload the KSAM le, use FCOPY to copy the le to a new KSAM le. As it copies the
data records, it writes new key entries for each data record. Only in this way can missing
key values be recovered. (Refer to the discussion of Reloading a KSAM File later in this
section.)
If you want to determine how many key values are missing and the le has more than one key,
you can compare the number of values in each B-Tree as listed by KEYINFO. These values
should be identical. When there is only one key in the le, you can use FCOPY to determine
the number of non-deleted records in the batch le. The number of key values for any key in
E-8
RECOVERY FROM SYSTEM FAILURE
the le should exactly match the number of valid data records. The FCOPY command to
determine this value is:
&gt;FROM=filename;TO=$NULL;KEY=0
If your le is very large, using this FCOPY command can be time consuming and you may
prefer to reload the le without checking the number of missing keys.
EXAMPLE OF FILE RECOVERY
Suppose you try to open le TEST and receive error message #192:
SYSTEM FAILURE OCCURRED WHILE KSAM FILE WAS OPENED
In order to have the most information about the le, rst run KSAMUTIL and request
VERIFY to list all the le information.
HP32208Y.2.4. THU, MAR 8, 1979, 12:53 PM KSAMUTIL VERSION:A.3.0
&gt;V TEST
WHICH (1=FILE INFO, 2=KSAM PARAMETERS, 3=KSAM CONTROL, 4=ALL)?4
SYSTEM FAILURE OCCURRED WHILE THE KSAM FILE WAS OPENED (1068)
|
KSAMUTIL error message--------------------------
Just like any other program, the VERIFY command cannot open the damaged le. So try
again using the NOCHECK option that allows such a le to be opened for read-only:
RECOVERY FROM SYSTEM FAILURE
E-9
The next step is to run LISTF,2 to see where the MPE end-of-le is positioned. Note that you
can request the MPE command without exiting from KSAMUTIL.
E-10
RECOVERY FROM SYSTEM FAILURE
&gt;:LISTF TEST,2
ACCOUNT= UTILITY
GROUP= KSAM
FILENAME CODE ------------LOGICAL RECORD----------- ----SPACE---SIZ
TYP
EOF
LIMIT R/B SECTORS #X MX
TEST
KSAM
80B
FA
900
|
1023
10
416 8
8
MPE end-of-le on data le
LISTF shows the MPE end-of-le after the rst 900 records, whereas option 1 of VERIFY
showed the KSAM end-of-le after 990 data records. This is a discrepancy of 90 records.
These records actually exist. You only have to run KEYINFO to reset the MPE end-of-le.
When you run KEYINFO, however, you may nd that there are other problems.
&gt;KI TEST
RECOVERY BEGINS
DATA FILE EOF DAMAGED
DATA FILE MPE EOF HAS BEEN RESET TO KSAM EOF &lt;-----
MPE end-of-le recovered
After resetting the MPE end-of-le for the data le, KEYINFO continues. It next displays
information on the two keys in the le TESTK.
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
% OF KEY BLOCK UTILIZATION
THE LARGEST KEY BLOCK ADDRESS
--------- INFO FOR KEY
# OF LEVELS OF B-TREE
# OF KEY BLOCKS
# OF SECTORS PER KEY BLOCK
# OF KEYS IN ROOT KEY BLOCK
# OF KEYS IN B-TREE
% OF KEY BLOCK UTILIZATION
THE LARGEST KEY BLOCK ADDRESS
1 --------2
16
8 &lt;-------KSAM end-of-le should
14
be at least 218
1000 &lt;----|
|
52.1
|
|
210 &lt;----------|
|
2 --------|
2
# of key entries in two
11
| keys do not match
8
| each other; do not match
9
| # of data records
997 &lt;----|
68.6
202
WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING
OR KEY VALUE(S) POINTING TO DATA RECORD BEYOND EOF
KEY FILE EOF(INTERNAL) DAMAGED
KEY FILE (INTERlNAL)EOF Has BFEN RESET &lt;---- End-of-le moved
forward
so all key blocks are included
Looking at the key information displayed for the two keys, the rst thing to check is where the
actual end of le should be. The largest key block address for key 1 is 210 and each block
requires 8 records, therefore the key le end-of-le should be at least 218. If you look back
to option 3 of the VERIFY display, it is listed as 210. Since this is not the real end-of-le,
KEYINFO resets the KSAM internal end-of-le to the actual end of le (see VERIFY display,
below).
Next, check the total number of key values for each key. The rst thing to notice is that they
do not match each other. The number of key values for each key should always be the same,
and each should equal the number of records in the data le. But, if you look at option 1 of
the VERIFY display, the number of records in the data le is 990, less than the number of key
RECOVERY FROM SYSTEM FAILURE
E-11
values for either key. (Note that if the le contains records marked for deletion, you can run
FCOPY to determine the number of active records).
In response to this discrepancy, KEYINFO deletes 10 key values from each key. The values
deleted are those that have no matching data record. This completes the KEYINFO
functions. Now that it has deleted 10 key values from the key entries for key 2, only 987 are
left (997 minus 10). This is three fewer than the number of key values in key 1 (990 = 1000
010). For this reason, KEYINFO must issue the warning that the le needs to be reloaded:
--------- KEY SEQUENCE
# OF INVALID KEY VALUES DELETED
1 --------10&lt;-----10
--------- KEY SEQUENCE
# OF INVALID KEY VALUES DELETED
RECOVERY ENDS
2 --------|
10&lt;-------|
values deleted that
have no matching data record.
WARNING: THERE ARE SOME RECORD(S) WITH KEY VALUE(S) MISSING
THE KSAM FILE HAS T0 BF RELOADED
Before reloading the le, as described below, use LISTF,2 to check the current MPE end-of-le
(after recovery); run VERIFY to check the current KSAM end-of-le positions; and run
KEYINFO again to see the number of key values left in each key following the previous
KEYINFO recovery.
E-12
RECOVERY FROM SYSTEM FAILURE
The name of the user who runs KEYINFO to recover the le for the RESET DATE shown by
VERIFY is stored in the key le control block, along with his account, group, and home group
(refer to Figure B-5).
RECOVERY FROM SYSTEM FAILURE
E-13
RELOADING A KSAM FILE
You use FCOPY to reload a KSAM le when KEYINFO cannot recover the le. You must
rst use the KSAMUTIL BUILD command to build the new le, and then use FCOPY to
copy the le. In general, you should use the KEY=0 option of FCOPY (see section II for
a complete description of the FCOPY options for KSAM les). KEY=0 copies the le in
chronological sequence so that the new le will be an exact copy of the original le, except
that records marked for deletion are physically deleted from the le.
For example, to reload the le TEST to a new KSAM le, NEWTEST:
:RUN FCOPY.PUB.SYS
&gt;FROM=TEST;TO=(NEWTEST,NEWKEY) ;KEY=0;NEW
After the le is successfully reloaded, you should purge the old le TEST and rename the le
NEWTEST. To do this, run KSAMUTIL and use the PURGE and RENAME commands as
follows;
RUN KSAMUTIL.PUB.SYS
HP32208V2.4 THU, MAR 8,1979,1:05 PM
&gt;PURGE TEST
TEST,TESTKEY PURGED
&gt;RENAME NEWTEST,TEST
&gt;RENAME NEWKEY,TESTKEY
KSAMUTIL VERSION:A.3.0
Now you can run any existing programs that referenced the old le TEST.
The only time you might not want to use the KEY= option to reload a damaged le is if the
key le has been accidentally purged. In this case, and if the le has xed-lengt,h records, you
can use the NOKSAM option. This option needs only the original data le. As it copies the
data le in chronological order to a new KSAM le, it creates a key le with key entries for
the data records. The NOKSAM option does not, however, allow you to copy a data le with
variable-length records. Refer to the instructions for copying variable-length KSAM les in
Section II.
For example, to reload a KSAM data le for which you have only a data le with xed-length
records, rst build the new data le, NEWFIL, then use the following FCOPY command:
&gt;FROM=DATAFIL;TO=NEWFIL;NOKSAM;NOUSERLABELS;
SUBSET=#%377,%377,,EXCLUDE
|
\__________________________/
|
|
|
|
|
|
|
to exclude records marked
for deletion by 01 in
rst two characters
you must not copy
user labels to a
KSAM le
This command copies only the non-deleted records; it creates a new KSAM le with only valid
records and a key le that has key entries for each data record.
After a system crash in which the key le is lost, it is possible that the MPE end-of-le follows
the KSAM end-of-le because it was written to disc just before the crash. If this is the case
and you use the NOKSAM option you should also use a SUBSET option to copy only the
records up to the KSAM end-of-le, not the undened area between the KSAM and MPE
end-of-les.
E-14
RECOVERY FROM SYSTEM FAILURE
EXPAND KEY BLOCK BUFFER AREA
Depending on the length of the existing le, the reloading procedure can take a long time.
One way to shorten this time is to increase the number of key block buers in the extra data
segment for the le. Since reloading is a write-only operation, the more buers that can be
allocated to key blocks, the less swapping is needed between the extra data segment and disc
as new key entries are added.
In order to increase the number of key block buers, enter the following commands:
:RUN FCOPY.PUB.SYS
&gt;FROM=TEST;TO=(NEW,NEWK);SUBSET=1,0 &lt;------------ create new le with 0
&gt;:FILE F=NEW;DEV=,,20 &lt;------------ increase number of key block buers
&gt;FROM=TEST;TO=*F;KEY=0 &lt;------------ copy data in chronological order
|
|------ remember to back reference le
records
RECOVERY FROM SYSTEM FAILURE
E-15
F
NATIVE LANGUAGE SUPPORT AND KSAM
OVERVIEW
The Keyed Sequential Access Method (KSAM) organizes records in a le according to the
content of key elds within each record.
Native Language Support (NLS) in KSAM provides the resources to create les whose keys of
type BYTE are sorted according to a native language collating sequence. All BYTE keys in
the le will be sorted using the collating sequence table of the specied language. Keys, as
well as data in the record, may contain 8-bit character data.
A le language attribute may be supplied when a KSAM le is created to provide a key le
organized according to the collating sequence of a native language. The language attribute
is provided when the le is created. All KSAM les created before NLS was introduced are
considered to have NATIVE-3000 as a language attribute.
A KSAM le can bebuiltwith KSAMUTIL, or programmatically using FOPEN.
CREATING KSAM FILES WITH KSAMUTIL
When using KSAMUTIL, the parameter LANG=langname or LANG= langnum may be supplied
on the BUILD command, as shown in Figure F-1. NATIVE-3000 is used as the default
language attribute if no language is specied.
The language specied in the LANG= parameter must be installed on the system at the time
the command is issued for KSAMUTIL to build the le. If the language is not installed, an
error message is returned and the le is not built.
Danish is specied as the language in the example. The language attribute of the KSAM le
can be checked by the VERIFY command (mode 3).
NATIVE LANGUAGE SUPPORT AND KSAM
F-1
RUN KSAMUTIL.PUB.SYS
HP32208A.03. 13 THU, FEB 16, 1984, 8:54 AM
KSAMUTIL VERSION:A.03.13
&gt;BUILD TEST;REC=-;80,3,F,ASCII;KEY=B,1,4;KEYFILE =TESTK;LANG=DANISH
&gt;VERIFY
WHICH (1=FILE INFO, 2-KSAM PARAMETERS, 3-KSAM CONTROL, 4=ALL)?4
TEST.LORO.NLS
CREATOR-SLORO
FOPTIONS(004005)=KSAM, :FILE, NOCCTL, F, FILENAME, ASCII, PERM
AOPTIONS(000400)=DEFAULT, NOBUF, DEFAULT, NO FLOCK, NO MR, IN
RECSIZE:SUB:TYP:LDNUM:DRT:UN.: CODE:LOGICAL PTR: END OF FILE:FILE LIMIT
-80: 9: 0:
3: 89: 2:
0:
0:
0:
1023
LOG. COUNT:PHYS. COUNT:BLK SZ:EXT SZ:NR EXT: LABELS:LDN:
DISCADDR:
0:
0: -240:
43:
8:
0: 3:00000234251:
KEY FILE=TESTK
KEY FILE DEVICE=4
SIZE=
114 KEYS=
FLAGWORD(000020)=RANDOM PRIMARY, FIRST RECORD=0, PERMANENT
KEY TY LENGTH
LOC. D KEY BF LEVEL
1 B
4
1 N
168
1
DATA FILE = TEST
KEY CREATED= 47/'84
KEY CHANGED= 47/'84
DATA RECS =
0
DATA BLK SZ=
120
FOPEN
1
FREADDIR
0
FREMOVE
0
FGETINFO
1
FWRITELABEL
0
FWRITE
0
FLOCK
0
FSETMODE
0
KEYBLK READ
2
KEY FILE EOF
10
MIN PRIME
0
DATA FIXED
TRUE
FIRST RECNUM
0
VERSION= A.3.13
9: 0: 7.6
9: 0: 8.5
DATA BLOCKS=
DATA REC SZ=
FREAD
FREADC
FSPACE
FGETKEYINFO
FCHECK
FUPDATE
FUNLOCK
FREE KEYBLK
KEYBLK WRITTEN
FREE KEY HD
MAX PRIME
DATA B/F
MIN RECSIZE
KEY ACCESS= 47/'84
COUNT START= 47/'84
0 END BLK WD=
80 ACCESSORS=
0 FCLOSE
0 FREADBYKEY
0 FFINDBYKEY
0 FREADLABEL
0 FFINDN
0 FPOINT
0 FCONTROL
0 FREE RECS
0 KEYBLK SPLIT
0 SYSTEM FAILURE
0 RESET DATE
3 TOTAL KEYS
4 LANG
WHICH (1-FILE INFO, 2-KSAM PARAMETERS,
9: 0:19.2
9: 0: 8.6
0
0
1
0
0
0
0
0
0
0
0
0
1
DANISH
3-KSAM CONTROL, 4-ALL)?
&gt;E
END OF PROGRAM
:
Figure F-1. KSAM File Test Program
F-2
NATIVE LANGUAGE SUPPORT AND KSAM
1
ERROR MESSAGES
KSAMUTIL error messages are listed in Table F-1.
Table F-1. KSAMUTIL Error Messages
ERROR#
MESSAGE
CAUSE
ACTION
Improper syntax was Enter language name using
used in specifying the correct syntax.
language name.
1070
`LANG' NOT FOLLOWED BY
`=' OR HAS TOO MANY
PARAMETERS.
1071
`LANG' LANGUAGE VALUE TOO Language name too
long, or missing as a
LONG OR ABSENT.
Enter correct language name.
parameter.
1072
`LANG' LANGUAGE NUMBER
VALUE INVALID .
The language number Enter correct language
number.
contains invalid
characters.
1073
`LANG' LANGUAGE NOT
SUPPORTED.
Language specied is Ask the System Manager to
congure the langauage on
not congured on
your system, or not a your system.
valid language name
or number.
1074
NATIVE LANGUAGE SUPPORT
IS NOT INSTALLED.
NLS is not installed
on your system.
1075
NATIVE LANGUAGE SUPPORT
LANGUAGE NOT SUPPORTED.
An NLS MPE error
Ask the System Manager to
occurred. No
congure the language on your
language table exists system.
for language specied.
1076
NATIVE LANGUAGE SUPPORT
RELATED ERROR.
An NLS MPE error
occurred.
Ask the System Manager to
congure the language on your
system.
Ask the System Manager to
congure the language on your
system; if it is already
congured, contact your
Hewlett-Packard support
representative.
NATIVE LANGUAGE SUPPORT AND KSAM
F-3
CREATING KSAM FILES PROGRAMMATICALLY
The user must provide a language ident ication number when calling FOPEN to build a KSAM
le. The language identication number is stored in word 10 of the KSAMPARAM array. The
FOPEN intrinsic checks each time a KSAM le is opened to determine whether the language
used is congured on the system. For backward compatibility reasons bit 11 in the agword
(word 15) must be set to 1 if a language other than 0 (NATIVE-3000) is used, to denote that
word 10 contains valid information.
If bit 11 of agword is 0, the default language, NATIVE-3000, is used and the data in word 10
is ignored. If the language is not congured, condition code CCL is returned by FOPEN .
The le system error messages listed in Table F-2 have been included with NLS:
Table F-2. KSAM File System Error Messages
ERROR#
MESSAGE
CAUSE
ACTION
196
LANGUAGE NOT SUPPORTED
The language name or Ask the System Manager to
number specied for congure the language on your
system.
FOPEN is not
congured on your
system, or is not a
valid language name
or number.
197
NATIVE LANGUAGE SUPPORT
RELATED ERROR.
Contact your Hewlett-Packard
An NLS MPE error
occurred on a FOPEN support representative.
call.
MODIFYING KSAM FILES
Every record added or updated in a KSAM le has its new keys of type BYTE inserted
in the key le according to the collating sequence of the language dened for that KSAM
le. That function is handled internally by a system version of the NLCOLLATE intrinsic
when the language attribute ofthe le is dierent from NATIVE-3000. A new key in a le
with a NATIVE-3000 language attribute will be ordered according to the result of a BYTE
COMPARE between the key of the new record and the keys of the records already in the key
le.
F-4
NATIVE LANGUAGE SUPPORT AND KSAM
GENERIC KEYS
NLS collating sequences dier from the USASCII collating, and the dierences must be
considered when performing generic key searches. Refer to the Native Language Support
Reference Manual (32414-90001) for more information.
The description of a generic key search in a KSAM le with a native language attribute is
presented from an application point of view
Keys matching a certain generic key may not be in consecutive order in the key le because
the keys are sorted according to a native language collating sequence. The key sequence in
Figure F-3 illustrates this with a French KSAM le; keylength is 4, the generic key length is 2.
The partial key \aa&quot; appears in nonconsecutive keys (with a result of 0 in the last column of
the gure). Records containing partial keys (such as \AA&quot; or \Aa&quot;0 are intermixed according
to the French collating sequence. These keys have a result of 1 listed.
If a generic key search is performed in a KSAM le with a language attribute other than
NATIVE-3000, the application program must determine whether the retrieved record matches
the generic key and, even if it does not, whether subsequence records might still match it.
The codes returned by NLKEYCOMPARE are shown in Figure F-2.
Refer to the Native Language Support Reference Manual (32414-90001) for a complete
discussion of the NLKEYCOMPARE intrinsic.
Figure F-2. Results Returned By The
RESULT
0
1
2
3
NLKEYCOMPARE
Intrinsic
MEANING
The retrieved key matches the generic key exactly.
The retrieved key does not match the generic key. Uppercase/lowercase priority
or accent priority is dierent.
The retrieved key value is less than the generic key. It precedes the designated
key in the collating sequence.
The retrieved key is greater than the generic key.
NATIVE LANGUAGE SUPPORT AND KSAM
F-5
The generic key search sequence is:
1. After FFINDBYKEY has been called with &gt;= as relational operator(relop), the logical record
pointer points to the data records indicated by the arrow labeled \Case 2&quot;.
2. The subsequent FREAD call will retrieve the data record. When the partial key \AA&quot; is
compared to the generic key \aa&quot; they are found to be dierent.
This comparison is done by calling the intrinsic NLKEYCOMPARE using the generic key and
the key found in the record. The result returned by NLKEYCOMPARE tells the application
whether the FREAD delivered a record:
a. Before the desired range (result 2).
b. In the desired range with an uppercase/lowercase or accent priority dierence (result 1).
c. With an exact match (result 0).
d. After the desired range (result 3).
3. To get all records whose key match the generic key exactly, the FREAD calls and subsequent
NLKEYCOMPARE call should continue until a result of 3 is returned.
When performing a generic key search in a KSAM le with a native language attribute other
than NATIVE-3000 use the NLKEYCOMPARE intrinsic to compare partial keys and generic keys.
Refer to the Native Language Support Reference Manual (32414-90001) for examples of generic
key searches in KSAM les with native language attributes.
F-6
NATIVE LANGUAGE SUPPORT AND KSAM
Key length: 4
Language: FRENCH (only USASCII characters are used in the example).
Desired records are all records whose record key starts with \aa&quot; (generic key = \aa&quot;,
length = 2) .
Pointer
Position
Case 1|-&gt;
Case 2|-&gt;
Case 3|-&gt;
Key
Value
A
a
AA
Aa
aA
aa
AAA
aaa
AAAA
AAAa
AAaa
AaAa
AaaA
Aaaa
aAAA
aAAa
aAaA
aaAA
aaaA
aaaa
Baaa
baaa
NLKEYCOMPARE Result
(\aa&quot; Compared to Key)
2
2
1
1
1
0
1
0
1
1
1
1
1
1
1
1
1
0
0
0
3
3
Figure F-3. Generic Key Searches
NATIVE LANGUAGE SUPPORT AND KSAM
F-7
Case:
1. FREAD starting at the beginning of the le.
2. FFINDBYKEY with relational operator = or &gt;= and subsequent FREAD calls.
3. FFINDBYKEY with relational operator &gt; and subsequent FREAD calls.
Key Value: Key values in ascending sequence.
Figure F-4. Generic Key Searches
F-8
NATIVE LANGUAGE SUPPORT AND KSAM
USING FCOPY WITH NLS KSAM FILES
COPYING FROM A KSAM FILE TO ANOTHER KSAM FILE
If the KSAM le already exists (built via KSAMUTIL or programmatically) the keys of type
BYTE are put into the new le according to the collating sequence belonging to the language
of the \TO&quot; le. If the le does not exist, a new le is built with the same language attribute
as the \FROM&quot; le.
CHANGING THE LANGUAGE ATTRIBUTE OF A KSAM FILE
FCOPY cannot be used to change the language attribute of an existing le. KSAMUTIL
must be used to build a new KSAM le with the new language attribute. Then the data can
be copied to this le using FCOPY. Keys of type BYTE in the destination key le will be
ordered according to the collating sequence of the new language.
MOVING NLS KSAM FILES TO PRE-NLS MPE
Restoring a KSAM le with a native language attribute other than NATIVE-3000 to a
system without NLS installed can result in an incorrect key sequence in the key le for tvpe
BYTE keys. Systems without NLS installed do not recognize any collating sequence except
NATIVE-3000.
If a le with a native language attribute otherthan NATIVE-3000 is restored, the rst FOPEN
on the le will return the same error condition code as if a system failure occurred while the
le was opened. KSAMUTIL should be used to build a new KSAM le, The le with the
native language attribute is recovered, and FCOPY is used to copy the recovered le into the
new KSAM le. See Figure F-5 for an example of this recovery procedure.
:RUN KSAMUTIL.PUB.SYS
HP32208A.03.10 SAT, SAT, MAY 26,1984, 12:33 PM KSAMUTIL VERSION:A.03.10
&gt;BUILD NEWDATA;REC=-80,3,F,ASCII;KEY=B,1,4,:KEYFILE =NEWKEY
&gt;KEYINFO OLDDATA;RECOVER
&gt;EXIT
:FCOPY FROM-OLDDATA;TO-NEWDATA;KEY=0
:RUN KSAMUTIL.PUB.SYS
HP32208A.03.10 SAT, SAT,MAY 26,1984, 12:33 PM KSAMUTIL VERSION:A.03.10
&gt;PURGE OLDDATA
&gt;RENAME NEWDATA,OLDDATA
&gt;RENAME NEWKEY,DLDKEY
&gt;EXIT
Figure F-5. KSAM Recovery Procedure
NATIVE LANGUAGE SUPPORT AND KSAM
F-9
">
Здравейте! Аз съм AI чатбот, специално обучен да ви помага с HP KSAM/3000 software. Аз съм прегледал подробно документа и мога да ви помогна да намерите точната информация, която ви е необходима, или да обясня съдържанието на ясен и прост език. Независимо дали търсите насоки за конкретни функции, стъпки за отстраняване на неизправности или обща употреба, не се колебайте да задавате своите въпроси. Колкото повече подробности предоставите за вашите притеснения или нужди, толкова по-точно и ефективно мога да ви помогна!
Асистентът пише
Асистентът не е на клавиатурата. Моля, опитайте отново по-късно.
Изглежда, че сте достигнали документ, който е написан на няколко езика, включително и такъв, който не е вашият роден език. Можете да използвате следните връзки, за да скриете временно страници без езика, който предпочитате.