Rockwell Automation 1747-PCINT User Manual

Allen-Bradley

API Software for 1746 I/O PCI

User

Interface

(Cat. No. 1747-PCIDOS, -PCINT)

Manual

Important User Information

Because of the variety of uses for the products described in this publication, those res ponsible for the application and use of thi s control equipment must satisfy themselves that all necessary steps have been taken to assure that eac h application and use meets all perfo rmance and safety require ments, inclu ding any applicable laws, regul ations, codes and standards.

The illustrations , charts, sample programs and layou t examples shown in this guide are intended solely for example. Since there are many variables and requi rements a ssociated wi th an y particula r insta llation , Allen-Bradley does not assume responsibility or liability (to include intellectual pr ope rt y liability) for act ual use based upon the example s 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 which should be taken into consideration when applying products such as those described in this publication.

Reproduction of the con tents of this copyr ighted public ation, in whole or in part, without writte n permission of Allen-Bra dley Company , Inc. is prohibited.

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

ATTENTION: Identifies informat ion about pra ctices or circumstances that can lead to personal injury or

Attention helps you to:

death, property damage or economic loss.

• identify a hazard

• avoid the hazard

• recognize the consequences

Important: Identifies information th at is critical for successful

application and understanding of the product.

AMIBIOS is a trademark of American Megatrends, Inc. SystemSoft and CardSoft are trademarks of SystemSoft Corporation. Microsoft and MS-DOS are trademarks of Microsoft.

Using This Manual

Preface

Who Should Use this Manual

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

This manual documents the 1746 I/O PCI Inter face API sof tware for DOS and the API software for Windows NT. The APIs use most of the same calls. Differences are noted as appropriate.

Terminology Throughout the language of t his doc ument, we refer to t he 174 6 I/O PCI Inter face

card (1747-PCIS) as the s canner and the 1747-PCIL cha ssis interface module as the adapter.

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.

Reference Material1746 I/O

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

PCI Interface

This document: 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

MindShare, Inc. Addison-Wesley Publishing Company

ISBN: 0-201-40993-3

Support Due to the PC-based architecture of the 1746 I/O PCI Interface, the telephone

support provided with the purchase price of the 1746 I/O PCI Interface consists primarily of determining if the sys tem software and hardwa re is operating within documented specifications. The tools for this support are:

• diagnostic utility disk that ships with the 1746 I/O PCI Interface

• 1746 I/O PCI Interface system diagnostic LEDs

The diagnostic util i ty disk uses the DOS API as its programming interface, which provides examples of how to u se the API . The diagnosti c utilit y disk i s a good tool to help diagnose your API application software. See appendix B for more information.

When you purchase a 1746 I/O PCI Interface 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-6.5.3 June 1998

Preface–2 Using This Manual

Publication 1747-6.5.3 June 1998

Overview Chapter 1

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

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

The 1746 I/O PCI Interface API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-2

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

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

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

Scanner Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-4

Checking LED Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5

STATUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5

Installing the DOSAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-5

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

Installation Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1-7

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

Using the API Chapter 2

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

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

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

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

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

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

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

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

Sample Windows NT MAKE file for Microsoft compilers. . . . . . . . . . . .2-7

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

Developing Applications Chapter 3

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

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

Programming Sequence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2

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

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

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

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

Scan I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-5

Programming Example for DOS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6

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

Handling Interrupt Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18

Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-18

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

Using the API Structures Chapter 4

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

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

Publication 1747-6.5.3 June 1998

Configuring I/O Modules

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

Library of Routines Chapter 6

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

OC_CalculateCRC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

OC_ClearFault. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

OC_CloseScanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4

OC_ConfigureDII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5

OC_CreateIO

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7

OC_DemandInputScan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9

OC_DemandOutputScan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10

OC_DownloadIO

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11

OC_EnableEOSNotify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13

OC_EnableForces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-15

OC_EnableSlot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17

OC_ErrorMsg. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18

OC_ExtendedErrorMsg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19

OC_GetBatteryStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21

OC_GetDeviceInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-22

OC_GetExtendedError. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23

OC_GetInputImage

UpdateCounter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-25

OC_GetIOConfiguration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-27

OC_GetLastFaultCause. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29

OC_GetMeasuredScan

Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-30

OC_GetScannerInitInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-31

OC_GetScannerStatus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-33

OC_GetScanner

WatchdogCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-35

