Allen-Bradley API Software for 1746 I/O PCI Interface (Cat. No.
Important User Information Because of the variety of uses for the products described in this publication, those responsible for the application and use of this control equipment must satisfy themselves that all necessary steps have been taken to assure that each application and use meets all performance and safety requirements, including any applicable laws, regulations, codes and standards. The illustrations, charts, sample programs and layout examples shown in this guide are intended solely for example.
Preface Using This Manual 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 in an MS-DOS or Windows NT environment. This manual documents the 1746 I/O PCI Interface API software for DOS and the API software for Windows NT. The APIs use most of the same calls. Differences are noted as appropriate.
Preface–2 Using This Manual Publication 1747-6.5.
Table of Contents 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. . . . . . . . . . . . . . .
ii Configuring I/O Modules Chapter 5 Library of Routines Chapter 6 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Configuring I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1 Using M0-M1 Files and G Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3 M0-M1 files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iii OC_InitScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46 OC_OpenScanner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48 OC_PetHostWatchdog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-49 OC_PollScanner. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-50 OC_ReadHostRetentive Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv Publication 1747-6.5.
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) • API for Windows NT (catalog number 1747-PCINT) The API software license agreement allows you to freely distribute the executable.
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 Interface scanner to control local I/O and to control remote I/O via the 1747-SN or 1747-SDN scanners.
Overview 1–3 The Windows NT API library is a DLL and must be installed on the system in order to run an application which uses it. The Windows NT API accesses the scanner via the driver created for the bus interface The driver: • • • • allocates resources (interrupt and memory window) initializes scanner hardware provides access to the scanner’s dual port RAM services interrupts from the scanner (priority messages) Important: Only access the OCdriver through the API library functions.
1–4 Overview Your application (the code you develop using the API) uses the dual port memory to communicate with the scanner to handle control functions on the 1746 backplane, such as: • • • • • • • • scanner commands and responses battery and scanner status scan rate frequency and timing I/O image counters priority messages and interrupts semaphores to ensure data integrity software-generated watchdogs control of the 4 user-definable LEDs, the 2-position jumper, and the 3position switch The scanner fu
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 STATUS The STATUS indicator reports the status of the scanner. The following table lists the LED states for STATUS: Installing the DOS API This state: Means: Take this action: Yellow The scanner is running POST.
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 applications before starting the setup process. 2. Select Run from the startup menu, then select the setup.exe program from the API diskette. 3. Click on OK to execute the setup utility. Follow the displayed instructions. Click on Next. 4.
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, OCdriver, to the system device driver directory (%SystemRoot%\system32\drivers). 2.
1–8 Overview Notes: Publication 1747-6.5.
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 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.
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 commandline switch to select the large memory model. For more information, see your user manual for your compiler.
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. #************************************************************************ # # Title: Makefile for Open Controller API Sample # # Abstract: # This file is used by the Borland MAKE utility to build the # sample application.
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.
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.
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 Multithre
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.
2–10 Using the API | clean: del del del del *.exe *.obj *.map *.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.
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. 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.
3–2 Developing Applications Programming Sequence Follow this programming sequence when you develop your application. 1 Access the scanner 2 Initialize the scanner 3 Configure the scanner 4 Control scanner operation 5 Scan I/O 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.
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 operational function is that which controls the LEDs. 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 application can communicate with the scanner.
3–4 Developing Applications The application can read the current I/O configuration with the OC_GetIOConfiguration function. If the scanner is not in Scan mode, this function returns the current scanner configuration which can be downloaded to the scanner 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.
Developing Applications 3–5 Scan I/O The scanner provides two basic methods for scanning I/O: timed scans and on-demand scans. The host application can use either, or a combination of both. Typically, the scanner reads inputs from modules and writes outputs to modules once every scan time. To read inputs and write outputs, the application calls OC_ReadInputImage and OC_WriteOutputImage independently from the scanner’s scan sequence.
3–6 Developing Applications Programming Example for DOS The following DOS example (sample.c on your API disk) shows how to program the above steps. Callouts on the right margin identify the code for each step. /************************************************************************ * * FILE:sample.c * * PURPOSE:Sample application code for 1746 I/O PCI Interface API * * SUMMARY:This program, * - Resets and initializes the scanner. * - Displays the scanner firmware and hardware versions.
Developing Applications /* ** Open the scanner */ retcode = OC_OpenScanner( &Handle, 0, 0); if ( retcode != SUCCESS ) { printf( ”\nERROR: OC_OpenScanner failed: %d\n”, retcode ); Ioexit( 1 ); } 3–7 Access the scanner See page 6-48. /* ** Reset the scanner */ printf( ”\n\n Going to reset OC, takes 6 seconds to complete...
3–8 Developing Applications /* ** Read switch position */ retcode = OC_GetSwitchPosition( Handle, &swpos ); if ( retcode != SUCCESS ) { printf( ”\nERROR: OC_GetSwitchPosition failed: %d\n”, retcode ); Ioexit( 1 ); } 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
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 ); } /* ** Set output update mode to always */ retcode = OC_SetOutputUpdateMode( Handle, OUTUPD_ALWAYS ); if ( retcode != SUCCESS ) { printf( ”\nERROR: OC_SetOutputUpdateMode failed: %d\n”, retcode ); Ioexit( 1 ); } /* ** Set scan time to 5ms, periodic scan mode */ retc
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 /************************************************************************ * * Name: Ioexit * * Description: * * Common error handling routine. This routine displays any * extended error and exits the program. * * Arguments: * retcode : int( input ) * This error code is passed to the exit() routine. * * External effects: * The program is terminated.
3–12 Developing Applications 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. /******************************************************************** * Title: Simple application sample code for 1746 I/O PCI Interface API * * Abstract: * * This file contains a simple application using the PCI * bus interface API.
Developing Applications 3–13 if (OC_GetExtendedError(OChandle, &exterr) == SUCCESS) { if ( exterr.ErrorCode != 0 ) { OC_ExtendedErrorMsg(OChandle, &exterr, &msg); printf("\n\nERROR: %d %s\n", msg, exterr.ErrorCode); } } OC_CloseScanner(OChandle); exit(rc); } /* end Ioexit() */ /************************************************************************* * Entry point: * tErrorEvent * * Description: * Thread to handle errors.
3–14 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.
Developing Applications /* Reset the scanner */ printf("\nResetting the scanner..."); if (SUCCESS != (rc = OC_ResetScanner(OChandle, OCWAIT))) { printf("\nERROR: OC_ResetScanner failed: %d\n", rc); Ioexit(1); } /* Check scanner status register */ if (SUCCESS != (rc = OC_GetScannerStatus(OChandle, &status))) { printf("\nERROR: OC_GetScannerStatus failed: %d\n", rc); Ioexit(1); } 3–15 Initialize the scanner See pages 6-63, 6-33, and 6-46.
3–16 Developing Applications /* 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
Developing Applications 3–17 /* Set output update mode to always */ if (SUCCESS != (rc = OC_SetOutputUpdateMode(OChandle, OUTUPD_ALWAYS))) { printf("\nERROR: OC_SetOutputUpdateMode failed: %d\n", rc); Ioexit(1); } /* Set scan time to 5ms, periodic scan mode */ if (SUCCESS != (rc = OC_SetScanTime(OChandle, SCAN_PERIODIC, 20))) { printf("\nERROR: OC_SetScanTime failed: %d\n", rc); Ioexit(1); } Control scanner operation See pages 6-70 and 6-73.
3–18 Developing Applications Handling Interrupt Messages 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.
Developing Applications 3–19 To determine the input and output image sizes, call OC_CreateIOConfiguration with a configuration that contains the I/O modules to be installed. OC_CreateIOConfiguration returns the number of bytes of I/O required by each module. Or you can use OC_GetIOConfig to use the current configuration, if one exists. The input and output sizes are based on the number of words of I/O required by each module.
3–20 Developing Applications Notes: Publication 1747-6.5.
Chapter 4 Using the API Structures Introduction This chapter describes the structures the API uses. These structures are declared in ocapi.h. API Structures Structure Name: Syntax: typedef struct tagDII_CFG DII_CFG Passed to OC_ConfigureDII. Configures a discrete input interrupt for a module.
4–2 Using the API Structures Structure Name: Syntax: OCSLOTCFG Configuration information for a module. The mix and type codes together form a unique identification for each module.
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 struct { BYTE mix; BYTE type; BYTE InputSize; BYTE OutputSize; WORD M0Size; WORD M1Size; WORD GSize; WORD *GData; char *Name; } OCSLOTCFG; /* /* /* /* /* /* /* /* /* Module I/O Mix value */ Module Type */ number of inputs in bytes */ number of outputs in bytes */ size of M0 file in words */ size of M1 file in words */ size of G file in words */ pointer to array of length GSize words */ pointer to module name string */ You can specify a module by name or by mix and type.
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:a Mix:b Type: 1203-SM1 Class1 1 1 35 35 14 16 1203-SM1 Class 4 4 136 17 1394-SJT 4 136 17 1746-IA4 4-Input 100/120 V ac 0 1 0 1746-IA8 8-Input 100/120 V ac 0 3 0 1746-IA16 16-Input 100/120 V ac 0 5 0 1746-IB8 8-Input (SINK) 24 V dc 0 3 6 1746-IB16 16-Input (SINK) 24 V dc 0 5 6 1746-IB32 32-Input (SINK) 24 V dc 0 7 6 1746-IC16 16-Input dc 0 5 9 1746-IH16 16-Input ac 0 5 7 1746-IG16 16-Input
Configuring I/O Modules Module Name:a Description: 1746-IO4 2-Input 100/120 V ac 2-Output [RLY] Class: 0 1746-IO8 4-Input 100/120 V ac 4-Output [RLY] 0 11 0 1746-IO12 6-Input 100/120 V ac 6-Output [RLY] 0 15 0 1746-INT4 4 thermocouples, isolated 1 35 15 1746sc-INO4VI Spectrum Controls, 4 Analog Outputs 1 35 19 1746sc-INI4VI Spectrum Controls, 4 Analog Inputs 1 35 20 Spectrum Controls, 4 Analog Outputs 1 35 21 1746sc-INI4I Spectrum Controls, 4 Analog Inputs 1 35 22 174
5–6 Configuring I/O Modules Notes: Publication 1747-6.5.
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 OC_CalculateCRC OC_CalculateCRC OC_CalculateCRC calculates a 16-bit CRC. Syntax: void OC_CalculateCRC(BYTE *bufPtr, WORD bLen, WORD *Crc); Parameters: Parameter: Description: bufPtr Points to the buffer that contains the bytes for the CRC calculation bLen Number of bytes for which to calculate the CRC Crc A word that returns the calculated CRC Description: This function is useful for verifying data integrity.
OC_ClearFault Library of Routines OC_ClearFault 6–3 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. If the scanner encounters an error condition, it generates an extended error and faults. The fault forces the scanner into Idle mode.
6–4 Library of Routines OC_CloseScanner OC_CloseScanner 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.
OC_ConfigureDII Library of Routines OC_ConfigureDII 6–5 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.
6–6 Library of Routines OC_ConfigureDII Return Value: Name: Value: 0 SUCCESS Description: discrete input interrupt (DII) was configured successfully ERR_OCACCESS 2 handle does not have access to the scanner 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 DII_CFG int Handle; diicfg; retcode; diicfg.
OC_CreateIO Configuration OC_CreateIO Configuration Library of Routines 6–7 OC_CreateIOConfiguration creates a scanner configuration from an applicationspecific 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.
6–8 Library of Routines OC_CreateIO Configuration Example: OCIOCFG int char iocfg; retcode, numslots, i; module_name[] = ”1746-BAS”; iocfg.Rack1Size = 10; iocfg.Rack2Size = 7; iocfg.Rack3Size = 0; /* 10 slot chassis */ /* 7 slot chassis */ /* Only 2 chassis */ numslots = iocfg.Rack1Size + iocfg.Rack2Size + iocfg.Rack3Size; for ( i=1; i
OC_DemandInputScan OC_DemandInputScan Library of Routines 6–9 OC_DemandInputScan forces the scanner to immediately perform an input scan. Syntax: int OC_DemandInputScan(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: OCWAIT OC_DemandInputScan waits for the input scan to be completed before returning to the caller. OCNOWAITOC_DemandInputScan returns immediately.
6–10 Library of Routines OC_DemandOutputScan OC_DemandOutputScan OC_DemandOutputScan forces the scanner to immediately perform an output scan. Syntax: int OC_DemandOutputScan(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner mode If mode is: OCWAIT OC_DemandOutputScan waits for the output scan to be completed before returning to the caller. OCNOWAITOC_DemandOutputScan returns immediately.
OC_DownloadIO Configuration OC_DownloadIO Configuration Library of Routines 6–11 OC_DownloadIOConfiguration downloads an I/O configuration to the scanner. Syntax: int OC_DownloadIOConfiguration(HANDLE handle, OCIOCFG *iocfg); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner iocfg Specifies the rack sizes and installed modules Description: The scanner must be in Idle mode to receive an I/O configuration.
6–12 Library of Routines OC_DownloadIO Configuration Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE OCIOCFG int Handle; iocfg; retcode; /* Either OC_CreateIOConfiguration() or OC_GetIOConfiguration() were */ /* called previously to fill in ’iocfg’ structure */ retcode = OC_DownloadIOConfiguration( Handle, &iocfg ); Publication 1747-6.5.
OC_EnableEOSNotify OC_EnableEOSNotify Library of Routines 6–13 OC_EnableEOSNotify controls whether end-of-scan notification messages are generated by the scanner. Syntax: int OC_EnableEOSNotify(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner If mode is: EOSMSG_ENABLE message the scanner generates an end-of-scan after each scan. Use the OC_PollScanner function mode EOSMSG_DISABLE scan to retrieve end-of-scan messages.
6–14 Library of Routines OC_EnableEOSNotify Return Value: Name: SUCCESS Value: 0 Description: notification was generated 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: HANDLE Handle; int retcode; retcode = OC_EnableEOSNotify( Handle, EOSMSG_ENABLE ); /* Use OC_PollScanner()
OC_EnableForces OC_EnableForces Library of Routines 6–15 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.
6–16 Library of Routines OC_EnableForces Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE int Handle; retcode; /* Use OC_SetForces() to configure forcing information first */ retcode = OC_EnableForces( Handle, FORCE_ENABLE ); Publication 1747-6.5.
OC_EnableSlot Library of Routines OC_EnableSlot 6–17 OC_EnableSlot enables fine tuning of the I/O scanning process. Syntax: int OC_EnableSlot(HANDLE handle, int slotnum, int state); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner slotnum Must contain a valid slot number.
6–18 Library of Routines OC_ErrorMsg OC_ErrorMsg OC_ErrorMsg returns a descriptive text message associated with the API return value errcode. Syntax: int OC_ErrorMsg(int errcode, char **msg); Description: The null-terminated message string is placed in a static buffer that is reused each time this function is called. A pointer to this buffer is returned in msg. Return Value: Name: Description: SUCCESS errcode was valid. msg points to corresponding error description.
OC_ExtendedErrorMsg OC_ExtendedErrorMsg Library of Routines 6–19 OC_ExtendedErrorMsg returns a descriptive text message associated with an extended error.
6–20 Library of Routines OC_ExtendedErrorMsg Example: HANDLE OCEXTERR char int Handle; exterr; *msg; retcode; /* Should already have called OC_GetExtendedError() to obtain exterr */ retcode = OC_ExtendedErrorMsg( Handle, &exterr, &msg ); printf(“ERROR:%s\n”, msg); Publication 1747-6.5.
OC_GetBatteryStatus Library of Routines OC_GetBatteryStatus 6–21 OC_GetBatteryStatus gets the current state of the battery of the scanner.
6–22 Library of Routines OC_GetDeviceInfo OC_GetDeviceInfo OC_GeDeviceInfo returns information about the scanner device.
OC_GetExtendedError OC_GetExtendedError Library of Routines 6–23 OC_GetExtendedError reads extended error information from the scanner. Syntax: int OC_GetExtendedError(HANDLE handle, OCEXTERR *buf); 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.
6–24 Library of Routines Considerations: Supported in the DOS API library and the Windows NT API library Example: HANDLE Handle; OCEXTERRexterr; int retcode; retcode = OC_GetExtendedError( Handle, &exterr ); Publication 1747-6.5.
OC_GetInputImage UpdateCounter OC_GetInputImage UpdateCounter Library of Routines 6–25 OC_GetInputImageUpdateCounter reads the value of the input image update counter from the scanner and places it into count.
6–26 Library of Routines Publication 1747-6.5.
OC_GetIOConfiguration OC_GetIOConfiguration Library of Routines 6–27 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. While it is executing, I/O scanning and DII’s are disabled.
6–28 Library of Routines OC_GetIOConfiguration Return Value: Name: Value: 0 SUCCESS Description: 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 Example: HANDLE OCIOCFG int Handle; iocfg; retcode; retcode = OC_GetIOConfiguration( Handle, &iocfg );
OC_GetLastFaultCause OC_GetLastFaultCause Library of Routines 6–29 OC_GetLastFaultCause retrieves the cause of the last fault. Syntax: int OC_GetLastFaultCause(HANDLE handle, BYTE *FaultCode, int *SlotNum); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner FaultCode Points to the address that contains the fault cause If the value returned in FaultCode is 0, the scanner has not received any faults since it has been reset.
6–30 Library of Routines OC_GetMeasuredScan Time 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.
OC_GetScannerInitInfo OC_GetScannerInitInfo Library of Routines 6–31 This function retrieves current information about the shared memory partitioning.
6–32 Library of Routines OC_GetScannerInitInfo 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 */ Publication 1747-6.5.
OC_GetScannerStatus OC_GetScannerStatus Library of Routines 6–33 OC_GetScannerStatus reads the current status of the scanner.
6–34 Library of Routines Example: HANDLE BYTE int Handle; scansts; retcode; retcode = OC_GetScannerStatus( Handle, &scansts ); Publication 1747-6.5.
OC_GetScanner WatchdogCount OC_GetScanner WatchdogCount Library of Routines 6–35 OC_GetScannerWatchdogCount reads the contents of the watchdog register of the scanner. Syntax: int OC_GetScannerWatchdogCount(HANDLE handle, BYTE *count); 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–36 Library of Routines OC_GetStatusFile 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.
OC_GetStatusFile Library of Routines Word/Bit: Classification: Description: 0/6 status Forces installed bit This bit is set is forces have been installed. 0/7 to 0/12 reserved 0/13 dynamic configuration 0/14 reserved Major error halted bit This bit is set by the scanner when a major error is encountered. The scanner enters a fault condition. Word 2, Fault Code will contain a code which can be used to diagnose the fault condition.
6–38 Library of Routines Word/Bit: OC_GetStatusFile Classification: Description: 9 to 10 status I/O interrupt enabled These two words are bit-mapped to the 30 I/O slots. Bits 9/1 through 10/ 14 refer to slots 1-30. Bits 9/0 and 10/15 are not used. The corresponding enable bit must be set in order for an I/O interrupt received priority message to be generated when a module issues an interrupt request.
OC_GetStatusFile Library of Routines Word/Bit: Classification: Description: dynamic configuration DII preset When this value is 0 or 1, an interrupt is generated each time the bit transition comparison is satisfied (see words 15 and 16). When this value is 2-65535, a count occurs each time the bit transition comparison is satisfied. When the total number of counts equals the DII preset value, an interrupt will be generated.
6–40 Library of Routines OC_GetSwitchPosition OC_GetSwitchPosition OC_GetSwitchPosition reads the current position of the three-position front-panel switch from the scanner.
OC_GetTemperature Library of Routines OC_GetTemperature 6–41 OC_GetTemperature reads the current temperature of the 1746 I/O PCI Interface’s built-in thermometer. Syntax: int OC_GetTemperature(HANDLE handle, BYTE*temp); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner temp Returns the temperature in degrees Celsius Description: The temperature is updated every 10 seconds by the scanner.
6–42 Library of Routines OC_GetUserJumper State OC_GetUserJumper State OC_GetUserJumperState reads the state of the user selectable jumper.
OC_GetUserLEDState Library of Routines OC_GetUserLEDState 6–43 OC_GetUserLEDState reads the status of one of the four user-defined LEDs.
6–44 Library of Routines OC_GetVersionInfo OC_GetVersionInfo OC_GetVersionInfo retrieves the current version of the API library, 1746 I/O PCI Interface hardware, and scanner firmware.
OC_GetVersionInfo Library of Routines 6–45 Example: HANDLE OCVERSIONINFO int Handle; verinfo; retcode; retcode = OC_GetVersionInfo( Handle, &verinfo ); Publication 1747-6.5.
6–46 Library of Routines OC_InitScanner OC_InitScanner This function initializes the shared memory interface between the host and scanner and this function configures the shared memory partitioning.
OC_InitScanner Library of Routines 6–47 Return Value: Name: Value: 0 SUCCESS Description: scanner was initialized successfully ERR_OCACCESS 2 handle does not have access to the scanner ERR_OCMEM 3 shared memory not found ERR_OCPAR 6 initialization failed due to invalid partition information ERR_OCPOST 7 POST in progress or scanner POST failed, see OC_GetScannerStatus ERR_OCREINIT 4 scanner has already been initialized ERR_OCRESPONSE 10 scanner did not respond to request Consideratio
OC_OpenScanner Library of Routines OC_OpenScanner 6–48 OC_OpenScanner acquires access to the scanner device and sets a unique ID that the application uses to access the scanner in subsequent functions. Syntax: DOS int OC_OpenScanner(HANDLE *handle, 0, 0); NT int OC_OpenScanner(HANDLE *handle); Important: The two argument values of zero are ignored by the DOS API function.They are a carryover from the Open Controller API.
OC_PetHostWatchdog Library of Routines OC_PetHostWatchdog 6–49 OC_PetHostWatchdog increments the host-to-scanner watchdog register of the scanner. Syntax: void OC_PetHostWatchdog(HANDLE handle); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner Description: OC_PetHostWatchdog must be called at time intervals less than the timeout value specified in the OC_SetHostWatchdog function.
6–50 Library of Routines OC_PollScanner OC_PollScanner OC_PollScanner reads module I/O interrupt, discrete input interrupt, and end-ofscan notification messages from the scanner.
OC_PollScanner Library of Routines 6–51 The data returned in the MsgData member array depends upon the value in MsgID: This MsgID: Returns: MsgID=OCMSG_IOINT MsgData[0]slot number that generated the interrupt MsgID=OCMSG_DIINT MsgData[0]mask of last bit transition that generated the interrupt MsgData[2]lowbyte of count of matches that generated the interrupt MsgData[3]highbyte of count of matches that generated the interrupt MsgID=OCMSG_EOS_DMDIN MsgData[0]number of scans that occurred since the l
6–52 Library of Routines OC_ReadHostRetentive Data OC_ReadHostRetentive Data OC_ReadHostRetentiveData reads the host-retentive-data partition of the scanner.
OC_ReadHostRetentive Data Library of Routines 6–53 Example: HANDLE BYTE int Handle; retent_data[500]; retcode; retcode = OC_ReadHostRetentiveData( Handle, retent_data, 0, 500 ); Publication 1747-6.5.
6–54 Library of Routines OC_ReadInputImage OC_ReadInputImage OC_ReadInputImage reads the current input image from the scanner. Syntax: int OC_ReadInputImage(HANDLE handle, WORD *inpimgcpy, int slotnum, WORD offset, WORD len, WORD *imagebuf); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner inpimgcpy If inpimgcpy is: NULL OC_ReadInputImage reads data directly from the input image in the scanner’s shared memory.
OC_ReadInputImage Library of Routines 6–55 Return Value: Name: Value: 0 SUCCESS Description: input 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; inputdata[2]; retcode; retcode = OC_ReadInputImage( Handle, NUL
6–56 Library of Routines OC_ReadIOConfigFile OC_ReadIOConfigFile OC_ReadIOConfigFile reads the configuration data that is already stored in the DOS file created using OC_WriteIOConfigFile.
OC_ReadModuleFile OC_ReadModuleFile Library of Routines 6–57 OC_ReadModuleFile reads a data file from a module.
6–58 Library of Routines OC_ReadModuleFile Example: HANDLE WORD int Handle; filedata[2]; retcode; retcode = OC_ReadModuleFile( Handle, FILTYP_M1, filedata, 6, 3, 2 ); /* Reads words 3 and 4 from module in slot 6. */ Publication 1747-6.5.
OC_ReadOutputImage OC_ReadOutputImage Library of Routines 6–59 OC_ReadOutputImage reads the current output image from the scanner. Syntax: int OC_ReadOutputImage(HANDLE handle, WORD *outimgcpy, int slotnum, WORD offset, WORD len, WORD *imagebuf); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner outimgcpy If outimgcpy is: NULL OC_ReadOutputImage reads data directly from the output image in the scanner’s shared memory.
6–60 Library of Routines OC_ReadOutputImage Example: HANDLE WORD int Handle; outputdata[2]; retcode; retcode = OC_ReadOutputImage( Handle, NULL, 6, 0, 2, outputdata ); /* Read slot 6 data, first 2 words, directly from the output image */ /* table to outputdata buffer */ Publication 1747-6.5.
OC_ReadSRAM OC_ReadSRAM Library of Routines 6–61 OC_ReadSRAM reads data from the battery-backed user memory. Syntax: int OC_ReadSRAM(HANDLE Handle, BYTE *bufptr, DWORD offset, DWORD length); Description: The battery-backed memory may be used to store important data that needs to be preserved in the event of a power failure. The size of the available memory in bytes may be obtained using OC_GetDeviceInfo.
6–62 Library of Routines OC_ReadSRAM Example: Byte buf[100]; /*buffer of 100 bytes of important data*/ HANDLE handle; Word crc, crc_saved; /* Read 100 bytes of data from offset 0 in SRAM */ OC_ReadSRAM(handle, buf, 0, 100); /* Calculate CRC */ OC_CalculateCRC(buf, 100, &crc); /* Read saved CRC at offset 100 in SRAM */ OC_ReadSRAM(handle, &crc_saved, 100, 2); /* Check CRC */ if (crc != saved_crc) printf(“ERROR: Data is corrupted.\n”); Publication 1747-6.5.
OC_ResetScanner Library of Routines OC_ResetScanner 6–63 OC_ResetScanner generates a temporary hard reset to the scanner. ! ATTENTION: outputs. This call stops scanning and resets Syntax: int OC_ResetScanner(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner If mode is: OCNOWAIT mode OCWAIT OC_ResetScanner returns after releasing the reset signal to the scanner. OC_ResetScanner returns after POST is completed.
6–64 Library of Routines OC_SetForces OC_SetForces 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.
OC_SetForces Library of Routines 6–65 Return Value: Name: SUCCESS Value: 0 Description: 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 handle; FORCEDATA forces; i
6–66 Library of Routines OC_SetHostWatchdog OC_SetHostWatchdog OC_SetHostWatchdog sets the host-to-scanner watchdog delay and mode of the scanner. Syntax: int OC_SetHostWatchdog(HANDLE handle, int mode, WORD delay); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner If mode is: WATCHDOG_IGNORE WATCHDOG_IDLE mode the host-to-scanner watchdog is disabled (default) a watchdog timeout causes the scanner to fault.
OC_SetInputUpdate Mode OC_SetInputUpdate Mode Library of Routines 6–67 OC_SetInputUpdateMode controls how the scanner updates inputs. Syntax: int OC_SetInputUpdateMode(HANDLE handle, int mode); Parameters: Parameter: Description: handle Must be a valid handle returned from OC_OpenScanner If mode is: INUPD_NEVER the scanner does not scan inputs unless explicitly requested by the OC_DemandInputScan function. INUPD_ALWAYS the scanner continuously updates inputs on every scan.
6–68 Library of Routines OC_SetIOIdleState OC_SetIOIdleState 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.
OC_SetModuleInterrupt OC_SetModuleInterrupt Library of Routines 6–69 OC_SetModuleInterrupt enables, disables, or acknowledges the module interrupt for the slot slotnum on the scanner.
6–70 Library of Routines OC_SetOutputUpdate Mode OC_SetOutputUpdate Mode OC_SetOutputUpdateMode controls how the scanner updates real outputs from the Output Image.
OC_SetOutputUpdate Mode Library of Routines 6–71 Return Value: Name: Value: 0 SUCCESS Description: conditional scan was set successfully ERR_OCACCESS 2 handle does not have access to the 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: HANDLE int Handle; retcode; retcode = OC_SetOutputUpdateMode( Handle, OUTUPD_NEVER ); /* Must use
6–72 Library of Routines OC_SetScanMode OC_SetScanMode 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 If mode is: SCAN_IDLE scanning I/O SCAN_RUN mode the scanner changes to Idle mode and stops the scanner changes to Scan mode and begins scanning I/O. Description: The scanner must be properly configured before going to Scan mode.
OC_SetScanTime Library of Routines OC_SetScanTime 6–73 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 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.
6–74 Library of Routines OC_SetUserLEDState OC_SetUserLEDState 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 only) LED_GREEN_FLASH only) LED is off LED is on, re
OC_SetupPowerFail Action OC_SetupPowerFail Action Library of Routines 6–75 OC_SetupPowerFailAction registers the action to be taken when a power fail interrupt is received from the scanner.
6–76 Library of Routines OC_SetupPowerFail Action Return Value: Name: Value: 0 SUCCESS Description: power fail action was registered 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 only. Example: This example is for DOS only.
OC_WaitForDII Library of Routines OC_WaitForDII 6–77 Blocks the calling thread until a DII interrupt is received from the scanner or milliseconds have elapsed.
6–78 Library of Routines OC_WaitForEos OC_WaitForEos Blocks the calling thread until an end-of-scan (EOS) notification is received from the scanner or msTimeout milliseconds have elapsed.
OC_WaitForEos Library of Routines 6–79 Example: HANDLE handle; intrc; MSGBUF eosMSG /* Wait for 10 seconds for the EOS */ rc = OC_WaitForEos(handle, 10000); switch(rc) { case SUCCESS:/* got EOS*/ /* reset the EOS event*/ OC_PollScanner (handle,OCMSG_EOS,&eosMSG); break; case ERR_OCRESPONSE:/* timed out */ printf(“\nTimed out waiting for EOS\n”); break; default; printf(“\nError!\n”); break; } Publication 1747-6.5.
6–80 Library of Routines OC_WaitForEosDmdIn 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.
OC_WaitForEosDmdIn Library of Routines 6–81 Example: HANDLE handle; intrc; MSGBUF eosMSG /* Request an input scan, but don’t wait */ OC_DemandInputScan(handle, OCNOWAIT); /* Could have other code here */ /* 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–82 Library of Routines OC_WaitForEosDmdOut OC_WaitForEosDmdOut Blocks the calling thread until a demand output end-of-scan (EOS) notification is received from the scanner or msTimeout milliseconds have elapsed.
OC_WaitForEosDmdOut Library of Routines 6–83 Example: HANDLE handle; intrc; MSGBUF eosMSG /* Request an output scan, but don’t wait */ OC_DemandOutputScan(handle, OCNOWAIT); /* Could have other code here */ /* Wait 1 second for the EOS */ rc = OC_WaitForEosDmdOut(handle, 1000); switch(rc) { case SUCCESS:/* got EOS*/ /* reset the EOS_DMDOUT event*/ OC_PollScanner (handle,OCMSG_EOS_DMDOUT,&eosMSG); /* do logic, etc.
6–84 Library of Routines OC_WaitForExtError OC_WaitForExtError Blocks the calling thread until an extended error is received from the scanner or milliseconds have elapsed.
OC_WaitForIoInt Library of Routines OC_WaitForIoInt 6–85 Blocks the calling thread until a module interrupt is received from the scanner or milliseconds have elapsed.
6–86 Library of Routines OC_WriteHostRetentive Data OC_WriteHostRetentive Data OC_WriteHostRetentiveData writes data to the host-retentive-data partition of the scanner.
OC_WriteIOConfigFile Library of Routines OC_WriteIOConfigFile 6–87 OC_WriteIOConfigFile writes the configuration data contained in the iocfg structure to the file named filename. Syntax: int OC_WriteIOConfigFile(OCIOCFG *iocfg, char *filename); Parameters: Parameter: Description: A structure that contains the configuration data that is to be written to iocfg filename References the file to write If filename does not exist, it is created.
6–88 Library of Routines OC_WriteModuleFile OC_WriteModuleFile OC_WriteModuleFile writes a data file to a module.
OC_WriteModuleFile Library of Routines 6–89 Example: HANDLE WORD int Handle; filedata[2]; retcode; filedata[0] = 0x55AA; filedata[1] = 0xAA55; retcode = OC_WriteModuleFile( Handle, FILTYP_M0, filedata, 6, 3, 2 ); /* Writes words 3 and 4 from module in slot 6 */ Publication 1747-6.5.
6–90 Library of Routines OC_WriteOutputImage OC_WriteOutputImage OC_WriteOutputImage updates the output image on the scanner.
OC_WriteOutputImage Library of Routines 6–91 Example: HANDLE WORD int Handle; outputdata[2]; retcode; outputdata[0] = 0x55AA; outputdata[1] = 0xAA55; retcode = OC_WriteOutputImage( Handle, NULL, 6, 0, 2, outputdata ); Publication 1747-6.5.
6–92 Library of Routines OC_WriteSRAM OC_WriteSRAM 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 data that needs to be preserved in the event of a power failure. The size of the available memory in bytes may be obtained using OC_GetDeviceInfo.
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).
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 this information: Table A.1 OCEXTERR Structure Buffer Offset: 0 Bytes: 1 Description: 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 A–3 The error code data provides information specific to the cause of all extended errors, except 0xF0 (see Table A.3). The first byte of the error code data contains a subsystem identifier. Table A.3 First Byte of Error Code Data - Scanner Communications Subsystem Error Codes Subsystem ID: 0x06 0x08 Description: Scanner Communications Backplane Interface (module I/O) The second byte of the error code data provides details about the subsystem identifier. Table A.
A–4 Error Codes If the extended error code is an internal scanner error (0xF0), the slot number is set to 0 and the first byte of the Error Code Data contains the source of the error. Table 9 lists the internal scanner extended error sources. Table A.6 Internal Scanner Errors Error Code: 0x03 Publication 1747-6.5.
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-6.5.
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 Cat. No. 1747-PCIDOS, -PCINT Check Problem(s) Type: Pub. No. 1747-6.5.3 Pub. Date June 1998 Part No.
PLEASE FASTEN HERE (DO NOT STAPLE) PLEASE FOLD HERE NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO.
Allen-Bradley, a Rockwell Automation Business, has been helping its customers improve productivity and quality for more than 90 years. We design, manufacture and support a broad range of automation products worldwide. They include logic processors, power and motion control devices, operator interfaces, sensors and a variety of software. Rockwell is one of the world’s leading technology companies. Worldwide representation.
