MagTek 99875125 User Manual

MAGTEK DEVICE DRIVERS

FOR WINDOWS

PROGRAMMING REFERENCE MANUAL

Manual Part Number: 99875125 Rev 8

OCTOBER 2004

REGISTERED TO ISO 9001:2000

1710 Apollo Court

Seal Beach, CA 90740

Phone: (562) 546-6400

FAX: (562) 546-6301

Technical Support: (651) 415-6800

www.magtek.com

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. Microsoft, MS, MSDOS, MSCOMM and Microsoft Visual Basic are registered trademarks of Microsoft Corporation, and Windows is a trademark of Microsoft Corporation.

REVISIONS

Rev

Number

1 20 Nov 98 Initial Release 2 16 Feb 99 Sec 1: Editorial comments for clarification; Sec 2: Added c_wr_secure

3 27 Apr 99 Global: Changed names of Mt-211 and MT-215 to port powered

4 21 Oct 99 Sec 1: added: part numbers of media, special commands, MICR

5 14 Dec 99 Appendix A: Added statement about "Long File Names" under "Adding

6 30 Nov 01 Editorial changes throughout and added Software Version MTD 1.10, 7 14 Oct 03 Engineering upgrade to Software Version 1.12. Added ISO logo, Tech

8 1 Oct 04 Updated to MTD 1.13 software release including Automated Installation

Date Notes

and trks 1, 2, and 3; Sec 3: Editorial comments for clarification; Appendix A: Added MT-85 and clarified tables; Appendix D: Added c_wr_secure and tks 1, 2, and 3 and MT-85 Encoder sheet.

readers; Sec 3: Added card insertion note to event; Sec 4: Added this section, Data Parsing. Appendix A: Changed file names. Appendix D. Changed names.

material; Sec 2: changed properties table; Sec 3: added errors 45 and 60 to write command; Sec 4: added descriptions to language format; updated default formats; Sec 5: replaced Visual Basic example; Appendix A; Completely revised; Appendix D: added applied_fmt to all forms.

MagTek Device Drivers" General Notes number 4; added statement to "Completing the Installation" about sharing a single port; Edited "Removing the Drivers"; added "Configuration Examples of NT Drivers." Appendix D: Under IntelliPIN PINPad and MSR, added statement under Remarks about IntelliPIN driver; under MiniWedge MSR added statement about ASCII and Character Conversion.

which includes Windows ME/2000/XP. Support phone number, and Software License and removed Limited

Warranty. Editorial throughout. Feature (Appendix A). Removed references to Windows 95.

REGISTERED TO ISO 9001:2000

1710 Apollo Court, Seal Beach, CA 90740 MagTek Part Number 99875125-2 Voice: (562) 546-6400 Fax: (562) 546-6301 13 June 2003

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 ABOVE ADDRESS ATTENTION: CUSTOMER SUPPORT.

TERMS, CONDITIONS AND RESTRICTIONS

MagTek, Incorporated (the "Licensor") owns and has the right to distribute the described software and documentation, collectively referred to as the "Software".

LICENSE: Licensor grants you (the "Licensee") the right to use the Software in conjunction with MagTek products.

LICENSEE MAY NOT COPY, MODIFY OR TRANSFER THE SOFTWARE IN WHOLE OR IN PART EXCEPT AS EXPRESSLY PROVIDED IN THIS AGREEMENT. Licensee may not decompile, disassemble or in any other manner attempt to reverse engineer the Software. Licensee shall not tamper with, bypass or alter any security features of the software or attempt to do so.

TRANSFER: Licensee may not transfer the Software or license to the Software to another party without prior written authorization of the

Licensor. If Licensee transfers the Software without authorization, all rights granted under this Agreement are automatically terminated.

purposes. All other copies of the Software are in violation of this Agreement.

TERM:

this Agreement if Licensee fails to comply with any of the terms, conditions or restrictions contained herein. Should Licensor terminate this Agreement due to Licensee's failure to comply, Licensee agrees to return the Software to Licensor. Receipt of returned Software by the

Licensor shall ma

This Agreement is in effect as long as Licensee continues the use of the Software. The Licensor also reserves the right to terminate

LIMITED WARRANTY:

from defects in material or workmanship under normal use. THE SOFTWARE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Because of the diversity of conditions and PC hardware under which the Software may be used, Licensor does not warrant that the Software will meet Licensee specifications or that the operation of the Software will be uninterrupted or free of errors.

IN NO EVENT WILL LICENSOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE. Licensee's sole remedy in the event of a defect in material or workmanship is expressly limited to replacement of the Software disk(s) if applicable.

GOVERNING LAW: If any provision of this Agreement is found to be unlawful, void or unenforceable, that provision shall be removed

from consideration under this Agreement and will not affect the enforceability of any of the remaining provisions. This Agreement shall be governed by the laws of the State of California and shall insure to the benefit of MagTek, Incorporated, its successors or assigns.

The Software is copyrighted. Licensee may not copy the Software except for archival purposes or to load for execution

rk the termination.

Licensor warrants to the Licensee that the disk(s) or other media on which the Software is recorded to be free

ACKNOWLEDGMENT:

ITS TERMS, CONDITIONS AND RESTRICTIONS AND AGREES TO BE BOUND BY THEM. LICENSEE ALSO AGREES THAT THIS AGREEMENT SUPERSEDES ANY AND ALL, VERBAL AND WRITTEN, COMMUNICATIONS BETWEEN LICENSOR AND LICENSEE OR THEIR ASSIGNS RELATING TO THE SUBJECT MATTER OF THIS AGREEMENT.

LICENSEE ACKNOWLEDGES THAT HE HAS READ THIS AGREEMENT, UNDERSTANDS ALL OF

QUESTIONS REGARDING THIS AGREEMENT SHOULD BE ADDRESSED IN WRITING TO MAGTEK, INCORPORATED, ATTENTION: CUSTOMER SUPPORT, AT THE ABOVE ADDRESS OR E-MAILED TO support@magtek.com.

iii

TABLE OF CONTENTS

SECTION 1. OVERVIEW.............................................................................................................................1

PROBLEMS WITH CONTROLLING DEVICES........................................................................................1

BENEFITS OF A CONTROL LANGUAGE AND DRIVER........................................................................2

LANGUAGE OVERVIEW..........................................................................................................................3

Properties..............................................................................................................................................3

COMMANDS.............................................................................................................................................4

TYPICAL OPERATION.............................................................................................................................5

Open a device.......................................................................................................................................5

Query the device’s capabilities.............................................................................................................5

Prepare the device for work..................................................................................................................5