OC_GetStatusFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36

OC_GetSwitchPosition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40

OC_GetTemperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41

OC_GetUserJumper

State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-42

OC_GetUserLEDState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43

OC_GetVersionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-44

Publication 1747-6.5.3 June 1998

OC_InitScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46

OC_OpenScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48

OC_PetHostWatchdog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49

OC_PollScanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-50

OC_ReadHostRetentive

Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-52

OC_ReadInputImage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-54

OC_ReadIOConfigFile. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-56

OC_ReadModuleFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-57

OC_ReadOutputImage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-59

OC_ReadSRAM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-61

OC_ResetScanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-63

OC_SetForces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-64

OC_SetHostWatchdog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-66

OC_SetInputUpdate

Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-67

OC_SetIOIdleState. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-68

OC_SetModuleInterrupt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-69

OC_SetOutputUpdate

Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-70

OC_SetScanMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-72

OC_SetScanTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-73

OC_SetUserLEDState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-74

OC_SetupPowerFail

Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-75

OC_WaitForDII. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-77

OC_WaitForEos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-78

OC_WaitForEosDmdIn. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-80

OC_WaitForEosDmdOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-82

OC_WaitForExtError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-84

OC_WaitForIoInt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-85

OC_WriteHostRetentive

Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-86

OC_WriteIOConfigFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-87

OC_WriteModuleFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-88

OC_WriteOutputImage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-90

OC_WriteSRAM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-92

iii

Error Codes Appendix A

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

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

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

Testing Function Calls Appendix B

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

Publication 1747-6.5.3 June 1998

Chapter

Overview

Introduction This chapter provides an overview of the 1746 I/O PCI Interface and the API

software. This chapter also descri bes how to in stall the API. You should have one of the following APIs:

• API for DOS (catalog number 1747-PCIDOS)

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

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

Relationship to the Open Controller

The API software fo r the 1746 I/O PCI Int erface is c ompatible wit h the API for the 1747 Open Controller. The sample code and header files contain comments and functions that are support ed by the Open Controller but not supported by the 1746 I/O PCI Interface. The following table lists the differences between the Open Controlle r and the 1746 I/O PCI Interface.

Open Controller 1746 I/O PCI Interface

User assigns interrupts and memory allocation. 1747-PCIS(2) is a plug-and-play card. Watchdog can reset the entire system. Watchdog cannot reset entire system. Contains OC_ReadRtcSRAM. Function not supported. Contains OC_WriteRtcSRAM. Function not supported. Does not provide access to user SRAM. Provides access to user SRAM.

Important: All references to Open Controller in the example code or header files

apply to the 1746 I/O PCI Interface.

Publication 1747-6.5.3 June 1988

1–2 Overview

The 1746 I/O PCI Interface API

Use the 1746 I/O PCI Interface API to develop the software interface between your application and the 1746 I/O PCI Interf ace scanner to control local I/O and to control remote I/O via the 1747-SN or 1747-SDN scanners. 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 dual port memory

local I/O

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

API Softwar e for DOS

The DOS API software provi des a library of C fun cti on cal l s f or DOS application programs to interface with the dual port memory. The DOS API supports any language compiler that uses the Pascal calling convention.

API Softwar e for Windows NT

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

The Windows NT API software consists of two main components:

• the 1746 I/O PCI Interface device driver (OCdriver)

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

Publication 1747-6.5.3 June 1998

Overview 1–3

The Windows NT API library is a DLL and mu st be installed on the system in order to run an application wh ich uses it. The W indows NT API accesses the scanner vi a the driver created for the bus interface The driver:

• allocates resources (interrupt and memory window)

• initializes scanner hardw are

• provides access to the scanner’s dual port RAM

• services interrupts from the scanner (priority messages)

Important: Only access the OCdriver through the AP I library functions. When the OCdriver is loaded it tries to allocat e an inter rupt and a me mory window

for the memory and interr upt that were alloca ted usi ng the set tings by the PCI bus at power-up for the dual port RAM.

Understanding the 1746 I/O PCI Interface Architecture

PCI bus

The 1746 I/O PCI Inter face archit ecture consists of a PCI card that plugs i nto 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

Scanner

CPU

dual port memory

Partition: Bytes: register 1K commands variable response variable output image variable input image variable host data variable

cable

1747-PCIL

1746 backplane interface

status and user LEDs

