IMAGESAFE WINDOWS API SPECIFICATIONS PROGRAMMING REFERENCE MANUAL MANUAL PART NUMBER 99875500-4 APRIL 2012 REGISTERED TO ISO 9001:2008 1710 Apollo Court Seal Beach, CA 90740 Phone: (562) 546-6400 Technical Support: (651) 415-6800 www.magtek.
Copyright© 2004 – 2012 MagTek®, Inc. Printed in the United States of America Information in this document is subject to change without notice. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of MagTek, Inc. MagTek is a registered trademark of MagTek, Inc. ImageSafeTM is a trademark of MagTek, Inc. Microsoft® is a trademark of Microsoft, Inc. REVISIONS ii Rev Number 1.01 2.
SOFTWARE LICENSE AGREEMENT IMPORTANT: YOU SHOULD CAREFULLY READ ALL THE TERMS, CONDITIONS AND RESTRICTIONS OF THIS LICENSE AGREEMENT BEFORE INSTALLING THE SOFTWARE PACKAGE. YOUR INSTALLATION OF THE SOFTWARE PACKAGE PRESUMES YOUR ACCEPTANCE OF THE TERMS, CONDITIONS, AND RESTRICTIONS CONTAINED IN THIS AGREEMENT. IF YOU DO NOT AGREE WITH THESE TERMS, CONDITIONS, AND RESTRICTIONS, PROMPTLY RETURN THE SOFTWARE PACKAGE AND ASSOCIATED DOCUMENTATION TO THE ABOVE ADDRESS, ATTENTION: CUSTOMER SUPPORT.
TABLE OF CONTENTS SECTION 1. OVERVIEW ............................................................................................................................. 1 REQUIREMENTS ..................................................................................................................................... 1 SECTION 2. IMAGESAFE SOFTWARE ARCHITECTURE ........................................................................ 3 API FUNCTIONS..................................................................
MTMICRGetImage .................................................................................................................................. 20 Parameters .......................................................................................................................................... 20 Return Values ....................................................................................................................................... 20 Remarks .................................................
Return Values....................................................................................................................................... 38 Example ............................................................................................................................................... 38 Remark ................................................................................................................................................ 38 SECTION 4. COMMANDS SENT TO DEVICE ...............
MICRDecode ........................................................................................................................................ 56 MICREPC .............................................................................................................................................. 56 MICROnUs ............................................................................................................................................ 57 MICROut ..............................................
EXAMPLE 3: DEVICE CAPABILITIES REPORTED BY EXCELLA DEVICE ........................................75 EXAMPLE 4: DEVICE USAGE REPORTED BY EXCELLA DEVICE ...................................................77 APPENDIX A. FORMAT LIST ................................................................................................................... 79 APPENDIX B. ERROR CODES AND MESSAGES .................................................................................. 97 APPENDIX C.
SECTION 1. OVERVIEW The sections of this manual are as follows: Section 1. Section 2. Overview ImageSafe Software Architecture – includes flow diagrams, screen captures, and several “How To” descriptions. Section 3. ImageSafe API – describes ImageSafe device API functions and return codes. Section 4. Commands Sent To Device – describes commands sent by the application to the ImageSafe device. Section 5. Keys Sent to Device – lists and explains keys sent to the ImageSafe device by the application.
ImageSafe Windows API Specifications 2
SECTION 2. IMAGESAFE SOFTWARE ARCHITECTURE API FUNCTIONS Table 2-1 lists functions provided by MTXMLMCR.dll. Please refer to Section 3 for a complete description of these functions. Table 2-1. Functions NAME DESCRIPTION PAGE 7 MTMICRGetDevice MTMICROpenDevice Get device name of all devices present. Opens device with the given name. MTMICRCloseDevice Closes device with the given name. 9 MTMICRSetValue Adds a key/value pair to a given section.
ImageSafe Windows API Specifications SOFTWARE FLOW FOR CHECK PROCESSING Figure 2-4 illustrates the sequence of check processing. Excella Present Yes Successful Open Device Yes Select desired options for check processing Send options to device Modify options Yes Want new option? Continue? No Close Device Figure 2-1.
Section 2. ImageSafe Software Architecture HOW TO PROCESS DOCUMENT USING IMAGESAFE API To process document, follow these steps: 1. Find the attached ImageSafe device by calling function MTMICRGetDevice. 2. Use function MTMICROpenDevice to open the device. 3. ImageSafe is now ready to accept the XML options using function MTMICRProcessCheck. For every document that is processed, a set of options must be sent to the device. These options define how the document will be processed, i.e.
ImageSafe Windows API Specifications HOW TO GET CHECK IMAGES To get a check image, follow these steps: 1. The function MTMICRProcessCheck contains information of the process operation provided by ImageSafe device after it completes document processing. Use this information to find the information of the scanned images in the ImageInfo section. The ImageInfo section contains the size of the image and the image identification for each image. 2.
SECTION 3. IMAGESAFE API MTMICRGetDevice MTMICRGetDevice function returns the device name of the device present in the system. ULONG MTMICRGetDevice ( DWORD dwDeviceContext, char *pcDevName ); Parameters dwDeviceContext This is the device number of the device. This must be set to 1 to get the first device in the system. Increment it by 1 to get the next device name. pcDevName Pointer to the buffer where the device name will be stored.
ImageSafe Windows API Specifications MTMICROpenDevice MTMICROpenDevice function opens the device with the given device name. ULONG MTMICROpenDevice ( char *pcDevName ); Parameters pcDevName Pointer to null terminated string that specifies the name of the device to open. Use function MTMICRGetDevice to obtain the device name. Return Values If the function succeeds, the return value is MICR_ST_OK.
.................................................................................................................... Section 3. ImageSafe API MTMICRCloseDevice MTMICRCloseDevice function closes the device with the given device name. ULONG MTMICRCloseDevice ( char *pcDevName ); Parameters pcDevName Pointer to null terminated string containing the name of the device to close. This is the device that is previously opened using function MTMICROpenDevice.
ImageSafe Windows API Specifications MTMICRSETVALUE MTMICRSetValue function adds a key/value pair to the given device settings specified in pcOptions buffer and in a given section specified in pcSection buffer. ULONG MTMICRSetValue ( char char char char DWORD *pcOptions, *pcSection, *pcKey, *pcValue, *pdwLength ); Parameters pcOptions Pointer to null terminated string containing all key/value pairs. pcSection Pointer to null terminated string containing the section name.
.................................................................................................................... Section 3.
ImageSafe Windows API Specifications Remarks The function returns MICR_ST_NOT_ENOUGH_MEMORY, if the memory allocated for pcOptions buffer is not big enough to store the additional key/value pair. The required size for the buffer is returned in pdwLength; The minimum size of the buffer should be equal to MTMICR_OPTIONS_BUFFER_SIZE. The MTMICRSetIndexValue function saves the new key/value pair in the pcOptions buffer only. This function does not send the new key/value pair to the device.
.................................................................................................................... Section 3. ImageSafe API MICR_ST_OK MICR_ST_NOT_ENOUGH_MEMORY MICR_ST_ERR_LOAD_XML MICR_ST_ERR_GET_DOM_POINTER MICR_ST_BAD_DATA MICR_ST_BAD_SECTION_NAME MICR_ST_BAD_KEY_NAME MICR_ST_BAD_VALUE_BUFFER MICR_ST_BAD_BUFFER_LENGTH MICR_ST_KEY_NOT_FOUND Remarks MTMICRGetValue finds the key in the pcDocInfo buffer then returns its value in the pcValue.
ImageSafe Windows API Specifications MTMICRGetIndexValue MTMICRGetIndexValue function retrieves a key/value pair that was previously stored in the pcDocInfo parameter. MTMICRGetIndexValue function is similar to the function MTMICRGetValue. MTMICRGetIndexValue function adds index to the key name before searching for the value of the key name pcKey in the pcDocInfo.
.................................................................................................................... Section 3. ImageSafe API Example char Settings [4096]; char DocInfo [4096]; char device[4096] =""; DWORD SettingsBufferSize; DWORD DocInfoSize; char cValue [1024]; DWORD valueSize; DWORD dwStatus; // Intialize Settings DocInfoSize = 4096; // Use function MTMICRGetDevice to get device name for variable “device” // Call MTMICRProcessCheck function to process a document.
ImageSafe Windows API Specifications Parameters pcDevName Pointer to null terminated string containing device name. pcSection Pointer to null terminated string containing the section name. e.g. DeviceCapabilities, DeviceUsage, DeviceStatus, etc. pcSectionData Pointer to the buffer that is used to store the data of the inquiry section. pdwLength Specifies the size of the pcSectionData buffer.
.................................................................................................................... Section 3. ImageSafe API MTMICRSendCommand MTMICRSendCommand function is used to send a single command to the device. ULONG MTMICRSendCommand ( char *pcDevName, char *pcCommand, char *pcResult, DWORD *pdwLength ); Parameters pcDevName Pointer to null terminated string containing device name. pcCommand Pointer to null terminated string containing the command string.
ImageSafe Windows API Specifications Example char szResult [4096]; char szDeviceName[4096]; char Buffer[256]; DWORD dwBufferLength ; DWORD dwStatus; szDeviceName = “Excella”; // assuming this device has been opened dwBufferLength = 4096; if (MTMICRSendCommand(szDeviceName, "ClearPathEntry", szResult , & dwBufferLength)== MICR_ST_OK) { dwBufferLength = 256; dwStatus = MTMICRGetValue(szResult, SECTION_COMMAND_STATUS,"ReturnCode", Buffer, & dwBufferLength); if (dwStatus == MICR_ST_OK) { dwStatus = atol (Buffe
.................................................................................................................... Section 3.
ImageSafe Windows API Specifications MTMICRGetImage MTMICRGetImage function sends to the given device name a request for image data results from a previously scan. ULONG MTMICRGetImage ( char *pcDevName, char *pcImageID, char *pcBuffer, DWORD *pdwLength ); Parameters pcDevName Pointer to null terminated string containing device name. pcImageID the identification of the requested image pcBuffer Pointer to buffer for storing the image data. pdwLength Specifies the size of the pcBuffer.
.................................................................................................................... Section 3. ImageSafe API Remarks If the function succeeds, MICR_ST_OK is returned. If the requested image is not found, MICR_ST_IMAGE_NOT_FOUND is returned. If the device fails to respond to the command, the return value is MICR_ST_DEVICE_NOT_RESPONDING. If the size of the buffer uses to store the image is not large enough, MICR_ST_NOT_ENOUGH_MEMORY is returned.
ImageSafe Windows API Specifications MTMICRGetImages MTMICRGetImages is similar to MTMICRGetImage except MTMICRGetImages can get multiple images in one function call. ULONG MTMICRGetImages ( char *pcDevName, GET_IMAGE *pGetImage, DWORD dwTotalImages ); Parameters pcDevName Pointer to null terminated string containing device name. pGetImage Pointer to a list of GET_IMAGE structures containing the image information.
.................................................................................................................... Section 3.
ImageSafe Windows API Specifications Example #define BUFFER_LEN 512 // DocInfo is returned by the MTMICRProcessCheck() #define BUFFER_LEN 4096 GET_IMAGE getImages [4]; DWORD dwSize = BUFFER_LEN; char szData [BUFFER_LEN]; DWORD dwStatus; for (int i = 1; i < 5; i++) { // Get the image size for image number i dwStatus = MTMICRGetIndexValue (DocInfo, ”Image Info”, ”Image Size”, i, szData, & dwSize); if (dwStatus == MICR_ST_OK) { // Convert the size to integer dwSize = atol (szData); if (dwSize < = 0) continue;
.................................................................................................................... Section 3. ImageSafe API Parameters pcData Pointer to null terminated string containing a set of key/value pairs. pdwSectionCount When the function returns, this variable contains the number of sections present in the pcData.
ImageSafe Windows API Specifications MTMICRGetSectionName MTMICRGetSectionName function returns the name of the section which has the section number given in variable dwSectionNumber. MTMICRGetSectionName parses through the buffer pcData containing a set of key/value pairs which was previously stored in the buffer by using function MTMICRSetValue or function MTMICRSetIndexValue.
.................................................................................................................... Section 3. ImageSafe API Example char Settings [4096]; char DocInfo [4096]; char device[4096] =""; DWORD SettingsBufferSize; DWORD DocInfoSize; char cValue [1024]; DWORD valueSize; DWORD dwStatus; // Intialize Settings DocInfoSize = 4096; // Use function MTMICRGetDevice to get device name for variable “device” // Call MTMICRProcessCheck function to process a document.
ImageSafe Windows API Specifications Parameters pcData Pointer to null terminated string containing a set of key/value pairs. pcSection Pointer to null terminated string containing the section name. pdwKeyCount When the function returns, this variable contains the number of keys under the section name pcSection present in the pcData.
.................................................................................................................... Section 3. ImageSafe API Example char Settings [4096]; char DocInfo [4096]; char device[4096] =""; DWORD SettingsBufferSize; DWORD DocInfoSize; char cValue [1024]; DWORD valueSize; DWORD dwStatus; // Intialize Settings DocInfoSize = 4096; // Use function MTMICRGetDevice to get device name for variable “device” // Call MTMICRProcessCheck function to process a document.
ImageSafe Windows API Specifications MTMICRGetKeyName MTMICRGetKeyName function returns the name of the key which has the key index number given in variable dwKeyNumber and belongs to the section group with the section name specified in variable pcSection. MTMICRGetKeyName parses through the buffer pcSettings containing a set of key/value pairs which was previously stored in the buffer by using function MTMICRSetValue or function MTMICRSetIndexValue.
.................................................................................................................... Section 3. ImageSafe API Remarks If the function succeeds MICR_ST_OK is returned. If pcSettings is NULL, MICR_ST_BAD_DATA is returned. If data in pcSettings string is not in XML format, MICR_ST_ERR_LOAD_XML is returned.
ImageSafe Windows API Specifications MTMICRSetTimeout MTMICRSetTimeout function sets a duration for timeout in case there is a communication problem with the ImageSafe device. MTMICRProcessCheck, MTMICRGetImage, MTMICRGetImages, and MTMICRQueryInfo functions use this timeout value to wait for the device to respond. This timeout should be greater than the total time required to wait for a check feed, check movement along the path, and image processing. A recommended time is 30 seconds.
.................................................................................................................... Section 3. ImageSafe API MTMICRGetTimeout MTMICRGetTimeout function returns the set timeout in milliseconds. MTMICRProcessCheck, MTMICRGetImage, MTMICRGetImages, and MTMICRQueryInfo functions use this timeout value to wait for device to respond. By default the timeout is 5 seconds. ULONG MTMICRGetTimeout ( DWORD *pdwMilliSeconds ); Parameters pdwMilliSeconds Pointer to a DWORD.
ImageSafe Windows API Specifications MTMICRLogEnable MTMICRLogEnable enable or disable the logging. If there is a desire to get a log file of all messages and errors, a valid log file handle must be set with function MTMICRSetLogFileHandle and also a TRUE value is set for parameter of function MTMICRLogEnable. By default, logging is disable. void MTMICRLogEnable ( BOOL bEnable ); Parameters bEnable a Boolean value indicates logging enabling or disabling request.
.................................................................................................................... Section 3.
ImageSafe Windows API Specifications Return Values No value is returned from this function. Example MTMICRSetLogLevel(DBGLOG_DLL_INTERNAL | DBGLOG_DLL_XMLDATA); Remarks If DLL_INTERNAL level is set, errors from API functions listed in file MTXMLMCR.h are logged. If DLL_EXTERNAL level is set, errors from DLL functions which are not listed in MTXMLMCR.h are logged.
.................................................................................................................... Section 3. ImageSafe API MTMICRCOMUnInitialize MTMICRCOMInitialize indirectly executed the function CoUninitialize(). By default, CoUninitialize() is executed when MTXMLMCR.DLL is unloaded. VOID MTMICRCOMUnInitialize ( void ); Parameters NONE Return Values No value is returned from this function.
ImageSafe Windows API Specifications MTMICRSetConfigFile MTMICRSetConfigFile function sets the path and file name of the API configuration file. Default filename is "MICRDEV.INI". VOID MTMICRSetConfigFile ( LPSTR lpszFile ); Parameters lpszFile Null terminated string containing full path to the configuration file. Return Values NONE Example MTMICRSetConfigFile(“c:\myconfig.txt”); Remark The file must be verified to be accessible before calling this function.
SECTION 4. COMMANDS SENT TO DEVICE Section 4 describes device commands that can be sent to the MagneSafe Reader MTMICRSendCommand (see Section 3). The MagneSafe Reader reply will include the CommandStatus and/or DeviceStatus sections (and their corresponding Key-Value pairs) as described in later chapters.
SECTION 5. KEYS SENT TO DEVICE Section 5 describes all the Sections (and their corresponding Key-Value pairs) to be sent by the application to the device for document processing. The application can send information the device using the following sections: Application, ProcessOptions, Endorser, and ImageOptions.
ImageSafe Windows API Specifications SECTION = Application The Application section includes keys to configure some required characteristics of the unit. Transfer This key determines the file transfer method. Values HTTP FTP Value Description Default: Transfer files using HTTP protocol Transfer files to FTP server DocUnits This key determines the unit of measurement.
Section 5. Keys Sent to Device DocFeed This key determines the input tray to be used for document processing. Values ALL MANUAL ID MSR Value Description Auto-detect & process both check and Magstripe card Process checks from the check entry Process ID card from card input tray. Process Magstripe card from MSR. DocFeedTimeout This key specifies the waiting period for a document to be fed.
ImageSafe Windows API Specifications INTFONT1 INTFONT2 Selects internal Font 1 (5x7 bitmap) Selects internal Font 2 (7x10 bitmap) PrintFrontFont This key determines the internal font to be used for the franking message. Values INTFONT1 INTFONT2 Value Description Selects internal Font 1 (5x7 bitmap) Selects internal Font 2 (7x10 bitmap) PrintStyle This key determines the style of the selected font for the endorsement message.
Section 5. Keys Sent to Device SECTION = ImageOptions The ImageOptions section includes keys that control various options to process the check images. Some of the keys below include the symbol ‘#’ to indicate a variable for the image number. The image number can be 1, 2, 3, or 4 (as specified in the Number key). Each image requires its own set of options controlled by the keys ImageColor#, Resolution#, Compression#, FileType#, and ImageSide#.
ImageSafe Windows API Specifications ImageSide# This key determines which side of the check will be associated with specified image number. Values FRONT BACK Value Description Scan the front of image of the check Scan the back image of the check FilterB This key can be used to change the sharpness and the file size of a black and white (B/W) image. The Default value of this key is 4. For a sharper image, set the value of this key to a smaller number.
Section 5. Keys Sent to Device SECTION = MICROptions The MICROptions section includes keys that control various options to get MICR character. Threshold This value is the minimum signal value used to detect the start of a MICR symbol. Values numeric value Value Description The minimum signal value to detect the start of a MICR symbol. The default value is 15 Quality This value is used to determine what quality is required for a character to be valid. The best range is 85-92.
SECTION 6. KEYS RECEIVED FROM DEVICE Section 6 describes all the Sections (and their corresponding Key-Value pairs) automatically reported by the device to the application after the requested document has been processed. The device reports information using the following sections: CommandStatus, DocInfo, ImageInfo, and MSRInfo. Note All Sections and Key-Value pairs described in this Section are also available from the device upon query by the application.
ImageSafe Windows API Specifications The following keys are included in the ImageInfo section: • ImageSize# • ImageURL# • ImageSHA1Key# • Number The following keys are included in the MSRInfo section: • CardType • MPData • MPStatus • TrackData1 • TrackData2 • TrackData3 • TrackStatus1 • TrackStatus2 • TrackStatus3 • EncryptedTrackData1 • EncryptedTrackData2 • EncryptedTrackData3 • DeviceSerialNumber • EncryptedSessionID • DUKPTserialnumber 50
Section 6. Keys Received From Device SECTION = CommandStatus This CommandStatus section includes keys that report various error conditions after a document has been processed. CheckDS This key is a general flag for critical device status, and it can be used to prompt applications to check the device status.
ImageSafe Windows API Specifications ResponseType This key is a general flag for data response type. It can be used to prompt the application to send next command. Values CHECK MSR ID NONE Value Description The response data include MICR and Image info The response data include MSR data or MagneSafe Reader reply info The response data include ID info Only command response RETURN CODES AND MESSAGES FROM IMAGESAFE The following tables (Tables 6-1 through 6-8.
Section 6. Keys Received From Device Table 6-4. Path Path (200-299) ReturnCode 201 202 203 204 205 206 207 208 209 210 250 ReturnMsg “Access Guide Unlatched” “No Doc Present” “Path Not Clear” “Document Jammed” “Multiple doc feed detected” “Manual detect during Autofeed” “Illegal Doc Feed Option” "Cannot find doc at location for this sequence move" "Check Sequence Aborted by Operator" "Doc Feed Path Error" “Timed out waiting for document” Table 6-5.
ImageSafe Windows API Specifications Table 6-7. Scan/Image ReturnCode 401 402 403 404 405 421 422 423 424 425 426 427 428 429 430 431 432 433 434 440 Scan/Image (400-499) ReturnMessage “Scan Failed.
Section 6. Keys Received From Device SECTION = DocInfo The DocInfo section includes keys that report on various attributes of the check document and information on the MICR data read from the check. DocUnits This key specifies the units of measurement used to report on check document dimensions (see the DocWidth and DocHeight keys below).
ImageSafe Windows API Specifications MICRAmt This key specifies the amount MICR field read from the check. Values string Value Description Amount MICR field MICRAux This key specifies the Auxiliary On-Us MICR field read from the check. Values string Value Description Auxiliary On-Us MICR field MICRBankNum This key specifies the 4-digit ABA Identifier MICR field read from the check.
Section 6. Keys Received From Device MICROnUs This key specifies the On-Us MICR field read from the check. Values string Value Description On-Us MICR field MICROut This key specifies the formatted MICR output data read from the check as defined by the MICRFmtCode key in Section=ProcessOptions. Values string Value Description Formatted MICR output data MICRSerNum This key specifies the sequence number MICR field read from the check.
ImageSafe Windows API Specifications MICRParseSts0 This key specifies a 4-digit status/error code reported by the device after parsing the MICR fields read from the check. Values numeric value Value Description For specific status/error code information refer to table 6-9 Table 6-9.
Section 6. Keys Received From Device MICRParseSts1 This key specifies a 2-digit status/error code reported by the device after parsing the MICR fields read from the check. Values numeric value Value Description For specific status/error code information refer to table 6-10 Table 6-10.
ImageSafe Windows API Specifications SECTION = ImageInfo The ImageInfo section includes keys that report on various attributes of the scanned images. Some of the keys below include the symbol ‘#’ to indicate a variable for the image number. The image number can be 1, 2, 3, or 4 (up to 4 images as specified in the Number key below). The device reports image information using the keys ImageSize#, ImageURL#, and ImageSHA1#.
Section 6. Keys Received From Device SECTION = MSRInfo The MSRInfo section includes keys that report on the information captured from the magnetic stripe card. CardType This key specifies the standard encoding format detected on the magnetic stripe card. Values NONE ISO CADL AAMVA Value Description Unknown Card Type ISO format Old California Drive License format American Association Motor Vehicle Administrators format MPData This key specifies the MagnePrint data read from the magnetic stripe card.
ImageSafe Windows API Specifications TrackStatus2 This key indicates whether a decode/read error was detected while reading Track 2. Values NONE OK ERROR Value Description No status No read error detected Read error detected TrackStatus3 This key indicates whether a decode/read error was detected while reading Track 3.
Section 6. Keys Received From Device DUKPTserialnumber This key specifies the DUKPT serial number from MagneSafe Reader.
SECTION 7. OTHER KEYS AVAILABLE FROM DEVICE Section 7 describes other Sections (and their corresponding key-value pairs) available from the device upon query by the application. The device can report these additional sections: DeviceUsage, DeviceCapabilities and DeviceStatus,.
ImageSafe Windows API Specifications SECTION = DeviceCapabilities The DeviceCapabilities section includes keys that report on the general capabilities of the device. AutoFeed This key indicates whether an auto-feed input tray is available on the device. Values T F Value Description True: auto-feed input tray is available False: auto-feed input tray is NOT available IDScan This key indicates whether the device is capable ID scanning ID cards.
Section 7. Other Keys Available from Device Image This key indicates what check scanning capabilities are available on the device. Values BOTH FRONT BACK NONE Value Description The device scans the front and back images of the check The device can only scan the front image of the check The device can only scan the back image of the check The device cannot scan any images MICR This key indicates whether the device is capable if reading MICR data.
ImageSafe Windows API Specifications SECTION = DeviceStatus The DeviceStatus section includes keys that report general operational status of the device. State This key specifies the general status of the device. Values ONLINE ERROR Value Description Device is connected and online; device is ready to process check Device is not ready to process check Path This key specifies status of the check path.
Section 7. Other Keys Available from Device USBSpeed This key specifies the protocol of USB connection. Values HI LOW Value Description The current USB connection is USB2.0 The current USB connection is USB1.1 StartTimeout This key specifies the firmware Timeout on check entry.
SECTION 8. EXAMPLES OF KEY-VALUE PAIRS This section contains examples of key-value pairs send to the ImageSafe device and the key-value pairs returned from ImageSafe device when requesting four images without endorsement. The corresponding key-value pairs for these examples are also provided in XML format. The examples include key-value pairs for querying the ImageSafe device. These are key-value pairs in the DeviceStatus, DeviceCapabilities, and DeviceUsage.
ImageSafe Windows API Specifications Key-Value Pairs Sent by STXDemo Application to Excella Device in XML Format 2 FRONT BACK COL24 100x100 JPEG JPG COL24 100x100 JPEG JPG
Section 8.
ImageSafe Windows API Specifications LATCHED NOTSUP TRUE OK PRESENT EMPTY OK OK OK EMPTY OK PRESENT OK 384 FACTORY FACTORY
Section 8.
ImageSafe Windows API Specifications Endorse ExpressCapable Firmware IDScan Image MICR MachineType MagStripe MagnePrint Stamp USBDriver UnitSerialNumber BOTH TRUE MS1.01.25K T BOTH T ExcellaSTX T T NONE RNDIS NONE DEVICE CAPABILITIES REPORTED BY EXCELLA DEVICE IN XML FORMAT - - F BOTH BOTH TRUE MS1.01.
Section 8.
APPENDIX A. FORMAT LIST For check reading, the ImageSafe device provides the flexibility to format the MICR fields and build a specific output string that will be transmitted to the Host. These output strings are referred to as Formats. The ImageSafe device has a built-in list of Formats (described below) from which the user may select one to become the active Format every time a check is read. The Formats may be selected using the Key- Pair Values described in Section 8.
ImageSafe Windows API Specifications Fmt 02xx: Parsed Text Format with Error Labels FC0200 - Parsed text with dashes FC0201 - Parsed text, replace dashes with “d” Error Labels - PE-parsed error, NE-no error, TR-transit error, CK-chk # error, TC-transit check digit error, AM-amount error, OU-on us/account# error, TP-tpc error Examples: - PTTR444455556;AC999-222-3;CK11045/PENE - PTTR111?11111;AC123456/PETR (“?” = unreadable character) Fmt 03xx: • [acct #]: Fmt 04xx: • [acct #]: Fmt 05xx: • [acct #
Appendix A.
ImageSafe Windows API Specifications Fmt 14xx: [transit] [acct #] [check #] • [transit]: - all characters in the field - keep dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes • [check #]: - always 6 characters, zero filled Fmt 15xx: [bank #] [acct #] • [bank #]: - all characters in the field - keep spaces and dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes Fmt 16xx: [bank
Appendix A.
ImageSafe Windows API Specifications Fmt 24xx: [transit] 'T' [acct #] 'A' [check #] 'C' [amount] '$' • [transit]: - all characters in the field - keep dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes • [check #]: - always 6 characters, zero filled • [amount]: - all characters in the field Fmt 25xx: 'M' 'C' [transit] 'D' [acct #] 'E' [check #] • [transit]: - all characters in the field - remove dashes and keep spaces (contig spcs = 1 s
Appendix A. Format List Fmt 29xx: 'C' '/' [transit] '/' [acct #] '/' [check #] '/' [status] • [transit]: - all characters in the field - keep dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes • [check #]: - maximum of 6 digits • [status]: - this is a programmable option that must be enabled (See Table 2-4).
ImageSafe Windows API Specifications Fmt 3300: '=' [transit] '=' [acct #] '=' [check #] '=' [status] • [transit]: - all characters in the field - remove dashes • [acct #] : - maximum of 14 digits - remove spaces and dashes • [check #]: - maximum of 8 digits - remove spaces and dashes • [status]: - this is a programmable option that must be enabled (See Table 2-4).
Appendix A.
ImageSafe Windows API Specifications Fmt 42xx: US check : [transit] [acct #] Can check: '9' [transit] [acct #] • [transit]: - all characters in the field - remove dashes • [acct #]: - always xx characters; zero filled; when xx=00 all characters are sent.
Appendix A.
ImageSafe Windows API Specifications Fmt 52xx: 'T' [transit] 'T' [acct #] 'A' [check #] • [transit]: - all characters in the field - remove dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes • [check #]: - all characters in the field - remove dashes and spaces Fmt 53xx: '/' [transit] '/' [acct #] '/' [check #] '/' [tpc] '/' [status] '/' • [transit]: - all characters in the field - remove dashes • [acct #]: - maximum of xx characters; wh
Appendix A.
ImageSafe Windows API Specifications Fmt 60xx: [transit] '/' [acct #] '/' [check #] '/' [check type] • [transit]: - all characters in the field - remove dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes • [check #]: - maximum of 10 characters - remove spaces and dashes - if no check #, remove preceding slash ('/') • [check type]:- personal checks ('1'); commercial checks ('2') Fmt 61xx: [transit] [acct #] [check #] • [tr
Appendix A. Format List Fmt 64xx: [transit] [acct #] [check #] [amount] • [transit]: - all characters in the field - keep dashes • [acct #]: - always xx characters, trailing spaces; when xx=00 all characters are sent - keep spaces and dashes • [check #]: - always 6 characters (N is on quick-init check), trailing spaces - remove spaces and dashes • [amount]: - all characters in the field - remove spaces and dashes - insert decimal point ('.
ImageSafe Windows API Specifications Fmt 68xx: [transit] [acct #] [check #] [amount] • [transit]: - all characters in the field - remove dashes • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove spaces and dashes • [check #]: - all characters in the field - remove dashes and spaces • [amount]: - all characters in the field - remove dashes, spaces and leading zeros - insert decimal point ('.
Appendix A.
ImageSafe Windows API Specifications Fmt 76xx: 'T' [transit] 'A' [acct #] 'C' [check #] 'M' [raw data] • [transit]: - all characters in the field - remove dashes and spaces • [acct #]: - maximum of xx characters; when xx=00 all characters are sent - remove dashes and spaces • [check #]: - all characters in the field- remove dashes and spaces • [raw data]: - translate MICR symbols to t,o,a,d 96
APPENDIX B. ERROR CODES AND MESSAGES The following are Error Codes and Error Messages from ImageSafe device API MTXMLMCR.dll. Error Code Error Message Error Code Error Message 0 "Success" 25 “Error connecting to the device.” 1 "Unknown Error" 26 “Error device is not open.” 2 "Bad Parameter" 27 “Error getting the pointer to DOM.” 3 “Operation Pending” 28 "Error loading XML." 4 “Operation Failed” 29 "Error finding key number." 5 “OverFlow” 30 "Error connecting to internet.
ImageSafe Windows API Specifications Error Code 98 Error Message 50 “Error Get Zero Content Length” 51 “Error Bad Device Name” 52 “Error Bad Doc Info Buffer” 53 “Error Bad Section Name” 54 “Error Bad Key Name” 55 “Error Bad Value Buffer” 56 “Error Bad Buffer Length” 57 “Error Bad Query Parameter” 58 “Error Bad Image Name” 59 “Error Bad Buffer” 60 “Error Bad Buffer Size” 61 "Error Bad Connect Request Timeout." 62 "Error Insufficient Disk space." 63 "Error MSXML Not Found.
APPENDIX C. HOW TO PROCESS CHECKS AND GET IMAGE QUALITY ASSURANCE Note This procedure is only for ImageSafe Software installed with ImageScore optional feature. The following steps describe the process of scanning a check to perform a set of tests on the scanned image to ensure the image qualifies a number of quality and usability criteria specified by the X9.37 standard: 1. Find the attached ImageSafe device by using function MTMICRGetDevice. 2. Use function MTMICROpenDevice to open the device. 3.
ImageSafe Windows API Specifications default values for all Image QA test metrics. For more information on these test metrics, see ImageScore manual (Please contact Help Desk). 11. Use function IS_LoadSetup to load the pre-defined setup file. When a setup file is loaded, any change to this file will not be taken into effect until you unload the old setup file. Use function IS_DeleteSetup to unload the old setup file then use function IS_LoadSetup to load the new setup file. 12.
INDEX MTMICRSendCommand ............................................ 17 MTMICRSetIndexValue............................................. 11 MTMICRSetLogFile .................................................. 34 MTMICRSetLogFileHandle ............... 34, 35, 36, 37, 38 MTMICRSetTimeout.................................................. 32 MTMICRSetValue...................................................... 10 A API Functions ....................................................................