Use the device......................................................................................................................................5

Close the device...................................................................................................................................6

METHODS OF ACCESSING THE DEVICE.............................................................................................6

Obtaining access to the device.............................................................................................................6

Interacting with the device....................................................................................................................7

Releasing access to the device............................................................................................................8

ERRORS AND ERROR PROCESSING...................................................................................................8

HANDLING SPECIAL COMMANDS.........................................................................................................9

Generic Devices ...................................................................................................................................9

IntelliPIN Driver.....................................................................................................................................9

MICR Format Numbers.........................................................................................................................9

FILE PROPERTIES................................................................................................................................10

INSTALLATION ......................................................................................................................................10

SECTION 2. PROPERTIES.......................................................................................................................11

account_no..........................................................................................................................................11

amount.................................................................................................................................................11

applied_fmt..........................................................................................................................................11

c_card_stat..........................................................................................................................................11

c_keypress ..........................................................................................................................................11

c_keystring ..........................................................................................................................................11

c_magnetic..........................................................................................................................................11

c_mechanics........................................................................................................................................11

c_pin....................................................................................................................................................11

c_smart................................................................................................................................................11

c_tracks ...............................................................................................................................................11

c_write .................................................................................................................................................12

c_wr_secure ........................................................................................................................................12

capitalize..............................................................................................................................................12

card_stat..............................................................................................................................................12

chk_account ........................................................................................................................................12

chk_amount.........................................................................................................................................12

chk_bankid ..........................................................................................................................................12

chk_data..............................................................................................................................................12

chk_format...........................................................................................................................................12

chk_mod10..........................................................................................................................................12

chk_number.........................................................................................................................................12

chk_routing..........................................................................................................................................12

chk_status ...........................................................................................................................................12

chk_transit ...........................................................................................................................................12

cmd_pending.......................................................................................................................................12

dblpinentry...........................................................................................................................................12

dev_status ...........................................................................................................................................12

dev_version .........................................................................................................................................12

enable_cmc7.......................................................................................................................................12

enc_key ........................................................................................................................ .......................13

enc_key_sn .........................................................................................................................................13

enc_mode............................................................................................................................................13

entry_echo...........................................................................................................................................13

entry_len..............................................................................................................................................13

entry_tout.............................................................................................................................................13

events_on............................................................................................................................................13

invalcmdrsp .........................................................................................................................................13

key_parity ..................................................................................................................... .......................13

lasterr...................................................................................................................................................13

max_pin_len........................................................................................................................................13

msg1 - msg4........................................................................................................................................14

oper_tout..............................................................................................................................................14

pin_blk_fmt..........................................................................................................................................14

pinfilldig................................................................................................................................................14

port_name ...........................................................................................................................................14

pwroffdelay..........................................................................................................................................14

s_down_tout........................................................................................................................................14

track1ss ...............................................................................................................................................14

trivpinchk..............................................................................................................................................14

trk_enable............................................................................................................................................14

trk1data................................................................................................................................................14

trk2data................................................................................................................................................14

trk3data................................................................................................................................................14

visa_mac1 ...........................................................................................................................................14

visa_mac2 ...........................................................................................................................................14

visa_mac3 ...........................................................................................................................................14

wr_coer................................................................................................................................................14

wr_secure............................................................................................................................................14

xact_type ...................................................................................................................... .......................14

SECTION 3. COMMANDS.........................................................................................................................15

DATA FORMAT......................................................................................................................................15

RESPONSES..........................................................................................................................................15

NOTATION CONVENTIONS..................................................................................................................16

COMMAND DESCRIPTIONS.................................................................................................................16

cancel..................................................................................................................................................16

display.................................................................................................................................................17

echo....................................................................................................................................................17

event...................................................................................................................................................18

get.......................................................................................................................................................18

load_key..............................................................................................................................................19

rawrecv ...............................................................................................................................................20

rawsend ..............................................................................................................................................21

rawxact................................................................................................................................................21

read.....................................................................................................................................................22

Read Arguments....................................................................................................................................23

reset....................................................................................................................................................26

set.......................................................................................................................................................26

ver.......................................................................................................................................................26

write ....................................................................................................................................................27

SECTION 4. MAGNETIC CARD DATA PARSING...................................................................................29

GOALS....................................................................................................................................................29

ASSUMPTIONS......................................................................................................................................29

DESCRIPTION .......................................................................................................................................30

LANGUAGE FORMAT............................................................................................................................31

Format Name......................................................................................................................................31

Format Template ................................................................................................................................31

Format Rules......................................................................................................................................31

DEFAULT FORMATS.............................................................................................................................35

EXAMPLE...............................................................................................................................................36

Retrieving properties from a magnetic card........................................................................................36

SECTION 5. EXAMPLE APPLICATIONS.................................................................................................39

PROGRAMMING HINTS........................................................................................................................39

VISUAL BASIC EXAMPLE .....................................................................................................................39

C++ EXAMPLE.......................................................................................................................................45

C#.NET EXAMPLE.................................................................................................................................50

C EXAMPLE ...........................................................................................................................................56

POWER BUILDER EXAMPLE................................................................................................................59

APPENDIX A. INSTALLATION AND SETUP...........................................................................................61

Installing USB HID Devices on Windows 2000 and XP .....................................................................62

Installing MTD Drivers ........................................................................................................................65

Installing on Windows NT, 2000 and XP............................................................................................68

Installing on Windows 98 and ME ......................................................................................................70

Completing the Installation .................................................................................................................72

Modifying MTD Driver Installation.......................................................................................................73

Modifying a Device Driver’s Settings..................................................................................................74

AUTOMATING MTD DRIVER INSTALLATION......................................................................................78

Pre-selecting The Device(s): ..............................................................................................................78

Reboot: ...............................................................................................................................................78

Installing OPOS:.................................................................................................................................78

Installing Generic Driver: ....................................................................................................................79

Installing IntelliPIN:.............................................................................................................................80

Installing MiniMICR:............................................................................................................................81

Installing MT-85:.................................................................................................................................82

Installing MT-95:.................................................................................................................................82

Installing Port Powered Swipe Reader:..............................................................................................83

Installing Port powered Insert Reader:...............................................................................................84

Installing MagWedge:.........................................................................................................................84

Installing MiniWedge:..........................................................................................................................85

Installing USB HID Swipe Reader:.....................................................................................................85

Sample MTDINST.INI FILE ................................................................................................................86

UNINSTALLING OLD MTD VERSIONS.................................................................................................88

Uninstalling Old Drivers from Windows 95, 98/ME.............................................................................89

Uninstalling Old Drivers from Windows NT ........................................................................................91

