IG_ISIS_drv_run

Begin to invoke an ISIS pipe; initialize the run handle.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_ISIS_drv_run_start( HISISDRV hDriver, LPHISISDRVRUN lphRun );

Arguments:

Name	Type	Description
hDriver	HISISDRV	The handle of the head (first) driver in the ISIS pipe.
lphRun	LPHISISDRVRUN	A pointer to the handle of the "run" (zone data structure) which is used to refer to the run zone operation. IG_ISIS_drv_run_start initializes this pointer.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Supported Raster Image Formats:

Depends on the scanner driver.

Example:

The following example uses IG_ISIS_drv_run_start, IG_ISIS_drv_run_step, and IG_ISIS_drv_run_done in three nested loops to invoke an ISIS pipe that allows background reading or scanning:

	Copy Code
/* IG_ISIS_drv_run_start example / INT32 MyIG_ISIS_run_zone(HISISDRV hDriver, char FAR lpcBuffer, int iSize) { HISISDRVRUN hRun; AT_ERRCOUNT nErrCount; if (!(nErrCount = IG_ISIS_drv_run_start(hDriver, &hRun))) { while (nErrCount == IGE_SUCCESS) { if (want to cancel the scan) break; else nErrCount = IG_ISIS_drv_run_step(hRun, lpcBuffer, iSize, 0); printf("Read %d bytes at address %08lx\n", nErrCount, lpcBuffer); } } nErrCount = IG_ISIS_drv_run_done(hRun); return nErrCount; }

Copy Code

/* IG_ISIS_drv_run_start example */
INT32 MyIG_ISIS_run_zone(HISISDRV hDriver, char FAR *lpcBuffer, int iSize)
{
        HISISDRVRUN hRun;
        AT_ERRCOUNT nErrCount;
        if (!(nErrCount = IG_ISIS_drv_run_start(hDriver, &hRun))) {
                while (nErrCount == IGE_SUCCESS) {
                        if (want to cancel the scan)
                                break;
                        else
                                nErrCount = IG_ISIS_drv_run_step(hRun, lpcBuffer, iSize, 0);
                        printf("Read %d bytes at address %08lx\n",
                                        nErrCount, lpcBuffer);
                }
        }
        nErrCount = IG_ISIS_drv_run_done(hRun);
        return nErrCount;
}

Remarks:

IG_ISIS_drv_run_start initializes the run.

IG_ISIS_drv_run_start is the first step in transferring data through an ISIS pipe. The head (first) driver in the pipe responds by performing whatever its function may be (scanning, reading, writing, compression) and then passes its data to the next driver in the pipe. IG_ISIS_drv_run_start is the first of four separate functions that are used to scan a page. The other functions are IG_ISIS_drv_run_zone (which returns a pointer to the zone structure to allow setting output parameters if necessary), IG_ISIS_drv_run_step (which transfers a specified number of bytes from the page), and IG_ISIS_drv_run_done (which completes the IG_ISIS_drv_run... operation). For common ISIS operations not requiring special or concurrent processing, it is much more convenient and automatic to use the IG_ISIS_drv_run_zone function.

There are several cases in which you may want to use the four separate functions to invoke an ISIS pipe:

The data is coming from a source that is not a part of the ISIS pipe; that is, the head (first) driver in the ISIS pipe is not a data generator. In this case, the IG_ISIS_drv_run_zone function can be used to send data into the head driver of the ISIS pipe, even though the data originated outside the pipe.
The data needs to be broken into small chunks in cases when you do not want to receive the entire page at once. The IG_ISIS_drv_run_step function can be used to specify the size of each "step" of data transfer. (However, this can also be done with the IG_ISIS_drv_run_zone function.)
The operation needs to yield periodically, for example to give other applications a chance to use CPU cycles and to determine whether or not a Cancel Scan command has been received. This can be important, especially when using very slow scanners, such as color scanners that may take minutes to scan a page. It is possible for a scan to complete without calling the yield process once. IG_ISIS_drv_run_step guarantees that control is given to the application periodically. This turnover of control is suitable for status reporting, displaying a progress monitor, an so forth.

An ISIS pipe exists to transfer image data from one entity (scanner, file, memory) to another. IG_ISIS_drv_run_start begins a data transfer operation of a single zone (image area) through the pipe by setting up a "run" data structure and initializing a handle to it. The run handle is used to refer to a particular zone's data and all of its parameters from the time it enters the first driver of the ISIS pipe until it reaches the destination driver of the pipe. Once a run is complete and a single zone has been transferred, the entire process must be repeated to transfer another image.

The IG_ISIS_drv_run_start function is the first of four functions that when used together invoke an ISIS pipe that has previously been established. Invoking a pipe starts a scanning, reading, writing, compression, or other operation as defined by the drivers linked in the pipe.

A zone may be an entire page side, a subarea of the page, or one of multiple subareas that can be defined with certain scanner drivers. Typically, it is an entire page.

IG_ISIS_drv_run_start is one of the basic components of IG_ISIS_drv_run_zone.