3-position switch

user jumper

watchdog contact

The dual port is an 8K byte memory partition (optionally battery-backed) that provides an int erface between the integrat ed scanner a nd your applic ation software that resides on the host.

Important: The jumper for the battery-backed dual port memory is disabled by

default. You must switch the jumper in order to enable the dual port memory battery-backed functi on. By enabling the battery-backed dual port memory, you will decrease the life of the battery.

Publication 1747-6.5.3 June 1998

1–4 Overview

Your application (the code y ou develop using the API ) u ses t he dual port memory to communicate with the scann er 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 i ntegrity

• software-generated watchdogs

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

position switch

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

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

• I/O values

• application parameters (timers, counters, presets)

Scanner Modes The scanner CPU operates in six basic modes:

• performing POST (power-on self test)

• waiting for h ost initializa tion

• 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 sc anner can enter Scan mode, the application must download a valid I/O configuration to the scanner.

Publication 1747-6.5.3 June 1998

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

Overview 1–5

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

• POST failure

• background diagnostic failure

• internal watchdog timeout

Checking LED Indicators

PCI INTERFACE

STATUS BATT

LED 1 LED 2

LED 3 LED 4

Installing the DOS API

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 Flashing red An I/O fault has occurred. Check software to identify

Solid red A scanner internal fault has

occurred.

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

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.

None

fault condition. Power system off and back on. If

the problem persists, service may be required.

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

Publication 1747-6.5.3 June 1998

1–6 Overview

Installing the Windows NT API

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

1. Insert the API diskette into a diskette drive.

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

2. Select Run from th e startup men u, then se lect th e

setup.exe program from the

API diskette .

3. Click on OK to execute the s etup utility . Follow the displaye d instructions. Click

on Next.

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

executable files (Complete) or the API executable files (Runtime), or just the API development files (Development). To develop applications with the API, you need the development files. To only run applications, only the runti me files are necessary. The development files consist of an include file, import library, and sample code. The runti me files consist of a d evice driver and a dynamical lylinked library.

Important: Runtime files may only be installed on a W indows NT system.

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

Choose the appropriate installation option and click on Next.

5. Specify the destination directory and click on Next.

6. The necessary fi les a re co pied to t he di sk, and th e syst em reg istr y i s updat ed to

include the OCdriver information.

7. Choose whether to reboot the system now or later and click on Finish. Important: You must shutdown and reboot the scan ner before using the API. (T he

setup utility sets the registry Start parameter for OCd river 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

Publication 1747-6.5.3 June 1998

Overview 1–7

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,

%SystemRoot%\system32\drivers).

(

OCdriver, to the system device driver directory

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 ut ility copi es

ocapi.lib , ocapi.h, and the sample

source files to a development directory.

Uninstalling the Windows NT API

To uninstall Windo ws 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.

3. Click on Add/Remove.

4. Click on Yes.

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

Publication 1747-6.5.3 June 1998

1–8 Overview

Notes:

Publication 1747-6.5.3 June 1998

Chapter

Using the API

Introduction This chapter describes the API and how to use its components. For more information

about developing applications using the API, see chapter 3.

Getting Started To use the API, make sure you ha ve 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 (

ocapi.lib

for Windows NT) and include ocapi.h. Y ou can copy the sample files

and adapt them for your application.

Programming Conventions

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

ocapi.dll) that you link with the host application’s object code using

(

commercially-available tools.

This convention: Considerations:

The DOS API functions are specified using the C programming language syntax. To allow you to develop control applications in other programming languages, the API functions use the standard

calling convention

header files

sample code

compiler support

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.

The API includes a header file (ocapi.h) tha t contains API function declarations, data structure definitions, and other constant definitions. The header file is in standard C format.

The API comes with sample files to provide an example application that communicates with the scanner. The sample files include all source files and MAKE files required to build the sample application.

The DOS API is supplied in the large memory model, compatible with both Microsoft 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++.

ocapil.lib for DOS or

Publication 1747-6.5.3 June 1998

2–2 Using the API

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:

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

memory mapping

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

control-break handler

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.

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]

[Ctrl-Break] key sequence, the following prompt is displayed:

or 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-6.5.3 June 1998

Windows NT Considerations

During development, the application must be linked with an import library that provides information ab out 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-t hread safe, so that mu lti-threaded co ntrol applicati ons 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 threa d w ill be blocke d until it is fre ed.

