Opening an Existing KSAM XL File

Using the HPFOPEN Intrinsic

The HPFOPEN intrinsic uses pairs of item numbers and items for optional parameter passing. An itemnum parameter passes an integer by value to define the parameter and expected data type of the value passed in its corresponding item parameter.

To open an existing permanent file, file characteristics do not have to be specified. This information is obtained by the file management system from the file's label.

Most often, the item number pairs that are needed to open an existing KSAM XL file include the file designator, its domain, and access options. The domain identifies the location of the file to be opened. The access option defines the method of access allowable for the file. In some cases, the dynamic locking option and exclusive option need to be specified if more than one process is to access the file.

Figure 4-1 “Opening an Existing KSAM XL File with HPFOPEN” provides a portion of a Pascal program that calls the HPFOPEN intrinsic to open the accounts receivable KSAM XL file. It presents the itemnum and item definitions and declarations as well as the HPFOPEN intrinsic call. In the example, the file is opened for update access, allowing all intrinsic usage. It also allows dynamic locking and shared access for concurrent use with other processes.

procedure open_permanent_KSAM_file;



const

   formal_designator_option = 2;

   domain_option            = 3;

   access_type_option       = 11;

   dynamic_locking_option   = 12;

   exclusive_option         = 13;

   ASCII_binary_option      = 53;



type

   pac160    = packed array [1..160] of char;



var 

   file_num  : integer;

   status    : integer;

   file_name : pac160;

   permanent : integer;

   update    : integer;

   lockable  : integer;

   shared    : integer;

   ascii     : integer;



begin

   file_num        := 0;

   status          := 0;

   file_name       := '%ARMSTR.MGR.AR%'

   permanent       := 1;

   update          := 5;

   lockable        := 1;

   shared          := 3;

   ascii           := 1;



   HPFOPEN(file_num, status,

          formal_designator_option, file_name,

          domain_option, permanent,

          access_type_option, update,

          dynamic_locking_option, lockable,

          exclusive_option, shared,

          ASCII_binary_option, ascii

          );



   if status <> 0 then handle_file_error (file_num, status);

end;

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. The following HPFOPEN intrinsic call provides the same options as the preceding example, but the itemnum parameters are identified by number. Note that the corresponding item parameters are variables that contain the appropriate selections. These variables would have to be defined and declared as in the previous sample.

   HPFOPEN(file_num, status,

          2, file_name,

          3, permanent,

          11, update,

          12, lockable,

          13, shared,

          53, ascii

          )

Using the FOPEN Intrinsic

Only the file designator and the domain need to be specified to open an existing file with the FOPEN intrinsic. Rather than the itemnum/item pairs in HPFOPEN, the FOPEN intrinsic parameters are specified as bit groupings. The domain must be specified in the foption parameter (bits 14:2). The aoption parameter must be set if an access other than read needs to be specified.

The FOPEN intrinsic uses positional parameters to specify options. This means that the sequence of parameter data defines the parameter to which it refers. For example, in an FOPEN intrinsic call, the file designator is followed by the foption parameter, which is followed by the aoption parameter. The following example shows the FOPEN intrinsic call to open an existing KSAM XL file for read only access:

   file_num:=FOPEN(file_name,3)

The variable file_num returns the file number for use in subsequent intrinsic calls. The foption value 3 specifies that an existing user file is to be opened (bits 14:2= (binary) 11). Because no aoption parameter was specified, the file is opened with read only access, the default.

To open an existing file with update access, specify the access mode in the aoption parameter. The other parameters remain the same. The following example opens the file with update access.

   file_num:=FOPEN(file_name,3,5)

In this example, the aoption value 5 specifies update access for the file (bits 12:4 = (binary) 0101). This level of access allows all other intrinsic calls for this file. Other binary access selections include:

If your file requires shared access and you are accessing records using pointer-dependent procedures, you must allow dynamic locking in the file opening procedure and use the FLOCK and FUNLOCK intrinsics to protect your transactions from access by another process. This ensures that no other user changes or deletes the record after you have positioned the pointer to it. In this case, the aoption parameter must be set to allow both shared access and dynamic locking, as well as to specify the access method. Note that the aoption parameter can be entered in octal notation listing "%" instead of "binary". This allows setting the shared and dynamic locking bits.

   FILENUM:=FOPEN(FILNAME,3,OCTAL ('340')

The preceding example allows shared access (bits 8:2 = binary 11) and dynamic locking (bits 10:3=1) with read only access (bits 12:4=0) .