Using KSAM XL and KSAM 64 900 Series HP 3000 Computer Systems Manufacturing Part Number: 32650-90886 E0300 U.S.A.
Notice 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 fitness 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.
Contents 1. Introduction Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 KSAM XL File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Automatic Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2. Creating a KSAM File Creating the File With the BUILD Command . .
Contents Writing Directly to Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Recovering from a System or Software Abort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Backing Up KSAM Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 Recovering from Index Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Status Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . KSAM Logical Record Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CKCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CKDELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents 6
Figures Figure 1-1.. General Representation of the KSAM Format . . . . . . . . . . . . . . . . . . . . . . . . 14 Figure 1-2.. A Simplified View of the KSAM File Structure . . . . . . . . . . . . . . . . . . . . . . . . 15 Figure 1-3.. Simple Index Tree Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Figure 2-1.. Creating a KSAM XL file using the OPTMBLK parameter . . . . . . . . . . . . . . 22 Figure 2-2.. Creating a KSAM 64 file using the OPTMBLK parameter . . . .
Figures Figure A-6.. Random Update with COBOL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 Figure B-1.. Closing a KSAM File with BKCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Figure B-2.. Deleting a Record With BKDELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Figure B-3.. Dynamically Locking a KSAM File with BKLOCK . . . . . . . . . . . . . . . . . . . . 239 Figure B-4.. Opening KSAM File with BKOPEN . . . . . . . . . . . .
Tables Table 5-1.. Pointer and Advance Flag Settings for Reading . . . . . . . . . . . . . . . . . . . . . . . . 48 Table 6-1.. Pointer and Advance Flag Settings for Writing . . . . . . . . . . . . . . . . . . . . . . . . 55 Table 9-1.. FCONTROL Itemnum/Item Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Table 9-2.. FFILEINFO Itemnum/Item Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Table 9-3.. FFILEINFO File Codes . . . . . . . . . . . . . .
Tables 10
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).
In This Book This manual provides programmers with descriptions and examples of the KSAM XL and KSAM 64 file formats and their accessing routines. The material is organized into nine chapters and two appendixes. The "Introduction" describes the KSAM XL and KSAM 64 files, their indexing mechanism, and their standard recovery methods. "Creating a KSAM XL or a KSAM 64 File" describes different methods of creating a KSAM XL or a KSAM 64 file.
1 Introduction The Keyed Sequential Access Method (KSAM) is a method of organizing data records according to the content of key fields within the record. This method allows sequential processing of records without relying on the physical location of the record in the file. Every record in a KSAM file contains a primary key field. The content of this field determines the logical sequence of each record. Alternate keys offer different sequences for accessing the same records.
Introduction KSAM XL File Format Figure 1-1.
Introduction KSAM XL File Format 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 file specifications and key specifications established when the file was built. It also contains pointers to the index and data page maps to manage the file'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.
Introduction KSAM XL File Format The index portion of the file 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.
Introduction Automatic Recovery 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 file, such as additions, modifications, or deletions, are immediately available to subsequent accesses by any process. The file system guarantees the order of concurrent data access.
Introduction Automatic Recovery 18 Chapter 1
2 Creating a KSAM File You can create a KSAM file in several different ways: • Using the BUILD command. The file name and file characteristics are specified in the command parameters. The file can then be loaded with data by using the FCOPY subsystem to load existing file data or by directing program output to the file. • Copying an existing file using the FCOPY subsystem. File characteristics can be defaulted to those of the existing file or modified by using a file equation.
Creating a KSAM File Creating the File With the BUILD Command — The length of the key. — 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 to select data block size. KSAM File Characteristics The key characteristics, the method of file numbering, and the reuse option are unique to KSAM files.
Creating a KSAM File Creating the File With the BUILD Command real 1 to 255 bytes of real number data. IEEE real 4, 8, or 16 bytes of IEEE real number data. numeric 1 to 28 bytes of numeric data. packed 1 to 14 bytes of packed decimal data (odd number of characters). *packed 2 to 14 bytes of signed packed decimal data (even number of characters). The duplication key characteristic is an optional field.
Creating a KSAM File Creating the File With the BUILD Command based on the record size of a file. Refer to MPE/iX Commands Reference Manual for more information on using this option. The LISTFILE, 7 command displays the optimal data block size and the 8 bit value of the flagword of the KSAM parameter. Figure 2-1.
Creating a KSAM File Creating the File With the BUILD Command Figure 2-4.
Creating a KSAM File Loading Data to a KSAM XL File Figure 2-6. Building the AR Master KSAM64 File :BUILD ARMSTR64.MGR.AR;REC=-80,,F,ASCII;& DEV=DISC;DISC=100;KSAM64;& 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.
Creating a KSAM File Loading Data to a KSAM64 File subsystem name. It displays a prompt (>) while awaiting input. :FCOPY > The FROM= command identifies the source file containing the data to be copied. The TO= parameter specifies the target file to which the data will be copied. The following example copies the existing master file records contained in OLDMSTR to the newly created KSAM XL file, ARMSTR. >FROM=OLDMSTR.MGR.AR;TO=(ARMSTR.MGR.
Creating a KSAM File Modifying Existing File Specifications While Copying :FCOPY FROM=DATA; TO=(*DATANEW) Modifying Existing File Specifications While Copying A file equation can be used to modify file specifications of an existing file. The FCOPY subsystem can be used to copy data from an existing file into a new file using a back reference to the file equation for the new specifications. The following example copies data from the file DOC to a new KSAM XL file DOC1.
Creating a KSAM File Building a KSAM File Programmatically 14:1 Enter a 1 if record numbering is to start with 1. Enter 0 if record numbering is to start with 0. 13:1 Enter 1 if only sequential writing by primary key is allowed. Enter 0 if random writing by primary key is allowed. 12:1 Enter 1 if deleted record space can be reused. Enter 0 if deleted record space cannot be used. 11:1 Enter 1 if a language type is specified. Enter 0 if a language type is not specified.
Creating a KSAM File Building a KSAM File Programmatically Figure 2-9. KSAM Parameter Format Number of Keys Enter a digit between 1 and 16 in word 16 to specify the number of keys to be defined for this file. Refer to Figure 2-9. for the location of this field. Key Parameters The following parameters are defined 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.
Creating a KSAM File Building a KSAM File Programmatically 1 Byte key (1 to 255 bytes) 2 Short integer key (255 bytes) 3 Integer key (255 bytes) 4 Real number key (255 bytes) 5 Long real number key (255 bytes) 6 Numeric display key (1 to 28 bytes) 7 Packed decimal key, odd number of digits (1 to 14 bytes) 8 Packed decimal key, even number of digits (2 to 14 bytes) 9 IEEE floating-point decimal key (4, 8, or 16 bytes) key length Enter the length of the key in bytes.
Creating a KSAM File Building a KSAM File Programmatically cm : bit1; chg_primary : bit1; kslang : bit1; ksreuse : bit1; seq_random : bit1; rec_numbering : bit1; resrvd2 : bit1); 4 : (resrvd3 : bit8; num_keys : bit8); 5 : (key_type : bit4; key_length : bit12); 6 : (dflag : bit1; maxkeyblk : bit15); 7 : (resrvd5 : bit8; rflag : bit1; resrvd6 : bit7); 8 : (key_location : bit16); end; ksam_struc = ARRAY[0..80] OF ksam_rec; . . . var ksam_param, ksamparam : ksam_struc; keylocation, reserved : bit16; . . .
Creating a KSAM File Using Related Commands parameter values rather than item number pairs to identify file characteristics and the KSAM key value array. Refer to Chapter 4 , “Opening and Closing the File,” for a description of the FOPEN intrinsic. Using Related Commands Several MPE/iX commands can be used for KSAM files. KSAM files can be deleted and renamed using the same commands used with standard files. File attributes can be modified with a file equation.
Creating a KSAM File Using Related Commands 32 Chapter 2
3 Obtaining File Information You can obtain file information about an existing file using the LISTFILE command or the FGETINFO and FGETKEYINFO intrinsics. You can also add specific information about your file by writing it to a user label. The FWRITELABEL and FREADLABEL intrinsics provide access to user labels. Displaying File and Key Information Use the LISTFILE command to display the file specifications used to build the file.
Obtaining File Information Displaying File and Key Information Figure 3-2. File Information Display for a KSAM XL File :LISTFILE ARMSTRXL.MGR.AR,5 *************************** FILE: ARMSTRXL.MGR.
Obtaining File Information Displaying File and Key Information KEY 1 2 3 4 KEY TYPE NUMERIC BYTE NUMERIC BYTE NUM KSAM KEYS: LANGUAGE : PRIMARY KEY : VERSION : KEY LOCATION KEY SIZE 4 10 65 70 6 25 5 3 4 ENGLISH RANDOM 2 DUP\RDUP NONE RDUP RDUP RDUP FIRST KSAM RECORD: REUSE RECORDS : COBOL : COMPUTEBLK SIZE : 1 YES NO OPTMBLK For a KSAM file, the file specifications, as well as the key information specified when the file was built, is displayed.
Obtaining File Information Accessing File Information from a Program Accessing File Information from a Program The FGETINFO intrinsic obtains a file's access and status information based on the parameters identified in the intrinsic call. Embedded parameters that are not desired are indicated by commas. Parameters omitted from the end of the list do not need to be indicated. In the following example, the intrinsic call returns the end of file in the variable named LSTREC.
Obtaining File Information Accessing Key Information From a Program Accessing Key Information From a Program Like the FGETINFO intrinsic, the FGETKEYINFO intrinsic provides access and status information about the keys of a KSAM file. It provides detailed information about the key location, type, and length in a parameter format similar to the FOPEN intrinsic key parameter.
Obtaining File Information Accessing Key Information From a Program 38 Chapter 3
4 Opening and Closing the File Some application programming languages offer commands for opening and closing KSAM files (for example, the ORGANIZATION IS INDEXED clause in COBOL). If not, use the HPFOPEN or FOPEN intrinsic to open the file, and the FCLOSE intrinsic to close the file. See the appropriate application language reference manual for details on how to call intrinsics. Opening an Existing KSAM File The HPFOPEN and FOPEN intrinsics both open KSAM files, as well as other file types.
Opening and Closing the File Opening an Existing KSAM File Figure 4-1. Opening an Existing KSAM File with HPFOPEN procedure open_permanent_KSAM_file; const formal_designator_option domain_option access_type_option dynamic_locking_option exclusive_option ASCII_binary_option type pac160 = = = = = = 2; 3; 11; 12; 13; 53; = packed array [1..
Opening and Closing the File Opening an Existing KSAM File The file_num parameter is used to return a file number to the calling program. This file number is used to identify the file in subsequent intrinsic calls. The status parameter returns a numeric code identifying the success or failure of the file opening process. For clarity, the itemnum parameters in the previous example have been defined as constants. This is not necessary for intrinsic use.
Opening and Closing the File Opening a New File binary 0001 or 1 To write to the file for the first time. binary 0010 or 2 To append records to the file. binary 0100 or 4 To allow both read and write access. binary 0101 or 5 To update records in the file.
Opening and Closing the File Opening a New File Figure 4-2. Opening a New KSAM File with HPFOPEN 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..
Opening and Closing the File Opening a New File file_num status file_name ksam_type write_access rec_len file_len save_perm ascii := 0; := 0; := '%ARMSTRXL.MGR.AR%'; := 3;{creating a KSAM XL file} {to create a KSAM64 file set to 7} := 1; := 80; := 100; := 1; := 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; . . .
Opening and Closing the File Opening a New File Figure 4-3. Opening a New KSAM XL File with FOPEN 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..
Opening and Closing the File Closing a KSAM File Closing a KSAM File The FCLOSE intrinsic terminates access to a file. The disposition and the security code parameters control the file's retention and its authorized users. When closing an existing file, you usually close it with both parameters set to zero. FCLOSE(FILNUM,0,0) You cannot change an existing permanent file to a temporary file using the FCLOSE intrinsic.
5 Reading File Data KSAM files offer multiple record retrieval options using primary and alternate keys, and logical and physical record numbers. The following list identifies the methods of reading KSAM file 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.
Reading File Data Sequential Access by Primary Key access files and identifies those pointers that are set by each. Table 5-1.
Reading File Data Sequential Access by Primary and Alternate Key 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 field. The FFINDN intrinsic identifies the first record by using a logical record number. The FFINDBYKEY intrinsic uses a key value to determine the first record. When the first record has been located, the FREAD intrinsic reads the first record specified by the alternate key.
Reading File Data Sequential Access by Primary and Alternate Key Figure 5-2. FFINDBYKEY Intrinsic Sample fby_keyvalue := '0000'; fby_keylocation := 1; fby_keylength := 4; fby_relop := 1; . . . FFINDBYKEY(filenum,fby_keyvalue,fby_keylocation,fby_keylength,fby_relop); . . .
Reading File Data Sequential Access by Partial Key Value 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 field. The intrinsic parameters (key value, key length, and relational operator) identify the partial value to be matched, the number of characters to be compared in the key field, and whether the record should equal the value or be greater than the value.
Reading File Data Random Access of a Single Record Random Access of a Single Record A record can be accessed randomly by a particular key value or by its relative or physical record number. Using a Key Value The FREADBYKEY intrinsic is recommended for retrieving records randomly. The desired key value and the key location are specified in the intrinsic parameters. The index of the specified key is checked for a matching key value and the appropriate record is read.
Reading File Data Sequential Access in Physical Record Order Sequential Access in Physical Record Order A sequential access in physical record order is really a series of random accesses by physical record number. The FPOINT and FREADC intrinsics are used to read records in order of their physical location in the file. The FPOINT intrinsic sets the physical record pointer to the position specified in its record number parameter.
Reading File Data Shared File Access Shared File Access If only one process is accessing a file, setting a pointer and reading a record in a two-step process does not present a problem. Shared file access, however, presents potential retrieval contention. If a pointer is positioned to retrieve a particular record by one process, another process could modify or delete the record before the original process reads it.
6 Writing and Updating Record Data When records are written to a file for the first 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-file marker if the record is the last in sequence. Updating and deleting records also rely on pointer positioning.
Writing and Updating Record Data Writing New Records Writing New Records The FWRITE intrinsic writes new records to a new or existing file from a buffer in your program. Index entries for primary and alternate keys are entered automatically for each record written. Depending on how the file was created, records may be written in random or sequential order. If the REUSE option is specified, each record is written to the next available space.
Writing and Updating Record Data Deleting a Record Deleting a Record The intrinsic FREMOVE effectively removes the current record from the KSAM file. When executed, the 4-byte record header is modified, 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 file, it is no longer possible to access the record through standard read operations.
Writing and Updating Record Data Shared Access 58 Chapter 6
7 Protecting the File and Its Data Attention must be paid to protecting a KSAM file's data. Check an intrinsic's status after a call to find information about a failed routine. The FCHECK and FERRMSG intrinsics provide error codes and messages after an intrinsic call has failed. Various intrinsics control file access when a file is shared by more than one process. Locking and unlocking the file controls access to a shared file during critical modification operations.
Protecting the File and Its Data Protecting Data When File Access is Shared Protecting Data When File Access is Shared If a KSAM file is shared with another process, you need to ensure that the most current data and key index information is retrieved. Locking files controls other processes from accessing the file while a modification routine is processing. Such a modification routine should include the pointer positioning and reading routines that are associated with the modification routine.
Protecting the File and Its Data Writing Directly to Disk FREADBYKEY FUPDATE FUNLOCK Writing Directly to Disk 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. (If the file is shared, you must lock the file before calling the FCONTROL intrinsic with a control code of 2.) A control code of 6 provides a similar function.
Protecting the File and Its Data Backing Up KSAM Files Backing Up KSAM Files A regularly scheduled backup of all files is always advisable. The STORE/RESTORE facility used for most other files is also appropriate for backing up KSAM files to tape. The following commands provide a backup routine for a KSAM file. FILE T=ARBACK;DEV=TAPE STORE ARMSTR.MGR.AR;*T NOTE Do not use the TRANSPORT option of the STORE command with KSAM files.
Protecting the File and Its Data Recovering from Index Corruption >FROM=OLDMSTR.MGR.AR;TO=(ARMSTR.MGR.AR);KEY=0 >EXIT Figure 7-2. Index Corruption Recovery for a KSAM64 File :BUILD ARMSTR64.MGR.AR;REC=-80,,F,ASCII;DEV=DISC;& DISC=100;KSAM64;KEY=(N,4,6;& B,10,25,RDUP;& N,65,5,RDUP;& B,70,3,RDUP;& FIRSTREC=1;REUSE :FILE ARMSTR64; KSAM64 :FCOPY >FROM=OLDMSTR64.MGR.AR;TO=(*ARMSTR64.MGR.
Protecting the File and Its Data Recovering from Index Corruption 64 Chapter 7
8 Migration and Mixed Mode Processing MPE/iX offers three KSAM file formats: CM KSAM, KSAM XL and KSAM64. CM KSAM is the two-file KSAM structure used on MPE V/E systems. KSAM XL and KSAM64, single-file KSAM structures, are used only on MPE/iX systems. KSAM XL and KSAM64 files offer a more convenient single-file format. Programs running in CM or NM can access any type of KSAM file. Use the FCOPY utility to migrate data and rebuild indexes from one KSAM file format to another.
Migration and Mixed Mode Processing Differences in KSAM File Features Differences in KSAM File Features Unlike CM KSAM files, KSAM XL and KSAM64 data records and indexes are combined in a single file. The file limit of KSAM XL files is substantially larger than CM KSAM files. The physical size of the KSAM file is the same as the MPE/iX native mode flat file. KSAM XL and KSAM64 files allow only fixed-length records. CM KSAM files allow fixed-length or variable-length records.
Migration and Mixed Mode Processing Migrating KSAM Files Migrating KSAM Files The data records from an existing KSAM file on an MPE V/E system can be migrated to an existing KSAM XL or KSAM64 file on an MPE/iX system. Perform the following steps to migrate an existing CM KSAM file with fixed-length records to a new KSAM XL or a KSAM64 file: 1. Store both the CM KSAM key file and data file to tape using the TRANSPORT option (used only if migrating to an MPE V/E system). 2.
Migration and Mixed Mode Processing Migrating KSAM Files the KSAM XL/64 file does not exist, a new file is created. A new file is also created by using the NEW option. If you create the file and copy data to it using one command, however, you are not able to change the key structure. This would not be acceptable when copying variable-length records because the record length and record type parameters must be modified to acceptable values. :FCOPY >FROM=ARMSTR.MGR.AR;TO=(ARMSTR2.MGR.
Migration and Mixed Mode Processing Mixed Mode Operation Mixed Mode Operation Application programs running in CM or NM can access either CM KSAM or KSAM XL/64 files. If you are using an RPG application, do not specify any record locking features. RPG will default to file-level locking. This is especially important for cross-development for multiple environments. In some organizations, cross development is necessary because satellite offices operate different types of systems.
Migration and Mixed Mode Processing Mixed Mode Operation 70 Chapter 8
9 KSAM Intrinsics The following section provides syntax and parameter definitions for the KSAM intrinsics. For details regarding status usage and data types, refer to the MPE/iX Error Message Manual Volumes 1, 2 and 3 and the MPE/iX Intrinsics Reference Manual.
KSAM Intrinsics FCHECK FCHECK Returns specific details about error conditions that occurred when a file system intrinsic returned a condition code indicating an I/O error. FCHECK applies to files on any device. Syntax I16V I16 I16 I32 I16 FCHECK(filenum,fserrorcode,translog,blocknum,numrecs); Parameters filenum 16-bit signed integer by value (optional) Specifies the file number of the file for which error information is to be returned.
KSAM Intrinsics FCHECK Condition Codes CCE Request granted. CCG Not returned. CCL Request denied. The file number passed by filenum is invalid, or a bounds violation occurred while processing this request (fserrorcode=73). Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FCLOSE FCLOSE Terminates access to a file on any device. Syntax I16V I16V I16V FCLOSE(filenum,disposition,securitycode); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file to be closed. disposition 16-bit signed integer by value (required) Passes the disposition of the file, significant only for files on disk and magnetic tape.
KSAM Intrinsics FCLOSE the file is a disk file, the file name is checked.If a file of the same name already exists in the temporary file domain, an error code is returned and the file remains open. 011 Close as a temporary job file (not rewound). This option has the same effect as domain disposition 010, except that tape files are not rewound. 100 Release the file. The file is deleted from the system.
KSAM Intrinsics FCLOSE securitycode 16-bit signed integer by value (required) Returns the type of security initially applied to the file (significant for new permanent files only). The valid options are: Value Meaning 0 Unrestricted access; can be accessed by any user, unless prohibited. 1 Private file creator security; can be accessed only by the creator. Operation Notes FCLOSE deletes buffers and control blocks where the process accessed the file.
KSAM Intrinsics FCONTROL FCONTROL Performs various control operations on a file or on the device where the file resides, including: • Verifying I/O. • Reading the hardware status word for the device where the file resides. • Setting a terminal's timeout interval. • Repositioning a file at its beginning. • Writing an end-of-file marker.
KSAM Intrinsics FCONTROL Table 9-1. FCONTROL Itemnum/Item Values Itemnum Mnemonic 2 I16 Item Description Complete I/O: Ensures that requested I/O has been physically completed. Valid only for buffered files. Posts the block being written (full or not). Item is ignored. A checkpoint record is written. In the event of a system crash, recovery is done to this state of the files.
KSAM Intrinsics FCONTROL Table 9-1. FCONTROL Itemnum/Item Values Itemnum Mnemonic 6 U16 Item Description Write end-of-file: Marks the end-of-file (EOF) on disk. It performs the function of itemnum=2 and writes the file label. This guarantees that the end-of-file is correct and the extent bit map is updated. Item is ignored. 7 U16 Space forward to tape mark: Not used for KSAM XL/64 files.
KSAM Intrinsics FERRMSG FERRMSG Returns a message corresponding to an FCHECK error number and enables error messages to be displayed from a program. Syntax I16 CA I16 FERRMSG(fserrorcode,msgbuffer,msglength); Parameters fserrorcode 16-bit signed integer by reference (required) Passes an error code returned by the FCHECK intrinsic, indicating which message to return in msgbuffer. msgbuffer character array (required) Returns the error message identified with fserrorcode.
KSAM Intrinsics FFILEINFO FFILEINFO Returns information about a file. Syntax I16V I16V * FFILEINFO(filenum[,itemnum,item] [...]); NOTE Up to five itemnum/item pairs can be specified. Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file for which information is requested. itemnum 16-bit signed integer by value (optional) Specifies which item value is to be returned. (Refer to Table 9-2.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type 2 U16 Item Description File options: Returns file characteristics (refer to the FFfoption figure). 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 can not be represented by foptions.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type Item Description 6 U16 Logical device number: Returns the logical device number of the device where the disk file label resides. • If the file is a disk file, the LDEV is the location of the file label. (File data can reside on the same device as the file label.) • If the file is spooled, the LDEV is a virtual device number that does not correspond to the system configuration I/O device list.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type 14 I16 Item Description Block size: Returns the file block size: • If the file is binary, the value is positive and the size is in halfwords. • If the file 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 file types (STD, KSAM, RIO, CIR, MSG).
KSAM Intrinsics FFILEINFO Table 9-2.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type Item Description 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.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type 61 CA Item Description NS 3000/XL remote environment ID name Note: If using NS 3000/XL RFA (remote file access), specify DSDEVICE ldev# when using a DS (point-to-point or X.25) link. A buffer 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.
KSAM Intrinsics FFILEINFO Table 9-2.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type 86 Item Description 32-bit signed integer by reference. File owner identifier: The file owner identifier (UID). Zero is returned as the file 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 file group name. Unused characters are blank filled.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num 90 Item Type Item Description 32-bit unsigned integer by reference. Record type: The following valid record types may be returned: 0 Fixed 1 Variable 2 Undefined 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 file size in bytes.
KSAM Intrinsics FFILEINFO Table 9-2. FFILEINFO Itemnum/Item Values Item num Item Type 94 Item Description 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.
KSAM Intrinsics FFILEINFO Table 9-3.
KSAM Intrinsics FFILEINFO Table 9-3.
KSAM Intrinsics FFILEINFO Table 9-3.
KSAM Intrinsics FFILEINFO Table 9-3.
KSAM Intrinsics FFILEINFO Figure 9-2. Aoption Bit Summary Condition Codes CCE (2) Request granted. CCG (0) Not returned. CCL (1) Request denied. Access or calling sequence error. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FFINDBYKEY FFINDBYKEY Positions the record pointer at the beginning of the first record matching the key value comparison in a KSAM file. Syntax I16V CA I16V I16V I16V FFINDBYKEY(filenum,value,location,length,relop); Parameters filenum 16-bit integer by value (required) Identifies the file number of the file to be positioned. value character array (required) Contains a value that determines which record is read.
KSAM Intrinsics FFINDBYKEY Operation Notes Split stack calls are permitted. The FFINDBYKEY intrinsic does not read the advance flag. It positions both the logical record pointer and the physical pointer to the appropriate record. When the function is complete, it sets the advance flag to FALSE. To locate and read a single record, use the FREADBYKEY intrinsic. Condition Codes CCE Request granted. CCG Request denied. The requested position was beyond the logical end-of-file or beginning-of-file.
KSAM Intrinsics FFINDN FFINDN Positions the logical record pointer to the relative record number according to the key sequence in a KSAM file. Syntax I16V DV I16V FFINDN(filenum,number,location); Parameters filenum 16-bit signed integer (required) Passes the file number of the file to be positioned. number double by value (required) Specifies a record number relative to the first logical record in the file.
KSAM Intrinsics FFINDN Condition Codes CCE Request granted. CCG Request denied. The requested position was beyond the logical end-of-file. CCL Request denied. An error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FGETINFO FGETINFO Returns access and status information about a file. NOTE FGETINFO is provided for compatibility with MPE V/E-based systems only. It is recommended that FFILEINFO be used to access data.
KSAM Intrinsics FGETINFO • If the file was created as an ASCII file, this value is negative and expresses the size in bytes. devtype 16-bit signed integer by reference (optional) Returns the type and subtype of the device being used for a KSAM, RIO, circular, or message file, 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 files, bit (8:8)=00000011 and bit (0:8)=00001000 (indicate a 7933/35 disk drive).
KSAM Intrinsics FGETINFO filelimit 32-bit signed integer by reference (optional) Returns a number representing the last logical record that could exist in the file (the physical limits of the file). If the file does not reside on disk, this value is zero. logcount 32-bit signed integer by reference (optional) Returns the total number of logical records passed to and from the program during the current file access.
KSAM Intrinsics FGETINFO Condition Codes CCE Request granted. CCG Not returned. CCL Request denied. An error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FGETKEYINFO FGETKEYINFO Requests access and status information about a KSAM file. Syntax I16V BA BA FGETKEYINFO(filenum,param,control) Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file about which information is requested. param byte array (required) Returns information describing the key information for a KSAM file. The length is 162 bytes. control byte array (required) Passes 256 bytes of control information about the key file.
KSAM Intrinsics FGETKEYINFO Figure 9-3. FGETKEYINFO Parameter Format The control parameter provides dynamic information about the use of the file from the time it was created. It counts the number of times the file 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.
KSAM Intrinsics FGETKEYINFO Figure 9-4.
KSAM Intrinsics FGETKEYINFO Table 9-4.
KSAM Intrinsics FGETKEYINFO Table 9-4.
KSAM Intrinsics FGETKEYINFO pertaining to KSAM files.
KSAM Intrinsics FLABELINFO FLABELINFO Returns information from the file label of a disk file. Syntax CA I16V I16 FLABELINFO(formaldesig,mode,fserrorcode, I16A REC I16A itemnum,item,itemerror); Parameters formaldesig character array (required) Passes the name of the file using either MPE syntax (the default) or HFS syntax. The file name must be terminated by a nonalphanumeric character other than a period (.), a slash (/), a hyphen (-), and an underscore (_).
KSAM Intrinsics FLABELINFO Bits Value/Meaning 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 field. 15:2 File Equations 0 Use file equations if they exist. 1 A file equation must be used. 2 Do not use a file equation.
KSAM Intrinsics FLABELINFO itemerror 16-bit signed integer array (required) Returns an error number corresponding to the items specified 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.
KSAM Intrinsics FLABELINFO Table 9-5. FLABELINFO Itemnum/Item Values Itemnum Mnemonic 7 U16 Item Description Last access date: The date in CALENDAR intrinsic format. May not be up-to-date when the file is open. Zero is returned as the last access date for root directories, MPE accounts, and MPE groups created prior to release 4.5. 8 U16 Last modification date: The date in CALENDAR intrinsic format. May not be up-to-date when the file is open.
KSAM Intrinsics FLABELINFO Table 9-5. FLABELINFO Itemnum/Item Values Itemnum Mnemonic 20 U32 Item Description File allocation time: The time when file was last restored (in CLOCK intrinsic format). Zero is returned as the file allocation time for root directories, MPE accounts, and MPE groups created prior to release 4.5. 21 U16 File allocation date: The date when the file was last restored (in CALENDAR intrinsic format).
KSAM Intrinsics FLABELINFO Table 9-5. FLABELINFO Itemnum/Item Values Itemnum Mnemonic Item Description 37 U16 Logical device number 38 REC Terminated HFS-syntax system absolute pathname: Upon input, the first four bytes are interpreted as a 32-bit unsigned integer specifying the maximum available buffer size in bytes. This maximum available buffer size does not include the four bytes used to represent this size.
KSAM Intrinsics FLABELINFO Table 9-5. FLABELINFO Itemnum/Item Values Itemnum Mnemonic Item Description 46 I32 File group identifier: The file group identifier (GID). Zero is returned as the group ID for root directories where GIDs have not been explicitly assigned.
KSAM Intrinsics FLABELINFO Table 9-5. FLABELINFO Itemnum/Item Values Itemnum Mnemonic 52 I32 Item Description MPE/iX Device Type: This item returns the following values for the following types of devices: 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 53 I32 Secure/Release: This item returns a value indicating whether the file is currently secured or released. A value of 1 indicates that the file is secured.
KSAM Intrinsics FLOCK FLOCK Dynamically locks a file. A call to FLOCK is required before any attempt is made to read or modify a file with shared access. NOTE The file system does not guarantee exclusive access, even when FLOCK and FUNLOCK are used, unless all programs that access the file cooperate by using locking. A program that opens the file with dynamic locking enabled will still be allowed to modify the file, even if it never calls FLOCK.
KSAM Intrinsics FOPEN FOPEN Opens a file. Syntax I16 CA U16V U16V I16V CA filenum:=FOPEN(formaldesig,foption,aoption,recsize,device, CA I16V formmsg,userlabels I32V I16V I16V I16V filesize,numextent,initialloc,filecode); Functional Return filenum 16-bit signed integer (assigned functional return) Returns a unique file number identifying the opened file. Parameters formaldesig character array (optional) Passes a formal file designator, following file naming conventions.
KSAM Intrinsics FOPEN NOTE For existing files, default conditions are specified in the file label. Device characteristics may override some foptions. Bits Value/Meaning 14:2 Domain Indicates which file domain is searched to locate a file. A nameless disk file must always be a new file. A device file (such as a tape or terminal) always resides in the system file domain (permanent file directory). Always specify a device file as old or permanent. The following bit settings are valid: 00 The file is new.
KSAM Intrinsics FOPEN allowed for KSAM files. 8:2 Record format Bit settings indicate internal record structure for a file. This option is applicable only at file creation. KSAM XL/64 support fixed-length records only (00). The file contains logical records of uniform length. 7:1 Carriage control No carriage-control directive is expected for KSAM files. 5:1 Disallow file equation option Indicates whether or not to allow file equations.
KSAM Intrinsics FOPEN Allows write access only, provided that the file's security provisions allow write access. Any data written in the file prior to the current FOPEN request is deleted. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. The EOF is set to 0. 0010 Allows write-save access only, if the file's security provisions allow write access. Previous data in the file is not deleted.
KSAM Intrinsics FOPEN files. 0111 Allows execute/read access only, if the file's security provisions allow execute access. This access allows only read access to any loaded file. The program must be running in PM to specify execute/read access. This access is changed to execute (only) access for KSAM, CIR, and RIO files. This option is not valid for message files. Default: 0000 10:1 Dynamic locking Enables/disables file locking for the file.
KSAM Intrinsics FOPEN 01 Exclusive access. After the file is opened, any additional HPFOPEN/FOPEN requests for this file are prohibited until this process issues the FCLOSE request or terminates. If any process is already accessing this file when an HPFOPEN/FOPEN call is issued with exclusive access specified, an error status is returned. If another HPFOPEN/FOPEN call is issued for this file while exclusive access is in effect, an error code is returned to the process that issued the call.
KSAM Intrinsics FOPEN Default: 0 0:3 recsize Reserved for MPE/iX. 16-bit signed integer by value (optional) Passes the size, in halfwords or bytes, of the logical records in the file. Positive values are halfwords, negative values are bytes. The valid range is dependent on storage and record formats: • For fixed-length and undefined-length ASCII files, the valid range is 1 to 32,767 bytes.
KSAM Intrinsics FOPEN 12:1 Enter 1 if deleted record space can be reused. Enter 0 if deleted record space cannot be used. 11:1 Enter 1 if a language type is specified. Enter 0 if a language type is not specified. 10:1 Enter 1 if the primary key cannot be changed with the FUPDATE intrinsic for files that are opened for sequential processing. Enter 0 if the primary key can be changed with the FUPDATE intrinsic for files that are opened for sequential processing.
KSAM Intrinsics FOPEN 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 specified. Key Location Enter the relative location in bytes of the key field in the record. Note that the first byte of the record is considered 1. Duplicate Key Flag Bits 0:1 specify the duplicate key flag. Enter 1 if duplicate key values are allowed for this key. Enter 0 if duplicate key values are not allowed for this key.
KSAM Intrinsics FOPEN Default: 0 filecode 16-bit signed integer by value (optional) Passes a value that can be used as a file code to identify the type of file. This code is recorded in the file label and is accessible through the FFILEINFO intrinsic. Applicable only at file creation (except when opening an old file that has a negative file code).
KSAM Intrinsics FOPEN Table 9-6.
KSAM Intrinsics FOPEN Figure 9-6. FOPEN KSAM Parameter Format A file can be referenced by its formal file designator. When executed, a unique file number is returned to the process. This file number, rather than the formal file designator, is used in subsequent calls to this file.
KSAM Intrinsics FOPEN Condition Codes CCE Request granted. The file is open. CCG Not returned. CCL Request denied. For example, another process already has exclusive or semi-exclusive access for this file, the privilege level of this file is not user (3), or an initial allocation of disk space cannot be made due to lack of disk space. If the file is not opened successfully, the file number value returned by FOPEN is 0. Call the FCHECK intrinsic for more details.
KSAM Intrinsics FPOINT FPOINT Sets the logical and physical record pointers to the specified record. Syntax I16V I32V FPOINT(filenum,lrecnum); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file where the pointer is to be set. lrecnum 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 file was created.
KSAM Intrinsics FREAD FREAD Reads a logical record in key sequence from a file to the buffer. Syntax I16 I16V UDS I16V lgth:=FREAD(filenum,buffer,length); Functional Return lgth 16-bit signed integer (assigned functional return) Returns the length of the data transferred to buffer: • If a negative value is passed in the length parameter,the lgth is a positive value indicating the number of bytes transferred.
KSAM Intrinsics FREAD Condition Codes CCE Request granted. The information was read. CCG Request denied. The logical end-of-data was encountered during reading. CCL Request denied. The information was not read because an error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FREADBYKEY FREADBYKEY Reads a logical record based on key value from a KSAM file to the target. Syntax I16 I16V LA I16V CA lgth:=FREADBYKEY(filenum,buffer,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 identified, but the data is not returned.
KSAM Intrinsics FREADBYKEY Operation Notes This intrinsic does not read the advance flag. It positions the logical record pointer and the physical pointer to the appropriate record. When its function is complete, it sets the advance flag to FALSE. Condition Codes CCE Request granted. CCG Request denied. The logical end-of-data or beginning-of-data was encountered during the read. CCL Request denied. An error occurred. Either an I/O error occurred or the key could not be located.
KSAM Intrinsics FREADC FREADC Reads a logical record in physical sequence from a KSAM file to the target. Syntax I16 I16V LAI 16V lgth:=FREADC(filenum,buffer,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 identified, but the data is not returned.
KSAM Intrinsics FREADC Condition Codes CCE Request granted. CCG Request denied. The logical end-of-data was encountered during the read. CCL Request denied. An error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FREADDIR FREADDIR Reads a logical record located by its physical record number from a file to the buffer. Syntax I16V UDS I16V I32V FREADDIR(filenum,buffer,length,lrecnum); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file to be read. buffer user-defined structure (required) Returns the record that was read. This structure should be large enough to hold all of the information to be transferred.
KSAM Intrinsics FREADDIR Condition Codes CCE Request granted. The information was read. CCG Request denied. End-of-data was encountered. CCL Request denied. The information was not read; an error occurred. Refer to this intrinsic in the MPE/iX Intrinsics Reference Manual for other codes pertaining to KSAM files.
KSAM Intrinsics FREADLABEL FREADLABEL Reads a user-defined file label. Syntax I16V UDS I16V I16V FREADLABEL(filenum,buffer,length,labelid); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file whose label is to be read. buffer user-defined structure (required) Returns the label that was read. This structure must be large enough to hold the number of halfwords specified by length.
KSAM Intrinsics FREMOVE FREMOVE Marks the current record in a KSAM file for deletion. Syntax I16V FREMOVE(filenum) Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file where the record is to be deleted. Operation Notes Split stack calls are permitted. When executed, the first bit in the record header is set to 1. This intrinsic does not read the advance flag. It sets the logical record pointer and the physical physical pointer to the appropriate record.
KSAM Intrinsics FRENAME FRENAME Renames an open disk file (and its lockword, if applicable). The file being renamed must be either: • A new file. • An old file (permanent or temporary), opened for exclusive access with the exclusive option of the HPFOPEN/FOPEN intrinsics, and with security provisions allowing write access. Syntax I16V CA FRENAME(filenum,formaldesig); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file to be renamed.
KSAM Intrinsics FRENAME file that was created, specify any account that shares the same volume set as the file being renamed. A permanent file cannot be renamed across account boundaries. If other than the current account name is specified for a permanent file, the CCL (1) error condition is returned and the file retains its old name. Operation Notes The formaldesig parameter uses MPE-escaped semantics.
KSAM Intrinsics FSPACE FSPACE Moves a record pointer forward or backward in a file. Syntax I16V I16V FSPACE(filenum,displacement); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file on which spacing is to be done. displacement 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.
KSAM Intrinsics FUNLOCK FUNLOCK Dynamically unlocks a file. Syntax I16V FUNLOCK(filenum); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file whose global RIN is to be unlocked. Condition Codes CCE Request granted. CCG Request denied. The file had not been locked by the calling process. CCL Request denied. The file was not opened with the dynamic locking aoption of the FOPEN/HPFOPEN intrinsic, or the filenum parameter is invalid.
KSAM Intrinsics FUPDATE FUPDATE Updates the contents of a logical record in a file. Syntax I16V UDS I16V FUPDATE(filenum,buffer,length); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file to be updated. buffer user-defined structure (required) Passes the record to be written in the update. length 16-bit signed integer by value (required) Passes the number of halfwords or bytes to be written to the file.
KSAM Intrinsics FUPDATE Condition Codes CCE Request granted. CCG Request denied. An end-of-file condition was encountered during updating. CCL 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 for other codes pertaining to KSAM files.
KSAM Intrinsics FWRITE FWRITE Writes a logical record from the buffer to a file. Syntax I16V UDS I16V U16V FWRITE(filenum,buffer,length,controlcode); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file to be written on. buffer user-defined structure (required) Passes the record to be written. length 16-bit signed integer by value (required) Passes the number of halfwords or bytes to be written to the record.
KSAM Intrinsics FWRITE Condition Codes CCE Request granted. CCG Request denied. The physical bounds of the file prevented further writing. CCL 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 specified in the flag word of the ksamparam in FOPEN and the primary key is not in ascending order.
KSAM Intrinsics FWRITELABEL FWRITELABEL Writes a user-defined file label. Syntax I16V UDS I16V I16V FWRITELABEL(filenum,buffer,length,labelid); Parameters filenum 16-bit signed integer by value (required) Passes the file number of the file to be labeled. buffer user-defined structure (required) Passes the label to be written. If the file is a labeled magnetic tape file, this label must be 40 halfwords in length.
KSAM Intrinsics HPFOPEN HPFOPEN Establishes access to a file and creates a file. Syntax I32 I32 I32V * HPFOPEN(filenum,status[,itemnum,item] [...]); NOTE Up to 41 itemnum/item pairs can be specified. Parameters filenum 32-bit signed integer by reference (required) Returns a file number used to identify the opened file in subsequent intrinsic calls.
KSAM Intrinsics HPFOPEN NOTE An itemnum takes precedence over any previously specified duplicate itemnum. Any duplicated itemnum is flagged as a warning. Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 0 2 Item Description 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. CA Formal designator: Passes a formal file designator, following MPE/iX file naming conventions.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic Item Description 2 Cont. CA Default: A nameless file is assigned that can be read from or written to, but not saved. (The domain of a nameless file must be new.) Only one of the following options can be in effect when a file is opened: itemnum=2 itemnum=51 3 I32 Domain: Passes a value indicating which file domain MPE/iX searches to locate the file. A nameless disk file must always be a new file.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic Item Description 5 Cont I32 Default: 0 For example, passing &MYFILE& in itemnum=2 and using itemnum=5 and item=4 to equate it with $STDIN is equivalent to the file equation FILE MYFILE=$STDIN. This option is not equated with itemnum=2 if both of the following conditions are true: The itemnum=9 option allows file equations for the file opening.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 10 I32 Item Description File type: Passes a value indicating the internal record structure used to access records in the file. If the file is old, this option is ignored. Specifying an itemnum=5 value other than zero overrides this option. This option is applicable only at file creation.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 11 Cont I32 158 Item Description Access type: 3 Append access only, if the file's security provisions allow either append or write access. FFINDBYKEY, FFINDN, FPOINT, FREAD, FREADBYKEY, FREADC, FREADDIR, FREMOVE, FSPACE, and FUPDATE intrinsic calls cannot reference this file. The record pointer is set to EOF prior to each FWRITE. For disk files, the EOF is updated after each FWRITE call.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 12 I32 Item Description Dynamic locking: Passes a value enabling or disabling file locking for the file. When specified, the FLOCK and FUNLOCK intrinsics can be used to dynamically permit or restrict concurrent access to a disk file by other processes at specified times.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 13 I32 Item Description Exclusive: Passes a value indicating continuous exclusive access to the file, from open to close. Use this option when performing a critical operation (for example, updating the file). The following values are valid: 160 0 If itemnum=11 specifies read only access, read-share access takes effect. Otherwise, exclusive access takes effect.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 13 Cont I32 Item Description 2 Read-share access (semi-exclusive access). After the file is opened, concurrent write access to this file through another HPFOPEN/FOPEN request is prohibited, whether issued by this process or another process, until this process issues the FCLOSE request or terminates. A subsequent request for the read/write or update itemnum=11 obtains read access.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 18 @32 Item Description Short-mapped: Returns a short pointer to the beginning of the data area of the file. This option maps the file into short pointer space. A short-mapped file can be 4-megabytes in length. The calling process can have up to 6-megabytes of short mapped files open at a time. Use the pointer as a large array of any type to efficiently access the file.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 20 CA Item Description Device name: Passes the logical device number, in ASCII form, of a specific device. The file is assumed to be permanent. If the device name option is specified, the nonshareable device should be ready prior to the HPFOPEN call (otherwise, an error results).
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 22 CA Item Description Volume class: Passes a character array representing a volume class name where the file space is to be restricted. This option is applicable only at file 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 file resides).
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 23 CA Item Description Volume name: Passes a character array representing a volume name that restricts the file specified to a specific volume. The volume must reside within the volume set of the group where the file resides. This option is applicable only at file creation.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 29 I32 Item Description Privileged access: Passes a value that temporarily restricts access to the file number returned from HPFOPEN to a calling process whose execution level is equal to or less than the value specified in this option. This restriction lasts until the file associated with the restricted file number is closed. Do not specify a value less than the execution level of the calling process.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 36 I32 Item Description Initial allocation: Passes a positive integer value indicating the number of extents to be allocated to the file initially. This option is applicable only at file creation. Default: 0 37 I32 Filecode: Passes a value that can be used as a file code to identify the type of file. This code is recorded in the file label and is accessible through the FFILEINFO intrinsic.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 42 CA Item Description Device class: Passes a device class where the file will reside. The file system uses the device class name to select a nonshareable device from a configured 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 specified, the file is allocated to any available device in that class.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 45 CA Item Description Fill character: Passes two ASCII characters that determine what padding character to use at the end of blocks or unused pages, and the padding used by itemnum=53. Do not use delimiter characters for this option. The fill character must be a 2-byte array. The first character only is used as the padding character. The second character is reserved for future use.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 50 Cont I32 Item Description Final disposition: 2 Temporary job file (rewound). The file is retained in your temporary (job or session) file domain and can be requested by any process within your job or session. If the file is a disk file, the uniqueness of the file name is checked. Should a file of the same name already exist in the temporary file domain, an error code is returned at close time and the file remains open.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 52 CA Item Description File equation string: Passes a character string that matches the MPE/iX file equation specification syntax exactly. This option allows the specification of options available in the FILE command. The formaldesig parameter and filereference parameter can contain embedded command interpreter variables and expressions.
KSAM Intrinsics HPFOPEN Table 9-7. HPFOPEN Itemnum/Item Values Itemnum Mnemonic 56 I32 Item Description Object class: Passes a user object class number, in the range 0 to 10, that is associated with the file. Default: Determined by the file code for system and subsystem files, and by the file type and record type for normal user files. 57 Reserved for MPE/iX. 58 Reserved for MPE/iX. 59 Reserved for MPE/iX. 60 Reserved for MPE/iX. 61 Reserved for MPE/iX. 64 ACD. Table 9-8.
KSAM Intrinsics HPFOPEN Table 9-8.
KSAM Intrinsics HPFOPEN Operation Notes Enables creation of a new file on a shareable device and defines the physical characteristics of that file prior to access. Enables access to existing files. Returns a file number to the calling process that uniquely identifies the file. Use the file number to reference the file in calls to other intrinsics. The format of the KSAM parameter is shown in Figure 9-7. Figure 9-7.
A COBOL Intrinsics COBOL compilers (COBOL 68 and earlier) required special intrinsics to access keyed files. The following intrinsics are provided only for the maintenance of COBOL 68 or earlier COBOL programs using KSAM structures. NOTE Do not use these intrinsics for new programming. Current COBOL file access modules provide KSAM file access. Calling a KSAM Procedure KSAM files are accessed from COBOL programs through calls to a set of procedures.
COBOL Intrinsics Filetable Parameter that further define operations to be performed on the file. The first two parameters, filetable and status, are included in every KSAM procedure call except CKERROR; other parameters may be specified 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.
COBOL Intrinsics Filetable Parameter procedure after the file named in halfwords 2-5 has been successfully opened. After the file is closed by CKCLOSE, filenumber is reset to 0. (This number should be set to zero when the file table is initially defined.) It must be defined as a COMPUTATIONAL item. filename The name of the KSAM file.
COBOL Intrinsics Status Parameter COMPUTATIONAL item. A code in the left byte of halfword 8 of the file table that indicates whether a CKLOCK or CKUNLOCK has been performed successfully since the operation specified in previous operation: lock/unlock 10 CKLOCK successful 11 CKUNLOCK successful A sample file table definition might be: WORKING-STORAGE SECTION. FILE_TABLE. 01 KSAM_FILE.
COBOL Intrinsics Status Parameter The current input/output operation was completed successfully; no duplicate keys were read or written. 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.
COBOL Intrinsics Status Parameter 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 first character of status = 0, the call was not successful. For example, a sample status parameter definition might be: WORKING-STORAGE SECTION. . . . 01 STAT. 02 STATUS-KEY-1 PIC X. 02 STATUS-KEY-2 PIC X.
COBOL Intrinsics KSAM Logical Record Pointer KSAM Logical Record Pointer Many of the KSAM procedures use a logical record pointer to indicate the current record in the file. This pointer points to a key value in the index area that identifies the current record in the data area. The particular key used, if the file has more than one key, is the key specified in the current procedure or the last procedure that referenced a key.
COBOL Intrinsics KSAM Logical Record Pointer Sample KSAM File The file KSAMFILE illustrated in Figure A-2. is used in all subsequent examples associated with the COBOL procedure calls. Figure A-2.
COBOL Intrinsics KSAM Logical Record Pointer A File Description in Working Storage for Figure A-2 appears below. File Description in Working Storage (Figure A-2). WORKING-STORAGE SECTION 77 RECSIZEPIC S9(4)COMP VALUE 74. 77 RESULTPIC 9(4)VALUE 0. 01 REC. 03 FILLERPIC XXVALUE SPACES. 03 NAMEPIC X(20). 03 PHONEPIC X(8). 03 OTHERDATAPIC X(44). 01 DAT. 03 NAMEPIC X(20). 03 PHONEPIC X(8). 03 OTHERDATAPIC X(44). 01 FILETABLE. 03 FILETABLEPIC S9(4)COMP VALUE 0. 03 FILENAMEPIC X(8)VALUE "KSAMFILE".
COBOL Intrinsics CKCLOSE CKCLOSE A call to CKCLOSE terminates file processing for the specified KSAM file. CALL "CKCLOSE" USING filetable, status When processing is completed, a KSAM file should be closed with a call to CKCLOSE. No further processing is allowed on the file until a CKOPEN procedure call opens the file. CKCLOSE can be executed only for a file that is open.
COBOL Intrinsics CKDELETE CKDELETE This procedure logically deletes a record from a KSAM file. CALL "CKDELETE" USING filetable, status In order to logically delete records from a KSAM file, you can use the procedure CKDELETE. If reuse is not specified, then a logically deleted record is marked for deletion, but is not physically removed from the file. The deletion mark makes such a record inaccessible but does not physically reduce the size of the file.
COBOL Intrinsics CKDELETE 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. The WORKING-STORAGE SECTION from Figure A-2. and the FINISH procedure from the CKCLOSE example are assumed for these examples.
COBOL Intrinsics CKDELETE READ-REC. CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. IF STATUS-KEY-1 = "1" THEN DISPLAY "END OF FILE REACHED" GO TO FINISH. IF STATUS-KEY-1 = "0" THEN IF NAME OF REC NOT LESS THAN "Q "THEN DISPLAY "DELETIONS COMPLETED" GO TO FINISH; ELSE GO TO DELETE-REC; ELSE DISPLAY "CKREAD ERROR, STATUS =", STAT IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKERROR NO.", RESULT. GO TO READ-REC. DELETE-REC. CALL "CKDELETE" USING FILETABLE, STAT.
COBOL Intrinsics CKDELETE In the second example, a file containing the primary keys of those records to be deleted from a KSAM file 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.
COBOL Intrinsics CKERROR CKERROR Converts KSAM file system error code returned in status to a display format number. 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 file 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.
COBOL Intrinsics CKLOCK CKLOCK A call to CKLOCK dynamically locks a KSAM file. CALL "CKLOCK" USING filetable, status, lockcond When access is shared, you must lock the file before calling CKWRITE, CKREWRITE, or CKDELETE. This ensures that another user cannot attempt to modify the file at the same time. It guarantees that the most recent data is available to each user who accesses the file. In order to call CKLOCK, the file must have been opened with a call to CKOPENSHR, not CKOPEN.
COBOL Intrinsics CKLOCK lockcond is set to 1, your process suspends until the other user unlocks the file or logs off. The following example opens file KSAMFILE for shared access with dynamic locking allowed. It then locks the file unconditionally. If another user has locked the file, the process suspends until the file is unlocked and then continues by locking your file. The status value is checked as soon as control returns to your process to ensure that the file has been locked before continuing.
COBOL Intrinsics CKOPEN CKOPEN A call to procedure CKOPEN initiates KSAM file processing. CALL "CKOPEN" USING filetable, status In order to process a KSAM file, it must be opened with a call to the CKOPEN procedure. CKOPEN initiates processing, specifies the type of processing and the access mode; the file must have been created previously.
COBOL Intrinsics CKOPEN pointer to the first record in the primary key chain. Figure A-3. Procedures Allowed for Input/Output Type/Access Mode Combinations Halfword 6 of filetable must be set to one of the following values before calling CKOPEN: 0 input only 1 output only 2 input/output In general, if you want to allow records to be read or the file to be positioned without allowing any new records to be written or any existing records to be changed, you should set the input/output type to 0.
COBOL Intrinsics CKOPEN 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. With this type of input/output, existing records are not cleared when you write a record with CKWRITE.
COBOL Intrinsics CKOPEN WORKING-STORAGE SECTION. 77 RESULT PIC 9(4) VALUE ZERO. 01 FILETABLE. 03 FILENUMBER PIC S9(4) COMP VALUE ZERO. 03 FILENAME PIC X(8) VALUE "KSAMFILE". 03 I-O-TYPE PIC S9(4) COMP VALUE ZERO.<--- input only 03 A-MODE PIC S9(4) COMP VALUE ZERO.<----- sequential access 03 PREV-OP PIC S9(4) COMP VALUE ZERO. 01 STAT. 03 STATUS-KEY-1 PIC X. 03 STATUS-KEY-2 PIC X. . . . PROCEDURE DIVISION. START. CALL "CKOPEN" USING FILETABLE, STAT. IF STATUS-KEY-1 ="0" THEN GO TO S-READ.
COBOL Intrinsics CKOPENSHR CKOPENSHR A call to CKOPENSHR initiates KSAM file processing with dynamic locking and shared access allowed. CALL "CKOPENSHR" USING filetable, status In order to process a KSAM file with shared access and dynamic locking, the file must be opened with a call to CKOPENSHR. CKOPENSHR is exactly like CKOPEN in that it initiates processing, specifies the type of processing, and specifies the access mode. The file must have been created previously.
COBOL Intrinsics CKREAD CKREAD A call to procedure CKREAD makes available the next logical record from a KSAM file. CALL "CKREAD" USING filetable, status, record, recordsize In order to read records in sequential order by key value, call procedure CKREAD. The file must have been opened in input or input/output mode with access mode specified as either sequential or dynamic.
COBOL Intrinsics CKREAD can be made incorrect by other users without your program being aware of it. For this reason, you should lock the file, position the pointer with a pointer-independent procedure, and then call CKREAD. When the last record is read, you should then unlock the file so other users can access the file. Example 2 below illustrates how you should read the file sequentially when access is shared. Using the WORKING-STORAGE SECTION from Figure A-2.
COBOL Intrinsics CKREAD 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 file for shared 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.
COBOL Intrinsics CKREADBYKEY CKREADBYKEY A call to CKREADBYKEY makes available a record identified by key value from a KSAM file. CALL "CKREADBYKEY" USING filetable, status, record, key, keyloc, recordsize Records can be read from a KSAM file 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.
COBOL Intrinsics CKREADBYKEY 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. (Note that in this as in the preceding examples, the WORKING-STORAGE SECTION from Figure A-2. continues to be useful.
COBOL Intrinsics CKREADBYKEY To find a record by the value of an alternate key, simply change two statements in the preceding example so that KEYLOC contains the location of the alternate key and the key value for comparison is found in item PHONE OF DAT rather than in NAME OF DAT: FIND RECORD. READ NEW-DATA INTO DAT; AT END GO TO FINISH. MOVE 23 TO KEYLOC. CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, PHONE OF DAT, KEYLOC, RECSIZE.
COBOL Intrinsics CKREWRITE CKREWRITE The procedure CKREWRITE replaces a record existing in a KSAM file with another record having a matching primary key. CALL "CKREWRITE" USING filetable, status, record, recordsize You can replace an existing record in a KSAM file with the procedure CKREWRITE. This procedure replaces a record previously read from the file with another record whose primary key matches the primary key of the record being replaced.
COBOL Intrinsics 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.
COBOL Intrinsics CKREWRITE Regardless of mode, an invalid key condition occurs if an alternate key value in the record to be written duplicates a corresponding alternate key for which duplicates are prohibited. When rewriting a record, try to avoid specifying an alternate key value that may duplicate a value existing in the file unless duplicates are allowed for the key. A duplicate key condition where duplicates are not allowed causes status to be set to 22 and the procedure is not executed.
COBOL Intrinsics CKREWRITE IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKERROR NO.", RESULT GO TO FINISH. READ-RECORD. CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. IF STATUS-KEY-1 = "1" THEN GO TO FINISH. <------------------ end of file IF STATUS-KEY-1 = "0" THEN GO TO WRITE-RECORD ELSE DISPLAY "CKREAD ERROR,STATUS =", STAT. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKERROR NO. ", RESULT GO TO READ-RECORD. WRITE-RECORD.
COBOL Intrinsics CKREWRITE DISPLAY "CKREWRITE ERROR, STATUS =", STAT. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "CKERROR NO.=", RESULT. GO TO FINISH.
COBOL Intrinsics CKSTART CKSTART A call to procedure CKSTART allows you to position the record pointer to a particular record in a KSAM file defined by its primary or alternate key value. CALL "CKSTART" USING filetable, status, relop, key, keyloc, keylength In order to position the current record pointer to a location in the file defined by a key value, call CKSTART.
COBOL Intrinsics CKSTART if so, the comparison proceeds as if the file key were truncated on the right to the same length as key length. If no record can be found whose key value satisfies the comparison, an invalid key condition is returned to status; that is, status is set to 23. If you use CKSTART to position the pointer before reading or updating the file sequentially in a shared environment, you must lock the file with a call to CKLOCK before calling CKSTART.
COBOL Intrinsics CKSTART IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STAT, RESULT DISPLAY "ERROR NUMBER", RESULT. GO TO READ-BY-PHONE. In the next example, CKSTART is used to position to the beginning of the series of names beginning with the letter "T". The KSAM file 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.
COBOL Intrinsics CKUNLOCK CKUNLOCK A call to CKUNLOCK unlocks a KSAM file dynamically locked by CKLOCK. CALL "CKUNLOCK" USING filetable, status A file locked by CKLOCK is released for use by other users with a call to CKUNLOCK. (If you log off from any connection with the system, the file is also unlocked.) Since dynamic locking takes place during shared access to the same file by more than one user, it is important that any file locked by CKLOCK be unlocked as soon as possible by CKUNLOCK.
COBOL Intrinsics CKUNLOCK DATA DIVISION. . . . 77 RESULT 01 STATUSKEY. 02 STATUS-KEY1 02 STATUS-KEY2 01 FILETABLE. 02 FILENUMBER 02 FILENAME 02 I-O-TYPE 02 A-MODE 02 PREV-OP PICTURE 9(4) VALUE 0. PICTURE X PICTURE X VALUE " ". VALUE " ". PICTURE PICTURE PICTURE PICTURE PICTURE S9(4) X(8) S9(4) S9(4) S9(4) COMP COMP COMP COMP VALUE VALUE VALUE VALUE VALUE 0. "KSAMFILE". 0. 0. 0. PROCEDURE DIVISION. . . . CALL "CKUNLOCK" USING FILETABLE, STATUSKEY.
COBOL Intrinsics CKWRITE CKWRITE Procedure CKWRITE copies a logical record from the program's data area to an output or an input/output KSAM file. CALL "CKWRITE" USING filetable, status, record, recordsize A call to procedure CKWRITE may be used to write records to a KSAM file either in sequential order or randomly by key value. The file must have been opened for output or for input/output, but not for input only.
COBOL Intrinsics CKWRITE If the file was opened for shared access with CKOPENSHR, then you must lock the file with a call to CKLOCK before writing any records. After the records are written, you should unlock the file with a call to CKUNLOCK.
COBOL Intrinsics CKWRITE . PROCEDURE DIVISION. START. . . . 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.
COBOL Intrinsics CKWRITE The second example, using the same DATA DIVISION and the same FINISH procedure, writes one record to the file 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.
COBOL Intrinsics Examples of KSAM File Access Examples of KSAM File Access The following three examples illustrate KSAM file access from a COBOL program. The file 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.
COBOL Intrinsics Examples of KSAM File Access 002500 002600 002700 002800 002900 003000 003100 003200 003300 003400 003500 003600 003700 003800 003900 004000 004100 004200 004300 004400 004500 004600 004700 004800 004900 005000 005100 005200 005300 005400 005500 005600 005700 005800 005900 006000 006100 006200 006300 006400 006500 006600 006700 006800 006900 007000 220 01 01 01 DATA-REC. 05 FILLER 05 REAL-DATA FILETABLE. 02 FILENUMBER 02 FILENAME 02 I-O-TYPE 02 A-MODE 02 PREV-OP STATUSKEY.
COBOL Intrinsics Examples of KSAM File Access Output from EXAMP1 Execution: NOLAN JACK HOSODA JOE ECKSTEIN LEO CARDIN RICK PASBY LINDA SEELY HENRY ROBERT GERRY TURNEWR IVAN WHITE GORDON WESTER ELDER END OF PROGRAM 923-4975 227-8214 287-5137 578-7018 295-1187 293-4220 258-5535 984-8498 398-0301 287-4598 967 REED AVE. 1180 SAINT PETER CT. 5303 STEVENS CREEK 11100 WOLFE ROAD TOWN & CNTRY VILLAGE 1144 LIBERTY ST. 12345 TELEGRAPH AVE . 22905 EMERSON ST. 4350 ASHBY AVE. 1256 KINGFISHER ST.
COBOL Intrinsics Examples of KSAM File Access 003100 003200 003300 003400 003500 003600 003700 003800 003900 004000 004100 004200 004300 004400 004500 004600 004700 004800 004900 005000 005100 005200 005300 005400 005500 005600 005700 005800 005900 006000 006100 006200 006300 006400 006500 006600 006700 006800 006900 007000 007100 007200 007300 007400 007500 007600 007700 007800 007900 008000 008100 008200 008400 008400 008500 008600 008700 222 01 02 FILENAME 02 I-O-TYPE 02 A-MODE 02 PREV-OP STATUSKEY.
COBOL Intrinsics Examples of KSAM File Access 008800 008900 009000 009100 009200 CALL "CKCLOSE" USING FILETABLE, STATUSKEY. IF STATUS-KEY-1 = "9" THEN CALL "CKERROR" USING STATUSKEY, RESULT DISPLAY "CKCLOSE ERROR NO.", RESULT. STOP RUN. Output from EXAMP2 Execution: ALPHABETICAL ORDER: CARDIN RICK 587-7018 11100 WOLFE ROAD ECKSTEIN LEO 287-5137 5303 STEVENS CREEK HOS0DA JOE 227-8214 1180 SAINT PETER CT. NOLAN JACK 923-4975 967 REED AVE.
COBOL Intrinsics Examples of KSAM File Access Figure A-6. Random Update with COBOL 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 004500 004600 004700 004800 004900 005000 005100 005200 005300 005400 005500 005600 005700 005800 005900 006000 224 IDENTIFICATION DIVISION, PROGRAM-ID. EXAMP3.
COBOL Intrinsics Examples of KSAM File Access 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 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 DISPLAY DATA-REC GO TO LOOP.
COBOL Intrinsics Examples of KSAM File Access 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 files. The following intrinsics were developed for these BASIC/V programs. NOTE 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 file intrinsics discussed in this manual.
BASIC/V Intrinsics Calling a KSAM Procedure 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 (filenumber, status [,parameterlist]) Where: statementlabel The number of the statement in the program. procname The KSAM access procedure to which control is transferred. filenumber A numeric variable whose value identifies an open KSAM file. This parameter must be present.
BASIC/V Intrinsics Status Parameter 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 first parameter. The first character of the status string determines its general type. The other three characters supply specific codes to further define the status.
BASIC/V Intrinsics Status Parameter 23 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 defined boundaries of the file; that is, to write past the end-of-file. 71 Request denied; File already locked — An attempt was made to lock a file with BKLOCK and the file is already locked.
BASIC/V Intrinsics KSAM Logical Record Pointer 220 DOEND 300 IF S$(2)= "2" THEN PRINT "DUPLICATE KEY" For any status value, you can call the BKERROR procedure and a message is returned that gives the meaning of the status code. You can then print this message rather than writing your own. KSAM Logical Record Pointer Many of the KSAM procedures use a logical record pointer to indicate the current record in the file.
BASIC/V Intrinsics BKCLOSE Shared Access Particular care must be taken when using the logical record pointer during shared access. Since the record pointer is maintained in a separate control block for each open file, one user may cause the record pointer to be inaccurate without other users being aware of it.
BASIC/V Intrinsics BKCLOSE Figure B-1.
BASIC/V Intrinsics BKDELETE BKDELETE Logically deletes a record from a KSAM file. CALL BKDELETE (filenum, status) A call to BKDELETE logically deletes the record referenced by the logical record pointer. If reuse is not specified, then a logically deleted record is marked for deletion, but is not physically removed from the file. The connection between a data record marked for deletion and the index area is severed.
BASIC/V Intrinsics BKDELETE 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. Figure B-2. contains an example illustrating the logical deletion of a record from a KSAM file. Figure B-2.
BASIC/V Intrinsics BKERROR BKERROR A call to BKERROR returns a message corresponding to the status value. CALL BKERROR (status, message) Call this procedure in order to get a printable string of characters that describes the condition that corresponds to the value of the status parameter. The string of ASCII characters returned in message can be printed as an error message.
BASIC/V Intrinsics BKERROR In another example, BKERROR is called to retrieve the message corresponding to the MPE file system error code returned when the first 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 Suppose the value returned in status is 9172.
BASIC/V Intrinsics BKLOCK BKLOCK Dynamically locks KSAM file during shared access. CALL BKLOCK(filenum,status[,condition]) When more than one user accesses the same file, BKLOCK can be used to make access to the file exclusive for one user while he writes to or updates the file. In order to use BKLOCK, the file must be opened with dynamic locking allowed by all users who are sharing the file.
BASIC/V Intrinsics BKLOCK Users who share the same file should cooperate on how they will share the file. Unless they all agree to allow locking, no one will be able to lock the file. Also, it is important to avoid situations where one user locks the file and forgets to unlock it. If this occurs when condition is set to a non-zero value, the calling process is not halted.
BASIC/V Intrinsics BKOPEN BKOPEN A call to procedure BKOPEN initiates KSAM file processing. CALL BKOPEN (filenum,status,name [,access[,lock[,exclusive[,sequence]]]]) In order to process a KSAM file, it must be opened with a call to the BKOPEN procedure. BKOPEN initiates processing, and optionally specifies how the file is to be processed. BKOPEN does not create the file; it must have been created previously. To open a file means to make it available for processing.
BASIC/V Intrinsics BKOPEN access 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.
BASIC/V Intrinsics BKOPEN concurrently by any user in any access mode, subject only to the MPE security provisions in effect. (Optional parameter) Default: If omitted or out of range, exclusive equals 2, semi-exclusive access. sequence A numeric expression whose value indicates whether records written to the file will be checked for primary key sequence or not. Acceptable values are: 0 No sequence checking.
BASIC/V Intrinsics BKOPEN records to a file, but not to change or delete existing records. If you plan to read and write records during the same process but do not want to alter existing records, use this access mode. If you want to rewrite or delete existing records in a KSAM file, you must open with access = 4. This mode allows you to use the BKREWRITE and BKDELETE procedures, as well as all the other procedures described in this section. Table B-2.
BASIC/V Intrinsics BKOPEN the access parameter.) Table B-3. Relationship of Exclusive Parameter to Access Parameter access=0 exclusive=0 exclusive=1 exclusive=2 (default) exclusive=3 shared exclusive semi-exclusive shared exclusive exclusive semi-exclusive shared (read only) access≠0 (write only, read/write, or update) When access is shared, it is good practice to allow dynamic locking so that individual users can dynamically lock the file while performing any updates to the file.
BASIC/V Intrinsics BKOPEN 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 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, TYPE ASCII, 16 REC/BLOCK.
BASIC/V Intrinsics BKREAD BKREAD Transfers the next logical record from a KSAM file to a BASIC program. CALL BKREAD(filenum,status[,parameterlist]) A call to BKREAD transfers the contents of a record from a KSAM file to a storage area defined 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.
BASIC/V Intrinsics BKREAD Values are read from the current record into the variables specified in parameterlist according to the type and length of the variable.
BASIC/V Intrinsics BKREAD A5 a 5-word integer array A2 a 2-word integer array A3 a 3-word integer array B1$ a 1-character string B2$ a 2-character string The five integers that were written to the beginning of each record are read into array A5. The next two arrays A2 and A3 receive the undefined values that filled the next five words of the record. The first string character is read into B1$, the next two into B2$.
BASIC/V Intrinsics BKREAD Figure B-5. Reading From a KSAM File with BKREAD 10 20 30 40 50 55 60 65 70 . . .
BASIC/V Intrinsics BKREADBYKEY BKREADBYKEY Transfers record identified by particular key value from KSAM file to BASIC program. CALL BKREADBYKEY(filenum,status,keyvalue,keylocation,parameterlist) A call to BKREADBYKEY locates and reads a record into a storage area identified by a list of variables in the BASIC program. The record to be read is located by matching the specified keyvalue with an identical value stored in the record starting at keylocation.
BASIC/V Intrinsics BKREADBYKEY keylocation parameters. The key value in the record to be read must exactly match the specified keyvalue. Unlike BKSTART, the only relation between the value in the record and the value in the call is that of equality. If duplicate key values are allowed in the key being sought, then the first record with a matching key value is read by BKREADBYKEY. To read the remaining records with duplicate key values, you should use BKREAD.
BASIC/V Intrinsics BKREWRITE BKREWRITE Changes the contents of a record in a KSAM file. CALL BKREWRITE (filenum, 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 file must be open in the access mode that allows update.
BASIC/V Intrinsics BKREWRITE NOTE Items written to a KSAM file with the BKREWRITE procedure are concatenated; rounding to halfword boundaries does not occur. The example in Figure B-9. writes new values to a record originally written in Figure B-13. and read in Figure B-5. The new values fill an array that had undefined values in the last five elements, now defined as two arrays A3 and A2 by the BKREAD call. The primary key value 23 in location 2 is unchanged.
BASIC/V Intrinsics BKREWRITE 2640 2650 2660 2670 2680 2690 2700 2710 2720 2730 2740 2750 2760 2770 2780 2790 2800 2810 2820 2830 2900 2910 2920 2930 2940 2950 2960 2970 2980 2990 3000 3010 3020 3030 3040 3050 3060 3070 3080 3090 3100 3110 3120 3130 3140 3150 3160 3170 3180 3190 3200 3210 254 REM REM REM REM REM REM REM F IS THE FILE NUMBER OF A KSAM FILE OPENED BY A CALL TO BKOPEN NOTE THAT FOR BKREWRITE,BKOPEN ACCESS MODE MUST=4 FOR UPDATE.
BASIC/V Intrinsics BKSTART BKSTART Positions a KSAM file to a particular record based on a key value. CALL BKSTART(filenum,status[,keyvalue[,keylocation [,relation ]]]) By calling BKSTART, you can position the record pointer to any record in the file 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.
BASIC/V Intrinsics BKSTART relation A numeric expression whose value specifies the relation between the specified keyvalue and the value of the key at keylocation. The record pointer is positioned to the first 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.
BASIC/V Intrinsics BKSTART 100 150 160 170 DIM A$(10),S$(4) A$=" " <------------------- assign null string to keyvalue L=21 <-------------------- assign alternate key location to keylocation CALL BKSTART(F,S$,A$,21) The default for relation is 2 (greater than or equal to) and need not be specified except for documentation purposes. Figure B-10. illustrates the use of BKSTART with default values for all optional parameters. Specified in this minimal form, it positions to the least valued primary key.
BASIC/V Intrinsics BKSTART The example in Figure B-11. positions the record pointer to a record containing a specific 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. Figure B-11.
BASIC/V Intrinsics BKUNLOCK BKUNLOCK Unlocks a KSAM file dynamically locked by BKLOCK. CALL BKUNLOCK(filenum,status) A file locked by BKLOCK is released for use by other users with a call to BKUNLOCK. (If you log off from any connection with the system, the file is also unlocked.) Since dynamic locking takes place during shared access to the same file by more than one user, it is important that any file locked by BKLOCK be unlocked as soon as possible by BKUNLOCK.
BASIC/V Intrinsics BKUNLOCK 1850 1860 1870 1880 1890 1900 260 CALL BKERROR(S$,M$) PRINT M$ GOTO 3620 DOEND REM REM THE PROGRAM CONTINUES Appendix B
BASIC/V Intrinsics BKWRITE BKWRITE Writes data from a BASIC program to a KSAM file. CALL BKWRITE (filenum,status,parameterlist) A call to procedure BKWRITE writes a record to a KSAM file from a BASIC program. This call provides the only way to create a KSAM record from a BASIC program. The file must have been opened with an access mode that allows writing. If access is shared, the file also must be opened for dynamic locking (lock = 1), and the file locked with BKLOCK before any records are written.
BASIC/V Intrinsics BKWRITE NOTE Items written to a KSAM file from a BASIC program are concatenated; rounding to halfword boundaries does not occur. Figure B-13. is an example of writing one string and one integer array to each record of the KSAM file. Figure B-13. Writing to a KSAM File with BKWRITE 10 20 30 40 50 55 60 65 70 80 90 100 110 120 130 135 . . .
BASIC/V Intrinsics BKWRITE 730 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CODE 740 PRINT "UNABLE TO WRITE TO ";N$;"ERROR "[S$]; DETAIL ";S$[& 2] 750 CALL BKERROR(S&,Ms) 760 PRINT M$ 770 GOTO 3620 780 DOEND 790 NEXT I 800 REM 810 REM THE PROGRAM CONTINUES Appendix B 263
BASIC/V Intrinsics BKWRITE 264 Appendix B
C HP C/iX Example Program The following example program shows how a KSAM XL file 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.
HP C/iX Example Program 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 filler_2[4]; struct { unsigned short filler_1 : 10; unsigned sho
HP C/iX Example Program HPCICOMMAND("PURGE " FILENAME "\r", &cmderror, , 2); assert(!cmderror || cmderror==-383); /* Create new KSAM XL file, output access, 44-byte ASCII records, limit = 100, save disposition */ HPFOPEN(&filenum, &status, 2, "-" FILENAME "-", 10, &ksamxl, 11, &out, 19, &recsize, 35, &filesize, 50, &save, 53, &ascii, 54, &ksamparam); assert(!status); /* Write test data to file */ for (i=0; i
HP C/iX Example Program FREAD(filenum, buffer, - sizeof buffer); if ((save_ccode=ccode()) == CCG) break; assert(save_ccode==CCE); printf(" %.5s %.20s %.3s-%.2s-%.4s " "%.4s %.2s/%.2s/%.
HP C/iX Example Program } static void update_records(void) { /* Update department code for several employees */ const struct {char empno[5]; char new_dept[4];} update_data[] = {{"28766", "9901"}, {"11111", "9905"}}; const int update_items = sizeof update_data / sizeof update_data[0]; int i; record_t buffer; for (i=0; i
HP C/iX Example Program 270 Appendix C
Index B BASIC/V intrinsics BKCLOSE, 232 BKDELETE, 234 BKERROR, 236 BKLOCK, 238 BKOPEN, 240 BKREAD, 246 BKREADBYKEY, 250 BKREWRITE, 252 BKSTART, 255 BKUNLOCK, 259 BKWRITE, 261 BKCLOSE BASIC/V intrinsic, 232 BKDELETE BASIC/V intrinsic, 234 BKERROR BASIC/V intrinsic, 236 BKLOCK BASIC/V intrinsic, 238 BKOPEN BASIC/V intrinsic, 240 BKREAD BASIC/V intrinsic, 246 BKREADBYKEY BASIC/V intrinsic, 250 BKREWRITE BASIC/V intrinsic, 252 BKSTART BASIC/V intrinsic, 255 BKUNLOCK BASIC/V intrinsic, 259 BKWRITE BASIC/V intri
Index deleting records, 57 device class, 19 Disk file file label information returned FLABELINFO, 111 disk file, remove FRENAME, 145 disposition, 46 domain, 39, 41, 46, 61, 66 DUP parameter, 21 dynamic locking, 39, 42, 54, 56, 57, 60 E error information, 59 F FCHECK intrinsic, 59, 72 FCLOSE intrinsic, 46, 74 FCONTROL intrinsic, 61, 77 FCOPY subsystem, 25, 61, 67 KEY= parameter, 25 FERRMSG intrinsic, 59, 80 FFILEINFO Intrinsic, 81 Returns information about a file, 81 FFINDBYKEY intrinsic, 49, 51, 97 FFINDN
Index FSPACE, 147 FUNLOCK, 42, 54, 56, 57, 60, 148 FUPDATE, 56, 149 FWRITE, 56, 151 FWRITELABEL, 37, 153 HPFOPEN, 19, 26, 30, 39, 42, 61, 154 item number pairs, 30, 39, 42 K key duplication, 20, 28 duplication method, 21 length, 28, 37 location, 20, 28, 37 size, 20 type, 20, 28, 37 key characteristics, 26 key data, 19 key field, 13 key index, 15 key parameters, 28 key sequence, 15 key specifications, 34, 37 KEY= parameter, 20 KSAM XL, 65 data area, 16 definition, 13 index area, 15 KSAM XL display, 33 KSAMU
Index shared access, 42, 54, 56, 57, 60 software abort, 61 specifying data block size, 22 STORE/RESTORE facility, 62 subsystems FCOPY, 25, 61, 67 system abort, 61 system logging, 61, 66 T TO= parameter, 25 transaction management, 17, 61, 66 tree structure, 16 U update access, 56 updating records, 56 user label, 37 utilities KSAMUTIL, 66 V variable-length records, 67 W writing records, 56 274 Index
