Rockwell Automation 1747-PCIS User Manual

API Software for 1746 I/O PCI Interface and 1747-OC Open Controller

1747-OCF, -PCIS

User Manual

Important User Information

Because of the variety of uses for the products described in this publication, those responsible for the application and use of this control equipment must satisfy themselves that all necessary steps have been taken to assure that each application and use meets all performance and safety requirements, including any applicable laws, regulations, codes and standards.

The illustrations, charts, sample programs and layout examples shown in this guide are intended solely for purposes of example. Since there are many variables and requirements associated with any particular installation, Allen-Bradley does not assume responsibility or liability (to include intellectual property liability) for actual use based upon the examples shown in this publication.

Allen-Bradley publication SGI-1.1, Safety Guidelines for the

Application, Installation and Maintenance of Solid-State Control

(available from your local Allen-Bradley office), describes some important differences between solid-state equipment and electromechanical devices that should be taken into consideration when applying products such as those described in this publication.

Reproduction of the contents of this copyrighted publication, in whole or part, without written permission of Rockwell Automation, is prohibited.

Throughout this manual we use notes to make you aware of safety considerations:

ATTENTION

Identifies information about practices or circumstances that can lead to personal injury or death, property damage or economic loss

Attention statements help you to:

• identify a hazard

• avoid a hazard

• recognize the consequences

IMPORTANT

Allen-Bradley is a trademark of Rockwell Automation

Identifies information that is critical for successful application and understanding of the product.

European Communities (EC) Directive Compliance

If this product has the CE mark it is approved for installation within the European Union and EEA regions. It has been designed and tested to meet the following directives.

EMC Directive

This product is tested to meet the Council Directive 89/336/EC Electromagnetic Compatibility (EMC) by applying the following standards, in whole or in part, documented in a technical construction file:

• EN 50081-2 EMC — Generic Emission Standard, Part 2 —

Industrial Environment

• EN 50082-2 EMC — Generic Immunity Standard, Part 2 —

Industrial Environment

This product is intended for use in an industrial environment.

Low Voltage Directive

This product is tested to meet Council Directive 73/23/EEC Low Voltage, by applying the safety requirements of EN 61131-2 Programmable Controllers, Part 2 - Equipment Requirements and Tests. For specific information required by EN 61131-2, see the appropriate sections in this publication, as well as the Allen-Bradley publication Industrial Automation Wiring and Grounding Guidelines For Noise Immunity, publication 1770-4.1.

This equipment is classified as open equipment and must be mounted in an enclosure during operation to provide safety protection.

Preface

Who Should Use this Manual

Terminology

Reference Material

Use this manual if you are responsible for developing control applications using the 1746 I/O PCI Interface API (application programming interface) software or Open Controller API software in an MS-DOS or Windows NT environment.

This manual documents the 1746 I/O PCI Interface API and Open Controller API software packages for DOS and Windows NT. The APIs use most of the same calls. Differences are noted as appropriate.

Throughout the language of this document, we refer to the 1746 I/O PCI Interface card (1747-PCIS) as the scanner and the 1747-PCIL chassis interface module as the adapter. We also refer to the open controller (1747-OCF) as a scanner.

There are two versions of the PCI Bus Interface Card. 1747-PCIS has a 256k memory capacity and the 1747-PCIS2 has a 1M capacity.

The following books might be useful as you develop your 1746 I/O PCI Interface applications:

This document: Written by: Has this ISBN number:

PC System Architecture Series PCI System Architecture

PCI Hardware and Software Architecture and Design Edward Solari and George Willse ISBN: 0-929392-28-0

In addition to the books listed above, the following books might be useful as you develop your 1746 I/O PCI Interface applications:

This document: By: Has this ISBN number:

PC System Architecture Series ISA System Architecture

The PCMCIA Developerÿs Guide Michael T. Mori and W. Dean Welder ISBN: 0-9640342-1-2

MindShare, Inc. Addison-Wesley Publishing Company

ISBN: 0-201-40993-3

ISBN: 0-201-40996-8

ISBN: 0-201-40991-7

1 Publication 1747-UM002A-US-P - June 2000

Preface 2

Additional Open Controller Documentation

This document: Has this

1747 Open Controller PCI Expansion Bus Installation Instructions 1747-5.16

1747 Open Controller PCMCIA Interface Module Installation Instructions 1747-5.13

1747 Open Controller A-B Communication Interface Module Installation Instructions

1747 Open Controller Video Interface Module Installation Instructions 1747-5.15

1747 Open Controller A-B Communication Interface Module User Manual 1747-6.18

1747 Open Controller IDE Interface Module for IDE-Compatible ATA Devices (PCCards) Installation Instructions

1747 Open Controller IDE Interface Module for an Internally-Mounted 2.5" IDE Drive Installation Instructions

