DTWAIN_SetFileAutoIncrement

The DTWAIN_SetFileAutoIncrement allows image files to be named by incrementing a number field in the file name.

DTWAIN_SOURCE	Source,
LONG	Increment,
DTWAIN_BOOL	bResetAfterAcquire,
DTWAIN_BOOL	bEnable );

If the function succeeds, TRUE is returned. If the function fails FALSE is returned.

The DTWAIN_SetFileAutoIncrement controls the naming of image files when DTWAIN_AcquireFile or DTWAIN_AcquireFileEx is used to acquire images. When the auto increment mode is used, file names will be named according to the base file name, the page acquired, and the increment count.

The Source parameter is the DTWAIN_SOURCE that will use the auto-increment feature. The Increment is the increment value used.

The bResetAfterAcquire should be TRUE if the file naming will start from the base file name if more than one acquisition is attempted in a single session. For example, if your application shows the TWAIN Source's user interface during acquisition, and the user acquires all the pages, and without closing the user interface, places more paper into the feeder and acquires all the pages again, setting bResetAfterAcquire to FALSE ensures that the file names will be unique. If bResetAfterAcquire is TRUE, a new acquisition will always start naming the files from the base file name. The bResetAfterAcquire should be set to FALSE to ensure that multiple acquisitions do not result in files being overwritten.

Note: If the user closes the Twain user interface, your application is responsible for saving the files acquired. DTWAIN_SetFileAutoIncrement does not "remember" the files that were saved if the user closes the Twain user interface.

The bEnable parameter must be TRUE to turn on auto-increment mode, FALSE to turn off auto-increment mode. If bEnable is FALSE, then the file naming convention reverts to the standard naming convention described in DTWAIN_AcquireFile.

The DTWAIN_SetFileAutoIncrement function should be called prior to calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx.

If the name of the base file is FILE001.BMP, and 4 pages are acquired, and the increment is 1, the names of the files will be

If the increment is set to 2, and the base file name is FILE000.BMP, the names of the files generated will be

If the increment is set to -1, and the base file name is FILE999.BMP, the names of the files will be:

The base file name is the file name specified in the call to DTWAIN_AcquireFile or DTWAIN_AcquireFileEx. Since these functions have the ability to accept multiple file names, if the auto-increment is on, only the first name in the list of names is considered.

The file name should consist of a numeric suffix. The number of digits in the suffix determines the maximum number of pages that can be acquired without overwriting the files that have already been generated. For example, a base file name of FILE0000.BMP will be able to acquire up to 10,000 pages in a single acquisition without overwriting previous files, since numbers 0000 to 9999 can be generated. If the number of pages exceeds the number of unique file names that can be generated with the numeric suffix, DTWAIN does not check for file overwrites. Therefore, you must make sure that the numeric suffix used in the file name is large enough to hold all of the pages that are planned to be acquired.

If the file name does not contain a numeric suffix, the naming convention in auto-increment mode is to append a number to the end of the file name. The number always starts at 0 up to the total number of pages acquired. For example, if the base name is FILEABC.BMP, and 4 pages are acquired, the following will be the names of the files:

Using the non-numeric suffix ensures that you will get unique file names, regardless of the number of pages, however you cannot control the increment step or the starting number in the file name.

To turn off the auto-increment mode, call DTWAIN_SetFileAutoIncrement with the bEnable parameter set to FALSE.

The above example will generate files named FILE000.BMP, FILE001.BMP, FILE002.BMP, etc. for pages being acquired. A maximum of 1,000 pages with unique file names can be acquired since "FILE000.BMP" can generate names from FILE000.BMP to FILE999.BMP.

The above example will generate files named FILE005.BMP, FILE007.BMP, FILE009.BMP, FILE011.BMP, etc.in a single acquisition. If the user decides to start another acquisition without closing the Twain user interface, the file names will continue from the last name generated (this is because of the bResetOnAcquire flag being set to FALSE in the call to DTWAIN_SetFileAutoIncrement).