T o crea te a consis te nt API, caref ul con sider at ion was given to th ese requi reme nts: :

This requirement: Considerations:

The NT API device driver detects the Scanner Adapter and automatically configures the memory window address and inte rrupt assignment. The base memory address jump er must be positioned to choose 32 bit addressing. The API and device driver must be installed on the system.

memory mapping

NT interrupts

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.

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.

Using the API 2–3

A group of thread-block ing functions are provided to aid mult i-threaded application development. The functions are:

• OC_WaitForDII

• OC_WaitForEos

• OC_WaitForEosDmdOut

• OC_WaitForIoInt

• OC_WaitForDmdIn

• OC_WaitForExtError

For more information, see chap ter 6.

Publication 1747-6.5.3 June 1998

2–4 Using the API

Tools to Use The API functions suppo rt both Microsoft and Bor land C compiler s. The AP I disk

includes sample MAKE files for each compiler. When you use the DOS API and link t o

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

ocapil.lib (DOS) or ocapi.lib (Windows NT).

Publication 1747-6.5.3 June 1998

Using the API 2–5

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.

# 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 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

Publication 1747-6.5.3 June 1998

2–6 Using the API

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 enviro nm en t va ri ab le s LI B an d # INCLUDE must be set to the path to the # Microsoft C libr ar y an d in cl ud e fi le s. # 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 # # 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

Publication 1747-6.5.3 June 1998

Using the API 2–7

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 # #---------------------------------------------# 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

Publication 1747-6.5.3 June 1998

2–8 Using the API

!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 #--------------------------------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

Publication 1747-6.5.3 June 1998

Using the API 2–9

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 # correspond to your environment. # #---------------------------------------------CPATH = D:\BC5 # Location of Borland tools CC = $(CPATH)\bin\Bcc32 # compiler LINK = $(CPATH)\bin\TLink32 # linker MAKE = $(CPATH)\bin\Make # make utility

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

#---------------------------------------------# Options #---------------------------------------------CFLAGS = -c -v -4 -tWM -w -I$(APIINC) LFLAGS = -v -Tpe -d -c -ap -r

#---------------------------------------------# Final Target #---------------------------------------------sample.exe : sample.obj $(APILIB) sampleb.mak $(LINK) @&&| $(LFLAGS) + D:\BC5\LIB\c0x32.obj + $*.obj, $*.exe, $*.map D:\BC5\LIB\import32.lib + D:\BC5\LIB\cw32mt.lib + $(APILIB)

Publication 1747-6.5.3 June 1998

2–10 Using the API

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

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

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

#---------------------------------------------# Create a Borland-compatible import library #---------------------------------------------$(APILIB): $(APIDLL) implib $(APILIB) $(APIDLL)

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

Publication 1747-6.5.3 June 1998

Chapter

Developing Applications

Introduction This chapter describ es the proper progra mming sequence for your a pplication. This

chapter also describes how to partition the dual port memory in the 1746 I/O PCI Interface.

How the API Functions Are Organized

Each of the API functions falls into one of these four categories:

• scanner initialization

• scanner I/O configuration

• data input/output

• user interface/miscellaneous

Chapter 6 describes each API function and identifies its functionality group.

Publication 1747-6.5.3 June 1998

3–2 Developing Applications

Programming Sequence

Access the scanner

Follow this programming sequence when you develop your application.

Initialize the scanner

Configure the scanner

Control scanner operation

Scan I/O

Access the scanner

The host applicatio n must first call OC_OpenScanner to ga in access to t he scanner . Once an applicati on has access, no other applicat ion can gain access to the s canner . When the application no longer requires access to the scanner, it must call OC_CloseScanner to release access of the scanner to other applications.

Once the scanner is opened, you must call OC_CloseScanner before exiting the application.

Publication 1747-6.5.3 June 1998

Developing Applications 3–3

Initialize the scanner

After the scanner is reset and performs its POST, the scanner waits for initialization.

In this state, the scanner can’t be configured or control I/O. The only ope rational function is that which co ntrols the LE Ds. Any call to a function that requires the scanner to be initialized returns an error. You must initialize the scanner by sending it partitioning information before the host applicat ion can commun icate with the scanner.