The following documents are available for additional information about the open controller and its options.

publication:

1747-5.14

1747-5.29

1747-5.30

Each open controller component ships with installation instructions. The user manuals are part of the open controller documentation set (catalog number 1747-OCDOC1) so you can order as many copies as you need. The documentation set includes one copy of each open controller document (as listed above).

In addition to the above documentation, the:

• 1747-OCVGA1 video interface module and the 1747-OCVGAE

video and Ethernet interface module include a disk with documentation for the video drivers

• 1747-OCPCM2 PCMCIA interface module kit (1747-OCPCM1

interface module plus CardSoft™ for DOS) includes a disk with CardSoft documentation.

Publication 1747-UM002A-US-P - June 2000

Preface 3

Support

Due to the PC-based architecture of the 1746 I/O PCI Interface and open controller, the telephone support provided with the purchase price of either product consists primarily of determining if the system software and hardware is operating within documented specifications. The tools for this support are:

• diagnostic utility disks that ship with the 1746 I/O PCI Interface

and open controller

• system diagnostic LEDs for 1746 I/O PCI Interface and

open controller

The diagnostic utility disk uses the DOS API as its programming interface, which provides examples of how to use the API. The diagnostic utility disk is a good tool to help diagnose your API application software. See appendix B for more information.

When you purchase either product (1746 I/O PCI Interface system or open controller system), you also receive firmware upgrades during the 12-month warranty period.

You can purchase extended support in blocks of 5 hours by ordering support contracts (1747-OCTS).

Publication 1747-UM002A-US-P - June 2000

Preface 4

Publication 1747-UM002A-US-P - June 2000

Overview

Chapter 1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1

Relationship to the Open Controller. . . . . . . . . . . . . . . . . . 1-1

Interface API to the Scanner . . . . . . . . . . . . . . . . . . . . . . . 1-2

API Software for DOS . . . . . . . . . . . . . . . . . . . . . . . . . 1-2

API Software for Windows NT . . . . . . . . . . . . . . . . . . . 1-3

Understanding the 1746 I/O PCI Interface Architecture . . . . 1-4

Understanding the Open Controller Architecture . . . . . . . . 1-4

Common Attributes of the 1746 I/O PCI Interface and 1747

Open Controller Architectures . . . . . . . . . . . . . . . . . . . 1-5

Scanner Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6

Checking LED Indicators . . . . . . . . . . . . . . . . . . . . . . . 1-7

STATUS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7

Installing the DOS API . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8

Installing the Windows NT API . . . . . . . . . . . . . . . . . . . . . 1-8

Installation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9

Uninstalling the Windows NT API. . . . . . . . . . . . . . . . . 1-10

Using the API

Developing Applications

Chapter 2

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

Programming Conventions . . . . . . . . . . . . . . . . . . . . . . . . 2-2

DOS Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

Windows NT Considerations . . . . . . . . . . . . . . . . . . . . 2-3

Tools to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

Sample DOS MAKE file for Borland compilers. . . . . . . . 2-4

Sample DOS MAKE file for Microsoft compilers. . . . . . . 2-5

Sample Windows NT MAKE file for Microsoft compilers 2-6

Sample Windows NT MAKE file for Borland compilers . 2-8

Chapter 3

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

How the API Functions Are Organized. . . . . . . . . . . . . . . . 3-1

Programming Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

Access the scanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Initialize the scanner . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Configure the scanner . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

Control scanner operation . . . . . . . . . . . . . . . . . . . . . . 3-4

Scan I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

Programming Example for DOS. . . . . . . . . . . . . . . . . . . . . 3-5

Programming Example for Windows NT . . . . . . . . . . . . . . 3-11

Handling Interrupt Messages . . . . . . . . . . . . . . . . . . . . . . . 3-17

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-17

Determining Partition Sizes for Shared Memory . . . . . . . . . 3-18

i Publication 1747-UM002A-US-P - June 2000

Table of Contents ii

Using the API Structures

Configuring I/O Modules

Library of Routines

Chapter 4

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

API Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

Chapter 5

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Configuring I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

Using M0-M1 Files and G Files. . . . . . . . . . . . . . . . . . . . . . 5-3

M0-M1 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

G files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

Supported I/O Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

Chapter 6

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

OC_CalculateCRC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

OC_ClearFault. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

OC_CloseScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

OC_ConfigureDII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

OC_CreateIOConfiguration . . . . . . . . . . . . . . . . . . . . . . . . 6-6

OC_DemandInputScan . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7

OC_DemandOutputScan . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8

OC_DownloadIOConfiguration . . . . . . . . . . . . . . . . . . . . . 6-9

OC_EnableEOSNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10

OC_EnableForces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12