Uninstalling Old Drivers from Windows 2000/XP ...............................................................................91

Uninstalling the Keyboard Hook Driver (W2000)................................................................................91

Uninstalling the Keyboard Hook Driver (XP) ......................................................................................94

Using the MTCFG Utility (WNT/2000/XP) ..........................................................................................96

Command Syntax Summary...............................................................................................................96

Displaying Configuration Information (WNT/2000/XP).......................................................................96

Configuring New Devices (WNT/2000/XP).........................................................................................97

Configuration Examples for Windows NT/2000/XP............................................................................97

Modifying a Device Driver's Settings (WNT/2000/XP)........................................................................98

Removing a Device (WNT/2000/XP)..................................................................................................99

MTD PROGRAMMING EXAMPLES.......................................................................................................99

APPENDIX B. COMMAND LIST SUMMARY..........................................................................................101

APPENDIX C. STATUS CODES.............................................................................................................103

APPENDIX D. DEVICE DRIVER SUMMARIES......................................................................................105

INTELLIPIN PINPAD & MSR................................................................................................................106

MAGWEDGE SWIPE READER ...........................................................................................................107

MINIWEDGE MSR................................................................................................................................108

MICR+ CHECK READER & MSR.........................................................................................................109

MINI MICR CHECK READER & MSR..................................................................................................110

PORT-POWERED RS-232 SWIPE READER......................................................................................111

PORT-POWERED RS-232 INSERTION READER..............................................................................112

MT-85 LOCO ENCODER .....................................................................................................................113

MT-95 HICO ENCODER.......................................................................................................................114

GENERIC..............................................................................................................................................115

INDEX........................................................................................................................................................117

FIGURES

Figure 1-1. MagTek Devices and Device Drivers for Windows..................................................................viii

vii

MTD

MagTek

Device Drivers

for Windows

Figure 1-1. MagTek Devices and Device Drivers for Windows

viii

SECTION 1. OVERVIEW

The MagTek Device (MTD) Drivers for Windows is a collection of individual drivers that support a number of MagTek products. These drivers provide a uniform application interface for controlling a wide range of MagTek devices. The drivers, combined with a device control language, solve many of the difficulties application developers face when attempting to control hardware devices. The difficulties mount when faced with the task of developing an application that supports an entire product line of devices.

Part Numbers for the MTD for all Windows platforms (95, 98, ME, NT, 2000, and XP) are as follows:

Part Number Medium 30037385 CD

99510030 Internet* *www.magtek.com

PROBLEMS WITH CONTROLLING DEVICES

The major problems with developing an application that supports an entire product line of devices are as follows:

• Each MagTek device has a unique set of commands. The commands usually perform

similar functions on a particular class of devices but either differs in syntax or have small variations in their functionality. An application would have to implement a custom mechanism to control each device it supported–much like DOS applications had to do to support various printers.

•

Most MagTek devices communicate via data streams, not packets. This means that an application receives data from the device one character at a time; it only receives partial command responses. It would be the application’s responsibility to collect the incoming data and parse it into individual responses.

Responses from MagTek devices are inherently asynchronous. When an application

•

sends a command that requires a response, the response from the device arrives (or worse, begins to arrive) long after the command is sent. The application would have to either poll the device until all of the response is collected or implement a callback mechanism to collect and receive it.

Most MagTek devices maintain a communication protocol of some kind. In addition to

•

this, the protocols differ between devices. For example, some devices frame responses with STX and ETX control characters and others simply use a CR or require a checksum in the frame. To deal with this, an application would have to recognize and implement all of the various protocols for the devices it supports.

MagTek Device Driver for Windows

