FOPEN

The ksamparam array defines the key file for a new KSAM file. If the file has already been created, this parameter can be set to all zeros or omitted. Otherwise, it must be assigned values to define the key file as shown in Table 4-8 “FOPEN ksamparam Parameter Format”.

When a new KSAM file is created, the MPE end-of-file for the key file is set to the file limit. The file limit is based on the key file size (see words 4-5 of ksamparam). The location of the key file end-of-file can be determined by executing the VERIFY command of KSAMUTIL and looking at the heading KEY FILE EOF. A call to FGETKEYINFO returns the key file size as the number of sectors used by the file.

Table 4-8 FOPEN ksamparam Parameter Format

This array defines the key file portion of a new KSAM file being created by the FOPEN call. The values are:

The array ksamparam is defined three different ways: as a numeric array containing 25 words (KSAMPARAMA), as a byte array equivalenced to the numeric array (KSAMPARAM), and as a double array also equivalenced to the numeric array (KSAMPARAMD). These three definitions allow the array to be addressed by word, by byte, or by double word asrequired.

The variable to which the file number is returned is declared to be an integer.

The two arrays that will contain the formal designator and device parameter values are declared and assigned these values. In this case, the formal designator is assigned the value JEXAMFIL. This name identifies both the KSAM file in its entirety and the data file if referenced separately. The device class name assigned to the device parameter is DISC.

Finally, the intrinsic itself is declared in an INTRINSIC statement.

The ksamparam parameter is assigned a variety of values that, for the sake of clarity, are assigned in separate statements. The values assigned to ksamparam define the key file. The statements that move values to ksamparam (refer to Figure 4-5 FOPEN Example - Building a KSAM file) tell the system everything it needs to know in order to build the key file.

The first item moved to ksamparam is the key file name, up to 8 characters enclosed in quotes. In this case, the key file name is JKEYFILE.

Next, the size of the key file is defined in terms of the maximum number of primary keys expected. The size is specified as a double word integer and is assigned to the third double word in the array, specified by an index of 2 counting from double word 0. The maximum number of primary keys should be the same as the maximum number of records specified in the filesize parameter of FOPEN. KSAM assigns a key file size based on this value. If there are alternate keys, the key file size is made proportionately larger. If the key file size is specified as zero, KSAM uses the value of the FOPEN filesize parameter as the key file size.

The device class name is assigned in the 8 bytes starting in byte 12 that are allocated to device description. In this case, the device class name is DISC, the same as the device class name specified in the device parameter of FOPEN for the data file.

$CONTROL MAIN-JEXAMPL1 
<<*********************************************************>>
<<*                                                       *>>
<<*              EXAMPLE l                                *>>
<<*            BUILD A KSAM FILE                          *>> 
<<*                                                       *>> 
<<*********************************************************>> 
ARRAY KSAMPARAMA(0:25);   
BYTE ARRAY KSAMPARAM (*)=KSAMPARAMA;   
DOUBLE ARRAY KSAMPARAMD(*)=KSAMPARAMA;   
INTEGER FILNUM;   
INTEGER ERRORCODE;   
INTEGER LENGTH;   
BYTE ARRAY FILENAME(0:9):="JEXAMFIL ";   
BYTE ARRAY DEVICE(0:9):="DISC ";   
ARRAY MESSAGE(0:35); 
ARRAY INPUT(0:39); 
ARRAY OUTPUT(*)=INPUT; 
INTRINSIC FOPEN,FCLOSE,PWRITE,READ,PRINT,TERMINATE; 
INTRINSIC FCHECK,FERRMSG;   
<<*******************************>> 
<<* SETUP KSAMPARAM FOR FOPEN   *>> 
<<*******************************>> 
MOVE KSAMPARAM;="JKEYFILE";           <<THE KEY FILE NAME>> 
KSAMPARAMD(2):=100D;                  <<THE MAX. # OF PRIMARY KEYS>>  
MOVE KSAMPARAM(12):="DISC";           <<THE KEY FILE DEVICE TYPE>> 
KSAMPARAMA(15):=%(2)000000000000010; <<THE FLAG WORD>> 
KSAMPARAMA(16):=2;                    <<PRIMARY KEY & ONE ALTERNATE>> 
MOVE KSAMPARAMA(17):=([4/1,12/20],   <<TYPE=ASCII; LENGTH=20 BYTES>> 
                       1,          <<KEY LOCATION START FROM COL 1>>
                      [1/0,15/4],  <<DUP NOT ALLOW; 4 KEY/BLOCK>> 
                       0);         <<RESERVED>> 