OC_EnableSlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13

OC_ErrorMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14

OC_ExtendedErrorMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15

OC_GetBatteryStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17

OC_GetDeviceInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18

OC_GetExtendedError. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19

OC_GetInputImageUpdateCounter. . . . . . . . . . . . . . . . . . . 6-20

OC_GetIOConfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21

OC_GetLastFaultCause . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22

OC_GetMeasuredScan Time. . . . . . . . . . . . . . . . . . . . . . . . 6-24

OC_GetResetCause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25

OC_GetScannerInitInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26

OC_GetScannerStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27

OC_GetScannerWatchdogCount. . . . . . . . . . . . . . . . . . . . . 6-29

OC_GetStatusFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30

OC_GetSwitchPosition. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-34

OC_GetTemperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35

OC_GetUserJumperState . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36

OC_GetUserLEDState . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-37

OC_GetVersionInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-38

OC_InitScanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-39

Publication 1747-UM002A-US-P - June 2000

Table of Contents iii

OC_OpenScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41

OC_PetHostWatchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43

OC_PollScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44

OC_ReadHostRetentiveData. . . . . . . . . . . . . . . . . . . . . . . . 6-46

OC_ReadInputImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-47

OC_ReadIOConfigFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49

OC_ReadModuleFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-50

OC_ReadOutputImage. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-51

OC_ReadSRAM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-52

OC_ResetScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-54

OC_SetForces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-55

OC_SetHostWatchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56

OC_SetInputUpdateMode . . . . . . . . . . . . . . . . . . . . . . . . . 6-58

OC_SetIOIdleState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59

OC_SetModuleInterrupt. . . . . . . . . . . . . . . . . . . . . . . . . . . 6-60

OC_SetOutputUpdateMode . . . . . . . . . . . . . . . . . . . . . . . . 6-61

OC_SetScanMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-63

OC_SetScanTime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-64

OC_SetUserLEDState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-65

OC_SetupPowerFailAction. . . . . . . . . . . . . . . . . . . . . . . . . 6-66

OC_WaitForDII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-68

OC_WaitForEos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-69

OC_WaitForEosDmdIn . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-70

OC_WaitForEosDmdOut . . . . . . . . . . . . . . . . . . . . . . . . . . 6-71

OC_WaitForExtError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-73

OC_WaitForIoInt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-74

OC_WriteHostRetentiveData . . . . . . . . . . . . . . . . . . . . . . . 6-75

OC_WriteIOConfigFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-76

OC_WriteModuleFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-77

OC_WriteOutputImage . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-78

OC_WriteSRAM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-80

Error Codes

Testing Function Calls

Header File

Appendix A

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Error Code Returned by API Functions. . . . . . . . . . . . . . . . A-1

Extended Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Appendix B

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Appendix C

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

DOS Header File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C-1

Windows NT Header File . . . . . . . . . . . . . . . . . . . . . . . . C-10

Publication 1747-UM002A-US-P - June 2000

Table of Contents iv

Publication 1747-UM002A-US-P - June 2000

Overview

Chapter

Introduction

Relationship to the Open Controller

This chapter provides an overview of the 1746 I/O PCI Interface and the API software. This chapter also describes how to install the API.

You should have one of the following APIs:

• API for DOS (catalog number 1747-PCIDOS or 1747-OCAPID)

• API for Windows NT (catalog number 1747-PCINT or

1747-OCAPINT)

The API software license agreement allows you to freely distribute the executable.

The API software for the 1746 I/O PCI Interface is compatible with the API for the 1747 Open Controller. The sample code and header files contain comments and functions that are supported by the Open Controller but not supported by the 1746 I/O PCI Interface. The following table lists the differences between the 1747-OCF Open Controller and the 1746 I/O PCI Interface.

Open Controller (1747-OCF) 1746 I/O PCI Interface (1746-PCIS)

Watchdog can reset the entire system. Watchdog cannot reset entire system.

API function call OC_GetResetCause returns reason scanner was reset

Dual-port memory not battery-backed Jumper to enable battery-backup for the

IMPORTANT

1 Publication 1747-UM002A-US-P - June 2000

All references to Open Controller in the example code or header files apply to the 1746 I/O PCI Interface.

No function call OC_GetResetCause because the watchdog cannot reset the entire system

dual-port memory

1-2 Overview

Interface API to the Scanner

You must develop a software interface between your application and a scanner to control local I/O and to control remote I/O via the 1747-SN or 1747-SDN scanners. Develop a software interface in one of the following methods:

• Use the 1746 I/O PCI Interface API to develop the interface

between your application and the 1746 I/O PCI Interface scanner.

• Use the API for 1747 Open Controller to develop the interface

between your application and the 1747 Open Controller.