• `MagTek devices are attached to the host in different ways. MagTek devices may be

attached to a serial port, parallel port, to another device or even to the keyboard port. All these ports differ greatly in nature and would all have to be accessed by the application. Additionally, meaningful communication with a device attached to the keyboard port would be tricky at best. This is because the operating system does not provide a means to send data to the keyboard port nor any mechanism to discriminate between the device data and manual keystrokes.

BENEFITS OF A CONTROL LANGUAGE AND DRIVER

A device control language is defined to support most of the functionality of all MagTek devices. As noted previously, most devices of a particular class have similar functionality. The control language defines a common set of commands that perform these functions in the same way for all MagTek devices, thus eliminating device-specific coding for most applications. If the need arises to perform an operation on a device not covered by the common command set, a “raw” send and receive command can be used to communicate directly with the device, effectively eliminating any limitations on the amount of control you have over the device.

The control language is based on a simple property/command model. This model is familiar to most developers who deal with properties and methods in development environments such as Visual Basic or Delphi. You set up the device by getting and setting properties and operate it by invoking commands.

The command set presents a synchronous interface to the application even though the device operates asynchronously, greatly simplifying the effort in retrieving responses from a device. The pattern is simple: send a command to the device and invoke a read command, which will not complete until after the entire response is received from the device.

The control language is implemented by a driver, which completes the solution for the application developer. The driver adds the following benefits:

• Gives easy access to the device. All MagTek devices are presented uniformly as a virtual

serial port, regardless of how they are actually attached to the host.

• Hides the communication protocol. Adding and stripping frames, performing

checksums, detecting and correcting communication errors, etc, are handled completely by the driver. The application sees only the data that it is interested in and can be assured that it is free from transport errors.

• Converts the incoming data stream into complete responses. The application receives

data from the device in easy to use packets. The entire response to a command is received in a single operation.

• Makes it easier to upgrade to a new device. The driver shields you from differences in

the new device’s commands or interface. When upgrading the device, an application can

Section 1. Overview

usually remain unchanged, even though the new device may be very different from the old one.

The features of a driver that implement a device control language completely shield an application developer from the complexities of device-specific functionality.

LANGUAGE OVERVIEW

The device control language is text based and designed to utilize the read and write file I/O facilities of the underlying operating system. All commands, their responses and properties consist of text strings that are written to or read from the driver using basic file I/O. The control language is based on a property/command model that is similar to the notions of properties and methods as accepted in environments such as Visual Basic or Delphi.

Properties

All properties are accessed in a uniform way: by using a get (/get prop) or a set(/set prop) command. Properties are either read/write or read only. A set command with a read only property will fail. All properties are identified by a string name and use strings for their arguments. Properties defined by the control language fall into the following three groups:

•

Capability properties – These properties contain information about the capabilities of a particular device and are generally read only. They allow an application to query a device’s capabilities to determine if the device is suitable for a particular task. Included in this category are c_cardwpin, c_check, c_pin, and c_magnetic (e. g., /get

c_check

Configuration properties – These properties configure a device for different modes of

•

operation or may alter the way some commands behave. Because of this, they are usually readable and writable. They give an application the ability to set up a device for a particular task that requires a specific, non-default mode of operation. Included in this category are

capitalize, dev_version, and port_name (e.g., /set capitalize 1).

•

Device-specific properties −These properties cover configuration requirements that are not common among MagTek devices, even if the devices belong to the same class. An application can determine if a particular set of device-specific properties is available by first querying the device’s capabilities or version. Refer to Appendix D, Device Driver Summaries, for a particular driver to see how these properties are affected with an individual device.

Properties can be “action” properties. That is, the driver may execute an action on the device when a property is set. For example, an application can enable or disable magnetic stripe tracks by setting the trk_enable property. The driver responds by sending one or more commands to the device to enable or disable the desired tracks.

MagTek Device Driver for Windows

COMMANDS

Like properties, commands are identified by a string name and have string arguments. All commands are terminated by line feed <LF> or a carriage return. To invoke a command, an application simply writes it to the driver in the same manner as writing to a file or serial port. If the command has a response defined for it, the application reads it from the driver using the same I/O handle as in the write.

Four types of commands are defined by the device control language:

•

Non-interactive – These commands manipulate the device without requiring any interaction with the user. The property commands get, set, reset, and ver are examples of this type.

Interactive – These commands interact with the user. They do not necessarily require the

•

user to do anything but may only prompt the user to do something. display is an example of such a command. Others, such as read or write, however, require user interaction to complete. For example, the user must either swipe a card or cancel the operation in order to complete a read command.

Device-specific – These commands give access to device-specific features. For example,

•

the load_key command is available for MagTek devices that use keys to encrypt data before sending it to the host.

Raw – These are effectively escape commands. They allow the application to bypass the

•

driver to perform device-specific operations that are not included in the driver syntax and not supported elsewhere. With these commands, an application has no limitations on the amount of control it has over a device. The raw commands can be formatted exactly as specified in the device documentation. The command bracketing will be inserted by the driver if required (e.g., <stx> and <etx> will be inserted for certain devices). Three commands are defined for this type: data directly to the device, and the first two.

A small set of interactive and non-interactive commands is all that is required for an application to perform the most common tasks with these devices. Device-specific or raw commands should rarely be needed.

rawsend and rawrecv, used to send and receive

rawxact, a transactional version that is a combination of

Section 1. Overview

TYPICAL OPERATION

This section describes a typical pattern that an application developer may use to operate a device. Although it is the most typical pattern, it is by no means the only viable one. Refer to Section 5, Example Applications, to see how to use the drivers in various applications.

Open a device

Access to the device is obtained by opening the comxx: port that the device was installed as. This is not the hardware port that the device may be attached to, but a virtual comxx: port presented by the driver (e.g., COM5 or higher). A handle is returned by the open function and is required for all subsequent interactions with the driver. When opened, the driver initializes itself and, where required, the device.

Some drivers support automatic settings. In this mode, the driver first attempts to communicate with the device at the previous setting or at the default setting if it is the first time. (The setting for the initial attempt is grayed out in the manual settings fields.) If the driver for certain devices (e.g., Mini MICR) does not receive a response, it will adjust the settings and try again. This sequence continues until the device responds or until all possible settings have been attempted.

If the driver is set for the automatic mode, it may take considerably longer for the device driver to detect an error. In particular, if the device is not connected to the specified port or if its power is off, the device driver may take several seconds attempting all possible settings before it returns an error. The application program should be tolerant of this delay. Not all of the devices support the automatic mode of detection.

Query the device’s capabilities

The application can query the device to determine if it can perform the required task. The capability properties (c_xxx) are provided for this purpose. For example, if an application requires the ability to read checks, it can

get the c_check property to determine if the device

can read checks (e.g., /get c_check).

Prepare the device for work

The device is prepared for operation by setting one or more of the configuration properties. Its mode of operation and other features are set up by these properties. Setting the property to

1 to cause all data written to or read from a card’s magnetic strip to be capitalized is

capitalize

an example of this type of initialization. In some cases, modifying a property may cause the driver to execute functions on the device.

Use the device

The device is now fully initialized ready for operation. Because most tasks with the device require interaction with the user, the application operates the device using primarily the interactive commands. A typical scenario is when, in response to some event, the user is

MagTek Device Driver for Windows

prompted to swipe a card by using the display command, followed by a read command to instruct the device to return the card data when swiped. All the facilities of the driver are utilized during this stage of operation.

Close the device

When the application is finished with the device, it simply closes the port using the handle obtained when it opened it. The driver shuts down the device if required.

METHODS OF ACCESSING THE DEVICE

This section describes how to use control language commands in a Visual Basic development environment using the MSComm (Microsoft Communication) component.

Obtaining access to the device

If the MSComm (Microsoft Communication) ActiveX component is used to access the device, set the CommPort property to the com port number of the device. Then, set the PortOpen property to True to open it. The following example shows how:

‘set error handling

On Error Resume Next

‘open the port

Comm.CommPort = 5 Comm.PortOpen = True If Err.Number <> 0 Then <<process error>> End If on error goto 0

Note

After issuing an Open command, the computer may spend several seconds attempting to communicate with the device. During this time the computer will appear to be hung up.

If file I/O access is desired, you have the option of using either the device’s friendly name, such

\\.\micr+ (where \\.\ specifies to Windows that this is a device and not a file) or its port

as name,

COM<5..15>. The friendly name is more intuitive and easier to remember than a port

number; however, the serial method gives the programmer better control of the device. The port number can be found in the operating system’s device UI. For example, open Control Panel/System/Device Manager/MagTek and select a specific driver. Under Properties, select the Settings tab. This gives both the Friendly Name and the port name (COM<5-15>). It also identifies the physical port that will be used to communicate with the device.

Open the device using either of the previous names. Use whatever facility is provided by your development environment for opening files. For Visual Basic, do the following:

Section 1. Overview

'set error handling On Error Resume Next

‘open the port for binary access

Open “\\.\micr+” For Binary Access Read Write As #1 If Err.Number <> 0 Then <<process error>> End If on error goto 0

Note

The friendly name of the device, as found in the operating system’s device UI (Device Manager in Windows 98, for example), must be prefixed with “\\.\” in order to open the device. If the previous example did not have the prefix, it would create a file named

micr+ in the current directory–clearly not the desired result.

Interacting with the device

An application interacts with the device by sending commands to the device and reading its responses. Commands are sent by writing to the opened port and responses from the device or property requests are retrieved by reading from the port.

To interact with the device using the MSComm component, invoke a command by assigning it to MSComm’s Output property. The response is received by MSComm’s OnComm event handler as a comEvReceive event or by directly polling the port. The entire response to a command or property request is received as a single event.

'submit echo command

Comm.Output = "/echo Hello" + Chr$(10)

Private Sub Comm_OnComm()

‘return if not a receive event

If Comm.CommEvent = comEvReceive Then ‘process received data a$ = Comm.Input ‘get echo data Else <<process non-read event>> End If End Sub

If using file I/O access, interaction with the device is indistinguishable from writing to or reading from a file.

MagTek Device Driver for Windows

‘set up error handling

On Error Resume Next

‘submit echo command

Put #1, , "/echo Hello" + Chr$(10)

‘declare an input buffer a$ = String(2000, Chr$(0))

‘read echo response from device

Get #1, , a$ If Err.Number <> 0 Then <<process error>> End If

Note

File I/O interaction with the device is synchronous; the read operation will block until a response is received from the device or is returned by the driver (as in a property request). This means that a read command cannot be canceled because the computer will not accept any new commands while one is pending. The only exception to this is when the development environment provides access to the Win32 API, giving the application the ability to use overlapped file I/O.

Releasing access to the device

Releasing access to the device is very simple. If using MSComm, close the device by setting its

PortOpen property to False:

‘close the port

mscomm1.PortOpen = FALSE

If opened as a file, close it as in the following:

‘close the port

Close #1

ERRORS AND ERROR PROCESSING

A command’s execution status is returned to an application in the command’s response, if it has one. The status value is a two digit numeric field located at positions 23 and 24 of the response (refer to Appendix C. Status Codes for a description of all error conditions) .

Errors are processed differently for property manipulation. If an error occurs while getting a property, the response will be returned with an empty property value. No status is returned when setting a property because the

set command has no response defined for it.

If a command returns a non-zero status, indicating an error, an application can typically respond in the following manner:

Section 1. Overview

1. It can prompt the user to repeat the action and re-submit the command. This is typical if the status does not indicate a failure, per se, but that the device may not be ready yet or first needs some other interaction by the user.

2. It can reset the device and prompt the user to repeat the action. Typically, this action is necessary if the device’s state or configuration has been corrupted, but is otherwise functioning correctly.

3. Finally, the application can refuse to continue operation of the device. An application should do this only if the returned status indicates that the device is malfunctioning.

HANDLING SPECIAL COMMANDS Generic Devices

Some devices such as the IntelliPIN support a set of commands that are not standard and/or do not follow the usual protocol. The Generic Driver can be used to support these commands. It does not know how to communicate with any device and does not support any protocol. The Generic Driver allows the application to send any string to a device. When the Generic Driver is used, the application must form the command, insert packet characters, and compute a check character where required. The Generic Driver only supports the “raw” commands.

The Generic Driver can be used whenever a deviation from the standard protocol is required or when no protocol exists at all. However, the Generic Driver, unlike all of the other drivers, does not support any properties. It is only available to support those cases that cannot be handled with the standard drivers.

IntelliPIN Driver

With release MTD 1.12, the IntelliPIN driver has been updated to support the special set of commands that require <si> and <so> instead of the usual <stx> and <etx> characters. These special commands that support the multi-master keys (e.g., 02, 04, 08, etc.) are not supported with the standard IntelliPIN commands. However, if these commands are used in the /rawsend or /rawxmit commands, the <si> and <so> will automatically be inserted.

MICR Format Numbers

In order to retrieve the built-in check properties (chk_***), the driver automatically configures the MICR units to format number 6500. However, there are some cases, especially outside the United States, where the check information is not consistent with format number 6500. In these cases, the installer has the option of modifying the format number string in the OEMSETUP.INF file.

MagTek Device Driver for Windows

The format number can be changed to another value (e.g., 7700 to allow use of a flex format) by editing the field following the format number entry (%CheckFormatCodeName%) in the OEMSETUP.INF file. This must be changed in three places depending on which drivers are to be used (MICR+, MiniMICR RS232, and MiniMICR Wedge). By defining a flex format that would duplicate the 6500 output format, the driver will still be able to parse the check data and present the individual properties (e.g., chk_account, chk_amount, chk_number, and chk_transit). If a suitable format cannot be developed to present the individual properties, the driver will still be able to present the check data (chk_data) as received from the MICR reader. If the existing format number in the MICR device is suitable, set the %CheckFormatCodeName% entry to null (i.e., “”), so it will not be modified by the Driver.

Refer to the appropriate MICR Technical Reference Manual for more information about the use of format numbers and available MICR fields.

FILE PROPERTIES

When updating the MagTek Device Drivers, discussing performance characteristics, or reporting errors, it will be important to identify the part number and version of the associated file(s). In order to determine which version is installed, use Windows Explorer and go to the \Windows\System directory. Right click on the associated “VXD” or “SYS” driver file (see Appendix A. Installation and Setup) and select Properties. Click on the Version tab. Note the File Version, Part Number, and Description.

INSTALLATION

The drivers are installed by means of an InstallShield application. All Windows platforms (95, 98, ME, NT, 2000, and XP) are supported. Refer to "Appendix A. Installation and Setup" for a full description of the installation procedure.

SECTION 2. PROPERTIES

This section lists the properties that are used in the MagTek Drivers. Properties can be interrogated by issuing a Commands for complete description and examples of all commands.

The

c_xxx properties are set by the driver and reflect the device’s capabilities. However, the

c_xxx properties do not indicate the configuration of the device. For example, a device may be

capable of reading all three magnetic tracks but be configured to only read two tracks or a MICR reader, while often configured with a magnetic stripe reader, may not have an MSR installed. Unless otherwise noted, 1 means the capability is available, 0 or null (i.e., the value is not present) means that the capability is not available.

In this table, the Access information indicates whether the property can be modified (Read/Write –R/W) or merely accessed (Read Only–R).

Property Access Description

account_no

amount applied_fmt

c_card_stat

c_cardwpin

c_check c_events

c_keypress c_keystring

c_magnetic c_mechanics

c_pin c_smart c_tracks

get command and modified with a set command. Refer to Section 3.

R/W Cardholder account number, including check digit. It is set by the

application to be used in PIN encryption commands (IntelliPIN).

R/W Transaction amount in cents, without punctuation (IntelliPIN).

R Indicates which format template was used to parse the magnetics

data. If no template or rule is applied, this property returns a null.

1 indicates that the driver supports retrieval of card sensor status

(e.g., PPINSERT)

1 if the device supports reading of a card and a PIN in response to

a single command (e.g., IntelliPIN). R R

1 if the device can read checks (e.g., MICR devices).

1 indicates that the driver supports unsolicited event notification

(e.g., PPINSERT). R R

1 if the device supports retrieval of a key press (e.g., IntelliPIN).

1 if the device supports retrieval of a sequence of key presses (e.g.,

IntelliPIN). R

1 if the device can read magnetic cards.

R This value indicates how the card reader’s mechanism operates:

0 – manually operated device or no card reader 1 – device is mechanized and supports “eject” 2 – device is mechanized and supports “eject” and “confiscate”

R R

1 if the device supports reading of PINs (e.g., IntelliPIN).

1 if the device supports smart cards.

R A three-character string, representing the tracks supported by the

device. The left-most position indicates track 1. Thus 110

indicates that the device can access tracks 1 and 2 but not track 3.

trk_enable to determine which tracks are enabled.

See

MagTek Device Driver for Windows

Property Access Description

c_write

1 if the device can encode a magnetic card in either LoCo or HiCo;

2 if the device can encode a magnetic card in only the setting

indicated in wr_coer

c_wr_secure

0 if the device does not support secure mode;

1 if the device can switch between secure and non-secure mode

(see wr_secure);

2 if the device only operates in the secure mode.

capitalize

card_stat

chk_account chk_amount chk_bankid chk_data chk_format

R/W

Set this to 0 to prevent the driver from capitalizing the data for the

read and write commands. The default value for this property is

1 (enable capitalization).

R Current card sensor status:

0 = not blocked, 1 = blocked (PPINSERT).

R Check account number from check (MICR). R Check amount from check (MICR). R Bank ID number from the transit field (MICR). R Output data string as received from MICR reader (MICR).

R/W

Indicates the format of the check data. Set to 6500 by default. If

this property is modified by the application, the chk_xx properties

(except chk_data and chk_status) will be set to null. (MICR)

chk_mod10 chk_number chk_routing chk_status chk_transit cmd_pending

dblpinentry

dev_status

R Mod10 check digit from the transit field (MICR). R Check number (MICR). R Routing number from the transit field (MICR). R 2-digit status code from the check just read (MICR). R Transit number from check (MICR). R Command pending–indicates which command, if any, is pending.

If none is pending, the second argument will be null:

/get cmd_pending<LF>

R/W

Set to 1 to enable double PIN entry such as when requesting a new

PIN; set to

0 when verifying a customer’s PIN (IntelliPIN).

Device status. 0 means device is connected and operational. Any

other value indicates a device-specific error. If the device fails to

respond, a null value is reported:

/get dev_status<LF>

dev_version

R Device version string. This value is read directly from the device,

if the device supports a version string. <CR> characters in the

string read from the device will be replaced with /. This property

will be useful in reporting operational problems to MagTek.

enable_cmc7

R/W

Set this property to

1 to enable CMC-7 characters decoding, 0 to

disable it. This is used for international checks; see MICR manual

for more information. (MICR)

Section 2. Properties

Property Access Description

enc_key

enc_key_sn

R/W Encryption key to use for the next encryption process (IntelliPIN):

Set Get Key M 4 Master key S 5 Session key 0-3 0-3 Lower working keys A-J A-J Upper working keys WA-WZ A-Z Working keys A-Z Wa-Wz a-z Working keys a-z

R/W Serial number of encryption key. Used to specify key serial

number for activating/deactivating PIN encryption in MSK mode

and to return the key serial number in DUKPT mode. The key

serial number is specified in clear text (IntelliPIN).

enc_mode entry_echo

R/W

Current encryption mode – msk or dukpt (IntelliPIN).

R/W Specifies how to display the characters when entered from the

keypad on the LCD screen (IntelliPIN):

• + (plus) to display as entered

• - (minus) to suppress display

entry_len

entry_tout

events_on

invalcmdrsp

key_parity lasterr

max_pin_len

• $ to display as amount

The value of this property affects the operation of the read

key_string

command. By default this property is empty.

R/W Maximum number of characters (1-32) to be collected with the

read key_string command. An empty value (default) for this

property converts to a length of 1. (IntelliPIN)

R/W Entry timeout: number of seconds (15-255) to wait for keypad

input. (IntelliPIN)

R/W

Set to 1 to enable unsolicited event notifications. The default is 0.

(PPINSERT)

R/W

Invalid command response: set to 1 to enable responses to invalid

commands (useful during program development). This is set to

(disabled) by default.

R/W

Set to

1 to enable parity check on encryption keys. (IntelliPIN)

R Status from the last command sent to the driver. A successfully

executed command will reset this value to 0. This property is

useful for checking the operation of the set commands. After

each

set, the response to get lasterr should be 0.

R/W Maximum PIN length (IntelliPIN):

• 1 – 16 for ibm format (IBM 3624)

• 4 – 12 for ansi format (ANSI 9.8)

MagTek Device Driver for Windows

Property Access Description

msg1 - msg4

R/W Messages to show on LCD screen with various commands.

msg1 – used by the read and display commands msg2 – used by the display and read Card_w_pin

commands

msg3 – used by the read Card_w_pin command msg4 – used by the key_press and key_string operations

To specify leading spaces, use \x20. See the display command for more information. (IntelliPIN)

offline_enc

R/W

Set to 1 to enable encode capability in standalone mode with

keyboard; 0 prevents standalone encoding (MT-95).

oper_tout pin_blk_fmt

pinfilldig port_name

R/W Operational timeout in seconds (15-255). (IntelliPIN) R/W PIN block format (IntelliPIN):

ansi (ANSI 9.8) or ibm (IBM 3624)

R/W

PIN fill digit (0..9, A..F) when pin_blk_fmt is ibm (IntelliPIN) R Indicates the virtual port number (e.g., COM6) derived from the

friendly port name.

pwroffdelay s_down_tout track1ss

track2ss track2ss

trivpinchk trk_enable

R/W Power off time delay in minutes (5-255). (IntelliPIN) R/W

R R R

R/W

Shutdown timeout in hours (1-31). Set to 0 to disable. (IntelliPIN)

Indicates Start Sentinel on Track 1 as received from the device.

Indicates Start Sentinel on Track 2 as received from the device.

Indicates Start Sentinel on Track 3 as received from the device.

Set to 1 for trivial PIN checki.e., don’t allow 1234. (IntelliPIN)

R/W Enable reading and writing of individual tracks. The value of this

property is a string of three characters, with 0 representing

disabled tracks and 1 representing enabled tracks, e.g., 110 enables

tracks 1 and 2 and disables track 3.

trk1data trk2data trk3data visa_mac1

visa_mac2 visa_mac3 wr_coer

wr_secure

R Data from track 1 excluding start sentinel and end sentinel. R Data from track 2 excluding start sentinel and end sentinel. R Data from track 3 excluding start sentinel and end sentinel. R Message authentication codes returned by device after PIN is

collected (DUKPT mode only). (IntelliPIN)

R/W Encode Coercivity Mode (MT-95). Specifies the energy level used

to encode the magnetic stripe:

0 = automatic selection 1 = LoCo only mode 2 = HiCo only mode

R/W

0 indicates the card can be removed between a read and write

operation. Set this to

1 to turn on secure online encode mode (MT-

95).

xact_type

R/W

Transaction type – d = debit, c = credit (IntelliPIN).

Properties like account_no and those properties created by the data parsing templates (see Section 4) that are affected by a card transaction will be modified only when a card is read without errors.

SECTION 3. COMMANDS

This section describes all of the commands that can be used with the MagTek Windows Device Drivers. Some commands require parameters to indicate to the driver exactly what function is to be performed. While there are a few device-specific commands, most commands can be used with any device.

DATA FORMAT

All commands sent to the driver and all responses received are strings of printable ASCII characters delimited by <LF>. The driver will also accept <CR> as a delimiter. All command and response strings begin with the character /. If a command has arguments, they should be separated with one or more white spaces. The driver accepts space space characters.

Note

A command delimiter sent immediately after the previous command delimiter is interpreted as an empty command and is ignored by the driver.

RESPONSES

All responses to the transaction commands are formatted with fixed fields, to allow them to be parsed either by scanning for white spaces or by using constant offsets into the response string. In the descriptions of the commands found later in this section, the arguments sent with the responses are shown in their respective locations but may not indicate the exact number of spaces. The actual responses are sent in a fixed-field format, as shown in the following table:

Field Offset Size Comment

command name 0

(0-11)

arg1 12

(12-23)

arg2 24

(24-??)

12 This field identifies the command that produced this

response, e.g., /get is followed by 8 spaces to fill the 12 locations.

12 Fixed-size argument – value depends on the

command sent. A property name is left justified in the field and begins in location 12. Status information is right justified in the field (with a trailing space) so the SS value will always be located at positions 21 and 22.

var Variable size argument – used for responses with

variable-size data, like /get prop or read status data.

<SP> and <TAB> as white

MagTek Device Drivers for Windows

Examples:

000000000011111111112222222222 012345678901234567890123456789 /read -00082 /get trk_enable 110

NOTATION CONVENTIONS

The following conventions are used in the tables that follow.

Fixed Size (Bold)

Used to represent literals (symbols, exactly as sent or received

from driver)

Italic

Used to represent placeholders (variable fields)

[] Expression parts in brackets are optional. The brackets are never

a part of the syntax

<LF>

ASCII control character. The only ASCII control characters used

are <LF> (0x0A) and <CR> (0x0D).

(a|b) Means that the expression can be either a or b, e.g., X(1|2) means

either X1 or X2. The parentheses and the | are never part of the

syntax.

COMMAND DESCRIPTIONS

The following list of commands includes function, syntax, errors, remarks, and examples as applicable.

cancel

Function

Syntax

Cancel a command.

/cancel [cmd]

The optional cmd can be any of the transaction commands such as:

/cancel rawrecv /cancel rawxact /cancel read /cancel write

If cmd is omitted, any pending commands will be canceled.

Errors

If the specified command is not active, the command is ignored and there is no response.

Remarks

Example

The command being canceled will send a response immediately. If a read command has been issued but the operation is to be aborted:

Command Response

/cancel read<LF> /read -00082<LF>

Section 3. Commands

display

Function

Syntax

Show a single message or two alternating messages on the device’s display.

/display [x]

The optional argument x indicates the message to be displayed.

Errors

Remarks

none If the optional argument x is provided, this command displays it as a single message.

If x is @, the driver sends a command to the device to display the idle message 00 (“Welcome”). If x is omitted, the command uses the values of the msg1 and msg2 properties for the message texts. If msg2 is empty, this command displays the text in

msg1; otherwise, it displays the texts in msg1 and msg2 as alternating messages. The

message texts are displayed unmodified, except for any ‘\’ characters, which are used as escape characters:

\r is converted to 0x0D (shown as <CR> in this document) \n is converted to 0x0A (shown as <LF> in this document), e.g., to be used as

line separator for LCD screens that can display multiple lines \\ is converted to \

echo

Function

Syntax

Errors

Remarks

Example

\xhh is converted to a character with ASCII value hh (always two hex digits). Not all ASCII values can be displayed. Leading and trailing spaces are removed from the message texts in the x

argument and the msg1 and msg2 properties. \x20 may be used for adding leading spaces.

To center the message “Thank You” on the IntelliPIN LCD:

Command Response

/display \x20\x20\x20Thank You

none

Echo data−driver test command.

/echo string

string is limited to 11 characters (the width of the ‘arg1’ field in the response

format) without any embedded spaces. none The driver responds by echoing the command back. If the command specifies a string that is longer than 11 characters or if a space appears, the response will be truncated. There is no translation for escape (\x00) commands. This command cannot be cancelled with

/cancel.

If you wish to ensure that the driver is properly installed, request it to echo a string:

Command Response

/echo Testing<LF> /echo Testing<LF>

MagTek Device Drivers for Windows

event

Function

Syntax

Errors

Remarks

Response to an unsolicited event notification.

none none

This response can occur when an unsolicited event, such as card inserted, occurs. The format of the response is: /event n data

n is a numeric event code:

1 – medium has been inserted into the reader 2 – medium has been removed from the reader

data specifies the type of medium that was inserted/removed:

M – magnetic

Events are sent to the application only if the c_events property is 1 (driver supports events) and the events_on property is set to 1 by the application. If a card has already been inserted when the driver is opened, there will not be any notification when

/get card_stat be issued immediately after opening the driver to see if a card

events_on is enabled. Consequently, it is recommended that

is blocking the sensor.

Example

If you wish to be notified when a card has been inserted into the PPINSERT:

Command Response

/set events_on 1<LF> /event 1 M<LF>

When a card is inserted into the slot.

get

Function

Syntax

Get a property.

/get prop

prop is one of the valid properties shown in Section 2 or any of those from data

parsing.

Errors

Remarks

/get abc<LF>

Since abc does not exist.

The driver sends a response in the format: /get prop val. If the requested property does not exist, the val field will be empty, i.e., <LF> follows the prop field. If the command was cancelled, both the prop and val fields will be

empty. In some cases, this command will interrogate the device to determine the property setting. Some properties cannot be interrogated if a command (such as read) is pending. The value will be null in this case.

Example

If you wish to find out which tracks are enabled, request the trk_enable property:

Command Response

/get trk_enable<LF> /get trk_enable 110<LF>

Indicating track 1 & 2 are enabled, track 3 is disabled.

Section 3. Commands

load_key

Function

Syntax

Load an encryption key into the device.

/load_key n key

n can be one of the following values:

M – master key (key is in clear text)

S – session key (key is encrypted under Master Key)

0 ... 3 – lower working keys (key is encrypted under Session Key)

A ... J – upper working keys (key is encrypted under Session Key)

key is the 16- or 32-character value of the key to be loaded.

Errors

/load_key 30<LF>

If the n field is invalid, key is the wrong length, or the device sends an error (e.g., there is a key parity error).

/load_key 45<LF>

If the required key is not loaded.

Remarks

This command is used to load a key into the device. With all but the master key, the selected key is encrypted under another key so the application must know the encrypted value of the key. The response to this command is: /load_key SS SS is a two digit status code; 00 – success, 30 – invalid, 45 – rejected, etc.

Example

To load the session key encrypted under the master key:

Command Response

/load_key S 99E1E835662DEA94<LF> /load_key 00<LF>

MagTek Device Drivers for Windows

rawrecv

Function

Syntax

Errors

Receive data from the device.

/rawrecv /rawrecv 45<LF>

If a command is already pending.

/rawrecv 82<LF>

If the command was canceled by the user (e.g., with CLEAR key)

Remarks

This command overrides the default processing of the next message that comes from the device and returns it to the application as a rawrecv response. Only one message from the device will be processed in this manner, after that the driver switches to normal operation. The response to this command is in the following format: /rawrecv status x

status is a 2-digit decimal value (refer to Appendix C. Status Codes for a

complete description of the status values)

x is the data received from the device with the following characters replaced:

• <CR> is replaced by \r

• <LF> is replaced by \n

• \ is replaced by \\

Example

• any other non-printable characters are replaced by \xhh, where hh is the

two digit hex code of the character. If a /rawsend command is sent that will cause the device to send back a response, the application should either submit a /rawrecv command before sending the data with /rawsend, or (better) use the /rawxact command.

Note

In some cases, the framing characters in the response are extracted by the driver and are not presented to the application.

To receive card data when the IntelliPIN is operating in the VeriFone mode:

Command Response

/rawrecv<LF> /rawrecv 00 ;12345?<LF>

Section 3. Commands

rawsend

Function

Syntax

Send arbitrary data to the device. /rawsend x

x is an arbitrary string which is transmitted directly to the device. The string x is passed as-is to the device, except for ‘\’ which is used as an ‘escape’ character:

• \r is converted to <CR>

• \n is converted to <LF>

• \\ is converted to \

• \xhh is converted to a character with ASCII value hh (always two hex digits),

e.g., \x20 is converted to a space.

Errors

Remarks

none

This command as with the other raw commands supports any features that have not been implemented in the standard set of commands. Note: the driver inserts appropriate framing characters, e.g., <stx> and <etx> or <si> and <so> for certain IntelliPIN commands.

Example

rawxact

Function

Syntax

Errors

Remarks

To change the default message 00 to show “Welcome to Our Bank” on two lines of the IntelliPIN:

Command

Response

/rawsend 5100Welcome to\x1COur Bank<LF>

none

Note: When using C++, include an extra slash to include the “/r”: “//rawsend…”

Execute a send/receive transaction with the device in raw mode.

/rawxact x

x is an arbitrary string which is transmitted directly to the device. The string x is passed as-is to the device, except for ‘\’ which is used as an ‘escape’ character:

• \r is converted to <CR>

• \n is converted to <LF>

• \\ is converted to \

• \xhh is converted to a character with ASCII value hh (always two hex digits),

e.g., \x20 is converted to a space.

/rawxact 45<LF>

If a command is already pending.

/rawxact 82<LF>

If the command was canceled by the user (e.g., with CLEAR key)

This command is a combination of /rawsend and /rawrecv. It sends the supplied data to the device, overrides the default processing of the next message that comes from the device and returns it to the application as a /rawxact response. After the response is returned (or canceled), the driver switches to normal operation. The syntax for this command is identical to the syntax of the /rawsend command; the syntax of the response is identical to the /rawrecv response.

Example

To load a master key of 23AB4589EF6701CD into the IntelliPIN:

Command Response

/rawxact 9423AB4589EF6701CD<LF> /rawxact 00 940<LF>

MagTek Device Drivers for Windows

read

Function

Syntax

Read data from the device. /read [[x] y]

The optional argument x specifies the data source; if x is missing, a card will be

read. Refer to the Read Argument table below for a description data sources.

The optional argument y is used to specify a message to be displayed on the

LCD screen, if supported, before carrying out the command. If y is omitted and the device supports a display, the text in the msg1 property is shown. In order to use y, the x argument must be present. See the display command for the description of the message format for y.

Errors

/read -00045<LF>

If a command is already pending or the enc_key is not defined for read pin.

/read -00082<LF>

If the command was canceled by the application (82) or by the user (83) (e.g., with CLEAR key).

Remarks

The response to this command has the following format: /read status data The status field is a 6-character string aligned to the right in the arg1 field. It is formatted as follows: TX1X2X3SS

T defines the type of data that was read:

C = a check was read M = a magnetic card was read P = a PIN was read K = a key press or string was read

- = indeterminate: no data was received from the device. Returned on errors

not specific to the data type, such as command canceled (SS=82).

Xi define a media-specific status. For checks, this is the decimal representation of

the check read status, as defined in the MICR specification. For magnetic cards, XXX indicates the read status for each of the three magnetic tracks (see card in the Read Arguments table below for a description of the status). For PIN data this status is always 000; for keypress and string data, XXX is the data length in characters.

SS is a two-digit status code. 00 indicates a good read (but some tracks may be

bad); any other status code indicates an error. These error codes indicate an error in the communication between the driver and the device or driver’s internal errors. Read errors are reported in the Xi fields and do not cause the SS field to be set to a non-zero value. See Appendix C. Status Codes.

write command below.

Example

The data format is described in the

To request an amount to be entered by the customer on the IntelliPIN:

Command

Response

/set entry_len 6<LF> /read key_string Enter the amount<LF> /read K00300 123<LF>

Example

To read a card (from any device):

Command Response

/read card<LF> /read M10900 ;12345?<LF>

track 1 error, track 2 good, track 3 blank

+ 98 hidden pages