MCP Driver information Version 1.01.07 TABLE OF CONTENTS SECTION 1. OVERVIEW SECTION 2. SYSTEM REQUIREMENTS Computer System Operating System Communication System SECTION 3. INSTALLATION Installing driver Uninstalling driver device instance Management Device Instance Overview MCPCFG Utility Overview MCPCFG Command Summary Adding a Device Instance Removing a Device Instance Displaying the List of Device Instances Displaying Device Instance Properties Modifying Device Instance Properties Restarting the MCP Driver Stopping the MCP Driver Device Instance Properties Generic Properties Serial Port Properties Parallel Port Properties SECTION 4. TRACE LOG SECTION 5. INTSTALLING USB SUPPLEMENT ON WINDOWS 95 SECTION 6. RELEASE INFORMATION SECTION 1. OVERVIEW The MCP driver is a kernel-mode driver that provides reliable communications between a user-mode application and an MCP device. It allows user-mode applications to access the features of MCP devices in a uniform way despite the variety of connection interfaces that the devices use. The driver includes a user-mode DLL that provides an easy-to-use interface for user mode applications, simplifying application development. The driver is a Windows Driver Model (WDM) kernel mode driver (.SYS). It operates under the control of the Windows I/O manager and is configured as an Automatic Start driver. The driver is loaded at boot time by the operating system. The driver accesses the controlled devices through standard serial and parallel port support. The part numbers for the MCP driver are: 30037438 Source 30037437 Disk 99510016 Web 99510018 Web Disk Images SECTION 2. SYSTEM REQUIREMENTS COMPUTER SYSTEM The driver requires a 133 MHz Intel Pentium based PC or better. OPERATING SYSTEM The driver is compatible with the following operating systems: 1. Windows NT 4.0 2. Windows 98 3. Windows 95 OSR2 with the USB supplement installed. OSR2 is not an upgrade of Windows 95. It is an OEM Service Release, made available to PC manufacturers for preinstallation on new PCs. An existing non USR2 version of Windows 95 cannot be upgraded even if one has the OSR2.1 installation CD available. Instead it would have to be upgraded to Windows 98. To find out if you have OSR2, check the Windows version number by opening the Control Panel, System Icon. It should have the letter "B" or "C" at the end if it is OSR2. To find out if you have the USB supplement installed, open Control Panel, Add/Remove Programs. Select the Install/Uninstall page. USB Supplement to OSR2 will be listed if it is installed. Note that a PC is not required to have a USB port in order for the USB supplement to be installed. The USB supplement is required because the MCP driver requires WDM support which is supplied by the USB supplement. For important information related to installing the USB supplement on Windows 95, see the Installing USB Supplement ON Windows 95 section in this document. 4. Windows 2000 COMMUNICATION SYSTEM The MCP driver uses the standard operating system drivers for device communication. Under Windows 95/98, the driver uses the VCOMM client API in order to communicate through the serial and parallel ports. Under Windows NT, the MCP driver uses the standard serial and parallel port drivers. The MCP driver does not access the serial/parallel port resources directly. This requires that the standard drivers for those communication ports provided by Windows are started and properly configured. SECTION 3. INSTALLATION INSTALLING DRIVER In Windows NT, only users with Administrator privileges may install system components. Log on as Administrator (or as a user with full administrative privileges) before attempting to install the MCP driver. The driver can only be installed from a directory that uses the short file/folder name format and that does not contain any spaces in the path. Before reinstalling or upgrading the driver the old driver must be uninstalled and the PC must be rebooted. To install the driver: 1. Make sure all the driver files and folders are contained in one folder. If the driver files and folders are stored on multiple disks or in multiple folders named Disk1, Disk2 etc., then copy the contents of all the disks or folders named Disk1, Disk2, etc. to one folder on your hard drive. For example, when finished copying, the following files and folders might be in the destination folder: CFGMGR32.DLL, Devices, MCPAPI.DLL, MCPCFG.EXE, MCPRES.dll, MCPSETUP.BAT, MCPSETUP.INF, pwd__.bat, setupapi.dll, Support, win95, win98 and winnt. 2. Run the MCPSETUP.BAT file. 3. Windows will not display any error messages if the installation completes successfully. 4. After successful installation, Windows will suggest restarting of the system in order for the installation to complete. Temporarily delay rebooting by choosing "No". 5. Open a MS-DOS prompt window. 6. Add a device instance for the device being installed. This can be done in a number of ways. A device instance batch file can be chosen and executed from the Devices folder supplied with the driver. An application program could provide the means for adding device instances. A device instance can be added manually at the MSDOS prompt. See Device Instance sections for details. For example, to manually add a device instance, named IntelliStripe, for a device connected to COM1 using default properties enter the following at the MSDOS prompt: mcpcfg a IntelliStripe Port.Name=COM1 7. Restart the system to finish installing the MCP driver. UNINSTALLING DRIVER To uninstall the driver: 1. Close all applications that interact with the driver. 2. Open Control Panel, Add/Remove Programs. 3. Select the Install/Uninstall page. 4. Find and select the MCP driver entry in the list of installed software (the entry should read "MCP Driver For Mag-Tek Communications Protocol (uninstall)") 5. Click on Add/Remove 6. The MCP entry should disappear from the list. No error messages must be displayed. 7. Restart the system to remove the MCP drivers. Do not reinstall the MCP drivers before restarting. DEVICE INSTANCE MANAGEMENT Device Instance Overview Before the MCP driver can communicate to a device, a device instance needs to be added. This should be done as part of the driver installation routine. A device instance is a logical connection between the MCP driver and an MCP device attached to a communication port on the computer. Creating a device instance assigns a name to a device instance and establishes properties that are used by the driver to communicate with a device. MCPCFG Utility Overview MCPCFG.EXE is a device instance configuration utility. This utility can create, display, modify and remove device instances. In addition, MCPCFG supports several installation-related commands, intended for use only by the installation script. These commands are listed only in the command summary later in this section, but are not described in detail. The utility is installed with the MCP driver. It is copied by the installer into the Windows directory. MCPCFG is a command-line utility, which can be used by an operator to enter commands at the Windows MS-DOS prompt, from a batch file, or from an application. The utility has only limited error checking capabilities so it must be used with care. For example, the entered baud rate parameter's value is not checked for validity. Note that changes made using MCPCFG do not take effect until the driver is restarted. On Windows NT, the driver can be restarted without rebooting by using MCPCFG. On Windows 95 and 98, the system must be rebooted for the changes to take effect. MCPCFG Command Summary This section shows a summary of all commands supported by MCPCFG.EXE. Command Description Device Instance Management mcpcfg a = Add device [= ...] mcpcfg aq = Add device (quiet) [= ...] mcpcfg r Remove device mcpcfg rq Remove device (quiet) mcpcfg l Display devices mcpcfg s = Change settings [= ...] mcpcfg sq = Change settings (quiet) [= ...] mcpcfg p Display device settings Installer Support Commands mcpcfg restart Stop (if started) and restart MCP drivers (NT only) mcpcfg stop Stop (if started) MCP drivers (NT only) mcpcfg osver Determine OS version. mcpcfg reboot Display the standard "Reboot Needed" dialog box, reboot if user answers "Yes" mcpcfg msg Display a message box; wait for user to click OK. mcpcfg wait Start a GUI-based Win32 process and wait for it to terminate. Adding a Device Instance Use the following command to add a new device instance: mcpcfg a Port.Name= [Transport= []] where: is a name chosen for the new device instance. This name must contain only characters that are valid for a file name and should have no '\' characters. The name must be unique, i.e.; no other MCP device should be using it. The new device will be visible under this name to applications using the MCP API. specifies the connection port to which the device is attached. It should specify a valid serial or parallel port. If the port name is not one of the pre-defined system port names (COM1..COM4 or LPT1..LPT3), a Transport setting must also be specified (see below). If one of the standard names is used, MCPCFG will automatically assign the transport type ("Serial" for COMx, "Parallel" for LPTx). specifies the transport type to be used for the device. This setting is optional if a standard connection port is used. If specified, it should be either "Serial" or "Parallel". other device settings may be specified at the time the device instance is created. Any number of additional settings may be specified. The syntax for these is the same as for the mcpcfg s command (see below). If other device settings are not specified, the default property values will be used. These defaults are listed in the properties sections. For Windows NT, Administrator privilege is required to execute this command. Example: mcpcfg a IntelliStripe Port.Name=COM1 The informational and diagnostic messages displayed by this command can be suppressed by using the "quiet" version: mcpcfg aq ... Removing a Device Instance Use the following command syntax to remove an existing device instance. mcpcfg r is a name of the device instance to be removed. This name was specified with the mcpcfg a command when the device was added. For Windows NT, Administrator privilege is required to execute this command. Example: mcpcfg r IntelliStripe The informational and diagnostic messages displayed by this command can be suppressed by using the "quiet" version: mcpcfg rq Displaying the List of Device Instances The following command displays the names of all configured device instances: mcpcfg l For Windows NT, this command may be used without Administrator privilege. Displaying Device Instance Properties To display the current settings for a device instance use the following command: mcpcfg p where: is a name of the device instance. This name was specified with the mcpcfg a command when the device was added. To see a list of existing device instance names, use mcpcfg l. The list displayed contains all properties that can be set for a device instance, whether or not they have been explicitly set by the operator. The values of the properties that have not been explicitly set are displayed as . This means that the driver will use its built-in default value for these properties. Since the actual default values are not known to MCPCFG, it could not display them. Refer to the device instance properties section of this document for the built-in default values of all properties. The mcpcfg p command does not require administrator privilege to be executed on NT. Example: mcpcfg p IntelliStripe Modifying Device Instance Properties To change one or more properties use the following command: mcpcfg s = [= ...] where: is a name of the device instance. is the name of the property to be set. is the new value for the property. If this string is empty, the property is set to the driver's built-in default value. Note that setting the Port.Name or the Transport property to "default" is not allowed. The whole string = should contain no spaces. If the value is a string and it must contain spaces, enclose the whole = expression in double quotes, e.g.: "TraceFilePath=c:\dir with spaces\logfile.txt". Any number of = pairs may be specified with this command (subject to limitations of the Windows command-line interpreter). For Windows NT, Administrator privilege is required to execute the mcpcfg s command. Example: mcpcfg s IntelliStripe Port.BaudRate=9600 Port.TraceEnabled=1 The informational and diagnostic messages displayed by this command can be suppressed by using the "quiet" version: mcpcfg sq = [= ...] Restarting the MCP Driver On Windows NT, MCPCFG can be used to restart the MCP driver, so that changes made using the commands described above can take effect without rebooting the system. On Windows 95 and 98, the system must be rebooted for the changes to take effect. No application should have the MCP driver opened at the time this command is executed. This command stops the MCP device driver and then restarts it. If the MCP driver was not started, no error message is displayed and the driver is started. To restart the MCP driver, use the following command: mcpcfg restart Administrator privilege is required to execute this command. Stopping the MCP Driver On Windows NT, MCPCFG can be used to stop the MCP driver. No application should have the MCP driver opened at the time this command is executed. To stop the MCP device driver, use: mcpcfg stop Administrator privilege is required to execute this command. DEVICE INSTANCE PROPERTIES Generic Properties These properties are used regardless of what communication transport type is used. They are not transport specific. Propery Name Description TraceFilePath Specifies the path and file name of the trace file. Both application message and transport frame trace data are placed in this file if tracing when enabled. If the path does not exist or the file name is invalid, tracing is disabled. Default file is "MCPTRACE.LOG" Default path is the Windows path. MaxTraceFileSize Maximum size (in K-bytes) of the trace file. When this size is reached, no new entries are logged. Note that 1K = 1024 bytes. Due to a limitation in Windows 95 and 98 disk cache management, it is recommended that the trace file size be limited to 1MB for each 16MB of installed memory. Exceeding the recommended limits may cause Windows to run out of memory and/or communications errors to occur. Default is 500 (K bytes) AppendTraceFile If tracing is enabled, the trace file will be cleared when the port is opened if this value is FALSE (0). If TRUE (1), new trace entries are appended to the existing contents of the trace file. Default is FALSE (no append). Core.TraceEnabled Enable or disable application message trace. This type of tracing logs only the application message portion of transported blocks. The message frames and transported blocks that do not contain application messages will not be logged. Another property, the transport dependent Port.TraceEnabled property allows all block content to be logged. Note that enabling this property and the Port.TraceEnabled property at the same time causes duplicate information to be logged. 0 - FALSE - trace disabled (Default) 1 - TRUE - trace enabled Core.ErrorLogLevel Error log level. Specifies the level of the MCP session exceptions to be logged into system event log: warnings, errors, etc. (This property is not related to the message trace utility). This is only used for debugging the driver and should normally be kept at its default setting. Can be one of the following values: 0 - no logging (Default) 1 - log errors only 2 - log everything Core.RspTimeout Message Response Timeout (specified in milliseconds). This is the maximum time required for the device to process an application command request and return a response. If this time expires, the request will be aborted. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. Default is 5000 ms (0 is not allowed). Serial Port Properties These properties are serial port specific. Value Notes Port.Name Serial Port Name to which the device is connected. Can be one of the standard values COM1, COM2, COM3, COM4. There is no default value. This property must be specified when a device instance is added. If one of the standard values is used, the Transport property is automatically set to Serial. If not, the Transport property must be set to Serial manually. Transport For a serial port this property is always set to Serial. It is automatically set if one of the standard values is used for the Port.Name property while adding a device instance. If not, it needs to be set manually. Port.EDCTypeOverride EDC type that the driver should use for all frames sent to or received by the MCP device. Upon protocol initialization, the driver retrieves the supported EDC types from the MCP device. If this property is not -1, the specified EDC type is used instead of the EDC type specified by the device. If EDCTypeOverride is -1, the driver uses the best EDC type supported by the device (CRC first, LRC second, No EDC last). Can be one of the following values: -1 - Use the best EDC type supported by the MCP device. (Default) 0 - No EDC 1 - 16-bit CRC (Cyclic Redundancy Check) 2 - 8-bit LRC (Longitudinal Redundancy Check) Port.TraceEnabled Enable or disable transport block trace. This type of tracing logs all transported blocks. Another property, the transport generic Core.TraceEnabled property allows only the application message portion of blocks to be logged. Note that enabling this property and the Core.TraceEnabled property at the same time causes duplicate information to be logged. 0 - FALSE - trace disabled (Default) 1 - TRUE - trace enabled Port.ErrorLogLevel Error log level. Specifies the level of the MCP session exceptions to be logged into system event log: warnings, errors, etc. (This property is not related to the message trace utility). This is only used for debugging the driver and should normally be kept at its default setting. Can be one of the following values: 0 - no logging (Default) 1 - log errors only 2 - log everything Port.BlockWaitTimeout Block Wait Timeout (specified in milliseconds). Maximum time allowed for a device to confirm it received a frame from the host. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. Default is 250 ms (0 is not allowed). Port.CharacterWaitTimeout Character Wait Timeout (specified in milliseconds). Maximum time allowed between characters when receiving a frame from a device. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. Default is 50 ms (0 is not allowed). Port.BaudRate Serial port baud rate. Valid values are 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600 and 115200. The default value is 9600. Note that baud sync only is intended to work on baud rates 9600 - 115200. Devices normally support only a subset of these values. See the devices technical reference manual to determine which values are supported. Port.Parity Serial port data parity. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. N None E Even (Default) O Odd S Space M Mark Devices normally support only a subset of these values. See the devices technical reference manual to determine which values are supported. Port.StopBits Number of stop bits. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. 1 1 stop bit (Default) 2 2 stop bits Devices normally support only a subset of these values. See the devices technical reference manual to determine which values are supported. Port.BaudSync Specifies whether the driver should submit a synchronization signal to the device or not. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. 0 FALSE - do not synchronize 1 TRUE - synchronize w/device (Default) Devices normally support only a subset of these values. See the devices technical reference manual to determine which values are supported. Parallel Port Properties These properties are parallel port specific. Value Notes Port.Name Parallel Port Name to which the device is connected. Can be one of the standard values LPT1, LPT2, LPT3, LPT4. There is no default value. This property must be specified when a device instance is added. If one of the standard values is used, the Transport property is automatically set to Parallel. If not, the Transport property must be set to Parallel manually. Transport For a parallel port this property is always set to Parallel. It is automatically set if one of the standard values is used for the Port.Name property while adding a device instance. If not, it needs to be set manually. Port.EDCTypeOverride EDC type that the driver should use for all frames sent to or received by the MCP device. Upon protocol initialization, the driver retrieves the supported EDC types from the MCP device. If this property is not -1, the specified EDC type is used instead of the EDC type specified by the device. If EDCTypeOverride is -1, the driver uses the best EDC type supported by the device (CRC first, LRC second, No EDC last). This is an active time property. That means that this property can be changed by an application using the McpSet function and the change will take effect immediately without restarting the driver. Can be one of the following values: -1 - Use the best EDC type supported by the MCP device. (Default) 0 - No EDC 1 - 16-bit CRC (Cyclic Redundancy Check) 2 - 8-bit LRC (Longitudinal Redundancy Check) Port.TraceEnabled Enable or disable transport block trace. This type of tracing logs all transported blocks. Another property, the transport generic Core.TraceEnabled property allows only the application message portion of blocks to be logged. Note that enabling this property and the Core.TraceEnabled property at the same time causes duplicate information to be logged. 0 FALSE - trace disabled (Default) 1 TRUE - trace enabled Port.ErrorLogLevel Error log level. Specifies the level of the MCP session exceptions to be logged into system event log: warnings, errors, etc. (This property is not related to the message trace utility). This is only used for debugging the driver and should normally be kept at its default setting. Can be one of the following values: 0 - no logging (Default) 1 - log errors only 2 - log everything Port.BlockWaitTimeout Block Wait Timeout (specified in milliseconds). Maximum time allowed for a device to confirm it received a frame from the host. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. Default is 250 ms (0 is not allowed). Port.CharacterWaitTimeout Character Wait Timeout (specified in milliseconds). Maximum time allowed between characters when receiving a frame from a device. This property should normally be kept at its default value. This value should only be changed if a device is compatible with other values. Default is 50 ms (0 is not allowed). SECTION 4. TRACE LOG The trace log is a file that logs the communications between the driver and a device. The trace log is used for helping application and device developers during the device development phase. It can be used for diagnosing problems with existing applications. The log can capture complete blocks transmitted and received by the driver or just the application message portion of blocks. The trace file is a text file and can be read using a standard text editor. The trace log utility can be enabled and configured using device instance properties. Details of these properties are in the device instance properties section of this document. These properties control enabling/disabling logging of the entire block, enabling/disabling logging of only the application message portion of the block, the name and path of the trace log file, the size of the trace log file and clearing of the trace log file. The properties are Port.TraceEnabled, Core.TraceEnabled, TraceFilePath, MaxTraceFileSize and AppendTraceFile respectively. Each line in the trace file has the following format: