C Programming - Data Files

Your C compiler library contains a low-level file function called sopen() that can be used to open a file in shared mode. Beginning with DOS 3.0, files could be opened in shared mode by loading a special program named SHARE.EXE. Shared mode, as the name implies, allows a file to be shared with other programs as well as your own. Using this function, you can allow other programs that are running to update the same file you are updating.

The sopen() function takes four parameters: a pointer to the filename you want to open, the operational mode you want to open the file in, the file sharing mode to use, and, if you are creating a file, the mode to create the file in. The second parameter of the sopen() function, usually referred to as the "operation flag" parameter, can have the following values assigned to it:

The third parameter of the sopen() function, usually referred to as the "sharing flag," can have the following values assigned to it:

If the sopen() function is successful, it returns a non-negative number that is the file's handle. If an error occurs, -1 is returned, and the global variable errno is set to one of the following values:

The following example shows how to open a file in shared mode:

#include <stdio.h>
#include <fcntl.h>
#include <sys\stat.h>
#include <io.h>
#include <share.h>
void main(void);
void main(void)
{
     int file_handle;
     /* Note that sopen() is not ANSI compliant */
     file_handle = sopen("C:\\DATA\\TEST.DAT", O_RDWR, SH_DENYNO);
     close(file_handle);
}

Whenever you are sharing a file's contents with other programs, you should be sure to use the standard C library function named locking() to lock a portion of your file when you are updating it.

By using the sopen() function, you can open a file in shared mode and explicitly deny reading and writing permissions to any other program but yours. This task is accomplished by using the SH_DENYWR shared flag to denote that your program is going to deny any writing or reading attempts by other programs. For example, the following snippet of code shows a file being opened in shared mode, denying access to all other files:

/* Note that the sopen() function is not ANSI compliant... */
fileHandle = sopen("C:\\DATA\\SETUP.DAT", O_RDWR, SH_DENYWR);

By issuing this statement, all other programs are denied access to the SETUP.DAT file. If another program were to try to open SETUP.DAT for reading or writing, it would receive an EACCES error code, denoting that access is denied to the file.

If your C compiler library comes with a function named locking() that can be used to lock and unlock portions of shared files.

The locking function takes three arguments: a handle to the shared file you are going to lock or unlock, the operation you want to perform on the file, and the number of bytes you want to lock. The file lock is placed relative to the current position of the file pointer, so if you are going to lock bytes located anywhere but at the beginning of the file, you need to reposition the file pointer by using the lseek() function.

The following example shows how a binary index file named SONGS.DAT can be locked and unlocked:

#include <stdio.h>
#include <io.h>
#include <fcntl.h>
#include <process.h>
#include <string.h>
#include <share.h>
#include <sys\locking.h>
void main(void);
void main(void)
{
     int file_handle, ret_code;
     char* song_name = "Six Months In A Leaky Boat";
     char rec_buffer[50];
     file_handle = sopen("C:\\DATA\\SONGS.DAT", O_RDWR, SH_DENYNO);
     /* Assuming a record size of 50 bytes, position the file
        pointer to the 10th record. */
     lseek(file_handle, 450, SEEK_SET);
     /* Lock the 50-byte record. */
     ret_code = locking(file_handle, LK_LOCK, 50);
     /* Write the data and close the file. */
     memset(rec_buffer, '\0', sizeof(rec_buffer));
     sprintf(rec_buffer, "%s", song_name);
     write(file_handle, rec_buffer, sizeof(rec_buffer));
     lseek(file_handle, 450, SEEK_SET);
     locking(file_handle, LK_UNLCK, 50);
     close(file_handle);
}

Notice that before the record is locked, the record pointer is positioned to the 10th record (450th byte) by using the lseek() function. Also notice that to write the record to the file, the record pointer has to be repositioned to the beginning of the record before unlocking the record.

When DOS encounters a critical error, it issues a call to interrupt 24, the critical error handler. Your C compiler library contains a function named harderr() that takes over the handling of calls to interrupt 24. The harderr() function takes one argument, a pointer to a function that is called if there is a hardware error.

Your user-defined hardware error-handling function is passed information regarding the specifics of the hardware error that occurred. In your function, you can display a user-defined message to avoid the ugly Abort, Retry, Fail message. This way, your program can elegantly handle such simple user errors as your not inserting the disk when prompted to do so.

When a hardware error is encountered and your function is called, you can either call the C library function hardretn() to return control to your application or call the C library function hardresume() to return control to DOS. Typically, disk errors can be trapped and your program can continue by using the hardresume() function. Other device errors, such as a bat FAT (file allocation table) error, are somewhat fatal, and your application should handle them by using the hardretn() function. Consider the following example, which uses the harderr() function to trap for critical errors and notifies the user when such an error occurs:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>
#include <ctype.h>
void main(void);
void far error_handler(unsigned, unsigned, unsigned far*);
void main(void)
{
     int file_handle, ret_code;
     /* Install the custom error-handling routine. */
     _harderr(error_handler);
     printf("\nEnsure that the A: drive is empty, \n");
     printf("then press any key.\n\n");
     getch();
     printf("Trying to write to the A: drive...\n\n");
     /* Attempt to access an empty A: drive... */
     ret_code = _dos_open("A:FILE.TMP", O_RDONLY, &file_handle);
     /* If the A: drive was empty, the error_handler() function was
        called. Notify the user of the result of that function. */
     switch (ret_code)
     {
          case 100: printf("Unknown device error!\n");
                    break;
          case 2:   printf("FILE.TMP was not found on drive A!\n");
                    break;
          case 0:   printf("FILE.TMP was found on drive A!\n");
                    break;
          default:  printf("Unknown error occurred!\n");
                    break;
     }
}
void far error_handler(unsigned device_error, unsigned error_val, 
                        unsigned far* device_header)
{
     long x;
     /* This condition will be true only if a nondisk error occurred. */
     if (device_error & 0x8000)
          _hardretn(100);
     /* Pause one second. */
     for (x=0; x<2000000; x++);
         /* Retry to access the drive. */
         _hardresume(_HARDERR_RETRY);
}

In this example, a custom hardware error handler is installed named error_handler(). When the program attempts to access the A: drive and no disk is found there, the error_handler() function is called. The error_handler() function first checks to ensure that the problem is a disk error. If the problem is not a disk error, it returns 100 by using the hardretn() function. Next, the program pauses for one second and issues a hardresume() call to retry accessing the A: drive.