MOVE KSAMPARAMA(21):=([4/1,12/8],  <<TYPE=ASCII; LENGTH=20 BYTES>> 
                       21,         <<KEY LOCATION START FROM COL 21>>
                      [1/0,15/4],  <<DUP NOT ALLOW; 4 KEY/BLOCK>> 
                       0);         <<RESERVED>> 
<<************************>> 
<<* OPEN THE KSAM FILE   *>> 
<<************************>> 
FILNJM:=FOPEN(FILENAME,         <<THE DATA FILE NAME>> 
              %(2)0000100000000100,  <<KSAM,ASCII,NEW FILE>> 
              %(2)0000000001000001,  <<KSAM ACCESS,EXCLUSIVE,WRITE>> 
              -72,              <<RECORD 72 BYTES LONG>> 
              DEVICE,                 <<DEVICE=DISC>> 
              KSAMPARAM,              <<THIS DESCRIBES THE KEYS>> 

              ,                       <<NO USERLABELS>> 
              10,                     <<BLOCK 10 RECORDS>> 
              ,                       <<NUMBUFFERS NOT USED>> 
             100D);                   <<THIS FILE CAN HOLD 100 RECORD>> 
IF FILNUM=0 
THEN BEGIN <<CANNOT OPEN KSAM FILE>> 
       MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; 
       PRINT(MESSAGE,-21,0); 
       FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> 
       FERRMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>> 
       PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> 
       TERMINATE; 
     END; 

Word 15, the flag word, is set next, It uses bits 13,14, and 15 to define three conditions of the key file. In this example, bit 14 is the only bit set. This means that record numbers in the file start with 1 rather than 0 (bit 14=1), that the file is a permanent file saved in the system directory (bit 15=0), and that records may be written to the file in random order rather than being restricted to ascending sequence by primary key (bit 13=0).In Figure 4-5 FOPEN Example - Building a KSAM file the flag word is specified as a binary value for clarity; it could have been specified as octal 2 (2 or %2) for brevity.

The right byte of the 16th word (byte 33) is set to 2 to specify that two keys are to be used: the primary key and one alternate.

This completes the general description of the file. Its name, size, device type, special conditions, and number of keys are now specified. The remainder of ksamparam defines each key in 4-word entries. The first entry always describes the primary key. Subsequent entries define up to 15 alternate keys. In this case, one primary and one alternate are defined.

Starting in word 17, the primary key is defined as type ASCII, 20 bytes long, its location starting in the first character of each record, and duplicate values are not allowed. It is blocked with four keys per block.

Starting in word 21, the altemate key is defined as type ASCII, 8 bytes long, located starting in character 21 of the record, duplicate values not allowed, and blocked four keys per block.

Refer to Table 4-8 “FOPEN ksamparam Parameter Format” for an illustration of the bit patterns used to define the ksamparam entries.

When all the variables and arrays that pass values by reference have been defined, the intrinsic FOPEN can be called. In Figure 4-5 FOPEN Example - Building a KSAM file, each parameter is shown on a separate line and documented for clarity, but the call could also be specified as:

      FILNUM:=FOPEN(FILNAME,%4004,%101,--72,DEVICE,KSAMPARAM,,10,0,100D); 

This call is identical to the call in Figure 4-5 FOPEN Example - Building a KSAM file except that octal values are used for foption and aoption.

foptions

The value of foptions is set to octal 4004, for which the bit pattern is:

This specification defines the following file options:

aoptions

The value of aoptions is set to octal 101, for which the bit pattern is:

This specification defines the following access options:

The example in Figure 4-6 FOPEN Example - Opening an Existing File illustrates opening a file for readonly access.

%CONTROL MAIN=JEXAMPL2 
<<*********************************************************************>>
<<*                                                                   *>>
<<*                                                                   *>>
<<*********************************************************************>>
INTEGER FILNUM;   
INTEGER ERRORCODE,LENGTH;   
BYTE ARRAY FILNAME(0:9):="JEXAMFIL ";   
ARRAY MESSAGE(0:35); 
ARRAY INPUT(0:39); 
ARRAY OUTPUT(*)=INPUT; 
BYTE ARRAY KEYVALUE(0:7):="000-0000"; 
INTEGER KEYLENGTH:=8; 
INTEGER KEYLOCATION:=21; 
INTEGER RELOP:=2; 
INTRINSIC FOPEN,FCLOSE,FREAD,FFINDBYKEY,READ,PRINT, 
          FCHECK,FERRMSG,PRINT'FILE'INFO,TERMINATE; 
