900 Series HP 3000 Computer Systems Using KSAM XL ABCDE HP Part No. 32650-90168 Printed in U.S.A.
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 or tness for a particular purpose. Hewlett-Packard shall not be liable for errors contained herein or for direct, indirect, special, incidental or consequential damages in connection with the furnishing or use of this material.
Printing History The following table lists the printings of this document, together with the respective release dates for each edition. The software version indicates the version of the software product at the time this document was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions.
iv
Preface MPE/iX, Multiprogramming Executive with Integrated POSIX, is the latest in a series of forward-compatible operating systems for the HP 3000 line of computers. In HP documentation and in talking with HP 3000 users, you will encounter references to MPE XL, the direct predecessor of MPE/iX. MPE/iX is a superset of MPE XL. You can continue to use MPE XL system documentation, although it may not refer to features added to the operating system to support POSIX (for example, hierarchical directories).
vi
In This Book This manual provides programmers with descriptions and examples of the KSAM XL le format and its accessing routines. The material is organized into nine chapters and two appendixes. The \Introduction" describes the KSAM XL le, its indexing mechanism, and its standard recovery methods. \Creating a KSAM XL File" describes di erent methods of creating a KSAM XL le. Standard commands have been adapted to create and load a KSAM XL le. Intrinsics are also available to create and open a KSAM XL le.
viii
Conventions UPPERCASE In a syntax statement, commands and keywords are shown in uppercase characters. The characters must be entered in the order shown; however, you can enter the characters in either uppercase or lowercase.
Conventions (continued) [ ... ] In a syntax statement, horizontal ellipses enclosed in brackets indicate that you can repeatedly select the element(s) that appear within the immediately preceding pair of brackets or braces. In the example below, you can select parameter zero or more times. Each instance of parameter must be preceded by a comma: [,parameter][...
Contents 1. Introduction KSAM XL File Format Index Area . . . . Data Area . . . . . Automatic Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 1-3 1-4 1-5 2. Creating a KSAM XL File Creating the File With the BUILD Command . . . KSAM XL File Characteristics . . . . . . . . . Key Characteristics . . . . . . . . . . . . . First Record Number . . . . . . . . . . . . REUSE Option . . . . . . . . . . . . . . Language ID . . . . . . . . . . . . . . . .
4. Opening and Closing the File Opening an Existing KSAM XL File Using the HPFOPEN Intrinsic . . Using the FOPEN Intrinsic . . . Opening a New File . . . . . . . Closing a KSAM XL File . . . . . Contents-2 . . . . . . . . . . . . . . . 4-1 4-1 4-3 4-4 4-8 5. Reading File Data Sequential Access by Primary Key . . . . . . Sequential Access by Primary and Alternate Key Specifying the Record Number . . . . . . . Specifying a Key Value . . . . . . . . . . Sequential Access by Partial Key Value . . . .
FLOCK . . . . FOPEN . . . . FPOINT . . . FREAD . . . . FREADBYKEY FREADC . . . FREADDIR . . FREADLABEL FREMOVE . . FRENAME . . FSPACE . . . FUNLOCK . . FUPDATE . . FWRITE . . . FWRITELABEL HPFOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BKLOCK . . . . BKOPEN . . . . BKREAD . . . . BKREADBYKEY BKREWRITE . . BKSTART . . . BKUNLOCK . . BKWRITE . . . . . . . . . . . . . . . . . . . C. HP C/iX Example Program Index Contents-4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figures 1-1. 1-2. 1-3. 2-1. 2-2. 2-3. 2-4. 2-5. 2-6. 3-1. 3-2. 3-3. 4-1. 4-2. 4-3. 5-1. 5-2. 5-3. 5-4. 7-1. 9-1. 9-2. 9-3. 9-4. 9-5. 9-6. 9-7. A-1. A-2. A-3. A-4. A-5. A-6. B-1. B-2. B-3. B-4. B-5. General Representation of the KSAM XL Format . A Simpli ed View of the KSAM File Structure . . Simple Index Tree Structure . . . . . . . . . . Creating a KSAM XL le using the OPTMBLK parameter . . . . . . . . . . . . . . . . Creating a KSAM XL le with the data block size set at 4K bytes (default) . . . . . . .
B-6. Reading a Record Located by Key Value with BKREADBYKEY . . . . . . . . . . . . . B-7. Rewriting Record in KSAM File with BKREWRITE B-8. Positioning Pointer to Least-Valued Record with BKSTART . . . . . . . . . . . . . . . . B-9. Positioning Pointer to Particular Record with BKSTART . . . . . . . . . . . . . . . . B-10. Dynamically Unlocking a KSAM File . . . . . . B-11. Writing to a KSAM File with BKWRITE . . . .
Tables 5-1. 6-1. 9-1. 9-2. 9-3. 9-4. 9-5. 9-6. 9-7. A-1. B-1. B-2. B-3. Pointer and Advance Flag Settings for Reading . . Pointer and Advance Flag Settings for Writing . . FCONTROL Itemnum/Item Values . . . . . . . FFILEINFO Itemnum/Item Values . . . . . . . FFILEINFO File Codes . . . . . . . . . . . . FLABELINFO Itemnum/Item Values . . . . . . FOPEN/HPFOPEN Parameter Equivalents . . . HPFOPEN Itemnum/Item Values . . . . . . . FOPEN/HPFOPEN Parameter Equivalents . . .
1 Introduction The Keyed Sequential Access Method (KSAM) is a method of organizing data records according to the content of key elds within the record. This method allows sequential processing of records without relying on the physical location of the record in the le. Every record in a KSAM le contains a primary key eld. The content of this eld determines the logical sequence of each record. Alternate keys o er di erent sequences for accessing the same records.
Figure 1-1.
Index Area The index area contains a control block, bit mappings for the pages of the index and data areas, and the key indexes. The control block contains the le speci cations and key speci cations established when the le was built. It also contains pointers to the index and data page maps to manage the le's space. A key index contains a key value and pointer for each record. This index data is arranged in ascending order based on the key value.
The index portion of the le is organized in a tree structure. Figure 1-3 provides a diagram of a simple structure. The entry point of the structure, the root, either points to the location of an entry or directs the search to branches of the structure for higher or lower entries. The branches narrow the search, again, either to an entry location or to an ever-decreasing number of higher or lower entries. The lowest level, or leaves, provides pointers to the locations of the remaining records.
le, thus interrupting the chronological sequence. In this case, physical location of a record does not represent the chronological order of written records. Any alterations to the data area of the le, such as additions, modi cations, or deletions, are immediately available to subsequent accesses by any process. The le system guarantees the order of concurrent data access.
2 Creating a KSAM XL File You can create a KSAM XL le in several di erent ways: Using the BUILD command. The le name and le characteristics are speci ed in the command parameters. The le can then be loaded with data by using the FCOPY subsystem to load existing le data or by directing program output to the le. Copying an existing le using the FCOPY subsystem. File characteristics can be defaulted to those of the existing le or modi ed by using a le equation.
Random insertion or sequential insertion of the key, if duplication is allowed. Record numbering starting with 0 or 1. Reuse of deleted record space or no reuse. Specify default data block size or allow KSAM XL to select data block size. KSAM XL File Characteristics The key characteristics, the method of le numbering, and the reuse option are unique to KSAM XL les. Each key must be de ned in the BUILD command's ;KEY= parameter.
byte integer real IEEE real numeric packed *packed 1 to 255 bytes. 1 to 255 bytes of integer data. 1 to 255 bytes of real number data. 4, 8, or 16 bytes of IEEE real number data. 1 to 28 bytes of numeric data. 1 to 14 bytes of packed decimal data (odd number of characters). 2 to 14 bytes of signed packed decimal data (even number of characters). The duplication key characteristic is an optional eld.
digits or by entering the language name. To nd out what languages can be accessed on your system, enter RUN NLUTIL.PUB.SYS. Any of the listed language IDs can be entered in this eld. The default language is Native-3000. Di erent a ectd languages may cause the sequential ordering of records to be a ected. OPTMBLK/DEFBLK Option Users can assure e cient disk space utilization by using the OPTMBLK option of the BUILD command.
d :BUILD XDEF;KSAMXL;KEY=(B,1,4) :LISTFILE XDEF,7 KEY --1 c a KEYTYPE ------BYTE KEY LOCATION KEY SIZE ------------------1 4 NONE NUM KSAM KEYS: 1 LANGUAGE : ENGLISH VERSION : 2 DATA : DUP/RDUP -------- FIRST KSAM RECORD : 0 REUSE RECORD : NO COMPUTE BLK SIZE : DEFBLK b Figure 2-2. Creating a KSAM XL file with the data block size set at 4K bytes (default) Use the FILE command along with the FCOPY command to copy a new KSAM XL le to one where the data block size is chosen using OPTMBLK.
d c :BUILD ARMSTR.MGR;REC=-80,,F,ASCII;& DEV=DISC;DISC=100;KSAMXL;& KEY=(N,4,6;& Specifies account number (primary) key B,10,25,RDUP;& Defines the last name key N,65,5,RDUP;& Defines the zip code key B,70,3,RDUP);& Defines the branch ID key FIRSTREC=1;REUSE ;LANG=5 Specifies that the first record is identified by number 1, that deleted record space can be reused, and that the native language is English. Figure 2-3.
d c d c a (N,4,6;& B,10,25,RDUP;& N,65,5,RDUP;& B,70,3,RDUP) b Figure 2-4 shows the command for setting up the same accounts receivable master le as in Figure 2-3. The KEY= parameter, however, refers to the indirect le named KEYDATA for the key data speci cations. The character ^ speci es that an indirect le contains the data. :BUILD ARMSTR.MGR.AR;REC=-80,,F,ASCII;DEV=DISC;& DISC=100;KSAMXL;KEY=^KEYDATA;& FIRSTREC=1;REUSE ;LANG=5 a b Figure 2-4.
le, the name is enclosed in parentheses. If the parentheses are not included, a standard le type is created. The following example creates a new master le, duplicating the le and key speci cations from the original le ARMSTR. Note that the le name is enclosed in parentheses, identifying the le type of the new le as a KSAM XL le type. >FROM=ARMSTR.MGR.AR;TO=(ARMBACK.MGR.AR) Modifying Existing File Specifications While Copying A le equation can be used to modify le speci cations of an existing le.
Language ID Flag word Enter the three digit code for the native language that you desire. To nd out what languages can be accessed on your system, enter RUN NLUTIL.PUB.SYS. A list of languages and their IDs is displayed on the screen. Any of the listed language IDs can be entered in this eld. The ag word contains two bytes de ning the KSAM XL le characteristics: Bits Value/Meaning 15:1 Reserved. 14:1 Enter a 1 if record numbering is to start with 1. 13:1 Enter 0 if record numbering is to start with 0.
Figure 2-5.
Number of Keys Enter a digit between 1 and 16 in word 16 to specify the number of keys to be de ned for this le. Refer to Figure 2-5 for the location of this eld. Key Parameters The following parameters are de ned for each key. The information about each key is similar to the BUILD command's KEY= parameter. key type Enter one of the following codes specifying the type of data the key will contain.
d c Chapter 4 provides an example of an HPFOPEN intrinsic call that creates and opens a KSAM XL le. type bit1=0..1; bit4=0..15; bit7=0..127; bit8=0..255; bit12=0..4095; bit15=0..32767; bit16=0..65535; pac80 = packed array [1..
d c a var ksam_param, ksamparam : ksam_struc; keylocation, reserved : bit16; .. . begin ksamparam[10].lang_id := 5; ksamparam[16].resrvd3 := 0; ksamparam[16].num_keys := 1; ksamparam[17].key_type := 2; ksamparam[17].key_length := 5; keylocation := 5; .. ksamparam[18].bitword := keylocation; . b KSAM Parameter Settings (continued) The HPFOPEN intrinsic uses item number pairs to identify intrinsic parameters. Item number 54 is paired with the KSAM parameter array to de ne the KSAM XL key structure.
Deleting a KSAM XL File KSAM XL les can be deleted using the PURGE command. As with standard les, the le named in the PURGE command is deleted. The accounts receivable le can be deleted using the following command. PURGE ARMSTR.MGR.AR Renaming a KSAM XL File The RENAME command can be used to change the name of an existing KSAM XL le. The le name speci ed in the command is deleted. The parameters for the RENAME command are the same as for standard les. The le name speci ed in the command is deleted.
3 Obtaining File Information You can obtain le information about an existing le using the LISTFILE command or the FGETINFO and FGETKEYINFO intrinsics. You can also add speci c information about your le by writing it to a user label. The FWRITELABEL and FREADLABEL intrinsics provide access to user labels. Displaying File and Key Information d c Use the LISTFILE command to display the le speci cations used to build the le.
Two options display the key speci cations for a KSAM XL le. Option 5 (DATA) displays the le speci cations and key data for the le. Option 7 (UNIQUE) displays information that is unique to the le type. For KSAM les, this displays the key data without the le speci cations. Figure 3-2 provides an example of the LISTFILE command using option 5 (DATA) and the display it generates.
d :LISTFILE ARMSTR.MGR.AR,7 ************************** FILE: ARMSTR.MGR.AR KEY 1 2 3 4 c a KEY TYPE NUMERIC BYTE NUMERIC BYTE NUM KSAM KEYS: LANGUAGE : PRIMARY KEY : VERSION : 4 ENGLISH RANDOM 2 KEY LOCATION KEY SIZE 4 10 65 70 6 25 5 3 DUP\RDUP NONE RDUP RDUP RDUP FIRST KSAM RECORD: 1 REUSE RECORDS : YES COMPUTE BLK SIZE : OPTMBLK b Figure 3-3.
The number of logical records currently in the data le. The number of the last logical record that could be contained by the le. The total number of logical records passed to and from the user during the current access of the le. The block size of the le. The disk extent size associated with the le. The maximum number of disk extents allowed for the le. The number of user labels allowed for the le. The name of the user who created the le. The sector address of the label of the le.
You can read the contents of user labels using the FREADLABEL intrinsic. During the normal reading of a le, user labels are skipped. The FREADLABEL intrinsic, therefore, should be called immediately after the le has been opened. To read a user label, the le must be opened with read, input/output, or update access, and the user labels to be read must be identi ed. Issue the following FREADLABEL intrinsic call to read the user label written in the previous example.
4 Opening and Closing the File Some application programming languages o er commands for opening and closing KSAM les (for example, the ORGANIZATION IS INDEXED clause in COBOL). If not, use the HPFOPEN or FOPEN intrinsic to open the le, and the FCLOSE intrinsic to close the le. See the appropriate application language reference manual for details on how to call intrinsics.
d procedure open_permanent_KSAM_file; const formal_designator_option domain_option access_type_option dynamic_locking_option exclusive_option ASCII_binary_option = = = = = = 2; 3; 11; 12; 13; 53; type pac160 = packed array [1..
The le num parameter is used to return a le number to the calling program. This le number is used to identify the le in subsequent intrinsic calls. The status parameter returns a numeric code identifying the success or failure of the le opening process. d c For clarity, the itemnum parameters in the previous example have been de ned as constants. This is not necessary for intrinsic use.
In this example, the aoption value 5 speci es update access for the le (bits 12:4 = (binary) 0101). This level of access allows all other intrinsic calls for this le. Other binary access selections include: binary 0000 or 0 To read the le. binary 0001 or 1 To write to the le for the rst time. binary 0010 or 2 To append records to the le. binary 0100 or 4 To allow both read and write access. binary 0101 or 5 To update records in the le.
d c a type bit1=0..1; bit4=0..15; bit7=0..127; bit8=0..255; bit12=0..4095; bit15=0..32767; bit16=0..65535; pac80 = packed array [1..
d c .. . begin file_num := 0; status := 0; file_name := '%ARMSTR.MGR.AR%'; ksam_type := 3; write_access := 1; rec_len := 80; file_len := 100; save_perm := 1; ascii := 1; .. . ksamparam[10].lang_id := 5; ksamparam[16].resrvd3 := 0; ksamparam[16].num_keys := 1; ksamparam[17].key_type := 2; ksamparam[17].key_length := 5; keylocation := 5; ksamparam[18].bitword := keylocation; .. .
d c a type bit1=0..1; bit4=0..15; bit7=0..127; bit8=0..255; bit12=0..4095; bit15=0..32767; bit16=0..65535; pac80 = packed array [1..
d c begin file_num := 0; file_name := 'ARMSTR.MGR.AR '; ksamparam[10].lang_id := 5; ksamparam[16].resrvd3 := 0; ksamparam[16].num_keys := 1; ksamparam[17].key_type := 2; ksamparam[17].key_length := 5; keylocation := 5; ksamparam[18].bitword := keylocation; file_num:=FOPEN(file_name,6148,1,-80,,ksamparam,,,,100) end; a b Opening a New KSAM XL File with FOPEN (continued) Closing a KSAM XL File The FCLOSE intrinsic terminates access to a le.
5 Reading File Data KSAM les o er multiple record retrieval options using primary and alternate keys, and logical and physical record numbers. The following list identi es the methods of reading KSAM le data: Sequential access: By primary key. By alternate key. In physical record order. Random access: By key value. By logical record number. By approximate key match. By partial key. By physical record number.
Table 5-1. Pointer and Advance Flag Settings for Reading Intrinsic Note Sequential Access by Primary Key Reads Sets Pointer Sets Advance Flag Advance Flag Pointer Dependant FFINDBYKEY no both no no FFINDN no both no no FPOINT no both no no FREAD yes both yes yes FREADBYKEY no both no no FREADC yes PHYS yes yes FREADDIR no PHYS yes no FSPACE yes both no yes COBOL II and Business BASIC provide KSAM le access routines that read records by key value.
Sequential Access by Primary and Alternate Key Two intrinsics, FFINDN and FFINDBYKEY, can be used to set the logical pointer to the lowest value of an alternate key eld. The FFINDN intrinsic identi es the rst record by using a logical record number. The FFINDBYKEY intrinsic uses a key value to determine the rst record. When the rst record has been located, the FREAD intrinsic reads the rst record speci ed by the alternate key.
d c a fby_keyvalue := '0000'; fby_keylocation := 1; fby_keylength := 4; := 1; .. fby_relop . .. FFINDBYKEY(filenum,fby_keyvalue,fby_keylocation,fby_keylength,fby_relop); . lgth := FREAD(filenum,fr_record,fr_tcount); b Figure 5-2. FFINDBYKEY Intrinsic Sample Sequential Access by Partial Key Value The FFINDBYKEY intrinsic can be used to point to those records that contain a common portion of a key eld.
To read all records containing \M0", a series of freads would be issued and a comparison made in the program to see when the key eld did not contain \M0" or the end of the le reached. A record can be accessed randomly by a particular key value or by its relative or physical record number. Random Access of a Single Record Using a Key Value d c The FREADBYKEY intrinsic is recommended for retrieving records randomly. The desired key value and the key location are speci ed in the intrinsic parameters.
used, however, if such a key was speci ed by a previous call to the FFINDBYKEY or FREADBYKEY intrinsic. Note Sequential Access in Physical Record Order This is true for the reads on the previous examples of FFINDN FFINDBYKEY, FREADBYKEY intrinsics that sets the key of reference for succeeding reads. A sequential access in physical record order is really a series of random accesses by physical record number.
d c An FLOCK intrinsic call should be made prior to a pointer positioning and record reading procedure to ensure that the proper retrieval is executed. The FUNLOCK intrinsic restores shared access once the retrieval is completed. Once the le is unlocked, do not assume that the pointer is still valid. Before using the pointer again, reposition it. The following sequence shows the appropriate locking procedure to ensure the proper sequence of records.
6 Writing and Updating Record Data When records are written to a le for the rst time, they are usually written sequentially. Following execution of an FWRITE intrinsic, the logical record pointer is positioned at the next sequential record in key sequence or at the end-of- le marker if the record is the last in sequence. Updating and deleting records also rely on pointer positioning. The logical and physical record pointers are usually positioned by a read procedure, as discussed in Chapter 5.
Writing New Records The FWRITE intrinsic writes new records to a new or existing le from a bu er in your program. Index entries for primary and alternate keys are entered automatically for each record written. Depending on how the le was created, records may be written in random or sequential order. If the REUSE option is speci ed, each record is written to the next available space. If the NOREUSE option is speci ed, all records are written at the end of the le.
Deleting a Record The intrinsic FREMOVE e ectively removes the current record from the KSAM XL le. When executed, the 4-byte record header is modi ed, identifying the record as deleted. All key entries pointing to this record are deleted from the indexes. Although the data still occupies record space in the le, it is no longer possible to access the record through standard read operations. Note that if deleted record space can be reused, this area can be overwritten by a new record.
7 Protecting the File and Its Data Attention must be paid to protecting a KSAM XL le's data. Check an intrinsic's status after a call to nd information about a failed routine. The FCHECK and FERRMSG intrinsics provide error codes and messages after an intrinsic call has failed. Various intrinsics control le access when a le is shared by more than one process. Locking and unlocking the le controls access to a shared le during critical modi cation operations.
corresponding message can also be found in the MPE/iX Intrinsics Reference Manual (32650-90028). Protecting Data When File Access is Shared If a KSAM XL le is shared with another process, you need to ensure that the most current data and key index information is retrieved. Locking les controls other processes from accessing the le while a modi cation routine is processing.
d c FLOCK FREADBYKEY FUNLOCK .. . Other users can access and modify this record while ..the user decides how to update it. . FLOCK FREADBYKEY FUPDATE FUNLOCK Writing Directly to Disk Recovering from a System or Software Abort a b The FCONTROL intrinsic's controlcode parameter settings identify the control operation desired. A setting of 2 ensures that the requested output has been physically completed.
To protect initial loading, use the BUILD command to create the le. The le is attached to transaction management when the BUILD command is used. A le can also be attached manually by creating and loading the le with the HPFOPEN intrinsic and specifying the DOMAIN=CREATE option. With this option, the le is attached and system logging begins with the rst access. Backing Up KSAM XL Files A regularly scheduled backup of all les is always advisable.
d c a :BUILD ARMSTR.MGR.AR;REC=-80,,F,ASCII;DEV=DISC;& DISC=100;KSAMXL;KEY=(N,4,6;& B,10,25,RDUP;& N,65,5,RDUP;& B,70,3,RDUP;& FIRSTREC=1;REUSE :FCOPY >FROM=OLDMSTR.MGR.AR;TO=(ARMSTR.MGR.AR);KEY=0 >EXIT b Figure 7-1.
8 Migration and Mixed Mode Processing MPE/iX o ers two KSAM le formats: CM KSAM and KSAM XL. CM KSAM is the two- le KSAM structure used on MPE V/E systems. KSAM XL, a single- le KSAM structure, is used only on MPE/iX systems. A KSAM XL le o ers a more convenient single- le format. Programs running in CM or NM can access either type of KSAM le. Use the FCOPY utility to migrate data and rebuild indexes from one KSAM le format to another.
Differences in KSAM File Features Unlike CM KSAM les, KSAM XL data records and indexes are combined in a single le. The le limit of KSAM XL les is substantially larger than CM KSAM les. The physical size of the KSAM le is the same as the MPE/iX native mode at le. KSAM XL les allow only xed-length records. CM KSAM les allow xed-length or variable-length records.
Migrating KSAM Files Note d c The data records from an existing KSAM le on an MPE V/E system can be migrated to an existing KSAM XL le on an MPE/iX system. Perform the following steps to migrate an existing CM KSAM le with xed-length records to a new KSAM XL le: 1. Store both the CM KSAM key le and data le to tape using the TRANSPORT option (used only if migrating to an MPE V/E system). 2. Restore both les to the MPE/iX machine (used only if migrating from an MPE V/E system). 3.
d c d c Migration Process Guide (30367-90007) for details about migrating application programs. You can create a new KSAM XL le and copy the CM KSAM record data in a single step. Enclose the new le name in parentheses to specify that this is a KSAM XL le. If the KSAM XL le does not exist, a new le is created. A new le is also created by using the NEW option. If you create the le and copy data to it using one command, however, you are not able to change the key structure.
Mixed Mode Operation Application programs running in CM or NM can access either CM KSAM or KSAM XL les. If you are using an RPG application, do not specify any record locking features. RPG will deafult to le-level locking. This is especially important for cross-development for multiple environments. In some organizations, cross development is necessary because satellite o ces operate di erent types of systems. CM KSAM les can be used on both MPE V/E and MPE/iX systems.
d c d c 8-6 To copy from one KSAM XL le to another existing KSAM XL le, enter a single le name for the target le. (KSAM XL les include indexes and data records in a single le.) Use this type of copy to back up current KSAM XL les or to create a test le on an MPE/iX system. :FCOPY >FROM=ARMSTR.MGR.AR;TO=ARBACK.MGR.AR >EXIT To create a new CM KSAM le and copy data to it from an existing KSAM XL le, remember that both the target data le name and the target key le name must be speci ed.
9 KSAM XL Intrinsics The following section provides syntax and parameter de nitions for the KSAM XL intrinsics. For details regarding status usage and data types, refer to the MPE/iX Error Message Manual Volumes 1, 2 and 3 (32650-90066, 32650-90152, and 32650-90368) and the MPE/iX Intrinsics Reference Manual (32650-90028).
Returns speci c details about error conditions that occurred when a le system intrinsic returned a condition code indicating an I/O error. FCHECK applies to les on any device. FCHECK Syntax I16V I16 I16 I32 I16 FCHECK( lenum,fserrorcode,translog,blocknum,numrecs); Parameters lenum 16-bit signed integer by value (optional) fserrorcode Speci es the le number of the le for which error information is to be returned.
FCHECK Condition Codes CCE CCG CCL Request granted. Not returned. Request denied. The le number passed by lenum is invalid, or a bounds violation occurred while processing this request (fserrorcode =73). Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
Terminates access to a le on any device. FCLOSE Syntax I16V I16V I16V FCLOSE( lenum,disposition,securitycode); Parameters lenum disposition 16-bit signed integer by value (required) Passes the le number of the le to be closed. 16-bit signed integer by value (required) Passes the disposition of the le, signi cant only for les on disk and magnetic tape. Note This disposition can be overridden by a corresponding parameter in a FILE command entered prior to program execution.
FCLOSE securitycode temporary le domain, an error code is returned and the le remains open. 011 Close as a temporary job le (not rewound). This option has the same e ect as domain disposition 010, except that tape les are not rewound. 100 Release the le. The le is deleted from the system. 101 Makes a permanent standard disk le temporary (valid only for standard disk les with either xed-length, variable-length, or unde ned-length record formats).
FCLOSE Operation Notes FCLOSE deletes bu ers and control blocks where the process accessed Condition Codes CCE CCG CCL the le. It also deallocates the device where the le resides, and it can change the disposition of the le. If FCLOSE calls are not issued for all les opened by the process, the calls are issued automatically by MPE/iX when the process terminates. Request granted. Not returned. Request denied.
FCONTROL Performs various control operations on a le or on the device where the le resides, including: Verifying I/O. Reading the hardware status word for the device where the le resides. Setting a terminal's timeout interval. Repositioning a le at its beginning. Writing an end-of- le marker.
FCONTROL Table 9-1. FCONTROL Itemnum/Item Values Itemnum Mnemonic 0 U16 Item Description General device control: The value speci ed is passed to the appropriate device driver. A value from the driver is returned in item . Not valid for spooled device les. Not applicable to KSAM les. 1 U16 Carriage control (CCTL): Not applicable to KSAM les. 2 I16 Complete I/O: Ensures that requested I/O has been physically completed. Valid only for bu ered les. Posts the block being written (full or not).
FCONTROL Table 9-1. FCONTROL Itemnum/Item Values (continued) Itemnum Mnemonic 6 U16 Item Description Write end-of- le: Marks the end-of- le (EOF) on disk. It performs the function of itemnum =2 and writes the le label. This guarantees that the end-of- le is correct and the extent bit map is updated. Item is ignored. 7 U16 Space forward to tape mark: Not used for KSAM XL les.
Returns a message corresponding to an FCHECK error number and enables error messages to be displayed from a program. FERRMSG Syntax I16 CA I16 FERRMSG(fserrorcode,msgbu er,msglength); Parameters fserrorcode 16-bit signed integer by reference (required) msgbu er Passes an error code returned by the FCHECK intrinsic, indicating which message to return in msgbu er . character array (required) msglength Returns the error message identi ed with fserrorcode .
FFILEINFO Returns information about a le. FFILEINFO Syntax I16V I16V * FFILEINFO( lenum[,itemnum,item] [...]); Note Parameters Up to ve itemnum/item pairs can be speci ed. lenum 16-bit signed integer by value (required) itemnum Passes the le number of the le for which information is requested. 16-bit signed integer by value (optional) item Speci es which item value is to be returned. (Refer to Table 9-2.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Itemnum Item Type Item Description 1 CA File designator (28 bytes): Returns the le designator of the le being referenced in the format: lename.groupname.accountname Must be >=28 bytes in length. Unused bytes are lled with right-justi ed blanks and a nameless le returns an empty string. The fully quali ed name of the le referenced by lenum is returned as the value of this itemnum .
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Itemnum Item Type Item Description 6 U16 Logical device number: Returns the logical device number of the device where the disk le label resides. If the le is a disk le, the LDEV is the location of the le label. (File data can reside on the same device as the le label.) If the le is spooled, the LDEV is a virtual device number that does not correspond to the system con guration I/O device list.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Itemnum Item Type 14 I16 Item Description Block size: Returns the le block size: If the le is binary, the value is positive and the size is in halfwords. If the le is ASCII, the value is negative and the size is in bytes. Maintained for compatibility with MPE V/E-based systems only. CM block size limits are used when FGETINFO returns block size information on all le types (STD, KSAM, RIO, CIR, MSG).
FFILEINFO Table 9-2.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Item Description Itemnum Item Type 41 I16 Device type 42 I16 Device subtype: Always returns an 8. (Indicates a 7933 or 7935 disk drive) 43 CA Environment le name (>=36 bytes) 44 I16 Number of disk extents currently allocated to the le 45 CA File name from labeled tape header 1 record (>= 17 bytes) 46 I16 Tape density 47 I16 DRT number: Always returns an 8. 48 I16 Device unit number: Always returns a 0.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Itemnum Item Type 61 CA Item Description NS 3000/XL remote environment ID name Note: If using NS 3000/XL RFA (remote le access), specify DSDEVICE ldev# when using a DS (point-to-point or X.25) link. A bu er must be provided for the node name (or envid ) with the required space of 52 bytes; otherwise, data corruption may occur on variables following itemnum =61 or an FSERR 73, BOUNDS VIOLATION may be returned.
FFILEINFO Table 9-2.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Itemnum 86 Item Description Item Type 32-bit signed integer by reference. File owner identi er: The le owner identi er (UID). Zero is returned as the le owner ID for root directories, accounts, and MPE groups created prior to the POSIX release. 87 32-byte character array by reference. File group: The le group name. Unused characters are blank lled.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Itemnum 90 Item Description Item Type 32-bit unsigned integer by reference. Record type: The following valid record types may be returned: 0 Fixed 1 Variable 2 Unde ned 3 Spool block 4 Root directory 5 Not applicable 6 Account directory 7 Group directory 8 Not applicable 9 Byte stream 10 Hierarchical directory 91 64-bit signed integer by reference. The current le size in bytes.
FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values (continued) Itemnum 94 Item Description Item Type 32-bit signed integer by reference. MPE/iX device type: This item returns the following values for the following types of devices: 95 0 Disk device 1 Tape device 2 Terminal device 3 Printer device 4 Remote device 5 Ports device 6 Reserved 7 Streams device 8 Sockets device 32-bit signed integer by reference.
FFILEINFO Table 9-3.
FFILEINFO Table 9-3.
FFILEINFO Table 9-3.
FFILEINFO Table 9-3.
FFILEINFO Figure 9-2. Aoption Bit Summary Condition Codes CCE (2) CCG (0) CCL (1) Request granted. Not returned. Request denied. Access or calling sequence error. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
FFINDBYKEY Positions the record pointer at the beginning of the rst record matching the key value comparison in a KSAM le. FFINDBYKEY Syntax I16V I16V I16V I16V FFINDBYKEY( lenum,value,location,length,relop); Parameters lenum CA 16-bit integer by value (required) value Identi es the le number of the le to be positioned. character array (required) location Contains a value that determines which record is read.
FFINDBYKEY Operation Notes Split stack calls are permitted. The FFINDBYKEY intrinsic does not read the advance ag. It positions both the logical record pointer and the physical pointer to the appropriate record. When the function is complete, it sets the advance ag to FALSE. To locate and read a single record, use the FREADBYKEY intrinsic. Condition Codes CCE CCG CCL Request granted. Request denied. The requested position was beyond the logical end-of- le or beginning-of- le. Request denied.
FFINDN Positions the logical record pointer to the relative record number according to the key sequence in a KSAM le. FFINDN Syntax I16V DV I16V FFINDN( lenum,number,location); Parameters lenum 16-bit signed integer (required) number Passes the le number of the le to be positioned. double by value (required) location Speci es a record number relative to the rst logical record in the le. Record numbers start with zero or one depending on the record numbering scheme speci ed at le creation.
FFINDN Condition Codes CCE CCG CCL Request granted. Request denied. The requested position was beyond the logical end-of- le. Request denied. An error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
FGETINFO Returns access and status information about a le. FGETINFO Note FGETINFO is provided for compatibility with MPE V/E-based systems only. It is recommended that FFILEINFO be used to access data.
FGETINFO devtype If the le was created as an ASCII le, this value is negative and expresses the size in bytes. 16-bit signed integer by reference (optional) ldevnum Returns the type and subtype of the device being used for a KSAM, RIO, circular, or message le, or devices such as a tape drive, printer, or terminal where bit (0:8) indicate device subtype, and bit (8:8) indicate device type. For standard disk les, bit (8:8)=00000011 and bit (0:8)=00001000 (indicate a 7933/35 disk drive).
FGETINFO lelimit Returns the pointer setting of the last logical record currently in the le (equivalent to the number of logical records currently in the le). If the le does not reside on disk, this value is zero. For interprocess communication (IPC), when a call to FCONTROL with itemnum =46 is in e ect, the number of records returned in eof includes open, close, and data records.
FGETINFO labaddr 32-bit signed integer by reference (optional) Returns a zero. Maintained for backward compatibility with MPE V/E-based systems. Operation Notes Returns access and status information about a le located on any device. The le must be opened by the calling process at the time of the FGETINFO call. Condition Codes CCE CCG CCL Request granted. Not returned. Request denied. An error occurred.
FGETKEYINFO Requests access and status information about a KSAM le. FGETKEYINFO Syntax I16V BA BA FGETKEYINFO( lenum,param,control) Parameters lenum 16-bit signed integer by value (required) param Passes the le number of the le about which information is requested. byte array (required) control Returns information describing the key information for a KSAM le. The length is 162 bytes. byte array (required) Passes 256 bytes of control information about the key le.
FGETKEYINFO Figure 9-3. FGETKEYINFO Parameter Format The control parameter provides dynamic information about the use of the le from the time it was created. It counts the number of times the le was referred to by intrinsics, and the date and time it was created, closed, updated, or written to. Its format is shown in Figure 9-4.
FGETKEYINFO Figure 9-4.
FGETKEYINFO FGETKEYINFO Control Parameter Format (continued) 9-38 KSAM XL Intrinsics
FGETKEYINFO Condition Codes CCE CCG CCL Request granted. Not returned. Request denied. An error occurred; insu cient space was declared for param or control , an illegal le number was speci ed, or the DB register is not set to the user stack. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
Returns information from the le label of a disk le. FLABELINFO Syntax CA I16V I16 FLABELINFO( formaldesig,mode,fserrorcode, I16A REC I16A itemnum,item,itemerror); Parameters formaldesig character array (required) Passes the name of the le using either MPE syntax (the default) or HFS syntax. The le name must be terminated by a nonalphanumeric character other than a period (.), a slash (/), a hyphen (-), and an underscore ( ).
FLABELINFO Bits Value/Meaning fserrorcode 0:11 Reserved for future use. 12:1 Symbolic Link Traversal 0 To traverse through symbolic links, if they exist. 1 Do not traversing through symbolic links, if they exist. 13:2 Caller Privilege Level Allows the caller to pretend to be less privileged. The privilege level is passed in this eld. 15:2 File Equations 0 Use le equations if they exist. 1 A le equation must be used. 2 Do not use a le equation.
FLABELINFO itemerror 16-bit signed integer array (required) Returns an error number corresponding to the items speci ed in the itemnum array. The itemnum/item and itemerror parameters are paired such that the nth element of the itemerror array corresponds to the nth element of the itemnum array. If a value in the itemerror array is negative, a warning exists for the corresponding item. If the value is positive, an error was detected for the corresponding item.
FLABELINFO Table 9-4. FLABELINFO Itemnum/Item Values Itemnum Mnemonic Item Description 1 CA File name (8 bytes): The le name component for the le referenced in formaldesig is returned as the value. If the le name is not expressible using MPE-only semantics, a le system error code (391) is returned in the associated itemerror . 2 CA Group name (8 bytes): The group name component for the le referenced in formaldesig is returned as the value.
FLABELINFO Table 9-4. FLABELINFO Itemnum/Item Values (continued) Itemnum Mnemonic 13 U16 Item Description File options: The record format extension bit is returned as the foption (1:1) bit. Byte stream record format is represented as a record format extension of one with a variable record format (foption (8:2) bits equal to 01). Directories, symbolic links, device links, pipes and FIFO's cannot be represented by foption .
FLABELINFO Table 9-4. FLABELINFO Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 30 U32 Record size (indicates bytes 31 U32 Block size (indicates bytes) 32 U32 Extent size (indicates bytes) 33 CA File lockword (8 bytes): Returned if you are the le creator, account manager, or system manager.
FLABELINFO Table 9-4. FLABELINFO Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 43 CA File owner (32 bytes): The full le owner name. Unused characters are lled with blanks. A symbolic zero (ASCII 48 in decimal) is returned as the le owner for root directories, accounts, and MPE groups created prior to release 4.5. 44 I32 File owner identi er: The le owner identi er (UID).
FLABELINFO Table 9-4. FLABELINFO Itemnum/Item Values (continued) Itemnum Mnemonic Item Description 50 I32 KSAM XL File Version: This item returns a value indicating the version number of a KSAM XL le. A value of 1 indicates an original type KSAM XL le. A value of 2 indicates the next generation KSAM XL le. A value of zero is returned if the le is not a KSAM XL le. 51 I32 KSAM XL Parameters: This item returns le information about KSAM XL.
FLABELINFO Condition Codes CCE (2) CCG (0) CCL (1) Request granted. Not returned. Request denied. An error occurred. Refer to the fserrorcode and itemerror parameters for more information. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
FLOCK Dynamically locks a le. A call to FLOCK is required before any attempt is made to read or modify a le with shared access. FLOCK Note The le system does not guarantee exclusive access, even when FLOCK and FUNLOCK are used, unless all programs that access the le cooperate by using locking. A program that opens the le with dynamic locking enabled will still be allowed to modify the le, even if it never calls FLOCK.
FLOCK CCL Request denied. This le was not opened with the dynamic locking aoption bit (10:1) speci ed in the FOPEN/HPFOPEN intrinsic. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
FOPEN Opens a le. FOPEN Syntax I16 CA U16V U16V I16V CA lenum:=FOPEN(formaldesig,foption,aoption,recsize,device, CA I16V I32V I16V formmsg,userlabels I16V lesize,numextent,initialloc, lecode); Functional Return Parameters lenum I16V 16-bit signed integer (assigned functional return) Returns a unique le number identifying the opened le. formaldesig character array (optional) Passes a formal le designator, following le naming conventions.
FOPEN Note For existing les, default conditions are speci ed in the le label. Device characteristics may override some foption s. Bits Value/Meaning 14:2 Domain Indicates which le domain is searched to locate a le. A nameless disk le must always be a new le. A device le (such as a tape or terminal) always resides in the system le domain (permanent le directory). Always specify a device le as old or permanent. The following bit settings are valid: 00 The le is new. No search is necessary.
FOPEN Bit settings indicate internal record structure for a le. This option is applicable only at le creation. 7:1 KSAM XL supports xed-length records only (00). The le contains logical records of uniform length. Carriage control 5:1 No carriage-control directive is expected for KSAM les. Disallow le equation option Indicates whether or not to allow le equations. A leading * in a formal le designator can override the setting to disallow FILE.
FOPEN 0001 0010 0011 0100 0101 9-54 KSAM XL Intrinsics Allows write access only, provided that the le's security provisions allow write access. Any data written in the le prior to the current FOPEN request is deleted. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this le. The EOF is set to 0. Allows write-save access only, if the le's security provisions allow write access. Previous data in the le is not deleted.
FOPEN 0110 0111 10:1 and write access are not allowed, the access type speci ed in the security provisions (either read or write) is allowed. All le intrinsics can be called for this le. The EOF is not changed. This option is not valid for message les. Allows execute access only, if the le's security provisions allow execute access. This access allows read/write access to any loaded le. The program must be running in PM to specify execute access. This option is not valid for message les.
FOPEN Note The le system does not guarantee exclusive access, even when FLOCK and FUNLOCK are used, unless all programs that access the le cooperate by using locking. A program that opens the le with dynamic locking enabled will still be allowd to modify the le, even if it never calls FLOCK. 8:2 Exclusive option Indicates continuous exclusive access to this le, from open to close. Use this option when performing a critical operation (for example, updating the le).
FOPEN to the calling process. If another HPFOPEN/FOPEN call that violates the read only restriction is issued while read-share access is in e ect, that call fails and an error code is returned to the calling process. Request read-share access only if the lock access mode is allowed by the security provisions for the le. 11 Share access. After the le is opened, concurrent access to this le by any process is permitted, in any access mode, subject to other security provisions in e ect.
FOPEN device character array (optional) Passes a string of ASCII characters terminating with any nonalphanumeric character except a slash (/) or period (.), designating the device where the le is to reside. For a KSAM le, the device must be a random access device such as a disk. ksamparam Default: DISC character array (optional) Contains a description of the KSAM XL parameters including the primary key and up to 15 alternate keys. If a new le is being created, this parameter must be speci ed.
FOPEN 9:1 8:1 0:9 with the FUPDATE intrinsic for les that are opened for sequential processing. This enables KSAM processing of COBOL information according to COBOL standards. Enter 1 if the le is programmatically accessed by the COBOL programming language. Enter 0 if the le is not programmatically accessed by the COBOL programming language. This enables KSAM to process COBOL information according to COBOL standards. Enter 1 if selecting optimal block size. Enter 0.
FOPEN Key Length Bits 4:12 specify the key length. Enter the length of the key in bytes. A maximum of 255 bytes is allowed, but the length is dependent on the type of key data speci ed. Key Location Enter the relative location in bytes of the key eld in the record. Note that the rst byte of the record is considered 1. Duplicate Key Flag Bits 0:1 specify the duplicate key ag. Enter 1 if duplicate key values are allowed for this key. Enter 0 if duplicate key values are not allowed for this key.
FOPEN numextent 16-bit signed integer by value (optional) Passes a value in the range 1 to 32 that determines the number of extents for the le. If a value of 1 and an initialloc value of 1 is speci ed, the le is created as one contiguous extent of disk space. If a value >1 is speci ed, a variable number of extents (with varying extent sizes) are allocated on a need basis. Applicable only at le creation.
FOPEN Table 9-5.
FOPEN Table 9-5. FOPEN/HPFOPEN Parameter Equivalents (continued) FOPEN Parameter numbu ers: Bits (11:5) Numbu ers Bits (4:7) Spooler copies Bits (0:4) Output priority lesize 44, numbu ers 34, spooler copies 27, output priority 35, lesize numextent 47, numextent initialloc 36, initial allocation lecode Operation Notes HPFOPEN Itemnum,Item 37, lecode Figure 9-6 shows the format of the KSAM parameter.
FOPEN Figure 9-6. FOPEN KSAM XL Parameter Format A le can be referenced by its formal le designator. When executed, a unique le number is returned to the process. This le number, rather than the formal le designator, is used in subsequent calls to this le.
FOPEN Condition Codes CCE CCG CCL Request granted. The le is open. Not returned. Request denied. For example, another process already has exclusive or semi-exclusive access for this le, the privilege level of this le is not user (3), or an initial allocation of disk space cannot be made due to lack of disk space. If the le is not opened successfully, the le number value returned by FOPEN is 0. Call the FCHECK intrinsic for more details.
Sets the logical and physical record pointers to the speci ed record. FPOINT Syntax I16V I32V FPOINT( lenum,lrecnum); Parameters lenum lrecnum 16-bit signed integer by value (required) Passes the le number of the le where the pointer is to be set. 32-bit signed integer by value (required) Passes the relative physical record number where the physical record pointer is to be positioned. Record numbering starts with zero or one, depending on how the le was created.
FREAD Reads a logical record in key sequence from a le to the bu er. FREAD Syntax I16 I16V UDS I16V lgth:=FREAD( lenum,bu er,length); Functional Return Parameters lgth 16-bit signed integer (assigned functional return) Returns the length of the data transferred to bu er : If a negative value is passed in the length parameter, the lgth is a positive value indicating the number of bytes transferred.
FREAD Operation Notes This intrinsic reads the advance ag and advances to the next record if the ag is set to TRUE. It positions the logical record pointer and the physical pointer to the appropriate record. When its function is complete, it sets the advance ag to TRUE. When the logical end-of-data is encountered, CCG is returned to the process. Condition Codes CCE CCG CCL Request granted. The information was read. Request denied. The logical end-of-data was encountered during reading. Request denied.
FREADBYKEY Reads a logical record based on key value from a KSAM le to the target. FREADBYKEY Syntax I16 I16V LA I16V CA lgth:=FREADBYKEY( lenum,bu er,length,value, I16V location); Functional Return lgth 16-bit signed integer by value (assigned functional return) Returns the length of the information transferred. If lgth is positive, it is a halfword count. If lgth is negative, it is a byte count. If lgth is 0, the position is identi ed, but the data is not returned.
FREADBYKEY Operation Notes This intrinsic does not read the advance ag. It positions the logical record pointer and the physical pointer to the appropriate record. When its function is complete, it sets the advance ag to FALSE. Condition Codes CCE CCG CCL Request granted. Request denied. The logical end-of-data or beginning-of-data was encountered during the read. Request denied. An error occurred. Either an I/O error occurred or the key could not be located.
FREADC Reads a logical record in physical sequence from a KSAM le to the target. FREADC Syntax I16 I16V LAI 16V lgth:=FREADC( lenum,bu er,length); Functional Return lgth 16-bit signed integer by value (assigned functional return) Returns the length of the information transferred. If lgth is positive, it is a halfword count. If lgth is negative, it is a byte count. If lgth is 0, the position is identi ed, but the data is not returned.
FREADC Condition Codes CCE CCG CCL Request granted. Request denied. The logical end-of-data was encountered during the read. Request denied. An error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
FREADDIR Reads a logical record located by its physical record number from a le to the bu er. FREADDIR Syntax I16V UDS I16V I32V FREADDIR( lenum,bu er,length,lrecnum); Parameters lenum 16-bit signed integer by value (required) bu er Passes the le number of the le to be read. user-de ned structure (required) length Returns the record that was read. This structure should be large enough to hold all of the information to be transferred.
FREADDIR Condition Codes CCE CCG CCL Request granted. The information was read. Request denied. End-of-data was encountered. Request denied. The information was not read; an error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
FREADLABEL Reads a user-de ned le label. FREADLABEL Syntax I16V I16V I16V FREADLABEL( lenum,bu er,length,labelid); Parameters lenum UDS 16-bit signed integer by value (required) bu er Passes the le number of the le whose label is to be read. user-de ned structure (required) length Returns the label that was read. This structure must be large enough to hold the number of halfwords speci ed by length .
Marks the current record in a KSAM le for deletion. FREMOVE Syntax I16V FREMOVE( lenum) Parameters lenum 16-bit signed integer by value (required) Passes the le number of the le where the record is to be deleted. Operation Notes Split stack calls are permitted. When executed, the rst bit in the record header is set to 1. This intrinsic does not read the advance ag. It sets the logical record pointer and the physical physical pointer to the appropriate record.
FRENAME Renames an open disk le (and its lockword, if applicable). The le being renamed must be either: A new le. An old le (permanent or temporary), opened for exclusive access with the exclusive option of the HPFOPEN/FOPEN intrinsics, and with security provisions allowing write access. FRENAME Syntax I16V CA FRENAME( lenum,formaldesig); Parameters lenum formaldesig 16-bit signed integer by value (required) Passes the le number of the le to be renamed.
FRENAME account Operation Notes Is the account name where the le is to reside. (Optional portion of formaldesig .) If renaming a new or temporary le that was created, specify any account that shares the same volume set as the le being renamed. A permanent le cannot be renamed across account boundaries. If other than the current account name is speci ed for a permanent le, the CCL (1) error condition is returned and the le retains its old name. The formaldesig parameter uses MPE-escaped semantics.
FRENAME Condition Codes CCE (2) CCG (0) CCL (1) Request granted. Not returned. Request denied. An error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
Moves a record pointer forward or backward in a le. FSPACE Syntax I16V I16V FSPACE( lenum,displacement); Parameters lenum displacement 16-bit signed integer by value (required) Passes the le number of the le on which spacing is to be done. 16-bit signed integer by value (required) Passes the number of logical records to be spaced over, relative to the current position of the logical record pointer. A positive value signi es forward spacing, a negative value signi es backward spacing.
FUNLOCK Dynamically unlocks a le. FUNLOCK Syntax I16V FUNLOCK( lenum); Parameters lenum 16-bit signed integer by value (required) Passes the le number of the le whose global RIN is to be unlocked. Condition Codes CCE CCG CCL Request granted. Request denied. The le had not been locked by the calling process. Request denied. The le was not opened with the dynamic locking aoption of the FOPEN/HPFOPEN intrinsic, or the lenum parameter is invalid.
Updates the contents of a logical record in a le. FUPDATE Syntax I16V UDS I16V FUPDATE( lenum,bu er,length); Parameters lenum 16-bit signed integer by value (required) bu er Passes the le number of the le to be updated. user-de ned structure (required) length Passes the record to be written in the update. 16-bit signed integer by value (required) Passes the number of halfwords or bytes to be written to the le. A positive value is in halfwords; a negative value is in bytes.
FUPDATE Condition Codes CCE CCG CCL Request granted. Request denied. An end-of- le condition was encountered during updating. Request denied. An error occurred. The length exceeds the size of the record, length does not include all the keys, or a disk I/O error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual (32650-90028) for other codes pertaining to KSAM les.
Writes a logical record from the bu er to a le. FWRITE Syntax I16V UDS I16V U16V FWRITE( lenum,bu er,length,controlcode); Parameters lenum 16-bit signed integer by value (required) bu er Passes the le number of the le to be written on. user-de ned structure (required) length Passes the record to be written. 16-bit signed integer by value (required) Passes the number of halfwords or bytes to be written to the record. If this value is positive, it signi es halfwords; if negative, bytes.
FWRITE Condition Codes CCE CCG CCL Request granted. Request denied. The physical bounds of the le prevented further writing. Request denied. An error occurred: an I/O error occurred; a duplicate key value occurred when duplicates are not allowed length does not include all keys sequential processing was speci ed in the ag word of the ksamparam in FOPEN and the primary key is not in ascending order.
Writes a user-de ned le label. FWRITELABEL Syntax I16V UDS I16V I16V FWRITELABEL( lenum,bu er,length,labelid); Parameters lenum 16-bit signed integer by value (required) bu er Passes the le number of the le to be labeled. user-de ned structure (required) length Passes the label to be written. If the le is a labeled magnetic tape le, this label must be 40 halfwords in length. 16-bit signed integer by value (optional) labelid Passes the number of halfwords or bytes to be written.
HPFOPEN Establishes access to a le and creates a le. HPFOPEN Syntax I32 I32 I32V * HPFOPEN( lenum,status[,itemnum,item] [...]); Note Parameters Up to 41 itemnum/item pairs can be speci ed. lenum 32-bit signed integer by reference (required) Returns a le number used to identify the opened le in subsequent intrinsic calls. status Can be used safely with all le system intrinsics that require a 16-bit le number to be passed in the intrinsic call (for example, FREAD, FWRITE, FCLOSE).
HPFOPEN Note An itemnum takes precedence over any previously speci ed duplicate itemnum . Any duplicated itemnum is agged as a warning. Table 9-6. HPFOPEN Itemnum/Item Values Itemnum Mnemonic End of option list: There is no corresponding item . The absence of an itemnum after the last itemnum,item pair is equivalent to specifying this option. 0 2 Item Description CA Formal designator: Passes a formal le designator, following MPE/iX le naming conventions.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 3 I32 Item Description Domain: Passes a value indicating which le domain MPE/iX searches to locate the le. A nameless disk le must always be a new le. A device le (such as a tape or terminal) always resides in the system le domain (permanent le directory). Always specify a device le as old or permanent. The following values are valid: 0 The le is a new temporary le. It is not placed in a directory.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 6 I32 Item Description Record format: Passes a value indicating the internal record structure desired for the le. This option is applicable only at le creation. Only a xed-length record is allowed for KSAM XL les (0). Default: 0 9 I32 Disallow le equation: Passes a value indicating whether or not MPE/iX le equations are allowed. A leading * in a formal le designator overrides the setting to disallow FILE equations.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 11 I32 Item Description Access type: Passes a value indicating the type of access intended for the le. This option restricts usage of the le system intrinsics. The following values are valid: 0 Read access only, if the le's security provisions allow read access. FWRITE, FUPDATE , and FREMOVE intrinsic calls cannot reference this le. The end-of- le (EOF) is not changed.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 12 I32 Item Description Dynamic locking: Passes a value enabling or disabling le locking for the le. When speci ed, the FLOCK and FUNLOCK intrinsics can be used to dynamically permit or restrict concurrent access to a disk le by other processes at speci ed times.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 13 I32 Item Description Exclusive: Passes a value indicating continuous exclusive access to the le, from open to close. Use this option when performing a critical operation (for example, updating the le). The following values are valid: 0 If itemnum =11 speci es read only access, read-share access takes e ect. Otherwise, exclusive access takes e ect. Regardless of which access option was selected, FFILEINFO reports zero.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 17 I32 Item Description Copy mode: Passes a value that determines if any le should be treated as a standard sequential le so it can be copied by logical record or physical block to another le. The following values are valid: 0 The le is accessed as its own le type (for example, a message le is treated as a message le). 1 The le is to be treated as a standard (STD) le, with variable-length records.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 19 I32 Item Description Record size: Passes the size, in bytes, of the logical records in the le. Valid range is dependent upon both storage format (ASCII or binary) and record format. For xed-length and unde ned-length ASCII les, a record size can be speci ed in the range 1 to 32,767.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 22 CA Item Description Volume class: Passes a character array representing a volume class name where the le space is to be restricted. This option is applicable only at le creation. A volume class is a subset of volumes within a volume set. The volume class name must be a valid volume class name residing on the volume set bound to the volume (the volume set is an attribute of the group in which the le resides).
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 26 CA Item Description Remote environment: Passes the node name of the remote computer where the le is located. This option is used when referencing a le located on a remote computer. Default: No node name passed (local le access) A character placed in the rst element designates the delimiter used by HPFOPEN to search for the end of the character array.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 36 I32 Item Description Initial allocation: Passes a positive integer value indicating the number of extents to be allocated to the le initially. This option is applicable only at le creation. Default: 0 37 I32 Filecode: Passes a value that can be used as a le code to identify the type of le. This code is recorded in the le label and is accessible through the FFILEINFO intrinsic.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 42 CA Item Description Device class: Passes a device class where the le will reside. The le system uses the device class name to select a nonshareable device from a con gured list of available devices. The name can have a length of up to eight alphanumeric characters, beginning with a letter (for example, TAPE). If a device class is speci ed, the le is allocated to any available device in that class.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 47 I32 Item Description Numextents: Passes a value in the range 1 to 32 that determines the number of extents for the le. This parameter is kept mainly for compatibility with MPE/V. Its main usefulness is that a le may be created with 1 contiguous extent. If a value of 1 is speci ed, the le is created as one contiguous extent of disk space.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 50 I32 Item Description Final disposition: Passes a value indicating the nal disposition of the le at close time (signi cant only for les on disk and magnetic tape). A corresponding parameter in a FILE command can override this option, unless le equations are disallowed with itemnum =9. The following values are valid: 0 No change. The disposition remains as it was before the le was opened.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 51 Item Description Pascal XL string: Passes a formal le designator, following MPE/iX le naming conventions, but using the Pascal/iX STRING type format. This option is identical to itemnum =2 except for the type of item. No delimiters are needed.
HPFOPEN Table 9-6. HPFOPEN Itemnum/Item Values (continued) Itemnum Mnemonic 54 REC Item Description KSAM parm: Passes a record that de nes the keys for a new KSAM le. The format of the parameter is the same as the FOPEN intrinsic ksamparam eld. Default: No record passed 55 56 Reserved for MPE/iX I32 Object class: Passes a user object class number, in the range 0 to 10, that is associated with the le.
HPFOPEN Table 9-7.
HPFOPEN Table 9-7. FOPEN/HPFOPEN Parameter Equivalents (continued) FOPEN Parameter numbu ers: Bits (11:5) Numbu ers Bits (4:7) Spooler copies Bits (0:4) Output priority lesize 44, numbu ers 34, spooler copies 27, output priority 35, lesize numextent 47, numextent initialloc 36, initial allocation lecode Operation Notes HPFOPEN Itemnum,Item 37, lecode Enables creation of a new le on a shareable device and de nes the physical characteristics of that le prior to access.
HPFOPEN Figure 9-7.
A COBOL Intrinsics COBOL compilers (COBOL 68 and earlier) required special intrinsics to access keyed les. The following intrinsics are provided only for the maintenance of COBOL 68 or earlier COBOL programs using KSAM structures. Note Calling a KSAM Procedure Do not use these intrinsics for new programming. Current COBOL le access modules provide KSAM le access. KSAM les are accessed from COBOL programs through calls to a set of procedures.
parameter input/output operation performed on the le by the called procedure. One or more parameters, depending on the particular procedure called, that further de ne 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 speci ed 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.
lenumber lename input/output type access mode previous operation A number identifying the le returned by the CKOPEN procedure after the le named in halfwords 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 de ned.) It must be de ned as a COMPUTATIONAL item. The name of the KSAM le.
lock/unlock d c altered by the programmer. It must be de ned as a COMPUTATIONAL item. A code in the left byte of halfword 8 of the le table that indicates whether a CKLOCK or CKUNLOCK has been performed successfully since the operation speci ed in previous operation: 10 CKLOCK successful 11 CKUNLOCK successful A sample le table de nition might be: WORKING-STORAGE SECTION. FILE_TABLE. 01 KSAM_FILE.
02 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. 10 At End condition | In a sequential read using CKREAD, no next logical record was in the le.
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, the call was not successful. d c d c d c For example, a sample status parameter de nition might be: WORKING-STORAGE SECTION. .. . 01 STAT. 02 STATUS-KEY-1 PIC X. 02 STATUS-KEY-2 PIC X.
Table A-1. Positioning the Logical Record Pointer Procedure Name PointerDependent Position of Pointer After Execution of Procedure CKSTART NO Points to key whose value was speci ed in call. CKREADBYKEY NO Points to key whose value was speci ed in call. CKWRITE NO Points to key whose value is next in key sequence to key value in record just written.
Sample KSAM File The le KSAMFILE illustrated in Figure A-2 is used in all subsequent examples associated with the COBOL procedure calls. Figure A-2. Representation of KSAMFILE Used in COBOL Examples A File Description in Working Storage for Figure A-2 appears on the following page.
File Description in Working Storage (Figure A-2). WORKING-STORAGE SECTION 77 RECSIZE PIC S9(4) COMP VALUE 74. 77 RESULT PIC 9(4) VALUE 0. 01 REC. 03 FILLER PIC XX VALUE SPACES. 03 NAME PIC X(20). 03 PHONE PIC X(8). 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 FILETABLE PIC S9(4) COMP VALUE 0. 03 FILENAME PIC X(8) VALUE "KSAMFILE". 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.
A call to CKCLOSE terminates le processing for the speci ed KSAM le. CKCLOSE 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.
CKDELETE CKDELETE This procedure logically deletes a record from a KSAM le. letable, status In order to logically delete records from a KSAM le, you can use the procedure CKDELETE. If reuse is not speci ed, then a logically deleted record is marked for deletion, 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.
CKDELETE d .. . c CKLOCK <--- to lock le CKSTART or CKREADBYKEY <--- to position pointer CKDELETE<--- to delete record at which pointer is positioned CKUNLOCK<--- to unlock le a b Following the call to CKDELETE, the pointer is positioned to the next key following the key in the deleted record. The following examples show the use of CKDELETE for sequential access using CKREAD and for random access using CKREADBYKEY.
CKDELETE d a FIND-REC. MOVE 0 TO RELOP.<--- test for equality between primary key and KEY MOVE "P" TO KEYVAL. MOVE 3 TO KEYLOC. MOVE 1 TO KEYLENGTH.<--- check rst character only CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH. IF STATUS-KEY-1 = "0" THEN GO TO READ-REC. IF STAT = "23" THEN DISPLAY "NO RECORD FOUND" GO TO FINISH. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKERROR NO.=", RESULT GO TO FINISH. READ-REC.
CKDELETE d c In the second example, 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 "CKOPEN" USING FILETABLE, STAT. . . . READ-KEY. READ DATA-FILE INTO DAT; AT END GO TO FINISH. CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, NAME OF DAT, KEYLOC, RECSIZE.
CKERROR Converts KSAM le system error code returned in status to a display format number. CKERROR CALL "CKERROR" USING status, result Whenever a 9 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.
A call to CKLOCK dynamically locks a KSAM le. CKLOCK letable, status, lockcond When access is shared, you must lock the le before calling CKWRITE, CKREWRITE, or CKDELETE. This ensures that another user cannot attempt to modify the le at the same time. 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.
CKLOCK your process will continue. If, however, lockcond is set to 1, your process suspends until the other user unlocks the le or logs o . d 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.
A call to procedure CKOPEN initiates KSAM le processing. CKOPEN letable, status In order to process a KSAM le, it must be opened with a call to the CKOPEN procedure. CKOPEN initiates processing, speci es the type of processing and the access mode; the le must have been created previously. 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).
CKOPEN 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. Figure A-3.
CKOPEN 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 mode, any of the KSAM procedures may be called.
CKOPEN writing. Use this input/output type if you want to save existing data in a le to which you are writing. Dynamic access allows you to use any call to process a le opened for input/output. 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.
CKOPEN 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 reopen the le: d CALL "CKCLOSE" USING FILETABLE, STAT. IF STATUS-KEY-1 ="9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKCLOSE FAILED -- ERROR NO.", STOP RUN. MOVE 1 TO I-O-TYPE.<--- output only CALL "CKOPEN" USlNG FILETABLE, STAT.
CKOPENSHR CKOPENSHR A call to CKOPENSHR initiates KSAM le processing with dynamic locking and shared access allowed. 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, speci es the type of processing, and speci es the access mode. The le must have been created previously.
A call to procedure CKREAD makes available the next logical record from a KSAM le. CKREAD 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 speci ed as either sequential or dynamic.
CKREAD call to CKREWRITE or CKDELETE. This ensures that the correct record is modi ed or deleted. Because CKREAD is a pointer-dependent procedure, 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 program being aware of it. For this reason, you should lock the le, position the pointer with a pointer-independent procedure, and then call CKREAD.
CKREAD d The following example provides a sequential read with shared access. PROCEDURE DIVISION. START. . . . MOVE 0 TO I-O-TYPE, A-MODE. CALL "CKOPENSHR" USING FILETABLE, STAT <--- open le for shared a access . . . <--- test status FIND-RECORD. MOVE 2 TO RELOP. MOVE "000-0000" TO KEYVAL. MOVE 23 TO KEYLOC, MOVE 8 TO KEYLENGTH. MOVE 1 TO LOCKCOND. CALL "CKLOCK" USING FILETABLE, STAT, LOCKCOND.<--- lock le unconditionally CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.
CKREADBYKEY A call to CKREADBYKEY makes available a record identi ed by key value from a KSAM le. CKREADBYKEY 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.
CKREADBYKEY Successful execution of CKREADBYKEY is indicated by the value 0 in the left byte of status . Unsuccessful execution is indicated by either the invalid key return or by a value of 9 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. In the following examples, update information is read into the area called DAT in the WORKING-STORAGE SECTION.
CKREADBYKEY d c Read a record located by its primary key value: a DATA DIVISION. .. . WORKING-STORAGE SECTION. 77 KEYLOC PIC S9(4) COMP. .. . PROCEDURE DIVISION. START. .. . MOVE 2 TO I-O-TYPE, A-MODE.<--- prepare to open for input/output, dynamic access CALL "CKOPEN" USING FILETABLE, STAT. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKOPEN ERROR NO. ", RESULT. IF STATUS-KEY-1 NOT="O" THEN DISPLAY "CKOPEN FAILED" STOP RUN. FIND-RECORD.
CKREADBYKEY 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 : d FIND RECORD. READ NEW-DATA INTO DAT; AT END GO TO FINISH. MOVE 23 TO KEYLOC. CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, PHONE OF DAT, KEYLOC, RECSIZE.
CKREWRITE CKREWRITE The procedure CKREWRITE replaces a record existing in a KSAM le with another record having a matching primary key. 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.
CKREWRITE 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 index area.
CKREWRITE and CKREWRITE before unlocking the le with CKUNLOCK. This ensures that no other users change the position of the pointer while you are sequentially updating the le. 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.
CKREWRITE d DATA DIVISION. .. . WORKING-STORAGE SECTION. \ 77 RELOP PIC S9(4) COMP.| 77 KEYVAL PIC X(20). |<--- items required by CKSTART 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 "CKOPEN" USING FILETABLE, STAT. . . . <--- check status UPDATE-FILE. MOVE 1 TO RELOP. MOVE "000-0000" TO KEYVAL.<--- set up CKSTART parameters to start MOVE 23 TO KEYLOC. reading at lowest alternate key a value c MOVE 8 TO KEYLENGTH.
CKREWRITE d c d c a WRITE-RECORD. MOVE SPACES TO OTHERDATA OF REC. CALL "CKREWRITE" USING FILETABLE, IF STATUS-KEY-1 = "0" THEN DISPLAY NAME OF"DATA CLEARED" GO TO READ-RECORD. DISPLAY "CKREWRITE ERROR, STATUS=", IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT, DISPLAY "CKERROR NO.=", GO TO READ-RECORD. b The second example nds the record with the primary key \ECKSTEIN, LEO "and changes the value of the secondary key to \257-5137": PROCEDURE DIVISION. START. .. .
CKREWRITE A call to procedure CKSTART allows you to position the record pointer to a particular record in a KSAM le de ned by its primary or alternate key value. CKSTART letable, status, relop, key, keyloc, keylength In order to position the current record pointer to a location in the le de ned by a key value, call CKSTART.
CKSTART Operation Notes When CKSTART is executed, the index area is searched for the rst key in the set of keys at location keyloc whose value when compared with key satis es the comparison speci ed by relop . The current record pointer is positioned to the beginning of the record in the data area associated with the key found by CKSTART.
CKSTART d NEW-POSITION. MOVE 2 TO RELOP.<--- KEYVAL a nd key value greater than or equal to MOVE "000-0000" TO KEYVAL. MOVE 23 TO KEYLOC. MOVE 8 TO KEYLENGTH. CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH. IF STAT = "23" THEN GO TO FINISH.<--- no record found IF STATUS-KEY-1 = "0" THEN GO TO READ-BY-PHONE.<--- lowest key value found DISPLAY "CKSTART ERROR, STATUS", STAT. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "ERROR NUM", RESULT. GO TO FINISH.
CKSTART d c In the next example, CKSTART is used to position to the beginning of the series of names beginning with the letter \T". The KSAM le key is located at character position 3 (NAME key); the parameter KEYVAL is set to the value \T"; 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".
CKUNLOCK A call to CKUNLOCK unlocks a KSAM le dynamically locked by CKLOCK. 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.
CKUNLOCK d c 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 a PICTURE 9(4) VALUE 0. PICTURE X PICTURE X VALUE " ". VALUE " ". PICTURE PICTURE PICTURE PICTURE PICTURE S9(4) X(8) S9(4) S9(4) S9(4) COMP VALUE VALUE COMP VALUE COMP VALUE COMP VALUE 0. "KSAMFILE". 0. 0. 0. PROCEDURE DIVISION. .. . CALL "CKUNLOCK" USING FILETABLE, STATUSKEY.
Procedure CKWRITE copies a logical record from the program's data area to an output or an input/output KSAM le. CKWRITE 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.
CKWRITE 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. 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.
CKWRITE d c 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). 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) 03 FILENAME PIC X(8) 03 I-O-TYPE PIC S9(4) 03 A-MODE PIC S9(4) 03 PREV-OP PIC S9(4) 01 STAT. 03 STATUS-KEY-1 PIC X. .. 03 STATUS-KEY-2 PIC X. . PROCEDURE DIVISION. START. .. . A-44 COBOL Intrinsics a COMP VALUE 74.
CKWRITE d c a MOVE 1 TO I-O-TYPE,<--- set type to output only CALL "CKOPEN" USING FILETABLE, STAT. IF STATUS-KEY-1="O" THEN GO TO WRITE-F. DISPLAY "CKOPEN ERROR, STATUS = ", STAT. IF STATUS-KEY-1= "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKERROR NO. ", RESULT. STOP RUN. WRITE-F. READ DATA-FILE INTO DAT; AT END GO TO FINISH. MOVE CORRESPONDING DAT TO REC. CALL "CKWRITE" USING FILETABLE, STAT, REC, RECSIZE. IF STATUS-KEY-1="0" THEN DISPLAY REC. GO TO WRITE-F.
CKWRITE d c The second example, using the same DATA DIVISION and the same FINISH procedure, writes one record to the le containing \ADAMSON JOHN" as its primary key value. PROCEDURE DIVISION. START. . . . MOVE 1 TO I-O TYPE.<--- output only MOVE 2 TO A-MODE.<--- random access CALL "CKOPEN"USING FILETABLE, STAT. . . . check status FIND-REC. READ DATA-FILE INTO DAT; AT END GO TO FINISH. IF NAME OF DAT = "ADAMSON JOHN" THEN GO TO WRlTE-REC; ELSE GO TO FIND-REC. WRITE-REC. MOVE CORRESPONDING DAT TO REC.
Examples of KSAM File Access Sequential Write 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 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. The rst example reads data from an input le into working storage and then writes it to a KSAM le.
d Input to EXAMP1: NOLAN HOSODA ECKSTEIN CARDIN PASBY SEELY ROBERT TURNEWR WHITE WESTER **END OF c a Program 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 JACK 923-4975 967 REED AVE. JOE 227-8214 1180 SAINT PETER CT. LEO 287-5137 5303 STEVENS CREEK RICK 578-7018 11100 WOLFE ROAD LINDA 295-1187 TOWN & CNTRY VILLAGE HENRY 293-4220 1144 LIBERTY ST.
d 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 a PROCEDURE DIVISION. START. OPEN INPUT SEQ-DATA CALL "CKOPEN" USING FILETABLE, STATUSKEY. IF STATUS-KEY-1="9" THEN CALL "CKERROR" USING STATUSKEY, RESULT DISPLAY "CKOPEN ERROR NO.", RESULT. IF STATUS-KEY-1 NOT = "0" THEN DISPLAY "CKOPEN FAILED" STOP RUN. LOOP.
Sequential Read d c 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 EXAMP2: 001000 IDENTIFICATION DIVISION. 001100 PROGRAM-ID. EXAMP2.
d c 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 007100 007200 007300 007400 a PROCEDURE DIVISION. START. CALL "CKOPEN" USING FILETABLE, STATUSKEY. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STATUSKEY, RESULT DISPLAY "CKOPEN ERROR NO.", RESULT. IF STATUS-KEY-1 NOT = "0" THEN DISPLAY "CKOPEN FAILED" STOP RUN.
d c 007500 007600 007700 007800 007900 008000 008100 008200 008400 008400 008500 008600 008700 008800 008900 009000 009100 009200 LOOP2. CALL "CKREAD" USING FILETABLE, STATUSKEY, DATA-REC, RECSIZE. IF STATUS-KEY-1 = "1" THEN GO TO FINISH. IF STATUS-KEY-1 = "0" THEN DISPLAY DATA-REC ELSE DISPLAY "CKREAD ERROR, STATUS =", STATUSKEY IF STATUS-KEY-1 ="9" THEN CALL "CKERROR" USING STATUSKEY, RESULT DISPLAY "ERROR NO. ", RESULT. GO TO LOOP2. FINISH. CALL "CKCLOSE" USING FILETABLE, STATUSKEY.
d c PHONE NO. HOSODA ROBERT WESTER ECKSTEIN SEELY PASBY WHITE CARDIN NOLAN TURNEWR ORDER: JOE GERRY ELDER LEO HENRY LINDA GORDON RICK JACK IVAN a 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 LIBERTY ST. TOWN & 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.
d c a 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 "NEWDATA". DATA DIVISION. FILE SECTION. FD NEW-DATA LABEL RECORDS ARE STANDARD.
d c 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 007100 007200 007300 007400 007500 007600 007700 007800 007900 008000 008100 008200 008300 008400 008500 008600 a PROCEDURE DIVISION. START. OPEN INPUT NEW-DATA. CALL "CKOPEN" USING FILETABLE, STATUSKEY. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STATUSKEY, RESULT DISPLAY "CKOPEN ERROR NO.", RESULT.
d c 008700 008800 008900 009000 009100 009200 009300 009400 009500 009600 009700 009800 009900 010000 010100 010200 010300 010400 010500 010600 010700 010800 010900 011000 011100 011200 011300 011400 011500 011600 011700 011800 DELETE-REC. CALL "CKDELETE" USING FILETABLE, STATUSKEY. IF STATUS-KEY-1 = "0" THEN DISPLAY MASTER-REC, "DELETED" GO TO LOOP. DISPLAY "CKDELETE ERROR, STATUS =" STATUSKEY. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR", USING STATUSKEY, RESULT DISPLAY "ERROR NO.", RESULT. GO TO LOOP.
d a Input to EXAMP3: NOLAN SMITH ECKSTEIN CARDIN PASBY JANE ROBERT TURNEW FORD WESTER JACK JOHN LEO RICK LINDAL MARY GERRY IVAN GERALD ELDER 923-4975 555-1212 1 ANY STREET. 102 FIRST ST. SUNNYVALE CA. OUR TOWN CA. 257-7000 11100 WOLFE ROAD CUPERTINO CA. 565-9090 259-5535 1776 BICENTENNIAL ST. 12345 TELEGRAPH AVE. AMAHEIM CA. BERKELEY CA. 555-1976 287-4598 1600 PENNSYLVANIA 1256 KINGFISHER ST. WASHINGTON DC. SUNNYVALE CA.
B BASIC/V Intrinsics The BASIC/V interpreter and compiler require special intrinsics to access existing KSAM les. The following intrinsics were developed for these BASIC/V programs. Note Overview These intrinsics are provided to allow BASIC/V programs to run in compatibility mode. Do not use these intrinsics when writing new programs in other languages or when porting BASIC/V programs. If you are porting to Business BASIC/XL, use the standard le intrinsics discussed in this manual.
Calling a KSAM Procedure The KSAM interface procedures are called from a BASIC program with a CALL statement of the following general form: statementlabel CALL procname ( lenumber, status [,parameterlist]) Where: statementlabel The number of the statement in the program. procname The KSAM access procedure to which control is transferred. lenumber A numeric variable whose value identi es an open KSAM le. This parameter must be present.
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 speci c codes to further de ne the status. The operation of a called procedure is successful only if the rst character returned in status is zero.
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 Invalid key; Boundary violation | An attempt was made with BKWRITE to write beyond the externally de ned boundaries of the le; that is, to write past the end-of- le. 71 Request denied; File already locked | An attempt was made to lock a le with BKLOCK and the le is already locked.
d c a 10 .. DIM S$(4) . 50 IF S$(1;1) = "0" THEN PRINT "SUCCESS" 60 .. ELSE PRINT "ERRORCODE=";S$ . 100 IF S$(1;1)= "9" THEN DO 110 PRINT "FILE ERROR=";S$(2) 120 .. DOEND . 200 IFS$ = "22" THEN DO 210 PRINT "DUPLICATE KEY ERROR" 220 DOEND 300 IF S$(2)= "2" THEN PRINT "DUPLICATE KEY" b 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.
Table B-1. Positioning the Logical Record Pointer PointerDependent Position of Pointer After Execution of Procedure BKSTART NO Points to key whose value was speci ed in call. BKREADBYKEY NO Points to key whose value was speci ed in call. BKWRITE NO Points to key whose value is next in ascending key sequence to key value in record just written.
BKCLOSE A call to BKCLOSE terminates le processing for the speci ed KSAM le. BKCLOSE 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 reopens the le. BKCLOSE can be executed only for a le that is open. Parameters lenum status Operation Notes A numeric variable containing the le number that identi es the le; this number was returned by the last call to BKOPEN.
BKCLOSE d c 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 THIS CALL SUCCEEDED REM IF S$[1,1]<>"0" THEN DO REM N$ CONTAINS THE NAME OF THE KSAM FILE REM S$ CONTAINS THE STATUS CODE SET BY
BKDELETE 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. If reuse is not speci ed, then a logically deleted record is marked for deletion, but is not physically removed from the le. The connection between a data record marked for deletion and the index area is severed.
BKDELETE are copied. Records marked for deletion are dropped from the data area during the copy. The new le is more compact, particularly if many records had been deleted from the old le. 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 ensures that no other user alters the record position between the call that locates the record and the call that deletes it.
BKDELETE d c 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 a 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
A call to BKERROR returns a message corresponding to the status value. BKERROR 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.
BKERROR d c 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. 10 .. . 50 60 70 80 DIM S$(4),M$(72) IF S$(1;1)="9" THEN DO CALL BKERROR(S$,M$) PRINT"FILE ERROR";S$(2);"MEANS";M$ DOEND a b Suppose the value returned in status is 9172.
Dynamically locks KSAM le during shared access. BKLOCK 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.
BKLOCK Operation Notes 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. 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.
A call to procedure BKOPEN initiates KSAM le processing. BKOPEN 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 speci es how the le is to be processed. BKOPEN does not create the le; it must have been created previously. To open a le means to make it available for processing.
BKOPEN access lock exclusive A numeric expression whose value indicates one of the permissible access types: 0 Read only . Use of procedures BKWRITE, BKREWRITE, and BKDELETE are prohibited. 1 Write only . Overwrites previously written data. Use of the procedures BKREAD, BKREADBYKEY, BKREWRITE, BKDELETE, and BKSTART are prohibited. 2 Write only . Saves previously written data and adds data. Use of the procedures BKREAD, BKREADBYKEY , BKREWRITE, BKDELETE, and BKSTART are prohibited. 3 Read and write .
BKOPEN 2 3 sequence Semi-exclusive. 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.) Shared. 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 e ect. (Optional parameter ) Default: If omitted or out of range, exclusive equals 2, semi-exclusive access.
BKOPEN There are two types of write only access. One clears any existing records before writing the speci ed 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 speci ed if you want to ensure that the le is not changed. This mode prohibits the writing of new records, and rewriting or deleting of existing records.
BKOPEN 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).
BKOPEN read the le in physical 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 physical order. The example in Figure B-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 ).
BKOPEN d c 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] <-------- status \ DIM N$[26] <------------- lename |- variable dimensions DIM M$[72] <-------- 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 80 BYTES, FIXED, TYP
BKREAD Transfers the next logical record from a KSAM le to a BASIC program. BKREAD CALL BKREAD( lenum,status[,parameterlist]) A call to BKREAD transfers the contents of a record from a KSAM le to a storage area de ned 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.
BKREAD d c Values are read from the current record into the variables speci ed in parameterlist according to the type and length of the variable.
BKREAD A5 A2 A3 B1$ B2$ a 5-word integer array a 2-word integer array a 3-word integer array a 1-character string 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 unde ned values that lled the next ve words of the record. The rst string character is read into B1$, the next two into B2$.
BKREAD d c 10 20 30 40 50 55 60 65 70 .. .
BKREADBYKEY BKREADBYKEY Transfers record identi ed 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 identi ed by a list of variables in the BASIC program. The record to be read is located by matching the speci ed keyvalue with an identical value stored in the record starting at keylocation .
BKREADBYKEY Operation Notes After calling BKREADBYKEY, you should always check the status parameter to determine whether the read was successful. Upon completion of BKREADBYKEY, the variables speci ed in parameterlist contain data read from the record located through the keyvalue and keylocation parameters. The key value in the record to be read must exactly match the speci ed keyvalue . Unlike BKSTART, the only relation between the value in the record and the value in the call is that of equality.
BKREADBYKEY d c 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 a 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 CONT
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 must be locked by BKLOCK before records are rewritten.
BKREWRITE Note Items written to a KSAM le with the BKREWRITE procedure are concatenated; rounding to halfword boundaries does not occur. The example in Figure B-7 writes new values to a record originally written in Figure B-11 and read in Figure B-5. The new values ll an array that had unde ned values in the last ve elements, now de ned as two arrays A3 and A2 by the BKREAD call. The primary key value 23 in location 2 is unchanged.
BKREWRITE d c 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 REM REM REM REM REM REM REM REM REM REM REM a ********************************************************* * 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
BKREWRITE d c 3070 3080 3090 3100 3110 3120 3130 3140 3150 3160 3170 3180 3190 3200 3210 a IF S$[1;1]<>"0 THEN DO REM N$ CONTAINS THE NAME OF THE KSAM FILE REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL PRINT "UNABLE TO REWRITE ";N$;" ERROR ";S$[1;1];" DETAIL ";S$[2] CALL BKERROR(S$,M$) PRINT M$ GOTO 3620 DOEND REM REM ECHO WHAT WAS UPDATED REM PRINT "REWRITTEN RECORD = ";B1;B2 MAT PRINT A5,A3,A2 REM REM THE PROGRAM CONTINUES b Rewriting Record in KSAM File with BKREWRITE (continued) BASI
Positions a KSAM le to a particular record based on a key value. BKSTART 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 alternate key, since BKSTART also allows you to select the key for positioning and for subsequent sequential reads.
BKSTART relation A numeric expression whose value speci es the relation between the speci ed 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 ). > 2 Any value greater than 2 is treated as if it were 2.
BKSTART Whenever a record cannot be found with a key that satis es the relation and value speci ed, the value 23 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.
BKSTART d c 1080 1090 1100 1110 1120 1130 1140 1150 1160 1170 1180 1190 1200 1210 1220 1230 1240 1250 1260 1270 1280 1290 1300 a 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]<>"0" THEN DO REM N$ CONTAINS THE NAME OF THE K
BKSTART d c The example in Figure B-9 positions the record pointer to a record containing a speci c key value. The value is 23; 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, not a value larger than 23.
BKUNLOCK BKUNLOCK Unlocks a KSAM 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.
BKUNLOCK d c 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 DETERMINE WHETHER THE CALL HAS SUCCEEDED REM IF S$(1;1)<>"0" THEN DO REM N$ CONTAINS THE NAME OF THE KSAM FILE REM S$ CONTAINS THE STATU
BKWRITE Writes data from a BASIC program to a KSAM le. BKWRITE 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.
BKWRITE previous primary key value only if the le was created with duplicate key values permitted. Note d c Items written to a KSAM le from a BASIC program are concatenated; rounding to halfword boundaries does not occur. Figure B-11 is an example of writing one string and one integer array to each record of the KSAM le. 10 20 30 40 50 55 60 65 70 80 90 100 110 120 130 135 .. .
BKWRITE d c 570 580 620 630 640 650 660 670 680 690 700 710 720 730 740 750 760 770 780 790 800 810 REM NOTE THAT ONLY THREE BYTES "123" 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 .
C HP C/iX Example Program The following example program shows how a KSAM XL le can be created, accessed, and updated from an HP C/iX program. This program uses features of ANSI C. Compile with INFO=-Aa + e. This example program uses the assert macro to do quick error checking. In a production program, more comprehensive error checking and reporting would be desirable.
open_file(); dump_file(); write_new_records(); update_records(); delete_records(); dump_file(); close_file(); return EXIT_SUCCESS; } static void close_file(void) { /* Close file */ FCLOSE(filenum, 0, 0); assert(ccode()==CCE); } static void create_file(void) { /* Create sample KSAM XL file and load initial test data */ int status; short cmderror; const int ksamxl=3, out=1, recsize=sizeof(record_t), filesize=100, save=1, ascii=1; const struct { short filler_1[10]; unsigned short language_id : 16; short fille
{1,20, 6,1,0,0,0,0}, {1, 4,35,1,0,0,0,0} } }; const record_t test_data[] = { "11111DOE JOHN 1230067898540821201", "03452CUSTER HERB 3218800003160821203", "28766WORKMAN DEBBIE 0006612341520850601", "33678MORSE EUGENE 8760098763160850715" } ; const int test_items = sizeof test_data / sizeof test_data[0]; int i; /* First, purge file if it already exists */ HPCICOMMAND("PURGE " FILENAME "\r", &cmderror, , 2); assert(!cmderror || cmderror==-383); /* Create new KSAM XL file, output access, 44-byte ASCII records,
assert(ccode()==CCE); unlock_file(); } printf("\n"); } static void dump_file(void) { /* List the file several different ways */ list_sequential_primary(); list_sequential_secondary(6); list_sequential_secondary(35); } static void list_sequential(void) { /* List the file, looping on FREAD until end-of-data */ int save_ccode; record_t buffer; for (;;) { FREAD(filenum, buffer, - sizeof buffer); if ((save_ccode=ccode()) == CCG) break; assert(save_ccode==CCE); printf(" %.5s %.20s %.3s-%.2s-%.4s " "%.4s %.2s/%.
unlock_file(); } static void lock_file(void) { /* Lock the file unconditionally */ FLOCK(filenum, 1); assert(ccode()==CCE); } static void open_file(void) { /* Open file for shared update access with locking */ int status; const int old=1, update=5, lock=1, shr=3; HPFOPEN(&filenum, &status, 2, "-" FILENAME "-", 3, &old, 11, &update, 12, &lock, 13, &shr); assert(!status); } static void unlock_file(void) { /* Unlock the file */ FUNLOCK(filenum); assert(ccode()==CCE); } static void update_records(void) { /* Upd
} static void write_new_records(void) { /* Add some entries to the file */ const record_t test_data[] = { "77777NEWMAN GEORGE 7770066661520871012", "55555GOODMAN BRIAN 5553300008540880815", "66666MANLEY SHAUNA 0003526143360890930" } ; const int test_items = sizeof test_data / sizeof test_data[0]; int i; for (i=0; i
Index A abort recovery, 7-3 access options, 4-1, 4-3 access selections, 4-4 advance ag, 5-1 alternate key, 1-1, 5-3 approximate key match, 5-3 automatic recovery, 1-5 B BASIC/V intrinsics BKCLOSE, B-7 BKDELETE, B-9 BKERROR, B-12 BKLOCK, B-14 BKOPEN, B-16 BKREAD, B-23 BKREADBYKEY, B-27 BKREWRITE, B-30 BKSTART, B-34 BKUNLOCK, B-39 BKWRITE, B-41 BKCLOSE BASIC/V intrinsic, B-7 BKDELETE BASIC/V intrinsic, B-9 BKERROR BASIC/V intrinsic, B-12 BKLOCK BASIC/V intrinsic, B-14 BKOPEN BASIC/V intrinsic, B-16 BKREAD
C Index-2 chronological order, 1-4 CKCLOSE COBOL 68 intrinsic, A-10 CKDELETE COBOL 68 intrinsic, A-11 CKERROR COBOL 68 intrinsic, A-15 CKLOCK COBOL 68 intrinsic, A-16 CKOPEN COBOL 68 intrinsic, A-18 CKOPENSHR COBOL 68 intrinsic, A-23 CKREAD COBOL 68 intrinsic, A-24 CKREADBYKEY COBOL 68 intrinsic, A-27 CKREWRITE COBOL 68 intrinsic, A-31 CKSTART COBOL 68 intrinsic, A-36 CKUNLOCK COBOL 68 intrinsic, A-40 CKWRITE COBOL 68 intrinsic, A-42 CM KSAM, 1-1, 8-1 CM KSAM display, 3-1 COBOL 68 intrinsics CKCLOSE, A-10
D data area, 1-4 data block size specifying, 2-4 DEFBLK option, 2-4 deleting records, 6-3 device class, 2-1 Disk le le label information returned FLABELINFO, 9-40 disk le, remove FRENAME, 9-77 disposition, 4-8 domain, 4-1, 4-3, 4-8, 7-3, 8-2 DUP parameter, 2-3 dynamic locking, 4-1, 4-4, 5-6, 6-2, 6-3, 7-2 E error information, 7-1 F FCHECK intrinsic, 7-1, 9-2 FCLOSE intrinsic, 4-8, 9-4 FCONTROL intrinsic, 7-3, 9-7 FCOPY subsystem, 2-7, 7-3, 8-3 KEY= parameter, 2-7 FERRMSG intrinsic, 7-1, 9-10 FFILEINFO
ag word, 2-9 FLOCK intrinsic, 4-4, 5-6, 6-2, 6-3, 7-2, 9-49 FOPEN intrinsic, 2-1, 2-8, 2-13, 4-1, 4-3, 4-6, 7-3, 9-50 FPOINT intrinsic, 5-5, 5-6, 9-66 FREADBYKEY intrinsic, 5-5 FREADC intrinsic, 5-5, 5-6 FREADDIR intrinsic, 5-5, 5-6, 9-73 FREAD intrinsic, 9-67 FREADLABEL intrinsic, 3-4, 9-75 FREMOVE intrinsic, 6-3 FRENAME Intrinsic, 9-77 Remove disk le, 9-77 FROM= parameter, 2-7 FSPACE intrinsic, 9-80 FUNLOCK intrinsic, 4-4, 5-6, 6-2, 6-3, 7-2, 9-81 FUPDATE intrinsic, 6-2, 9-82 FWRITE intrinsic, 6-2, 9-84 F
K key duplication, 2-2, 2-11 duplication method, 2-3 length, 2-11, 3-4 location, 2-2, 2-11, 3-4 size, 2-2 type, 2-2, 2-11, 3-4 key characteristics, 2-8 key data, 2-1 key eld, 1-1 key index, 1-3 KEY= parameter, 2-2 key parameters, 2-11 key sequence, 1-3 key speci cations, 3-2, 3-4 KSAMUTIL utility, 8-2 KSAM XL, 8-1 data area, 1-4 de nition, 1-1 index area, 1-3 KSAM XL display, 3-1 L language ID, 2-9, 9-58 LISTFILE, 2-4 LISTFILE command, 3-1, 3-2, 8-2 LISTFILE options, 3-1 loading data, 2-7 logical record
Index-6 R random access, 5-5 by key, 5-5 by physical record number, 5-5 by relative record number, 5-5 RDUP parameter, 2-3 record deletion, 6-3 record header, 1-4, 6-3 record-level locking, 8-1 record numbering, 2-1, 2-3, 2-9, 5-3 record protection, 7-1 record retrieval, 5-1 record sequence change, 2-7 record space reuse, 2-1, 2-3, 2-9 record updates, 6-2 record writing, 6-2 recoverability, 8-2 recovered data space, 1-4 recovery, 1-5 relational operator, 5-4 relative record location, 2-7 relative record n
U update access, 6-2 updating records, 6-2 user label, 3-4 utilities KSAMUTIL, 8-2 V variable-length records, 8-3 W writing records, 6-2 Index-7
