File I/O and Extended Attributes

Extended Attributes

A more thorough discussion of EA API and a detailed discussion of the API structures for the FAT and HPFS can be found in the OS/2  Programming Guide and various other IBM technical publications. The short description offered here is merely for the benefit of the programming examples and to help the programmer understand the API syntax used to attain the EA information. Extended attributes will appear foreign to DOS users and programmers, and their usefulness generally is questioned almost immediately. Only upon closer inspection does it become evident that EAs are quite important and really constitute a must-have feature , especially in high-end operating systems such as OS/2. Basically the Extended Attributes are nothing more than a storage area of information no more than 64K in sire that are available for applications to use as  they please. OS/2 defines several standard types of EAs that are available for general use. Also, the programmer can define application-specific extended attributes. The only restriction is that the total EA size s cannot exceed 64K. Standard EAs are called SEAs, and by convention starts with a period [.]. They include:

.ASSOCTABLE
.CODEPAGE
.COMMENTS
.HISTORY
.ICON
.KEYPHRASES
.LONGNAME
.SUBJECT
.TYPE
.VERSION

EAs - Fragile: Handle with Care

The LIBPATH.C Example

LIBPATH.C
LIBPATH.MAK
LIBPATH.DEF

The first step is to find the system boot drive. In order to do this, use DosQuerySysInfo and specify the arguments corresponding to the boot drive information. DosQuerySysInfo takes three input parameters and one output parameter, and returns the values of the system's static variables:

 APIRET  DosQuerySysInfo (
  ULONG     uStartIndex; /* Ordinal of the first system variable to return. */
  ULONG     uLastIndex;  /* Ordinal of the last system variable to return. */
  PVOID     pDataBuf;    /* Address of the data buffer where the system returns the variable values. */
  ULONG     ulDataBufLen);/* Length, in bytes, of the data buffer. */
/* APIRET     Return Code. */

This call can return a single value or a range of values, depending on the ulSrartIndex, ulLastIndex. As is evident by the example, in order to obtain a single value, the ulStartIndex and ulLastIndex are set to the same input value:

arReturn = DosQuerySysInfo(
                 QSV_BOOT_DRIVE,
                 QSV_BOOT_DRIVE,
                 &ulDrive,
                 sizeof( ulDrive) );

Gotcha! An application that is intended to be used in the HPFS/FAT environment should make the DosQuerySysInfo call and determine the maximum value of the legal file name length: QSV_MAX_COMP_LENGTH. For HPFS, this value is much greater than FAT (255). The application should issue this call in its initialization section and remember the pertinent values for future DosFindFirst, DosFindNext  buffer sire allocation values.

Getting the File Size

 arReturn = DosQueryPathInfo(
                        pchFile,
                        FIL_STANDARD,
                        &fsStatus,
                        sizeof( fsStatus) );
pchBuffer = malloc (fsStatus.cbFile +1);

DosQueryPathInfo  is used to determine the size of CONFIG.SYS. The function is designed to get file information for a file or subdirectory. The first parameter, pchFile, is the fully qualified path for the file. The second parameter is the level of information required. All we need for this example is standard file information, FIL_STANDARD. The information level determines the third parameter. If FIL_STANDARD is specified, a pointer to a FILESTATUS3 structure is used. The structure looks like this:

  typedef struct _FILESTATUS3 {
   FDATE     fdateCreation;    /*  Date of file creation. */
   FTIME     ftimeCreation;    /*  Time of file creation. */
   FDATE     fdateLastAccess;  /*  Date of last access. */
   FTIME     ftimeLastAccess;  /*  Time of last access. */
   FDATE     fdateLastWrite;   /*  Date of last write. */
   FTIME     ftimeLastWrite;   /*  Time of last write. */
   ULONG     cbFile;           /*  File size (end of data). */
   ULONG     cbFileAlloc;      /*  File allocated size. */
   ULONG     attrFile;         /*  Attributes of the file. */
 } FILESTATUS3;

The FILESTATUS3 structure contains two fields of interest: cbFile and cbFileAlloc. The cbFiIe element contains the actual size of the file, start to finish, in bytes. The cbFileAlloc, on the other hand, contains the file size, based on system allocation unit (AU) size, whose value can be a multiple of 512, 2K, 4K, 8K, l6K,32K. and so on, depending on the type of magnetic media used. HPFS and diskettes use 512-byte AUs, while the FAT AU size depends on the volume size. cbFileAlloc is of minimal value in applications, and the cbFile value should be used to allocate the required storage. Thus, cbFile size value is used in the next call to allocate the memory buffer needed to read the whole CONFIG.SYS at once, plus an extra byte for a NULL character.

This memory allocation does not have to be performed. It is possible to read one character at a time and parse the output using a 1-byte storage area. The method used in CHKEA was used for ease of implementation as well as performance reasons. Reading the whole file is much quicker. (Since the CONFIG.SYS is generally smaller than 4K in size, it should easily fit into a single page of memory, which is the smallest allocation allowed in 32-bit OS/2.) The parsing can be achieved more rapidly as well. Memory operations are much quicker than storage disk I/O.
 

Opening a File

arReturn = DosOpen (
     pchFile,
     &hfFile,
     &ulAction,
     0,
     FILE_NORMAL,
     FILE_OPEN,
     OPEN_FLAGS_FAIL_ON_ERROR |
     OPEN_FLAGS_SEQUENTIAL |
     OPEN_SHARE_DENYNONE |
     OPEN_ACCESS_READONLY,
     NULL);

Reading a File

arReturn = DosRead(
     hfFile,
     pchBuffer,
     fsStatus.cbFile,
     &ulBytesRead);

Note: In DOS and OS/2 it is possible to get a good return code (arReturn = 0) and not have the DosRead/DosWrite  API complete as expected. It is a good idea to check for the return code first, then check for the BytesRead value and compare it with the expected number.

arReturn = DosClose(  hfFile );
printf( "\n%s\n", pchLibpath);
free(pchBuffer);