In either application type (1746 I/O PCI Interface or 1747 Open Controller), the API provides calls for typical control functions, such as:

• configuring I/O files

• initializing the scanner

• accessing the user LEDs, user jumper, and 3-position switch

• reading 1746 I/O PCI Interface status

• enabling/disabling forces

Application

API

1746 I/O PCI Interface/Open Controller dual port memory

remote I/O via 1747-SN or 1747-SDN

local I/O

API Software for DOS

The DOS API software provides a library of C function calls for DOS application programs to interface with the dual port memory. The DOS API supports any language compiler that uses the Pascal calling convention.

Publication 1747-UM002A-US-P - June 2000

Overview 1-3

API Software for Windows NT

The Windows NT API supports any programming languages that use the Win32 _stdcall calling convention for application interface functions. The Windows NT API function names are exported from a DLL in undecorated format to simplify access from other programming languages.

The Windows NT API software consists of two main components:

• the OCdriver (depending on your application, either 1746 I/O

PCI Interface device driver or Open Controller device driver)

• the API library, which is a DLL (dynamically-linked library)

The Windows NT API library is a DLL and must be installed on the system in order to run an application which uses it. The Windows NT API accesses the scanner via the driver created for the bus interface The driver:

• allocates resources (interrupt and memory window)

• initializes scanner hardware

• provides access to the scanner’s dual port RAM

• services interrupts from the scanner (priority messages)

• provides access to SRAM

IMPORTANT

Only access the OCdriver through the API library functions.

When the OCdriver is loaded it tries to allocate an interrupt and a memory window for the memory and interrupt that were allocated using the settings by the PCI bus at power-up for the dual port RAM.

If IRQ 11 and address oxC8000 are not available (i.e., another device already allocated the resource), OCdriver tries to allocate any resource for which the scanner hardware can be configured (IRQ 10, 12, and 15; memory address 0xCA000 - 0xDE000). OCdriver fails to load if an interrupt and memory window cannot be allocated.

Once an interrupt and memory window are allocated, OCdriver initializes the scanner hardware to match the allocated resources.

Publication 1747-UM002A-US-P - June 2000

1-4 Overview

Understanding the 1746 I/O PCI Interface Architecture

PCI bus

Scanner

The 1746 I/O PCI Interface architecture consists of a PCI card that plugs into a PC and cables to a 1746 I/O chassis. The scanner scans the 1746 local I/O bus and reads/writes inputs and outputs to/from the dual port registers.

1747-PCIS

CPU

dual port memory

3DUWLWLRQ %\WHV UHJLVWHU . FRPPDQGV YDULDEOH UHVSRQVH YDULDEOH RXWSXWLPDJH YDULDEOH LQSXWLPDJH YDULDEOH KRVWGDWD YDULDEOH

cable

1747-PCIL

1746 backplane interface

status and user LEDs

3-position switch

user jumper

watchdog contact

Understanding the Open Controller Architecture

Open Controller CPU module

scanner

80188

to 1746 local I/O bus

CPU bus memory

scanner firmware

The open controller architecture consists of two CPUs (scanner and controller) that share dual-port memory. The scanner scans the 1746 local I/O bus and reads/writes inputs and outputs to/from the dual-port registers. The controller has a PC-based architecture with a 266Mhz Pentium to run your application software.

PCI

dual port memory

Partition: Bytes: register 1K

commands responses

output image

input image variable

host data variable

variable variable variable

controller (PC-based architecture)

266MHz Pentium

disk bus

memory

BIOS

application software

Publication 1747-UM002A-US-P - June 2000

to 1746 PCI bus

Overview 1-5

Common Attributes of the 1746 I/O PCI Interface and 1747 Open Controller Architectures

The functionality described in the rest of this chapter is shared by both architectures, 1746 I/O PCI Interface and 1747 Open Controller.

The dual port is an 8K byte memory partition (optionally battery-backed) that provides an interface between the integrated scanner and your application software that resides on the host.

IMPORTANT

Your application (the code you develop using the API) uses the dual port memory to communicate with the scanner to handle control functions on the 1746 backplane, such as:

• scanner commands and responses

• battery and scanner status

• scan rate frequency and timing

• I/O image counters

• priority messages and interrupts

• semaphores to ensure data integrity

• software-generated watchdogs

• control of the 4 user-definable LEDs, the 2-position jumper, and

the 3-position switch

On the 1747-PCIS only, the jumper for the battery-backup dual-port memory is disabled by default. You must switch the jumper to enable the battery-backup feature.

The 1747-OCF dual port is NOT battery-backed.

The scanner functionality of the dual port supports I/O control functions, such as:

• synchronizing scans to the application

• forcing I/O

• defining discrete-input interrupts

• defining I/O module-driven interrupts (such as for the 1746-BAS

module)

