Notes on record-oriented input/output

Record-oriented input/output, which is possible for SAM, ISAM and PAM files, is always binary input/output. In the case of record-oriented input/output using the ASCII variants of the input/output functions (see "C library functions that support ASCII encoding"), data is therefore not converted either when it is written or when it is read.

With the fopen/fopen64 or freopen/freopen64 functions, the file must always be opened in binary mode and with the parameter option "type=record".

With the creat/creat64 or freopen/freopen64 functions, the file must always be opened in binary mode and the specification of O_RECORD.

Input/output functions which read or write characters or strings (up to \n) cannot be used for record-oriented input/output.

Available input/output functions

The following functions are available for processing files with stream input/output:

creat/creat64, fopen/fopen64, freopen/freopen64, open/open64	Open
close, fclose	Close
fread, read	Read
fwrite, write	Write
fsetpos/fsetpos64	Positioning in the data stream
fgetpos/fgetpos64	Position in the data stream
fseek/fseek64, lseek/lseek64	Position at start/end of file
rewind	Position at start of file
flocate	Explicitly position in an ISAM file
fdelrec	Delete a record in an ISAM file

In addition, the following functions for file processing and error handling can be used unchanged:

feof, ferror, clearerr, unlink, remove, rename

Any input/output functions not listed here are not available for record-oriented input/output and are rejected with an error return value.
For performance reasons, however, no checks are carried out for the two macros getc and putc. The behavior is undefined if these macros are used on files with record-oriented input/output.

Processing a file for record-oriented and stream-oriented input/output

Files which have been created for record-oriented input/output can be opened for streamoriented input/output and vice versa. However, stream-oriented input/output does not support all the file attributes which are possible for record-oriented input/output.

FCB type of a new file to be created

The FCB type (FCBTYPE) of a new file to be created can be defined as follows:

• Specification in a ADD-FILE-LINK command and use of the LINK name in the fopen/fopen64 and freopen/freopen64 function

• Specification of the forg parameter in the fopen/fopen64 and
  freopen/freopen64 functions:

  "forg=seq": a SAM file is created
  "forg=key": an ISAM file is created.

The following restrictions apply to the FCBTYPE of a file and the entries for fopen/fopen64 and freopen/freopen64:

• For "type=record" the file must have FCBTYPE SAM, PAM or ISAM.

• For "forg=seq" the file must have FCBTYPE SAM or PAM.

• For "forg=key" the file must have FCBTYPE ISAM.

• Specifying the append mode "a" is not allowed for ISAM files. The position is determined by the key in the record.

The following restrictions apply to the FCBTYPE of a file and the entries for creat/creat64 and open/open64:

• If O_RECORD is specified the file must have FCBTYPE SAM, PAM or ISAM.

Multiple keys for ISAM files

By default, multiple keys are not permitted for ISAM files. They may, however, be used if DUP-KEY=Y is specified in a ADD-FILE-LINK command.

Example of record-oriented processing of an ISAM file

The following program creates and processes an ISAM file using record-oriented input/output.

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
main()
{
  FILE * isamfp;
  size_t ret=0;
  int    i,intret;
  char   buffer[200];
  char   buffer2[200];
  static char * texts[3] = {"1  Ritchie***, 9999, ZZ",
                            "2  Kernighan*, 8765",
                            "3  Stroustrup, 1234, C++"};
  static char isamlink[] = "ADD-FILE-LINK LINK=ISAMFILE,F-NAME=FILE.ISAM,"
                           "ACCESS-METHOD=ISAM(KEY-LEN=10,KEY-POS=4),"
                           "REC-FORM=FIXED(REC-SIZE=50)";
  static int maxtext = 3;
  fpos_t isampos;
  ret = system(isamlink);
  if (ret != 0)
  {
     printf("system(isamlink) error\n");
     exit(1);
  }
  isamfp = fopen("link=isamfile", "wb+,type=record,forg=key");
  if (isamfp == 0)
  {
     printf("Attempt to open isamfp has failed\n");
     exit(2);
  }
  /* Write 3 records to ISAM file */
  for (i=0; i<maxtext; i++)
  {
     ret = fwrite(texts[i], 1, strlen(texts[i]), isamfp);
     if (ret == 0)
     {
        printf("Error on writing to ISAM file\n");
        exit(3);
     }
   }
  /* Read records from beginning of file and write on standard output */
  rewind(isamfp);
  for (i=0; i<maxtext; i++)
  {
     ret = fread(buffer, 1, 100, isamfp);
     fwrite(buffer, 1, ret, stdout);
  }
  /* Position explicitly on basis of key value and start processing */
  flocate(isamfp, "Ritch", strlen("Ritch"), _KEY_GE);
  ret = fread(buffer, 1, 100, isamfp);    /*"Ritchie" has been read        */
  *(buffer+ret) = '\0';                   /* EOS at end of record          */
  printf("\nRecord read: %s\n", buffer);
  fgetpos(isamfp, &isampos);              /* Record position after         */
                                          /* record just read              */
  ret = fread(buffer, 1, 100, isamfp);    /*"Stroustrup" has been read     */
  *(buffer+ret) = '\0';                   /* EOS at end of record          */
  printf("Record read: %s\n", buffer);
  fsetpos(isamfp, &isampos);              /* Reset file position indicator */
  ret = fread(buffer2, 1, 100, isamfp);   /*"Stroustrup" is read again     */
  *(buffer2+ret) = '\0';                  /* EOS at end of record          */
  printf("Record read: %s\n", buffer2);
  intret = fdelrec(isamfp, "Kernighan*"); /* Delete a record               */
  if (intret == 0)
     printf("Kernighan deleted\n");
  intret = fdelrec(isamfp, "Kernighan*"); /* Attempt to delete a record    */
  if (intret > 0)                         /* that has already been deleted */
     printf("OK, this record no longer exists\n");
  else
     printf("Error, \"Kernighan*\" could be deleted twice\n");
  printf("******* END OF PROGRAM *******\n");
}