Updated May 2016; see History

xcall AUI, AUI_IMAGE, IMGOP_ACQUIRE, handle, status, filespec, attribs {,appname, pages, scanflags, pagesize}

IMGOP_ACQUIRE invokes a TWAIN "Acquire" to retrieve an image from the default TWAIN input device (aka "Data Source"). In the most common case, which involves scanners, this is equivalent to "scan-and-save-image". Manufacturers of image input devices such as scanners typically provide a TWAIN driver and user interface which allows the user to access the functionality of the device. This way, the application does not need to know any details about the device (such as what kinds of controls and options it has). It just knows that once the Acquire operation is started, it will return with a file (if successful) or an error code (if not).

IMGOP_ACQUIRE provides support for scanning multiple pages; see the following topic, Multi-Page Scanning, for more information.

Parameters

handle  (Num)  [in]

is not used here, is included only for conformity with the other opcodes.

status  (Num)  [out]

returns 0 for success, else an error; see Status Codes.

filespec

is the specification of the file (AMOS or native format) to store the image in. The extension you specify will determine the image format and must be one of the file types listed in the comp following table (e.g. test.jpg or dsk9:test.bmp[100,20]).

attribs  [in]

defines various attributes for the scan, mapped as shown below.

map1 attribs,b,4            ! compress, pixel type, resolution attributes

map1 attribsx,@attribs      ! overlay to break out fields

   map2 comp,b,1            ! compression options; see below)

   map2 pixtype,b,1         ! pixel type: (see below)

   map2 resx,b,1            ! x resolution (in multiples of 25 DPI)

   map2 resy,b,1            ! y resolution (in multiples of 25 DIP)

comp  [in]

is a compression-related factor determined by the image type:

pixtype  [in]

The pixtype options are shown in the following table. The first three of these are standard for most scanners, the others are somewhat exotic and may not be supported.

resx, resy  [in]

these fields are scaled to multiples of 25 DPI (i.e. 12=300 DPI), in order to fit a reasonable range of possible resolutions in 8 bits.

For each of the pixtype, resx, and resy fields, 0 is interpreted as no change to the existing or default settings. So existing programs that pass only the old comp value will continue to work as before.

Note that for many scanners, setting the pixel type and resolution options may not have an effect unless the IMGSF_HIDEUI flag is set in the scanflags parameter. That is, displaying the scanner's user interface may override the application settings with the scanner's own previously saved settings.

appname  (String)  [in]

is an optional string containing the name of your application, which, depending on the particular TWAIN driver, may be displayed in the title bar of the device’s user interface window.

pages  (Num)  [in/out]

specifies the desired (or maximum) number of pages to scan. On return, it will contain the actual number scanned.

scanflags  (Num)  [in]

specifies flags (defined in ashell.def) affecting the scanning operation:

pagesize  (Num)  [in]

sets pagesize. Options are defined in the ASHINC:ashell.def file, the most common options being: TWSS_A4LETTER = 1, TWSS_USLETTER = 3, TWSS_USLEGAL  = 4

Comments

Note that the acquisition (scanning) of the image data is independent of the saving of the image file, so it is up to you to specify an image format (via the file extension) that is compatible with the type of scan. (Or conversely, for the scanning operator to select options compatible with the file format.) For example, PCX only supports 1 and 8 bit data, so a 24-bit scan will result in an error while attempting to save the file.

See the program IMAGE.BP in EXLIB:[908,32] for an example of using the pages and scanflags parameters.

History

2016 April, A-Shell 6.3.1512:  Add ability to set the page size via the pagesize parameter.

2016 April, A-Shell 6.3.1510: Old comp parameter redefined as attribs. Note that existing/older programs which simply use the comp parameter remain upward compatible with the attribs interpretation; the layout above guarantees that the comp value is interpreted the same either way, and the other fields would just be considered zero, meaning use the current defaults.

2016 April, A-Shell 6.3.1510: the IMGSF_HIDEUI option in the scanflags parameter now works in single-page scanning mode. Previously single page scans (pages=1) always displayed the scanner's user interface regardless of the scanflags.

2012 June, A-Shell 6.2.1306:  Add support for multi-page scanning via the pages and scanflags parameters.