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.
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.
Preface Who Should Use this Manual 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.
Preface 2 Additional Open Controller Documentation The following documents are available for additional information about the open controller and its options. This document: Has this publication: 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-5.
Preface Support 3 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.
Preface 4 Publication 1747-UM002A-US-P - June 2000
Table of Contents Chapter 1 Overview 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 . . . .
Table of Contents ii Chapter 4 Using the API Structures Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 API Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1 Chapter 5 Configuring I/O Modules Introduction . . . . . . . . . . . . . . Configuring I/O . . . . . . . . . . . Using M0-M1 Files and G Files. M0-M1 files . . . . . . . . . . . . G files . . . . . . . . . . . . . . . . Supported I/O Modules. . . . . . . . . . . . . . . . .
Table of Contents OC_OpenScanner . . . . . . . . OC_PetHostWatchdog . . . . . OC_PollScanner . . . . . . . . . OC_ReadHostRetentiveData. OC_ReadInputImage . . . . . . OC_ReadIOConfigFile . . . . . OC_ReadModuleFile . . . . . . OC_ReadOutputImage. . . . . OC_ReadSRAM . . . . . . . . . . OC_ResetScanner . . . . . . . . OC_SetForces . . . . . . . . . . . OC_SetHostWatchdog . . . . . OC_SetInputUpdateMode . . OC_SetIOIdleState. . . . . . . . OC_SetModuleInterrupt . . . . OC_SetOutputUpdateMode .
Table of Contents iv Publication 1747-UM002A-US-P - June 2000
Chapter 1 Overview Introduction 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.
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.
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.
1-4 Overview Understanding the 1746 I/O PCI Interface Architecture 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 1747-PCIL 1746 backplane interface dual port memory Scanner CPU PCI bus cable 3DUWLWLRQ %\WHV UHJLVWHU .
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.
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 i
Overview 1-7 Checking LED Indicators The graphics below show LED displays. 1746 PCI I/O Interface PCI INTERFACE STATUS 1747 Open Controller OC 266 PENTIUM BATT LED 1 LED 2 LED 3 LED 4 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.
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.
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.
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.
Chapter 2 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 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.
2-2 Using the API Programming Conventions 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. This convention: Considerations: calling convention 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 Pascal calling convention.
Using the API 2-3 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.
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.
Using the API APIINC = .. 2-5 # 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.
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.
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.
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.
Using the API 2-9 # 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.
2-10 Using the API Notes: Publication 1747-UM002A-US-P - June 2000
Chapter 3 Developing Applications Introduction This chapter describes the proper programming sequence for your application. This chapter also describes how to partition the dual port memory in the 1746 I/O PCI Interface.
3-2 Developing Applications Access the scanner The host application must first call OC_OpenScanner to gain access to the scanner. Once an application has access, no other application can gain access to the scanner. 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.
Developing Applications 3-3 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.
3-4 Developing Applications Control scanner operation Once the scanner has been configured, the application can control scanner operation. 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/disable 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.
Developing Applications 3-5 The application can change the behavior of the input and output scans by allowing the application to have more control over I/O scanning. The application can prevent the scanner from doing any output scans and allow the application to read inputs and initialize outputs before the scanner begins to write outputs. This mode allows the application to pre-scan the inputs before the outputs are written.
3-6 Developing Applications /*======================================================================= = INCLUDE FILES = =========================================================================*/ #include ”ocapi.h” #include #include #include #include #include
Developing Applications 3-7 /* ** Reset the scanner */ printf( ”\n\n Going to reset OC, takes 6 seconds to complete...
3-8 Developing Applications } printf( ”\n\n Switch position: ” ); switch( swpos ) { case SWITCH_TOP: printf( ”Top \n” ); break; case SWITCH_BOTTOM: printf( ”Bottom \n” ); break; case SWITCH_MIDDLE: printf( ”Middle \n” ); break; } delay( 3000 ); /* ** Read auto-config */ retcode = OC_GetIOConfiguration( Handle, &OCcfg ); if ( retcode != SUCCESS ) { printf( ”\nERROR: OC_GetIOConfiguration failed: %d\n”, retcode ); Ioexit( 1 ); } /* ** Display rack configuration */ slots = OCcfg.Rack1Size + OCcfg.
Developing Applications /* ** Download the configuration to the scanner */ retcode = OC_DownloadIOConfiguration( Handle, &OCcfg ); if ( retcode != SUCCESS ) { printf( ”\nERROR: OC_DownloadIOConfiguration failed: %d\n”, retcode ); Ioexit( 1 ); } 3-9 Configure the scanner.
3-10 Developing Applications /* ** Read first Input word */ retcode = OC_ReadInputImage( Handle, NULL, input_slot, 0, 1, &wData ); if ( retcode != SUCCESS ) { printf( ”\nERROR: OC_ReadInputImage failed: %d\n”, retcode ); Ioexit( 1 ); } printf( ”\n\n First input image data word --> 0x%04x \n”, wData ); delay( 3000 ); /* ** Write to the first Output word */ printf( ”\n\n Incrementing first discrete output word.
Developing Applications 3-11 OC_ExtendedErrorMsg(Handle, &exterr, &msg); printf(”\nERROR: %s\n”, msg); } } OC_CloseScanner(Handle); exit(retcode); } /* end Ioexit() */ Programming Example for Windows NT The following Windows NT example (sample.c on your Windows NT API disk) shows how to program the above steps. Callouts on the right margin identify the code for each step.
3-12 Developing Applications * * External effects: * The program is terminated. * * Return value: * none * * Access: Public * ----------------------------------------------------------------------* Notes: * *************************************************************************/ void Ioexit int rc ) { OCEXTERR exterr; char *msg; if (OC_GetExtendedError(OChandle, &exterr) == SUCCESS) { if ( exterr.ErrorCode != 0 ) { OC_ExtendedErrorMsg(OChandle, &exterr, &msg); printf("\n\nERROR: %d %s\n", msg, exterr.
Developing Applications /************************************************************************ * * Entry point: * main * * Description: * Entry point of the PCI I/O bus interface API sample application. * * This program resets, initializes, and autoconfigures the scanner. * It displays the scanner firmware and hardware versions, and * the front panel switch position. * It lights User LED 1, reads inputs from a 32 pt discrete * input module, and writes data to the M0 file on a BAS module.
3-14 Developing Applications /* Reset the scanner */ printf("\nResetting the scanner...
Developing Applications 3-15 printf("\nERROR: OC_GetTemperature failed: %d\n", rc); Ioexit(1); } printf("\nTemperature: %dC ", temp); /* Read auto-config */ if (SUCCESS != (rc = OC_GetIOConfiguration(OChandle, &OCcfg))) { printf("\nERROR: OC_GetIOConfiguration failed: %d\n", rc); Ioexit(1); } /* Display rack configuration */ slots = OCcfg.Rack1Size + OCcfg.Rack2Size + OCcfg.Rack3Size; if ( slots > 31 ) slots = 31; printf("\n\nRack configuration:"); for (i=1; i
3-16 Developing Applications /* Download the configuration to the scanner */ if (SUCCESS != (rc = OC_DownloadIOConfiguration(OChandle, &OCcfg))) { printf("\nERROR: OC_DownloadIOConfiguration failed: %d\n", rc); Ioexit(1); } Configure the scanner.
Developing Applications Handling Interrupt Messages 3-17 Modules that communicate via discrete input interrupts or module interrupts require special attention. The API buffers these interrupts internally until they are extracted via OC_PollScanner. The internal message buffer can hold as many as 5 messages. If the message buffer is full, the oldest message in the buffer is overwritten by the next message.
3-18 Developing Applications Determining Partition Sizes for Shared Memory The host application initializes the scanner by providing partitioning information, which contains the size of memory to be reserved in the shared memory for the input and output images. The size of memory to be reserved for each of the images must be greater than or equal to the number of input and output words required by each module. The host application can’t communicate with the scanner until it has been initialized.
Developing Applications 3-19 Any remaining shared memory can be allocated for host retentive data, which is the portion of the dual port RAM that you can use to store data in case power fails. If the application doesn’t need host retentive data, set its size to 0. If the application needs host retentive data, the application can determine the amount of memory available by using the OCSEGMENTSIZELIMIT constant. This constant specifies the total number of bytes available for the three segment sizes.
3-20 Developing Applications Notes: Publication 1747-UM002A-US-P - June 2000
Chapter 4 Using the API Structures Introduction This chapter describes the structures the API uses. These structures are declared in ocapi.h. API Structures The table below list API structures. 1 Structure Name: Syntax: DII_CFG Passed to OC_ConfigureDII. Configures a discrete input interrupt for a module. typedef struct tagDII_CFG FORCEDATA Passed to OC_SetForces. Configures input and output forces.
4-2 Using the API Structures Structure Name: Syntax: OCIOCFG Used by OC_CreateIOConfiguration, OC_GetIOConfiguration, and OC_DownloadIOConfiguratio n. Configuration information for a system. 1, 2, or 3 racks may be configured for up to 30 I/O modules. (Slot 0 is reserved for the 1746 I/O PCI Interface.
Chapter 5 Configuring I/O Modules Introduction This chapter explains how to configure the I/O modules for your 1746 I/O PCI Interface system. You can either use the autoconfigure (OC_GetIOConfiguration) function or build your own configuration (OC_CreateIOConfiguration). A separate I/O configuration utility is available for the PCI SLC I/O bus interface to simplify this process. The utility is on the 1746 I/O PCI Interface utilities disk that ships with the 1746 I/O PCI Interface (1747-PCIS[2]).
5-2 Configuring I/O Modules SlotCfg contains information about each slot in the racks. The 1746 I/O PCI Interface supports as many as 31 slots, numbered 0 to 30. Slot 0 is the adapter slot (left slot of rack 1) and is invalid for scanner functions.
Configuring I/O Modules Using M0-M1 Files and G Files 5-3 The 1746 I/O PCI Interface uses M0-M1 files and G files to download configuration information to specialty I/O modules. The following descriptions describe the basics of M0-M1 and G files. For detailed information, see the user manual for the specialty I/O module you are configuring. M0-M1 files M0 and M1 files are data files that reside in specialty I/O modules only.
5-4 Configuring I/O Modules Supported I/O Modules Module Name:1 AMCI-1561 1203-SM1 Class1 1203-SM1 Class 4 1394-SJT 1746-IA4 1746-IA8 1746-IA16 1746-IB8 1746-IB16 1746-IB32 1746-IC16 1746-IH16 1746-IG16 1746-IM4 1746-IM8 1746-IM16 1746-IN16 1746-ITB16 1746-ITV16 1746-IV8 1746-IV16 1746-IV32 1746-OA8 1746-OA16 1746-OAP12 1746-OB8 1746-OB16 1746-OB16E 1746-OB32 1746-OBP8 1746-OBP16 1746-OG16 1746-OV8 1746-OV16 1746-OV32 1746-OW4 1746-OW8 1746-OW16 1746-OX8 1746-OVP16 1 2 Description: Class: 4-Input 100/1
Configuring I/O Modules Type: 0 0 0 1 1 1 1 1 1 1 3 1 1 1 1 1 1 1 1 1 3 1 3 1 1 Mix:2 8 11 15 35 35 35 35 35 44 35 127 32 32 32 32 54 54 35 35 35 127 33 101 35 35 BASIC Module - 5/02 Configuration 4 131 6 1747-DCM1F Synchronized Axes Open Loop Velocity Direct Commun. Module (1/4 RACK) 4 4 1 136 131 32 27 15 25 1747-DCM2F Direct Commun. Module (1/2 RACK) 1 33 25 1747-DCM3F Direct Commun. Module (3/4 RACK) 1 34 25 1747-DCM4F 1747-MNET 1747-SDN 1747-SN Direct Commun.
5-6 Configuring I/O Modules Notes: Publication 1747-UM002A-US-P - June 2000
Chapter 6 Library of Routines Introduction The MS-DOS API is a run-time library that can be linked with most industry standard programming language compilers using the Pascal calling convention. The Windows NT API is a 32-bit DLL that can be linked with most industry-standard programming language compilers. This chapter provides the programming information for each routine and identifies which operating system supports the routine. The calling convention for each API function is shown in C format.
6-2 Library of Routines Example: BYTE WORD int buffer[100]; buffer_crc; retcode; retcode = OC_CalculateCRC( buffer, 100, &buffer_crc ); OC_ClearFault OC_ClearFault clears any fault condition of the scanner. Syntax: int OC_ClearFault(HANDLE handle); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner Description: All extended error information must be retrieved before the fault can be cleared.
Library of Routines OC_CloseScanner 6-3 This function must always be called before exiting the application. Syntax: int OC_CloseScanner(HANDLE handle); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner Description: This function releases control of the scanner device, releases the interrupt assigned by OC_OpenScanner, and disables the segment address assignment.
6-4 Library of Routines OC_ConfigureDII OC_ConfigureDII allows an application to receive a message from the scanner when an input bit pattern of a discrete I/O module matches a compare value.
Library of Routines This value: 6-5 Means: IOEdgeType Defines the bit pattern to compare. Only bits that correspond to bits set to 1 in IOIncludeMask are used. Only bits 0 - 7 are valid. IOEdgeType is a bit-mapped value. If a bit is set to 1, the comparison for the bit matches when its corresponding discrete input bit changes from 0 to 1. If a bit is set to 0, the comparison for the bit matches when its corresponding discrete input bit changes from 1 to 0.
6-6 Library of Routines OC_CreateIO Configuration OC_CreateIOConfiguration creates a scanner configuration from an application-specific installation of rack sizes and installed modules. See chapter 5 for more information. Syntax: int OC_CreateIOConfiguration(OCIOCFG *iocfg); Parameters: Parameter: Description: iocfg Specifies the rack sizes and installed modules Description: Modules can be specified by name or by mix and type.
Library of Routines 6-7 Example: OCIOCFG int char iocfg; retcode, numslots, i; module_name[] = ”1746-BAS”; iocfg.Rack1Size = 10;/* 10 slot chassis */ iocfg.Rack2Size = 7;/* 7 slot chassis */ iocfg.Rack3Size = 0;/* Only 2 chassis */ numslots = iocfg.Rack1Size + iocfg.Rack2Size + iocfg.Rack3Size; for ( i=1; i
6-8 Library of Routines The scanner updates the input image with data read from the modules. Use OC_ReadInputImage to read data from the input image.
Library of Routines 6-9 Return Value: Name: Value: Description: SUCCESS 0 demand output request was successful ERR_OCACCESS 2 handle does not have access to scanner ERR_OCRESPONSE 10 scanner did not respond to request ERR_OCSCANCFG 14 scanner has not been configured Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE int Handle; retcode; retcode = OC_DemandOutputScan( Handle, OCWAIT ); OC_DownloadIO Configuration OC_DownloadIOConfiguration do
6-10 Library of Routines BYTE BYTE BYTE OCSLOTCFG Rack1Size;/* number of slots in Rack 1 */ Rack2Size;/* number of slots in Rack 2 */ Rack3Size;/* number of slots in Rack 3 */ SlotCfg[OCMAXSLOT];/* configuration for each slot */ } OCIOCFG; Return Value: Name: Value: Description: SUCCESS 0 I/O configuration was downloaded successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner ERR_OCOUTOFMEM 17 unable to allocate
Library of Routines 6-11 Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: EOSMSG_ENABLE the scanner generates an end-of-scan message after each scan. Use the OC_PollScanner function to retrieve end-of-scan messages. EOSMSG_DISABLE the scanner does not generate End-of-scan messages. End-of-scan messages are disabled after the scanner has been reset.
6-12 Library of Routines Example: HANDLE int Handle; retcode; retcode = OC_EnableEOSNotify( Handle, EOSMSG_ENABLE ); /* Use OC_PollScanner() to check EOS messages */ OC_EnableForces OC_EnableForces enables/disables forces for all inputs and outputs with entries in the force files on the scanner. ATTENTION ! Enabling forces will potentially change the output data values that your application was previously controlling.
Library of Routines 6-13 Return Value: Name: Value: Description: SUCCESS 0 forces were updated successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCNOFORCES 15 no forces installed, scanner cannot enable forces ERR_OCPARAM 8 parameter contains invalid value ERR_OCRESPONSE 10 scanner did not respond to request ERR_OCSCANCFG 14 scanner has not been configured Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE int Handle;
6-14 Library of Routines Description: This function enables or disables the scanner from scanning the module in a specific slotnum. This applies to both the input and output scan. Slots that are disabled are not included in the I/O scan. By default, all slots are enabled.
Library of Routines 6-15 Return Value: Name: Description: SUCCESS errcode was valid. msg points to corresponding error description. ERR_OCPARAM errcode was invalid. msg points to unknown error code string. Considerations: Supported in the DOS API library and the Windows NT API library.
6-16 Library of Routines Description: This function is useful when displaying an error message. You should use OC_GetExtendedError to obtain the message before using OC_ExtendedErrorMsg to display the message. If you don’t use OC_GetExtendedError first, OC_ExtendedErrorMsg displays a null message.
Library of Routines OC_GetBatteryStatus 6-17 OC_GetBatteryStatus gets the current state of the battery of the scanner. Syntax: int OC_GetBatteryStatus(HANDLE handle, BYTE *batstate); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner batstate If batstate is: BATTERY_GOOD battery voltage is good BATTERY_LOW battery voltage has dropped below a reliable level Description: The battery provides backup power for the host retentive data (dual port RAM).
6-18 Library of Routines OC_GetDeviceInfo OC_GeDeviceInfo returns information about the scanner device.
Library of Routines OC_GetExtendedError 6-19 OC_GetExtendedError reads extended error information from the scanner. Syntax: int *buf); OC_GetExtendedError(HANDLE handle, OCEXTERR Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner buf Contains the extended error information If no extended error information is available, the error code field of buf will be 0. Description: The extended error information is written during Scan mode or its configuration.
6-20 Library of Routines Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE OCEXTERR int Handle; exterr; retcode; retcode = OC_GetExtendedError( Handle, &exterr ); OC_GetInputImage UpdateCounter OC_GetInputImageUpdateCounter reads the value of the input image update counter from the scanner and places it into count.
Library of Routines 6-21 Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE BYTE int Handle; count; retcode; retcode = OC_GetInputImageUpdateCounter( Handle, &count ); OC_GetIOConfiguration OC_GetIOConfiguration queries the I/O rack about the installed rack sizes and I/O modules in each 1746 chassis. ATTENTION ! OC_GetIOConfiguration can take several milliseconds to complete, depending upon the rack configuration.
6-22 Library of Routines BYTE OCSLOTCFG slot */ } OCIOCFG; Rack3Size;/* number of slots in Rack 3 */ SlotCfg[OCMAXSLOT];/* configuration for each Return Value: Name: Value: Description: SUCCESS 0 I/O configuration was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner ERR_OCRESPONSE 10 scanner did not respond to request Considerations: Supported in the DOS API library and the Windows NT API library Exa
Library of Routines 6-23 Description: When the scanner faults, an extended error is generated. The error code and slot number of the most recent fault is retained and returned by this function. The fault cause is a duplicate of the most recent extended error. The OC_ClearFault function clears the fault in the scanner but does not clear the cause of the last fault. See Appendix A for error codes.
6-24 Library of Routines OC_GetMeasuredScan Time OC_GetMeasuredScanTime returns the maximum and last observed I/ O scan times. Syntax: int OC_GetMeasuredScanTime(HANDLE Handle, WORD *maxtime, WORD *lasttime); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner maxtime Returns the maximum scan time lasttime Returns the last scan time Description: The scanner calculates these values at the end of each I/O scan.
Library of Routines OC_GetResetCause 6-25 This function can only be used on the 1747-OCF controller. The 1747-PCIS cannot reset the host. Syntax: int OC_GetResetCause (HANDLE, handle, int *Cause); Description: OC_GetResetCause returns the reason the scanner was last reset. Handle must be a valid handle returned from OC_OpenScanner. The cause of the last scanner reset is written to the address pointed to by Cause. If Cause is RESET_HOST_WD, the last scanner reset was caused by a Host Watchdog timeout.
6-26 Library of Routines OC_GetScannerInitInfo This function retrieves current information about the shared memory partitioning. Syntax: int *scaninit); OC_GetScannerInitInfo(HANDLE handle, OCINIT Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner scaninit Points to the structure that contains the initialization information this function returns Description: If the scanner has not been initialized, OC_GetScannerInitInfo returns an error.
Library of Routines 6-27 Example: HANDLE OCINIT int Handle; scaninit; retcode; retcode = OC_GetScannerInitInfo( Handle, &scaninit ); if ( retcode == SUCCESS ) { printf( ”Input Image Size = %d bytes \n”, scaninit.InputImageSize ); printf( ”Output Image Size = %d bytes \n”, scaninit.OutputImageSize ); printf( ”Host Retentive Data Size = %d bytes \n”, scaninit.HostRetentiveDataSize ); } else /* handle error */ OC_GetScannerStatus OC_GetScannerStatus reads the current status of the scanner.
6-28 Library of Routines Description: If OC_GetScannerStatus returns SUCCESS, scansts has one of these values: This value: Has this hex value: Means the: SCANSTS_BPIC 4 POST backplane IC test failed; scanner is halted SCANSTS_CRC 2 software CRC checksum failed SCANSTS_DPR 5 POST dual port RAM test failed; scanner is halted SCANSTS_FAULT 13 scanner faulted; scanner is in Scan mode SCANSTS_IDLE 11 scanner initialized; scanner is in Idle mode SCANSTS_INIT 10 POST passed; waiting for OC_In
Library of Routines OC_GetScanner WatchdogCount 6-29 OC_GetScannerWatchdogCount reads the contents of the watchdog register of the scanner. Syntax: int *count); OC_GetScannerWatchdogCount(HANDLE handle, BYTE Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner count Returns the watchdog register contents Description: The watchdog register is incremented by the scanner after every timed I/O scan.
6-30 Library of Routines OC_GetStatusFile OC_GetStatusFile reads a copy of the current scanner system status file into the STSFILE structure pointed to by stsfil on the scanner. Syntax: int *stsfil); OC_GetStatusFile(HANDLE handle, STSFILE Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner stsfil Points to the STSFILE structure that contains scanner system status Description: The status file is updated by the scanner at the end of each I/O scan.
Library of Routines 6-31 Word/Bit: Classification: Description: 0/7 to 0/12 reserved 0/13 dynamic configuration 0/14 reserved 0/15 status 1/0 to 1/10 reserved 1/11 status Battery low bit This bit is set by the scanner when the Battery Low LED is on. It is cleared when the Battery Low LED is off. 1/12 status DII overflow bit This bit is set by the scanner when a DII interrupt occurs and the scanner is unable to successfully transmit the DII Received priority message to the host.
6-32 Library of Routines Word/Bit: Classification: Description: 7 to 8 status I/O interrupt pending These two words are bit-mapped to the 30 I/O slots. Bits 7/1 through 8/14 refer to slots 1-30. Bits 7/0 and 8/15 are not used. The pending bit associated with a slot is set when an interrupt request is received from that slot. This bit is set regardless of the state of the I/O interrupt enabled bit (wee word 9 and 10).
Library of Routines 6-33 Word/Bit: Classification: Description: 16 dynamic configuration DII compare value This word contains a bit-mapped value that corresponds to the bit transitions that must occur in the discrete I/O module for a count or interrupt to occur. Only bits 0-7 are used in the DII function. Setting a bit indicates that the bit must transition from a 0 to a 1 to satisfy the compare condition for that bit.
6-34 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 system status file was read successfully ERR_OCACCESS 2 handle does not have access to scanner Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE STSFILE int Handle; stsfile; retcode; retcode = OC_GetStatusFile( Handle, &stsfile ); OC_GetSwitchPosition OC_GetSwitchPosition reads the current position of the three-position front-panel switch from the scanner.
Library of Routines 6-35 Return Value: Name: Value: Description: SUCCESS 0 switch position was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE BYTE int Handle; sw_pos; retcode; retcode = OC_GetSwitchPosition( Handle, &sw_pos ); if ( sw_pos == SWITCH_BOTTOM ) OC_SetScanMode ( Handle, SCAN_IDLE ); OC_GetTempe
6-36 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 temperature was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE BYTE int Handle; temp; retcode; retcode = OC_GetTemperature( Handle, &temp ); OC_GetUserJumper State OC_GetUserJumperState reads the state of the user selectable jumper
Library of Routines 6-37 Return Value: Name: Value: Description: SUCCESS 0 switch position was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE BYTE int Handle; jmpr; retcode; retcode = OC_GetUserJumperState( Handle, &jmpr ); OC_GetUserLEDState OC_GetUserLEDState reads the status of one of the four user-def
6-38 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 LED was read successfully ERR_OCACCESS 2 handle does not have access to scanner Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE int int Handle; led_state; retcode; retcode = OC_GetUserLEDState( Handle, 1, &led_state ); OC_GetVersionInfo OC_GetVersionInfo retrieves the current version of the API library, 1746 I/O PCI Interface hardware, and scanner firmware.
Library of Routines 6-39 WORD OCHardwareRevision; /* Hardware revision */ } OCVERSIONINFO; The Windows NT version uses the above structure with these additional members: WORD WORD OCDriverSeries; / * Device driver series */ OCDriverRevision / * Device driver series revision */ Return Value: Name: Value: Description: SUCCESS 0 version information was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner Consi
6-40 Library of Routines Description: If the scanner is executing POST when this function is called, ERR_OCPOST is returned. If the scanner has been previously initialized and the partition information in scaninit is identical to the current scanner partitioning, OC_InitScanner returns successfully.
Library of Routines 6-41 scaninit.InputImageSize = 128; / * 64 words for input image */ scaninit.OutputImageSize = 128; / * 64 words for output image */ scaninit.HostRetentiveDataSize = 500; / * 256 words for host data area */ retcode = OC_InitScanner( Handle, &scaninit ); OC_OpenScanner OC_OpenScanner acquires access to the scanner device and sets a unique ID that the application uses to access the scanner in subsequent functions.
6-42 Library of Routines The shared memory segment address must be set to an address that does not conflict with other hardware and software. The recommended segment address is 0xC800. You can use any of the following shared segment addresses (listed in hex): • • • • • • • • C000 - D000 C200 - D200 C400 - D400 C600 - D600 C800 - D800 CA00 - DA00 CC00 - DC00 CE00 - DE00 irqnum defines the ISA-bus interrupt number assigned to the scanner.
Library of Routines 6-43 Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE int Handle; retcode; retcode = OC_OpenScanner(&Handle, 0, 0 ); if OC_OpenScanner(&Handle, 0xC800, IRQ11) ! = SUCCESS) {printf(‘Scanner could not be opened!\n’);} OC_PetHostWatchdog OC_PetHostWatchdog increments the host-to-scanner watchdog register of the scanner.
6-44 Library of Routines OC_PollScanner OC_PollScanner reads module I/O interrupt, discrete input interrupt, and end-of-scan notification messages from the scanner.
Library of Routines 6-45 The MsgID member of the msgbuf structure will be one of the following values: This value: Means: OCMSG_NONE No message available OCMSG_IOINIT I/O module interrupt message, see OC_SetModuleInterrupt OCMSG_DIINT Discrete input interrupt message, see OC_ConfigureDII OCMSG_EOS_DMDIN End-of-scan notification message from OC_DemandInputScan command, see OC_EnableEOSNotify OCMSG_EOS_DMDOUT End-of-scan notification message from OC_DemandOutputScan command, see OC_EnableEOSNotif
6-46 Library of Routines Example: HANDLE MSGBUF int Handle; msgbuf; retcode; retcode = OC_PollScanner( Handle, OCMSG_ANY, &msgbuf ); /* Check msgbuf.MsgID for what message is available */ OC_ReadHostRetentive Data OC_ReadHostRetentiveData reads the host-retentive-data partition of the scanner.
Library of Routines 6-47 Return Value: Name: Value: Description: SUCCESS 0 host retentive data was written successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCINIT 5 scanner has not been initialized, see OC_InitScanner ERR_OCPARAM 8 parameter contains invalid value Considerations: Supported in the DOS API library and the Windows NT API library Example: OC_ReadInputImage HANDLE BYTE int Handle; retent_data[500]; retcode; retcode = OC_ReadHostRetentiveData( Handle,
6-48 Library of Routines Description: To guarantee that a series of calls to OC_ReadInputImage read data from a single input scan, OC_ReadInputImage can first be called to read the entire input image into a local buffer pointed to by imagebuf, with the inpimgcpy pointer set to NULL and slotnum set to -1. The imagebuf buffer can then be passed as inpimgcpy in subsequent OC_ReadInputImage calls to retrieve the slot data from the copy of the input image.
Library of Routines OC_ReadIOConfigFile 6-49 OC_ReadIOConfigFile reads the configuration data that is already stored in the DOS file created using OC_WriteIOConfigFile.
6-50 Library of Routines OC_ReadModuleFile OC_ReadModuleFile reads a data file from a module.
Library of Routines 6-51 Example: HANDLE WORD int Handle; filedata[2]; retcode; retcode = OC_ReadModuleFile( Handle, FILTYP_M1, filedata, 6, 3, 2 ); /* OC_ReadOutputImage Reads words 3 and 4 from module in slot 6. */ OC_ReadOutputImage reads the current output image from the scanner.
6-52 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 output image was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCPARAM 8 parameter contains invalid value ERR_OCSCANCFG 14 scanner has not been configured ERR_OCSLOT 12 slot number is invalid Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE WORD int Handle; outputdata[2]; retcode; retcode = OC_ReadOutputImage( Handle, NULL, 6, 0, 2, o
Library of Routines 6-53 the offset within the memroy to begin reading. length specifiies the number of bytes to be read. If offset +length points past the end of the memory, no bytes will be written and ERR_OCPRAM will be returned. Return Value: Name: Description: SUCCESS data was read successfully ERR_OCACCESS handle does not have access to scanner ERR_OCPARAM offset+length points past the end of the memory Considerations: Supported in the Windows NT API library only.
6-54 Library of Routines OC_ResetScanner OC_ResetScanner generates a hard or soft reset to the scanner. This call stops scanning and resets outputs. ATTENTION ! Syntax: int OC_ResetScanner(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: OCNOWAIT OCWAIT OCSOFTRESET OC_ResetScanner returns after releasing the reset signal to the scanner. OC_ResetScanner returns after POST is completed.
Library of Routines OC_SetForces 6-55 OC_SetForces installs and removes input and output forces to the scanner. Syntax: int OC_SetForces(HANDLE handle, FORCEDATA * forcedata) Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner forcedata Defines the inputs and outputs to force. Description: If the result of OC_SetForces removes all I/O forces, the scanner disables forces.
6-56 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 I/O forces were configured successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCPARAM 8 parameter contains invalid value ERR_OCRESPONSE 10 scanner did not respond to request ERR_OCSCANCFG 14 scanner has not been configured ERR_OCSLOT 12 slot number is invalid Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE FORCEDATA int handle; forces; retcod
Library of Routines 6-57 Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: WATCHDOG_IGNORE WATCHDOG_IDLE WATCHDOG_RESET delay The host-to-scanner watchdog is disabled (default). A watchdog timeout causes the scanner to fault. The status LED is set to flashing red, the I/O is reset, I/O scanning stops, and internal scanner error of 0x0B is set, and the major error code is set to 0x40.
6-58 Library of Routines Example: HANDLE int Handle; retcode; retcode = OC_SetHostWatchdog(Handle, WATCHDOG_IDLE, 10 ); /* Watchdog times out in 1 second and places scanner in idle mode */ OC_SetInputUpdate Mode OC_SetInputUpdateMode controls how the scanner updates inputs.
Library of Routines OC_SetIOIdleState 6-59 OC_SetIOIdleState controls the state of I/O when the scanner goes from Scan mode to Idle mode. Syntax: int OC_SetIOIdleState(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: IDLESTATE_HOLD module I/O’s maintain their last state. IDLESTATE_RESET module I/O’s are reset by the scanner. The default I/O idle state is IDLESTATE_RESET.
6-60 Library of Routines OC_SetModuleInterrupt OC_SetModuleInterrupt enables, disables, or acknowledges the module interrupt for the slot slotnum on the scanner.
Library of Routines 6-61 Example: HANDLE int Handle; retcode; retcode = OC_SetModuleInterrupt( Handle, 6, IOINT_ENABLE ); /* Slot 6 module now enabled to generate module interrupts. */ /* Use OC_PollScanner() to check for Module Interrupt messages. */ OC_SetOutputUpdate Mode OC_SetOutputUpdateMode controls how the scanner updates real outputs from the Output Image.
6-62 Library of Routines Setting the output update mode to OUTUPD_CHANGE allows the host application to signal the scanner to write outputs by calling OC_WriteOutputImage. This setting allows the scanner’s minimum scan time to be reduced (since it is only scanning inputs most of the time), and is provided as a performance enhancement. Setting the output update mode to OUTUPD_ALWAYS forces the scanner to write outputs from the output image on every scan.
Library of Routines OC_SetScanMode 6-63 OC_SetScanMode changes the scan mode of the scanner. Syntax: int OC_SetScanMode(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: SCAN_IDLE SCAN_RUN the scanner changes to Idle mode and stops scanning I/O the scanner changes to Scan mode and begins scanning I/O. Description: The scanner must be properly configured before going to Scan mode.
6-64 Library of Routines OC_SetScanTime OC_SetScanTime sets the I/O scan time and I/O scan interval of the scanner. Syntax: int OC_SetScanTime(HANDLE handle, int mode, int time); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode time If mode is: SCAN_PERIODIC time determines the frequency of I/O scans in multiples of 250us and must contain a value between 1 and 255.
Library of Routines OC_SetUserLEDState 6-65 OC_SetUserLEDState sets the state of a user-defined LED Syntax: int OC_SetUserLEDState(HANDLE handle, int lednum, int state); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner lednum Must be a value from 1 to 4, which corresponds to LED1, LED2, LED3, and LED4 ledstate If ledstate is: LED_OFF LED_RED_SOLID LED_GREEN_SOLID LED_RED_FLASH LED_GREEN_FLASH LED is off LED is on, red solid LED is on, green solid L
6-66 Library of Routines OC_SetupPowerFail Action OC_SetupPowerFailAction registers the action to be taken when a power fail interrupt is received from the scanner.
Library of Routines 6-67 A system typically has at least 10 milliseconds, and possibly as much as 50 milliseconds or more between the power fail interrupt and the loss of power. The duration of this interval is a function of the power supply and system configuration, and it varies from system to system. You might need to experiment to determine the typical value for a particular system. Data is copied to the host retentive data partition at the rate of approximately 1K bytes per millisecond.
6-68 Library of Routines OC_WaitForDII Blocks the calling thread until a DII interrupt is received from the scanner or msTimeout milliseconds have elapsed.
Library of Routines OC_WaitForEos 6-69 Blocks the calling thread until an end-of-scan (EOS) notification is received from the scanner or msTimeout milliseconds have elapsed.
6-70 Library of Routines OC_WaitForEosDmdIn Blocks the calling thread until a demand input end-of-scan (EOS) notification is received from the scanner or msTimeout milliseconds have elapsed.
Library of Routines 6-71 /* Wait 1 second for the EOS */ rc = OC_WaitForEosDmdIn(handle, 1000); switch(rc) { case SUCCESS: /* got EOS*/ /* reset the EOS_DMDIN event*/ OC_PollScanner (handle,OCMSG_EOS_DMDIN,&eosMSG); /* do logic, etc.
6-72 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 demand output EOS message was received ERR_RESPONSE 10 msTimeout milliseconds elapsed without an EOS ERR_OCACCESS 2 handle does not have access to scanner Considerations: Supported in the Windows NT API library only.
Library of Routines OC_WaitForExtError 6-73 Blocks the calling thread until an extended error is received from the scanner or msTimeout milliseconds have elapsed.
6-74 Library of Routines OC_WaitForIoInt Blocks the calling thread until a module interrupt is received from the scanner or msTimeout milliseconds have elapsed.
Library of Routines OC_WriteHostRetentive Data 6-75 OC_WriteHostRetentiveData writes data to the host-retentive-data partition of the scanner.
6-76 Library of Routines Example: OC_WriteIOConfigFile HANDLE BYTE int Handle; retent_data[500]; retcode; retcode = OC_WriteHostRetentiveData( Handle, retent_data, 0, 500 ); OC_WriteIOConfigFile writes the configuration data contained in the iocfg structure to the file named filename.
Library of Routines 6-77 Considerations: Supported in the DOS API library and the Windows NT API library Example: OCIOCFG int ‘iocfg retcode; /* Either OC_CreateIOConfiguration() or OC_GetIOConfiguration() were */ /* called previously to fill in ’iocfg’ structure */ retcode = OC_WriteIOConfigFile( &iocfg, ”RACK1.CFG” ); OC_WriteModuleFile OC_WriteModuleFile writes a data file to a module.
6-78 Library of Routines Return Value: Name: Value: Description: SUCCESS 0 file was read successfully ERR_OCACCESS 2 handle does not have access to scanner ERR_OCPARAM 8 parameter contains invalid value ERR_OCRESPONSE 10 scanner did not respond to request ERR_OCSCANCFG 14 scanner has not been configured ERR_OCSLOT 12 slot number is invalid Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE WORD int Handle; filedata[2]; retcode; filedata[
Library of Routines 6-79 Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner outimgcpy If outimgcpy is: NULL OC_WriteOutputImage writes data directly to the output image in the scanner’s shared memory; if the update mode is OUTUPD_CHANGE, the scanner is signalled to update the outputs not NULL OC_WriteOutputImage writes data to outimgcpy; the output image data is not affected If file integrity is not necessary, the host application can set outimgcpy to NULL
6-80 Library of Routines Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE WORD int Handle; outputdata[2]; retcode; outputdata[0] = 0x55AA; outputdata[1] = 0xAA55; retcode = OC_WriteSRAM OC_WriteOutputImage( Handle, NULL, 6, 0, 2, outputdata ); OC_WriteSRAM wires data to the battery-backed user memory Syntax: int OC_WriteSRAM(HANDLE Handle, BYTE*bufptr, DWORD offset, DWORD length); Description: The battery-backed memory may be used to store important
Library of Routines 6-81 Return Value: Name: Description: SUCCESS data was written successfully ERR_OCACCESS handle does not have access to scanner ERR_OCPARAM offset+length points past the end of the memory Considerations: Supported in the Windows NT API library only.
6-82 Library of Routines Notes: Publication 1747-UM002A-US-P - June 2000
Appendix A Error Codes Introduction This appendix describes the error code data. Error Code Returned by API Functions Most of the API functions return values (see chapter 6). These are the values returned by the API functions to indicate success or possible error conditions (but not all are returned by each function).
A-2 Error Codes Extended Error Codes The OC_GetExtendedError function returns error information in a structure of type OCEXTERR. This structure is five bytes in length and contains the following information: Buffer Offset: Bytes: Description: 0 1 extended error code 1 1 associated slot or file number 2 3 error code data When the scanner encounters an error, the extended error code and associated slot (if any) is written to the extended error code and slot number fields.
Error Codes Extended Error Code: Description: 0x60 - 0x8F Module specific errors (see I/O module documentation) 0x90 MINT occurred on disabled slot 0x91 PINT occurred on disabled slot 0x93 Unsupported module error 0x94 Module has been inserted or reset 0xF0 Internal scanner error A-3 The error code data provides information specific to the cause of all extended errors, except 0xF0.
A-4 Error Codes The third byte of the Error Code Data provides details about the Subsystem Error Codes.
Appendix B Testing Function Calls Introduction Both the DOS API and the Windows NT API come with a utility program called api_test.exe. This interactive program lets you execute, from the keyboard, every API call for the 1746 I/O PCI Interface. Use the source code of the utility program, along with the executable program, to test different argument values for each function call and to verify correct scanner operation. Another DOS utility program called ocdiag.
B-2 Testing Function Calls Notes: Publication 1747-UM002A-US-P - June 2000
Appendix C Header File Introduction The API comes with a header file (ocapi.h) that defines: • • • • • error code values status values type definitions structures function prototypes DOS Header File /************************************************************************* * Title: 1746 I/O PCI Interface API library header file * * Abstract: * Contains definitions, structures, and function templates for * all functions defined in the Open Controller API. This file is * distributed as part of the API.
C-2 Header File #define #define #define #define #define #define #define #define #define ERR_OCSLOT ERR_OCFAULT ERR_OCSCANCFG ERR_OCNOFORCES ERR_OCOVERRUN ERR_OCOUTOFMEM ERR_OCUNKNOWN ERR_OCFILERROR ERR_OCNOTSUPP 12 13 14 15 16 17 18 19 20 /* slot number is invalid /* request denied because scanner faulted /* Scanner IO Configuration not downloaded /* no forces installed, cannot enable forces /* DII, I/O Int, or ErrReport message overrun /* memory allocate failed /* unknown module type /* error occured
Header File #define SCAN_PERIODIC 1 /* Select periodic mode - next scan occurs every time*250us C-3 */ /* ***** Scan Mode ***** */ /* These values are passed to the OC_SetScanMode() function. */ /* */ #define SCAN_IDLE 0 /* Select Idle mode (not scanning I/O) */ #define SCAN_RUN 1 /* Select Scan mode (scanning I/O) */ /* ***** IO Idle State ***** */ /* These values are passed to the OC_SetIOIdleState() function.
C-4 Header File /* ***** Switch Position ***** */ /* These values are returned by the /* #define SWITCH_TOP 0xFF #define SWITCH_MIDDLE 0x00 #define SWITCH_BOTTOM 0x01 OC_GetSwitchPosition() function. */ */ /* Switch is in the Top position */ /* Switch is in the Middle position */ /* Switch is in the Bottom position */ /* ***** Jumper State ***** */ /* These values are returned by the OC_GetUserJumperState() function.
Header File C-5 /* ***** Module File Types ***** */ /* These values are passed to the OC_WriteModuleFile() and OC_ReadModuleFile() */ /* functions.
C-6 Header File * dual-port RAM partition sizes for output image, * input image, and host retentive data. * *************************************************************/ typedef struct tagOCINIT { WORD OutputImageSize; /* size in bytes */ WORD InputImageSize; /* size in bytes */ WORD HostRetentiveDataSize; /* size in bytes */ } OCINIT; /************************************************************ * Structure Name: OCSLOTCFG * * Description: * * Configuration information for a module.
Header File C-7 typedef struct tagFORCEDATA BYTE SlotNum; WORD WordOffset; BYTE IOType; WORD ForceMask; WORD ForceVal; } FORCEDATA; /* /* /* /* /* slot number */ offset to word to force */ selects force inputs or outputs */ bits set to 1 are forced, 0 removes forces */ selects force state of bits set to 1 in ForceMask */ /************************************************************ * Structure Name: DII_CFG * * Description: * * Passed to OC_ConfigureDII().
C-8 Header File * Description: * * Returned by OC_GetExtendedError(). * I/O error report from scanner.
Header File C-9 int pascal OC_CloseScanner(HANDLE); int pascal OC_InitScanner(HANDLE, OCINIT *); int pascal OC_GetScannerInitInfo(HANDLE, OCINIT *); int pascal OC_ResetScanner(HANDLE, int); int pascal OC_GetScannerStatus(HANDLE, BYTE *); int pascal OC_CreateIOConfiguration(OCIOCFG *); int pascal OC_DownloadIOConfiguration(HANDLE, OCIOCFG *); int pascal OC_GetIOConfiguration(HANDLE, OCIOCFG *); int pascal OC_ConfigureDII(HANDLE, DII_CFG *); int pascal OC_SetModuleInterrupt(HANDLE, int, int); int pascal OC_
C-10 Header File Windows NT Header File /************************************************************************ * * Title: 1746 I/O PCI Interface API library header file * * Abstract: * * Contains definitions, structures, and function templates for * all functions defined in the Open Controller API. This file is * distributed as part of the API. * * * Environment: * 1747-PCIS, -PCIS2 Bus Interface * Microsoft Windows NT 4.
Header File #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define EERR_OCWDTIMEOUT EERR_OCMODACCESS EERR_OCPINTSTUCK EERR_OCMODMISSING EERR_OCMODINNOSLOT EERR_OCMODMISMATCH EERR_OCIOMISMATCH EERR_OCRACKMISMATCH EERR_OCSPIOLOCKTOUT EERR_OCSPIOFAULT EERR_OCSPIOCMDTOUT EERR_OCMODINT EERR_OCGFILE EERR_OCMFILE EERR_OCINVALIDINT EERR_OCIODRIVER EERR_OCMODULEMIN EERR_OCMODULEMAX EERR_
C-12 Header File /* ***** PollScanner Message ID’s ***** */ /* These values are passed to the OC_PollScanner() function (message filter), and */ /* are returned in the MsgID member of the MSGBUF structure.
Header File #define JUMPER_PRESENT 0 /* User jumper is installed */ #define JUMPER_ABSENT 1 /* User jumper is not installed */ /* ***** Watchdog Settings ***** */ /* These values are passed to the OC_SetHostWatchdog() function.
C-14 Header File #define OCSTSFILEWSIZE 25 /* Status file size in words */ #define OCRTCSRAMSIZE 0x1000 /* size of real-time clock SRAM */ #define OCSEGMENTSIZELIMIT 0x1A00 /* size of dual-port RAM available for I/O and host partitions */ /* **** Device Type Definitions **** /* Returned by OC_GetDeviceInfo().
Header File char } OCSLOTCFG; *Name; C-15 /* pointer to module name string */ /************************************************************ * Structure Name: OCIOCFG * * Description: * * Used by OC_CreateIOConfiguration(), OC_GetIOConfiguration(), * and OC_DownloadIOConfiguration(). * Configuration information for a system. 1, 2, or 3 * racks may be configured for up to 30 I/O modules. * (Slot 0 is reserved for the Open Controller.
C-16 Header File * Description: * * Scanner status file. * *************************************************************/ typedef struct tagSTSFILE { WORD wWordNum[OCSTSFILEWSIZE]; } STSFILE; /************************************************************ * Structure Name: MSGBUF * * Description: * * Returned by OC_PollScanner(). * MsgID identifies the message type. Type-specific * data is contained in MsgData[].
Header File WORD OCdriverRevision; } OCVERSIONINFO; /* Device driver revision C-17 */ /************************************************************ * Structure Name: OCDEVICEINFO * * Description: * * Returned by OC_GetDeviceInfo(). * Information regarding the scanner device.
C-18 Header File DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTRY DLLENTR
Index Numerics 1746 I/O PCI Interface Architecture 1-4 A Access the Scanner During the programming sequence 3-2 API Functions Error codes A-1 Organization 3-1 API Interface Installing the DOS API 1-8 Installing the NT API 1-8 Removing the NT API 1-10 Tools to use 2-4 API Software for DOS 1-2 API Software for NT 1-3 API Structures 4-1 Architecture 1746 I/O PCI interface 1-4 Common attributes of the 1747-OCF and 1746-PCIS 1-5 Open Controller 1-4 B Borland Compilers Sample DOS MAKE file 2-4 Sample NT MAKE fi
2 Index M M0-M1 Files Using 5-3 Microsoft Compilers Sample DOS MAKE file 2-5 Sample NT MAKE file 2-6 N Non-Recoverable Fault 1-6 NT Header File C-10 NT Programming Considerations 2-3 NT Programming Example 3-11 O OC_CalculateCRC Routine 6-1 OC_ClearFault Routine 6-2 OC_CloseScanner Routine 6-3 OC_ConfigureDLL Routine 6-4 OC_CreateIOConfiguration Routine 6-6 OC_DemandInputScan Routine 6-7 OC_DemandOutputScan Routine 6-8 OC_DownloadIOConfiguration Routine 6-9 OC_EnableEOSNotify Routine 6-10 OC_EnableForce
Index R Reference Material P-1 Relationship Between the 1747-OCF and 1746-PCIS 1-1 Removing the NT API 1-10 Routines 6-1 OC_CalculateCRC 6-1 OC_ClearFault 6-2 OC_CloseScanner 6-3 OC_ConfigureDLL 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_GetInputImageUpdateCount
4 Index T Telephone Support P-3 Terminology P-1 Testing Function Calls B-1 Tools 2-4 Troubleshooting LED indicators 1-7 Publication 1747-UM002A-US-P - June 2000 U Using M0-M1 and G Files 5-3 W Waiting for Host Initialization 1-6
Allen-Bradley Publication Problem Report If you find a problem with our documentation, please complete and return this form. Pub. Name API Software for 1746 I/O PCI Interface and 1747-OC Open Controller User Manual Cat. No. 1747-PCIS, -OCF Check Problem(s) Type: Pub. No. 1747-UM002A-US-P Pub. Date June 2000 Part No.
PLEASE FASTEN HERE (DO NOT STAPLE) Other Comments PLEASE FOLD HERE NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO.
Back Cover Publication 1747-UM002A-US-P - June 2000 5 Supersedes Publication 1747-6.5.3 - June 1998 PN 957259-85 © 2000 Rockwell International Corporation. Printed in the U.S.A.