<<************************>> 
<<* OPEN THE KSAM FILE   *>> 
<<************************>> 
  FFILNUM:=OPEN(FILNAME,3);   <<OPEN THE KSAM FILE>>
IF FILNUM=0 
THEN BEGIN <<CANNOT OPEN KSAM FILE>> 
       MOVE MESSAGE:="CANNOT OPEN KSAM FILE"; 
       PRINT(MESSAGE,-21,0); 
       FCHECK(FILNUM,ERRORCODE); <<GET THE ERROR NUMBER>> 
       FERRMSG(ERRORCODE,MESSAGE,LENGTH); <<GET MESSAGE STRING>> 
       PRINT(MESSAGE,-LENGTH,0); <<PRINT ERROR MESSAGE>> 
       TERMINATE; 
     END; 

The file name is specified in the FILNAME array declaration as JEXAMFIL. This is the file that was created and opened for write-only access in Figure 4-5 FOPEN Example - Building a KSAM file. It is opened for read-only access with the call:

   FILNUM:=FOPEN(FILNAME,3); 

The value of foptions is set to the value 3, for which the bit pattern is:

This specification defines the following file options:

Because this is an existing (old) user file, other foptions settings defined when the file was created need not be respecified. For example, at creation the file was defined as containing ASCII code (bit 13=1). In subsequent FOPEN calls this bit can be 0 without changing the code to binary.

When an old user file is opened, the job file domain is searched first and then the system file domain is searched for the file specified in the formal designator.

The access parameter, aoptions, is not specified, but by default it specifies the following access mode:

To open an existing file for write access, you use the same foptions values as you do to open the file for read-only access. The different access mode is specified in the aoptions parameter.

For example, assuming FILNUM and FILNAME have been declared:

     FILNUM:=FOPEN(FILNAME,3,1) 

The foptions specification is the same as described above. The aoptions specification is:

This bit pattem defines the following access options:

This opens the file for write-only access in which all previous data is deleted. It is the access mode to use when writing to a file for the first time. If you want to write to the end of an existing file then bits 12-15 should equal 0010 and aoptions could be specified as 2 if other aoptions values are defaulted. To open the file for both reading and writing, bits 12-15 should be set to 0100, or the value 4. For update, these bits are set to 0101, or the value 5.

You may want to open either the key file or the data file as a standard MPE file. To do this, name the file you want to open in the formaldesignator parameter, set foptions bit 4:1 to 1, and then set aoptions bit 3:1 to 1. These settings indicate that the file is a KSAM file, but is to be treated as an MPE file. The remaining parameter settings depend on what you want to do with the open file. For example, if you want to read the key file, JKEYFILE, as an MPE file, you call FOPEN as follows:

     INTEGER          FILNUM; 
     BYTE ARRAY       FILNAME(0:9):="JKEYFILE ";
     .
     .
     .
     INTRINSIC FOPEN,...;
     .
     .
     .
     FILNUM:=FOPEN(FILNAME,%4003,%10000); 

The value of foptions defines the following file options:

The value of aoptions indicates the following:

Normally, the only time you need to set bit 4 of foptions to 1 is when you are originally creating a KSAM file. However, when you are opening an existing KSAM file for non-KSAM access, you must set this bit to 1 so that the system can distinguish the KSAM data or key file from an MPE file.

When a file is opened for shared access (aoptions bits 8,9=11), and you plan to modify the file in any way, you must enable dynamic locking (aoptions bit 10=1). This is necessary since you cannot call FWRITE, FUPDATE, or FREMOVE to modify a shared file without first calling FLOCK to lock the file.

Even if you are not planning to modify the file, but only plan to read it sequentially, you should allow dynamic locking when you open the file. This is because FREAD (as well as FUPDATE and FREMOVE) is a pointer-dependent procedure. Any time you call a pointer-dependent procedure (refer to Table 4-2 “Positioning the Pointers”), you must precede it with a call to a pointer-independent procedure that positions the pointer. It is important to call FLOCK to lock the file before setting the pointer with the pointer-independent procedure and leave it locked until you have completed the sequential read or update. This insures that no other user changes the position of the pointer between the call that positions the pointer and the call that depends on the pointer.