• enabling and disabling I/O slots

• resetting I/O

Publication 1747-UM002A-US-P - June 2000

1-6 Overview

In addition to providing access to the control scanner, the dual port memory also provides non-volatile (optional battery-backed) storage for:

• I/O values

• application parameters (timers, counters, presets)

Scanner Modes

In both application types, the scanner CPU operates in six basic modes:

• performing POST (power-on self test)

• waiting for host initialization

• Idle

• Scan

• Faulted

• non-recoverable fault

After the scanner successfully completes the POST, the scanner waits for an initialization complete command from the application. Once the scanner receives this command, the scanner enters Idle mode.

Before the scanner can enter Scan mode, the application must download a valid I/O configuration to the scanner.

If a recoverable fault occurs, the scanner enters Faulted mode. Use the OC_ClearFault API function to clear the fault before the scanner can resume operating in Scan mode.

If a non-recoverable fault occurs, reset the scanner (cycle power). Some possible non-recoverable faults include:

Publication 1747-UM002A-US-P - June 2000

• POST failure

• background diagnostic failure

• internal watchdog timeout

Checking LED Indicators

The graphics below show LED displays.

1746 PCI I/O Interface 1747 Open Controller

Overview 1-7

PCI INTERFACE

STATUS BATT

LED 1 LED 2

LED 3 LED 4

OC 266 PENTIUM

STATUS BATT

COM 1 COM 2

LED 1 LED 2

LED 3 LED 4

STATUS

The STATUS indicator reports the status of the scanner. The following table lists the LED states for STATUS:

This state: Means: Take this action:

Yellow The scanner is running POST. None

Flashing green The scanner is in idle mode and

is not scanning I/O.

Solid green The scanner is scanning I/O. None

None

Flashing red An I/O fault has occurred. Check software to identify

fault condition.

Solid red A scanner internal fault has

occurred.

Power system off and back on. If the problem persists, service may be required.

Off The adapter is not powered up. Turn on power.

Publication 1747-UM002A-US-P - June 2000

1-8 Overview

Installing the DOS API

Installing the Windows NT API

To install the DOS API, copy the following files to a directory you create. The sample code files are optional, but they show how to use the API functions.

This file: Contains:

ocapil.lib API functions that you link to your application

ocapi.h API header file that contains API-referenced structures

sample.c Sample application program calling the API functions

sampleb.mak Sample make file for the Borland C compiler

samplem.mak Sample make file for the Microsoft C compiler

To install the Windows NT API, use the setup utility:

TIP

It is recommended that you exit all applications before starting the setup process.

1. Copy the contents of the API diskette to a temporary directory

on the open controllerÿs disk drive. (This step is not necessary if a local diskette drive is connected.) The device driver file is OCdriver.sys.

2. Select Run from the startup menu, then select the setup.exe

program from the temporary directory.

3. Click on OK to execute the setup utility. Follow the displayed

instructions. Click on Continue.

4. The next dialog lets you choose whether to install the API

executable alone (Runtime) or the API executable and the development files (Runtime and & Development). To develop applications with the API, you need the development files. To only run applications, the development files are not necessary. The development files consist of an include file, import library, and sample code.

IMPORTANT

Runtime files may only be installed on a Windows NT system. However, the development files may be installed on either Windows NT or Windows 95 systems.

Publication 1747-UM002A-US-P - June 2000

Choose the appropriate installation option and click on Next.

Overview 1-9

5. Click on Continue.

6. If the development files were selected in the last dialog, the next

dialog allows a destination directory to be specified. Click on Continue after you select the directory.

7. The necessary files are copied to the disk, and the system

registry is updated to include the OCdriver information.

8. Press OK to exit the setup utility. The contents of the

temporary directory can now be deleted.

IMPORTANT

You must shutdown and reboot the scanner before using the API. (The setup utility sets the registry Start parameter for OCdriver to Automatic; therefore, the service manager starts the OCdriver when the system is booted.)

The Windows NT API uses these files:

This file: Contains:

ocapi.lib Import library in Microsoft COFF format

ocapi.h API header file that contains API-referenced structures

ocapi.dll API DLL

sample.c Sample application program calling the API functions

sampleb.mak Sample make file for the Borland C compiler

samplem.mak Sample make file for the Microsoft C compiler

Installation Details

This section describes the actions the setup utility performs to install the API and OCdriver.

If you select Runtime (Complete), the setup utility:

1. copies the device driver file,

driver directory (

%SystemRoot%\system32\drivers).

OCdriver, to the system device

Publication 1747-UM002A-US-P - June 2000

1-10 Overview

2. adds this key and these values to the system registry:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services

OCdriver

ErrorControl: REG_DWORD 0x1

Group: REG_SZ Extended base

