Click above to get retro games delivered to your door ever month!

   CftsOpen( <expC>, <expN1>, [<expL> | <expN2>] )

      Purpose

   This function is used to open an existing index file.

       Parameters

   <expC> a string representing a file path name. It may contain drive 
   and subdirectory information.

   <expN1> is an integer which will be multiplied by 1024 to determine 
   how much buffer space is to be used by the CFTS routines for this 
   index. For example, a value of 20 will allocate 20k or 20480 bytes of 
   buffer space plus a small amount of overhead. See the comments section 
   for CftsCrea() for how to use this number most wisely. The minimum 
   size is 1. Performance will improve greatly if the entire index file 
   will fit into this buffer. If not, some experimentation will be 
   helpful in determining the best size. In network operation this buffer 
   is automatically set to the minimum size.

   The memory buffer size is less critical in the newer more powerful 
   computers where fast fixed disks and extensive disk caching are 
   common. Some experimentation will help chose the proper settings for 
   any particular application and environment.

   <expN2> is an integer expression indicating the read-write and 
   sharing modes for the file. A CFTS index can be opened read-write or 
   read-only and EXCLUSIVE or SHARED. The EXCLUSIVE and SHARED modes 
   follow Clipper's use of the terms. When an index is opened read-write, 
   the application can read existing index records and write new ones to 
   the file. When the file is opened read-only, the application can only 
   read records from the index. This mode is useful with CD-ROM 
   applications or with applications that must prevent users from 
   inadvertently updating an existing index.

   The values to use are:
       0    READ-WRITE + SHARED
       1    READ-WRITE + EXCLUSIVE
       2    READ-ONLY + SHARED
       3    READ-ONLY + EXCLUSIVE

   <expL> is an optional choice for the OPEN MODE parameter. Existing 
   Clipper applications that use the logical values .F. and .T. to 
   indicate SHARED or EXCLUSIVE modes will continue to work with this 
   version of CFTS. Users of the LANtastic and PC-MOS versions of CFTS 
   will need to modify their code to conform to the new mode parameter.

       Return Value

   Returns a CFTShandle (0 through 63) if successful, else returns a 
   negative integer indicating an error (see below). Both CftsCrea() and 
   CftsOpen() return a 'HANDLE' to the calling program.  You must save 
   the handle returned by these functions for use with the remaining CFTS 
   functions. CFTS handles are nothing more than a magic cookie returned 
   by CFTS's create and open routines; in other words, the value of a 
   CFTS handle is only meaningful to other CFTS functions. Although you 
   may inspect the value of the handle, its value is arbitrary and of no 
   significance except to other CFTS functions. Under no circumstances 
   should your application ever change the value of a CFTS handle.

       Errors Returned

    -2   (MEMERR): System was unable to allocate the memory requested. 
                   Try again with a smaller value of <expN>.
    -5   (BADREAD): System generated a read error while reading the 
                    index file header. This error is associated with 
                    trying to open a file that is already open.
   -10   (OPENERR): Open failure. System was unable to open the file 
                    specified by <expC>. Insure that the file does exist
                    and it is not read protected.
   -16   (BADPARMS): Invalid parameters were passed to the function.
   -17   (NOMOREHANDLES): Ran out of CFTS handles.
   -20   (LOCKFAILED): Unable to lock file.
   -21   (NOMORELOCKS): Lock table exhausted.
   -22   (CANNOTUNLOCK): Unable to unlock file.

       Comments

           Network Operation

   The CftsOpen() mode parameter is patterned after Clipper's 
   Net_Use() function; in earlier versions of CFTS, the parameter was 
   required to be .T. or .F., just like Clipper's Net_Use() function. .F. 
   meant open the filefor sharing by more than one application, while .T. 
   meant open the file exclusively. Note that the type of the open mode 
   parameter has changed from a logical to an integer with this version 
   of CFTS. (See above for an explanation of the values now supported by 
   CFTS.)

   Whenever a new CFTS index file is created it is always created in 
   EXCLUSIVE mode. If an application needs to create an index and then 
   use it in SHARED mode, it must create the index using CftsCrea(), then 
   close the index, and use CftsOpen() to reopen the file with the 
   SHARING mode on. Users of the interface functions provided in the 
   CFTS.PRGs should make note that Cfts_Index() does require a mode 
   parameter. This is because once the function creates and builds a new 
   index, it closes the index and then reopens it in the desired mode.
   
   It is possible, on some systems, to get a -20, LOCKFAILED error. If 
   CftsOpen() cannot lock the file, after trying three times, it will 
   return the -20 error. You can insert code to trap the -20 and force 
   the program to try again. This will prove satisfactory in most cases.
   
           How CFTS Works on a Local Area Network

   When an application tries to open an index in SHARED mode, 
   CftsOpen() tests for the presence of support for file locking and 
   adjusts its behavior accordingly. Assuming that you are on a network 
   and you open your CFTS index in SHARED mode, CFTS automatically 
   institutes a system of locks while keeping its buffers flushed. In the 
   event that you attempt open a CFTS index in SHARED mode on a machine 
   that does not support file and record locking, CFTS does not try to 
   lock files and it manages its buffers in the same way that using a "1" 
   open mode would. (The READ-ONLY open-mode does not change the way CFTS 
   handles its internal buffers when running in SHARED mode. That is, the 
   memory buffer is set to 1K.)

   Index Applications' demonstration program BIB.PRG supports 
   CftsOpen(), as do the Cfts_Open() and Cfts_Index() functions in
   CFTS87.PRG or CFTS5.PRG. These files are on the CFTS 
   version 2 distribution disk.We urge you to examine this code when 
   beginning to work with the library.

       Example

   .
   .
   .
   ianame = 'sales.ia'
   xhandle = CftsOpen( ianame, 20, 1 )
   if xhandle <0
      ? 'error opening ' + ianame + 'CFTS index file'
   endif
   .
   .
   .