home *** CD-ROM | disk | FTP | other *** search
/ World of Shareware - Software Farm 2 / wosw_2.zip / wosw_2 / PASCAL / BCSHARE.ZIP / BCSHARE.DOC < prev    next >
Text File  |  1990-11-17  |  10KB  |  242 lines
  1.                           BCSHARE Beta Version 0.7
  2.                          Compliments of Mike Woltz
  3.                      Copyright (C) By Mike Woltz 1990
  4.                            Buffalo Creek Software    
  5.                                 A Member Of
  6.                   The Association Of Shareware Professionals
  7.                    Home of SPITFIRE Bulletin Board System
  8.  
  9.      BCSHARE is written by Mike Woltz (Buffalo Creek Software) to be used
  10.      to open files in a manner to provide the use of file sharing and
  11.      locking for multitasking and/or LAN systems.  BCSHARE is written
  12.      in Turbo Pascal and interfaced with assembler code (BCSFILE.OBJ) for
  13.      speed.  You are free to use BCSHARE within your programs written in
  14.      Turbo Pascal provided Buffalo Creek Software is given credit for this
  15.      code either in your program documentation or within your program
  16.      itself.  While you are free to use BCSHARE, you are NOT allowed to
  17.      alter this code.
  18.  
  19.      FILE SHARING
  20.      ------------
  21.      Turbo Pascal uses a byte variable named FILEMODE to set the file access
  22.      mode when non-text files are opened for use.  The value of FILEMODE can
  23.      be changed for the purpose of opening non-text files in any mode your
  24.      application requires.  Unfortunately, FILEMODE is not used for opening
  25.      text files.  When text files are opened using the standard procedures,
  26.      the file access mode is totally controlled by Turbo Pascal.  BCSHARE
  27.      changes that for you.  BCSHARE opens text files and does all the file
  28.      I/O in a manner to allow file sharing.  There is really nothing to it.
  29.      Simply assign your text files using BCSHARE's AssignTxtFile procedure
  30.      and BCSHARE will do the rest.  For example...
  31.  
  32.      Uses
  33.        BCSHARE,
  34.        DOS;
  35.      VAR
  36.        TF   : Text;
  37.        Line : String;
  38.  
  39.      Begin;
  40.        AssignTxtFile(TF,'BCSHARE.DOC');
  41.        {$I-}Reset(TF);{$I+}
  42.        If IOResult<>0 Then Halt;
  43.        While Not EOF(TF) Do
  44.        Begin;
  45.          {$I-}Readln(TF,Line);{$I+}
  46.          If IOResult<>0 Then
  47.          Begin;
  48.            {$I-}Close(TF);{$I+}
  49.            If IOResult<>0 Then;
  50.            Halt;
  51.          End;
  52.          Writeln(Line);
  53.        End;
  54.        {$I-}Close(TF);{$I+}
  55.        If IOResult<>0 Then;
  56.      End.
  57.  
  58.      As you will notice from the above example, once you have used
  59.      AssignTxtFile, you then use the Turbo Pascal 'Reset','Rewrite',
  60.      'Append' and 'Close' procedures as you normally would when working
  61.      with text files.  BCSHARE works hand in hand with Turbo Pascal so
  62.      these standard procedures can be used.
  63.  
  64.      BCSHARE makes file sharing with non-text files very simple.  BCSHARE
  65.      has a procedure named SetFileMode which needs to be called just before
  66.      you 'Reset' or 'Rewrite' a non-text file.  SetFileMode is used to change
  67.      the value of Turbo Pascal's byte variable FileMode.  SetFileMode will
  68.      assign 5 different values to FileMode.
  69.  
  70.      SetFileMode(ReadMode);       Setting FileMode to 'ReadMode' will allow
  71.                                   other programs to access the file for read
  72.                                   but not for write while the file is open
  73.                                   for read purposes.
  74.      SetFIleMode(WriteMode);      Setting FileMode to 'WriteMode' will allow
  75.                                   other programs to access the file for write
  76.                                   but not for read while the file is open for
  77.                                   write purposes.
  78.      SetFileMode(NormalMode);     Setting FileMode to 'NormalMode' (default)
  79.                                   will allow read or write access to the file
  80.                                   for one program only.
  81.      SetFileMode(ReadDenyNone);   Setting FileMode to 'ReadDenyNone' will allow
  82.                                   other programs to access the file for read
  83.                                   or for write while the file is open for read
  84.                                   purposes.
  85.      SetFileMode(WriteDenyNone);  Setting FileMode to 'WriteDenyNone' will
  86.                                   allow other programs to access the file for
  87.                                   read or for write purposes while the file is
  88.                                   open for write purposes.
  89.  
  90.      SetFileMode is used as in the following example...
  91.  
  92.      Uses
  93.        BCSHARE,
  94.        DOS;
  95.      TYPE
  96.        Example = Record
  97.                    ExStr : String;
  98.                  End;
  99.      VAR
  100.        EF   : File Of Example;
  101.        Exam : Example;
  102.  
  103.      Begin;
  104.        Assign(EF,'EXAMPLE.DAT');
  105.        SetFileMode(ReadDenyNone);
  106.        {$I-}Reset(EF);{$I+}
  107.        If IOResult<>0 Then Halt;
  108.        SetFileMode(NormalMode);
  109.        While Not EOF(EF) Do
  110.        Begin;
  111.          {$I-}Read(EF,Exam);{$I+}
  112.          If IOResult<>0 Then
  113.          Begin;
  114.            {$I-}Close(EF);{$I+}
  115.            If IOResult<>0 Then;
  116.            Halt;
  117.          End;
  118.          Writeln(Exam.ExStr);
  119.        End;
  120.        {$I-}Close(EF);{$I+}
  121.        If IOResult<>0 Then;
  122.      End.
  123.  
  124.      The above example demonstrates how simple BCSHARE makes it to utilize
  125.      non-text files in a file sharing manner.  Simply use SetFileMode to
  126.      set the file access mode (FileMode) before you 'Reset' or 'Rewrite' the
  127.      non-text file.  Please note that it is important to use SetFileMode to
  128.      set FileMode to default immediately after 'Reset' or 'Rewrite'.  You do
  129.      not have to use SetFileMode when working with text files, BCSHARE takes
  130.      care of that task for you.
  131.  
  132.      FILE LOCKING
  133.      ------------
  134.      In the event your program is opening and working with files in a file
  135.      sharing manner as described above, then it becomes important to lock
  136.      all or part of a file before writing to the file.  This locking is done
  137.      to keep a second program from accessing the same portion of the file that
  138.      your program is writing to.  In other words, if two programs attempted to
  139.      write to the same place in a file at the same time undetermined results
  140.      would occur.  BCSHARE provides a procedure to lock and unlock all or part
  141.      of a file.  This procedure is named LockFile.  LockFile must know the
  142.      DOS filehandle, the mode (lock or unlock), the starting point of the lock
  143.      or unlock and the number of bytes to lock or unlock.  The declared
  144.      procedure is as listed below...
  145.  
  146.      Procedure LockFile(Handle : Word; Mode : Byte; Start,Amount : LongInt);
  147.  
  148.      You will notice that the DOS filehandle, the mode (lock or unlock), the
  149.      starting point of the lock or unlock and the number of bytes to lock or
  150.      unlock are passed to the procedure.  The below example demonstrates 
  151.      locking and unlocking a portion of a file...
  152.  
  153.      Uses
  154.        BCSHARE,
  155.        DOS;
  156.      TYPE
  157.        Example = Record
  158.                    ExStr : String;
  159.                  End;
  160.      VAR
  161.        EF   : File Of Example;
  162.        Exam : Example;
  163.  
  164.      Begin;
  165.        Assign(EF,'EXAMPLE.DAT');
  166.        SetFileMode(WriteDenyNone);
  167.        {$I-}Reset(EF);{$I+}
  168.        If IOResult<>0 Then Halt;
  169.        SetFileMode(NormalMode);
  170.        Seek(EF,12);
  171.        Exam.ExStr:='Buffalo Creek Software';
  172.        With FileRec Do LockFile(Handle,Lock,12*RecSize,RecSize);
  173.        {$I-}Write(EF,Exam);{$I+}
  174.        With FileRec Do LockFile(Handle,UnLock,12*RecSize,RecSize);
  175.        If IOResult<>0 Then
  176.        Begin;
  177.          {$I-}Close(EF);{$I+}
  178.          If IOResult<>0 Then;
  179.          Halt;
  180.        End;
  181.        {$I-}Close(EF);{$I+}
  182.        If IOResult<>0 Then;
  183.      End.
  184.  
  185.      If you think that is simple then you are correct.  There is one rule
  186.      you must follow.  You must always unlock the identical portion of the
  187.      file that you locked before closing the file.  Failure to do so will
  188.      provide undetermined results.  NOTE: FileRec is a record type within
  189.      the Turbo Pascal DOS unit.  Handle and RecSize are variables of
  190.      FileRec.  Please refer to your Turbo Pascal manual for additional
  191.      information pertaining to the FileRec structure.  FileRec pertains
  192.      to non-text files while TextRec pertains to text files.
  193.  
  194.      The below example demonstrates locking the end of a text file for the
  195.      purpose of appending text to the file.  The entire file could be locked,
  196.      however, this example simply locks the portion to be written to...
  197.  
  198.      Uses
  199.        BCSHARE,
  200.        DOS;
  201.      VAR
  202.        TF      : Text;
  203.        Line    : String;
  204.        DirInfo : SearchRec;
  205.        IOError : Integer;
  206.  
  207.      Begin;
  208.        AssignTxtFile(TF,'BCSHARE.DOC');
  209.        {$I-}Append(TF);{$I+}
  210.        If IOResult<>0 Then Halt;
  211.        FindFirst('BCSHARE.DOC',Archive,DirInfo);
  212.        Line:='Buffalo Creek Software';
  213.        With TextRec(TF) Do LockFile(Handle,Lock,DirInfo.Size-1,2147483647);
  214.        {$I-}Writeln(TF,Line);{$I+}
  215.        IOError:=IOResult;
  216.        With TextRec(TF) Do LockFile(Handle,UnLock,DirInfo.Size-1,2147483647);
  217.        If IOError<>0 Then
  218.        Begin;
  219.          {$I-}Close(TF);{$I+}
  220.          If IOResult<>0 Then;
  221.          Halt;
  222.        End;
  223.        {$I-}Close(TF);{$I+}
  224.        If IOResult<>0 Then;
  225.      End.
  226.  
  227.      BCSHARE Beta Version 0.7 - Released 11-17-90 - Revision Notes
  228.  
  229.      All previous versions of BCSHARE did not return the corresponding
  230.      error code when using the REWRITE procedure (text file).  The correct
  231.      error code is now returned in IOResult.
  232.  
  233.      All previous versions of BCSHARE did not return the corresponding
  234.      error code when using the LOCKFILE procedure.  The correct error code
  235.      if now returned in the variable IO_Error.
  236.      
  237.  
  238.      Hopefully you will find BCSHARE useful to you.  Your comments and
  239.      suggestions for improvement are welcome.  All questions, comments and/or
  240.      suggestions regarding BCSHARE should be left in a message on
  241.      Buffalo Creek's BBS at 515-225-8496 * 38400/19200/9600/2400/1200.
  242.