Five. Access method

There are two access methods provided by this library:

• Completion return type access
  Do not return control to the application until the access process is complete.

• Immediate return access
  Once the access request is accepted, control is returned immediately.

5.1 Completion return type access

Return-on-completion access is similar to the standard C library's file access functions.
A program example of completion return type access is shown below.

[example]

#define BUF_SIZE 2048

GfsHn gfs; /* file handle */
Sint32 fid; /* File identifier */
Sint32 nsct = 1; /* Number of read sectors */
Uint32 buf[BUF_SIZE/4]; /* Reading area */

gfs = GFS_Open(fid); /* File open */

GFS_Fread(gfs, nsct, buf, BUF_SIZE); /* Read nsct sector into buf */

GFS_Close(gfs); /* Close file */

5.2 Immediate return access

Immediate return access is achieved using request functions and server functions. The request function executes only the request acceptance process and returns immediately. The actual access processing is performed by repeatedly calling the server function while monitoring the input completion status. You can also perform application processing within a server function call loop. Once a request has been issued to a file handle, a request cannot be issued until the access process is completed.

(1) Immediate return type access to a single file

For single file access, GFS_NwExecOne is the server function.
An example of a program that accesses a single file with immediate return is shown below. In this example, GFS_NwFread is the request function.

example]

#define BUF_SIZE 2048*2

GfsHn gfs; /* file handle */
Sint32 nsct = 2; /* Number of read sectors */
Sint32 stat; /* Server status */
Uint32 buf[BUF_SIZE/4]; /* Reading area */

gfs = GFS_Open(fid); /* File open */
/* Request function */
GFS_NwFread(gfs, nsct, buf, BUF_SIZE); /* Read nsct sector into buf */
                                        /* Return immediately */

for (;;) {
     /* Server function */
     stat = GFS_NwExecOne(gfs); /* Execute reading */
     if (stat == GFS_SVR_COMPLETED) { /* Is loading complete? */
          break;
     }
     user(); /* Any user processing */
}

GFS_Close(gfs); /* Close file */

(2) Immediate return type access to multiple files

For continuous access of multiple files, GFS_NwExecSerer becomes the server function.
The request function is the same as accessing a single file.
An application issues access processing requests for multiple files. After that, access processing is executed sequentially by periodically passing control to the server. Access processing is performed one by one in the order in which requests are received.
The following is an example program that performs user processing while reading three files.

[example]

/* Number of sectors read from each file */
#define NSCT1 1
#define NSCT2 2
#define NSCT3 3

/* Size of data storage area for each file (unit: bytes) */
#define BSIZE1 2048*NSCT1
#define BSIZE2 2048*NSCT2
#define BSIZE3 2048*NSCT3


Sint32 fid1, fid2, fid3; /* File identifier for each file */
GfsHn gfs1, gfs2, gfs3; /* File handle for each file */
Uint32 buf1[BSIZE1/4]; /* Data storage area for each file */
Uint32 buf2[BSIZE2/4];
Uint32 buf3[BSIZE3/4];
GfsHn now_gfs; /* File handle being accessed */
Sint32 stat; /* Server status */

gfs1 = GFS_Open(fid1); /* File open */
gfs2 = GFS_Open(fid2);
gfs3 = GFS_Open(fid3);
GFS_NwFread(gfs1, NSCT1, buf1, BSIZE1); /* Start read operation */
GFS_NwFread(gfs2, NSCT2, buf2, BSIZE2);
GFS_NwFread(gfs3, NSCT3, buf3, BSIZE3);
for (;;) {
    stat = GFS_NwExecServer(&now_gfs); /* Execute reading */
    if (stat == GFS_SVR_COMPLETED) { /* No work to do? */
              break;
    }
    user(); /* Any user processing */
}
GFS_Close(gfs1);
GFS_Close(gfs2);
GFS_Close(gfs3);

(3) Read ahead to CD buffer

When reading large files successively little by little, you can take full advantage of the CD reading speed by specifying read ahead to the CD buffer with GFS_NwCdRead.
The example program shown below reads a 1000-sector file successively, 10 sectors at a time. Since GFS_NwCdRead specifies to read ahead 1000 sectors, 1000 sectors of the target file are played continuously and stored in the buffer. Since data is being extracted from the CD buffer in parallel with this process, the buffer will not become full and playback will not be interrupted.
If the processing in this example is performed without read-ahead, CD playback will be interrupted every 10 sectors, resulting in wasted time.

[example]

#define SECT_SIZE 2048
#define FILE_SECT 1000
#define FILE_SIZE (FILE_SECT*SECT_SIZE)
#define RD_UNIT 10

Uint8 *rd_bp, *proc_bp; /* Read buffer and processing buffer */
Uint32 buf1[RD_UNIT*SECT_SIZE/4]; /* Data storage area 1 */
Uint32 buf2[RD_UNIT*SECT_SIZE/4]; /* Data storage area 2 */
GfsHn gfs;
Sint32 i, stat, nbyte;

gfs = GFS_Open(fid);
GFS_NwCdRead(gfs, FILE_SECT); /* Pre-read instruction to CD buffer */
GFS_SetTransPara(gfs, RD_UNIT); /* Extract maximum RD_UNIT sectors at once */
for (i = 0; i< FILE_SECT / RD_UNIT; ++i) {
    /* Read and process buffer settings */
    if (i & 1) {
        rd_bp = buf1;
        proc_bp = buf2;
    } else {
        rd_bp = buf2;
        proc_bp = buf1;
    }
    /* Execute extraction from CD buffer */
    GFS_NwFread(gfs, RD_UNIT, rd_bp, RD_UNIT * SECT_SIZE);
    do {
        if (i & 0) {
            user_process(proc_bp); /* Processing the read data */
        } else {
            user_process0(); /* Processing before data is read */
        }
          GFS_NwExecOne(gfs);
          GFS_NwGetStat(gfs, &stat, &nbyte);
    }while (nbyte< RD_UNIT * SECT_SIZE);
}