Start: REG_DWORD 0x2

Type: REG_DWORD 0x1 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services

Drivers\ OCdriver

EventMessageFile= REG_EXPAND_SZ%SystemRoot%\System32\Drivers\OCdriver.sys

TypesSupported= REG_DWORD 0X00000007

3. copies the library file,

OCapi.dll, to the %SystemRoot%\system32

directory.

If you select Runtime & Development, the setup utility performs the same steps as for Runtime only and the setup utility copies

ocapi.h, and the sample source files to a development directory.

ocapi.lib

If you want to develop your application on a computer other than the open controller, copy the ocapi.lib and ocapi.h files to the development computer (do not run the setup utility on the

development computer). You won’t be able to run your application on the development computer. The runtime API only works on an open controller.

Uninstalling the Windows NT API

To uninstall Windows NT API, use the following instructions.

1. From the Control Panel, select Add/Remove Programs.

2. From the list of installed programs, select Open Control API.

Publication 1747-UM002A-US-P - June 2000

3. Click on Add/Remove.

4. Click on Yes.

All of the API files and registry keys will be deleted.

Using the API

Chapter

Introduction

Getting Started

This chapter describes the API and how to use its components. For more information about developing applications using the API, see chapter 3.

To use the API, make sure you have copied the following files to your development directories. The sample files are optional.

This file: Contains:

ocapil.lib API functions that you link to your application (DOS only)

ocapi.lib Import library in Microsoft COFF format (Windows NT

only)

ocapi.h API header file that contains API-referenced structures

ocapi.dll API DLL (Windows NT only)

sample.c Sample application program calling the API functions

sampleb.mak Sample MAKE file for the Borland C compiler

samplem.mak Sample MAKE file for the Microsoft C compiler

Your application must link to the appropriate library ( DOS or copy the sample files and adapt them for your application.

ocapi.lib for Windows NT) and include ocapi.h. You can

ocapil.lib for

1 Publication 1747-UM002A-US-P - June 2000

2-2 Using the API

Programming Conventions

This convention: Considerations:

calling convention The DOS API functions are specified using the C programming language syntax. To

header files The API includes a header file (ocapi.h) that contains API function declarations,

sample code The API comes with sample files to provide an example application that communicates

compiler support The DOS API is supplied in the large memory model, compatible with both Microsoft

The API is supplied as an object code library file [DOS (ocapil.lib)] or a DLL [NT (

ocapi.dll)] that you link with the host application’s

object code using commercially-available tools.

allow you to develop control applications in other programming languages, the API functions use the standard Pascal calling convention. The Windows NT API supports any programming languages that use the Win32 _stdcall calling convention for application interface functions. The Windows NT API function names are exported from the DLL in undecorated format to simplify access from other programming languages.

data structure definitions, and other constant definitions. The header file is in standard C format.

with the scanner. The sample files include all source files and MAKE files required to build the sample application.

and Borland compilers. The DOS library (ocapil.lib) is compiled as a 16-bit MS-DOS library using the 80386 instruction set. The Windows NT library (ocapi.dll) is compiled for use with Microsoft Visual C++ or Borland C++.

DOS Considerations

The DOS API is as consistent as possible with APIs for other operating system platforms. This makes it easier for you to migrate applications and it simplifies support. To create a consistent API, careful consideration was given to these requirements:

This requirement: Considerations:

memory mapping The dual port RAM, or shared memory, is mapped automatically at power-up by the PCI bus in the

host processor’s memory address space on any even 8K boundary between 0xC0000 and 0xDFFFF. For MS-DOS, it is important that any installed memory managers (such as EMM386) or other TSR software avoid accessing the 8K dual port memory window. Place the base memory select jumper in 1M position to allow the PCI BIOS to assign a base memory address.

DOS interrupts An interrupt is automatically assigned to the scanner by the PCI bus at power-up.

control-break handler Because communication with the scanner requires memory and interrupt resources (as described

above), improper termination of the host application can leave these resources allocated by the scanner and unusable by other applications. For this reason the API includes a default control-break handler. The default control-break handler is installed by OC_OpenScanner. If you press a [Ctrl-C] or [Ctrl-Break] key sequence, the following prompt is displayed: Terminate Application? (Y/N) _ A response of Y properly exits the application; a response of N causes the application to continue. If you need a different control-break handler, you must install it after calling the OC_OpenScanner function. Always call the OC_CloseScanner function before exiting an application.

Publication 1747-UM002A-US-P - June 2000

Windows NT Considerations

During development, the application must be linked with an import library that provides information about the functions contained within the DLL. The API import library is compatible with the Microsoft linker. You can generate import libraries for other programming languages from the DLL.