Initialize the scanner by calling the OC_InitScanner function to send the scanner partitioning information, which defines in bytes the size of the output image, the input image, and the host retentive data. Each of these memory segments must be at least large eno ugh t o hold their respective data, and must be an even number. If the input or out put partit ion is init ialized s maller t han the actua l size of the input or output image for a configuration, the OC_DownloadIOConfiguration function returns an error. The host retentive data size is optional and can be 0.

To determine the input image and output image sizes, use the OC_CreateIOConfiguration function to create an I/O configuration. OC_CreateIOConfigurati on returns an I/O co nfiguratio n with the number of by tes of inputs and outputs for each module. If a configuration already exists, you can use OC_GetIOConfig to return the current I/O configuration. The application can then calculate the minimum size of the segments required to hold the input and output images. For more information, see page 3-18.

The API has a defined constant specifying the total number of bytes available for the three segmenters This constant is specified as:

OCSEGMENTSIZELIMIT

Once the scanner has been initialized properly it cannot be re-initialized unless it is reset with the OC_ResetScanner function. Once the scanner is reset, scanner communications are disabled again until the scanner is initialized. The host application can call OC_GetScannerStatus to determine if the scanner has been initialized.

If the scanner was previously initialize d, the host app lication can retrieve the initialization partition information with the OC_GetScannerInitInfo function instead of resetting and re-initializing the scanner.

Configure the scanner

T o access I/O modules in a ra ck, you must define the rack sizes and installed module types for the scanner. You can either create a specific configuration or read the current configuration. The scanner cannot be set to Scan mode until it has been configured (received a valid scanner configuration).

If the scanner is in Scan mode and the host applic ation has not downloaded a scanne r configuration, the scanner has already been configured. To control I/O, use OC_GetIOConfiguration to retrieve the current scanner configuration.

Publication 1747-6.5.3 Junel 1998

3–4 Developing Applications

The application can read the current I/O configuration with the OC_GetIOConfiguration fu nction. If the scanner is not in Scan mode, this fu nction returns the curre nt scan ner conf igu rati on which ca n be down loaded to th e scanne r using OC_DownloadIOConfiguration.

If the application requires a specific I/O configuration, the application can define the I/O configuration structure with the rack sizes and module types installed in each slot. The application passes this configuration structure to OC_CreateIOConfiguration. OC_CreateIOConfiguration returns a scanner configuration that can be downloaded to the scanner. For more information, see chapter 5.

Once a valid scanner configuration is successfully downloaded to the scanner via OC_DownloadIOConfiguration, the application can set the scanner to Scan mode and control I/O.

Both OC_CreateIOConfiguration and OC_GetIOConfiguration build the configuration data from an internal database of supported I/O modules.

Control scanner operation

Once the scanner has been confi gured, the application can control scanner op eration. The host application can:

• set the scanner to Idle or Scan mode

• control the scan time

• control I/O

• read or write module files

• clear faults

• enable/dis able slots

• set I/O Idle state

• install/remove forces

• handle module interrupts and discrete input interrupts

The API uses messages to communicate with the scanner. The scan time settings affect the time allowed by the scanner to process a message. OC_SetScanTi me adjusts the scan time of the application.

The scanner processes messages during any available time that it is not scanning I/O. If the scan time is set too small, some API functions might take a relatively long time to complete. If some functions seem to be taking too long to complete, increase the scan time t o provide more time fo r the scanner t o process message s. If

the scan time is set too la r ge, I/ O won’ t upd at e fast eno ugh. For inf ormati on about estimating scan time, see PCIS Bus Card for 1746 Local I/O Installation

Instructions, publication 1747-5.31.

Publication 1747-6.5.3 June 1998

+ 125 hidden pages

Rockwell Automation 1747-PCINT User Manual

Important User Information

Using This Manual

Table of Contents

Introduction This chapter provides an overview of the 1746 I/O PCI Interface and the API

Relationship to the Open Controller

The 1746 I/O PCI Interface API

Understanding the 1746 I/O PCI Interface Architecture

Scanner Modes The scanner CPU operates in six basic modes:

Installing the DOS API

Installing the Windows NT API

Introduction This chapter describes the API and how to use its components. For more information

Getting Started To use the API, make sure you ha ve copied the following files to your development

Programming Conventions

Tools to Use The API functions suppo rt both Microsoft and Bor land C compiler s. The AP I disk

Introduction This chapter describ es the proper progra mming sequence for your a pplication. This

How the API Functions Are Organized

Programming Sequence