The Windows NT API can only be accessed by one process at a time. The API is designed to be multi-thread safe, so that multi-threaded control applications can be developed. Where necessary, the API functions acquire a mutex before accessing the scanner interface. In this way, access to the scanner device is serialized. If the mutex is in use by another thread, a thread will be blocked until it is freed.

To create a consistent API, careful consideration was given to these requirements::

This requirement: Considerations:

Using the API 2-3

memory mapping The NT API device driver detects the Scanner Adapter and automatically configures the

memory window address and interrupt assignment. The base memory address jumper must be positioned to choose 32 bit addressing. The API and device driver must be installed on the system. Place the base memory select jumper in 32-bit position to allow the PCI BIOS to assign a base memory address anywhere in 32-bit memory for protected-mode applications (WinNT). NT device drivers (1747-PCINT) use the PCI BIOS or OS services to determine the memory window base address and provide access to the dual port memory.

• To determine the allocated memory base address and interrupt, run the

Windows NT diagnostic found in Administrative Tools.

NT interrupts An interrupt is automatically assigned to the scanner by the PCI bus at power-up

• To determine the allocated memory base address and interrupt, run the

Windows NT diagnostic found in Administrative Tools.

A group of thread-blocking functions are provided to aid multi-threaded application development. The functions are:

• OC_WaitForDII

• OC_WaitForEos

• OC_WaitForEosDmdOut

• OC_WaitForIoInt

• OC_WaitForDmdIn

• OC_WaitForExtError

For more information, see chapter 6.

Publication 1747-UM002A-US-P - June 2000

2-4 Using the API

Tools to Use

The API functions support both Microsoft and Borland C compilers. The API disk includes sample MAKE files for each compiler.

When you use the DOS API and link to

ocapil.lib, use the

appropriate command-line switch to select the large memory model. For more information, see your user manual for your compiler.

If you plan to use a programming language other than C, make sure the programming language follows the appropriate calling convention (Pascal for the DOS API; Win32 _stdcall for Windows NT). After you write your application, use your compiler to link to (DOS) or

ocapi.lib (Windows NT).

ocapil.lib

The follow pages offer sample MAKE files for DOS and Windows NT systems on Microsoft and Borland compilers.

Sample DOS MAKE file for Borland compilers

The following sample file shows how to use a Borland MAKE file. The bold headings indicate the statements you need to modify for your environment.

#************************************************************************ # # Title: Makefile for Open Controller API Sample # # Abstract: # This file is used by the Borland MAKE utility to build the # sample application. # # Environment: # 1747-OCE Open Controller # MS-DOS # Borland C/C++ Compiler (16-bit)# #************************************************************************ #

# Paths to Tools

# # Note: Modify the following paths to # correspond to your environment. # #---------------------------------------------CPATH = D:\BC5 # Location of Borland tools CC = $(CPATH)\bin\Bcc # compiler LINK = $(CPATH)\bin\TLink # linker MAKE = $(CPATH)\bin\Make # make utility

#---------------------------------------------# Path to API Library and Include file # # Note: Modify the following path to # correspond to your environment. # #---------------------------------------------APILIB = ..\ocapil.lib # Path to Open Controller API library

Publication 1747-UM002A-US-P - June 2000

APIINC = .. # Path to Open Controller API include file

#---------------------------------------------# Options #---------------------------------------------CFLAGS = -c -v- -w -ml -I$(APIINC) LFLAGS = -v- -Tde -d -c

sample.exe : sample.obj $(APILIB) sampleb.mak $(LINK) $(LFLAGS) c0l sample.obj, $*.exe, $*.map, $(APILIB) cl

clean: del *.exe del *.obj del *.map

rebuild: $(MAKE) clean $(MAKE) .c.obj: $(CC) $(CFLAGS) $*.c

sample.obj: sample.c $(APIINC)\ocapi.h sampleb.mak

Using the API 2-5

Sample DOS MAKE file for Microsoft compilers

The following sample file shows how to use a Microsoft MAKE file. The bold headings indicate the statements you need to modify for your environment.

#************************************************************************

Title: Makefile for Open Controller API Sample

# Abstract: # This file is used by the Microsoft NMake utility to build the # sample application.

# Environment: # 1747-OCE Open Controller # MS-DOS # Microsoft C/C++ Compiler (16-bit) #************************************************************************

#---------------------------------------------# Note: The environment variables LIB and # INCLUDE must be set to the path to the # Microsoft C library and include files. # For example:

# set LIB=D:\MSVC15\LIB # set INCLUDE=D:\MSVC15\INCLUDE

#---------------------------------------------# Paths to Tools

# Note: Modify the following paths to # correspond to your environment.

#---------------------------------------------CPATH = D:\MSVC15 # Location of Microsoft tools CC = $(CPATH)\bin\cl # compiler LINK = $(CPATH)\bin\link # linker MAKE = $(CPATH)\bin\nmake # make utility

#---------------------------------------------# Path to API Library and Include file

Publication 1747-UM002A-US-P - June 2000

2-6 Using the API

# Note: Modify the following path to # correspond to your environment.

#---------------------------------------------APILIB = ..ocapil.lib # Path to Open Controller API library APIINC = .. # Path to Open Controller API include file

#---------------------------------------------# Options #------------ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -CFLAGS = /c /nologo /G3 /W3 /AL /Oi /D /Gx- /I $(APIINC) LFLAGS = /MAP:A /NOI /PACKC

sample.exe : sample.obj $(APILIB) samplem.mak $(LINK) $(LFLAGS) sample.obj, $*.exe, $*.map, $(APILIB), nul.def

clean: del *.exe del *.obj del *.map

rebuild: $(MAKE) -f samplem.mak clean $(MAKE) -f samplem.mak

.c.obj: $(CC) $(CFLAGS) $*.c

sample.obj: sample.c $(APIINC)\ocapi.h samplem.mak

Sample Windows NT MAKE file for Microsoft compilers

The following sample file shows how to use a Microsoft MAKE file. The bold headings indicate the statements you need to modify for your environment.

#************************************************************************ # Title: Makefile for Open Controller NT API Sample # # Abstract: # This file is used by the Microsoft NMake utility to build the # sample application. # # Environment: # 1747-OCE Open Controller # Microsoft Windows NT 4.0 # Microsoft Visual C++ # # (c)Copyright Allen-Bradley # #************************************************************************

#---------------------------------------------# Note: The environment variable LIB # must be set to the path to the # Microsoft C library files. # For example: # # set LIB=D:\MSDEV\LIB # #----------------------------------------------

Publication 1747-UM002A-US-P - June 2000

Using the API 2-7

# Paths to Tools # # Note: Modify the following paths to # correspond to your environment. # #---------------------------------------------CPATH = D:\MSDEV # Location of Microsoft tools CC = $(CPATH)\bin\cl # compiler LINK = $(CPATH)\bin\link # linker MAKE = $(CPATH)\bin\nmake # make utility

#---------------------------------------------# Path to API Library and Include file # # Note: Modify the following paths to # correspond to your environment. # #---------------------------------------------APILIB = ..\api\lib\ocapi.lib # Path to Open Controller API library APIINC = ..\api\include # Path to Open Controller API include file

#---------------------------------# Compiler/Linker Debugging Options # (Define DEBUG for debugging.) #---------------------------------!ifdef DEBUG CDEBUG = -Zi -Od LDEBUG = -debug:full -debugtype:cv !else CDEBUG = -Ox LDEBUG = /RELEASE !endif

#------------------------------------------# Compiler Options # # -W3 Turn on warnings # -GB Optimize code for 80486/Pentium # -MT Use Multithreaded runtime lib # #------------------------------------------CFLAGS = -W3 -GB -MT \

-I$(APIINC) -I$(CPATH)\include

#---------------------------------# Linker Options # #---------------------------------LFLAGS = /NODEFAULTLIB /SUBSYSTEM:CONSOLE \ /INCREMENTAL:NO /PDB:NONE

#-----------------------------------# Libraries # # libcmt Multithreaded C runtime # kernel32 Base system lib # #-----------------------------------LIBS = libcmt.lib kernel32.lib

#--------------------------------# Final target

Publication 1747-UM002A-US-P - June 2000

2-8 Using the API

#--------------------------------sample.exe : sample.obj $(APILIB) $(LINK) @<< $(LDEBUG) $(LFLAGS) $(LIBS) $**

@echo Finished clean:

del *.exe del *.obj del *.map

rebuild: $(MAKE) -f samplem.mak clean $(MAKE) -f samplem.mak

#-------------------------# Intermediate target rules #-------------------------.c.obj: $(CC) @<< /c $(CDEBUG) $(CFLAGS) $*.c

#--------------------------------# Intermediate target dependancies #---------------------------------

sample.obj: sample.c $(APIINC)\ocapi.h samplem.mak

Sample Windows NT MAKE file for Borland compilers

The following sample file shows how to use a Borland MAKE file. The bold headings indicate the statements you need to modify for your environment.

#************************************************************************ # # Title: Makefile for Open Controller API Sample # # Abstract: # This file is used by the Borland MAKE utility to build the # sample application. # # Environment: # 1747-OCE Open Controller # Microsoft Windows NT 4.0 # Borland C++ Compiler # # (c)Copyright Allen-Bradley # #************************************************************************ #---------------------------------------------# Paths to Tools # # Note: Modify the following paths to

Publication 1747-UM002A-US-P - June 2000

+ 144 hidden pages