Home

SCADAPack3xx C++ Tools User Manual

1. Document Version 1 70 5 23 2012 617 Structures and Types MM QUEUE FULL Ger MM STATIONS ARE EQUAL 28 MM EXCEPTION DEVICE FAILURE 297 30 MM EXCEPTION DEVICE BUSY MODBUS CMD STATUS MM_SENT returns a valid command has been sent MM_RECEIVED returns response was received MM_NO_MESSAGE returns no message was sent MM_BAD_FUNCTION returns invalid function code used MM_BAD_SLAVE returns invalid slave station address used MM_BAD_ADDRESS returns invalid database address used MM_BAD_LENGTH returns invalid message length MM_PROTOCOL_NOT_SUPPORTED returns selected protocol is not supported MM_CONNECTING returns connecting to slave IP address MM_CONNECTED returns connected to slave IP address MM_CONNECT_TIMEOUT returns timeout while connecting to slave IP address MM_SEND_ERROR returns TCP IP error has occurred while sending message MM_RSP_TIMEOUT returns timeout has occurred waiting for response MM_RSP_ERROR returns slave has closed connection incorrect response or incorrect response length MM_DISCONNECTING returns disconnecting from slave IP address is in progress MM_DISCONNECTED returns connection to slave IP address is disconnected MM_BAD_CONNECT_ID returns invalid connection ID MM_BAD_PROTOCOL_TYPE returns invalid protocol type MM_BAD_IP_ADDRESS retur
2. get_protocol com3 amp protocolSettings protocolSettings type NO PROTOCOL set protocol com3 amp protocolSettings 7 Load DNP Configuration Parameters configuration masterAddress 100 configuration rtuAddress 1 configuration datalinkConfirm FALSE configuration datalinkRetries DEFAULT DLINK_ RETRIES configuration datalinkTimeout DEFAULT DNK TIMEOUT configuration operateTimeout DEFAULT OPERATE TIMEOUT configuration applicationConfirm FALSE configuration maximumResponse DEFAULT MAX RESP LENGTH configuration applicationRetries DEFAULT APPL RETRIES configuration applicationTimeout DEFAULT APPL TIMEOUT configuration timeSynchronization NO TIME SYNC configuration BI number configuration BI startAddress 0 configuration BI reportingMethod REPORT ALL EVENTS configuration BI soeBufferSiz 1000 configuration BO number 1051 configuration BO startAddress 0 configuration CI16 number 50 configuration CI16 startAddress 0 configuration CI16 reportingMethod REPORT ALL EVENTS configuration CI16 bufferSize 0 configuration CI32 number 0 configuration CI32 startAddress 100 configuration CI32 reportingMethod REPORT ALL EVENTS configurati
3. BOOLEAN status struct myTable pTable status TRUE if getProgramStatus FUNCPTR main NEW PROGRAM Application has just been downloaded request resource DYNAMIC MEMORY status allocateMemory void amp pNvMemory gt pAllocatedMem MEM SIZE release resource DYNAMIC MEMORY Document Version 1 70 5 23 2012 659 Example Programs if status TRUE set program status so memory is not re allocated until application is downloaded again setProgramStatus FUNCPTR main PROGRAM EXECUTED use non volatile memory for table structure pTable struct myTable zl pNvMemory gt pAllocatedMem while TRUE if status TRUE pTable is used in remainder of program print error message Allow other tasks to execute release processor Master Message Example Using Modbus Protocol This program sends a master message on com2 using the Modbus protocol then waits for a response from the slave The number of good and failed messages is printed to com1 poll c Polling program for Modbus slave wait for response The wait for response function waits for a response to be received to a master message on the serial port specified by stream It returns when a response is received or when the period specified by time in tenths of a second expires Document Vers
4. be either typedef enum dlogMediaStatus type DLOGS MEDIA PRESENT media is present DLOGS_ MEDIA NOT _PRESENT no external media present DLOGS_ MEDIA EXT FULL external media is full DLOGS_ MEDIA INT FULL internal media is full DLOGS MEDIA ALL FULL ext and int media full dlogMediaStatus dlogRecordElement Type This structure defines a data log record It provides on how an element in a record can be packed into a log file typedef struct dlogRecordElement_ typ UCHAR type UINT32 size UINT32 offset Document Version 1 70 5 23 2012 590 Structures and Types dlogRecordElement e type is the type of field Valid values are i a S 32 bit signed integer a VE a es eee lem point DLOG_FIRST_USER_TYPE custom types type specific to DLOG_LAST_USER_TYPE e size is the size in bytes of the element The sizeof function can be used to determine this value e offset is the offset in bytes of the first byte of the element from the start of the record passed to the dlogWrite function Example This is an example on how a record can be defined It contains information on how the structure can be packed into log files User type definition array of 10 UINT16 variables typedef UINT16 userType 10 Structure used to copy one record into data log typedef struct dataRecord UINT16 valuel INT32 value2 double value3 float value4 Document Ve
5. Description The installRTCHandler function allows an application program to override Modbus protocol and DNP protocol commands to set the real time clock This function specifies a function to be called when a Modbus or DNP message is received for the station The installed handler function is called only if the message is to set the real time clock The function has one parameter a pointer to a function to handle the messages See the section RTCHandler Function for a full Description of the function and its parameters If the pointer is NULL no function is called for set the real time clock commands and the default method is used set the real time clock The function has no return value Notes Call this function with the NULL pointer to disable processing of Set Real Time Clock messages This needs to be done when the application program is ended with an exit handler Use the installExitHandler function to install the exit handler If the RTC handler is not disabled within an exit handler it will remain installed and continue to operate until the controller power is cycled Changing the protocol type or Erasing the C Program from the Telepace Initialize dialog will not remove the handler If the handler is located in a RAM based application and left enabled while a different C application is downloaded the original handler will be corrupted and the system will likely not work See Also RTCHandler Function installExitHandler
6. Description The getABConfiguration function gets the DF1 protocol configuration parameters for the stream H stream does not point to a valid serial port the function has no effect ABConfig must point to a DF1 protocol configuration structure The getABConfiguration function copies the DF1 configuration parameters into the ABConfig structure and returns a pointer to it See Also setABConfiguration Example This program displays the DF1 configuration parameters for com1 include lt ctools h gt int main void struct ABConfiguration ABConfig getABConfiguration coml amp ABConfig fprintf coml Min protected address Su r n ABConfig min protected address fprintf com1 Max protected address Su r n ABConfig max protected address Document Version 1 70 5 23 2012 244 Function Specifications getclock Read the Real Time Clock Syntax include lt ctools h gt void getclock TIME time Description The getclock function reads the time and date from the real time clock hardware The getclock function copies the time and date information to the TIME structure pointed to by time Notes The time format returned by the getclock function is not compatible with the standard UNIX style functions The lO_SYSTEM resource needs to be requested before calling this function See Also getClockTime setclock Example This program displays the current date and time include lt ctool
7. TRUE set analog input types to RTD in deg F inputType 0 1 inputType 1 1 inputType 2 1 inputType 3 1 set filter inputFilter 3 minimum filter status ioWrite55050utputs 5 inputType add module scan to queue if 1oRequest MT_55050utputs Di status FALSE wait for scan to complete ioNotification MY_ EVENT wait event MY_EVENT check status of last scan if ioStatus MT _55050utputs 5 amp io status status FALSE else if io status commStatus status FALSE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 381 Function Specifications ioWrite5506Outputs Write 5506 Configuration Syntax include lt ctools h gt BOOLEAN ioWrite55060utputs UINT16 moduleAddress UINT16 amp inputType 8 UINT16 inputFilter UINT16 scanFrequency Description This function writes configuration data to the I O Table for a 5506 I O module Data are written to the module when an I O request for the module is processed moduleAddress is the address of the 5506 module Valid values are 0 to 15 inputType is a reference to an array of eight UINT16 variables selecting the input range for the corresponding analog input Valid values are e 0 O0to 5V e 1 1to5V e 2 0to20mA e 3 4to 20 mA inputFilter selects input filter sele
8. Document Version 1 70 5 23 2012 310 Function Specifications RTCHandler Function User Specified Real Time Clock Handler Function The handler function is a user specified function that handles processing of Modbus messages or DNP messages for setting the real time clock The function can have any name rtchandler is used in the Description below Syntax include lt ctools h gt void rtchandler TIME now TIME newTime 1 Description This function rtchandler is a user defined handler for processing Modbus messages or DNP messages The function is called only for messages that set the real time clock The rtchandler function should set the real time clock to the requested time If there is a delay before this can be done the time when the message was received is provided so that a correction to the requested time can be made The function has two parameters e The now parameter is a pointer to the structure containing the time when the message was received e The new parameter is a pointer to the structure containing the requested time The function does not return a value Notes The IO_SYSTEM resource has already been requested before calling this function If this function calls other functions that require the O_SYSTEM resource e g setclock there is no need to request or release the resource This function must not request or release the IO_SYSTEM resource See Also installRT CHandler
9. ioWriteDout32 Write to 32 Digital Outputs Syntax include lt ctools h gt BOOLEAN ioWriteDout32 UINT16 moduleAddress UINT32 data Description This function writes data to the I O tables for the 32 point digital output module at the specified module address Data are written to the module when an I O request for the module is processed moduleAddress is the address of the digital output module The valid range is 0 to 15 data is the output data to be written Data are written to the I O table The function returns TRUE if the data was written The function returns FALSE if the module address is invalid See Also Example This program turns ON all 32 digital outputs of a 32 point Digital Output Module at module address 0 include lt ctools h gt int main void Write data to digital output module ioWriteDout32 0 OxFFFFFFFF ioRequest MT _Dout32 0 Document Version 1 70 5 23 2012 394 Function Specifications ioWriteDout8 Write Data to 8 Point Digital Output Module Syntax include lt ctools h gt BOOLEAN ioWriteDout8 UINT16 moduleAddress UCHAR data Description This function writes data to the I O tables for the 8 point digital output module at the specified module address Data are written to the module when an I O request for the module is processed The function has two parameters the module address and the data to be written Data are read from the 8 bit
10. message stream com2 message function 2 message slaveStation 2 message slaveRegister 10001 message masterRegister 1 message length 8 message timeout 30 messag ventRequest TRUE message eventNo 1 main communication loop while TRUE send a new command request _resourc status masterSession2 release resourc IO_SYSTEM serialModbusMaster amp message IO SYSTEM if status MM R EC EIV wait for completion timeout has occurred wait_event 1 vent when response or if masterSession2 masterCmdStatu good badt allow other tasks to execute release processor Document Version 1 70 5 23 2012 665 Example Programs Master Message Example Using mTcpMasterMessage This program sends master messages on the LAN interface using Modbus TCP protocol SCADAPack 350 C Application Main Program Copyright 2001 2004 Control Microsystems Inc SEES cee EE EE ee es include lt ctools h gt master IP modes typedef enum masterIPModes t MIP OPEN CONNECTION 0 MIP CONNECTING MIP SEND MESSAGE MIP WAIT FOR RESPONSE MIP DISCONNECT MIP CLOSE MIP MODE E oa ta a a en a ee ee eee Se eee See Se eS main This routine is the main application loop fa ay pat Sy i at pr a int main void MIP MODE
11. modemDial Connect to a Remote Dial up Controller Syntax include lt ctools h gt enum DialError modemDial struct ModemSetup configuration reserve id id Description The modemDial function connects a controller to a remote controller using an external dial up modem One modemDial function may be active on each serial port The modemDial function handles port sharing and multiple dialing attempts The ModemSetup structure specified by configuration defines the serial port dialing parameters modem initialization string and the phone number to dial Refer to the Structures and Types section for a Description of the fields in the ModemSetup structure id points to a reservation identifier for the serial port The identifier provides that no other modem control function can access the serial port This parameter needs to be supplied to the modemDialEnd and modemDialStatus functions The function returns an error code DE_NoError indicates that the connect operation has begun Any other code indicates an error Refer to the dialup h section for a complete Description of error codes Notes The serial port type needs to be set to RS232_ MODEM The modemDialStatus function returns the status of the connection attempt initiated by modemDial The modemDialEnd function terminates the connection to the remote controller A pause of a few seconds is required between terminating a connection and initiating a new call This p
12. Figure 2 Queue Status at Start of main Task Execution Point 3 Event 10 Queue Running Task main This point occurs just after the echoData task is created The echoData task is higher priority than the main task so it is made the running task The main task is placed into the ready queue It will execute when it becomes the highest priority task The echoData task initializes the serial port and installs the serial port handler function signalCharacter It will then wait for an event This will suspend the task until the event occurs The signalCharacter function will generate an event each time a character is received without an error Ready Queue Event 10 Queue Running Task echoData Document Version 1 70 5 23 2012 56 Real Time Operating System Execution Point 4 Execution Point 5 Execution Point 6 Figure 3 Queue Status after Creation of echoData Task This point occurs just after the echoData task waits for event 10 It has been placed on the event queue for event 10 The highest priority task on the ready queue was the main task It is now running On the next instruction it will create another task at the same priority as main Event 10 Queue echoData 100 255 Figure 4 Queue Status After echoData Task Waits for Event This point occurs just after the creation of the auxiliary task This task is the same priori
13. body of task 2 loop event handler wait event TIME TO PRINT fprintf coml It s time for a coffee break r n I a EI POVERE JALE Ie he pe ee gs Ae The myShutdown function stops the signalling of TIME TO PRINT events when application is stopped void myShutdown void endTimedEvent TIME TO PRINT int main void TASKINFO taskStatus continuos processing task at priority 100 create _task taskl 100 applicationGroup 2 event handler needs larger stack for printf function create task task2 75 applicationGroup 4 set up task exit handler to stop signalling of events when this task ends getTaskInfo 0 amp taskStatus installExitHandler taskStatus taskID FUNCPTR myShutdown start timed event to occur every 10 sec startTimedEvent TIME TO PRINT 100 while TRUE body of main task loop other processing code Document Version 1 70 5 23 2012 636 Example Programs DataLog Example KKKKKKKKKKKKKKKKKKKKKKKKKKKKKK kk KK KK kk kk kk kk kk kk kk kk kk kk kk KK KK KKK DES Cha LN ER This program is an example to demonstrate one or more programming functions or methods This is not an application specific program and it is presented as a programming example only Control Microsystems assumes no liability for the use or application of this example program or any portion thereof SCADAPack 3
14. clear overflow error flag to re enable coml clearerr coml1 fputc character coml auxiliary The auxiliary function is a task that performs some action required by the program It does not have specific function so that the real time operating system features are clearer x void auxiliary void while TRUE add application specific code here Allow other tasks of this priority to run release processor This function creates two tasks one at priority three and one at priority 1 to demonstrate the functions of the RTOS void main void Document Version 1 70 5 23 2012 54 Real Time Operating System Create serial communication task create _task echoData 3 applicationGroup 3 Create a task same priority as main task create task auxiliary 1 applicationGroup 2 5 while TRUE add application specific code here Allow other tasks of this priority to execute E release processor Explanation of Task Execution Execution Point 1 SCADAPack 350 and 4203 controllers can execute one task at a time The Real Time Operating System RTOS switches between the tasks to provide parallel execution of multiple tasks The application program can be event driven or tasks can execute round robin one after another This program illustrates both types of execution Task execution is based upo
15. ioWriteAout4 Write Data to 4 Point Analog Output Module Syntax include lt ctools h gt BOOLEAN ioWriteAout4 UINT16 moduleAddress INT16 amp data 4 Description This function writes data to the I O tables for the 4 point analog output module at the specified module address Data are written to the module when an I O request for the module is processed The function has two parameters the module address and a reference to an array of four INT16 variables Data are read from the array and written to the I O table The valid range for moduleAddress is 0 to 15 The function returns TRUE if the data was written The function returns FALSE if the module address is invalid Notes This function writes to the output table only Use the ioRequest function to write the data to the module e Call ioRequest with the module type MT_Aout4 for analog output modules without checksum support All modules can use this module type e Call ioRequest with the module type MT_Aout4_ Checksum for analog output modules with checksum support Some modules such as the 5304 can use this module type Example This Example sets all four outputs of any analog output module to half scale include lt ctools h gt int main void INT16 dataArray 4 set all output values to one half scale dataArray 0 16384 dataArray 1 16384 dataArray 2 16384 dataArray 3 16384 Write data to analog output module at modul
16. Description The setStatusMode function controls wether APPLICATION or SYSTEM status bits are shown on the STAT LED The function has no return value Document Version 1 70 5 23 2012 542 Function Specifications setWakeSource Sets Conditions for Waking from Sleep Mode Syntax include lt ctools h gt void setWakeSource UINT32 enableMask Description The setWakeSource routine enables and disables sources that will wake up the processor It enables all sources specified by enableMask All other sources are disabled Valid wake up sources are listed below Multiple sources may be ORed together e WS NONE e WS ALL e WS_RTC_ALARM e WS _COUNTER_1_OVERFLOW e WS COUNTER 2 OVERFLOW e WS COUNTER 3 OVERFLOW e WS LED POWER_SWITCH e WS_DIN_1_CHANGE e WS _COM3_VISION Notes Specifying WS_NONE as the wake up source will keep the controller from waking except by a power on reset See Also getWakeSource setPowerMode Example The code fragments below show how to enable and disable wake up sources Wake up on all sources setWakeSource WS_ ALL Enable wake up on real time clock only setWakeSource WS_RTC_ALARM Document Version 1 70 5 23 2012 543 Function Specifications shutdown Syntax include lt ctools h gt int shutdown int socketDescriptor int howToShutdown 1 Description Shutdown a socket in read write or both directions determined by the par
17. UINT32 slaveConnections UINT32 masterConnections UINT32 unusedConnections Document Version 1 70 5 23 2012 613 Structures and Types IP CONN ECTION SUMMARY e slaveConnections is the number of active slave TCP IP connections e masterConnections is the number of active master TCP IP connections e unusedConnections is the number of unused TCP IP connections available IP_CONFIG_MODE Enumeration The IP_CONFIG_MODE enumeration defines IP configuration options The PPP options are not supported on SCADAPack 350 or 4203 controllers typedef enum ipConfigMode t IPConfig CtrlSettings IPConfig GatewayOnLAN IPConfig GatewayOnComl IPConfig GatewayOnCom2 IPConfig GatewayOnCom3 IPConfig GatewayOnCom4 IP_CONFIG MODE e oy BWwWNHMRrR OO oN ON ONON e PConfig_CtrlSettings configures IP settings from controller settings Default gateway is on LAN subnet IP_SETTINGS defines gateway address Same as IPConfig_GatewayOnLAN e PConfig_GatewayOnLAN configures IP settings from controller settings Default gateway is on LAN subnet IP_SETTINGS defines gateway address Same as IPConfig_CtrlSettings e IPConfig_GatewayOnCom1 configures IP settings from controller settings Default gateway is the com1 PPP connection e IPConfig_GatewayOnCom2 configures IP settings from controller settings Default gateway is the com2 PPP connection e IPConfig_GatewayOnComs3 configures IP settings from cont
18. data log exists DLOGS DIFFERENT data log configuration differs DLOGS INVALID data log configuration invalid DLOGS NOMEMORY failed due to lack of memory DLOGS BADID data log ID is not valid DLOGS WRONGPARAM wrong parameter except dlogID DLOGS BUFFERFULL data log buffer is full DLOGS COMPLETE operation is complete dlogStatus dlogTransferStatus Type The dlogTransferStatus enumerated type indicates the status of the current or recent auto transfer operation The transfer status only makes sense for data logs configured to perform autocopy or automove transfers when an external USB media is inserted The transfer status for data logs without auto transfer capabilities is defaulted to DLOGS_TRANSFER_DONE_ALL typedef enum dlogTransferStatus type Document Version 1 70 5 23 2012 592 Structures and Types DLOGS TRANSFER INPROGRESS Auto transfer is not done or in progress DLOGS TRANSFER DONE ALL Auto transfer is done with files transferred DLOGS TRANSFER DONE NO WORK Auto transfer is done with no files transferred DLOGS TRANSFER DONE INVALID TOKEN Auto transfer is done because of invalid token DLOGS_ TRANSFER NOT USED Auto transfer not configured or not started dlogTransferStatus DNP_ADDRESS_MAP_TABLE dnpAnalogInput The dnpAddressMapTable type describes an entry in the DNP Address Mapping Table typedef struct dnpAddre
19. else if address gt 11000 amp amp address lt 11000 SAMPLE SIZE value pMyDatabase gt statusDbase address 11001 return TRUE else if address gt 31000 amp amp address lt 31000 SAMPLE SIZE vyalue pMyDatabase gt inputDbase address 31001 return TRUE else if address gt 41000 amp amp address lt 41000 SAMPLE SIZE value pMyDatabase gt holdingDbase address 41001 return TRUE all other addresses are not handled return FALSE Be pg pe er a ee ee te ag a Ee ne ee a E This is the setdbase handler a Ee be Eege See static BOOLEAN setdbaseHandler UINT16 address Modbus register address INT16 value value to write at address Document Version 1 70 5 23 2012 655 Example Programs struct myDatabase pMyDatabase pointer to custom database pMyDatabase struct myDatabase pNvMemory gt pAllocatedMem if pMyDatabase NULL database could not be allocated return FALSE if address gt 1000 amp amp address lt 1000 SAMPLE SIZE if value 0 pMyDatabase gt coilDbase address 1001 Fl ER FALSI S pMyDatabase gt coilDbase address 1001 TRU return TRUE else if address gt 11000 amp amp address lt 11000 SAMPLE SIZE if va
20. wait_event Wait for an event to occur Document Version 1 70 5 23 2012 50 Real Time Operating System System Events Error Reporting poll_event Check if an event has occurred Continue execution if one has not occurred signal_event Signal that an event has occurred interrupt_signal_eventSignal that an event has occurred from an interrupt handler This function should only be called from within an interrupt handler There are two support functions which are not part of the RTOS that may be used with events startTimedEvent Enables signaling of an event at regular intervals endTimedEvent Terminates signaling of a regular event The RTOS defines events for communication port management and background I O operations An application program may define other events as required Care needs to be taken not to duplicate any of the event numbers declared in ctools h as system events BACKGROUND This event triggers execution of the background I O routines An application program cannot use it COM1_RCVR This event is used by communication protocols to signal a character or message received on com1 It can be used in a custom character handler see install_handler COM2_RCVR This event is used by communication protocols to signal a character or message received on com2 It can be used in a custom character handler see install_handler COM3_RCVR This event is used by communication protocols to signal a character or
21. BOOLEAN ioReadDout3Z2 UINT16 moduleAddress UINT32 amp data Description The ioReadDout32 function reads buffered data for a 32 bit digital output module Buffered data are written using the ioWriteDout32 function The function has two parameters moduleAddress is the address of the module The valid range is 0 to 15 data is reference to a UINT32 variable If the module address is valid data are copied to this variable The function returns FALSE if the moduleAddress is invalid otherwise TRUE is returned See Also ioReadDout8 ioReadDout16 Document Version 1 70 5 23 2012 358 Function Specifications ioReadDout8 Read Data From 8 point Digital Output Module Syntax include lt ctools h gt BOOLEAN ioReadDout8 UINT16 moduleAddress UCHAR amp data Description This function reads buffered data used for the 8 point digital output module at the specified module address Buffered data are written using the ioWriteDout8 function The function has two parameters the module address and a reference to an UCHAR variable If the moduleAddress is valid digital inout data are copied to the variable The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 359 Function Specifications ioReadSP2Inputs Read SCADAPack 350 Inputs Syntax include lt ctools h gt BOOLEAN ioRea
22. Document Version 1 70 5 23 2012 311 Function Specifications ioClear Turn Off all Outputs Syntax include lt ctools h gt void ioClear void Description The ioClear function turns off all outputs as follows e a reset of all WO modules is added to the I O System queue e analog outputs are set to 0 e digital outputs are set to 0 turned off Notification of the completion of I O requests made by this function may be obtained using the ioNotification function Notes The lIO_SYSTEM resource needs to be requested before calling this function Document Version 1 70 5 23 2012 312 Function Specifications ioDatabaseReset Initialize O Database with Default Values Syntax include lt ctools h gt void ioDatabaseReset void Description The ioDatabaseReset function resets the target controller to default settings e Configuration parameters are reset to the default values e Communication status counters are reset to zero e Output I O points are cleared e Locked variables are unlocked e Clear all I O forcing e Clear all I O points e Set all database locations to zero e Set I O database for real time clock to current time e Clear real time clock alarm settings e Configure serial ports with default parameters e Configure serial ports with default protocols e Clear serial port event counters e Clear store and forward configuration e Enable LED power by default and return to defau
23. Document Version 1 70 5 23 2012 693
24. Function Specifications inputType status ioWrite56070utputs 5 doutData aoutData inputFilter scanFrequency outputType add module scan to queue if ioRequest MT_5607Outputs 5 status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT check status of last scan if i1o0Status MT 56070utputs 5 amp io status status FALSE else if io status commStatus status FALSE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 389 Function Specifications ioWriteAout2 Write Data to 2 Point Analog Output Module Syntax include lt ctools h gt BOOLI EAN ioWriteAout2 UINT16 moduleAddress INT16 amp data 2 Description This function writes data to the I O tables for the 2 point analog output module at the specified module address Data are written to the module when an I O request for the module is processed The f array unction has two parameters the module address and a reference to an of two INT16 variables Data are read from the array and written to the I O table The valid range for moduleAddress is 0 to 15 The f unction returns TRUE if the data was written The function returns FALSE if the module address is invalid Document Version 1 70 5 23 2012 390 Function Specifications
25. Inter task Communication Functions There are five RTOS functions for inter task communication Refer to the Function Specification section for details on each function listed send_message Send a message envelope to another task receive_message Read a received message from the task s message queue or wait if the queue is empty poll_message Read a received message from the task s message queue Continue execution of the task if the queue is empty allocate_envelope Obtain a message envelope from free pool maintained by the RTOS or wait if none is available deallocate_envelope Return a message envelope to the free pool maintained by the RTOS Inter task Communication Structures Event Notification The ctools h file defines the structure Message Envelope Structure for inter task communication information Refer to the C Tools Structures and Types section for complete information on structures and enumeration types The event notification functions provide a mechanism for communicating the occurrence of events without specifying the task that will act upon the event This is different from inter task communication which communicates to a specific task Multiple occurrences of a single type of event are queued by the RTOS until a task waits for or polls the event Event Notification Functions There are four RTOS functions for event notification Refer to the Function Specification section for details on each function listed
26. dnpConfiguration The DNP_DISCONNECTED event indicates that the handler has disconnected from the master station The application sends this event to DNP When DNP receives this event it will request a new connection before sending unsolicited messages The DND CONNECTION REQUIRED event indicates that DNP wishes to connect to the master station DNP sends this event to the application The application should process this event by making a connection The DNP_MESSAGE_COMPLETE event indicates that DNP has received confirmation of unsolicited messages from the master station DNP sends this event to the application The application should process this event by disconnecting In many applications a short delay before disconnecting is useful as it allows the master station to send commands to the slave after the unsolicited reporting is complete The DNP_MESSAGE_TIMEOUT event indicates that DNP has attempted to send an unsolicited message but did not receive confirmation after all attempts This usually means there is a communication problem DNP sends this event to the application The application should process this event by disconnecting The dnpConfiguration type describes the DNP parameters typedef struct dnpConfiguration type UINT16 BI_ UINT16 BO NT16 masterAddress NT16 rtuAddress AR datalinkConfirm AR datalinkRetries datalinkTimeout operateTimeout applicationConfirm maximumResponse applicationRetries app
27. fprintf com1 Priority d r n settings priority else Document Version 1 70 5 23 2012 263 Function Specifications fprintf coml Serial port is not valid r n Document Version 1 70 5 23 2012 264 Function Specifications getProtocolSettingsEx Reads extended protocol settings for a serial port Syntax include lt ctools h gt BOOLEAN getProtocolSettingsEx FILE stream PROTOCOL SETTINGS EX pSettings 1 Description The setProtocolSettingsEx function sets protocol parameters for a serial port This function supports extended addressing and Enron Modbus parameters The function has two arguments e port specifies the serial port It is one of com1 com2 or com3 e pSettings is a pointer to a PROTOCOL_SETTINGS_ExX structure Refer to the description of the structure for an explanation of the parameters The function returns TRUE if the settings were retrieved It returns FALSE if the stream is not valid Notes Extended addressing and the Enron Modbus station are available on the Modbus RTU and Modbus ASCII protocols only See the TeleBUS Protocols User Manual for details See Also setProtocolSettingsEx setProtocolSettings start_protocol get_protocol get_protocol_status set_protocol modemNotification Example This program displays the protocol configuration for com1 include lt ctools h gt int main void PROTOCOL SETTINGS EX settings
28. inputs Refer to the SCADAPack 350 System Hardware Manual for further information on controller counter inputs and counter input modules There are three library functions related to counters Refer to the Function Specification section for details on each function listed ioReadCounter5232 Read buffered data from the 5232 counter inputs ioReadCounter4 Read buffered data from any 4 point Counter input module Status LED and Output Functions The status LED and output indicate alarm conditions The STAT LED blinks and the STATUS output opens when an alarm occurs The STAT LED turns off and the STATUS output closes when alarms clear The STAT LED blinks a binary sequence indicating alarm codes The sequences consist of long and short flashes followed by an off delay of 1 second The sequence then repeats The sequence may be read as the Controller Status Code Refer to the SCADAPack 350 System Hardware Manual or the SCADAPack 4203 Hardware Manual for further information on the status LED and digital output There are three library functions related to the status LED and digital output Refer to the Function Specification section for details on each function listed clearStatusBit Clears bits in controller status code getStatusBit Gets the bits in controller status code setStatusBit Sets the bits in controller status code UO Forcing Functions There are six library functions related to I O forcing Refer to the Function Speci
29. print data if done 5 scan dinData ainData 5 amp io status io status commStatus fprintf coml status u Dins 0 to 7 X Ain 4 d r n status dinData 0 ainData 4 done TRUE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 339 Function Specifications ioRead5606Outputs Read 5606 Outputs Syntax include lt ctools h gt BOOLEAN ioRead56060utputs UINT16 moduleAddress UCHAR amp doutData 2 INT16 amp aoutData 2 UINT16 amp inputType 8 UINT16 amp inputFilter UINT16 amp scanFrequency UINT16 SoutputType Description This function reads buffered data from the digital and analog outputs of a 5606 I O module Buffered data are written using the ioWrite5606Outputs function moduleAddress is the address of the 5606 module Valid values are 0 to 7 doutData is a reference to an array of two UCHAR variables Digital data for the 16 outputs are written to this array One bit in the array represents each output point aoutData is a reference to an array of two INT16 variables Analog data for the two analog outputs are written to this array inputType is a reference to an array of eight UINT16 variables Analog input measurement types are written to this array Valid values are e 0 0to 5V e 1 0to10V e 2 0to20mA e 3 4to20mA inputFilter is a reference to a UINT16 v
30. rsp_received is the number of responses received by the master_message function rsp_sent is the number of responses sent command is the status of the last protocol command sent task_id is the ID of the protocol task This field is used by the set_protocol function to control protocol execution stored_messages is the number of messages stored for forwarding forwarded_messages is the number of messages forwarded PORT_CHARACTERISTICS The PORT_CHARACTERISTICS type is a structure that contains serial port characteristics typedef struct portCharacteristics tag UINT16 dataflow UINT16 buffering UINT16 protocol UINT32 options PORT CHARACTERISTICS dataflow is a bit mapped field describing the data flow options supported on the serial port ANDing can isolate the options with the PC_FLOW_RX_RECEIVE_STOP PC_FLOW_RX_XON_XOFF PC_FLOW_TX_IGNORE_CTS or PC_FLOW_TX_XON_XOFF macros buffering describes the buffering options supported No buffering options are currently supported protocol describes the protocol options supported The macro PC_PROTOCOL_RTU_FRAMING is the only option supported options describes additional options supported No additional options are currently supported Document Version 1 70 5 23 2012 626 Structures and Types pstatus READSTATUS The pstatus structure contains serial port status information struct pstatus UINT16 framing NT16 parity NT16 c_over
31. struct prot settings UCHAR type UCHAR station UCHAR priority UINT16 SFMessaging 1 type is the protocol type It may be one of NO_PROTOCOL MODBUS_RTU MODBUS_ ASCII AR FULL BCC AB_HALF_BCC AB_FULL_CRC AB_HALF_CRC DNP macros To set the remaining settings use the function mTcpSetinterfaceEx station is the station address of the controller Each serial port may have a different address The valid values are determined by the communication protocol This field is not used if the protocol type is NO PROTOCOL priority is the task priority of the protocol task This field is not used if the protocol type is NO PROTOCOL SFMessaging is the enable Store and Forward messaging control flag The prot_status structure contains protocol status information struct Drot status UINT16 command_errors UINT16 format errors UINT16 checksum errors UINT16 cmd received UINT16 cmd sent UINT16 rsp received UINT16 rsp sent Document Version 1 70 5 23 2012 625 Structures and Types UINT16 command INT16 task id UINT16 stored messages UINT16 forwarded messages 1 command_errors is the number of messages received with invalid command codes format_errors is the number of messages received with bad message data checksum_errors is the number of messages received with bad checksums cmd_received is the number of commands received cmd_sent is the number of commands sent by the master_message function
32. 71 pResponsett pResponse O pResponsett pResponse F pResponsett pResponse F pResponse t responseLength 4 return NORMAL else if pMessage 1 request resource IO SYSTEM setdbase MODBUS 1 1 release_resource IO SYSTEM pResponse response pResponse 71 pResponsett pResponse O pResponsett pResponse N pResponsett responseLength 3 return NORMAL return FUNCTION NOT HANDLED T Document Version 1 70 5 23 2012 649 Example Programs else return FUNCTION NOT HANDLED static void myshutdown void removeModbusHandler myModbusHandler This routine is the modbus slave application Serial port com2 is configured for Modbus ASCII protocol Register Assignment is configured The modbus handler is installed The exit handler is installed Siete SSS S2eS2e RSS SS SSeS SSS Sf SSeS SSeS Sess int main void TASKINFO taskStatus struct pconfig portSettings struct prot_settings protSettings portSettings baud BAUD9600 portSettings duplex FULL portSettings parity NONE portSettings data_bits DATA7 portSettings stop bits STOP1 portSettings flow rx RFC_NONE portSettings flow tx TFC_NONE portSettings type RS232 portSettings timeout 600 set _port com2 amp portSettings get protocol com2 amp protSettings protSettings station 1 pr
33. Document Version 1 70 5 23 2012 677 Porting Existing C Tools Applications The installModbusHandler is used to add user defined extensions to the standard Modbus protocol To uninstall a Modbus handler in a SCADAPack 32 C application the same function is called with the NULL pointer SCADAPack C applications support the installation of multiple Modbus handlers In order to remove a specific Modbus handler the new function removeModbusHandler is used Calling installModbusHandler with the NULL pointer has no effect Unsupported C Tools Functions The following sections describe functions that are supported by the SCADAPack 32 C Tools but are not supported by the SCADAPack C Tools Refer to these sections when porting existing C Tools Applications to the SCADAPack 350 and 4203 Timers The following C Tools Timer functions are not supported Use the functions readStopwatch or startTimedEvent instead runTimers settimer timer Option Switch Function The following C Tools function is not supported optionSwitch IP Functions The following C Tools functions are not supported Document Version 1 70 5 23 2012 678 Porting Existing C Tools Applications Function tfGetOobDataOffset tfGetPppDnslpAddress tfGetPppPeerlpAddress tfGetSendCompltBytes tfGetWaitingBytes tfGetZeroCopyBuffer tflnetToAscii tfloctl tfPingClose tfPingGetStatistics tfPingOpenStart tfPppSetOption tfRead tf
34. If the variable is found TRUE is returned and the message is written to the string pointed to by msg If the variable is not found or if the IEC 61131 1 Symbols Status is invalid FALSE is returned and the buffer is left unchanged The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum The pointer msg needs to point to a character string large enough to hold the maximum length declared for the specified message variable plus two length bytes and a null termination byte i e max declared length 3 IEC 61131 1 message variables have the following format Byte Description Location Maximum length as declared in IEC 61131 1 Dictionary 1 to 255 Current Length number of bytes up to first null byte in message data 0 to maximum length First message data byte Last byte in message buffer max 2 Null termination byte Terminates a message having the maximum length Notes 1 2 This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address
35. SCADAPack 350 and 4203 controllers use flash memory to store controller settings The flash memory functions have one parameter flags indicating which areas to store into flash A sum of more than one area may be selected Valid flags are listed below and defined in ctools h Area Flag Loaded on Reset Controller Settings in this Area CS_ETHERNET Ethernet MAC address CS_OPTIONS Controller factory options CS PERMANENT Saved settings loaded Controller type IP address on Service and Run Gateway Network mask IP Boot Configuration mode Lock state Replaced with default and password I O System settings on Cold Boot settings I O error indication setting Telepace Firmware only Document Version 1 70 5 23 2012 61 Overview of Programming Functions System Functions Area Flag Loaded on Reset Controller Settings in this Area Register assignment Outputs on stop settings Saved settings loaded Serial port settings Serial on Run Boot protocol settings Modbus TCP Default settings settings HART I O settings loaded on Service LED power settings Store and Boot forward table Replaced with default settings on Cold Boot There are two library functions related to the configuration data flash memory Refer to the Function Specification section for details on each function listed flashSettingsLoad This function stores the controller settings in the indicated area or areas to flash memory fla
36. To connect to a controller using Telepace firmware e Connect the cable to a serial port on the PC e Connect the cable to the com3 serial port on the controller e Open the Telepace program To configure the PC serial port select PC Communication Settings from the Telepace Communications menu The PC Communications Settings dialog will appear The default settings shown in this dialog are the same as the default serial port settings for the controller Document Version 1 70 5 23 2012 28 Getting Started Modbus RTU Configuration General Advanced Information Communication Component Modbus RTU Control Microsystems Inc Modbus Communication Settings Addressing Standard zl Station PP Timeout br seconds Attempts 3 m Serial Port Settings Port Im sl Baud aen rs Parity Nowe sl Stop Bits itt sl Connection Type Direct Connection zl Use the drop down selector for the Port box to select the PC serial port being used Once the desired serial communication parameters have been set click on the OK button The serial ports are set to their default parameters when a Cold Boot is done These settings are 9600 baud 8 data bits no parity 1 stop bit Modbus RTU protocol and station address 1 Loading the Application To load the Hello C application into the controller e Select Controller gt C C Program Loader e Click Add e Click Browse e Locate the application
37. class2Pol1l0ffset class3Poll0ffset timeSyncOffset classlMaxEvents class2MaxEvents class3MaxEvents savelINFlagsRegister dnpMasterPollTableEx Document Version 1 70 5 23 2012 606 Structures and Types dnpPointType dnpRemoteStationAddress is the remote DNP station address classOPollRate is the Class 0 Polling rate class1PollRate is the Class 1 Polling rate class2PollRate is the Class 2 Polling rate class3PollRate is the Class 3 Polling rate timeSyncRate is the time synchronization rate unsolicitedResponseFlags are the DNP Master Unsolicited Response enable flags TimeSyncRate is the time synchronisation rate unsolicitedResponseF lags are the flags for enabling Unsolicited Responses classOPollOffset is the offset for Class 0 Polling class1PollOffset is the offset for Class 1 Polling class2PollOffset is the offset for Class 2 Polling class3PollOffset is the offset for Class 3 Polling timeSyncOffset is the offset for time synchronization class1MaxEvents is the maximum limit of Class 1 events in poll response class2MaxEvents is the maximum limit of Class 2 events in poll response class3MaxEvents is the maximum limit of Class 3 events in poll response savellNFlagsRegister The enumerated type DNP_POINT_TYPE includes all allowed DNP data point types typedef enum dnpPointType DNP_POINT TYPE BI POINT 0 binary input AI16 POINT 16 bit analog input
38. getTaskinfo Get Information on a Task Syntax include lt ctools h gt BOOLEAN getTaskInfo INT32 taskID TASKINFO pTaskInfo Description The getTaskInfo function returns information about the task specified by taskID If taskID is 0 the function returns information about the current task The function copies task information to the TASKINFO structure pointed to by pTaskinfo FALSE is returned if the task specified by task D doesn t exist otherwise TRUE is returned and the data is copied Refer to the Structures and Types section for a Description of the fields in the TASKINFO structure Example See the Get Task Status Example in the Examples section Document Version 1 70 5 23 2012 277 Function Specifications getVersion Get Firmware Version Information Syntax include lt ctools h gt VERSION getVersion void Description The getVersion function obtains firmware version information It returns a VERSION structure Refer to the Structures and Types section for a Description of the fields in the VERSION structure Notes The version information can be used to adapt a program to a specific type of controller or version of firmware For Example a bug work around could be executed only if older firmware is detected Example This program displays the version information include lt ctools h gt int main void struct prot settings settings VERSION versionInfo Disab
39. if getProtocolSettingsEx coml amp settings fprintf coml Type d r n settings type fprintf coml Station Sd r n settings station fprintf coml Address Mode d r n settings mode fprintf coml SF Sd r n settings SFMessaging fprintf coml Priority d r n settings priority fprintf coml Enron S d r n settings enronEnabled fprintf coml Enron station d r n Document Version 1 70 5 23 2012 265 Function Specifications settings enronStation fprintf coml Serial port is not valid r n Document Version 1 70 5 23 2012 266 Function Specifications get_protocol_status Get Protocol Information Syntax include lt ctools h gt struct prot status get protocol status FILE stream Description The get_protocol_status function returns the protocol error and message counters for stream H stream does not point to a valid serial port the function has no effect Refer to the Overview of Functions section for detailed information on communication protocols See Also clear_protocol_status Example This program displays the checksum error counter for com2 include lt ctools h gt int main void struct prot Status status status get protocol status com2 fprintf coml Checksum d r n status checksum errors Document Version 1 70 5 23 2012 267 Function Specifications getSFTranslation Read Store and Forward
40. set program status so memory is not re allocated until next program download setProgramStatus FUNCPTR main PROGRAM EXECUTED zero fill new custom database memset pNvMemory gt pAllocatedMem 0 MEM SIZE else memory could not be allocated pNvMemory gt pAllocatedMem NULL install exit handler to remove the custom database if the application is stopped or erased getTaskInfo 0 amp taskStatus installExitHandler taskStatus taskID FUNCPTR myshutdown Document Version 1 70 5 23 2012 657 Example Programs install database handlers installDbaseHandler dbaseHandler installSetdbaseHandler setdbaseHandler This routine is the main program The custom i o database is initialized The database is then updated continuously with I O data in the main loop a a a e a a een a a a ene Rn ne PO ae a le ne int main void UINT16 dinData data from 16 Din points INT16 ainData 8 data from 8 Ain points UINT16 doutData 0 data written to Dout points UINT16 index initialize custom i o database initializeDatabase main loop while TRUE write data to Output tables ioWrite56010utputs doutData add I O requests to the I O System queue ioRequest MT 560lInputs 0 ioRequest MT_56010utputs 0 this event signals completion of preceding i o requests ioNotification SCAN EVENT
41. 1 get the command byte Document Version 1 70 5 23 2012 234 Function Specifications command pCommand 0 switch command read unit status command case 7 iff the response buffer is large enough if responseSize gt 2 build the response header pResponse 0 pCommand 0 set the unit status pResponse 1 17 set response length pResponseLength 2 indicate the command worked result NORMAL else buffer is to small to respond result ILLEGAL FUNCTION break add cases for other commands here default command is invalid result ILLEGAL FUNCTION else command is too short so return error result ILLEGAL FUNCTION return result This function unhooks the protocol handler when the main task ends void mainExitHandler void unhook the handler function enroniInstallCommandHandler NULL int main void TASKINFO thisTask Document Version 1 70 5 23 2012 235 Function Specifications install handler to execute when this task ends thisTask getTaskInfo 0 installExitHandler thisTask taskID FUNCPTR mainExitHandler install handler for Enron Modbus enroniInstallCommandHandler commandHandler infinite loop of main task while TRUE add application code here Document Ve
42. 20 ledControl state LED OFF ledSetDefault ledControl release resource IO SYSTEM the reset of the program Document Version 1 70 5 23 2012 410 Function Specifications listen Syntax include lt ctools h gt int listen int socketDescriptor int backlog 1 Description To accept connections a socket is first created with socket a backlog for incoming connections is specified with listen and then the connections are accepted with accept The listen call applies only to sockets of type SOCK_STREAM The backLog parameter defines the maximum length the queue of pending connections may grow to If a connection request arrives with the queue full and the underlying protocol supports retransmission the connection request may be ignored so that retries may succeed For AF_INET sockets the TCP will retry the connection If the backlog is not cleared by the time the TCP times out connect will fail with ETIMEDOUT Parameters socketDescriptor The socket descriptor to listen on backlog The maximum number of outstanding connections allowed on the socket Returns 0 Success 1 An error occurred listen can fail for the following reason EADDRINUSE The address is currently used by another socket EBADF The socket descriptor is invalid EOPNOTSUPP The socket is not of a type that supports the operation listen Document Version 1 70 5 23 2012 411 Function Specifica
43. 5 23 2012 672 Porting Existing C Tools Applications Porting Existing C Tools Applications Porting SCADAPack 32 C Applications to the SCADAPack 350 and 4203 Compiler Differences between Hitachi and GNU The Hitachi compiler used with the SCADAPack 32 has the following difference with GNU compiler used with the SCADAPack 350 and 4203 The order of bit fields is reversed Bit field ordering is not specified by the C standard It is left to the compiler maker Existing programs using bit fields need to be modified if the order of the bit fields affects the operation of the program If the bit fields are being used only for space efficiency the program does not need rewriting Porting Existing C Tools Applications Existing SCADAPack 32 C applications are highly compatible with the SCADAPack 350 and 4203 C Tools However changes are necessary The following guide describes the steps in porting an application Copy SCADAPack C Application Framework Begin by making a copy of the SCADAPack C application framework using the IEC 61131 1 sample application or the Telepace sample application By default the samples are installed at C Program Files Control Microsystems CTools Controller Framework Applications Make a copy of one of the following directories e C Program Files Control Microsystems CTools Controller Framework Applications Telepace e C Program Files Control Microsystems CTools Controller Framework Appli
44. 5 23 2012 630 Structures and Types taskinfo_tag TIME it is waiting If the status field is TS_WAIT_RESOURCE then requirement indicates on which resource it is waiting error is the task error code This is the same value as returned by the check_error function type is the task type It will be either SYSTEM or applicationGroup The taskInfo_tag structure contains start up task information struct taskInfo tag void address UINT16 stack UINT16 identity 1 address is the pointer to the start up routine stack is the required stack size for the routine identity is the type of routine found STARTUP_APPLICATION or STARTUP_SYSTEM The TIME structure contains time and date for reading or writing the real time clock struct clock UINT16 year NT16 month NT16 day NT16 dayofweek NT16 hour NT16 minute NT16 second NT16 hundredth TIME C C C K C CC HHHHHHH year is the current year It is in the range 97 for the year 1997 to 96 for the year 2096 month is the current month It is in the range 1 to 12 day is the current day Itis in the range 1 to 31 dayofweek is the current day of the week It is in the range 1 to 7 The application program defines the meaning of this field hour is the current hour It is in the range 00 to 23 minute is the current minute It is in the range 00 to 59 second is the current second It is in the range 00 to 59 hundredth is the
45. BOOLEAN status IO STATUS io status main loop while TRUE add module scan to queue if i1oRequest MT_4203DRInputs 0 Document Version 1 70 5 23 2012 317 Function Specifications status FALSE else wait for scan to complete ioNotification MY EVENT wait event MY_EVENT vead input data from last scan status ioRead4203DRInputs dinData ainData cinData check status of last scan if status FALSE insert code to handle the failure here else if io0Status MT_4203DRInputs 0 amp io status insert code to handle the failure here else if io status commStatus insert code to handle the failure here else The last scan was successful so print the data ainData fprintf com2 status u Dins 0 SX Ain Sd r n status dinData done TRUE sleep processor for 100ms sleep processor 100 Document Version 1 70 5 23 2012 318 Function Specifications ioRead4203DSInputs Read 4203 DS Inputs Syntax include lt ctools h gt BOOLEAN ioRead4203DSInputs UCHAR amp dinData INT16 amp ainData 3 UINT32 amp cinData l 2 Description This function reads buffered data from the digital and analog inputs of the 4203 DS I O Buffered data are updated when an I O request for the module is processed dinData is a reference to a UCHAR variab
46. Document Version 1 70 5 23 2012 364 Function Specifications Document Version 1 70 5 23 2012 365 Function Specifications ioSetConfiguration Set LO Controller Configuration Syntax include lt ctools h gt BOOLEAN ioSetConfiguration const IO CONFIG amp settings Description This function sets the I O controller configuration and adds a request to write the settings to the I O controller The function has one argument a reference to an O_CONFIG structure The function returns TRUE if the request was added The function returns FALSE if there is no room in the request queue or if there is an error in the settings Document Version 1 70 5 23 2012 366 Function Specifications ioStatus Read Status of Last Scan of Specified LO Module Syntax include lt ctools h gt BOOLEAN ioStatus IO TYPE moduleType UINT16 moduleAddress IO STATUS status Description This function reads the status of the last scan of the specified I O module The function has three arguments the module type the module address and a pointer to an O_STATUS structure Refer to the table below for valid I O module types and address ranges The function returns TRUE if status information was copied to the structure pointed to by status The function returns FALSE if an argument is invalid is no room in the request queue or if an argument is invalid 01015 1015 Document Version 1 70 5 23 2012
47. Function Specifications ioReadCounterSP2 Read Data From the SCADAPack 350 Counter Inputs Syntax include lt ctools h gt BOOLEAN ioReadCounterSP2 UINT32 amp data 3 Description This function reads buffered data from the SCADAPack 350 counter inputs Buffered data are updated when an I O request for the module is processed The function has one parameter a reference to an array of three UINT32 variables The buffered data are copied to the array The maximum count is 4 294 967 295 Counters roll back to 0 when the maximum count is exceeded The function returns TRUE Document Version 1 70 5 23 2012 352 Function Specifications ioReadDin16 Read Data From 16 point Digital Input Module Syntax include lt ctools h gt BOOLEAN ioReadDinl6 UINT16 moduleAddress UINT16 amp data Description This function reads buffered data from the 16 point digital input module at the specified module address Buffered data are updated when an I O request for the module is processed The function has two parameters the module address and a reference to an INT16 variable If the moduleAddress is valid digital input data are copied to the variable The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 353 Function Specifications ioReadDin32 Read 32 Digital Inputs Syntax in
48. If there is an invalid setting FALSE is returned and the settings are not saved otherwise TRUE is returned To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request resource FLASH MEMORY flashSettingsSave CS PERMANENT release resource FLASH MEMORY Document Version 1 70 5 23 2012 239 Function Specifications flashSettingsLoad Load Controller Settings from Flash Syntax include lt ctools h gt BOOLEAN flashSettingsLoad UINT32 areaFlags Description This function loads the controller settings in the indicated area or areas from flash memory Settings in other areas are not affected The function has one parameter areaFlags indicating which areas to read from flash A sum of more than one area may be selected If an unsupported flag is set the flag has no effect If there is no supported flag set e g areaFlags 0 nothing is done The function has no return value See the function flashSettingsSave for a list of valid flags Notes The FLASH_MEMORY resource needs to be requested before calling this function Document Version 1 70 5 23 2012 240 Function Specifications flashSettingsSave Save Controller Settings to Flash Syntax include lt ctools h gt BOOLEAN flashSettingsSave UINT32 areaFlags Description This function stores
49. Non Volatile Data Sections UO System Functions C Tools applications could make any variable non volatile by renaming the memory section where it was located This was done using a compiler pragma directive This is not supported on the SCADAPack 350 and 4203 SCADAPack C Tools applications can make variables non volatile by locating them in SRAM There is 8 KB of SRAM available for static application variables If this is not enough up to 1 MB of SRAM is available for dynamic non volatile memory allocation See the function allocateMemory To create a non volatile section refer to the section Non Volatile Memory nvMemory h The SCADAPack 350 SCADAPack 4203 and SCADAPack 32 use a different I O system architecture than the SCADAPack I O operations can be performed in parallel with application program execution This improves the performance of IEC 61131 1 and Telepace applications and can have similar impact on user applications In the new architecture I O requests are added to a queue Requests are read from the queue and processed by separate I O controller hardware Data are stored in I O arrays that can be read and written by the application program The Document Version 1 70 5 23 2012 684 Porting Existing C Tools Applications application program can also synchronize with the I O controller to determine when a set of I O requests is complete Existing application programs need to be rewritten to use the new I O
50. amp settings settings type DNP set protocol com2 amp settings Save port settings so DNP protocol will automatically start request resource IO SYSTEM save EEPROM RUN release resource IO SYSTEM Configure Binary Output Points for index 0 index lt configuration BO number index Document Version 1 70 5 23 2012 181 Function Specifications binaryOutput modbusAddressl 1 index binaryOutput modbusAddress2 1 index binaryOutput controlType NOT PAIRED dnpSaveBOConfig index amp binaryOutput Configure Binary Input Points for index O index lt configuration BI number index binaryInput modbusAddress 10001 index binaryInput class CLASS 1 binaryInput eventTyp COS dnpSaveBIConfig index amp binaryInput Configure 16 Bit Analog Input Points for index 0 index lt configuration AI16 number index analogInput modbusAddress 30001 index analogInput class CLASS 2 analogInput deadband 1 dnpSaveAI16Config index g amp analogInput Configure32 Bit Analog Input Points for index 0 index lt configuration AI32 number indext analogInput modbusAddress 30001 index 2 analogInput class CLASS 2 analogInput deadband 1 dnpSaveAI32Config index amp analogInput Configure 16 Bit Analog Output Points for index O index
51. aoutData 1 32767 status ioWriteSP20utputs doutData aoutData Document Version 1 70 5 23 2012 396 Function Specifications add module scan to queue if ioRequest MT_SP2Outputs 0 status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT check status of last scan if i1oStatus MT SP2Outputs 0 amp io status status FALSE else if io_status commStatus status FALSE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 397 Function Specifications ipFindFriendlylPAddress Checks if an address is in the Friendly IP List Syntax BOOLEAN ipFindFriendlyIPAddress UINT32 ipAddress Description This function checks if the IP address ipAddress is in the Friendly IP List The function returns TRUE if the supplied ipAddress is in the Friendly IP List Otherwise FALSE is returned Document Version 1 70 5 23 2012 398 Function Specifications ipGetConnectionSummary Get Summary of Active TCP IP Connections Syntax include lt ctools h gt void ipGetConnectionSummary IP CONNECTION SUMMARY pSummary Description The ipGetConnectionSummary function returns a summary of the number of active IP connections The IP connections include Modbus TCP Modbus RTU over UDP Modbus ASCII over UDP DNP over TCP
52. else Turn off FORCE LED if DIN1 is OFF forceLed LED OFF Suspend DIN1 OFF or resume DIN1 ON loging ff if dinlCurrentState dinlPreviousState if dinlCurrentState dlogStatusInfo dlogResume dlogIdNumber dlogStatusInfo dlogSuspend dlogIdNumber dinlPreviousState dinlCurrentState Document Version 1 70 5 23 2012 641 Example Programs DNP Configuration Example SCADAPack 350 C Application Main Program Copyright 2001 2004 Control Microsystems Inc The following program demonstrates how to configure DNP for operation on com3 of the SCADAPack 350 extern C add prototypes here UINT32 mainPriority 100 UINT32 mainStack 4 UINT32 applicationGroup 0 UINT16 index loop index PROTOCOL CONFIGURATION protocolSettings protocol settings dnpConfiguration configuration configuration settings dnpBinaryOutput binaryOutput binary output settings dnpBinaryInput binaryInput binary input settings dnpAnalogInput analogInput analog input settings dnpAnalogOutput analogOutput analog output settings dnpCounterInput counterInput conter input settings Document Version 1 70 5 23 2012 642 Example Programs Stop any protocol currently active on com port 3
53. input point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetAl32Contig Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 205 Function Specifications dnpSaveAlSFConfig Save Short Floating Point Analog Input Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveAISFConfig UINT16 point dnpAnalogIinput pAnalogInput 1 Description The dnpSaveAlSFConfig function sets the configuration of a DNP short floating point analog input point The function has two parameters the point number and a pointer to a configuration structure The function returns TRUE if the configuration was successfully written or FALSE otherwise if the point number is not valid or the configuration is not valid or if the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 206 Function Specifications dnpSaveAO16Config Save DNP 16 Bit Analog Output Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveAOl16Config UINT16 point dnpAnalogOutp
54. iongtudna pariy eror 2 reseed aways a outerowveiow oo y o oeie o E e f bit 7 of the high byte is cleared the high byte contains a command response summary The table shows common values Other values may be defined for specific commands Consult the documentation for the HART device 32 Busy the device is performing a function that cannot be interrupted by this command 64 Command not Implemented the command is not defined for this device e The low byte contains the field device status This field is bit mapped The table shows the meaning of each bit as defined by the HART protocol specifications Consult the documentation for the HART device for more information et eects e configuration changed more status available use command 48 to read primary variable analog output fixed non primary variable out of limits primary variable out of limits primary variable analog output saturated See Also hartSetConfiguration Document Version 1 70 5 23 2012 295 Function Specifications hartGetConfiguration Read HART Module Settings Syntax include lt ctools h gt BOOLEAN hartGetConfiguration UINT16 module HART SETTINGS settings Description This function returns the configuration settings of a 5904 module The function has two parameters the module number of the 5904 module 0 to 3 and a pointer to the settings structure The function returns TRUE if the setti
55. lee erte ON E 429 PVT CP Get Onl EE 430 MTC ellene 431 MT CPGetMtS ACS EN ss xsi vi ess cece vs veces es veep uses sees et eas vysnus vous steasseepaesveanseerspeeeareees 432 Ke e lee 433 ue ve E ue RE 434 MTCPSetlnterface AA 435 MTcpSetlnterfaceEX A 436 IMIPCDSCTPIOLOCO TTT 437 MTcpMasterClose ou eee eeennee erect ee eneneeeetenaeeeeseneeeeesenaeeeenenaeeeene 438 mTcpMasterDisCOnne ct 0 ce eeeeeceeeeeeeneeeeeeeneeeetenaeeeeeeeeeeeetenaeeeeseneeeeee 439 mTcepMasterMessage seieseesieeesirrssrrissrrirssrtinnsttintnstintnntirnnsttnnnnetnnnnnennnnt 440 Ree EE 442 MT cpMasterStatus e 444 MTCDRUNMSEIVED cccceceesccceeeeseeceetenseneeeeesenseesesenaeesessaeseseesensesseseeaeesenseneentegs 445 Alte 446 lte 447 eTAto ID ar Ere Srrerereree reer erecer Renee peer rec er E rece rete 448 ll 450 fete Fall t lb beeerorteereeererertrnccerrtrercrertrertrrrttercrsrtrarterrtcerrrerercrtrtrtecrsrereccrtcr treet reer 452 POIAB SIW erer 453 DEEM 454 POS HIE 456 ele 457 een le 458 DOEN 459 ee 460 Document Version 1 70 5 23 2012 ro UT U ModE E 461 readBoolVarlablev scnci ini inl ee inh ee a 462 ele re 464 read nl elle ele EE 465 readintVarable ei ni an an a A aa 466 ele Ee VE Ee EE 468 BEO ln CEINE ol CA une StEASES ERT SUEAEESREKEEEL ELE SES EEN T 470 ele tele et A PENI TEE AES EE SEEE EEE EEEE 472 Cal TEL DOS steen TA E E E E E E EE 473 read Mu e EE 474 receive EE 476 LEE 477 FOCVITONV te REENEN EE EE EE
56. lt configuration AO16 number indext analogOutput modbusAddress 40001 index dnpSaveAO16Config index amp analogOutput Configure 32 Bit Analog Output Points for index 0 index lt configuration AO32 number index analogOutput modbusAddress 40101 index 2 dnpSaveAO32Config index g amp analogOutput Configure 16 Bit Counter Input Points for index 0 index lt configuration CI16 number indext Document Version 1 70 5 23 2012 182 Function Specifications counterInput modbusAddress 30001 index counterInput class CLASS 3 counterInput threshold 1 dnpSaveC1I16Config index amp counterInput Configure 32 bit Counter Input Points for index 0 index lt configuration CI32 number index t 30001 index 2 CLASS 3 l counterInput modbusAddress counterInput class counterInput threshold dnpSaveCI32Config index amp counterInput add additional initialization code for your application here loop forever while TRUE add additional code for your application here allow other tasks of this priority to execute release processor return Document Version 1 70 5 23 2012 183 Function Specifications dnpGetConfigurationEx Read DNP Extended Configuration Syntax BOOLEAN dnpGetConfigurationEx dnpConfigurationEx pDnpConfigurationEx 1 Descr
57. release processor Document Version 1 70 5 23 2012 345 Function Specifications ioReadAin4 Read Data From 4 point Analog Input Module Syntax include lt ctools h gt BOOLEAN ioReadAin4 UINT16 moduleAddress INT16 amp data 4 Description This function reads buffered data from the 4 point analog input module at the specified module address Buffered data are updated when an I O request for the module is processed The function has two parameters the module address and a reference to an array of four INT16 variables If the moduleAddress is valid analog input data are copied to the array The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 346 Function Specifications ioReadAin8 Read Data From 8 point Analog Input Module Syntax include lt ctools h gt BOOLEAN ioReadAin8 UINT16 moduleAddress INT16 amp data 8 Description This function reads buffered data from the 8 point analog input module at the specified moduleAddress Buffered data are updated when an I O request for the module is processed The function has two parameters the module address and a reference to an array of eight INT16 variables If the moduleAddress is valid analog input data are copied to the array The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module
58. release resource IO SYSTEM fprintf coml It s quitting time r n int main void struct prot settings settings ALARM SETTING alarm Disable the protocol on serial port 1 settings type NO PROTOCOL settings station 1 settings priority 250 settings SFMessaging FALSE request _ resource IO SYSTEM set _protocol coml amp settings release resource IO SYSTEM Install clock handler function installClockHandler alarmHandler Create task for processing alarm events create task processAlarms 75 applicationGroup 4 Set real time clock alarm alarm type AT ABSOLUTE alarm hour 16 alarm minute 0 alarm second 0 request resource IO SYSTEM setClockAlarm alarm release resource IO SYSTEM while TRUE Document Version 1 70 5 23 2012 653 Example Programs body of main task loop other processing code Allow other tasks to execute release processor Install Database Handler Example This program assumes that the pointer pAllocatedMem has been declared in nvMemory h This is a sample IEC 61131 1 application for the installDbaseHandler and installSetdbaseHandler functions This sample program demonstrates database handlers for the Modbus registers 1001 to 1100 11001 to 11100 31001 to 31100 41001 to 41100 This database is allocated in non volatile memory
59. status u Dins 0 X Ain 2 d r n status dinData ainData 2 done TRUE sleep processor for 100ms sleep processor 100 Document Version 1 70 5 23 2012 320 Function Specifications ioRead5210Inputs Read SCADAPack 330 controller board inputs Syntax include lt ctools h gt BOOLEAN ioRead5210Inputs UINT32 amp counterData 3 UCHAR amp dinData 1 Description This function reads buffered data from the digital and counter inputs of a SCADAPack 330 controller board Buffered data are updated when an I O request for the module is processed counterData is a reference to an array to receive the counter input values Data from three counter inputs is written to this variable dinData is a reference to a variable to receive the digital input values e Bit 0 of this variable is written with the com3 HMI power status e Bits 1 to 7 are not used The function returns TRUE as no I O errors are possible See Also ioRead52100utputs Example This program displays the values of the 7 internal digital inputs and the single physical digital input The first counter input is displayed as well include lt ctools h gt include nvMemory h define MY EVENT 1 void main void UCHAR dinData UINT32 counterData 3 IO STATUS io status BOOLEAN status main loop while TRUE add module scan to queue if i1o0Request MT_5210Inputs 0
60. the records that have been read and leaves any records added since the records were read If the sequence number specifies a record that is not in the log no records are removed See Also See example DataLog program in the Example Programs section datalogReadStart datalogReadNext datalogWrite Example include lt ctools h gt int main void UINT16 logID UINT32 sequenceNumber BOOLEAN purgeAll Document Version 1 70 5 23 2012 137 Function Specifications select data log to be purged logID 10 set flag to purge only part of data log purgeAll FALSE purge the oldest 150 records sequenceNumber 150 if datalogPurge logID purgeAll sequenceNumber Successful at purging the first 150 records of Log Start writing records again To purge the entire data log set flag to TRUE purgeAll TRUE call function with same parameters if datalogPurge logID purgeAll sequenceNumber Successful at purging the entire data log Start writing records again Document Version 1 70 5 23 2012 138 Function Specifications datalogReadNext Read Data Log Next Function This function returns the next record in the data log Syntax include lt ctools h gt BOOLEAN datalogReadNext UINT16 logID UINT32 sequenceNumber UINT32 pSequenceNumber UINT32 pNextSequenceNumber UINT16 pData D
61. 1 Parameters service specifies the service for which the credentials are being set index specifies the index for the credentials Indices are service specific username specifies the username to grant access to password specifies the password that is valid with the username Description The setLoginCredentials function registers a username and password pair for the specified service Valid services are 0 FTP Maximum username and password length is 16 bytes Only index 0 is supported The valid values of index are service specific The username and password are both NULL terminated strings with a service defined maximum length True is returned if the credentials were set False is returned if the service rejected the credentials or if the service was unrecognized Notes Duplicate usernames are supported See Also getLoginCredentials clearLoginCredentials Document Version 1 70 5 23 2012 523 Function Specifications setPowerMode Set Current Power Mode Syntax include lt ctools h gt BOOLEAN setPowerMode UCHAR cpuPower UCHAR lan UCHAR usbHost Description The setPowerMode function returns TRUE if the new settings were successfully applied The setPowerMode function allows for power savings to be realised by controlling the power to the LAN port changing the clock speed and individually controlling the host and peripheral USB power The following table of macros summarizes the choices av
62. 200 30000 40 50 amp dLogConfig DLS CREATED UINT16 amp data one record was written in data log Document Version 1 70 5 23 2012 134 Function Specifications datalogDelete Delete Data Log Function Syntax include lt ctools h gt BOOLEAN datalogDelete UINT16 og D Description This function destroys the specified data log The memory used by the data log is returned to the freed section The function has one parameter log D specifies the data log to be deleted The valid range is 0 to 15 The function returns TRUE if the data log was deleted The function returns FALSE if the log ID is not valid or if the log had not been created Example See example DataLog program in the Example Programs section This program shows the only way to change the configuration of an existing log which is to delete the log and recreate the data log include lt ctools h gt int main void UINT16 logID DATALOG CONFIGURATION dLogConfig Select logID 10 logID 10 Read the configuration of logID 10 if datalogSettings logID amp dLogConfig if dLogConfig typesOfFields 0 DLV_INT16 Wrong type Delete log and create new one Xy if datalogDelete logID Re enter the log configuration dLogConfig records 200 dLogConfig fields 5 dLogConfig typesOfFields 0 DLV_UINT16 dLogConfig typesOfFields 1 DLV_IN
63. 3 events to hold before reporting enableUnsolicitedOnStartup controls whether unsolicited reporting is initially enabled or disabled in the controller sendUnsolicitedOnStartup controls whether a null unsolicited message is sent from the controller on startup level2Compliance controls which DNP point types are sent in a Class 0 Poll If level2Compliance is TRUE floating point types and 32 bit Analog Outputs are not sent because they are not level 2 compliant DNP types they are converted to 32 bit Analog Inputs and 16 bit Analog Outputs If level2Compliance is FALSE all points are reported as their true point type The dnpConfigurationEx type includes extra parameters in the DNP Configuration typedef struct dnpConfigurationEx type NT16 rtuAddress HAR datalinkConfirm HAR datalinkRetries NT16 datalinkTimeout NT16 operateTimeout HAR applicationConfirm NT16 maximumResponse HAR applicationRetries L Re E Eo Rag a E E QAHAHHAAH Document Version 1 70 5 23 2012 600 Structures and Types N N e HHAHHAHHAHHAHHAHAAHHAHHAHHAHHAHAHAHHAHEAHQAHAHAHAHHAHHAHAHAHGAHAHAHAHAHAHHAHHAHQAHAHHAHEAHQHHHAHHEAQHHZH T16 T16 T16 NT16 AR NT16 NT16 NT16 NT16 NT16 AR NT16 NT16 NT16 AR NT16 AR NT16 NT16 AR NT16 NT16 NT16 AR NT16 AR NT16 NT16 AR NT16 AR NT16 NT16 NT16 NT16 AR NT16 NT16 AR NT16 NT16 NT16
64. 367 Function Specifications Document Version 1 70 5 23 2012 368 Function Specifications ioSystemReset Add Reset Request to I O Controller Request Queue Syntax include lt ctools h gt BOOLEAN ioSystemReset void Description This function adds a reset request to the I O Controller request queue When the request is sent to the I O Controller all UO modules are reset The function has no arguments The function returns TRUE if the request was added The function returns FALSE if there is no room in the request queue Document Version 1 70 5 23 2012 369 Function Specifications ioVersion Get the I O Controller Firmware Version Syntax include lt ctools h gt BOOLI EAN ioVersion UINT16 amp pVersion Description This function returns the I O controller firmware version The version is read from the I O controller at initialization The f unction has one argument a reference to an UINT16 value to which the firmware version is copied if it is available The f unction returns TRUE if the firmware version is available It returns FALSE if the firmware version has not been read from the I O controller Document Version 1 70 5 23 2012 370 Function Specifications ioWrite4203DROutputs Write 4203 DR Outputs Syntax include lt ctools h gt BOOLEAN ioWrite4203DROutputs UCHAR amp doutData INT16 amp aoutData Description This funct
65. 5 23 2012 176 Function Specifications dnpGetBOConfig Get DNP Binary Output Configuration Syntax include lt ctools h gt BOOLEAN dnpGetBOConfig UINT16 point dnpBinaryOutput pBinaryOutput Description The dnpGetBOConfig function reads the configuration of a DNP binary output point The function has two parameters the point number and a pointer to a binary output point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveBOConfig Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 177 Function Specifications dnpGetCl1 6Config Get DNP 16 bit Counter Input Configuration Syntax include lt ctools h gt BOOLEAN dnpGetC1I16Config UINT16 point dnpCounterInput pCounterInput Description The dnpGetCl16Config function reads the configuration of a DNP 16 bit counter input point The function has two parameters the point number and a pointer to a counter input point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created
66. 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the specified unsigned long value is written to the variable If the variable is not found or if the IEC 61131 1 Symbols Status is invalid nothing is done and FALSE is returned The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the setdbase function The IO_SYSTEM system resource needs to be requested before calling this function Example This program writes the value 10000 ms to the timer variable named Delay include lt ctools h gt int main void BOOLEAN status request resource IO SYSTEM status writeTimerVariable Delay 10000 release resource IO SYSTEM Document Version 1 70 5 23 2012 569 Function Specifications xcopy Copy a folder and all sub folders Syntax include lt ctools h gt STATUS xcopy
67. AI32 POINT 32 bit analog input AISF POINT short float analog input AILF POINT long float analog input C116 POINT 16 bit counter output C132 POINT 32 bit counter output BO POINT binary output AO16 POINT 16 bit analog output AO32_ POINT 32 bit analog output AOSF POINT short float analog output AOLF_ POINT long float analog output ER Document Version 1 70 5 23 2012 607 Structures and Types dnpProtocolStatus The dnpPrototocolStatus structure contains status information for DNP message transactions struct dnpPrototocolStatus dnpRoutingTableEx INT16 successes INT16 failures INT16 failuresSinceLastSuccess INT16 formatErrors INT16 framesReceived ch I I NT16 framesSent NT16 messagesReceived NT16 messagesSent Le K C E K Le E C successes is the number of successful DNP message transactions failures is the total number of failed DNP message transactions failuresSinceLastSuccess is the number of failures since last the success formatErrors is the number of messages received with bad message data framesReceived is the number of DNP frames message packets received framesSent is the number of DNP frames message packets sent messagesReceived is the number of DNP messages received messagesSent is the number of DNP messages sent commandsStatus is the status of the last protocol command sent The dnpR
68. Also set_port Example include lt ctools h gt int main void struct pconfig settings get_port coml amp settings fprintf coml Baud rate Sd r n settings baud fprintf com1 Duplex d r n settings duplex Document Version 1 70 5 23 2012 259 Function Specifications getPowerMode Get Current Power Mode Syntax include lt ctools h gt BOOLEAN getPowerMode UCHAR cpuPower UCHAR lan UCHAR usbHost Description The getPowerMode function places the current state of the CPU LAN USB peripheral port and USB host port in the passed parameters The following table lists the possible return values and their meaning PM_CPU_FULL The CPU is set to run at full speed PM_CPU_REDUCED The CPU is set to run at a reduced speed PM _CPU_SLEEP The CPU is set to sleep mode The function always returns TRUE The application program may set the current power mode with the setPowerMode function See Also setPowerMode setWakeSource getWakeSource Document Version 1 70 5 23 2012 260 Function Specifications getProgramStatus Get Program Status Flag Syntax include lt ctools h gt UINT16 getProgramStatus FUNCPTR entryPoint Description The getProgramStatus function returns the application program status flag of the program specified by entryPoint The passed parameter should always be in the function main The status flag is set to NEW_PROGRAM when the C program downl
69. Arm7 tcl bin tclsh84 exe S CTOOLS PATH Arm7 host x86 win32 bin munch tcl c arm gt ctdt c ccarm CFLAGS c fdollars in identifiers ctdt c o ctdt o Link downloadable application ccarm I r nostdlib W1 X W1 EL T S CTOOLS PATH Arm7 target h tool gnu ldscripts link OUT imImage o ctdt o o APPLICATION NAME out Clean up temporary files del ctdt c ctdt o The next sections describe how to make the intermediate objects and check that symbols will be resolved when the application is loaded into the controller Generally no changes will ever be required in this section rules for making intermediate objects imImage o objects Merge all object files into one ccarm I r nostdlib W1 X W1 EL W1 S objects o imImage o link with controller specific CTools library to check for unresolved externals SSeS sss CS SSeS SSeS Se See A ee Se See ee ee ee Sse Ee See SSeS imLink SCADAPack350 0 imImage o echo lecho Sess SHS SSRs EE aS SSeS aS aa R EE echo Checking for unresolved externals with SCADAPack 350 CTools library Gecho Sass SasSse ase aa aa ae Se a Sa ee Se ldarm e0 imImage o S INCLUDE PATH SCADAPack 350 IEC 61131 1 Firmware Image o imLink SCADAPack350 0 imLink 4203 0 imImage o echo Eeer ss S2S Re SSeS aS ae EE Sse sess SSeS EE echo Checking for unresolved externals with 4203 library lecho ae a aaa EE la ldarm e0 imImage o S INCLUDE PATH SC
70. Assignment Enumeration Types The ctools h file defines one enumeration type The ioModules enumeration type defines a list of results of sending a command Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Document Version 1 70 5 23 2012 84 Overview of Programming Functions Register Assignment Structure The ctools h file defines the structure RegAssign Refer to the C Tools Structures and Types section for complete information on structures and enumeration types IEC 61131 1 Variable Access Functions Variables declared in an IEC 61131 1 application are accessed from a C application using the IEC 61131 1 variable access functions listed below Refer to the Function Specification section for details on each function listed readBoolVariable Returns the current value of the specified boolean variable readIntVariable Returns the current value of the specified integer variable readRealVariable Returns the current value of the specified real variable readMsgVariable Returns the current value of the specified message variable readTimerVariable Returns the current value of the specified timer variable writeBoolVariable Writes to the specified boolean variable writelntVariable Writes to the specified integer variable writeRealVariable Writes to the specified real variable writeMsgVariable Writes to the specified message variable writeTimerVariable Writes to t
71. Description The portStream function returns the file pointer corresponding to index This function is the inverse of the portIndex function If the index is not valid the NULL pointer is returned See Also portIndex Document Version 1 70 5 23 2012 459 Function Specifications queryStack Query Stack Space for Known Tasks Syntax include lt ctools h gt void queryStack UCHAR filename Description The queryStack function generates a csv file with the supplied filename The csv file contains the current stack condition of all known tasks The file that is created can be extracted through FTP or Telepace Studio s File Management tool Notes This function should be used infrequently as a debugging aid Itis also recommended to be used during C application development to confirm that the tasks created by the C application have sufficient stack space Exercising all code paths is recommended before calling this function to obtain the most useful results Example include lt ctools h gt queryStack d0 myStack csv Document Version 1 70 5 23 2012 460 Function Specifications queue_mode Control Serial Data Transmission Syntax include lt ctools h gt void queue mode FILE stream INT16 mode Description The queue_mode function controls transmission of the serial data Normally data output to a serial port are placed in the transmit buffer and transmitted as soon as the
72. Function Specifications 5505 I O Module parameters 0 to 3 define the analog input type for the corresponding input Valid values are e 0 RTD in deg Celsius e 1 RTDin deg Fahrenheit e 2 RTD in deg Kelvin e 3 resistance measurement in ohms 5505 I O Module parameters 4 defines the analog input filter Valid values are e 0 0 5s e 1 15 e 2 2s e 3 4s 5506 I O Module parameters 0 to 7 define the analog input type for the corresponding input Valid values are e 0O Oto 5 V input e 1 1to5Vinput e 2 0to 20 mA input e 3 4to 20 mA input 5506 I O Module parameters 8 defines the analog input filter Valid values are e 0Q lt 3Hz maximum filter e 1 6Hz e 2 11 Hz e 3 30 Hz minimum filter 5506 I O Module parameters 9 defines the scan frequency Valid values are e 0 60Hz e 1 50 Hz 5606 I O Module parameters 0 to 7 define the analog input type for the corresponding input Valid values are e 0O Oto 5 V input e 1 1to5Vinput e 2 0to 20 mA input e 3 4to 20 mA input 5606 I O Module parameters 8 defines the analog input filter Valid values are e 0Q lt 3Hz maximum filter Document Version 1 70 5 23 2012 99 Function Specifications e 1 6Hz e 2 11 Hz e 3 30 Hz minimum filter 5606 I O Module parameters 9 defines the scan frequency Valid values are e 0 60Hz e 1 50Hz 5606 I O Module parameters 10 defines the analog output type Valid values are e 0 0 to 20
73. List size ipAddressStart and ipAddressEnd specify a range of IP addresses or a single IP address if they are the same to be added to the list Valid values are any IP address the start IP address needs to be lower than or equal to the end IP address The function returns TRUE if successful and FALSE if the index or address is invalid Notes IpWriteFriendlyIPListSize needs to be called before calling this function See Also ipReadFriendlyIPListEntry Document Version 1 70 5 23 2012 405 Function Specifications ipWriteFriendlyIPListSize Write the size of the Friendly IP List Syntax BOOLEAN ipWriteFriendlyIPListSize UINT16 size Description This function sets the size of the Friendly IP List This needs to be written before any entries are written to the list size specifies the number of active entries in the list Valid values are 0 to 32 The function returns TRUE if successful FALSE otherwise See Also ipReadFriendly PListSize Document Version 1 70 5 23 2012 406 Function Specifications ledGetDefault Read LED Power Control Parameters Syntax include lt ctools h gt struct ledControl tag ledGetDefault void Description The ledGetDefault routine returns the default LED power control parameters The controller controls LED power to 5000 I O modules To conserve power the LEDs can be disabled The user can change the LED power setting with the LED POWER switch on the contr
74. MIP DISCONNECT break break case MIP DISCONNECT if mTcpMasterDisconnect connectID disconnect is successfully started mode MIP CLOSE break case MIP CLOSE if mTcpMasterClose connectID connection has been successfully released open new connection and start again mode MIP OPEN CONNECTION break release processor to other priority 254 tasks release processor Modem Initialization Example The following code shows how to initialize a modem Typically the modem initialization is used to prepare a modem to answer calls The example sets up a Hayes modem to answer incoming calls include lt ctools h gt include lt string h gt int main void struct ModemInit initSettings reserve id portID enum DialError status enum DialState state struct pconfig portSettings Configure serial port 1 Document Version 1 70 5 23 2012 669 Example Programs portSettings baud BAUD1200 portSettings duplex FULL portSettings parity NONE portSettings data_ bits DATA8 portSettings stop bits STOP1 portSettings flow rx RFC MODBUS_RTU portSettings flow tx TFC_NONE portSettings type RS232 MODEM portSettings timeout 600 request _ resource IO SYSTEM set _port coml amp portSettings release resource IO SYSTEM Initialize Hayes modem to answer incoming calls initSett
75. MSG_PEEK Returns gt 0 0 1 recv will fail if EBADF ENOBUFS EMSGSIZE EWOULDBLOCK ESHUTDOWN EINVAL ENOTCONN Don t wait for data but rather return immediately Read any out of band data present on the socket rather than the regular in band data Peek at the data present on the socket the data is returned but not consumed so that a subsequent receive operation will see the same data Number of bytes actually received from the socket EOF An error occurred The socket descriptor is invalid There was insufficient user memory available to complete the operation The socket requires that message be received atomically and bufferLength was too small The socket is marked as non blocking or the MSG_DONTWAIT flag is used and no data is available to be read or the MSG_OOB flag is set and the out of band data has not arrived yet from the peer The remote socket has closed the connection and there is no more data to be received TCP socket only One of the parameters is invalid or the MSG_OOB flag is set and either the SO_OOBINLINE option is set or there is no out of band data to read or coming from the peer Socket is not connected Document Version 1 70 5 23 2012 478 Function Specifications recvfrom Syntax include lt ctools h gt int recvfrom int socketDescriptor char bufferPtr int bufferLength int flags struct sockaddr fromPtr int fromLe
76. NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 NT16 applicationTimeout timeSynchronization BI_number BI_startAddress BI_reportingMethod BI_soeBufferSize BO number BO_startAddress CI16_ number CI16 startAddress CI16 reportingMethod CI16 bufferSize C132 number C132 startAddress C132 reportingMethod C132 bufferSize C132 wordOrder AI16_ number AI16 startAddress AI16_ reportingMethod AI16_ bufferSize AI32_ number AI32_ startAddress AI32_reportingMethod AI32_ bufferSize AI32_ wordOrder AISF_ number AISF_startAddress AISF_reportingMethod AISF bufferSize AISF_wordOrder AO16 number AO16 startAddress AO32_ number AO32_ startAddress AO32_wordOrder AOSF_ number AOSF_startAddress AOSF_wordOrder autoUnsolicitedClass1 holdTimeClass1 holdCountClass1 autoUnsolicitedClass2 holdTimeClass2 holdCountClass2 autoUnsolicitedClass3 holdTimeClass3 holdCountClass3 enableUnsolicitedOnStartup sendUnsolicitedOnStartup level2Compliance masterAddressCount masterAddress 8 maxEventsInResponse dialAttempts dialTimeout Document Version 1 70 5 23 2012 601 Structures and Types UINT16 pauseTime UINT16 onlineInactivity UINT16 dialType Char modemInitString 64 dnpConfigurationEx e rtuAddress is the address of the RTU The master station must send messages to this address Valid values are 0 to 65534 e datalink
77. Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveCl16Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 178 Function Specifications dnpGetCli32Config Get DNP 32 bit Counter Input Configuration Syntax include lt ctools h gt BOOLEAN dnpGetCI32Config UINT32 point dnpCountertInput pCounterInput Description The dnpGetCl32Config function reads the configuration of a DNP 32 bit counter input point The function has two parameters the point number and a pointer to a counter input point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveCl32Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 179 Function Specifications dnpGetConfiguration Get DNP Configuration Syntax include lt ctools h gt BOOLEAN dnpGetConfiguration dnpConfiguration pConfiguration Description The dnpGetConfiguration function reads the DNP configuration The function has one parameter a pointer to a DNP configuration structure The function returns TRUE i
78. O module Buffered data are updated when an I O request for the module is processed moduleAddress is the address of the 5505 module Valid values are 0 to 15 dinData is a reference to a UINT16 variable Digital data for the 16 internal inputs are written to this variable One bit in the variable represents each input point The function of the 16 digital inputs is described in the table below Point Offset OFF channel 0 RTD is good P ON chame O RTD sapen or PWR mpwtisot 1 OFF channel 0 data in range Iessen O 2 OFF channel 0 RTD is e 3 wire measurement NEE EE OFF channel 1 RTD is good ON channel 1 RTD is open or PWR input is off 5 OFF channel 1 data in range J OFF channel 1 RTD i is using 3 wire measurement Jaeger 7 reserved for future use e for future use OFF channel 2 RTD is good B o OFF channel 2 data in range TT J 10 OFF channel 2 RTD is using 3 wire measurement J Document Version 1 70 5 23 2012 329 Function Specifications Point Offset 11 reserved for future use 2 for future use K OFF channel 3 RTD is evei e op ON channel 3 RTD is open or PWR input is off OFF channel 3 data in range TS L ns 14 OFF channel 3 RTD is using 3 wire measurement TT Iesse Reserved for future use ainData is a reference to an array of four floating point variables Analog data are written to this array The function returns FALSE if the module address is inval
79. PROTOCOL TYPE protocolType CONNECTION TYPE appType UINT16 timeout UINT32 connectID MODBUS CMD STATUS cmdStatus Description The mTcpMasterOpen function allocates the resources needed to make a Modbus IP master connection to a remote IP address These resources consist of a connection ID from the connection pool and the creation of a task to service the master IP connection When the task is created an initial connection to remotelP is attempted However the connection ID and master task are not restricted to just one remote P The currently connected IP address may be disconnected and connected to a different IP address any time mTcpMasterMessage is called with a different remotelP for this connection ID See mTcpMasterMessage for more details Valid values for protocolType are IPP_ModbusTcp IPP_ModbusRtuOverUdp or IPP_ModbusAsciiOverUdp There is only one valid value for aopType CT_MasterCApp For TCP protocols the timeout specifies the time in tenths of seconds to wait for a connection to be established whenever a connection is attempted by the created master task To disable the timeout and wait forever for a connection to be established set the timeout to 0 Each time this function is called a new connection ID is allocated from the connection pool If the number of currently allocated connections is less than 20 a task is created to service the allocated connection and the function returns TRUE If
80. RTOS then determines if the new task is higher priority than the executing task Since the echoData task is higher priority than the auxiliary task a task switch occurs The auxiliary task is placed on the Ready queue The echoData task executes Observe the position of auxiliary in the Ready queue The main task will execute before it at the next task switch Document Version 1 70 5 23 2012 58 Real Time Operating System Ready Queue Running Task echoData auxiliary Figure 8 Queue Status after Character Received Execution Point 9 This point occurs just after the echoData task waits for the character received event It is placed on the event 10 queue The highest priority task on the ready queue main is given the processor and executes Ready Queue Event 10 Queue Running Task main echoData 100 auxiliary 255 null Figure 9 Queue Status after echoData Waits for Event Document Version 1 70 5 23 2012 59 Overview of Programming Functions Overview of Programming Functions This section of the User Manual provides an overview of the Functions Macros Structure and Types available to the user The Functions Macros Structure and Types overview is separated into sections of related functions Refer to the Function Specification C Tools Macros and C Tools Structures and Types sections of this manual for
81. See manual for details UINT32 mainPriority 100 Stack space allocated to the task main Note that at least 10 stack blocks are needed when calling fprants ER UINT32 mainStack 10 Application group assigned to the task main A unique value is assigned by the system to the applicationGroup for this application Use this variable in calls to create _task by this application See manual for details UINT32 applicationGroup 0 For this tutorial the C code to print hello world to serial port 2 will be added to the main task The hello world message will be output to the com2 serial port of the controller A terminal connected to the port will display the message The fprintf function prints the message to the com2 serial port Document Version 1 70 5 23 2012 22 Getting Started Edit the main cpp text and add the text shown in bold in the following section int main void add program initialization here Print the message fprintf com2 hello world r n main loop while TRUE add remainder of program here Compiling the C Application Review makefile Once the editing of the project is completed the application needs to be compiled and linked This produces an executable file that can be loaded into the SCADAPack 350 or 4203 controller The C tools use the gnu make utility to build applications Application builds are managed by
82. See the Example in the Example Programs chapter under the section Master Message Example Using DF1 Protocol The resetAll ABSlaves function should not normally be needed if polling is done using the sample polling function poll_for_response shown in this example See Also pollABSlave Example This program segment will cause all slaves communicating on the com2 serial port to erase all pending responses include lt ctools h gt resetAllABSlaves com2 Document Version 1 70 5 23 2012 488 Function Specifications resetClockAlarm Acknowledge and Reset Real Time Clock Alarm Syntax include lt ctools h gt void resetClockAlarm void Description Real time clock alarms occur once after being set The alarm setting remains in the real time clock The alarm needs to be acknowledged before it can occur again The resetClockAlarm function acknowledges the last real time clock alarm and re enables the alarm Notes This function should be called after a real time clock alarm occurs The IO_SYSTEM resource needs to be requested before calling this function Example See the Example for the installClockHandler function Document Version 1 70 5 23 2012 489 Function Specifications route Redirect Standard LO Streams Syntax include lt ctools h gt void route UCHAR logical UCHAR hardware Description The route function redirects the I O streams associated with stdout stdin and stder
83. Send Command using HART Interface Module Syntax include lt ctools h gt BOOLEAN hartCommand UINT16 module HART DEVICE const device HART COMMAND const command void processResponse UINT16 HART RESPONSE 1 Description This function sends a command to a HART slave device using a HART interface module This function can be used to implement HART commands not provided by the Network Layer API The function has four parameters The first is the module number of the 5904 interface 0 to 3 The second is the device to which the command is to be sent The third parameter is a structure describing the command to send This contains the command number and the data field of the HART message See the HART protocol documentation for your device for details The fourth parameter is a pointer to a function that will process the response This function is called when a response to the command is received by the HART interface The function is defined as follows void function name HART RESPONSE response The single parameter is a structure containing the response code and the data field from the message The function returns TRUE if the 5904 interface responded and FALSE if it did not or if the module number is not valid or there is an error in the command Notes The function returns immediately after the command is sent The calling program needs to wait for the response to be receiv
84. The dnpBinaryOutput type describes a DNP binary output point typedef struct dnpBinaryOutput_type UINT16 modbusAddress1 UINT16 modbusAddress2 UCHAR controlType dnpBinaryOutput modbusAddress1 is the address of the first Modbus register associated with the point This field is always used modbusAddressz2 is the address of the second Modbus register associated with the point This field is used only with paired outputs See the controlType field controlType determines if one or two outputs are associated with this output point It may be set to PAIRED or NOT_PAIRED A paired output uses two Modbus registers for output The first output is the Trip output and the second is the Close output This is used with Control Relay Output Block objects A non paired output uses one Modbus register for output This is used with Binary Output objects dnpConnectionEventType This enumerated type lists DNP events typedef enum dnpConnectionEventType DNP_CONNECTED 0 F DND DISCONNECTED DND CONNECTION REQUIRED DNP MESSAGE COMPLETE DNP MESSAGE TIMEOUT DND CONNECTION EVENT The DNP_CONNECTED event indicates that the handler has connected to the master station The application sends this event to DNP When DNP receives this event it will send unsolicited messages Document Version 1 70 5 23 2012 595 Structures and Types
85. The function has no effect if the serial port is not an RS232 port Document Version 1 70 5 23 2012 515 Function Specifications setFtpServerState Sets the state of the FTP server Syntax include lt ctools h gt BOOLEAN setFtpServerState UINT32 state 1 Parameters state specifies the desired operational state of the FTP server The following values for state are defined e 0 FTP server disabled e 1 FTP server enabled anonymous login permitted e 2 FTP server enabled username and password required Description The setFtpServerState function sets the state of the FTP server TRUE is returned if the specified state was set FALSE is returned if the specified state could not be set Notes This function is only relevant for Ethernet enabled controllers See Also getFtpServerState Document Version 1 70 5 23 2012 516 Function Specifications setForceFlag Set Force Flag State for a Register Telepace firmware only Syntax include lt ctools h gt BOOLEAN setForceFlag UINT16 type UINT16 address UINT16 value Description The setForceFlag function sets the force flag s for the specified database register s to value value is either 1 or 0 or a 16 bit mask for LINEAR digital addresses The valid range for address is determined by the database addressing type If the address or addressing type is not valid force flags are left unchanged and FALSE is returned otherwi
86. a communications domain in which communication will take place this selects the protocol family that should be used The protocol family is generally the same as the address family for the addresses supplied in later operations on the socket These families are defined in the include file lt ctools h gt H protocol has been specified but no exact match for the tuplet family type and protocol is found then the first entry containing the specified family and type with zero for protocol will be used The currently understood format is PF_INET for ARPA Internet protocols The socket has the indicated type which specifies the communication semantics Currently defined types are SOCK_STREAM SOCK_DGRAM SOCK_RAW A SOCK_STREAM type provides sequenced reliable two way connection based byte streams An out of band data transmission mechanism is supported A SOCK_DGRAM socket supports datagrams connectionless unreliable messages of a fixed typically small maximum length a SOCK_DGRAM user is required to read an entire packet with each recv call or variation of recv call otherwise an error code of EMSGSIZE is returned protocol specifies a particular protocol to be used with the socket Normally only a single protocol exists to support a particular socket type within a given protocol family However multiple protocols may exist in which case a particular protocol needs to be specified in this manner The protocol number to use is particul
87. a description of the fields in the SFTranslationStatus structure The code field of the structure is set to one of the following If there is an error the index field is set to the location of the translation that is not valid SF_VALID All translations are valid SF_NO_TRANSLATION The entry defines re transmission of the same message on the same port SF_PORT_OUT_OF_RANG One or both of the interfaces is not valid E SF_STATION OUT OE RH One or both of the stations is not valid ANGE SF_ALREADY_DEFINED The translation already exists in the table SF_INVALID_FORWARDIN The forwarding IP address is invalid G_IP Notes The TeleBUS Protocols User Manual describes store and forward messaging mode See Also clearSFTranslationTable Example See the example for the setSFTranslationEx function Document Version 1 70 5 23 2012 109 Function Specifications clearAllForcing Clear All Forcing Telepace firmware only Syntax include lt ctools h gt void clearAllForcing void Description The clearAllForcing function removes all forcing conditions from all I O database registers The O_SYSTEM resource must be requested before calling this function See Also setForceFlag getForceFlag overrideDbase Document Version 1 70 5 23 2012 110 Function Specifications clearBreakCondition Clear a break condition on a serial port Syntax include lt ctools h gt void clearBreakCondition F
88. a make file For the simplest applications no modifications of the makefile are needed This section may be skimmed the first time through but contains information that will be usefull for building more sophisticated applications The makefile is designed to build a application for both the SCADAPack 350 and 4203 controllers Command line options allow the application to be targeted for a specific controller if the application code contains functions that are specific to the controller Open the file makefile in the application folder The file shown below is from the IEC 61131 1 application framework makefile Make file for SCADAPack 350 4203 C Tools application for IEC 61131 1 firmware Copyright 2007 Control Microsystems Inc usage make makes application for all controllers make TARGET SCADAPack350 makes application for SCADAPack 350 controller make TARGET 4203 makes application for 4203 controller make clean deletes all output files Document Version 1 70 5 23 2012 23 Getting Started The first section of the file sets the name of the output file The default name is myApp You should modify this for you application ee ew See ear set the name of the output file here Le E ay e EE A E E EE EE E EE EE EE ee Ee De dEr E SE Ee Se APPLICATION NAME myApp The next section lists all the object files in the application There is one object file corresponding to each C or
89. accept Parameters socketDescriptor The socket descriptor that was created with socket and bound to with bind and is listening for connections with listen addressPtr The structure to write the incoming address into addressLengthPtr Initially it contains the amount of space pointed to by addressPtr On return it contains the length in bytes of the address returned Returns New Socket Descriptor or 1 on error If accept fails the errorCode can be retrieved with getErrorCode socketDescriptor which will return one of the following error codes EBADF The socket descriptor is invalid EINVALaddressPtr was a null pointer Document Version 1 70 5 23 2012 90 Function Specifications EINVAL addressLengthPtr was a null pointer EINVAL The value of addressLengthPtr was too small ENOBUFS There was insufficient user memory available to complete the operation EPERM Cannot call accept without calling listen first EOPNOTSUPP The referenced socket is not of type SOCK_STREAM EPROTO A protocol error has occurred for example the connection has already been released EWOULDBLOCK The socket is marked as non blocking and no connections are present to be accepted Document Version 1 70 5 23 2012 91 Function Specifications addRegAssignment Add Register Assignment Telepace firmware only Syntax include lt ctools h gt BOOLEAN addRegAssignment UINT16 moduleType INT16 moduleAddress UINT16 startingR
90. address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 347 Function Specifications ioReadAout2 Read Data From 2 point Analog Output Module Syntax include lt ctools h gt BOOLEAN ioReadAout2 UINT16 moduleAddress INT16 amp data 2 Description This function reads buffered data used for the 2 point analog output module at the specified module address Buffered data are written using the ioWriteAout2 function The function has two parameters the module address and a reference to an array of two INT16 variables If the moduleAddress is valid data are copied to the array The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 348 Function Specifications ioReadAout4 Read Data From 4 point Analog Output Module Syntax include lt ctools h gt BOOLEAN ioReadAout4 UINT16 moduleAddress INT16 amp data 4 Description This function reads buffered data used for the 4 point analog output module at the specified module address Buffered data are written using the ioWriteAout4 function The function has two parameters the module address and a reference to an array of four INT16 variables If the moduleAddress is valid data are copied to the array The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is inval
91. address is not available on the remote local machine Addresses in the specified address family cannot be used with this socket The socket is non blocking and the current connection attempt has not yet been completed The socket is non blocking and a previous connection attempt has not yet been completed socketDescriptor is not a valid descriptor The attempt to connect was forcefully rejected The calling program should close the socket descriptor and issue another socket call to obtain a new descriptor before attempting another connect call Cannot call connect after listen call One of the parameters is invalid The socket is already connected The calling program should close the socket descriptor and issue another socket call to obtain a new descriptor before attempting another connect call No route to the host we want to connect to The socket referred to by addressPir is a socket of a type other than type socketDescriptor for example socketDescriptor is a SOCK_DGRAM socket while addressPtr refers to a SOCK_STREAM socket Connection establishment timed out without establishing a connection The calling program should close the socket descriptor and issue another socket call to obtain a new descriptor before attempting another connect call Document Version 1 70 5 23 2012 126 Function Specifications copy Copy a File Syntax include lt ctools h gt STATUS copy const char source con
92. address parameter indicates that we want to reset a previously set outgoing interface for multicast packets sent on that socket IP_MULTICAST_TTL Get the default IP TTL for outgoing multicast datagrams IP_TOS IP type of service Default 0 IP_TTL IP Time To Live in seconds Default 64 The following options are recognized at the TCP level IP_PROTOTCP protocolLevel options Document Version 1 70 5 23 2012 272 Function Specifications TCP_MAXSEG TCP_NODELAY Parameters socketDescriptor protocolLevel optionName optionValuePtr optionLengthPtr SOL_SOCKET IP_PROTOIP IP_PROTOTCP Protocol Level SOL_SOCKET IP_PROTOIP Get the maximum TCP segment size sent on the network The TCP_MAXSEG value is the maximum amount of data including TCP options but not the TCP header that can be sent per segment to the peer i e the amount of user data sent per segment is the value given by the TCP_MAXSEG option minus any enabled TCP option for example 12 bytes for a TCP time stamp option Default is IP MTU minus 40 bytes If this option value is non zero the Nagle algorithm that buffers the sent data inside the TCP is disabled Useful to allow client s TCP to send small packets as soon as possible like mouse clicks Default 0 The socket descriptor to get the option from The protocol to get the option from See below The option to get See above and below The pointer to a user variable into which the opti
93. amount of non volatile memory allocated by the specified task group or 0 if the specified group was invalid See Also allocateMemory freeMemory memoryPoolSize Document Version 1 70 5 23 2012 414 Function Specifications memoryPoolSize Return the size of non volatile memory pool in bytes Syntax UINT32 memoryPoolSize void Description The function takes no input parameters and returns the size of the non volatile memory pool in bytes See Also allocateMemory freeMemory memoryPoolUsage Document Version 1 70 5 23 2012 415 Function Specifications modbusExceptionStatus Set Response to Protocol Command Syntax include lt ctools h gt void modbusExceptionStatus UCHAR status Description The modbusExceptionStatus function is used in conjunction with the Modbus compatible communication protocol It sets the result returned in response to the Read Exception Status command This command is provided for compatibility with some Modbus protocol drivers for host computers The value of status is determined by the requirements of the host computer Notes The specified result will be sent each time that the protocol command is received until a new result is specified The result is cleared when the controller is reset The application program needs to initialize the status each time it is run See Also master_message Document Version 1 70 5 23 2012 416 Function Specific
94. amp Forward table with controller settings request _ resource FLASH MEMORY flashSettingsSave CS_ RUN release resource FLASH MEMORY Translations may involve any combination of interfaces The interfaces may be running a Serial Modbus or Modbus IP protocol Serial Modbus Interface Serial Modbus Interface Modbus IP Interface Serial Modbus Interface Serial Modbus Interface Modbus IP Network e g com1 com2 or com3 e g Modbus TCP Modbus RTU over UDP or Modbus ASCII over UDP Modbus IP Interface Modbus IP Network e g Ethernet e g Modbus TCP Modbus RTU over UDP or Modbus ASCII over UDP Modbus IP Network as Forwarding Interface When forwarding to a TCP or UDP network the protocol type is selected for the forwardinterface in the SF_TRANSLATION_EX structure The IP Stack automatically determines the exact interface e g Ethernet1 to use when it searches the network for the forwardlPAddress Also when forwarding on a TCP or UDP network the forwarding destination IP address needs to be entered as the forward PAddress The forward PAddress is entered as an IP address string of the format 255 255 255 255 The forwardlPAddress is needed to know where to connect so that the command can be forwarded to its final destination Document Version 1 70 5 23 2012 535 Function Specifications Modbus IP Network as Slave Interface There is no field for a slave IP address This information
95. and DNP over UDP The information is copied to the structure pointed to be pSummary The structure IP_CONNECTION_SUMMARY is described in the Structures and Types section The information in the structure summarizes the number of connections as master slave or unused Note that if a connection is allocated to master messaging but is currently disconnected it will still be listed in the number of master connections Also additional connections for store and forward translations will be included in the summary For Example a master connection will be listed if a serial to Ethernet store and forward translation is currently active Document Version 1 70 5 23 2012 399 Function Specifications ipGetinterfaceType Get Interface Type from IP Address Syntax include lt ctools h gt BOOLEAN ipGetInterfaceType IP ADDRESS locallIP COM INTERFACE pifType Description The function ipGetInterfaceType determines the interface that is configured to the specified local IP address ocal P If no interface is configured to the specified IP address FALSE is returned otherwise TRUE is returned and the interface type if copied to the value pointed to by ifType iplnitializeFriendlylPSettings Reset the friendly IP list Syntax void iplnitializeFriendlylPSettings void Description This function deletes all Friendly IP List entries and disables the Friendly IP List The function has no parameters The
96. and a pointer to a configuration structure The function returns TRUE if the configuration was successfully read or FALSE otherwise if the point number is not valid or pointer is NULL or if the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 171 Function Specifications dnpGetAO16Config Get DNP 16 bit Analog Output Configuration Syntax include lt ctools h gt BOOLEAN dnpGetAO16Config UINT16 point dnpAnalogOutput pAnalogOutput Description The dnpGetAO16Config function reads the configuration of a DNP 16 bit analog output point The function has two parameters the point number and a pointer to an analog output point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveAO16Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 172 Function Specifications dnpGetAO32Config Get DNP 32 bit Analog Output Configuration Syntax include lt ctools h gt BOOLEAN dnpGetAO32Config UINT32 point dnpAnalogOutput pAnalogOutput Descri
97. and the dbase function Document Version 1 70 5 23 2012 468 Function Specifications The IO_SYSTEM system resource needs to be requested before calling this function See Also readintVariable readRealVariable Example This program displays the contents of the message variable named msgData of maximum length 20 include lt ctools h gt int main void BOOLEAN status UCHAR msg 23 request resource IO SYSTEM status readMsgVariable msgData msg release resource IO SYSTEM fprintf coml status Su max length d current length message s r n status msg 0 msg 1 msg 2 Document Version 1 70 5 23 2012 469 Function Specifications readRealVariable Read IEC 61131 1 Real Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN readRealVariable UCHAR varName float value Description This function returns the current value of the specified real i e floating point variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the variable value is written to the floating point value pointed to by value If the variable is not found or if the IEC 61131 1 Symbols Status is invalid FALSE is returned and the current value is left unchanged The IEC 611
98. any changes and will return FALSE if this is attempted The protocol needs to be disabled in order to make a change involving these parameters e DI number e BI_cosBufferSize e DI _soeBufferSize e BO number e Cl16_number e Cl16_bufferSize e C132_number e Cl82_bufferSize e Al16 number e Al16_reportingMethod e Al16_bufferSize e Al32_number e AI32_reportingMethod e Al82_bufferSize Document Version 1 70 5 23 2012 215 Function Specifications e AQO16_number e AQO832_number The following parameters can be changed when DNP is enabled e masterAddress e rtuAddress e datalinkConfirm e datalinkRetries e datalinkTimeout e operateTimeout e applicationConfirm e maximumResponse e applicationRetries e applicationTimeout e timeSynchronization e unsolicited e holdTime e holdCount See Also dnpGetConfiguration Example See example in the dnoGetConfiguration function section Document Version 1 70 5 23 2012 216 Function Specifications dnpSaveConfigurationEx Write DNP Extended Configuration Syntax BOOLEAN dnpSaveConfigurationEx dnpConfigurationEx pDnpConfigurationEx 1 Description This function writes the extended DNP configuration parameters The function has one parameter a pointer to the DNP extended configuration structure The function returns TRUE if the configuration was successfully written or FALSE otherwise if the pointer is NULL or if th
99. are not supported by the SCADAPack C Tools Refer to these sections when porting existing SCADAPack C Tools Applications Document Version 1 70 5 23 2012 691 Porting Existing C Tools Applications Application Checksum Function A checksum is no longer used for the C application The C Tools function applicationChecksum is not supported Backwards Compatibility Functions These functions were supported in previous C Tools for backwards compatibility however they were stubs The following C Tools functions are not supported Function setSFMapping getSFMapping Boot Type Functions These functions are not useful to C Applications The following C Tools functions are not supported Function setBootType getBootType UO Bus Communication Functions The SCADAPack 350 and 4203 I O System does not support these C Tools functions These functions provide user access to third party UC compatible devices Without these functions access is limited to Control Microsystems I O modules only Function ioBusStart ioBusStop ioBusReadByte ioBusReadLastByte ioBusWriteByte ioBusSelectForRead ioBusSelectForWrite ioBusReadMessage ioBusWriteMessage Timers The following C Tools Timer functions are not supported Use the functions readStopwatch or startTimedEvent instead Function interval read_timer_info Document Version 1 70 5 23 2012 692 Porting Existing C Tools Applications
100. are waiting for resources The envelope queue holds tasks that are waiting for envelopes Priority Inversion Prevention When a higher priority task Task H requests a resource which is already obtained by a lower priority task Task L the higher priority task is blocked until Task L releases the resource If Task L is unable to execute to the point where its releases the resource Task H will remain blocked This is called a Priority Inversion To keep this from occurring the prevention method known as Priority Inheritance has been implemented In the example already described the lower priority task Task L is promoted to the priority of Task H until it releases the needed resource At this point Task L is returned to its original priority Task H will obtain the resource now that it is available Document Version 1 70 5 23 2012 46 Real Time Operating System This does not stop deadlocks that occur when each task requests a resource that the other has already obtained This deadly embrace is a design error in the application program Operating System Scheduling The operating system supports a round robin scheduling algorithm combined with pre emptive priority scheduling It shares the CPU fairly among ready tasks of the same priority Round robin scheduling uses time slicing to achieve fair allocation of the CPU to tasks with the same priority Each task in a group of tasks with the same priority executes for a de
101. at a reduced speed PM_CPU_SLEEP The CPU is set to sleep mode PM_LAN ENABLED The LAN is enabled PM_LAN_DISABLED The LAN is disabled PM_USB_PERIPHERAL_ENA The USB peripheral port is enabled BLED PM_USB_PERIPHERAL_DISA The USB peripheral port is disabled BLED PM _USB_HOST_ENABLED The USB host port is enabled PM _USB_HOST_DISABLED The USB host port is disabled PM_UNAVAILABLE The status of the device could not be read DM NO CHANGE The current value will be used PROGRAM_EXECUTED Application program has been executed PROGRAM_NOT_LOADED The requested application program is not loaded REPORT_SLAVE_ID RFC_MODBUS_RTU Flow control type may be used in place of ENABLE RFC_NONE Flow control type may be used in place of DISABLE RS232 Specifies serial port is an RS 232 port RS232_MODEM Specifies serial port is an RS 232 dial up Document Version 1 70 5 23 2012 580 Macro Definitions SR EEESE RS485_2WIRE Specifies serial port is a 2 wire RS 485 port CE for collision avoidance SG MODULE_FAILURE Status LED code for I O module communication failure SG NORMAL Status LED code for normal status SERIAL_PORTS Number of serial ports SERVICE Run Service switch is in SERVICE position SF_ALREADY_DEFINED Result code translation is already defined in the table SF_PORT_OUT_OF_RANGE _ Result code serial port is not valid SF_NO_TRANSLATION Result code entry does not define a translation SF_INDEX OUT OE RA
102. band data In your application you can send out of band data by calling the send function with the MSG_OOB flag All the bytes of data sent that way using send with the MSG_OOB flag are out of band data bytes If you call send several times with out of band data TCP will always keep track of where the last out of band byte of data is in the byte data stream and flag this byte as the last byte of urgent data To receive out of band data please see the recv section of this manual Parameters socketDescriptor The socket descriptor to use to send data bufferPtr The buffer to send bufferLength The length of the buffer to send flags See below The flags parameter is formed by ORing one or more of the following MSG_DONTWAIT Don t wait for data send to complete but rather return immediately MSG_OOB Send out of band data on sockets that support this notion The underlying protocol needs to also support out of band data Only SOCK_STREAM sockets created in the AF_INET address family support out of band data MSG_DONTROUTE The SO_DONTROUTE option is turned on for the duration of the operation Only diagnostic or routing programs use it Returns gt 0 Number of bytes actually sent on the socket 1 An error occurred send will fail if EBADF The socket descriptor is invalid ENOBUFS There was insufficient user memory available to complete the operation EHOSTUNREACH Non TCP socket only No route to destination ho
103. be prepended to the command and a carriage returned appended to the command when it is sent to the modem MTCP_CONFIGURATION The Modbus TCP Settings structure defines settings for the Modbus TCP communication protocol typedef struct st _ModbusTcpSettings UINT16 portNumber UINT32 masterIdleTimeout UINT32 slaveRecvTimeout UINT32 maxServerConnections MTCP_CONFIGURATION e portNumber is the Modbus TCP protocol port number Valid port numbers are 0 to 65535 Selecting port number 65535 allows a server to listen for incoming connection requests on all the ports Default port number is 502 e masterldleTimeout is the length of time in seconds that a master connection will wait for the user to send the next command before ending the connection Set to 0 to disable timeout and let application close the connection Valid values are any 32 bit integer Default value is 10 seconds e slaveRecvTimeout is the length of time in seconds that a server connection will wait for a message before ending the connection Set to 0 to disable timeout and let remote client close connection Valid values are any 32 bit integer Default value is 10 seconds maxServerConnections is the maximum number of connections allowed by the server at once Default value is 20 Document Version 1 70 5 23 2012 620 Structures and Types MTCP_IF_SETTINGS The Modbus IP Interface Settings structure defines the interface settings when using
104. clock the minimum wait time is 16 6 ms Wait times will be rounded up to the next tick value Refer to the Real Time Operating System section for more information on tasks and task scheduling See Also release_processor Document Version 1 70 5 23 2012 547 Function Specifications sleepMode Suspend Controller Operation Syntax include lt ctools h gt UINT16 sleepMode void Description The sleepMode function puts the controller into a sleep mode Sleep mode reduces the power consumption to a minimum by halting the microprocessor clock All programs halt until the controller resumes execution All output points turn off while the controller is in sleep mode The controller resumes execution under the conditions shown in the table below The application program may disable some wake up conditions If a wake up condition is disabled the controller will not resume execution when the condition occurs All wake up conditions will be enabled by default Refer to the Description of the setWakeSource function for details sleepMode returns the source that woke the controller from sleep See Also getWakeSource setWakeSource Document Version 1 70 5 23 2012 548 Function Specifications socket Syntax include lt ctools h gt int socket int family int type int protocol 1 Description socket creates an endpoint for communication and returns a descriptor The family parameter specifies
105. codes e _slaveStation specifies the network address of the slave station This is also known as the slave station number e slaveRegister specifies a Modbus register in the slave station Depending on the protocol function code data may be read or written at this location e masterRegister specifies a Modbus register in the master this controller Depending on the protocol function code data may be read or written at this location e length specifies the number of registers Document Version 1 70 5 23 2012 440 Function Specifications The timeout in tenths of seconds tells the mastering task how long to wait for a response from the slave For TCP protocols the same timeout is also used by the mastering task as the time to wait for a connection to be re established if this is required To disable the timeout and have the mastering task wait forever for a response or a connection to be established set the timeout to 0 This timeout replaces the initial timeout specified in mTcpMasterOpen This allows mTcpMasterMessage to specify different timeout values for different IP addresses each time the function is called If a TCP protocol connection is left idle and the master idle timeout occurs the connection is closed to conserve resources at the remote slave The connection is automatically re established the next time mTcpMasterMessage is called Master idle timeout is set using the function mTcpSetProtocol Closing the TCP I
106. completes define IO COMPLETE 0 int main void INT16 ainData 4 analog input data INT16 aoutData 4 analog output data PID DATA pidData PID algorithm data BOOLEAN executed indicates if PID executed read analog input ioRequest MT Ain4 0 ioNotification IO COMPLETE wait event IO COMPLETE ioReadAin4 0 ainData ia ER get initial process value from analog input pidData pv ainData 0 Document Version 1 70 5 23 2012 450 Function Specifications configure PID block pidData sp 1000 pidData gain 1 pidData reset 100 pidData rate 0 pidData deadband 10 pidData fullScale 32767 pidData zeroScale 0 pidData manualOutput 0 pidData period 1000 pidData autoMode TRUE initialize the PID block pidInitialize amp pidData main loop while TRUE execute all I O requests ioRequest MT Ain4 0 ioNotification IO COMPLETE wait event IO COMPLETE get process input ioReadAin4 0 ainData pidData pv ainData 0 execute the PID block xecuted pidExecute amp pidData if the output changed if executed write the output to analog output module aoutData 0 pidData output ioWriteAout4 0 aoutData ioRequest MT Aout4 0 release processor to other priority 254 tasks release processor Documen
107. configuration Notes DNP needs to be enabled before calling this function in order to create the DNP configuration The function returns TRUE if successful FALSE otherwise Document Version 1 70 5 23 2012 223 Function Specifications dnpWriteMasterPollTableEntry Write DNP Master Poll Table Entry Syntax include lt ctools h gt BOOLEAN dnpWriteMasterPollTableEntry UINT16 index UINT16 dnpAddress UINT16 classOPollRate UINT16 class1PollRate UINT16 class2PollRate UINT16 class3PollRate UINT16 timeSyncRate UINT16 unsolicitedResponseFlags 1 Description This function writes an entry in the DNP master poll table Notes DNP needs to be enabled before calling this function in order to create the DNP configuration The function returns TRUE if successful FALSE otherwise Document Version 1 70 5 23 2012 224 Function Specifications dnpWriteMasterPollTableEntryEx Write DNP Master Poll Table Extended Entry Syntax BOOLEAN dnpWriteMasterPollTableEntryEx UINT16 index DnpMasterPollEx type pMasterPoll 1 Description This function writes an extended entry in the DNP master poll table The function returns TRUE if successful FALSE otherwise Notes This function is only available on the SCADAPack 32 SCADAPack 350 and 4203 DNP needs to be enabled before calling this function in order to create the DNP configuration This function supersedes th
108. const char source const char destination Description The xcopy function copies all files in the specified source folder and sub folders to the location specified by destination If the xcopy operation failed then ERROR is returned OK is returned if the xcopy operation completed successfully The xcopy function used a significant amount of stack space 2 extra stack blocks are required for each layer of sub directories that are to be copied Example When copying myFolder at least 6 stack blocks will be needed due to the 3 levels of folder structure myFolder ProjectA ltem 1 myFolder ProjectB ltem2 myFolder ProjectC ltem 1 myFolder ProjectD ltem1 See Also copy xdelete Document Version 1 70 5 23 2012 570 Function Specifications xdelete Delete a folder and all sub folder Syntax include lt ctools h gt UINT16 xdelete const char source Description The xdelete function deletes all files and folders in the specified source folder If the xdelete operation fails then ERROR is returned OK is returned if the xdelete operation completed successfully The xdelete function used a significant amount of stack space 2 extra stack blocks are required for each layer of sub directories that are to be deleted Example When deleting myFolder at least 6 stack blocks will be needed due to the 3 levels of folder structure myFolder ProjectA ltem 1 myFolder ProjectB ltem2 myFolder ProjectC ltem1
109. current hundredth of a second It is in the range 00 to 99 Document Version 1 70 5 23 2012 631 Structures and Types timer_info timeval VERSION WRITESTATUS The timer_info structure contains information about a timer struct timer info UINT16 time UINT16 interval UINT16 interval remaining 1 e time is the time remaining in the timer in ticks e interval is the length of a timer tick in 10ths of a second e interval_remaining is the time remaining in the interval count down register in 10ths of a second struct timeval long tv_sec Number of Seconds long tv_usec Number of micro seconds he The Firmware Version Information Structure holds information about the firmware typedef struct versionInfo tag UINT16 version UINT16 build UINT16 controller CHAR date VI DATE SIZE 1 CHAR copyright VI_STRING SIZE 1 VERSION e version is the firmware version number e controller is target controller for the firmware e date is a string containing the date the firmware was created e copyright is a string containing Control Microsystems copyright information The WRITESTATUS enumerated type indicates the status of an IC bus message read and may have one of the following values enum WriteStatus WS success WS_selectFailed WS_noAcknowledge Document Version 1 70 5 23 2012 632 Structures and Types F typedef enum WriteStatus WRITESTA
110. delays e timing of process events such as tank fill times e generation of time based interrupts to schedule regular activities e control of digital outputs by time periods The 32 timers are individually programmable for tick rates from ten per second to once every 25 5 seconds Time periods from 0 1 second to greater than nineteen days can be measured and controlled Timer functions require an initialization step before they are used This initialization step creates the timer support task The function runTimers starts the timer task and needs to be called first in order to provide timer functionality There are four library functions related to timers Refer to the Function Specification section for details on each function listed interval Set timer tick interval in tenths of seconds settimer Set a timer Timers count down from the set value to zero timer Read the time period remaining in a timer read_timer_info Read information about a software timer Timer Information Structure The ctools h file defines the structure Timer Information for timer information Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Alternative Methods for Timing If the overhead of the timer task is undesired two alternative methods supported by the firmware exist for user timing See the functions timedEvents and readStopwatch Real Time Clock Functions The controller is provide
111. detailed explanations of the Functions Macros Structure and Types described here Controller Operation Start Up Functions Start Up Macros This section of the manual provides an overview of the functions relating to controller operation The following functions are called by the application startup function appstart They are for use only in the context of appstart Refer to the Function Specification section for details on each function listed startup_task Returns the address of the system start up routine runBackgroundlO Starts or stops the Background I O task runTarget Starts or stops the run time engine task initializeApplicationVariables Initializes user application variables runlOSystem Starts or stops the I O system start_protocol Starts serial protocol according to stored parameters mTcpRunServer Starts or stops the Modbus TCP Server task runMasterlpStartTask Starts or stops the Modbus TCP Master support task runBackgroundlO Starts or stops background UO task e g Dialup support pushbutton LED power control runTarget Starts or stops the run time engine Ladder Logic or IEC 61131 1 executeConstructors Execute user created global class object constructors executeDestructors Execute user created global class object destructors The ctools h file defines the following macros for use with the start up task Refer to the C Tools Macros section for details on each macro listed STARTUP_APPLICATION Specifie
112. e masterMessage function that uses 39800 to 39999 as destination registers e setForceFlag function that use 39800 to 39999 as destination registers e Any registerAssignment that uses registers 39800 to 39999 39800 uchar 8 Controller ID padded with nulls 0 first byte in lowest register one byte per register 39808 Firmware version major 100 minor 39809 Firmware version build number if applicable 39810 Logic application 1 identifier see format below 39813 Logic application 2 identifier see format below 39816 uint Number of applications identifiers used 0 to 32 Identifiers are listed sequentially starting with identifier 1 Unused identifiers will return 0 39817 Application identifier 1 see format below 39820 Application identifier 2 see format below Document Version 1 70 5 23 2012 122 Function Specifications Application identifier 8 see format below Application identifier 9 see format below Application identifier 14 see format below Application identifier 16 see format below Application identifier 18 see format below Application identifier 20 see format below Application identifier 31 see format below Application identifier 32 see format below 39913 to Reserved for future expansion 39999 Application Identifier The application identifier is formatted as follows Company ID see below Application number 0 to 65535 Document Version 1 70 5 23 2012 123 Fu
113. eege eege ees 583 UE 583 Document Version 1 70 5 23 2012 SIFUCTUFES and TYPOS is sessi seient eege 585 ADDPREGG MODE eee eeeeeeeaaaeeeeeeeeesecaaaaeeeeeeeeseensaaeeeeees 585 ALADM GETIING 585 COM INTERFACE iraran aa nitran anaa aaeain aaua haAE 585 COMM ENDPOINT 586 CONNECTION_TYPE 1 cccccccceeeeeeeceeneeeeeeeeeeeeeaaaeeeeeeeeeeeecaaaaeeeeeeesesecsaaeeeeeees 586 DATALOG_CONFIGURATION eeeeeeceeeeeeeeeeeeeeeeeaeeeeeeeeeeeeecaaeeeeeeeeeeeeenaaaes 586 DATALOG_STATUS 200 0 cc ceeeeccceeee cece eee eecceee eset ee eeecaaaaeeeeeeeeeeeeaaaeeeeeeeeteeenaaaes 587 DATALOG VADIADILE 587 BIETE eee 587 DIEUS CEEE 588 dlogConfiguration Tvpe 589 dlogCMITime Type sssssessssseressssssssirrrttssssrirrrtstsssttirrnnttssstnnnnunnsssstnnnnnnnnnnnnt 590 elle elle ER e 590 GlogRecordElement Vy Pe sisisi praeina apararen AEn AEEA riara 590 dog fo Te 592 dlogTransferStatus Type 592 DND ADDDREGG MAP TABLE 593 ellene el e 593 Dnp AnaloolnputGborttloat 594 OnpAnalogOutpout snai even eesre AEE EEEE eens 594 elei EIN Alle 594 ele El a d OC a gt Cmeeremmrernnrrcetrerccrrrerrrrcterercrrrrenrrcrccercerreenrrcrccercerreerrt rcrccerecrret 594 CMpBinarVvOulpUlb eege eae fet Aaia Atte eee 595 dnpConnectonEvent vpe 595 AnpCon liguration vw eee PARE RAR ERR EA 596 dnpContigurationEx c 8 nh ei eA a a A a 600 dnpCounnterInputeceste innana BHR Ri RE AG 605 dnpMasterPoll AAA 606 DNP Master Poll table Extended Emtm 606 elei Ee llg
114. eh dlogStatusiInfo dlogCreate amp usbMemLogConfig amp dlogidNumber while TRUE Read RTC and I Os request resource IO SYSTEM databaseRead MODBUS 10001 amp dinlCurrentState getclock amp currentTime release resource IO SYSTEM Gi Turn on FORCE LED flashing and data logging if DIN1 is turned ON if dinlCurrentState if currentTime second rtcPreviousSecond rtcPreviousSecond currentTime second forceLed getForceLed Log data every 5 seconds if currentTime second 5 640 Document Version 1 70 5 23 2012 Example Programs if logData request resource IO_ SYSTEM Get RTC time stamp date time getClockTime amp flashMemoryRecord valuel days amp flashMemoryRecord valuel centiseconds Read AIN1 raw value databaseRead MODBUS 30001 amp flashMemoryRecord value2 release resource IO SYSTEM Scale AIN1 0 100 flashMemoryRecord value3 float flashMemoryRecord value2 16384 0 100 0 Write date to log file dlogStatusInfo dlogWrite dlogIdNumber UCHAR amp flashMemoryRecord if dlogStatusInfo DLOGS BUFFERFULL dlogStatusInfo dlogFlush dlogIidNumber dlogStatusInfo dlogWrite dlogIdNumber UCHAR amp flashMemoryRecord logData FALSE else logData TRUE
115. example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 208 Function Specifications dnpSaveAOSFConfig Save Short Floating Point Analog Output Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveAOSFConfig UINT16 point dnpAnalogOutput pAnalogOutput 1 Description The dnpSaveAOSFConfig function sets the configuration of a DNP short floating point analog output point The function has two parameters the point number and a pointer to a configuration structure The function returns TRUE if the configuration was successfully written or FALSE otherwise if the point number is not valid or the configuration is not valid or if the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP Document Version 1 70 5 23 2012 209 Function Specifications dnpSaveBliConfig Save DNP Binary Input Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveBIConfig UINT16 point dnpBinaryInput pBinaryInput 1 Description The dnpSaveBlConfig function sets the configuration of a DNP binary input point The function has two parameters the point number and a pointer to a binary input point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configurati
116. from last scan status ioRead5415Inputs 0 dinData check status of last scan if io0Status MT _5415Inputs 0 amp io status status FALSE else if io status commStatus status FALSE print data fprintf coml status u Dins 0 to 7 X r n status dinData 0 release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 327 Function Specifications ioRead5415O0utputs Read 5415 module outputs Syntax include lt ctools h gt BOOLEAN ioRead54150utputs UINT16 moduleAddress UCHAR amp doutData 2 Description This function reads buffered data from I O table for the 12 output points of a 5415 relay output module Buffered data are written using the ioWrite54150utputs function moduleAddress is the address of the 5415 module Valid values are 0 to 15 doutData is a reference to an array of two UCHAR variables Digital data for the 12 outputs are written to this array One bit in the array represents each output point See Also ioWrite54150utputs ioRead541 5Inputs Document Version 1 70 5 23 2012 328 Function Specifications ioRead5505Inputs Read 5505 Inputs Syntax include lt ctools h gt BOOLEAN ioRead5505Inputs UINT16 moduleAddress UINT16 amp dinData float amp ainData 4 Description This function reads buffered data from the digital and analog inputs of a 5505 I
117. function with the argument state set to FALSE stops the Background I O task Calling the function with state set to TRUE starts the task This function should only be needed in the context of the startup function appstart Document Version 1 70 5 23 2012 492 Function Specifications runlOSystem Run I O System Syntax include lt ctools h gt void runIOSystem BOOLEAN state Description The runlOSystem function is used to start or stop the I O System tasks The I O System needs to be running to access I O modules through the functions in the ioRead and ioWrite group Calling the function with the argument state set to FALSE stops the I O System Calling the function with state set to TRUE starts the I O System This function should only be needed in the context of the startup function appstart Document Version 1 70 5 23 2012 493 Function Specifications runLed Control Run LED State Syntax include lt ctools h gt void runLed UINT16 state Description The runLed function sets the run light LED to the specified state state may be one of the following values LED ON turn on run LED LED OFF turn off run LED The run LED remains in the specified state until changed or until the controller is reset Notes The ladder logic interpreter controls the state of the RUN LED If a ladder logic program is loaded and running in the controller the interpreter sets the RUN LED to ON In this situ
118. has a new syntax A TASKINFO structure is no longer returned by the function Instead a pointer to a TASKINFO structure is passed as an argument and a status flag is returned The getTaskInfo function is documented in the Function Specifications section EEPROM Flash Memory Functions SCADAPack 350 and 4203 controllers use flash memory instead of EEPROM to store controller settings The following functions are no longer supported The replacement function is indicated for each Replaced with a fashSettingsLoad lashSetingsSave Controller Status Function The controller status functions setStatusBit and getStatusBit are fully supported The setStatus function is no longer supported Use setStatusBit in place of setStatus Store and Forward Functions The syntax for the following two functions has been changed Instead of passing or returning a SFTranslation structure the new functions pass a pointer to a SF_TRANSLATION structure See the new function syntax in the sections following getSFTranslation Read Store and Forward Translation setSFTranslation Write store and forward translation table entry The previous structure struct SFTranslation shown below is no longer supported struct SFTranslation unsigned portA unsigned stationA unsigned portB unsigned stationB Document Version 1 70 5 23 2012 688 Porting Existing C Tools Applications This structure is replaced with the structure SF_TRANSLAT
119. if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetBOConfig Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 212 Function Specifications dnpSaveCl16Config Save DNP 16 Bit Counter Input Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveCI16Config UINT16 point dnpCounteriInput pCounterInput 1 Description The dnpSaveCl16Config function sets the configuration of a DNP 16 bit counter input point The function has two parameters the point number and a pointer to a counter input point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetCl16Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 213 Function Specifications dnpSaveCl32Config Save DNP 32 Bit Counter Input Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveC1I32Config UINT32 point dnpCounterInput pCounterInput 1 Description
120. in an application program The application program should stop the signaling of timed events when the task which waits for the events is ended If the event signaling is not stopped events will continue to build up in the queue until a function waits for them The Start Timed Event Example shows a simple method using the installExitHandler function See Also endTimedEvent Document Version 1 70 5 23 2012 553 Function Specifications sysSerialSetRxTimeout Set Serial Idle Timeout Before Received Characters Signaled Syntax include lt ctools h gt void sysSerialSetRxTimeout UCHAR port UCHAR timeout Description The sysSerialSetRxTimeout function causes the operating system to report the arrival of characters on the specified port after the specified number of 4 bit timeout intervals A port value of 0 specifies com1 1 specifies com2 and 2 specifies com3 The timeout specifies the number of 4 bit time intervals that the serial receive line needs to be idle for before reporting character arrival Care needs to be exercised as the character time will consist of a start bit 7 or 8 data bits an optional parity bit and a stop bit The number of bits per byte needs to be calculated for the serial port configuration that is being used When the specified timeout has elapsed the installed character hander for that port will be called for each of the received characters Notes This function is useful for message fr
121. invalid or if the device address is invalid Notes The function returns immediately after the command is sent The calling program needs to wait for the response to be received Use the hartStatus command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command A program needs to initialize the link before executing any other commands See Also hartCommand11 hartStatus hartSetConfiguration Document Version 1 70 5 23 2012 286 Function Specifications hartCommand1 Read Primary Variable Syntax include lt ctools h gt BOOLEAN hartCommandl UINT16 module HART DEVICE const device HART VARIABLE primaryVariable Description This function reads the primary variable of a HART device using command 1 The function has three parameters the module number of the 5904 module 0 to 3 the device to be read and a pointer to the primary variable The variable pointed to by primaryVariable is updated when the response is received by the 5904 interface The primaryVariable must be a static modular or global variable A primaryVariable should be declared for each HART I O module in use A local variable or dynamically allocated variable may not be used because a late command response received after the variable is freed will write data over the freed variable space The function returns TRUE if the command was sent The
122. is received for the Enron Modbus station function is a pointer to the handler function If function is NULL the handler is disabled The function has no return value Notes The application needs to disable the handler when the application ends This stops the protocol driver from calling the handler while the application is stopped Call the enronInstallCommmandHandler with a NULL pointer The usual method is to create a task exit handler function to do this See the Example below for details The handler function has five parameters e length is the number of characters in the command message e pCommand is a pointer to the command message The first byte in the message is the function code followed by the Enron Modbus message See the Enron Modbus protocol specification for details on the message formats e responseSize is the size of the response buffer in characters e pResponseLength is a pointer to a variable that will hold the number of characters in the response If the handler returns TRUE it needs to set this variable e pResponse is a pointer to a buffer that will hold the response message The buffer size is responseSize characters The handler must not write beyond the end of the buffer If the handler returns TRUE it needs to set this variable The data needs to start with the function code and end with the last Document Version 1 70 5 23 2012 233 Function Specifications data byte The protocol drive
123. is used in the sample polling function Tool Tor response shown in this example See Also resetAllABSlaves Example This program segment polls slave station 9 for a response communicating on the com2 serial port include lt ctools h gt pollABSlave com2 9 Document Version 1 70 5 23 2012 453 Function Specifications poll_ event Test for Event Occurrence Syntax include lt ctools h gt BOOLEAN poll event UINT32 event Description The poll_event function tests if an event has occurred The poll_event function returns TRUE and the event counter is decrements if the event has occurred Otherwise it returns FALSE The current task always continues to execute Notes Refer to the Real Time Operating System section for more information on events Valid events are numbered 0 to RTOS_EVENTS 1 Any events defined in primitiv h are not valid events for use in an application program Example This program is based on the Install Serial Port Handler Example include lt ctools h gt include nvMemory h define CHAR RECEIVED 11 void signal serial INT32 port INT32 character int main void INT32 character struct prot settings protocolSettings disable protocol get_protocol com2 amp protocolSettings protocolSettings type NO PROTOCOL request resource IO SYSTEM set protocol com2 amp protocolSettings release resource IO SYSTEM Ena
124. lt ctools h gt BOOLEAN dnpWriteRoutingTableEntry UINT16 index UINT16 address UINT16 comPort UINT16 retries UINT16 timeout 1 Description This function writes an entry in the DNP routing table This function is used to write entries without IP addresses To create an entry with an IP address use the dnpWriteRoutingTableEntryEx function Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Use the dnpCreateRoutingTable function to create the routing table and specify its size The function returns TRUE if successful FALSE otherwise Example See the example in the dnpGetConfiguration section Document Version 1 70 5 23 2012 227 Function Specifications dnpWriteRoutingTableEntryEx Write Routing Table Entry with Extended Information Syntax include lt ctools h gt BOOLEAN dnpWriteRoutingTableEntryEx UINT16 index UINT16 address UINT16 comPort UINT16 retries UINT16 timeout IP_ADDRESS ipaddress 1 Description dnpWriteRoutingTableEntryEx writes an entry in the DNP routing table This function is used to write entries with IP addresses To create an entry without an IP address use the dnpWriteRoutingTableEntry function Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Use the dnpCreateRoutingTable function to create the routing table and specify its size The funct
125. mA output e 1 4to 20 mA output 5607 UO Module parameters 0 to 7 define the analog input type for the corresponding input The remaining parameters are not used Valid values are e 0O Oto 5 V input e 1 0to 10 V input e 2 0to 20 mA input e 3 4to 20 mA input 5607 I O Module parameters 8 defines the analog input filter Valid values are e 0Q lt 3Hz maximum filter e 1 6Hz e 2 11 Hz e 3 30 Hz minimum filter 5607 I O Module parameters 9 defines the scan frequency Valid values are e 0 60Hz e 1 50Hz 5607 I O Module parameters 10 defines the analog output type Valid values are e 0 0 to 20 mA output e 1 4 to 20 mA output Notes Up to 150 modules may be added to the Register Assignment If the Register Assignment is full or if an incorrect value is specified for any argument this function returns FALSE otherwise TRUE is returned Document Version 1 70 5 23 2012 100 Function Specifications Output registers specified for certain CNFG type modules are initialized with the current parameter values when the module is added to the Register Assignment e g CNFG_realTimeClock Call clearRegAssignment first before using the addRegAssignmentEx function when creating a new Register Assignment Duplicate or overlapping register assignments are not checked for by this function Overlapping register assignments may result in unpredictable I O activity To obtain error checking that avoids invalid
126. master and slave connections that are currently active If the initial connection started by this function fails the connection will be attempted again if necessary each time mTcpMasterMessage is called See the function mTcpMasterMessage for a discussion of whether to allocate one or several connections when polling multiple remote IP addresses Example See Example for Master Message Example Using mTcpMasterMessage Document Version 1 70 5 23 2012 443 Function Specifications mTcpMasterStatus Modbus IP Master Command Status Syntax include lt ctools h gt BOOLEAN mTcpMasterStatus UINT32 connectID MODBUS CMD STATUS cmdStatus Description The mTcpMasterStatus function obtains the Modbus command status for the connection specified by connectiD This function copies the master command status to the value pointed to by cmdStatus FALSE is returned if the specified connectiD is invalid otherwise TRUE is returned and the status is copied This function may not be called after calling the function mTcpMasterClose with the same connectID The results of such a call are unpredictable as the connectID may have been re used already for a new connection Expected values returned for the command status are described for the enumeration type MODBUS_CMD_STATUS in the Structures and Types section Example See Example for Master Message Example Using mTcpMasterMessage Document Version 1 70 5 23 2012 444
127. mode IP_SETTINGS ipSettings IP ADDRESS remotelIP IP PROTOCOL TYPE protocolType CONNECTION TYPE appType UINT16 timeout UINT32 connectID ODBUS_ CMD STATUS cmdStatus BOOLEAN status UINT16 function UINT16 slaveStation UINT16 slaveRegister UINT16 masterRegister UINT16 length IP settings for SCADAPack LAN interface ipSettings ipConfigMode IPConfig GatewayOnLAN ipSettings ipAddress 0 inet_addr 172 16 10 0 ipSettings gateway 0 inet_addr 172 16 0 1 ipSettings netMask inet_addr 255 255 0 0 ipSettings ipVersion 4 status ethernetSetIP amp ipSettings master IP command definition remoteIP s addr inet_addr 172 16 3 8 destination IP address Document Version 1 70 5 23 2012 666 Example Programs protocolType IPP _ModbusTcp appType CT MasterCApp timeout 30 tenths of seconds function 37 read holding registers slaveStation 1 slaveRegister 40155 masterRegister 40001 length 2 main loop mode MIP OPEN CONNECTION while TRUE switch mode case MIP OPEN CONNECTION open a connection status mTcpMasterOpen remotelIP protocolType appType timeout amp connectID amp cmdStatus 1 if status mode MIP CONNECTING break case MIP CONNECTING check master command status status mTcpMasterStatus connectID amp cmdStatus i
128. ms The stopwatch time rolls over to 0 when it reaches the maximum value for an unsigned long integer 4 294 967 295 ms or about 49 7 days Example This program measures the execution time in ms of an operation include lt ctools h gt int main void UINT32 startTime endTime startTime readStopwatch operation to be timed endTime readStopwatch fprintf coml Execution time lu ms r n endTime startTime Document Version 1 70 5 23 2012 472 Function Specifications readThermistor Read Controller Ambient Temperature Syntax include lt ctools h gt INT16 readThermistor UINT16 scale Description The readThermistor function returns the temperature measured at the main board in the specified temperature scale If the temperature scale is not recognized the temperature is returned in Celsius The scale may be T_CELSIUS T_FAHRENHEIT T_KELVIN or T_RANKINE The temperature is rounded to the nearest degree Example include lt ctools h gt void checkTemperature void INT16 temperature temperature readThermistor T_FAHREHEIT if temperature lt 0 fprintf coml It s COLD r n lse if temperature gt 90 fprintf coml It s HOT r n Document Version 1 70 5 23 2012 473 Function Specifications readTimerVariable Read IEC 61131 1 Timer Variable IEC 61131 1 firmware only Syntax include lt ctool
129. on the socket TCP socket only TM_EALREAY A previous close call is already in progress TM_ECONNABORTED The TCP connection was reset because the linger option was on with a timeout value of 0 TCP socket only TM_ETIMEDOUT The linger option was on with a non zero timeout value and the linger timeout expired before the TCP close handshake with the remote host could complete blocking TCP socket only Document Version 1 70 5 23 2012 119 Function Specifications configurationRegisterMapping Enable or disable mapping of device configuration registers Syntax include lt ctools h gt void configurationRegisterMapping BOOLEAN enabled 1 Description This function enables or disables mapping of device configuration registers These registers are located at a fixed location in the input register area enabled selects if the registers are mapped Valid values are TRUE and FALSE Selecting FALSE hide the configuration data but does not change it See Also configurationSetApplicationID Document Version 1 70 5 23 2012 120 Function Specifications configurationSetApplicationID Set an application ID Syntax include lt ctools h gt BOOLEAN configurationSetApplicationID UINT16 applicationType UINT16 action UINT16 companyID UINT16 application UINT16 version 1 Description This function stores or removes an application ID in the device configuration data The device configur
130. option value is set User variable is of data type described below The size of the user variable It is the size of the option data type described below Socket level protocol IP level protocol TCP level protocol ProtocolLevel Option Name Option data Option type value SOL_SOCKET SO_DONTROUTE int Oor1 SO_KEEPALIVE int Oori GO _ LINGER struct linger Document Version 1 70 5 23 2012 539 Function Specifications ProtocolLevel Option Name Option data Option type value SO_OOBINLINE int Oori SO_RCVBUF unsigned long SO_RCVLOWAT unsigned long SO_REUSEADDR int Oori SO_SNDBUF unsigned long SO_SNDLOWAT unsigned long IP_PROTOIP IP_TOS unsigned char IP_TTL unsigned char IP_MULTICAST_TTL unsigned char IP_MULTICAST_IF struct in_addr IP_PROTOTCP TCP_MAXSEG int TCP_NODELAY int Oor1 Returns 0 Successful set of option 1 An error occurred setsockopt will fail if EBADF The socket descriptor is invalid EINVAL One of the parameters is invalid ENOPROTOOPT The option is unknown at the level indicated EPERM Option cannot be set after the connection has been established ENETDOWN Specified interface not configured yet EADDRINUSE Multicast host group already added to the interface ENOBUF ENOENT Attempted to delete a non existent multicast entry on the specified interface Not enough memory to add new multicast entry Document Version 1 70 5 23 2012 540 Function Specifications setStatusBit Set Bits in Cont
131. pointed to by pTranslation into the store and forward translation table at the location specified by index Valid values for index are 0 to 127 The function checks for invalid translations The translation is stored even if invalid The SF_TRANSLATION structure is described in the Structures and Types section The function returns a SFTranslationStatus structure It is described in the Structures and Types section The code field of the structure is set to one of the following If there is an error the index field is set to the location of the translation that is not valid SE VALID VALID All All translations are valid are valid message on the same port E valid SF_STATION_OUT_OF_R_ One or both of the stations is not valid ANGE SF_ALREADY_DEFINED The translation already exists in the table G INDEX_OUT_OF_RAN The entry referenced by index does not exist in the table INVALID_FORWARDIN The forwarding IP address is invalid G_IP Notes The TeleBUS Protocols User Manual describes the store and forward messaging mode Writing a translation with both stations set to station 65535 can clear a translation in the table Station 65535 is not a valid station Document Version 1 70 5 23 2012 531 Function Specifications The Modbus protocol type and communication parameters may differ between serial ports The store and forward messaging will translate the protocol messages Translations describe t
132. register assignments such as these use the Telepace Register Assignment dialog to build the Register Assignment Then save the Register Assignment in a Ladder Logic file e g filename lad and download it with the C program or transfer the Register Assignment to the C program using the clearRegAssignment and addRegAssignmentEx functions To save the Register Assignment with the controller settings in flash memory so that it is loaded on controller reset call flashSettingsSave as shown in the example below The IO_SYSTEM resource needs to be requested before calling this function See Also addRegAssignment clearRegAssignment Example include lt ctools h gt int main void UINT16 parameters 16 request resource IO SYSTEM Create the Register Assignment clearRegAssignment add a 5606 module parameters 0 0 0to5 Vv parameters 1 0 0to5 Vv parameters 2 0 0to5 Vv parameters 3 0 0to5 Vv parameters 4 3 4 to 20 mA parameters 5 3 4 to 20 mA parameters 6 3 4 to 20 mA parameters 7 3 4 to 20 mA parameters 8 0 3 Hz input filter parameters 9 0 60 Hz scan frequency parameters 10 1 4 to 20 mA outputs addRegAssignmentEx SCADAPack 560610 0 1 10001 30001 40001 parameters release resource IO SYSTEM Document Version 1 70 5 23 2012 101 Function Specifications save register assignment
133. removed the flush might not remove any records from the buffer If this is the case the function returns DLOGS_ FAILURE The file remains open after flushing To close a file in preparation for moving it or removing external media use the dlogSuspend function See Also dlogSuspend Document Version 1 70 5 23 2012 154 Function Specifications dlogGetStatus Return the auto transfer and media status information of a data log Syntax include lt ctools h gt dlogStatus dlogGetStatus UINT32 dlogID dlogTransferStatus transferStatus dlogMediaStatus mediaStatus BOOLEAN extMediaInUse Parameters The function has these parameters e dlogID is the ID of the data log e transferStatus is a pointer to memory where the transfer status is written to e mediaStatus is a pointer to memory where the media status is written to D extMedialnUse is a pointer to memory where it is written if the external media is in use or not The function returns e DLOGS_SUCCESS if status information was retrieved e DLOGS_BADID if the data log ID is invalid Description This function returns the transfer status media status and external media in use information of a particular data log The transfer status indicates the result or the progress of a recent triggered auto transfer to a removable mass storage device The media status indicates the presence of log media and if it provides space for dlog operations The ext
134. set to FALSE Default value is FALSE e enronEnabled determines if the Enron Modbus station is enabled It may be TRUE or FALSE Document Version 1 70 5 23 2012 621 Structures and Types e enronStation is the station address for the Enron Modbus protocol It is used if enronEnabled is set to TRUE Valid values are 1 to 255 for standard addressing and 1 to 65534 for extended addressing pconfig The pconfig structure contains serial port settings struct pconfig UINT16 baud UINT16 duplex UINT16 parity UINT16 data bits UINT16 stop bits UINT16 flow rx UINT16 flow tx UINT16 type UINT16 timeout 1 e baud is the communication speed It is one of the BAUD macros e duplex is either the FULL or HALF macro e parity is one of NONE EVEN or ODD macros e data_bits is the word length It is either the DATA7 or DATA8 macro e stop_bits in the number of stop bits transmitted The only supported selection is the STOP1 macro e flow_rx specifies flow control on the receiver It is either the RFC_MODBUS_RTU ENABLE or RFC_NONE DISABLE If the Modbus RTU protocol is used set flow_rx to RFC_MODBUS_RTU For the Modbus ASCII protocol or any other protocol set flow_rx to RFC_NONE e flow_tx specifies flow control on the transmitter It is either the TFC_IGNORE_CTS ENABLE or TFC_NONE DISABLE macro Setting this parameter to TFC_IGNORE_CTS causes the port to ignore the CTS signal Setting this paramete
135. state It is either the LED_ON or LED_OFF macro e time is the period in minutes after which the LED power returns to its default state MASTER_MESSAGE The MASTER_MESSAGE structure defines a Modbus serial master message typedef struct st_masterMessage FILE stream serial port UINT16 function Modbus function code UINT16 slaveStation slave station address UINT16 slaveRegister slave Modbus register UINT16 masterRegister master Modbus register UINT16 length number of registers UINT16 timeout time to wait for response in tenths of seconds BOOLEAN eventRequest signal event on completion optional UINT32 eventNo event to signal when timeout or response received optional MASTER MESSAGE e streamis the serial port to send the command message Valid values are com1 com2 and com3 e function specifies the Modbus function code Refer to the communication protocol manual for supported function codes Document Version 1 70 5 23 2012 616 Structures and Types e _slaveStation specifies the address of the slave station e slaveRegister specifies the location of data in the slave station Depending on the Modbus function code data may be read or written at this location e masterRegister specifies the location of data in the master this controller Depending on the function code data may be read or written at this location e length specifies
136. status FALSE Document Version 1 70 5 23 2012 321 Function Specifications wait for scan to complete ioNotification MY_ EVENT wait event MY_EVENT read input data from last scan status ioRead5210Inputs counterData dinData check status of last scan if i1o0Status MT_5210Inputs 0 bio status status FALSE else if i0 status commStatus status FALSE print data fprintf coml status u Dins 0 to 7 X Counter 1 d r n status dinData counterData 0 release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 322 Function Specifications ioRead52100utputs Read SCADAPack 330 controller board outputs Syntax include lt ctools h gt BOOLEAN ioRead52100utputs UCHAR amp doutData 1 Description This function reads buffered data from the digital outputs of a SCADAPack 330 controller board Buffered data are written with the ioWrite5210Outputs function doutData is a reference to a variable to receive the digital output values e Bit 0 of this variable is written with the USB LED control e Bit 1 of this variable is written with the com3 HMI power control e Bits 2 to 7 are not used The function returns TRUE as no I O errors are possible See Also ioRead5210Inputs ioWrite52100utputs Document Version 1 70 5 23 2012 323 Function Speci
137. system functions Most I O System functions are C functions In order to call C functions from a source file the source file must be a CPP file If an existing C file must be renamed to a CPP file The following is a list of the UO System functions Each function is documented in the Function Specifications section Description C TieNotifcation Request tege T ioSystemResi Request reset of al VO modules iones Request TO module scan Toses Read 10 module status v ioReadAin4 Read buffered data from 4 point analog input module v ioReadAin8 Read buffered data from 8 point analog input module v ioReadAout2 Read buffered data for 2 point analog output module v ioReadAout4 Read buffered data for 4 point analog output module v ioReadCounter4 Read buffered data from 4 point TTT Liceo n v ioReadCounterSP2 Read buffered data from SCADAPack 350 counters v ioReadDin16 Read buffered data from 16 point digital input module v ioReadDin8 Read buffered data from 8 point digital input module v ioReadDout16 Read buffered data for 16 point digital output module v ioReadDout8 Read buffered data for 8 point digital output module v ioReadSP2Inputs Read buffered data from SCADAPack 350 inputs v ioReadSP2Outputs Read buffered data for SCADAPack 350 outputs ioWriteAout2 Write buffered data for 2 point Document Version 1 70 5 23 2012 685 Porting Existing C Tools Applications a analog outpu
138. the controller settings in the indicated area or areas to flash memory Settings in other areas are not affected The function has one parameter areaFlags indicating which areas to store into flash A sum of more than one area may be selected The function returns TRUE if all the settings were stored and FALSE if there was an error writing to flash If an unsupported flag is set the flag has no effect If there is no supported flag set e g areaFlags 0 all current settings are saved again Valid flags are listed below and defined in ctools h Area Flag Loaded on Reset Controller Settings in this Area CS_ETHERNET Ethernet MAC address CS_OPTIONS Controller factory options CS PERMANENT Saved settings loaded Controller type IP address on Service and Run Gateway Network mask IP Boot Configuration mode Lock state and password I O Replaced with default System settings settings on Cold Boot Saved settings loaded Serial port settings Serial on Run Boot protocol settings Modbus TCP settings HART I O settings LED power Default settings loaded settings on Service Boot Replaced with default settings on Cold Boot Notes The FLASH_MEMORY resource needs to be requested before calling this function Document Version 1 70 5 23 2012 241 Function Specifications forceLed Set State of Force LED Syntax include lt ctools h gt void forceLed UINT16 state Description The forceL
139. the resource is in use the task is blocked until it is available Notes Use the request_resource function to control access to non sharable resources Refer to the Real Time Operating System section for more information on resources See Also release_resource Example This code fragment obtains the dynamic memory resource allocates some memory and releases the resource include lt ctools h gt void task void unsigned ptr code here request _ resource DYNAMIC MEMORY ptr unsigned malloc size t 100 release resource DYNAMIC MEMORY more code here Document Version 1 70 5 23 2012 487 Function Specifications resetAlIABSlaves Erase All DF1 Slave Responses Syntax include lt ctools h gt UINT16 resetAllABSlaves FILE stream Description The resetAllABSlaves function is used to send a protocol message to all slaves communicating on the specified port to erase all responses not yet polled stream specifies the serial port This function applies to the DF1 Half Duplex protocols only The function returns FALSE if the protocol currently installed on the specified serial port is not a DF 1 Half Duplex protocol otherwise it returns TRUE Notes The purpose of this command is to re synch slaves with the master if the master has lost track of the order of responses to poll This situation may exist if the master has been power cycled for Example
140. to prevent unauthorized changes in operating characteristics Document Version 1 70 5 23 2012 17 About The Book About The Book Ata Glance Document Scope This manual describes C Tools for SCADAPack 300 and 4203 controllers Validity Notes This document is valid for all SCADAPack 300 and 4203 firmware versions Product Related Information AWARNING UNINTENDED EQUIPMENT OPERATION The application of this product requires expertise in the design and programming of control systems Only persons with such expertise should be allowed to program install alter and apply this product Follow all local and national safety codes and standards Failure to follow these instructions can result in death serious injury or equipment damage User Comments We welcome your comments about this document You can reach us by e mail at technicalsupport controlmicrosystems com Document Version 1 70 5 23 2012 18 Overview Overview The SCADAPack C Tools are ideal for engineers and programmers who require advanced programming tools for SCADA applications and process control The SCADAPack controllers execute Telepace Ladder Logic or IEC 61131 1 and up to 32 C application programs simultaneously providing you with maximum flexibility in implementing your control strategy This manual provides documentation on SCADAPack C programming and the library of C language process control and SCADA functi
141. units specified by variableCode 0 Variables 1 transmitter variable code and units specified by variableCode 1 Variables 2 transmitter variable code and units specified by variableCode 2 Variables 3 transmitter variable code and units specified by variableCode 3 The function returns TRUE if the command was sent The function returns FALSE if the module number is invalid Notes The HART_DEVICE structure needs to be initialized using hartCommandoO or hartCommand11 The pointer variables needs to point to an array with at least four elements Document Version 1 70 5 23 2012 292 Function Specifications The function returns immediately after the command is sent The calling program needs to wait for the response to be received Use the hartStatus command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command The function requests four variables and expects four variables in the response See Also hartCommand3 hartStatus hartSetConfiguration Document Version 1 70 5 23 2012 293 Function Specifications hartStatus Return Status of Last HART Command Sent Syntax include lt ctools h gt BOOLEAN hartStatus UINT16 module HART RESULT status UINT16 code Description This function returns the status of the last HART command sent by a 5904 module 0 to 3 Use this function to determin
142. well as the main task priority Task priorities are discussed under changes to the function create_task The heap size is no longer configurable The C application has access to the entire system heap Open the sample appstart cpp to review these application settings Priority of the task main Priority 100 is recommended for a continuously running task UINT32 mainPriority 100 Stack space allocated to the task main Note that at least 5 stack blocks are needed to call fprintf UINT32 mainStack 5 Application group assigned to the task main A unique value is assigned by the system to the applicationGroup for this application Use this variable in calls to create_task by this application UINT32 applicationGroup 0 A C application should not require any further modifications to appstart cpp Note that there are no longer function calls in appstart for starting various drivers as there were in the SCADAPack version These drivers are already running when a C Application is executed It is still possible to call these Document Version 1 70 5 23 2012 680 Porting Existing C Tools Applications functions to disable functionality For example runTarget FALSE may still be called from appstart or main to stop the logic application Add Existing Program Files to Framework e Copy all user written C files from the SCADAPack application to the framework directory created in t
143. with a socket Options may exist at multiple protocol levels they are always present at the uppermost socket level When manipulating socket options the level at which the option resides and the name of the option must be specified To manipulate options at the socket level protocolLevel is specified as SOL_SOCKET To manipulate options at any other level protoco Level is the protocol number of the protocol that controls the option For Example to indicate that an option is to be interpreted by the TCP protocol protocolLevel is set to the TCP protocol number For getsockopt the parameters optionValuePir and optionLengthPtr identify a buffer in which the value s for the requested option s are to be returned For getsockopt optionLengthPir is a value result parameter initially containing the size of the buffer pointed to by optionValuePtr and modified on return to indicate the actual size of the value returned optionName and any specified options are passed un interpreted to the appropriate protocol module for interpretation The include file lt ctools h gt contains definitions for the options described below Options vary in format and name Most socket level options take an int for optionValuePtr SO_LINGER uses a struct linger parameter that specifies the desired state of the option and the linger interval see below struct linger is defined in lt ctools h gt struct linger contains the following members onoff on 1 off
144. 0 _linger linger time in seconds The following options are recognized at the socket level SOL_SOCKET protocolLevel options SO_ACCEPTCONN Enable disable listening for connections listen turns on this option SO_DONTROUTE Enable disable routing bypass for outgoing messages Default 0 SO_KEEPALIVE Enable disable keep connections alive Default 0 disable SO_OOBINLINE Enable disable reception of out of band data in band Default is 0 Document Version 1 70 5 23 2012 271 Function Specifications SO_REUSEADDR Enable disable local address reuse Default 0 disable SO_RCVLOWAT The low water mark for receiving SO_SNDLOWAT The low water mark for sending SO_RCVBUF The buffer size for input Default is 8192 bytes SO_SNDBUF The buffer size for output Default is 8192 bytes SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind call should allow reuse of local addresses SO_KEEPALIVE enables the periodic transmission of messages every 2 hours on a connected socket If the connected party fails to respond to these messages the connection is considered broken SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities Instead messages are directed to the appropriate network interface according to the network portion of the destination address SO_LINGER controls the action taken when unsent messages are queued on a socket and a close on the socket is perfor
145. 0 mA inputFilter selects input filter selection is written to this variable e 0 3Hz e 1 6Hz e 2 11 Hz e 3 30 Hz scanFrequency selects the scan frequency setting Valid values are e 0 60Hz e 1 50 Hz Document Version 1 70 5 23 2012 387 Function Specifications outputType selects the analog output type setting Valid values are e 0to20mA e 1 4to20mA The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5607Outputs ioRead5607Inputs Example This program turns on all 10 digital outputs and sets the analog outputs to full scale on the 5607 module at address 5 include lt ctools h gt define MY EVENT 1 void main void UCHAR doutData 2 INT16 aoutData 2 UINT16 inputType 8 UINT16 inputFilter UINT16 scanFrequency UINT16 outputType IO STATUS io status BOOLEAN status main loop while TRUE write data to output tables for next scan doutData 0 OxFF doutData 1 OxFF aoutData 0 32767 aoutData 1 32767 set analog input types to 4 20 mA inputType 0 3 inputType 1 3 inputType 2 3 inputType 3 3 inputType 4 3 inputType 5 3 inputType 6 37 inputType 7 3 set filter and frequency inputFilter 3 minimum filter scanFrequency 0 60 Hz set analog output type to 4 20 mA outputType 1 Document Version 1 70 5 23 2012 388
146. 0 to 7 X r n status dinData 0 release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 325 Function Specifications ioRead541 5Inputs Read 5415 module inputs Syntax include lt ctools h gt BOOLEAN ioRead5415Inputs UINT16 moduleAddress UCHAR amp dinData Description This function reads buffered data from the digital inputs relay coil power status and power jumper position of the 5415 relay output module Buffered data are updated when an I O request for the module is processed moduleAddress is the address of the 5415 module Valid values are 0 to 15 dinData is a reference to a UCHAR variable Digital data from the 2 inputs are written to this array Bit 0 holds the relay coil power status Bit 1 holds the relay power jumper position See Also ioWrite54150utputs ioRead541 50utputs Example This Example reads the digital inputs on the 5415 I O module include lt ctools h gt include nvMemory h define MY EVENT 1 void main void UCHAR dinData 1 IO STATUS io status BOOLEAN status main loop while TRUE add module scan to queue if i1oRequest MT_5415Inputs 0 status FALSE wait for scan to complete ioNotification MY EVENT Document Version 1 70 5 23 2012 326 Function Specifications wait event MY_EVENT read input data
147. 012 300 Function Specifications htons Syntax include lt ctools h gt unsigned short htons unsigned short shortValue 1 Description This function converts a short value from host byte order to network byte order Parameters shortValue The value to convert Returns The converted value Document Version 1 70 5 23 2012 301 Function Specifications inet_addr Syntax include lt ctools h gt unsigned long inet addr char ipAddressDottedStringPtr 1 Function Description This function converts an IP address from the decimal dotted notation to an unsigned long Parameters ijpAddressDottedStringPtr The dotted string i e 208 229 201 4 Returns Value Meaning 1 Error Other The IP Address in Network Byte Order Document Version 1 70 5 23 2012 302 Function Specifications install_ handler Install Serial Port Handler Syntax include lt ctools h gt void install handler FILE stream BOOLEAN function INT32 INT32 Description The install_handler function installs a serial port character handler function The serial port driver calls this function each time it receives a character If stream does not point to a valid serial port the function has no effect function specifies the handler function which takes two arguments The first argument is the port number The second argument is the received character If function is NULL the default handler for th
148. 1 70 5 23 2012 574 Macro Definitions DE_FailedToConnect The modem could not connect to the remote site DE_InitError Modem initialization failed the modem may be turned off DE_NoDialTone Modem did not detect a dial tone or the S6 setting in the modem is too short DE WE DE_NoModem The serial port is not configured as a modem port type must be RS232_MODEM Or no modem is connected to the controller serial port function or has answered an incoming call DIN_END DIN_START DISABLE Specifies flow control is disabled DNP Specifies the DNP protocol for the serial port Variable name decrease output DOUT_END Number of last regular digital output channel DOUT_START Number of first regular digital output channel DS_Calling The controller is making a connection to a remote controller DS _ Connected The controller is connected to a remote controller remote controller functions such as malloc and alloc DIO_SUPPORTED If defined indicates digital I O hardware supported Document Version 1 70 5 23 2012 575 Macro Definitions channel channel channel channel FORCE SINGLE COIL GASFLOW Gas Flow calculation firmware option Definition 1IO_SYSTEM System resource for all I O hardware functions LAN ENABLED Enables LAN communication power consumption Document Version 1 70 5 23 2012 576 Macro Definitions LINEAR Specifies linear database addressing LOAD_MULTIPLE_R
149. 1131 1 application downloaded or e There is no IEC 61131 1 variable assigned to the specified Modbus address The function has two parameters e The address parameter is the Modbus address to be read e The value parameter is a pointer to an integer containing the current value at address If the address is to be handled the handler function needs to return TRUE and the value pointed to by value needs to be set to the current value for the specified Modbus address If the address is not to be handled the function needs to return FALSE and the value pointed to by value needs to be left unchanged Notes The IO_SYSTEM resource must be requested before calling dbase which calls this handler Requesting the IO_SYSTEM resource allows that only one task may call the handler at a time Therefore the function does not have to be re entrant An array may be defined to store the current values for all Modbus addresses handled by this function See the section Data Storage if a non initialized data array is required See Also installDbaseHandler Document Version 1 70 5 23 2012 148 Function Specifications deallocate_envelope Return Envelope to the RTOS Syntax include lt ctools h gt void deallocate envelope envelope penv Description The deallocate_envelope function returns the envelope pointed to by penv to the pool of free envelopes maintained by the operating system See Also allocate_envelope Exampl
150. 31 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the dbase function The IO_SYSTEM system resource needs to be requested before calling this function See Also readintVariable Example This program displays the contents of the real variable named Flow include lt ctools h gt int main void BOOLEAN status float value request resource IO SYSTEM status readRealVariable Flow value release resource IO SYSTEM Document Version 1 70 5 23 2012 470 Function Specifications fprintf coml status Su Flow Sf r n status value Document Version 1 70 5 23 2012 471 Function Specifications readStopwatch Read Stopwatch Timer Syntax include lt ctools h gt UINT32 readStopwatch void Description The readStopwatch function reads the stopwatch timer The stopwatch time is in ms and has a resolution of 10
151. 32 startTime create _task taskl 75 applicationGroup 4 while TRUE body of main task loop Document Version 1 70 5 23 2012 545 Function Specifications The body of this main task is intended solely for signaling the event waited for by taskl Normally main would be busy with more important things to do otherwise the code in taskl could be executed within main s wait loop startTime readStopwatch while readStopwatch startTime lt 1000 wait for 1 s Allow other tasks to execute release processor signal event 20 Document Version 1 70 5 23 2012 546 Function Specifications sleep_processor Release Processor to other Tasks for a certain time Syntax include lt ctools h gt void sleep processor UINT32 msTime Description The sleep_processor function releases control of the CPU to other tasks for a certain time Other tasks of the same priority get a chance to run or when no such task is in a ready state lower priority tasks will run This function is similar to release_processor with the difference that the CPU is released for at least msTime which represents milliseconds Tasks of the same priority run ina round robin fashion as each releases the processor to the next Notes The call sleep_processor 0 has the same effect as the call release_processor Internally the sleep time msTime will be converted into ticks With a 60 Hz system
152. 50 C Application Main Program Copyright c 2009 Control Microsystems Inc DESCRIPTION The following program demonstrates how to configure data log for data logging into the external FLUSH memory This program is doing the following adding register assignment for SCADAPack 350 configure data for logging thr values per record date time AIN1 raw value and AIN1 scaled value 0 to 100 and then creates the log use DIN1 to suspend DIN1 OFF or resume DIN1 ON data loging toggling FORCE LED every second as indication that data logging is active loging data every 5 seconds Date 01 APR 09 Name Goran Babic Descr File Example created FER A IK A AR he IR A I A A AA A A AA A he e I A I d include ctools h include nvMemory h extern C Document Version 1 70 5 23 2012 637 Example Programs add prototypes here typedef struct dataRecord dlogCMITime valuel INT16 value2 float value3 dlogRecord KKK Eh k K K I K k k K K k he k k k k k k K A K k k K K k k K I K k k k k k k k k k k k k k k main This routine is the main application loop FER AK A A AR he A A A A kkk kkk kkk kkk kkk kkk k kkk kkk kK d int main void char statusString SUCCESS FAILURE INPROGRESS EXISTS DIFFERENT INVALID NOMEMORY BADID WRONGPARAM BUFFERFULL NOTSTARTED
153. 5506Outputs ioRead5601Inputs ioRead5604Inputs ioRead5606Inputs ioRead5606Outputs ioRead5607Inputs ioRead56070utputs Read the controller ambient temperature sensor Read 4 analog inputs into I O database Read 8 analog inputs into I O database Read the digital and analog inputs from a 5505 I O Module Read the configuration data from a 5505 I O Module Read the digital and analog inputs from a 5506 I O Module Read the configuration data from a 5506 I O Module Write the configuration data to a 5505 I O Module Write the configuration data to a 5506 I O Module Read the digital and analog inputs from a SCADAPack 5601 I O Module Read the digital and analog inputs from a SCADAPack 5604 I O Module Read the digital and analog inputs from a 5606 I O Module Read the digital and analog outputs from a 5606 I O Module Read the digital and analog inputs from a 5607 I O Module Read the digital and analog outputs from a 5607 I O Module ioRead4203DRinputs Read the inputs from a 4203 DR controller ioRead4203DSInputs Read the inputs from a 4203 DS controller Analog Output Functions The controller supports external analog output modules Refer to the SCADAPack 350 System Hardware Manual or the SCADAPack 4203 Hardware Manual for further information on these modules There are three library functions related to analog output modules Refer to the Function Specification section for details on each function listed i
154. 6 eventCountAI32 number of 32 bit analog input UINT16 eventCountAISF number of short floating point analog input events UINT16 eventCountClass1 number of class 1 events UINT16 eventCountClass2 number of class 2 events UINT16 eventCountClass3 number of class 3 events DND RUNTIME STATUS eventCountBI is number of binary input events eventCountCl16 is number of 16 bit counter events eventCountCl32 is number of 32 bit counter events eventCountAl16 is number of 16 bit analog input events eventCountAl32 is number of 32 bit analog input events EventCountAISF is number of short floating point analog input events eventCountClass1 is the class 1 event counter eventCountClass2 is the class 2 event counter eventCountClasss is the class 3 event counter The envelope type is a structure containing a message envelope Envelopes are used for inter task communication Document Version 1 70 5 23 2012 609 Structures and Types HART_COMMAND HART_DEVICE typedef struct envelope type UINT32 source sender task ID UINT32 destination destination task ID UINT32 type type of message UINT32 data the message data envelope e link is a pointer to the next envelope in a queue This field is used by the RTOS It is of no interest to an application program e source is the task ID of the task sending the message This field is specified automatically by the send_mes
155. 654 Memory Allocation Exvample 659 Master Message Example Using Modbus Protocol eeeeeeeeeeseeeeeeeseeene 660 Master Message Example Using serialModbusMaster ssssssssssnnnennneneennne 662 Master Message Example Using mTcpMasterMessage eeeeneceeneeeene 666 Modem Initialization Example 0 cccccccceceeeeeeeeeeeeeeccceeeeeeeeeteeectaeeeeeeeeeenee 669 Real Time Clock Program Example sssssssesseeeessesssssirrrisesssrrirnnssssssrrrnnnsssens 670 Start Timed Event Example cccccceeeeeeeeccneeeeeeeeeeeeeecaaeeeeeeeeeeeesnsaeeeeeees 671 Porting Existing C Tools Applications s eeeeeeeeeeeees 673 Document Version 1 70 5 23 2012 Porting SCADAPack 32 C Applications to the SCADAPack 350 and 4203 673 Partially Supported C Tools Functions sssssssssesseeseseseeessssseeesssesseeaaes 675 Unsupported C Tools Funchons nnana nnmnnn 678 Porting SCADAPack C Applications to the SCADAPack 350 and 4203 Document Version 1 70 5 23 2012 Index of Figures Figure 1 Figure 2 Figure 3 Figure 4 Figure 5 Figure 6 Figure 7 Figure 8 Figure 9 Queue Status before Execution of Main Task 56 Queue Status at Start of main Task 56 Queue Status after Creation of echoData Task ccccecceseeeeeeeees 57 Queue Status After echoData Task Waits for Event 57 Queue Status after Creation of auxiliary Task 57 Queue Status After main Task Releases Pro
156. 70 5 23 2012 567 Function Specifications For better performance use the variable s network address and the setdbase function The IO_SYSTEM system resource needs to be requested before calling this function Example This program writes the message Warning to the message variable named TextData TextData has a maximum length of 10 bytes and a current length of 7 bytes include lt ctools h gt int main void BOOLEAN status unsigned char msg 13 10 7 W al rn i n Wake ony msg msg msg msg msg msg msg msg msg msg msg msg msg ll Q ov Oo AJO AHC ll fa request CesourtcellO SYSTEM status writeMsgVariable TextData msg release resource IO SYSTEM Document Version 1 70 5 23 2012 568 Function Specifications writeTimerVariable Write to IEC 61131 1 Timer Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN writeTimerVariable UCHAR varName UINT32 value Description This function writes a value in milliseconds to the specified timer variable The maximum value that may be written is 86399999 ms or 24 hours If the value is greater than 86399999 ms the va ue modulus 86399999 is written to the timer variable The specified timer may be active or stopped The variable is specified by its name expressed as a character string The name is case insensitive The IEC
157. ADASense 4203 IEC 61131 1 Firmware Image o imLink 4203 0 Document Version 1 70 5 23 2012 26 Getting Started Build the Application The next section lists the dependencies of the object files on header and source files Add additional header files and source files here The ctools h file is not added to the list of dependencies list all source file dependencies her appstart o appstart cpp nvMemory h main o main cpp nvMemory h The next section contains the rules for compiling files Generally no changes will ever be required in this section The compiler options affecting this that should be changed are defined in the CFLAGS setting above SoS eae a Sa ee ee eS ee oe ee Ee eo SS eee ee Se ee SS rules for making files E SS ee Se Se a EE Se e Se ee Se eee ee ere eS e Se So S C ccarm CFLAGS c lt o SR 0 cpp ccarm CFLAGS c lt o SR The next section contains the rules for cleaning out output files from a folder Use make clean to start over from a clean slate and compile files again If you add additional types of output files you will need to modify this section PHONY clean clean del o del out The gnu C compiler is a command line compiler To build the application e Open a command prompt from a shortcut or use this procedure o Click Start gt Run o In Opentype cmd and click OK e Switch to the folder containing the project o For example type cd c projects s
158. ALUS iat ivectenchinehsevivestvnehonehseshseshvnet eu ebekeb eege gh Abee geg thehwevhvevevnet EES 275 QEStStatusB this egsbttet e dh aeresEtAEKAEEEASESREERAEEEAEEEASEEREERAEEEAEEEASEEREERAAEEAEEEASEEREEAATE OASE 276 GEL TASKING EE 277 QELVEFSION siete EEEE EE E E E E EEE EEEE EEE 278 Oe ke Ett eEseeesEEeEEAEEESSEREEAEEEAEEEASEEREEAEEEAEUEASEEREERKEEEAEEEASEEREEEKALEA EA eES 279 Handler FOOT eee gege ee eege EE eae 280 Te EN 283 ELTERE geegent 284 EE e une EE 286 W e EIN 287 W eu ln 288 EEE e anla E S EAEE AAAA iii 289 EEE anlaa ET e Abd VATA 291 w al E IT 292 W E 294 Nat GetCombiQurati On vases vs cscs eevee vs vees vt es vse us us beset epee vysnusvauesteasseepausveanseerseeeeartesse 296 een Ee 297 Part PaCkStrinO s ssscasevczeceescdvecseasateeececdvusvacsaaeencesdvveveeatviad sasdebeveandnaaz aitebeaeaetnase 298 bart lnpack Gring 299 LTB 300 lte 301 lei el 302 installl Ha NGl et s25 2 s 208 ei Hee HENAN Ne HENAN RHR NNER NE Nee 303 installClockHandler sinnena a a a EES 304 June Ree E ITT 305 installSetdbaseHandler ceccceeeeeeeeeeeeeeeccneeeeeeeeeeeeeccaeeeeeeeeeteeedaeeeeeeeeetnee 306 EE UI ne E E 308 installModbusHandler cceeeeeeeeeeeeeeeeeeeeeceeeeeeeeeeeeecaaeeeeeeeesteeecaaeeeeeeeeenee 309 InstalIRTCHANIEL eerror eeaeee nn nnn nin nn ni aeo aa ain 310 Fe Cainer RUIN CUO EE 311 EEN 312 eil 313 IOGCIGONfGUFALION orra r E T 315 leiere HO GE 316 ei 203 Wl leie 317 Iobiead 202tDGlnpute eres 319 el
159. Also clearBreakCondition Document Version 1 70 5 23 2012 509 Function Specifications setclock Set Real Time Clock Syntax include lt ctools h gt void setclock TIME now Description The setclock function sets the real time clock now references a TIME structure containing the time and date to be set Refer to the Structures and Types section for a Description of the fields All fields of the clock structure needs to be set with valid values for the clock to operate properly Notes The IO_SYSTEM resource needs to be requested before calling this function See Also getclock Example This function switches the clock to daylight savings time include lt ctools h gt void daylight void TIME now request resource IO SYSTEM getclock amp now now hour now hour 1 24 setclock amp now request resource IO SYSTEM Document Version 1 70 5 23 2012 510 Function Specifications setClockAlarm Set the Real Time Clock Alarm Syntax include lt ctools h gt UINT16 setClockAlarm ALARM SETTING alarm Description The setClockAlarm function configures the real time clock to alarm at the specified alarm setting The ALARM_SETTING structure alarm specifies the time of the alarm Refer to the ctools h section for a Description of the fields in the structure The function returns TRUE if the alarm can be configured and FALSE if there is an error i
160. BUS CONNECTION STATUS if the state has changed if currentConnectionState lastConnectionState iff the connection is active if currentConnectionState Inform DNP that a connection exists Kf dnpConnectionEvent DNP_CONNECTED clear the request flag setdbase MODBUS CONNECTION REQUIRED 0 else Inform DNP that the connection is closed dnpConnectionEvent DNP_DISCONNECTED clear the message flags Document Version 1 70 5 23 2012 190 Function Specifications setdbase MODBUS MESSAGE COMPLETE 0 setdbase MODBUS MESSAGE FAILED 0 save the new state lastConnectionState currentConnectionState release the processor so other tasks can run release resource IO SYSTEM release processor 191 Document Version 1 70 5 23 2012 Function Specifications dnpMasterClassPoll Send DNP Class Poll Syntax BOOLEAN dnpMasterClassPoll UINT16 slaveAddress UINT16 classFlags 1 Description The dnpMasterClassPoll function sends a Class Poll message in DNP to request the specified data classes from a DNP slave slaveAddress specifies the DNP station address of the slave classFlags specifies the classes of data to request It can contain any combination of the following values if multiple values are used they shou
161. C fendif Lh ee Sea re SE Include files if Ee RR ee eee Pee Se oe include ctools h b i Add fields to this global structure for variables used in your application file s that need to be non volatile Include nvMemory h in all files that use the variable pNvMemory to access NV memory typedef struct s_nvMemory UCHAR dummyVariable Add fields here for variables used in your application file s that need to be non volatile Non volatile variables required by main cpp UINT32 variablel UCHAR arrayl1 20 struct sample table 10 Non volatile variables required by file2 cpp float variable2 NV MEMORY Pointer to static non volatile data Document Version 1 70 5 23 2012 43 C Program Development extern NV MEMORY pNvMemory ifdef cplusplus endif endif NVMEMORY_H GNU Compiler Options The GNU C compiler is installed with the C Tools The build bat file included in the sample C application uses the following command line for compiling ccarm 03 mapcs 32 mlittle endian march armv4 ansi fno builtin DARMEL I SCTOOLS PATH DCPU ARMARCH4 DTOOL FAMILY gnu DTOOL gnu std c99 c main cpp These compiler options are described in the table below The complete list of compiler options is may be found in the document Using the GNU Compiler Collection GCC which is installed with the compiler at C Program Files Control Microsys
162. CADAPack C Applications The SCADAPack 350 and 4203 support up to 32 separate user loaded C Applications Event numbers 0 to 31 were made available to the SCADAPack C application This same event number range needs to be shared on the SCADAPack 350 and 4203 among the user loaded C Applications The Realflo C Application uses events 20 21 or 22 These events may not be used by other C Applications when the Realflo C Application is loaded in the SCADAPack 350 and 4203 Stack used by fprintf Function Tasks that call the function fprintf require at least 5 stack blocks This function required only 4 stack blocks when used in SCADAPack C applications As a general rule add 1 stack block to the amount used in a SCADAPack application Macro stdout is Disabled The macro stdout is disabled in the SCADAPack C Tools Instead use the serial port macros com1 com2 or com3 This means that the following functions that use stdout do not work printf putc getc Use the replacement functions listed below Replaced with Task Creation Function The task priorities have changed with the SCADAPack 350 and 4203 There are now 255 priority levels and the highest priority task has a priority of 0 Existing calls to create_task will need to be modified to account for a lower number being a higher priority The table below contains the recommended priority values to use when porting Priority Description Equivalent Priority Pri
163. COL TYPE type IP PROTOCOL SETTINGS pSettings Description The mTcpGetProtocol function copies the settings for a specific Modbus IP or DNP IP protocol to the structure pointed to by pSettings The protocol type is selected with the type argument and it may be set to any of the following IPP_ModbusTcp IPP_ModbusRtuOverUdp IPP_ModbusAsciiOverUdp IPP_DnpOverTcp or IPP_DnpOverUdp If the protocol type is valid the settings are copied and TRUE is returned If the protocol type is invalid FALSE is returned and nothing is copied The structure IP_PROTOCOL_SETTINGS is described in the Structures and Types section See Also mTcpSetProtocol mTcpGetInterfaceEx Document Version 1 70 5 23 2012 433 Function Specifications mTcpSetConfig Set Modbus TCP Protocol Settings Syntax include lt ctools h gt BOOLEAN mTcpSetConfig MTCP_CONFIGURATION pSettings Description The mTcpSetConfig function is used to configure settings common to all connections using the Modbus TCP protocol Existing connections are maintained after calling this function For this reason it is recommended that all connections using this protocol be closed before calling this function If this function is used to change the port number or maximum number of server connections then the Modbus TCP Server task is ended and re started with the new settings Port number changes will only affect new connections made after calling this f
164. COMPLETE hy strLogDescription Data Log to File Example strLogName AIN1 data log INT16 rtcPreviousSecond 0 dinlCurrentState 0 dinlPreviousState 0 UINT32 dlogidNumber dlogStatus dlogStatusInfo dlogRecordElement recordFieldsDefinitions 3 TIME currentTime BOOLEAN logData TRUE Document Version 1 70 5 23 2012 638 Example Programs dlogRecord flashMemoryRecord dlogConfiguration usbMemLogConfig 7x SI Add RTC and SP350 I Os in register assignment wf request _ resource IO SYSTEM clearRegAssignment addRegAssignment SCADAPack 210 0 1 10001 30001 40001 release resource IO SYSTEM CS x Delete all existing logs d ay dlogStatusInfo dlogDeleteAll Data log configuration Config struct version should be always set to 1 usbMemLogConfig configVersion 1 The oldest log file will be deleted when a new fil would exceed defined maximum number of files when this parameter is set to TRU Fl usbMemLogConfig fileRingBuffer TRUE Interval in seconds after which server will flush buffer to file usbMemLogConfig bufferFlushInterval 10 Buffer size is number of records in the data log buffer usbMemLogConfig bufferRecordSize 1000 External drive selected when set to 3 usbMemLogConfig fileMode 3 Fl Maximum num
165. CPP source file The framework has two files You should add additional files here objects appstart o main o The next section sets the default list of controllers for which the application is made The targets in this list are used when make is typed on the command line without arguments The default list can be overridded by specifying targets on the command line The application is linked against symbol files for the firmware for these target controllers The C Tools and include paths are set in the next section The paths are taken from the environment variable you set during installation If the variable is not present they default to the standard paths You don t need to do anything to this section take the C Tools path from the environment or set default if it s not there default may not be correct for all installations ifeq strip CTOOLS PATH CTOOLS PATH C Program Files Control Microsystems CTools endif INCLUDE PATH CTOOLS PATH Controller IEC 61131 1 Document Version 1 70 5 23 2012 24 Getting Started The next section sets the default compiler flags You can add to or modify these flags Change the default options with care as many are required for correct operation The flags are described in the gnu C compiler manual I Ee a en er A ee Se Ee compiler flags eS Ser a eS a Se Se ae ae SE SE eee See eee ee CFLAGS 03 mapcs 32 mlittle endian march armv4 an
166. CTION STATUS 1 connection status register sampleDNPHandler This function is the user defined DNP connection handler It will be called by internal DNP routines when a connection is required when confirmation of a message is received and when a communication timeout occurs Document Version 1 70 5 23 2012 188 Function Specifications The function takes a variable of type DND CONNECTION EVENT as an input This input instructs the handler as to what functionality is required The valid choices are connection required DNP_CONNECTION REQUIRED message confirmation received DNP_MESSAGE COMPLETE and timeout occurred DNP_ MESSAGE TIMEOUT he function does not return any values SJ static void sampleDNPHandler DND CONNECTION EVENT event Determine what connection event is required or just occurred switch event case DNP_CONNECTION REQUIRED indicate connection is needed and clear other bits request _ resource IO_ SYSTEM setdbase MODBUS CONNECTION REQUIRED 1 setdbase MODBUS MESSAGE COMPLETE 0 setdbase MODBUS MESSAGE FAILED 0 release resource IO SYSTEM break case DNP_MESSAGE COMPLETE indicate message sent and clear other bits Bul reque
167. Confirm enables requesting data link layer confirmations Valid values are TRUE and FALSE e datalinkRetries is the number of times the data link layer will retry a failed message Valid values are 0 to 255 e datalinkTimeout is the length of time the data link layer will wait for a response before trying again or aborting the transmission The value is measured in milliseconds Valid values are 100 to 60000 in multiples of 100 milliseconds e operateTimeout is the length of time an operate command is valid after receiving a select command The value is measured in seconds Valid values are 1 to 6500 e applicationConfirm enables requesting application layer confirmations Valid values are TRUE and FALSE e maximumResponse is the maximum length of an application layer response Valid values are 20 to 2048 The recommended value is 2048 unless the master cannot handle responses this large e applicationRetries is the number of times the application layer will retry a transmission Valid values are 0 to 255 e applicationTimeout is the length of time the application layer will wait for a response before trying again or aborting the transmission The value is measured in milliseconds Valid values are 100 to 60000 in multiples of 100 milliseconds This value must be larger than the data link timeout e timeSynchronization defines how often the RTU will request a time synchronization from the master e Set this to NO_TIME_SYNC to disable
168. DNP event buffer The format of the event will depend on the Event Reporting Method and Class of Event Object that have been configured for the point The function returns TRUE if the event was generated It returns FALSE if the DNP point is invalid or if the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 167 Function Specifications dnpGenerateEventLog Generates a change event for the DNP point Syntax include lt ctools h gt BOOLEAN dnpGenerateEventlLog UINT16 pointType UINT16 pointAddress Description The dnpGenerateEventLog function generates a change event for the DNP point Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 168 Function Specifications dnpGetAl16Config Get DNP 16 bit Analog Input Configuration Syntax include lt ctools h gt BOOLEAN dnpGetAI16Config UINT16 point dnpAnalogInput pAnalogInput Description The dnpGetAl16Config function reads the configuration of a DNP 16 bit analog input point The function has two parameters the point number and a pointer to an analog input point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been cre
169. Document Version 1 70 5 23 2012 464 Function Specifications readinputVoltage Read Input Voltage Syntax include lt ctools h gt INT16 readInputVoltage void Description The readInputVoltage function returns the input supply voltage in millivolts The typical range is 9000 to 30000 mV Example include lt ctools h gt if readInputVoltage lt 9000 fprintf coml The input supply voltage is low r n Document Version 1 70 5 23 2012 465 Function Specifications readintVariable Read IEC 61131 1 Integer Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN readIntVariable UCHAR varName INT32 value Description This function returns the current value of the specified integer variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the variable value is written to the signed long value pointed to by value If the variable is not found or if the IEC 61131 1 Symbols Status is invalid FALSE is returned and the current value is left unchanged The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to th
170. E 156 elle eg UE 157 elle RESUME EE 158 elle Eet 159 GIOGSUSPENG WE 160 GIOQW rite cs cet cus shel ENE ENEO EEEE EEEE EEEE 161 elle en ee E 162 ANPCONNESCTIONEVESNt as scvecvedveegenedversenetvavtunedvnesenetesebenydeeeynytenvueanteevueeetenyeeseneyys 163 dnpCreatehddreseMapping Table 164 dnpCreateMasterPoll Table 0 eee e cesses ee eeenaeeeeeesaeeeeeesaaeeeeseaeeeeneaeees 165 AnpCreateROutingT aile 166 AnpGenerateChangeE vent cceeecceneeeeeeeeeeeecaeeeeeeeeeeeecaaeeeeeeeesteesnnaaeeeeees 167 AnpGenerateEventLlog ecccceesccceeeesseeeeeseeeeesesseeeesesseenessesennessenseneesenseneess 168 AnpGetAl1 GC omg 169 CMP GOTAIS2C OMAN RE 170 CMP GTA SE GON hs ess ess esis veces vs cues cabs op pees TENNEK NEREP TIS vee saususenseesvepeversanes seeeeere 171 MPG EtTAO TG COMIC BEE 172 CMP GTA OS2AC RE 173 CMPGETAOSE ue DEE 174 COMP EE ee te WEE 175 dnpGeiblConfotN AA 176 CNPGEIBO COMO f x ssessersercensts ores pense Sanat one penne Sinan tees penne ei as 177 ONPGetG Leute ET 178 dnpGetC S2Conlig t 4 nanannntnanennnnanenn nna a as 179 dnptGettonfiouration eee ececeeeeesneeeeeeenneeeeeenaeeeeseseeeeseseeeesseneeeesenaeees 180 AnpGetConfigurationEX 0 0 eee ee essere cesses eeeenaeeeeseaeeeeseseeeessenaeeeeeenaeees 184 AnpGetRuntimeStatus oe cece eeeeenneeeeeenaeeeesesaeeeeeesaeeeessenaeeeesenaeees 185 dnptGet JnsoltcitedBackoft me 186 dnplnstallConnectiontiandler 187 dnpMasterlaseboll 192 alle een ET 193 CMP Geiger se e
171. EEN 479 redlsierBulkDevCperation 481 release PrOCOSSOM ci astesceesieesveesetenetveetenvtenstenetenyivevienstesenenyivnvevasteeunenebeneeveriyays 483 Ee le 484 removeModbusHandler AA 485 EDD SlOM APEE A AE EE ECKER EAEA O NEESS EREN 486 FEQUEST CSOULCE TTT 487 FESCTAIIABSIAVES wesc cviiecitesieeassesdeeestessbepanesgeensteeshssneetguenstegsbessaesuaetststeeeaseveaea 488 stlechen ebeseguEEtAKSLAEEEAREREEEEAEELAASEEREREEEEAEELAASERERREEE EELER ERSEERRE SEAN 489 FOULS enen E A A E A E EET 490 FUNBaCKQrOUNLO a E 492 ONEI TE 493 IR 494 FUAMAaSterl pS taut TASK ess cscs ve cies sees tessa eyes essees O nar es SEERRSENEREEA AER SE NEES EEN 495 PUD AOU ET 496 SO CL OE REER ORERE ORRERA EESEEReSEEE 497 SONG E 499 SOMO nET et e E 502 SOMO E 504 serialModbushasier AAA 506 Set DF1 Protocol Configuration c ccccceccceeeceeeeeeeeeeeeeeecceeeeeeeeeeeesnsaeeeeeees 508 SetBreakConditiOna r ass face neh nena nena Hehehe ees 509 ee EE 510 eu EE 511 ele EE 512 Setdbase Handler Function c cccccceeeeeeeeeccneeeeeeeeeeeeeeccaeeeeeeeeseseennneeeeeees 514 SEDAR a EE 515 SEIT erstat a aaa O aaO aia 516 Aa E 517 lei reelle lte ue Le D 519 setOutputsInStopMode AAA 520 Aoi TEE 521 S tkoginCredentjal Sirari atni e 523 e ee E 524 e tee Tue tive retentions ra 525 EE erger E 526 Ge atelier le EE 527 setProtocolSettingSEX AA 529 Document Version 1 70 5 23 2012 SetSPiiranslation sce cna ee EE EE 531 SEtSF lranslation Ex
172. EGISTER Modbus function code S LOAD_SINGLE_REGISTER Modbus function code LOW_POWER_MODE Reduces the operating speed of the controller reducing power consumption MAX_NUMBER_OF_FIELDS The maximum number of fields in a data log record MAX_NUMBER_OF_LOGS The maximum number of data logs MAX_PRIORITY The maximum task priority address code length address returned an address exception returned a function exception returned a value exception sent ORTED not supported received MM_SENT MODBUS Specifies Modbus database addressing MODBUS_ASCII Specifies the Modbus ASCII protocol emulation for the serial port MODBUS_ PARSER System resource Modbus protocol message parser MODBUS_RTU Specifies the Modbus RTU protocol emulation for the serial port Document Version 1 70 5 23 2012 577 Macro Definitions MODEM_CMD_MAX_LEN Maximum length of the modem initialization command string MODEM_MSG System event new modem message generated WC ae MIT Aoutd Checkaum Four channel analog output module with checksum This module type can only be used with analog output modules with checksum support MT_Counter4 Four channel counter input module MT_CounterSP2 SCADAPack 350 controller board counter inputs MT_Din16 Sixteen channel digital input module MT_Din32 Thirty two channel digital input module MT_Din8 Eight channel digital input module MSG_POINTER Specifies the data field in an envelope contains a poin
173. EI eee i ee A An A A RA 607 dnpProetocelStatusine ih BH BAR NE EHR RIK HE AG 608 dnpRouting WE E EE 608 DNP_RUNTIME_ STATUS ceececccceeeee eee ee eeeeeaaeeeeeeeeeeeecaaeeeeeeeeeeneenaaaes 609 UE 609 HAT COMMAND teeter eet ee tees essere et eecaaeeeeeeeeeteeedaaeeeeeeeeenee 610 HART DEVICE E 610 HART RESPONSE E E E A EE E E 611 HART RESULT erreiaren tnea aaaea tana latae ena Daa aeaa EELER OESEER EES EE 611 HARE SEL E EEEE EE EEEE AEE ES 612 HART VARIABLE vs ctetesccesctesseenstenetenstenvtensbenetensbeavhensteeetensteavtvesteeetensteneeeecteees 612 IOM CONFIG ee E 612 IO STATUS e 613 IP DB nle A E EEEE E EAE AEE O 613 IP CONNECTION GUMMARN 613 IP_CONFIG_MODE Enumeration 0 ccssssssssseeeeeeeesesssssssesseseseseseseeaeaaes 614 IP PROTOCOL SETTING te a a ebe rtetet eet eg ieteeteasdeeteteetavieetes 614 P de Kee el d 615 DPSS ET TING eege erer seve egkegeeg e eege E eege 615 Document Version 1 70 5 23 2012 Elei E e EE 616 MASTERsMESSAGE s ii tnd ine a 616 MODBUS GMB STATUS aisha natant naan 617 MOGe Il itt 5 escent a a eee 619 Modem Sctlip seth Mat ann an an A a A At 619 MTOR CONFIGURATION a a 620 MEO A E N E E E E asteestineeeeste ege 621 MTOP IESEL HN EXinduandadndadndadnadaielnedeiedesindeninaee 621 POCONO WE 622 PID DATA OENES AN ek EEEE ated EEEE EEE EEEO E 622 PROTOCOL SETTINGS E 624 PROTOCOL_SETTINGS_EX Twpe 624 prot setting a eee vaceeete cavteneteyelnctunedvnetysutenebenedvestes vinnetenebee
174. Function Specifications mTcpRunServer Run Modbus IP Servers Syntax include lt ctools h gt void mTcpRunServer BOOLEAN state Description The mTcpRunServer function is used to start the servers for each IP protocol The IP protocols include Modbus TCP Modbus RTU over UDP Modbus ASCII over UDP DNP over TCP and DNP over UDP Calling this function with TRUE starts the servers according to the IP protocol settings If the server enabled setting for the protocol is TRUE then the server is started If the server enabled setting for the protocol is FALSE then the server is stopped Calling this function with FALSE stops each IP protocol server and updates IP protocol settings accordingly Use the function mTcpSetProtocol to enable or disable a server for a specific IP protocol This function should only be needed in the context of the startup function appstart Document Version 1 70 5 23 2012 445 Function Specifications ntohl Syntax include lt ctools h gt unsigned long ntohl unsigned long longValue 1 Description This function converts a long value from network byte order to host byte order Parameters longValue The value to convert Returns The converted value Document Version 1 70 5 23 2012 446 Function Specifications ntohs Syntax include lt ctools h gt unsigned short ntohs unsigned short shortValue 1 Description This function converts a short value fr
175. Group 4 msg allocate envelope msg gt destination tid msg gt type MSG_DATA msg gt data 1002 ll Document Version 1 70 5 23 2012 502 Function Specifications send_message msg wait for ever so that main and other APPLICATION tasks won t end while TRUE Allow other tasks to execute release processor Document Version 1 70 5 23 2012 503 Function Specifications sendto Syntax include lt trsocket h gt int sendto int socketDescriptor char bufferPtr int bufferLength int flags const struct sockaddr toPtr int toLength 1 Description sendto is used to transmit a message to another transport end point sendto may be used at any time either in a connected or unconnected state but not for a TCP socket socketDescriptor is a socket created with socket The address of the target is given by to with toLength specifying its size If the message is too long to pass atomically through the underlying protocol then 1 is returned with the socket error being set to EMSGSIZE and the message is not transmitted A return value of 1 indicates locally detected errors only A positive return value does not implicitly mean the message was delivered but rather that it was sent If the socket does not have enough buffer space available to hold the message being sent and is in blocking mode sendto blocks If it is in non blocking mode or the MSG_DONTWAIT
176. I string into a HART packed ASCII string The function has three parameters a pointer to a packed array a pointer to an unpacked array and the size of the packed array The packed array needs to be a multiple of three in size The unpacked array needs to be a multiple of four in size It should be padded with spaces at the end if the string is not long enough The function has no return value See Also hartUnpackString Document Version 1 70 5 23 2012 298 Function Specifications hartUnpackString Convert HART Packed String to String Syntax include lt ctools h gt void hartUnpackString CHAR pString const CHAR pPackedString UINT16 sizePackedString Description This function unpacks a HART packed ASCII string into a normal ASCII string The function has three parameters a pointer to an unpacked array a pointer to a packed array and the size of the packed array The packed array needs to be a multiple of three in size The unpacked array needs to be a multiple of four in size The function has no return value See Also hartPackString Document Version 1 70 5 23 2012 299 Function Specifications htonl Syntax include lt ctools h gt unsigned long htonl unsigned long longValue 1 Description This function converts a long value from host byte order to network byte order Parameters longValue The value to convert Returns The converted value Document Version 1 70 5 23 2
177. ID Parameters The function has these parameters e dlogID is the ID of the data log The function returns e DLOGS_SUCCESS if logging was resumed e DLOGS _BADID if the data log ID is invalid Description This function resumes writing to a previously suspended data log If external media is configured for the data log the first connected drive name is retrieved If data log configuration files are not present they are created immediately The data log file is created when the first data log record is written from the log buffer A dlogResume call on an already active data log has no impact See Also dlogSuspend Document Version 1 70 5 23 2012 158 Function Specifications dlogSpace Return the space available in the data log buffer Syntax include lt ctools h gt dlogStatus dlogSpace UINT32 dlogID UINT32 pBufferRecords Parameters The function has these parameters e dlogID is the ID of the data log e pBufferRecords is a pointer a variable to hold the number of records in the buffer The function returns e DLOGS_ SUCCESS if the number of records was returned e DLOGS_BADID if the data log ID is invalid e DLOGS_WRONGPARANM if an error due to wrong parameter happened e DLOGS_FAILURE if an unexpected error happened Description This function returns the number of records remaining in the data log buffer for the log This determines how many records the data log server can be written to t
178. ID although the ID will eventually recycle if enough logs are created Document Version 1 70 5 23 2012 151 Function Specifications dlogDelete Delete a data log and all associated resources except log files Syntax include lt ctools h gt dlogStatus dlogDelete UINT32 dlogID Parameters The function has these parameters e dlogID is the ID of the data log to be deleted The function returns e DLOGS_SUCCESS if the data log was deleted e DLOGS_BADID if the data log ID is not valid e DLOGS_FAILURE if the data log could not be deleted Description This function deletes a data log The memory for the log is freed The data log ID is marked as invalid The data log server will not collect further records for this log ID The directory file is deleted if it is accessible This might be not the case if data log files were written to removable media The data log name is removed from the master log file Data Log files are not deleted If the log was created with a path the created directory still exists after the log is deleted Document Version 1 70 5 23 2012 152 Function Specifications dlogDeleteAll Delete all data logs and all associated resources except log files Syntax include lt ctools h gt dlogStatus dlogDeleteAl1 Parameters The function has no parameters The function returns e DLOGS_SUCCESS if all data logs were deleted e DLOGS_FAILURE if all data logs could not be deleted De
179. ILE stream 1 Parameters stream is a pointer to a serial port valid serial ports are com com2 coms and com4 Description The clearBreakCondition function clears a break condition on the communication port specified by stream The communication port will return to idle status Notes This function is only relevant for RS232 ports The function will have no effect on other port types See Also setBreakCondition Document Version 1 70 5 23 2012 111 Function Specifications clear_errors Clear Serial Port Error Counters Syntax include lt ctools h gt void clear errors UCHAR port Description The clear_errors function clears the serial port error counters for the serial port specified by port H port is not a valid serial port the function has no effect The IO_SYSTEM resource needs to be requested before calling this function Document Version 1 70 5 23 2012 112 Function Specifications clear_protocol_status Clear Protocol Counters Syntax include lt ctools h gt void clear protocol status FIL Description The clear_protocol_status function cl serial port specified by port If portis effect The lO_SYSTEM resource needs to E stream ears the error and message counters for the not a valid serial port the function has no be requested before calling this function Document Version 1 70 5 23 2012 113 Function Specifications clearLoginCr
180. ION which includes an IP address field to accommodate store and forward involving the Ethernet port The structure is defined as typedef struct st_SFTranslationMTcp COM_INTERFACE slavelnterface slave interface type UINT16 slaveStation slave station address COM_INTERFACE forwardInterface forwarding interface type UINT16 forwardStation forwarding station address IP_ADDRESS forward IPAddress forwarding IP address SF_TRANSLATION The following table explains how to correct existing programs that use the older structure The new SF_TRANSLATION structure is documented following this table Item to be replaced Replacement struct SFTranslation The new structure has the macro name SF_TRANSLATION portA field Set s avelnterface field portA 1 1 com1 2 com2 3 com3 100 Ethernet1 portB field Set forwardinterface field portB 1 1 com1 2 com2 3 com3 100 Ethernet1 stationA field slaveStation field stationB field forwardStation field Instead of entering a translation in any order for the communication interfaces as done with the old structure the translation data is entered specifying the receiving slave interface slavelnterface and slaveStation and the forwarding master interface forwardinterface forwardStation and forward PAddress if applicable Translations describe the communication path of the master command e g the slave interface which receives the command an
181. IO_SYSTEM system resource needs to be requested before calling this function Example This program writes a TRUE state to the boolean variable named Switch include lt ctools h gt int main void BOOLEAN status request resource IO SYSTEM status writeBoolVariable Switch1 TRUE release resource IO SYSTEM Document Version 1 70 5 23 2012 564 Function Specifications writelntVariable Write to IEC 61131 1 Integer Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN writeIntVariable UCHAR varName INT32 long value Description This function writes to the specified integer variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the specified signed long value is written to the variable If the variable is not found or if the IEC 61131 1 Symbols Status is invalid nothing is done and FALSE is returned The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by
182. LE port Description The modemAbort function unconditionally terminates a dial up connection connection in progress or modem initialization started by the C application port specifies the serial port where the modem is installed The connection or initialization is terminated only if it was started from a C application Connections made from a Ladder Logic application and answered calls are not terminated This function can be used in a task exit handler Notes The serial port type needs to be set to RS232_ MODEM A pause of a few seconds is required between terminating a connection and initiating a new call This pause allows the external modem time to hang up Use this function in a task exit handler to clean up any open dial up connections or modem initializations If a task is ended by executing end_task from another task modem connections or initializations needs to be aborted in the exit handler Otherwise the reservation ID for the port remains valid No other task or Ladder Logic program may use modem functions on the port Not calling modemAbort or modemAbortAll in the task exit handler may result in the port being unavailable to any programs until the controller is reset The modem connection or initialization is automatically terminated when IEC 61131 1 stops the C application and when the controller is rebooted Reservation IDs returned by the modemDial and modemlInit functions on this port are invalid after callin
183. LOGS_BADID if the data log ID is not valid e DLOGS FAILURE if the record could not be written due to a run time error Description This function writes a record to the data log specified by dlogID Memory is copied from the pointer address to the data log buffer The data is packed as it is written to the buffer Gaps due to structure alignments are not written Packing is performed using the size and offset information specified during data log creation dlogWrite stores a record sequence number at the start of the record in the buffer A CRC16 value is computed for the data including the heading sequence number and stored at the end of the record The data log buffer is flushed regularly to data log files by the data log server task See Also dlogFlush Document Version 1 70 5 23 2012 161 Function Specifications dnpClearEventLogs Clear DNP Event Log Syntax include lt ctools h gt BOOLI EAN dnpClearl Description EventLogs void The dnpClearEventLogs function deletes all change events from the DNP change event buffers for all point types Document Version 1 70 5 23 2012 162 Function Specifications dnpConnectionEvent Report a DNP connection event Syntax include lt ctools h gt void dnpConnectionEvent UINT16 dnpAddress DND CONNECTION EVENT event Description The dnpConnectionEvent function is used to report a change in connection status to D
184. M ENDPOINT CONNECTION_TYPE The CONNECTION_TYPE enumerated type defines connection types supported by the connection pool typedef enum ipConnection t CT Unused 0 CT Slave slave task connection CT_MasterIEC 61131 1 master task connection created for an IEC 61131 1 masterip FB CT MasterCApp master task connection created for a C application CT_MasterSF master task connection created for store and forward CONNECTION TYPE Only the connection type CT_MasterCApp may be used in C applications DATALOG_CONFIGURATION The data log configuration structure holds the configuration of the data log Each record in a data log may hold up to eight fields The typesOfFields entry in the structure specifies the types of the fields Not all the fields are used if fewer than eight elements are declared in this array The amount of memory used for a record depends on the number of fields in the record and the size of each field Use the datalogRecordSize function to determine the memory needed for each record Document Version 1 70 5 23 2012 586 Structures and Types typedef struct datalogConfig type UINT16 records of records UINT16 fields of fields per record SJ DATALOG VARIABLE typesOfFields MAX NUMBER OF FIELDS DATALOG CONFIGURATION DATALOG_STATUS The data log status enumerated type is used to report status information typed
185. NGE Result code invalid translation table index SF_STATION_OUT_OF_RAN Result code station number is not valid GE SF_TABLE_ SIZE Number of entries in the store and forward table SIGNAL_OFF Specifies a signal is de asserted SIGNAL_DCD Matches status of DCD input SIGNAL_OH I O line bit mask off hook signal SIGNAL_OH Not supported forced low 1 SIGNAL_ON Specifies a signal is asserted SIGNAL_RING I O line bit mask ring signal 1 SIGNAL_RING Not supported forced low 0 SIGNAL_VOICE I O line bit mask voice data switch signal Document Version 1 70 5 23 2012 581 Macro Definitions database linear database linear database database STARTUP_ Specifies the application start up task STARTUP_SYSTEM Specifies the system start up task STOP1 Specifies 1 stop bit SYSTEM Specifies a system type task System tasks are not terminated by the end_application function T_CELSIUS Specifies temperatures in degrees Celsius T FAHRENHEIT Specifies temperatures in degrees Fahrenheit TFC_IGNORE_CTS Flow control type may be used in place of ENABLE TFC_NONE Flow control type may be used in place of DISABLE TS_READY Task status indicating task is ready to execute TS_WAIT_ Task status indicating task is blocked RESOURCE waiting for a resource Document Version 1 70 5 23 2012 582 Macro Definitions waiting for an envelope waiting for an event waiting for a message V VI_DATE_SIZE
186. NO wait for your event to be signalled when all your I O requests have been processed wait event SCAN EVENT NO get the data read from Input modules ioRead5601Inputs dinData ainData request resource IO SYSTEM copy Ain data to the database for index 0 index lt 8 index setdbase MODBUS 31001 index ainData index copy Din data to the database for index 0 index lt 16 index tt if dinData amp 0x01 setdbase MODBUS 11001 index 1 else Document Version 1 70 5 23 2012 658 Example Programs setdbase MODBUS 11001 index 0 dinData gt gt 1 get 12 DOUT points from the database for index 0 index lt 12 index doutData lt lt 1 if dbase MODBUS 1012 index doutData 1 release resource IO SYSTEM release processor to other priority 254 tasks release processor Memory Allocation Example This program allocates dynamic non volatile memory only when the C Application is run the first time after downloading Refer to the section Non Volatile Data Sections for instructions on declaring non volatile variables This program assumes that the pointer pAllocatedMem has been declared in nvMemory h include lt ctools h gt include nvMemory h struct myTable UINT32 data 100 define MEM SIZE sizeof struct myTable int main void
187. NP This function is only used if a custom DNP connection handler has been installed dnpAddress is the address of the remote DNP station event is current connection status The valid connection status settings are DNP_CONNECTED and DNP_DISCONNECTED See Also dnpInstallConnectionHandler Example See the dnplnstallConnectionHandler example Document Version 1 70 5 23 2012 163 Function Specifications dnpCreateAddressMappingTable Create DNP Address Mapping Table Syntax include lt ctools h gt BOOLEAN dnpCreateAddressMappingTable UINT16 size CHAR enableMapChangeEvents Description The dnpCreateAddressMappingTable function destroys any existing DNP address mapping table and allocates memory for a new address mapping table according to the size parameter Notes DNP needs to be enabled before calling this function in order to create the DNP configuration The function returns TRUE if successful FALSE otherwise Document Version 1 70 5 23 2012 164 Function Specifications dnpCreateMasterPollTable Create DNP Master Poll Table Syntax include lt ctools h gt BOOLEAN dnpCreateMasterPollTable UINT16 size Description This function destroys any existing DNP master poll table and allocates memory for a new table according to the size parameter The poll interval is set in seconds Notes DNP needs to be enabled before calling this function in order to creat
188. Notes If the specified register is currently forced dbase returns the forced value for the register The I O database is not modified when the controller is reset It is a permanent storage area which is maintained during power outages The lIO_SYSTEM resource needs to be requested before calling this function See Also setdbase Example include lt ctools h gt int main void int a request resource IO SYSTEM Read Modbus status input point a dbase MODBUS 10001 Read 16 bit register a dbase LINEAR 3020 Read 16 bit register beginning at first status register Document Version 1 70 5 23 2012 146 Function Specifications a Read 6th input register EAR START INPUT 5 a dbase dbase LIN LIN EAR START STATUS release resource IO SYST EM Document Version 1 70 5 23 2012 147 Function Specifications Dbase Handler Function User Defined Dbase Handler Function The dbase handler function is a user defined function that handles reading of Modbus addresses not assigned in the IEC 61131 1 Dictionary The function can have any name dbaseHandler is used in the description below Syntax include lt ctools h gt BOOLEAN dbaseHandler UINT16 address INT value Description This function is called by the dbase function when one of the following conditions apply e There is no IEC 6
189. Number of characters in version information date field WwW WRITESTATUS WG NONE Bit mask to disable all wake sources WS_REAL_TIME CLOCK Bit mask to enable real time clock as a wake up source WS_INTERUPT_INPUT Bit mask to enable interrupt input as wake up source WS_LED POWER_SWITCH Bit mask to enable LED power switch as wake up source WS_COUNTER_1_OVERFLO Bit mask to enable counter 1 overflow as a WwW wake up source WS_COUNTER_2 OVERFLO Bit mask to enable counter 2 overflow as a WwW wake up source WS_COUNTER_3 OVERFLO Bit mask to enable counter 3 overflow as a WwW wake up source WS_LED POWER_SWITCH Bit mask to enable LED power switch as a wake up source WS_DIN_1_CHANGE Bit mask to enable DIN 1 change of state as a wake up source WS_COMS3_VISION Bit mask to enable the SCADAPack Vision on COM 3 as a wake up source WS_COM3_ DCD Bit mask to enable CDC signal on COM3 as wake up source WS_DINO_ CHANGE Bit mask to enable digital input 0 as wake up source WS _410 ENABLE SWITCH Bit mask to enable the SOLARPack 410 enable switch as wake up source WG ONE SECOND ALARM Bit mask to enable one second alarm as Document Version 1 70 5 23 2012 583 Macro Definitions a ii aepo WS_ALL Bit mask to enable all wake up sources Document Version 1 70 5 23 2012 584 Structures and Types Structures and Types ADDRESS_MODE The ADDRESS_MODE enumerated type describes addressing modes for communication pro
190. Order of Al32 points O LSW first 1 MSW first e AQ16_number is the number of 16 bit analog output points Valid values are 0 to 9999 e A0Q16_startAddress is the DNP address of the first AO16 point e AQ32_number is the number of 32 bit analog output points Valid values are 0 to 9999 e AQ32_startAddress is the DNP address of the first AO32 point e AQ32_wordOrder is the Word Order of AO32 points O LSW first 1 MSW first e AOSF_number is the number of short float Analog Outputs e AOSF_startAddress is the DNP address of first AOSF point Document Version 1 70 5 23 2012 599 Structures and Types dnpConfigurationEx AOSF_wordOrder is the Word Order of AOSF points O LSW first 1 MSW first autoUnsolicitedClass1 enables or disables automatic Unsolicited reporting of Class 1 events holdTimeClass1 is the maximum period to hold Class 1 events before reporting holdCountClass1 is the maximum number of Class 1 events to hold before reporting autoUnsolicitedClass2 enables or disables automatic Unsolicited reporting of Class 2 events holdTimeClass2 is the maximum period to hold Class 2 events before reporting holdCountClass2 is the maximum number of Class 2 events to hold before reporting autoUnsolicitedClass3 enables or disables automatic Unsolicited reporting of Class 3 events holdTimeClass3 is the maximum period to hold Class 3 events before reporting holdCountClass2 is the maximum number of Class
191. P connection in an idle timeout does not return the connection ID to the pool of available connections The connection ID remains allocated to this master session until mTcpMasterClose is called An error code is returned if the specified connectiD is invalid or if a command argument is invalid otherwise MM_SENT is returned If the last command message is still in progress the command status is returned and a new message is not sent The mTcpMasterMessage returns immediately It is the mastering task created in the background that services the IP connection The command status returned by this function is set to MM_SENT if a valid master message was sent Other values returned for the command status are described for the enumeration type MODBUS_CMD_STATUS in the Structures and Types section Use the function mTcpMasterStatus to determine the progress of the Modbus IP command and the slave response The command status will be set to MM_RECEIVED when the response to the message is received Notes Refer to the communication protocol manual for more information The IO_SYSTEM resource needs to be requested before calling this function Example See the Example in the Example Programs chapter under the section Master IP Message Example Document Version 1 70 5 23 2012 441 Function Specifications mTcpMasterOpen Open a Modbus IP Master Connection Syntax include lt ctools h gt BOOLEAN mTcpMasterOpen IP ADDRESS remoteIP IP
192. P_CONNECTION_REQUIRED DNP_MESSAGE_COMPLETE or DNP_MESSAGE_TIMEOUT See the structure definition for the meaning of these events The handler function has no return value By default no connection handler is installed and no special steps are taken when DNP requires a connection receives a message confirmation or a timeout occurs See Also dnpConnectionEvent Document Version 1 70 5 23 2012 187 Function Specifications Example This example shows how a C application can handle the events and inform a logic application of the events The logic application is responsible for making and ending the dial up connection The program uses the following registers e 10001 turns on when a connection is requested by DNP for unsolicited reporting e 10002 turns on when the unsolicited report is complete e 10003 turns on when the unsolicited report is fails e The ladder logic program turns on register 1 when the connection is complete and turns off the register when the connection is broken JP yo Se Rees soe as SSeS ee Ske ee a et dnp c Demonstration program for using the DNP connection handler Copyright 2001 Control Microsystems Inc X ky define CONNECTION REQUIRED 10001 register for signaling connection required define MESSAGE COMPLETE 10002 register for signaling unsolicited message is complete define MESSAGE FAILED 10003 register for signaling unsolicited message failed define CONNE
193. RegisterSocketCB tfRegisterSocketCBParam tfResetConnection tfSendTolnterface tfSetPppPeerlpAddress tfSetTreckOptions tfSocketArrayWalk tfUseDialer tfWrite tfZeroCopyRecv tfZeroCopyRecvFrom tfZeroCopySend tfZeroCopySendTo writev PPP Functions The following C Tools PPP functions are not supported Function pppGetInterfaceHandle pppReadSettings pppReadUserTableEntry pppReadUserTableSize pppWriteSettings pppWriteUserTableEntry pppWriteUserTableSize Document Version 1 70 5 23 2012 679 Porting Existing C Tools Applications Porting SCADAPack C Applications to the SCADAPack 350 and 4203 Porting Existing C Tools Applications Existing SCADAPack C applications are highly compatible with the SCADAPack C Tools However changes are necessary The following guide describes the steps in porting an application Copy SCADAPack C Application Framework Begin by making a copy of the SCADAPack C application framework using the IEC 61131 1 sample application or the Telepace sample application By default the samples are installed at C Program Files Control Microsystems CTools Controller Framework Applications Make a copy of one of the following directories e C Program Files Control Microsystems CTools Controller Framework Applications Telepace e C Program Files Control Microsystems CTools Controller Framework Applications IEC 61131 1 Changes to appstart cpp The new appstart cpp assigns the stack size as
194. S LED POWER SWITCH fputs LED Power Switch r n coml if enabled amp WS COUNTER _1 OVERFLOW fputs Counter 1 Overflow r n coml if enabled amp WS COUNTER_1 OVERFLOW fputs Counter 2 Overflow r n coml if enabled amp WS COUNTER_1 OVERFLOW fputs Counter 3 Overflow r n coml Document Version 1 70 5 23 2012 279 Function Specifications Handler Function User Specified Handler Function The handler function is a user specified function that handles processing of Modbus messages not recognized by the protocol The function can have any name handler is used in the Description below Syntax include lt ctools h gt UINT16 handler UCHAR message UINT16 messageLength UCHAR response UINT16 responseLength 1 Description This function handler is a user defined handler for processing Modbus messages The function is called for each Modbus message with a function code that is not recognized by the standard Modbus protocol The handler function should process the message string and create a response string If the message is not understood one of the error codes should be returned The function has four parameters e The message parameter is a pointer to the first character of the received message The first character of the message is the function code The format of the data after the function code is defined by the function code e The messageLength parameter is the number of c
195. SCADAPack 300 amp 4203 C Tools User and Reference Manual 5 23 2012 Schneider The information provided in this documentation contains general descriptions and or technical characteristics of the performance of the products contained herein This documentation is not intended as a substitute for and is not to be used for determining suitability or reliability of these products for specific user applications It is the duty of any such user or integrator to perform the appropriate and complete risk analysis evaluation and testing of the products with respect to the relevant specific application or use thereof Neither Schneider Electric nor any of its affiliates or subsidiaries shall be responsible or liable for misuse of the information contained herein If you have any suggestions for improvements or amendments or have found errors in this publication please notify us No part of this document may be reproduced in any form or by any means electronic or mechanical including photocopying without express written permission of Schneider Electric All pertinent state regional and local safety regulations must be observed when installing and using this product For reasons of safety and to help ensure compliance with documented system data only the manufacturer should perform repairs to components When devices are used for applications with technical safety requirements the relevant instructions must be followed Failure to use Schne
196. Specifications ledSetDefault Set Default Parameters for LED Power Control Syntax include lt ctools h gt UINT16 ledSetDefault struct ledControl_ tag ledControl Description The ledSetDefault routine sets default parameters for LED power control The controller controls LED power to 5000 I O modules To conserve power the LEDs can be disabled The LED power setting can be changed by the user with the LED POWER switch on the controller The LED power returns to its default state after a user specified time period The edContro structure contains the default values Refer to the Structures and Types section for a Description of the fields in the ledControl_tag structure Valid values for the state field are LED_ON and LED_OFF Valid values for the time field are 1 to 65535 minutes The function returns TRUE if the parameters are valid and false if they are not If either parameter is not valid the default values are not changed The IO_SYSTEM resource needs to be requested before calling this function To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Example include lt ctools h gt int main void struct ledControl_tag ledControl request resource IO SYSTEM Turn LEDS off after 20 minutes ledControl time
197. Store and Forward Translation Configuration Syntax include lt ctools h gt void clearSFTranslationTable void Description The clearSFTranslationTable function clears all entries in the store and forward translation table To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Notes The TeleBUS Protocols User Manual describes store and forward messaging mode The IO_SYSTEM resource needs to be requested before calling this function See Also checkSFTranslationT able Document Version 1 70 5 23 2012 116 Function Specifications clearStatusBit Clear Bits in Controller Status Code Syntax include lt ctools h gt UINT16 clearStatusBit UINT16 bitMask Description The clearStatusBit function clears the bits indicated by bitMask in the controller status code When the status code is non zero the STAT LED blinks a binary sequence corresponding to the code If code is zero the STAT LED turns off The function returns the value of the status register Notes The status output opens if code is non zero Refer to the System Hardware Manual for more information The binary sequence consists of short and long flashes of the error LED A short flash of 1 10th of a second indicates a binary zero A longer flash of appro
198. Structures and Types section for complete information on structures and enumeration types Resource Management The resource management functions arbitrate access to non sharable resources These resources include physical devices such as serial ports and software that is not re entrant Document Version 1 70 5 23 2012 47 Real Time Operating System The RTOS defines nine system resources which are used by components of the I O drivers memory allocation functions and communication protocols An application program may define other resources as required Take care not to duplicate any of the resource numbers declared in ctools h as system resources Resource Management Functions There are three RTOS functions for resource management Refer to the Function Specification section for details on each function listed request_resource Request access to a resource and wait if the resource is not available Doll resource Request access to a resource Continue execution if the resource is not available release_resource Free a resource for use by other tasks 1O_SYSTEM Resource The IO_SYSTEM resource regulates access to functions using the I O system C application programs ladder logic programs communication protocols and background UO operations share the I O system It is imperative the resource is obtained to avoid a conflict as protocols and background operations are interrupt driven Retaining control of the resource for m
199. Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the dbase function The IO_SYSTEM system resource needs to be requested before calling this function See Also readintVariable readRealVariable Example This program displays the contents of the boolean variable named Switch1 include lt ctools h gt int main void BOOLEAN status UCHAR char value request resource IO SYSTEM status readBoolVariable Switchl amp value release resource IO SYSTEM Document Version 1 70 5 23 2012 462 Function Specifications fprintf coml status Su Switchl Sd r n status value Document Version 1 70 5 23 2012 463 Function Specifications readBattery Read Lithium Battery Voltage Syntax include lt ctools h gt INT16 readBattery void Description The readBattery function returns the RAM backup battery voltage in millivolts The range is 0 to 5000 mV A normal reading is about 3600 mV Example include lt ctools h gt if readBattery lt 2500 fprintf coml Battery Voltage is low r n
200. T32 dLogConfig typesOfFields 2 DLV_DOUBLE Document Version 1 70 5 23 2012 135 Function Specifications dLogConfig typesOfFields 3 DLV_FLOAT dLogConfig typesOfFields 4 DLV_FLOAT datalogCreate logID amp dLogConfig else could not delete log else Could not read settings Document Version 1 70 5 23 2012 136 Function Specifications datalogPurge Purge Data Log Function Syntax include lt ctools h gt BOOLEAN datalogPurge UINT16 oof BOOLEAN purgeAll UINT32 sequenceNumber Description This function removes records from a data log The function can remove all the records or a group of records starting with the oldest in the log The function has three parameters og D specifies the data log The valid range is 0 to 15 If purgeAll is TRUE all records are removed otherwise the oldest records are removed sequenceNumber specifies the sequence number of the most recent record to remove All records up to and including this record are removed This parameter is ignored if purgeAll is TRUE The function returns TRUE if the operation succeeds The function returns FALSE if the log ID is invalid if the log has not been created or if the sequence number cannot be found in the log Notes Purging the oldest records in the log is usually done after reading the log The sequence number used is that of the last record read from the log This removes
201. TRIES datalinkTimeout DEFAULT DLINK TIMEOUT operateTimeout configuration configuration DEFAULT OPERATE TIMEOUT applicationConfirm maximumResponse configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration configuration DEFAULT MAX RESP LENGTH applicationRetries applicationTimeout timeSynchronization DI number BI_cosBufferSize BI_soeBufferSiz BO_number CI16 number CI16 bufferSize CI32_ number CI32 bufferSize AI16 number AI16_ reportingMethod AI16 bufferSize AI32_ number AI32_reportingMethod AI32 bufferSize AOQ16 number AOQ32_ number unsolicited holdTime holdCount DI EFAULT_DNP MASTER DEFAULT DNP_ RTU TRUE TRUE DEFAULT APPL RETRIES DEFAULT APPL TIMEOUT TIME SYNC 8 DEFAULT _COS_ BUFF DEFAULT SOE BUFF 8 24 48 T25 24 24 CURRENT_VALUE 24 Lee CURRENT VALUE 12 8 8 TRUE DEFAULT HOLD TIME DEFAULT HOLD COUNT dnpSaveConfiguration configuration Start DNP protocol on com port 2 get_protocol com2
202. TUS e WS success returns write was successful e WS selectFailed returns slave could not be selected e WS_noAcknowledge returns slave failed to acknowledge data Document Version 1 70 5 23 2012 633 Example Programs Example Programs Connecting with a Remote Controller Example The following code shows how to connect to a remote controller using a modem The example uses a US Robotics modem It also demonstrates the use of the modemAbort function in an exit handler include lt ctools h gt include lt string h gt The myshutdown function aborts any active modem connections when the task is ended void myshutdown void modemAbort com1 int main void struct ModemSetup dialSettings reserve id portID enum DialError status enum DialState state struct pconfig portSettings TASKINFO taskStatus Configure serial port 1 portSettings baud BAUD19200 portSettings duplex FULL portSettings parity NONE portSettings data_bits DATA8 portSettings stop bits STOP1 portSettings flow rx RFC_MODBUS_RTU portSettings flow tx TFC_NONE portSettings type RS232 MODEM portSettings timeout 600 request resource IO SYSTEM set _port coml amp portSettings release resource IO SYSTEM Configure US Robotics modem dialSettings port coml dialSettings dialAttempts 3 dialSettings detectTime 60 dialSettings pauseTime 30 dialSetti
203. The dnpSaveCl32Config function sets the configuration of a DNP 32 bit counter input point The function has two parameters the point number and a pointer to a counter input point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetCl32Contfig Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 214 Function Specifications dnpSaveConfiguration Save DNP Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveConfiguration dnpConfiguration pConfiguration 1 Description The dnpSaveConfiguration function sets the DNP configuration The function has one parameter a pointer to a DNP configuration structure The function returns TRUE if the configuration was updated and FALSE if an error occurred No changes are made to any parameters if an error occurs Notes This function needs to be called before enabling DNP This function does not write the configuration for the Unsolicited Back Off Time Use the function dnoSaveUnsolicitedBackoffTime to save the Unsolicited Back Off Time configuration The following parameters cannot be changed if DNP is enabled The function will not make
204. The function has no parameters The function returns the total number of active entries in the list or zero if the list is empty See Also ipReadFriendly PListEntry ipWriteFriendlylPListEntry ipWriteFriendlylPListSize Document Version 1 70 5 23 2012 403 Function Specifications ipWriteFriendlyListControl Enable or disable the friendly IP list Syntax BOOLEAN ipWriteFriendlyListControl BOOLEAN state 1 Description This function enables or disables the friendly IP list When the list is disabled the controller accepts messages from any IP address When the list is enabled only messages from the IP addresses on the list are accepted state specifies if the friendly IP list is enabled or disabled Valid values are TRUE enabled and FALSE disabled If the list is not valid then it can not be enabled The function returns TRUE if command was successful It returns FALSE if it was attempted to enable an empty list or a list with invalid entries See Also ipReadFriendlyListControl Document Version 1 70 5 23 2012 404 Function Specifications ipWriteFriendlyIPListEntry Write one entry in the friendly IP list Syntax BOOLEAN ipWriteFriendlyIPListEntry UINT16 index IP ADDRESS ipAddressStart IP ADDRESS ipAddressEnd i Description This function writes an entry in the Friendly IP List index specifies the location in the list and needs to be less than or equal to the Friendly IP
205. Translation Syntax include lt ctools h gt void getSFTranslation UINT16 index SF TRANSLATION pTranslation Description Instead of using the getSFTranslation function use the getSFTranslationEx function which supports translations with a timeout and authentication The getSFTranslation function copies the entry from the store and forward translation table at index to the structure pointed to by pTranslation If index is invalid a disabled table entry is copied The disabled table entry has both station fields set to 65535 The SF_TRANSLATION structure is described in the Structures and Types section manual Notes The TeleBUS Protocols User Manual describes store and forward messaging mode See Also setSFTranslation clearSFTranslationTable checkSFTranslationTable Document Version 1 70 5 23 2012 268 Function Specifications getSFTranslationEx Read Store and Forward Translation Method 2 Syntax include lt ctools h gt void getSFTranslationEx UINT16 index SF TRANSLATION EX pTranslation Description The getSFTranslationEx function copies the entry from the store and forward translation table at index to the structure pointed to by pTranslation If index is invalid a disabled table entry is copied The disabled table entry has both station fields set to 65535 If the userName parameter is non NULL then the user name used for authentication purposes will be copied into the array pointed t
206. US ASCII settings station 2 settings priority 250 settings SFMessaging FALSE set protocol com2 amp settings Set communication parameters for port 2 portset baud BAUD9600 portset duplex HALF portset parity NONE portset data_bits DATA8 portset stop bits STOP1 portset flow rx RFC_NONE portset flow tx TFC_NONE portset typ RS485 4WIRE portset timeout 600 set _port com2 amp portset release resource IO SYSTEM enable timers used in wait for response runTimers TRUE Main communication loop while TRUE Transfer slave inputs to outputs request_resource IO_ SYSTEM master message com2 2 1 10001 release resource IO SYSTEM wait for response com2 10 17 8J Transfer inputs to slave outputs request resource IO SYSTEM master message com2 15 1 release resource IO SYSTEM wait for response com2 10 1 10009 8 Allow other tasks to execute release processor Master Message Example Using serialModbusMaster This program sends master messages on com2 demonstrating two methods using the function serialModbusMaster SCADAPack 350 C Application Main Program Copyright 2001 2004 Control Microsystems Inc include lt ctools h gt function prototypes Document Version 1 70 5 23 2012 662 Example Programs static void master2 void wa se Se ee ee ge be
207. VE E ENEEK E ENEE EE 105 DINA enre E eee ieee eee 106 Check EOT EE 107 ewe Tu EE 108 checkSF Translation Tabler rreren nieee EEANN E NEEE EEEE HETA 109 ele Le E 110 clearBreakCondition ccccccccccccccccceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeteess 111 CICAL_CVTOMS cccccccccseseseccccceeecaaseeseceeeeeeesasseesecceeeeeeseseassceeeeeseesaaaaeeceeeeeeeeaaaegees 112 Cear oroiocol status 113 ClearLoginCredentials cccccceccccceceeeeeeeeeeeeeccaaeeeeeeeeeseecaaeeeeeeeeseeestaaeeeeees 114 Ceartieoihesionment 115 CearGtTranslaton ale 116 CeartGtatuebn errereen nEaN NA EEKAN EENAA EARRAK EE 117 CIO ANS EE 118 ele 119 configurationRegisterMapping ssssseeessssssssrrssssssrrirrrrttsssrninrnnnsnsstnnnnnnsssnt 120 configurationSetApplication ID ssseeeeeessessssirrtsssssrrirrnrstsssrntrrnnrtnssennnnnnnesnt 121 ee 125 ele 127 ol LE 128 Che ale Jak esst eege eegeggi E ee Re Rs A Ss A ees 129 fotcl Ez lof Ioic Le EE 131 database Add E 132 e Elle Tee EE 133 Elle Tel BEE 135 e Elle Tei re EE 137 e Ee Tel el E 139 atalog Read Staite n a E eta EE EN AEEA 141 datalogobiecordt tze AA 143 datalogSettingS EE 144 Document Version 1 70 5 23 2012 elle e dt 145 ele 146 Dbase Handler Function essssssssssssrsssssssriirrrtsssttrirnntttssttnrnnnnnasstnnnnnnnnennnt 148 Ceallocate emelope A 149 Gelee EE 150 elle et RE 152 leie RTE UE 153 elle Le IO WEE 154 elle e Ee EE 155 Clog R
208. ValuePtr optionLength ProtocolLevel SOL_SOCKET IP_PROTOIP IP_PROTOTCP Sets the maximum TCP segment size sent on the network The TCP_MAXSEG value is the maximum amount of data including TCP options but not the TCP header that can be sent per segment to the peer i e the amount of user data sent per segment is the value given by the TCP_MAXSEG option minus any enabled TCP option for example 12 bytes for a TCP time stamp option The TCP_MAXSEG value can be decreased or increased prior to a connection establishment but it is not recommended to set it to a value higher than the IP MTU minus 40 bytes for example 1460 bytes on Ethernet since this would cause fragmentation of TCP segments Setting the TCP_MAXSEG option will inhibit the automactic computation of that value by the system based on the IP MTU which avoids fragmentation and will also inhibit Path Mtu Discovery After the connection has started this value cannot be changed The TCP_MAXSEG value cannot be set below 64 bytes Default value is IP MTU minus 40 bytes Set this option value to a non zero value to disable the Nagle algorithm that buffers the sent data inside the TCP Useful to allow client s TCP to send small packets as soon as possible like mouse clicks Default 0 The socket descriptor to set the options on The protocol to set the option on See below The name of the option to set See below and above The pointer to a user variable from which the
209. Version 1 70 5 23 2012 78 Overview of Programming Functions DNP Communication Protocol Structures and Types The ctools h file defines the structures DNP Configuration Binary Input Point Binary Output Point Analog Input Point Analog Output Point and Counter Input Point Refer to the C Tools Structures and Types section for complete information on structures and enumeration types DF1 Communication Protocol The TeleBUS DEI protocol supports the DEI Basic Command Set in the Half Duplex and Full Duplex DF1 protocols DF1 Communication Protocol Functions There are several library functions related to DF1 communication protocol Refer to the Function Specification section for details on each function listed getABConfiguration Reads DF1 protocol configuration parameters pollABSlave Requests a response from a slave controller using the half duplex version of the protocol resetAllIABSlaves Clears responses from the response buffers of half duplex slave controllers setABConfiguration Defines DF1 protocol configuration parameters TCP IP Communications TCP IP Functions The SCADAPack 350 and SCADAPack 357 controllers have one 10 100BaseT Ethernet port The ctools h file defines the following TCP IP related functions Refer to the Function Specification section for details on each function listed ethernetGetIP Get the Ethernet controller TCP IP settings ethernetSetIP Set the Ethernet controller TCP IP settings ethe
210. When the handlers are installed calls to the functions dbase setdbase databaseRead and databaseWrite for these Modbus registers will call these handlers This is true as long as the register is not already assigned to an IEC 61131 1 variable Note that these database access functions are used by C applications and by all protocols include lt ctools h gt include lt string h gt include nvMemory h define SAMPLE SIZE 100 define SCAN EVENT NO 0 custom Modbus database structure struct myDatabase BOOLEAN coilDbase SAMPLE SIZE BOOLEAN statusDbase SAMPLE SIZE INT16 inputDbase SAMPLE SIZE INT16 holdingDbase SAMPLE SIZE F define MEM SIZE sizeof struct myDatabase This is the dbase handler Document Version 1 70 5 23 2012 654 Example Programs Se Se et a e ea a ee SS eee Se eee static BOOLEAN dbaseHandler UINT16 address Modbus register address INT16 value pointer to value at address struct myDatabase pMyDatabase pointer to custom database pMyDatabase struct myDatabase pNvMemory gt pAllocatedMem if pMyDatabase NULL database could not be allocated return FALSE if address gt 1000 amp amp address lt 1000 SAMPLE SIZE value pMyDatabase gt coilDbase address 1001 return TRUE
211. XISTS If the log ID is not valid the creation operation fails The function returns DLS_BADID If the configuration is not valid the creation operation fails The function returns DLS_BADCONFIG See Also See example DataLog program in the Example Programs section datalogDelete datalogSettings Example This program creates a data log and writes one record to it include lt ctools h gt Structure used to copy one record into data log struct dataRecord Document Version 1 70 5 23 2012 133 Function Specifications UINT1 INT32 doubl float float be 6 valu valu e valu valu valu int main void el e2 e3 e4 e5 UINT16 logID DATALOG CONFIGURATION dLogConfig log configuration struct dataRecord data record sample Assign a number to the data log logID Fi Loo Loo Loo Loo Loo Loo Loo OO 0 00 10 11 in onfig onfig onfig onfig onfig onfig onfig the log configuration structure records 200 Assign some data for the data data data data data if datalogCreate logID Start writing records in log if datalogWrite logID valuel value2 value3 value4 value5 fields 5 typesOfFields 0 DLV_UINT16 typesOfFields 1 DLV_INT32 typesOfFields 2 DLV_DOUBLE typesOfFields 3 DLV_FLOAT typesOfFields 4 DLV_FLOAT log 100
212. _LEN Maximum length of the phone number string Dial Up Modem Enumeration Types The ctools h file defines the enumerated types DialError and DialState Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Dial up Modem Structures The ctools h file defines the structures ModemInit and ModemSetup Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Serial Communication Protocols The TeleBUS protocols are compatible with the widely used Modbus RTU and ASCII protocols The TeleBUS communication protocols provide a standard communication interface to SCADAPack controllers Additional TeleBUS commands provide remote programming and diagnostics capability The TeleBUS protocols provide access to the I O database in the controller The I O database contains user assigned registers and general purpose registers Assigned registers map directly to the I O hardware or system parameter in the controller General purpose registers can be used by ladder logic and C application programs to store processed information and to receive information from a remote device Document Version 1 70 5 23 2012 73 Overview of Programming Functions The TeleBUS protocols operate on a wide variety of serial data links These include RS 232 serial ports RS 485 serial ports radios leased line modems and dial up modems The protocols are g
213. able readRealVariable Example This program displays the contents of the timer variable named Time1 include lt ctools h gt int main void BOOLEAN status UINT32 value request resource IO SYSTEM status readTimerVariable Timel amp value Document Version 1 70 5 23 2012 474 Function Specifications release resource IO SYSTEM fprintf coml status Su Timel lu r n status value Document Version 1 70 5 23 2012 475 Function Specifications receive_message Receive a Message Syntax include lt ctools h gt nvelope receive message void Description The receive_message function reads the next available envelope from the message queue for the current task If the queue is empty the task is blocked until a message is sent to it The receive_message function returns a pointer to an envelope structure Notes Refer to the Real Time Operating System section for more information on messages See Also send_message Example This task waits for messages then prints their contents The envelopes received are returned to the operating system include lt ctools h gt void show_message void envelope msg while TRUE msg receive message fprintf coml Message data ld r n msg gt data deallocate_ envelope msg Document Version 1 70 5 23 2012 476 Function Specifications recv Syntax in
214. ables Otherwise FALSE is returned Notes This function is currently only supported on the SCADAPack 350 and 4203 Document Version 1 70 5 23 2012 253 Function Specifications getlOErrorIndication Get I O Module Error Indication Syntax include lt ctools h gt BOOLEAN getlOErrorIndication void Description The getlOErrorindication function returns the state of the I O module error indication TRUE is returned if the I O module communication status is currently reported in the controller status register and Status LED FALSE is returned if the IO module communication status is not reported Notes Refer to the 5203 4 System Manual SCADAPack 32 System Manual or the SCADAPack 350 System Manual for further information on the Status LED and Status Output See Also setlOErrorIndication Document Version 1 70 5 23 2012 254 Function Specifications getOutputsiInStopMode Get Outputs In Stop Mode Telepace firmware only Syntax include lt ctools h gt void getOutputsInStopMode BOOLEAN holdDoutsOnStop BOOLEAN holdAoutsOnStop 1 Description The getOutputsInStopMode function copies the values of the output control flags into the integers pointed to by douts inStopMode and aoutsinStopMode If the value pointed to by holdDoutsOnStop is TRUE then digital outputs are held at their last state when the Ladder Logic program is stopped If the value pointed to by holdDoutsOnStop
215. ack 350 4203 controllers Event Numbers for SCADAPack C Applications The SCADAPack 350 4203 support up to 32 separate user loaded C Applications Event numbers 0 to 31 were made available to the SCADAPack 32 C application This same event number range need to be shared on the SCADAPack 350 4203 among the user loaded C Applications The Realflo C Application uses events 20 21 or 22 These events may not be used by other C Applications when the Realflo C Application is loaded in the SCADAPack 350 4203 Stack used by fprintf Function Tasks that call the function fprintf require at least 5 stack blocks This function required only 4 stack blocks when used in SCADAPack 32 C applications As a general rule add 1 stack block to the amount used in a SCADAPack 32 C application Document Version 1 70 5 23 2012 675 Porting Existing C Tools Applications Macro stdout is Disabled The macro stdout is disabled in the SCADAPack C Tools Instead use the serial port macros com1 com2 or com3 This means that the following functions that use stdout do not work printf putc getc Use the replacement functions listed below Task Creation Function The task priorities have changed with the SCADAPack 350 and 4203 There are now 255 priority levels and the highest priority task has a priority of 0 Existing calls to create_task will need to be modified to account for a lower number being a higher priority The tab
216. acter handler install handler coml informOfCharacterArrival Calculate the character size 1 start bit 8 data bits no parity bits 1 stop bit characterSize 1 8 1 Delay for 5 seconds sleep processor 5000 Document Version 1 70 5 23 2012 555 Function Specifications Determine the number of timeout intervals needed The multiplication by 8 is due to 8 character times to delay The division by 4 is because every value specifies 4 bit times timeoutInterval characterSize 8 4 Set COM1 to signal character arrival after 8 character times of silence sysSerialSetRxTimeout COM1 INDEX timeoutInterval while TRUE Wait for the serial callback handler to report a message has been received wait event COM RCVR Reset the data to process flag so that we ll be notified when the next message arrives dataToProcess COM1 INDEX FALSE Read out data and process message her See Also install_ handler Document Version 1 70 5 23 2012 556 Function Specifications unregisterBulkDevOperation Un register bulk device operation Syntax include lt ctools h gt BOOLEAN unregisterBulkDevOperation char extDriveName Description The unregisterBulkDevOperation function un registers an operation on a bulk memory device It is used in conjunction with the registerBulkDevOperation to ensure that intern
217. ailable PM CPU FULL The CPU is set to run at full speed PM_CPU_REDUCED The CPU is set to run at a reduced speed PM _CPU_SLEEP The CPU is set to sleep mode PM_NO_CHANGE TRUE is returned if the requested change was made otherwise FALSE is returned The application program may view the current power mode with the getPowerMode function See Also getPowerMode setWakeSource getWakeSource Document Version 1 70 5 23 2012 524 Function Specifications setProgramStatus Set Program Status Flag Syntax include lt ctools h gt void setProgramStatus FUNCPTR entryPoint UINT16 status Description The setProgramStatus function sets the application program status flag The status flag is set to NEW_PROGRAM when a cold boot of the controller is performed or a program is downloaded to the controller from the program loader The parameter entryPoint should always be set to the function main Notes There are three pre defined values for the flag However the application program may make whatever use of the flag it sees fit NEW_PROGRAM indicates the program is newly loaded PROGRAM_EXECUTED indicates the program has been executed PROGRAM_NOT_LOADED indicates that the requested program is not loaded See Also getProgramStatus Example See Get Program Status Example Document Version 1 70 5 23 2012 525 Function Specifications set_protocol Set Communication Protocol Configuration Syntax includ
218. al function Document Version 1 70 5 23 2012 563 Function Specifications writeBoolVariable Write to IEC 61131 1 Boolean Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN writeBoolVariable UCHAR varName UCHAR value Description This function writes to the specified boolean variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the specified value is written to the variable If the variable is not found or if the IEC 61131 1 Symbols Status is invalid nothing is done and FALSE is returned The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum TRUE is written when value is any non zero value FALSE is written when value is 0 Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the setdbase function The
219. al resources used for the bulk device are correctly released if the device is un mounted in the middle of an operation Parameters extDriveName_ The mounted bulk device drive name typically bd0 Returns TRUE The un register was successful FALSE The drive name was invalid Notes The registerBulkDevOperation and unregisterBulkDevOperation should only be used with a dynamically mounted bulk device such as a USB memory stick The unregisterBulkDevOperation needs to be called with the same device drive name as the registerBulkDevOperation See Also registerBulkDevOperation Example include lt ctools h gt int main void if registerBulkDevOperation bd0 FALSE printf registerBulkDevOperation bd0 failed r n Copy d0 logs logi bd0 logs log1 if unregisterBulkDevOperation bd0 FALSE printf unregisterBulkDevOperation bd0 failed r n Document Version 1 70 5 23 2012 557 Function Specifications Document Version 1 70 5 23 2012 558 Function Specifications wait_event Wait for an Event Syntax include lt ctools h gt void wait event UINT32 event Description The wait_event function tests if an event has occurred If the event has occurred the event counter is decrements and the function returns If the event has not occurred the task is blocked until it does occur Notes Refer to the Real Time Oper
220. alogInputShortFloat e modbusAddress is the address of the Modbus register number associated with the point e eventClass is the reporting class for the object It may be set to CLASS_1 CLASS_2 or CLASS_3 e deadband is the amount by which the analog input value needs to change before an event will be reported for the point The dnpAnalogOutput type describes a DNP analog output point This type is used for both 16 bit and 32 bit points typedef struct dnpAnalogOutput_type UINT16 modbusAddress dnpAnalogOutput e modbusAddress is the address of the Modbus register associated with the point The dnpBinaryInput type describes a DNP binary input point typedef struct dnpBinaryInput_type UINT16 modbusAddress UCHAR class dnpBinaryInput e modbusAddress is the address of the Modbus register associated with the point e class is the reporting class for the object It may be set to CLASS_1 CLASS_2 or CLASS_3 The dnpBinarylnputEx type describes an extended DNP Binary Input point typedef struct dnpBinaryInputEx type UINT16 modbusAddress Document Version 1 70 5 23 2012 594 Structures and Types dnpBinaryOutput UCHAR eventClass UCHAR debounce dnpBinarylInputEx modbusAddress is the address of the Modbus register associated with the point class is the reporting class for the object It may be set to CLASS _1 CLASS_2 or CLASS_3 debounceTime is the debounce time for thebinary input
221. ameter Description A data log has to be created before any client can log data records The configuration structure contains a data log name It is a string which is used to build the log file names Each data log name has to be unique a data log creation will fail if one already exists with the same name A data log name can also contain a path Therefore it is possible to have log files with the same prefix naming but in different directories e g DIR1 LOG1 and DIR2 LOG1 The Document Version 1 70 5 23 2012 150 Function Specifications relative data log name will be combined with the drive name depending on the configuration The dlogCreate call creates a data log instance The data log specific buffer configuration and run time data are allocated in dynamic non volatile memory Data log files are not created these are created as needed by the data log server If dlogCreate is called for an existing data log the configuration parameters are compared If they are the same the function returns a valid dlogID with a warning return value DLOGS_EXISTS If they are different the function returns with the error DLOGS_DIFFERENT Data Log data is stored in non volatile memory If this memory cannot be allocated dlogCreate returns DLOGS_NOMEMORY dlogCreate returns in an output parameter a data log ID which is used for further operations on the data log A newly created data log won t reuse a recently deleted
222. ameter howToShutdown Parameters socketDescriptor The socket to shutdown howToShutdown Direction 0 Read 1 Write 2 Both Returns 0 Success 1 An error occurred shutdown will fail if EBADF The socket descriptor is invalid EINVAL One of the parameters is invalid ENOPROTOOPT The option is unknown at the level indicated Document Version 1 70 5 23 2012 544 Function Specifications signal_event Signal Occurrence of Event Syntax include lt ctools h gt void signal event UINT32 event number Description The signal_event function signals that the event_number event has occurred If there are tasks waiting for the event the highest priority task is made ready to execute Otherwise the event flag is incremented Up to 32767 occurrences of an event will be recorded The current task is blocked if there is a higher priority task waiting for the event Notes Refer to the Real Time Operating System section for more information on events Valid events are numbered 0 to RTOS_EVENTS 1 Any events defined in ctools h are not valid events for use in an application program This function can be called from application and interrupt code See Also poll_ event Example This program creates a task to wait for an event then signals the event include lt ctools h gt void taskl void while TRUE wait event 20 fprintf com1 Event 20 occurred r n int main void UINT
223. aming based on the receive line being idle for a fixed minimum time between messages The Example below shows a simple method using the sysSerialSetRxTimeout function to control when serial data is reported Example This program specifies a timeout of 8 character times on com 1 five seconds after the program starts assuming that the port is setup for 8 N 1 operation include lt ctools h gt define COM1 INDEX 0 BOOLEAN dataToProcess 3 FALSE FALSE FALSE BOOLEAN informOfCharacterArrival int arg int c BOOLEAN retval UINT32 previousIntMask switch arg case 0 case 1 case 2 Notify of the arrival if dataToProcess arg FALSE Document Version 1 70 5 23 2012 554 Function Specifications switch arg case 0 interrupt signal event COM1 RCVR break case 1 interrupt signal event COM2 RCVR break case 2 interrupt signal event COM3 RCVR break default Do nothing this case should be impossible to each break Prevent notifications from being generated until the next level has looked at the data dataToProcess arg TRUE We handled the character so return FALSE retval TRUE break default We didn t handle the character so return TRUE retval TRUE break return retval int main void UINT32 characterSize UCHAR timeoutInterval install the serial char
224. amp io_status if ioStatus MT_SP2Inputs status FALSE else if status print data when coil register 100 IO SYSTEM request resourc dbase MODBUS 100 release_resourc io_status commStatus FALSE is selected IO_ SYSTEM if printNow if done fprintf coml status u Dins 0 to 7 EN Ain 4 d r n status dinData 0 ainData 4 done TRUE else done FALSE release processor release processor to other priority 1 tasks Document Version 1 70 5 23 2012 361 Function Specifications ioReadSP2Outputs Read SCADAPack 350 Outputs Syntax include lt ctools h gt BOOLEAN ioReadSP20utputs UCHAR amp doutData 2 INT16 amp aoutData 2 Description This function reads buffered data from the digital and analog outputs of a SCADAPack 350 I O module Buffered data are written using the ioWriteSP2Outputs function doutData is a reference to an array of two UCHAR variables Digital data for the 10 outputs are written to this array One bit in the array represents each output point aoutData is a reference to an array of two INT16 variables Analog data for the two analog outputs are written to this array The function returns TRUE See Also ioReadSP2Inputs ioWriteSP2Outputs Example This program reads output data from the I O table for the SCADAPack 350 digital outputs and analog outp
225. and you want to interrupt with a C keystroke at the socket level you want to be able to send the C flagged as special data also called out of band data You also want the TCP protocol to let the peer or remote TCP know as soon as possible that a special character is coming and you want the peer or remote TCP to notify the peer or remote application as soon as possible At the TCP level this mechanism is called TCP urgent data At the socket level the mechanism is called out of band data Out of band data generated by the socket layer is implemented at the TCP layer with the urgent data mechanism The user application can send one or several out of band data bytes With TCP you cannot send the out of band data ahead of the data that has already been buffered in the TCP send buffer but you can let the other side know with the urgent flag i e the term urgent data that out of band Document Version 1 70 5 23 2012 499 Function Specifications data is coming and you can let the peer TCP know the offset of the current data to the last byte of out of band data So with TCP the out of band data byte s are not sent ahead of the data stream but the TCP protocol can notify the remote TCP ahead of time that some out of band data byte s exist What TCP does is mark the byte stream where urgent data ends and set the Urgent flag bit in the TCP header flag field as long as it is sending data before or up to the last byte of out of
226. andler Configures the connection handler for DNP dnpMasterClassPoll Sends a Class Poll message in DNP to request the specified data classes from a DNP slave DnpMasterClockSync sends a Clock Synchronization message in DNP toa DNP slave dnpPortStatus Returns the DNP message statistics for the specified communication port dnpReadAddressMappingTableEntry Reads an entry from the DNP address mapping table dnpReadAddressMappingTableSize Reads the total number of entries in the DNP address mapping table dnpReadMasterPollTableEntry Reads an entry from the DNP master poll table dnpReadMasterPollTableEntryEx Reads an extended entry from the DNP master poll table dnpReadPMasterPollTableSize Reads the total number of entries in the DNP master poll table dnpReadRoutingTableEntry Reads an entry from the routing table dnpReadRoutingTableEntryEx Reads an extended entry from the DNP routing table dnpReadRoutingTableEntry_DialString Reads a primary and secondary dial string from an entry in the DNP routing table dnpReadRoutingTableSize Reads the total number of entries in the routing table dnpSaveAl16Config Sets the configuration of a DNP 16 bit analog input point Document Version 1 70 5 23 2012 77 Overview of Programming Functions dnpSaveAl32Config Sets the configuration of a DNP 32 bit analog input point dnpSaveAlSFConfig Sets the configuration of a DNP 32 bit short floating analog input point dnpSa
227. angeEvent Generates a change event for the DNP point dnpGenerateEventLogGenerates a change event for the DNP point dnpGetAl16Config Reads the configuration of a DNP 16 bit analog input point dnpGetAl32Config Reads the configuration of a DNP 32 bit analog input point dnpGetAlSFConfig Reads the configuration of a DNP 32 bit short floating analog input point dnpGetAO16Config Reads the configuration of a DNP 16 bit analog output point dnpGetAO32Config Reads the configuration of a DNP 32 bit analog output point dnpGetAOSFConfig Sets the configuration of a DNP 32 bit short floating analog output point dnpGetCl16Config Reads the configuration of a DNP 16 bit counter input point dnpGetCl32Config Reads the configuration of a DNP 32 bit counter input point Document Version 1 70 5 23 2012 76 Overview of Programming Functions dnpGetBiConfig Reads the configuration of a DNP binary input point dnpGetBIConfigEx Reads the configuration of an extended DNP Binary Input point dnpGetBOConfig Reads the configuration of a DNP binary output point dnpGetCl16Config Reads the configuration of a DNP 16 bit counter input point dnpGetCl32Config Reads the configuration of a DNP 32 bit counter input point dnpGetConfiguration Reads the DNP protocol configuration dnpGetConfigurationEx Reads the extended DNP configuration parameters dnpGetRuntimeStatus Reads the current status of DNP change event buffers dnpinstallConnectionH
228. any Modbus IP protocol on the specified interface typedef struct st_MTcpIfSettings UINT16 station UCHAR addrMode BOOLEAN sfMessaging MTCP_IF SETTINGS e station is the Modbus station address for the specified communication interface Valid values are 1 to 255 in standard Modbus 1 to 65534 in extended Modbus Default value is 1 e addrMode is the addressing mode AM standard or AM_extended Default value is AM standard e SFMessaging is the enable Store and Forward messaging control flag Enable store and forward when set to TRUE Disable store and forward when set to FALSE Default value is FALSE MTCP_IF_SETTINGS EX The Modbus IP Interface Extended Settings structure defines the interface settings when using any Modbus IP protocol on the specified interface This structure includes Enron Modbus support typedef struct st _MTcpIfSettingsEx type UINT16 station UCHAR addrMode BOOLEAN sfMessaging BOOLEAN enronEnabled UINT16 enronStation MTCP_IF SETTINGS EX e station is the Modbus station address for the specified communication interface Valid values are 1 to 255 in standard Modbus 1 to 65534 in extended Modbus Default value is 1 e addrMode is the addressing mode AM standard or AM_extended Default value is AM standard e SFMessaging is the enable Store and Forward messaging control flag Enable store and forward when set to TRUE Disable store and forward when
229. ar tenner 393 JOW NLC DOULS EE 394 EN DIE Diol it ea Tr T T TTN ETE TEE E TT cree 395 IEN OESCH 396 IPFindFriendlylIPACCress cccccesessceceeeeseeceeeeseeceneeseeneeeeenenseeseneeanenensneneneess 398 Det onpechonfzumm am 399 ipGetinterlacel pes nies hae ee eee een 400 ipReadFriendly EistControl ec vecnenea vein tna nyt evens 401 Document Version 1 70 5 23 2012 IpDieadFrendlvlPt jett 402 ipReadFriendlylPListSizes annaia aa 403 ipWriteFriendlyListControl 0 0 ceeeecceeeeeeeeceeeeseeceeeeeeeneeeeesenseeseneeaeesensanaeeeees 404 IpVWrtetrtendlvlPl ett mir 405 ipWriteFriendly PLIStSiZe anaana aa a 406 elteren ee ANA a aa 407 Ielwen A AE ATT ERREENKTEEEEgeE e 408 Jeder wiet es detstivetesdesstasdinetea aea am Da aaa bane hae anaba deh kA EE dE 409 Ee EIERE 410 EE 411 Master MeS dG E EN 412 MEMO POO USAGE fei cies NEE EOE OEE EE EEE EEEE EEEE 414 UE ue Ted lee EE 415 MOGDUSEXCE PONS tats vcci vs sessesseeeseetensteneseueyenvtes cheng yeeneneteevevevgyeeneneteneevereyass 416 ModbusSlavel RE 417 Uelet el e 418 MOGEMADOMAI oie chen steveesvetenveesetvnetenetenvbensteuntenvteevbenstysetinstuevevasteeeninetenvevereyayl 419 MODEM Dial iiss c Benches EEEE E EEEE EEEE 421 aleto Saal DIEU male ET 423 MOdeEM DialStatus s vecccvisccccsssseesevseecstenseepesesszessteaesssneesgaenstegsbssseesvanssseteeeapeeeese 424 FOGGIA LA i Aaa T AA A EEEE EEEE ET 425 paleo ciani LAlid alate PAE E E E E ETS 427 MOCeMINItStatus A 428
230. ar to the communication domain in which communication is to take place If the caller specifies a protocol then it will be packaged into a socket level option request and sent to the underlying protocol layers Sockets of type SOCK_STREAM are full duplex byte streams A stream socket needs to be in a connected state before any data may be sent or received on it A connection to another socket is created with connect on the client side On the server side the server needs to call listen and then accept Once connected data may be transferred using recv and send calls or some variant of the send and recv calls When a session has been completed a close of the socket should be performed The communications protocols used to implement a Document Version 1 70 5 23 2012 549 Function Specifications SOCK_STREAM ensure that data is not lost or duplicated If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time then the connection is considered broken and calls will indicate an error with 1 return value and with ETIMEDOUT as the specific socket error The TCP protocols optionally keep sockets warm by forcing transmissions roughly every two hours in the absence of other activity An error is then indicated if no response can be elicited on an otherwise idle connection for an extended period for instance 5 minutes SOCK_DGRAM or SOCK_RAW sockets allow da
231. ariable read a timer variable reset the clock alarm set the system clock set the clock alarm set a database register set the forcing flag set the serial port set the protocol for an interface set the protocol settings setProtocolSettingsEx set the protocol settings setSFTranslation setSFTranslationEx writeBoolVariable writelntVariable writeRealVariable writeMsgVariable writeTimerVariable DYNAMIC_MEMORY Resource configure Store and Forward translation configure Store and Forward translation write a Boolean variable write an Integer variable write a Real variable write a Message variable write a Timer variable The DYNAMIC_MEMORY resource regulates access to memory allocation functions These functions allocate memory from the system heap The heap is shared amongst tasks The allocation functions are non reentrant The DYNAMIC_MEMORY resource needs to be obtained before using any of the following functions Document Version 1 70 5 23 2012 49 Real Time Operating System calloc allocates data space dynamically free frees dynamically allocated memory malloc allocates data space dynamically realloc changes the size of dynamically allocated space Inter task Communication The inter task communication functions pass information between tasks These functions can be used for data exchange and task synchronization Messages are queued by the RTOS until the receiving task is ready to process the data
232. ariable The input filter selection is written to this variable e 0 3Hz e 1 6Hz e 2 11 Hz e 3 30Hz scanFrequency is a reference to a UINT16 variable The scan frequency selection is written to this variable e 0 60Hz Document Version 1 70 5 23 2012 340 Function Specifications e 1 50 Hz outputType is a reference to a UINT16 variable The analog output type is written to this variable D 0to20mA e 1 4to 20 mA The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5606Inputs ioWrite5606Outputs Example This program reads output data from the I O table for the 5606 digital outputs and analog outputs at address 5 include lt ctools h gt int main void UCHAR doutData 2 INT16 aoutData 2 UINT16 inputType 8 UINT16 inputFilter UINT16 scanFrequency UINT16 outputType BOOLEAN status BOOLEAN done main loop while TRUE read output data from I O table status ioRead56 060utputs 5 doutData aoutData inputType inputFilter scanFrequency outputType print data if done fprintf coml status u Douts 0 to 7 X Aout 0 Sd r n status doutData 0 aoutData 0 done TRUI Fl release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 341 Function Specifications ioRead5607Inputs Read 5607 Inputs Syntax include l
233. arting port number to IPPORT_RESERVED 1 IPPORT_RESERVED is defined as 1024 If the bind fails because that port is already used then rresvport decrements the port number and tries again If it finally reaches IPPORT_RESERVEDSTART defined as 600 and finds it already in use it returns 1 and set the socket error to EAGAIN If this function successfully binds to a reserved port number it returns the socket descriptor to the user and stores the reserved port that the socket is bound to in the integer cell pointed to by portToReservePtr Parameters portToReservePtr Pointer to the port number to reserve and to the port number reserved on success Returns gt 0 Valid socket descriptor 1 An error occurred If an error occurred the socket error can be retrieved by calling getErrorCode socketDescriptor rresvport will fail if EAGAIN The TCP IP stack could not find any port number available between IPPORT_RESERVEDSTART and the port number to reserve EINVAL Bad parameter pointer is null or port number to reserve is less than IPPORT_RESERVEDSTART 600 Document Version 1 70 5 23 2012 491 Function Specifications runBackgroundlO Run Background I O Task Syntax include lt ctools h gt void runBackgroundIO BOOLEAN state Description The runBackgroundlO function is used to start or stop the Background I O task This task provides dialup support and controls the LED Power pushbutton Calling the
234. assigned to the specified Modbus address The function has two parameters e The address parameter is the Modbus address to be written e The value parameter is the integer value to write to the Modbus address If the address is to be handled the handler function needs to return TRUE and write value to the current value at the Modbus address If the address is not to be handled the function needs to return FALSE and do nothing Notes The IO_SYSTEM resource must be requested before calling setdbase which calls this handler Requesting the IO_SYSTEM resource provides that only one task may call the handler at a time Therefore the function does not have to be re entrant An array may be defined to store the current values for all Modbus addresses handled by this function See the section Data Storage if a non initialized data array is required See Also installSetdbaseHandler Document Version 1 70 5 23 2012 514 Function Specifications setDTR Control RS232 Port DTR Signal Syntax include lt ctools h gt void setDTR FILE stream UINT16 state Description The setDTR function sets the status of the DTR signal line for the communication port specified by port When state is SIGNAL_ON the DTR line is asserted When state is SIGNAL_OFF the DTR line is de asserted Notes The DTR line follows the normal RS232 voltage levels for asserted and de asserted states This function is only useful on RS232 ports
235. ated Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 169 Function Specifications dnpGetAl32Config Get DNP 32 bit Analog Input Configuration Syntax include lt ctools h gt BOOLEAN dnpGetAI32Config UINT32 point dnpAnalogInput pAnalogInput Description The dnpGetAl32Config function reads the configuration of a DNP 32 bit analog input point The function has two parameters the point number and a pointer to an analog input point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveAl32Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 170 Function Specifications dnpGetAlSFConfig Get Short Floating Point Analog Input Configuration Syntax include lt ctools h gt BOOLEAN dnpGetAISFConfig UINT16 point dnpAnalogInput pAnalogInput Description The dnpGetAlSFConfig function reads the configuration of a DNP short floating point analog input point The function has two parameters the point number
236. ates a potentially hazardous situation which if not avoided can result in equipment damage PLEASE NOTE Electrical equipment should be installed operated serviced and maintained only by qualified personnel No responsibility is assumed by Schneider Electric for any consequences arising out of the use of this material Document Version 1 70 5 23 2012 15 A qualified person is one who has skills and knowledge related to the construction and operation of electrical equipment and the installation and has received safety training to recognize and avoid the hazards involved BEFORE YOU BEGIN Do not use this product on machinery lacking effective point of operation guarding Lack of effective point of operation guarding on a machine can result in serious injury to the operator of that machine A CAUTION UNINTENDED EQUIPMENT OPERATION e Verify that all installation and set up procedures have been completed e Before operational tests are performed remove all blocks or other temporary holding means used for shipment from all component devices e Remove tools meters and debris from equipment Failure to follow these instructions can result in death serious injury or equipment damage Follow all start up tests recommended in the equipment documentation Store all equipment documentation for future references Software testing must be done in both simulated and real environments Verify that the
237. ating System section for more information on events Valid events are numbered 0 to RTOS_EVENTS 1 Any events defined in primitiv h are not valid events for use in an application program Example See the Example for the signal_event function Document Version 1 70 5 23 2012 559 Function Specifications wd_auto Automatic Watchdog Timer Mode Syntax include lt ctools h gt void wd auto void Description The wd_auto function gives control of the watchdog timer to the operating system The timer is automatically updated by the system Notes Refer to the Functions Overview section for more information Example See the Example for the wd_manual function Document Version 1 70 5 23 2012 560 Function Specifications wd_enabled Enable Watchdog Syntax include lt ctools h gt void wd_enabled BOOLEAN state Description The function wd_enabled enables or disables the controller watchdog This function should only be needed in the context of the startup function appstart where it is called only when a debug build is made of the application By default a Release build of the application enables the watchdog and a Debug build of the application disables the watchdog The watchdog needs to be disabled in order to debug an application using the source level debugging e g stepping setting breakpoints tools provided by the Hitachi HDI and Emulator Calling the function with state set
238. ating in such a fashion the watchdog timer detects any hardware or firmware problems Document Version 1 70 5 23 2012 69 Overview of Programming Functions The watchdog timer can detect failure of an application program The program takes control of the timer and resets it regularly If unexpected operation of the program occurs the reset pulses cease and the watchdog timer resets the CPU The program restarts from the beginning There are three library functions related to the watchdog timer Refer to the Function Specification section for details on each function listed wd_auto Gives control of the watchdog timer to the operating system default wd_manual Gives control of the watchdog timer to an application program wd_pulse Generates a watchdog reset pulse A watchdog reset pulse needs to be generated at least every 500 ms The CPU resets and program execution starts from the beginning of the program if the watchdog timer is not reset Watchdog Timer Program Example The following program segment shows how the watchdog timer could be used to detect the failure of a section of a program wd manual take control of watchdog timer do program code wd pulse reset the watchdog timer while condition wd_auto return control to OS Pass control of the watchdog timer back to the operating system before stopping a program or switching to another task that expects the operating syst
239. ation appears in Modbus registers if the register mapping is enabled applicationType specifies the type of application It is one of DCAT_LOGIC1 DCAT_LOGIC2 or DCAT_C e DCAT_LOGIC1 Device configuration application type is the first logic application e DCAT_LOGIC2 Device configuration application type is the second logic application e DCAT_C Device configuration application type is a C application If DCAT_C is used the application ID is added to the table of C applications The applications don t appear in any fixed order in the C application table action specifies if the ID is to be added or removed Valid values are DCA_ADD and DCA_REMOVE e DCA_ADD attempting to add a duplicate value matching companyID application and version will result in only one entry in the table The function will return TRUE indicating the data is in the table e DCA REMOVE For logic applications the ID will be removed unconditionally For C applications the ID will be removed if it is found in the table matching companyID application and version companyID specifies your company Contact Control Microsystems to obtain a company ID 0 indicates an unused entry application specifies your application Valid values are 0 to 65535 You need to maintain unique values for your company version is the version of your application in the format major 100 minor Valid values are 0 to 65535 The function returns TRUE if the action
240. ation if the C application turns the RUN LED to OFF a conflict occurs and the RUN LED will blink OFF and ON Example include lt ctools h gt int main void runLed LED ON program is running the rest of the code Document Version 1 70 5 23 2012 494 Function Specifications runMasterlpStartTask Run TCP IP Master Message Support Task Syntax include lt ctools h gt void runMasterIpStartTask BOOLEAN state Description The runMasterlpStartTask function is used to start or stop the TCP IP master message support task This task needs to be running to allow master messaging over a TCP IP network using the functions in the mTcpMaster group Calling the function with the argument state set to FALSE stops the task Calling the function with state set to TRUE starts the task This function should only be needed in the context of the startup function appstart See Also mTcpMasterMessage Document Version 1 70 5 23 2012 495 Function Specifications runTarget Start the Run Time Engine Syntax include lt ctools h gt void runTarget BOOLEAN state Description The runTarget function is used to start or stop the run time engine task For Telepace firmware this is the Ladder Logic run time engine For IEC 61131 1 firmware this is the IEC 61131 1 IEC 1131 run time engine Calling the function with the argument state set to FALSE stops the run time engine task Cal
241. ations wait event MY_EVENT check status of last scan if io0Status MT 4203DSOutputs insert code to handle else if io status commStatus insert code to handle release processor for 100ms sleep processor 100 0 amp io status the failure here the failure here Document Version 1 70 5 23 2012 374 Function Specifications ioWrite52100utputs Write SCADAPack 330 controller board outputs Syntax include lt ctools h gt BOOLEAN ioWrite52100ututs UCHAR amp doutData 1 Description This function writes buffered data to the digital outputs of a SCADAPack 330 controller board Data are written to the module when an I O request for the module is processed doutData is a reference to a variable holding the digital output values e Bit 0 of this variable is written to the USB LED control e Bit 1 of this variable is written to the com3 HMI power control e Bits 2 to 7 are not used The function returns TRUE as no I O errors are possible See Also ioRead52100utputs Example This Example turns on the USB STAT LED include lt ctools h gt include nvMemory h define MY EVENT 1 void main void UCHAR doutData 1 IO STATUS Lo status BOOLEAN status main loop while TRUE write data to output tables for next scan doutData 0 0x01 status ioWrite52100utputs doutData 0 add mod
242. ations modbusSlavelD Set Response to Protocol Command Syntax include lt ctools h gt void modbusSlaveID UCHAR string UINT16 length Description The modbusSlavelD function is used in conjunction with the Modbus compatible communication protocol It sets the result returned in response to the Report Slave ID command This command is provided for compatibility with some Modbus protocol drivers for host computers string points to a string of at least length characters The contents of the string are determined by the requirements of the host computer The string is not NULL terminated and may contain multiple NULL characters The length specifies how many characters are returned by the protocol command length must be in the range 1 to REPORT_SLAVE_ID_SIZE If length is too large only the first REPORT_SLAVE_ID_SIZE characters of the string will be sent in response to the command Notes The specified result will be sent each time that the protocol command is received until a new result is specified The function copies the data pointed to by string string may be modified after the function is called The result is cleared when the controller is reset The application program needs to initialize the salve ID string each time it is run Document Version 1 70 5 23 2012 417 Function Specifications modemAbort Unconditionally Terminate Dial up Connection Syntax include lt ctools h gt void modemAbort FI
243. ause allows the external modem time to hang up If a communication protocol is active on the serial port when a connection is initiated the protocol will be disabled until the connection is made then re enabled This allows the controller to communicate with the external modem on the port The protocol settings will also be restored when a connection is terminated with the modemDialEnd function If amodemlInit function or an incoming call is active on the port the modemDial function cannot access the port and will return an error code of DE_NotInControl If communication stops for more than five minutes then outgoing call requests are allowed to end the incoming call This prevents the modem or the calling application from permanently disabling outgoing calls The reservation identifier is valid until the call is terminated and another modem function or an incoming call takes control of the port Document Version 1 70 5 23 2012 421 Function Specifications To optimize performance minimize the length of messages on com3 Examples of recommended uses for com3 are for local operator display terminals and for programming and diagnostics using the IEC 61131 1 program Do not call this function in a task exit handler Example Refer to the Examples in the Connecting with a Remote Controller Example section Document Version 1 70 5 23 2012 422 Function Specifications modemDialEnd Terminate Dial up Connection Sy
244. ax include lt ctools h gt BOOLEAN mIcpSetProtocol IP_PROTOCOL TYPE type IP PROTOCOL SETTINGS pSettings Description The mTcpSetProtocol function is used to configure settings for a specific Modbus IP protocol The protocol type argument may be set to any of the following IPP_ModbusTcp IPP_ModbusRtuOverUdp IPP_ModbusAsciiOverUdp IPP_DnpOverTcp or IPP_DnpOverUdp If this function is used to change the port number then the server task for the selected protocol is ended and re started with the new settings Port number changes will only affect new connections made after calling this function Other changes take effect on existing as well as new connections This function may be used to change the server enable status The serverEnabled setting selects whether the server is enabled for the selected protocol If this flag is set to TRUE the controller supports incoming slave messages that use the selected protocol Setting this flag to FALSE prevents the controller from processing slave messages for this protocol Master messaging is always enabled The function copies the settings from the structure pointed to by pSettings to the settings of the specified protocol and returns TRUE The structure IP_PROTOCOL_SETTINGS is described in the Structures and Types section If there is an invalid setting FALSE is returned and the settings are not copied To save these settings with the controller settings in flash memory so that
245. ay of eight UINT16 variables Analog input measurement types are written to this array Valid values are e 0 0to 5V e 1 0to10V e 2 0to20mA e 3 4to20mA inputFilter is a reference to a UINT16 variable The input filter selection is written to this variable e 0 3Hz e 1 6Hz e 2 11 Hz e 3 30Hz scanFrequency is a reference to a UINT16 variable The scan frequency selection is written to this variable e 0 60Hz Document Version 1 70 5 23 2012 344 Function Specifications e 1 50 Hz outputType is a reference to a UINT16 variable The analog output type is written to this variable D 0to20mA e 1 4to 20 mA The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5607Inputs ioWrite5607Outputs Example This program reads output data from the I O table for the 5607 digital outputs and analog outputs at address 5 include lt ctools h gt void main void UCHAR doutData 2 INT16 aoutData 2 UINT16 inputType 8 UINT16 inputFilter UINT16 scanFrequency UINT16 outputType BOOLEAN status BOOLEAN done main loop while TRUE read output data from I O table status ioRead56070utputs 5 doutData aoutData inputType inputFilter scanFrequency outputType print data fprintf com3 status u Douts D to 7 X Aout 0 d r n status doutData 0 aoutData 0 release processor to other priority 1 tasks
246. bat command line options and loading the application into the controller This step is specific to the application It must be tested to confirm it operates correctly on the SCADAPack 350 and 4203 controllers You also should pay attention to the following e SCADAPack 350 and 4203 controllers have higher performance than do SCADAPack controllers Check that any I O operations allow enough time for field signals to change state Some timing relationships in the existing program may not be true in the new program depending on how you have implemented them For example a calculation done between two I O operations may execute faster and cause the second I O operation to take place sooner than you want e Check that any periodic functions execute at the correct rate If you ve used standard timing functions this should not be a problem If you ve used delay loops then these will execute faster You should replace them with standard timing functions Partially Supported C Tools Functions The following sections describe functions that are supported by the Telepace C Tools and IEC 61131 1 C Tools but are only partially supported by the Document Version 1 70 5 23 2012 682 Porting Existing C Tools Applications SCADAPack C Tools The following features are similar to existing C Tools features but require some source code modification Refer to these sections when porting existing SCADAPack C Tools Applications Event Numbers for S
247. be declared for each HART I O module in use A local variable or dynamically allocated variable may not be used because a late command response received after the variable is freed will write data over the freed variable space The function returns TRUE if the command was sent The function returns FALSE if the module number is invalid Notes The HART_DEVICE structure needs to be initialized using hartCommandoO or hartCommand11 The function returns immediately after the command is sent The calling program needs to wait for the response to be received Use the hartStatus command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command The code field of both HART_VARIABLE structures is not changed The response from the HART device to command 2 does not include variable codes The units field of the pvCurrent variable is set to 39 units mA The units field of the pvPercent variable is set to 57 units percent The response from the HART device to command 2 does not include units See Also hartCommand1 hartStatus hartSetConfiguration Document Version 1 70 5 23 2012 288 Function Specifications hartCommand3 Read Primary Variable Current and Dynamic Variables Syntax include lt ctools h gt BOOLEAN hartCommand3 UINT16 module HART DEVICE const device HART VARIABLE variables Description This function rea
248. be used with IP routing table entries but it cannot set the IP address Use the dnpRoutingTableEx structure instead The DNP Routing Table is a list of routes which are maintained in ascending order of DNP addresses typedef struct RoutingTable type UINT16 address station address UINT16 comPort com port interface UINT16 retries number of retries UINT16 timeout timeout in milliseconds routingTable e address is the DNP station address of the destination station e comPort specifies the communications port interface Allowed values are 1 serial port com1 2 serial port com2 3 serial port com3 4 serial port com4 103 DNP over TCP using LAN port 104 DNP over UDP using LAN port e _retries is the number of times the data link layer will retry the message in the event of a failure e timeout is the timeout in milliseconds SF_TRANSLATION The SF_TRANSLATION structure contains Store and Forward Messaging translation information This is used to define an address and port translation typedef struct st_SFTranslationMTcp COM INTERFACE slaveInterface slave interface typ UINT16 slaveStation slave station address COM INTERFACE forwardInterface forwarding interface type UINT16 forwardStation forwarding station address IP ADDRESS forwardIPAddress forwarding IP address SF_TRANSLATION e slavelnterface is the communication interface which recei
249. ber of executable instances of this application Valid values for applicationType are 0 to 65535 Default type is 0 Valid values for applicationTypeLimit are 0 to 32 Default limit is 0 which no limit UINT32 applicationType 0 valid types 0 to 65535 UCHAR applicationTypeLimit O valid limits 0 to 32 0 no limit The variable mainPriority selects the priority for the task main The task main is declared in the file main cpp There are 255 priority levels and the highest priority task has a priority of 0 The table below lists the recommended priority values to use with the SCADAPack 350 and 4203 The logic application executes in a continuous loop at priority 100 This means that a task selected with priority gt 100 will not be given the CPU Priority 100 is suitable for C Applications Document Version 1 70 5 23 2012 34 C Program Development Recomme nded Use Not recomme nded Document Version 1 70 5 23 2012 35 C Program Development Recomme nded Use Document Version 1 70 5 23 2012 36 C Program Development Recomme nded Use Serial protocol tasks IP protocol tasks or other Document Version 1 70 5 23 2012 37 C Program Development Recomme nded Use blocking task e g wait_even t called each loop Document Version 1 70 5 23 2012 38 C Program Development Recomme nded Use continuou sly running lo
250. ber of log files usbMemLogConfig numFiles 50 File size in number of records usbMemLogConfig fileRecordSize 1000 Number of elements fields in each record usbMemLogConfig numRecordElements 3 1st field Date and Time recordFieldsDefinitions 0 type DOG CMITIM Fl ER recordFieldsDefinitions 0 size sizeof dlogCMITime recordFieldsDefinitions 0 offset offsetof dlogRecord valuel 2nd field 16 bit AIN raw value recordFieldsDefinitions 1 type DLOG_INT16 Document Version 1 70 5 23 2012 639 Example Programs recordFields recordFields value2 3rd field recordFields recordFields recordFields value3 Pointer to array of record usbMeml recordFieldsD Security token disabled when set to 0 usbMemLogConfig securityToken Definitions 1 size sizeof INT16 Definitions 1 offset offsetof dlogRecord 32 bit floating point scaled value Definitions 2 type DLOG_ FLOAT Definitions 2 size sizeof float Definitions 2 offset offsetof dlogRecord lement definitions LogConfig recordList efinitions 0 Text description of log Maximum 255 characters memcpy usbMemLogConfig description strLogDescription strlen strLogDescription 1 The log name Maximum 255 characters memcpy usbMemLogConfig logName strLogName strlen strLogName 1 Create the log
251. ble character handler install handler com2 BOOLEAN INT32 INT32 signal serial while TRUE if poll event CHAR _ RECEIVED character fgetc com2 Document Version 1 70 5 23 2012 454 Function Specifications if character EOF clear overflow error flag to re enable coml clearerr coml fputs character com2 fputc character com2 fputs r n com2 Allow other tasks to execute release processor void signal serial INT32 port INT32 character interrupt signal event CHAR RECEIVED Document Version 1 70 5 23 2012 455 Function Specifications poll_ message Test for Received Message Syntax include lt ctools h gt envelope poll message void Description The poll_message function tests if a message has been received by the current task The poll_message function returns a pointer to an envelope if a message has been received It returns NULL if no message has been received The current task always continues to execute Notes Refer to the Real Time Operating System section for more information on messages See Also poll_event Example This task performs a function continuously and processes received messages from higher priority tasks when they are received include lt ctools h gt void task void nvelope letter while TRUE
252. cation Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the setdbase function The IO_SYSTEM system resource needs to be requested before calling this function Example This program writes the value 25 607 to the real variable named Flowrate include lt ctools h gt int main void BOOLEAN status request resource IO SYSTEM status writeRealVariable Flowrate 25 607 release resource IO SYSTEM Document Version 1 70 5 23 2012 566 Function Specifications writeMsgVariable Write to IEC 61131 1 Message Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN writeMsgVariable UCHAR varName UCHAR msg Description This function writes to the specified message variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and
253. cations outputType selects the analog output type setting Valid values are e 0to20mA e 1 4to20mA The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5606Inputs ioRead5606Outputs Example This program turns on all 16 digital outputs and sets the analog outputs to full scale on the 5606 module at address 5 include lt ctools h gt define MY EVENT 1 int main void UCHAR doutData 2 INT16 aoutData 2 UINT16 inputType 8 UINT16 inputFilter UINT16 scanFrequency UINT16 outputType IO STATUS io status BOOLEAN status main loop while TRUE write data to output tables for next scan doutData 0 OxFF doutData 1 OxFF aoutData 0 32767 aoutData 1 32767 set analog input types to 4 20 mA inputType 0 3 inputType 1 3 inputType 2 3 inputType 3 3 inputType 4 3 inputType 5 3 inputType 6 37 inputType 7 3 set filter and frequency inputFilter 3 minimum filter scanFrequency 0 60 Hz set analog output type to 4 20 mA outputType 1 Document Version 1 70 5 23 2012 385 Function Specifications inputType status ioWrite5 6060utputs 5 doutData aoutData inputFilter scanFrequency outputType add module scan to queue if 1oRequest MT 5606Outputs Di status FALSE wait for scan to complete ioNot
254. cations IEC 61131 1 Changes to appstart cpp Instead of appSettings src used in SCADAPack 32 C applications the new appstart cpp assigns the stack size as well as the main task priority Task priorities are discussed under changes to the function create_task The heap size is no longer configurable The C application has access to the entire system heap Open the sample appstart cpp to review these application settings Priority of the task main Priority 100 is recommended for a continuously running task UINT32 mainPriority 100 Document Version 1 70 5 23 2012 673 Porting Existing C Tools Applications Stack space allocated to the task main Note that at least 5 stack blocks are needed to call fprintf UINT32 mainStack 5 Application group assigned to the task main A unique value is assigned by the system to the applicationGroup for this application Use this variable in calls to create_task by this application UINT32 applicationGroup 0 A C application should not require any further modifications to appstart cpp There are no longer function calls in appstart for starting various drivers as there were in the SCADAPack 32 version These drivers are already running when a C Application is executed It is still possible to call these functions to disable functionality For example runTarget FALSE may still be called from appstart or main to stop the logic applicatio
255. ces to one for example select a unique value for applicationType and set applicationTypeLimit 1 The appstart function is the entry point for the C Application This function begins by initializing the global pointer to static non volatile data The main task is called next If the main task returns the application including tasks created by main is ended Non Volatile Memory nvMemory h Version 1 C Applications may declare variables as non volatile by locating them in SRAM There is 8 KB of SRAM available for static non volatile variables And if this is not enough up to 1 MB of SRAM is available for dynamic non volatile memory allocation For more details see the function allocateMemory Only non initialized variables are defined as non volatile Initialized variables are not need to be non volatile since they are initialized to the same value on application startup The following example describes the procedure for declaring non volatile variables Consider the following C Application defined in the two files main cpp and file2 cpp The first version of these files defines which non volatile variables are required for each file Local and module variables would normally exist as well Document Version 1 70 5 23 2012 41 C Program Development Version 2 main cpp include ctools h Non volatile variables required by main cpp static UINT32 variablel static UCHAR array1 20 static struct sam
256. cessor secceeeceerreens 58 Queue Status at Start of auxiliary Task 58 Queue Status after Character Received ccccceseeceeeeeeeeeeeeeeeeeeeees 59 Queue Status after echoData Waits for Event 59 Document Version 1 70 5 23 2012 Safety Information Read these instructions carefully and look at the equipment to become familiar with the device before trying to install operate or maintain it The following special messages may appear throughout this documentation or on the equipment to warn of potential hazards or to call attention to information that clarifies or simplifies a procedure The addition of this symbol to a Danger or Warning safety label indicates that an electrical hazard exists which will result in personal injury if the instructions are not followed This is the safety alert symbol It is used to alert you to potential personal injury hazards Obey all safety messages that follow this symbol to avoid possible injury or death ADANGER DANGER indicates an imminently hazardous situation which if not avoided will result in death or serious injury AWARNING WARNING indicates a potentially hazardous situation which if not avoided can result in death or serious injury ACAUTION CAUTION indicates a potentially hazardous situation which if not avoided can result in minor or moderate CAUTION CAUTION used without the safety alert symbol indic
257. cessor to other priority 254 tasks release processor This program stores a default alarm limit into the I O database the first time it is run On subsequent executions it uses the limit in the database The limit in the database can be modified by a communication protocol during execution include lt ctools h gt define HI ALARI 41000 define ALARM OUTPUT 1026 define SCAN EVENT 0 int main void if getProgramStatus FUNCPTR main NEW PROGRAM Set default alarm limit request resource IO SYSTEM setdbase MODBUS HI ALARM 4000 release resource IO SYSTEM Use values in database from now on setProgramStatus FUNCPTR main PROGRAM EXECUTED while TRUE INT16 ain 8 analog input module data Scan ain module ioRequest MT Ain 0 ioNotification SCAN EVENT wait event SCAN EVENT ioReadAin8 0 ain Test input against alarm limits request resource IO SYSTEM if ain 0 gt dbase MODBUS HI ALARM setdbase MODBUS ALARM OUTPUT 1 else setdbase MODBUS ALARM OUTPUT 0 Document Version 1 70 5 23 2012 646 Example Programs release resource IO SYSTEM Allow other tasks to execute release processor Get Task Status Example The following program displays information about all valid tasks include lt string h gt inc
258. clude lt ctools h gt BOOLEAN ioReadDin32 UINT16 moduleAddress UINT32 amp data Description This function reads buffered data from the 32 point digital input module at the specified module address Buffered data are updated when an I O request for the module is processed moduleAddress is the address of the digital output module The valid range is 0 to 15 data is a reference to a variable to receive the input data The function returns TRUE if data was written The function returns FALSE if the module address is invalid See Also ioReadDin8 ioReadDin16 Example This program displays the values of the 32 digital inputs read from a 32 point Digital Input Module at module address 0 include lt ctools h gt define IO NOTIFICATION 0 int main void UINT16 point UINT32 dinData request read from digital input module ioRequest MT_Din32 0 wait for the read to complete ioNotification IO NOTIFICATION wait event IO NOTIFICATION get the data read ioReadDin32 0 dinData Print module data fprintf coml Point Value for point 0 point lt 32 pointtt fprintf coml n r d D point Document Version 1 70 5 23 2012 354 Function Specifications putchar dinData amp 0x0001 1 0 dinData gt gt 1 Document Version 1 70 5 23 2012 355 Function Specifications ioReadDin8 Read Data From 8 point Digital Input Module Syntax incl
259. clude lt ctools h gt int recv int socketDescriptor char bufferPtr int bufferLength int flags 1 Description recv is used to receive messages from another socket recv may be used only on a connected socket see connect accept socketDescriptor is a socket created with socket or accept The length of the message is returned If a message is too long to fit in the supplied buffer excess bytes may be discarded depending on the type of socket the message is received from see socket The length of the message returned could also be smaller than bufferLength this is not an error If no messages are available at the socket the receive call waits for a message to arrive unless the socket is non blocking or the MSG_DONTWAIT flag is set in the flags parameter in which case 1 is returned with socket error being set to EWOULDBLOCK Out of band data not in the stream urgent data when the SO_OOBINLINE option is not set default TCP protocol only A single out of band data byte is provided with the TCP protocol when the SO_OOBINLINE option is not set If an out of band data byte is present recv with the MSG_OOB flag not set will not read past the position of the out of band data byte in a single recv request That is if there are 10 bytes from the current read position until the out of band byte and if we execute a recv specifying a bufferLength of 20 bytes and a flag value of 0 recv will only return 10 bytes This force
260. cludes the command file build bat to do this Please see the section Application Development for more details on editing build bat command line options and loading the application into the controller Test the Application This step is specific to the application It needs to be tested to confirm it operates correctly on the SCADAPack controllers e SCADAPack 32 controllers have higher performance than do SCADAPack 350 4203 controllers Check that any I O operations allow enough time for field signals to change state Some timing relationships in the existing program may not be true in the new program depending on how you have implemented them For example a calculation done between two I O operations may execute slower and cause the second I O operation to take place later than you want e Check that any periodic functions execute at the correct rate If you ve used standard timing functions this should not be a problem If you ve used delay loops then these will execute slower You should replace them with standard timing functions Partially Supported C Tools Functions The following sections describe functions that are supported by the SCADAPack 32 C Tools but are only partially supported by the SCADAPack C Tools The following features are similar to existing SCADAPack 32 C Tools features but require some source code modification Refer to these sections when porting existing SCADAPack 32 C Tools Applications to the SCADAP
261. completed system is free from all short circuits and grounds except those grounds installed according to local regulations according to the National Electrical Code in the U S A for instance If high potential voltage testing is necessary follow recommendations in equipment documentation to prevent accidental equipment damage Before energizing equipment e Remove tools meters and debris from equipment e Close the equipment enclosure door e Remove ground from incoming power lines e Perform all start up tests recommended by the manufacturer OPERATION AND ADJUSTMENTS The following precautions are from the NEMA Standards Publication ICS 7 1 1995 English version prevails e Regardless of the care exercised in the design and manufacture of equipment or in the selection and ratings of components there are hazards that can be encountered if such equipment is improperly operated e tis sometimes possible to misadjust the equipment and thus produce unsatisfactory or unsafe operation Always use the manufacturer s Document Version 1 70 5 23 2012 16 instructions as a guide for functional adjustments Personnel who have access to these adjustments should be familiar with the equipment manufacturer s instructions and the machinery used with the electrical equipment e Only those operational adjustments actually required by the operator should be accessible to the operator Access to other controls should be restricted
262. conds include lt string h gt include lt ctools h gt define TIME TO PRINT 15 The myshutdown function stops the signalling of TIME TO PRINT events Zeie EE shoes esee eee eee EE void myshutdown void endTimedEvent TIME TO PRINT 26552 S a e eS Se SS Se Se ee ee SE eee eS The main function sets up signalling of a timed event then waits for that event The time is printed each time the event occurs Beas ea Se SSS Se SSS eS Se Sa ee eS int main void struct prot settings settings struct clock now TASKINFO taskStatus Disable the protocol on serial port 1 settings type NO PROTOCOL settings station 1 settings priority 250 settings SFMessaging FALSE request _ resource IO SYSTEM set protocol coml amp settings release resource IO SYSTEM set up task exit handler to stop signalling of events when this task ends Document Version 1 70 5 23 2012 671 Example Programs getTaskInfo 0 installl myshutdown amp taskStatus ExitHandler taskStatus taskID start timed event startTimedEvent TIME TO PRINT 100 while TRUE wait event TIME request _resourc TO PRINT getclock amp now release resourc IO SYSTEM fprintf com1 now minute now IO SYSTEM FUNCPTR Time 02u 02u 02u r n now hour second Document Version 1 70
263. cription This function reads the total number of entries in the routing table Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 203 Function Specifications dnpSaveAl16Config Save DNP 16 Bit Analog Input Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveAI16Config UINT16 point dnpAnalogInput pAnalogInput 1 Description The dnpSaveAl16Config function sets the configuration of a DNP 16 bit analog input point The function has two parameters the point number and a pointer to an analog input point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 204 Function Specifications dnpSaveAl32Config Save DNP 32 Bit Analog Input Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveAI32Config UINT32 point dnpAnalogInput pAnalogInput 3 Description The dnpSaveAl32Config function sets the configuration of a DNP 32 bit analog input point The function has two parameters the point number and a pointer to an analog
264. ction Specifications modeminit Initialize Dial up Modem Syntax include lt ctools h gt enum DialError modemInit struct ModemInit configuration reserve id id Description The modemlnit function sends an initialization string to an external dial up modem It is typically used to set up a modem to answer incoming calls One modemlnit function may be active on each serial port The modemInit function handles port sharing and multiple dialing attempts The ModemInit structure pointed to by configuration defines the serial port and modem initialization string Refer to the Structures and Types section for a Description of the fields in the Modeminit structure The id variable is set to a reservation identifier for the serial port The identifier provides that no other modem control function can access the serial port This parameter needs to be supplied to the modemInitEnd and modemInitStatus functions The function returns an error code DE_NoError indicates that the initialize operation has begun Any other code indicates an error Refer to the Structures and Types section for a complete Description of error codes Notes The serial port type must be set to RS232_MODEM The modemInitStatus function returns the status of the connection attempt initiated by modemInit The modemlnitEnd function terminates initialization of the modem If acommunication protocol is active on the serial port the protocol will be disable
265. ction is written to this variable e 0 3Hz e 1 6Hz e 2 11 Hz e 3 30 Hz scanFrequency selects the scan frequency setting Valid values are e 0 60Hz e 1 50 Hz The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5506lnputs ioRead5506Outputs Example This program writes configuration data to the 5506 module at address 5 Document Version 1 70 5 23 2012 382 Function Specifications include lt ctools h gt define MY EVENT 1 int main void UINT16 inputType 8 UINT16 inputFilter UINT16 scanFrequency IO STATUS io status BOOLEAN status main loop while inputFilter TRUE set analog input types to 4 20 mA inputType 0 3 inputType 1 3 inputType 2 37 inputType 3 SF inputType 4 3 inputType 5 3 inputType 6 3 inputType 7 3 set filter and frequency inputFilter 3 minimum filter scanFrequency 0 60 Hz status ioWrite55060utputs 5 inputType scanFrequency add module scan to queue if ioRequest MT_5506Outputs Di status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT check status of last scan if io0Status MT 5506Outputs 5 amp io status status FALSE else if io status commStatus status FALSE release pr
266. ctions e initialize application program variables e execute the main function Source code for the appstart function is supplied with the C Tools sample application in the file appstart cpp The following discussion refers to statements found in this file At the top of appstart cpp are initialized global variables used to configure settings for the main task Sr These parameters are used when the task main is created Priority of the task main Priority 100 is recommended for a continuously running task A task with priority gt 100 will never be given the CPU See manual for details UINT32 mainPriority 100 Stack space allocated to the task main Note that at least 5 stack blocks are needed when calling fprintf UINT32 mainStack 5 Application group assigned to the task main A unique value is assigned by the system to the applicationGroup for this application Use this variable in all calls to create_task by this application See manual for details Document Version 1 70 5 23 2012 33 C Program Development mainPRiority UINT32 applicationGroup 0 Pointer to static non volatile data Define the structure NV_MEMORY in nvMemory h MV MEMORY pNvMemory NULL Size of structure in static non volatile memory UINT32 nvMemorySize sizeof NV_MEMORY applicationType and applicationTypeLimit may be used to limit the num
267. d stopping is to allow us to determine when we are at the out of band byte mark When we are at the mark recv with the MSG_OOB flag set can read the out of band data byte The user needs to use select in order to know when out of band data has arrived or is arriving Out of band data when the SO_OOBINLINE option is set see setsockopt TCP protocol only If the SO_OOBINLINE option is enabled the out of band data is left in the normal data stream and is read without specifying the MSG_OOB More than one out of band data bytes can be in the stream at any given time The out of band byte mark corresponds to the final byte of out of band data that was received In this case the MSG_OOB flag cannot be used with recv The out of band data will be read in line with the other data Again recv will not read past the position of the out of band mark in a single recv request The user needs to use select in order to know when out of band data has arrived or is arriving Document Version 1 70 5 23 2012 477 Function Specifications select may be used to determine when more data arrives or and when out of band data arrives Parameters socketDescriptor bufferPtr bufferLength flags The socket descriptor to receive data from The buffer to put the received data into The length of the buffer area that bufferPtr points to See below The flags parameter is formed by ORing one or more of the following MSG_DONTWAIT MSG_OOB
268. d the forwarding interface to forward the command The response to the command is automatically returned to the master through the same communication path in reverse The getSFTranslation and setSFTranslation functions are documented in the Function Specifications section Document Version 1 70 5 23 2012 689 Porting Existing C Tools Applications Serial Port Configuration Functions portConfiguration The C Tools function portConfiguration returned a pointer to the port configuration table for com1 and com2 only These functions are no longer supported Use the functions get_port and set_port in place of portConfiguration Default Settings for Com1 and Com2 Rx Flow Control The default settings for Com1 and Com2 have changed All serial ports of the SCADAPack 350 and 4203 have the same default settings and the same range of available settings This change is most notable in the default setting for Rx Flow control as described below The documentation for the structure pconfig has been updated below to reflect these changes The C Tools required the Rx Flow Control for com1 and com2 to be set to DISABLE when the Modbus RTU protocol is used The ports com1 and com2 on the SCADAPack 350 and 4203 must have Rx Flow Control set to RFC_MODBUS_RTU or ENABLE when the Modbus RTU protocol is used Rx Flow Control must be set to RFC_NONE or DISABLE when the Modbus ASCII or any other protocol is used Rx and Tx Flow Control requ
269. d until the initialization is complete then re enabled This allows the controller to communicate with the external modem on the port The protocol settings will also be restored when initialization is terminated with the modeminitEnd function If amodemDial function or an incoming call is active on the port the modemInit function cannot access the port and will return an error code of DE_NotInControl The reservation identifier is valid until the call is terminated and another modem function or an incoming call takes control of the port To optimize performance minimize the length of messages on com3 Examples of recommended uses for com3 are for local operator display terminals and for programming and diagnostics using the IEC 61131 1 program Do not call this function in a task exit handler Document Version 1 70 5 23 2012 425 Function Specifications Example Refer to the Example in the Modem Initialization Example section Document Version 1 70 5 23 2012 426 Function Specifications modemlnitEnd Abort Initialization of Dial up Modem Syntax include lt ctools h gt void modemInitEnd FILE port reserve id id enum DialError error Description The modemtInitEnd function terminates a modem initialization in progress port specifies the serial port where the modem is installed id is the port reservation identifier returned by the modemInit function The function sets the variable p
270. d will not be sequential This indicates that records were overwritten between calls to read data The sequence number rolls over after reaching its maximum value Document Version 1 70 5 23 2012 139 Function Specifications See Also See example DataLog program in the Example Programs section datalogReadStart datalogPurge datalogWrite Example See the example for datalogReadStart Document Version 1 70 5 23 2012 140 Function Specifications datalogReadStart Read Data Log Start Function Syntax include lt ctools h gt BOOLEAN datalogReadStart UINT16 ogID UINT32 pSequenceNumber Description This function returns the sequence number of the record at the start of the data log This is the oldest record in the log The function has two parameters log D specifies the data log The valid range is 0 to 15 pSequenceNumber is a pointer to a variable to hold the sequence number The function returns TRUE if the operation succeeded The function returns FALSE if the log ID is not valid or if the log has not been created Notes Use the datalogReadNext function to read records from the log The function will return a sequence number even if the log is empty In this case the next call to datalogReadNext will return no data See Also See example DataLog program in the Example Programs section datalogReadNext datalogPurge datalogWrite Example include lt ctools h gt include lt stdlib h g
271. d with a hardware based real time clock that independently maintains the time and date for the operating system The time and date remain accurate during power off This allows the controller to be synchronized to time of day for such functions as shift production reports automatic instrument calibration energy logging etc The calendar can be used to automatically take the controller off line during weekends and holidays The calendar automatically handles leap years There are eight library functions which access the real time clock Refer to the Function Specification section for details on each function listed Document Version 1 70 5 23 2012 68 Overview of Programming Functions alarmin Returns absolute time of alarm given elapsed time getclock Read the real time clock getClockAlarm Reads the real time clock alarm settings getClockTime Read the real time clock installClockHandler Installs a handler for real time clock alarms resetClockAlarm Resets the real time clock alarm so it will recur at the same time next day setclock Set the real time clock setClockAlarm Sets real time clock alarm Real Time Clock Structures The ctools h file defines the structures Real Time Clock Structure and Alarm Settings Structure for real time clock information Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Stopwatch Timer Functions The stopwatch is a counter tha
272. dDin16 ioReadDin32 ioRead5601Inputs ioRead5604Inputs ioRead5606Outputs ioRead56070utputs ioReadDin8 amp Read the digital and analog inputs from a 5606 I O Module Read buffered data from the 5232 digital inputs Read buffered data from the 5232 counter inputs Read buffered data from the 5414 Digital input module Write 5414 module configuration parameters Read buffered data from any 16 point Digital input module Read buffered data from any 32 point Digital input module Read buffered data from the digital and analog inputs of a 5601 I O module Read the digital and analog inputs from a SCADAPack 5604 I O Module Read the digital and analog outputs from a 5606 I O Module Read the digital and analog outputs from a 5607 I O Module Read buffered data from any 8 point Digital input module Document Version 1 70 5 23 2012 64 Overview of Programming Functions Digital Output Functions The controller supports external digital output modules Refer to the SCADAPack 350 System Hardware Manual for further information on controller digital output modules There are several library functions related to digital output modules Refer to the Function Specification section for details on each function listed ioRead5606Inputs ioReadDout16 ioReadDout32 ioRead5415Inputs ioRead54150utputs ioRead5601 Outputs ioRead5604O0utputs ioReadDout8 ioWriteDout16 ioWriteDout32 ioWrite54150utp
273. dSP2Inputs UCHAR amp dinData 2 INT16 amp ainData 8 Description This function reads buffered data from the digital and analog inputs of the SCADAPack 350 I O Buffered data are updated when an I O request for the module is processed dinData is a reference to an array of two UCHAR variables Digital data for the 12 inputs are written to this array One bit in the array represents each input point ainData is a reference to an array of eight INT16 variables Analog data are written to this array The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioReadSP2Outputs ioWriteSP2Outputs Example This program displays the values of the first 8 digital inputs and the 5th analog input read from the SCADAPack 350 I O include lt ctools h gt define MY EVENT 1 int main void UCHAR dinData 2 INT16 ainData 8 IO STATUS io status BOOLEAN status BOOLEAN done BOOLEAN printNow main loop while TRUE add module scan to queue if i1oRequest MT_SP2Inputs 0 status FALSE Document Version 1 70 5 23 2012 360 Function Specifications printNow wait for scan to complete ioNotification MY EV ENT wait event MY_EVENT r read input data from last scan status ioReadSP2Inputs dinData ainData check status of last scan 0
274. data value and written to the I O table The valid range for moduleAddress is 0 to 15 The function returns TRUE if the data was written The function returns FALSE if the module address is invalid Document Version 1 70 5 23 2012 395 Function Specifications ioWriteSP2Outputs Write SCADAPack 350 Outputs Syntax include lt ctools h gt BOOLEAN ioWriteSP20Outputs UCHAR amp doutData 2 INT16 amp aoutData 2 Description This function writes data to the I O table for the 10 digital outputs and 2 analog outputs of the SCADAPack 350 I O Data are written to the module when an I O request for the module is processed doutData is a reference to an array of two UCHAR variables Digital data for the 10 outputs are read from this array One bit in the array represents each output point aoutData is a reference to an array of two INT16 variables Analog data for the two analog outputs are read from this array The function returns TRUE See Also ioReadSP2Outputs ioReadSP2Inputs Example This program turns on all 10 digital outputs and sets the analog outputs to full scale on the SCADAPack 350 include lt ctools h gt define MY EVENT 1 int main void UCHAR doutData 2 INT16 aoutData 2 IO STATUS io status BOOLEAN status main loop while TRUE write data to output tables for next scan doutData 0 OxFF doutData 1 0x03 aoutData 0 32767
275. dbusHandler UINT16 handler UCHAR UINT16 UCHAR UINT16 zi 1 Description The removeModbusHandler function allows user defined extensions to standard Modbus protocol to be removed This function specifies the previously installed function that is to be removed This function returns TRUE if the specified handler was removed and FALSE if the specified handler is not present Notes This function is used to remove a user defined extension to the standard Modbus protocol See Also installModbusHandler Document Version 1 70 5 23 2012 485 Function Specifications report_error Set Task Error Code Syntax include lt ctools h gt void report error UINT32 error Description The report_error functions sets the error code for the current task to error An error code is maintained for each executing task Notes This function is used in sharable I O routines to return error codes to the task using the routine Some functions supplied with the Microtec C compiler report errors using the global variable errno The error code in this variable may be written over by another task before it can be used Document Version 1 70 5 23 2012 486 Function Specifications request_resource Obtain Control of a Resource Syntax include lt ctools h gt void request resource UINT32 resource Description The request_resource function obtains control of the resource specified by resource If
276. de to handle release processor for 100ms sleep processor 100 the failure here 0 amp io status the failure here the failure here Document Version 1 70 5 23 2012 372 Function Specifications ioWrite4203DSOutputs Write 4203 DS Outputs Syntax include lt ctools h gt BOOLEAN ioWrite4203DSOutputs UCHAR amp doutData Description This function writes data to the I O table for the digital outputs of the 4203 DS I O Data is written to the module when an I O request for the module is processed doutData is a reference to a UCHAR variable Digital data for the outputs is read from this variable One bit in the array represents each output point The function returns TRUE if the supplied data was written to the I O table FALSE is returned if the data could not be written to the I O table See Also ioRead4203DSInputs Example This program turns on the digital outputs on the 4203 DS include lt ctools h gt define MY EVENT 1 int main void UCHAR doutData IO STATUS io status main loop while TRUE write data to output tables for next scan doutData 0x03 ioWrite4203DSOutputs doutData add module scan to queue if ioRequest MT_4203DSOutputs 0 insert code to handle the failure here wait for scan to complete ioNotification MY EVENT Document Version 1 70 5 23 2012 373 Function Specific
277. ds Notes If the serial port settings are the same as the current settings this function has no effect The serial port is reset when settings are changed All data in the receive and transmit buffers are discarded The IO_SYSTEM resource needs to be requested before calling this function To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request _ resource FLASH MEMORY flashSettingsSave CS_ RUN release resource FLASH MEMORY See Also get_port Example This code fragment changes the baud rate on com2 to 19200 baud include lt ctools h gt struct pconfig settings get_port com2 amp settings settings baud BAUD19200 request resource IO SYSTEM set _port com2 amp settings release resource IO SYSTEM This code fragment sets com2 to the same settings as com1 include lt ctools h gt struct pconfig settings Document Version 1 70 5 23 2012 521 Function Specifications request resource IO_ SYSTEM set _port com2 get _port coml amp settings release resource IO SYSTEM Document Version 1 70 5 23 2012 522 Function Specifications setLoginCredentials Sets login credentials for a service Syntax include lt ctools h gt BOOLEAN setLoginCredentials UINT32 service UINT32 index UCHAR username UCHAR password
278. ds dynamic variables and primary variable current from a HART device using command 3 The function has three parameters the module number of the 5904 module 0 to 3 the device to be read and a pointer to an array of five HART_VARIABLE structures The variables array must be static modular or global variables An array of variables should be declared for each HART I O module in use A local variable or dynamically allocated variable may not be used because a late command response received after the variable is freed will write data over the freed variable space The variables array is updated when the response is received by the 5904 interface as follows Variables 0 primary variable current Variables 1 primary variable Variables 2 secondary variable Variables 3 tertiary variable Variables 4 fourth variable The function returns TRUE if the command was sent The function returns FALSE if the module number is invalid Notes The HART_DEVICE structure needs to be initialized using hartCommandoO or hartCommand11 The function returns immediately after the command is sent The calling program needs to wait for the response to be received Use the hartStatus command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command Document Version 1 70 5 23 2012 289 Function Specifications Not all devices return primary secondar
279. dule I O types Specify 0 for startingRegister2 startingRegister3 or startingRegister4 if not applicable Document Version 1 70 5 23 2012 94 Function Specifications Notes Up to 150 modules may be added to the Register Assignment If the Register Assignment is full or if an incorrect value is specified for any argument this function returns FALSE otherwise TRUE is returned Output registers specified for certain CNFG type modules are initialized with the current parameter values when the module is added to the Register Assignment e g CNFG_realTimeClock Call clearRegAssignment first before using the addRegAssignment function when creating a new Register Assignment Duplicate or overlapping register assignments are not checked for by this function Overlapping register assignments may result in unpredictable LUC activity To obtain error checking that avoids invalid register assignments such as these use the Telepace Register Assignment dialog to build the Register Assignment Then save the Register Assignment in a Ladder Logic file e g filename lad and download it with the C program or transfer the Register Assignment to the C program using the clearRegAssignment and addRegAssignment functions To save the Register Assignment with the controller settings in flash memory so that it is loaded on controller reset call flashSettingsSave as shown in the example below The lIO_SYSTEM resource needs to be requested befor
280. e IO SYSTEM Enable character handler install handler com2 BOOLEAN INT32 INT32 signal serial Print each character as it is received while TRUE wait event CHAR RECEIVED character fgetc com2 if character EOF clear overflow error flag to re enable coml clearerr coml fputs character com2 fputc character com2 fputs r n com2 release processor to other priority 1 tasks release processor SSeS SoS Sees Ste e EE Ee eee ee SE Se ee Se Seer Se ee ee eee ee SS signal serial This routine signals an event when a character is received If there is an error the character is ignored af void signal serial INT32 port INT32 character interrupt signal event CHAR RECEIVED Install Clock Handler Example This program demonstrates how to call a function at a specific time of day include lt ctools h gt define ALARM EVENT 20 This function signals an event when the alarm occurs Document Version 1 70 5 23 2012 652 Example Programs void alarmHandler void interrupt signal event ALARM EVENT This task processes alarms signaled by the clock handler void processAlarms void while TRUE wait event ALARM EVENT Reset the alarm for the next day request _ resource IO SYSTEM resetClockAlarm
281. e See the example for the allocate_envelope function Document Version 1 70 5 23 2012 149 Function Specifications dlogCreate Create a data log using the specified configuration Syntax include lt ctools h gt dlogStatus dlogCreate dlogConfiguration pConfiguration UINT32 dlogID Parameters The function has these parameters e pConfiguration is a pointer to a data log configuration structure containing the data log configuration See the description of the configuration structure for details on the parameters that can be configured in the data log e dloglD is a pointer to a variable where the data log ID will be written if the function is successful If the pointer is NULL the creation of the data log will fail and the function will return DLOGS_FAILURE The function returns e DLOGS_SUCCESS if the log could be created Valid dlogID returned as output parameter e DLOGS_EXISTS if alog exists with same configuration parameters Valid dlogID returned as output parameter e DLOGS_DIFFERENT if a log with the same name exists with different parameters The dlogID is not valid e DLOGS_NOMEMORY if the log could not be created due to lack of memory The dlogID is not valid e DLOGS_INVALID if the configuration data is not valid The dlogID is not valid e DLOGS_FAILURE if an error occurred during creation of the log The dlogID is not valid e DLOGS_WRONGPARANM if an error occurred due to a wrong par
282. e lt ctools h gt INT16 set protocol FILE stream struct prot settings settings Description The set_protocol function sets protocol parameters port needs to specify one of com1 com2 or com3 settings references a protocol configuration structure Refer to the Description of the prot_settings structure for an explanation of the fields The set_protocol function returns TRUE if the settings were changed It returns FALSE if there is an error in the settings or if the protocol does not start The IO_SYSTEM resource needs to be requested before calling this function To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Notes Setting the protocol type to NO PROTOCOL ends the protocol task and frees the stack resources allocated to it Add a call to modemNotification when writing a custom protocol See Also get_protocol Example This code fragment changes the station number of the com2 protocol to 4 include lt ctools h gt struct prot settings settings get_protocol com2 amp settings settings station 4 request resource IO SYSTEM set _protocol com2 amp settings release resource IO SYSTEM Document Version 1 70 5 23 2012 526 Function Specifications setProtocolSettings Set Protocol E
283. e DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration This function does not write the configuration for the Unsolicited Back Off Time Use the function dnoSaveUnsolicitedBackoffTime to save the Unsolicited Back Off Time configuration This function supersedes the dnpSaveConfiguration function Document Version 1 70 5 23 2012 217 Function Specifications dnpSaveUnsolicitedBackoffTime Set the DNP unsolicited resend time Syntax BOOLEAN dnpSaveUnsolicitedBackoffTime UINT16 backoffTime 1 Description The dnpSaveUnsolicitedBackoffTime function writes the unsolicited resend time to the controller The time is in seconds and the allowed range is 0 65535 seconds A value of zero indicates that the unsolicited resend timer is disabled The function returns TRUE if the function was successful It returns FALSE if the DNP configuration has not been created Document Version 1 70 5 23 2012 218 Function Specifications dnpSendUnsolicitedResponse Send DNP Unsolicited Response Syntax BOOLEAN dnpSendUnsolicitedResponse UINT16 classFlags 1 Description The dnpSendUnsolicitedResponse function sends an Unsolicited Response message in DNP with data from the specified classes classFlags specifies the class or classes of event data to include in the message It can contain any combination of the follo
284. e address 0 ioWriteAout4 0 dataArray ioRequest MT Aout4 0 Document Version 1 70 5 23 2012 391 Function Specifications ioWriteAout5303 Write Data to 5303 Analog Output Module Syntax include lt ctools h gt BOOLEAN ioWriteAout5303 INT16 amp data 2 Description This function writes data to the I O tables for the 2 point 5303 analog output module Data are written to the module when an I O request for the module is processed The function has one parameter a reference to an array of two INT16 variables Data are read from the array and written to the I O table The function returns TRUE Document Version 1 70 5 23 2012 392 Function Specifications ioWriteDout16 Write Data to 16 Point Digital Output Module Syntax include lt ctools h gt BOOLEAN ioWriteDout16 UINT16 moduleAddress UINT16 data Description This function writes data to the I O tables for the 16 point digital output module at the specified module address Data are written to the module when an I O request for the module is processed The function has two parameters the module address and the data to be written Data are read from the 16 bit data value and written to the I O table The valid range for moduleAddress is 0 to 15 The function returns TRUE if the data was written The function returns FALSE if the module address is invalid Document Version 1 70 5 23 2012 393 Function Specifications
285. e calling this function See Also clearRegAssignment Example include lt ctools h gt int main void request resource IO SYSTEM Create the Register Assignment clearRegAssignment addRegAssignment SCADAPack 210 0 1 10001 30001 40001 addRegAssignment AOUT_ 5302 1 40003 0 0 0 addRegAssignment DIAG forceLED 1 10017 0 0 0 addRegAssignment DIAG controllerStatus 1 30009 D O addRegAssignment DIAG protocolStatus 2 30010 0 0 0 release resource IO SYSTEM save register assignment with controller settings Document Version 1 70 5 23 2012 95 Function Specifications request resource FLASH MEMORY flashSettingsSave CS _PERMANE release resource FLASH MEMORY Document Version 1 70 5 23 2012 96 Function Specifications addRegAssignmentEx Add Register Assignment Telepace firmware only Syntax include lt ctools h gt BOOLEAN addRegAssignmentEx UINT16 moduleType INT16 moduleAddress UINT16 startingRegisterl UINT16 startingRegister2 UINT16 startingRegister3 UINT16 startingRegister4 UINT16 parameters 16 1 Description The addRegAssignmentEx function adds one I O module to the current Register Assignment of type moduleType The following symbolic constants are valid values for moduleType AIN_520xTemperature CNTR_5410 AIN_520xRAMBattery DIAG_commStatus AIN_ 5501 DIAG_co
286. e can refer to an actual I O hardware module e g 5407 Digital Input Module or it may refer to a set of controller parameters such as serial port settings The chapter Register Assignment Reference of the Telepace Ladder Logic Reference and User Manual contains a description of what each module is used for and the register assignment requirements for the I O module Register assignments configured using the Telepace Register Assignment dialog may be stored in the Telepace program file or downloaded directly to the controller To obtain error checking that stops invalid register assignments use the Telepace Register Assignment dialog to initially build the Register Assignment The Register Assignment can then be saved in a Ladder Logic file e g filename lad and downloaded with the C program Register Assignment Functions There are several library functions related to register assignment Refer to the Function Specification section for details on each function listed clearRegAssignment Erases the current Register Assignment addRegAssignment Adds one I O module to the current Register Assignment getlOErrorindication Gets the control flag for the I O module error indication getOutputsInStopMode Gets the control flags for state of Outputs in Ladders Stop Mode setlOErrorIndication Sets the control flag for the I O module error indication setOutputsInStopMode Sets the control flags for state of Outputs in Ladders Stop Mode Register
287. e controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the dbase function The IO_SYSTEM system resource needs to be requested before calling this function See Also readRealVariable Example This program displays the contents of the integer variable named Temperature include lt ctools h gt int main void BOOLEAN status INT32 value request resource IO SYSTEM status readIntVariable Temperature amp value release resource IO SYSTEM Document Version 1 70 5 23 2012 466 Function Specifications fprintf coml status u Temp Sld r n status value Document Version 1 70 5 23 2012 467 Function Specifications readMsgVariable Read IEC 61131 1 Message Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN readMsgVariable UCHAR varName UCHAR msg Description This function returns the current value of the specified message variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive
288. e deadband e pvN1 is the process value from n 1 iteration e pvNz2 is the process value from n 2 iteration e errorN1 is the error from n 1 iteration e _lastTime is the time of last execution Document Version 1 70 5 23 2012 623 Structures and Types PROTOCOL_SETTINGS The Extended Protocol Settings structure defines settings for a communication protocol This structure differs from the standard settings in that it allows additional settings to be specified typedef struct protocolSettings t UCHAR type UINT16 station UCHAR priority UINT16 SFMessaging ADDRESS MODE mode PROTOCOL SETTINGS type is the protocol type It may be one of NO_PROTOCOL MODBUS_RTU or MODBUS_ ASCII AB_FULL_BCC AB_FULL_CRC AB_HALF_BCC DNP or AB_HALF_CRC macros To set the remaining settings use the function mTcpSetInterfaceEx station is the station address of the controller Each serial port may have a different address The valid values are determined by the communication protocol This field is not used if the protocol type is NO PROTOCOL priority is the task priority of the protocol task This field is not used if the protocol type is NO PROTOCOL SFMessaging is the enable Store and Forward messaging control flag ADDRESS_MODE is the addressing mode standard or extended PROTOCOL_SETTINGS_EX Type This structure contains serial port protocol settings including Enron Modbus support typedef struct
289. e dnpWriteMasterPollTableEntry function Document Version 1 70 5 23 2012 225 Function Specifications dnpWriteRoutingTableEntry_DialString Write DNP Routing Table Entry Dial Strings Syntax BOOLEAN dnpWriteRoutingTableEntry DialStrings UINT16 index UINT16 primaryDialStringLength CHAR primaryDialString UINT16 secondaryDialStringLength CHAR secondaryDialString 1 Description This function writes a primary and secondary dial string into an entry in the DNP routing table index specifies the index of an entry in the DNP routing table primaryDialStringLength specifies the length of primaryDialString excluding the null terminator character primaryDialString specifies the dial string used when dialing the target station This string is used on the first attempt secondaryDialStringLength specifies the length of secondaryDialString excluding the null terminator character secondaryDialString specifies the dial string to be used when dialing the target station It is used for the next attempt if the first attempt fails The function returns TRUE if the configuration was written and FALSE if an error occurred Notes This function needs to be used in conjunction with the dnpWriteRoutingTableEntry function to write a complete entry in the DNP routing table Document Version 1 70 5 23 2012 226 Function Specifications dnpWriteRoutingTableEntry Write Routing Table Entry Syntax include
290. e echoData task is higher priority than main The auxiliary task is the same priority as main The main task then executes round robin with other tasks of the same priority The auxiliary task is a simple task that executes round robin with the other tasks of its priority Only the code necessary for task switching is shown to simplify the example The echoData task waits for a character to be received on a serial port then echoes it back out the port It waits for the event of the character being received to allow lower priority tasks to execute It installs a character handler function signalCharacter that signals an event each time a character is received This function is hooked into the receiver interrupt handler for the serial port The execution of this program is explained in the Explanation of Task Execution section Real Time Operating System Sample Copyright c 2006 Control Microsystems Inc This program creates several simple tasks for demonstration of the functionality of the real time operation system Wi include lt stdio h gt include lt ctools h gt ay signalCharacter Document Version 1 70 5 23 2012 52 Real Time Operating System The signalCharacter function signals an event when a character is received This function must be called from an interrupt handler KY void signalCharacter UINT16 character UINT16 error If there was no error signal that a cha
291. e if a response has been received to a command sent The function has three parameters the module number of the 5904 module a pointer to the status variable and a pointer to the additional status code variable The status and code variables are updated with the following information HART interface HR_NoModuleResponse not used module is not communicating Command ready HR_CommandPending not used to be sent Command sent to HR_CommandSent current attempt number device Response HR_Response response code from HART received device see Notes No valid response HR_NoResponse O no response from HART received after all device attempts made Other error response code from HART device see Notes HART interface HR_WaitTransmit not used module is not ready to transmit The function returns TRUE if the status was read The function returns FALSE if the module number is invalid Notes The response code from the HART device contains communication error and status information The information varies by device but there are some common values e If bit 7 of the high byte is set the high byte contains a communication error summary This field is bit mapped The table shows the meaning of each bit Document Version 1 70 5 23 2012 294 Function Specifications as defined by the HART protocol specifications Consult the documentation for the HART device for more information Bt escroien e onica pariyoro D
292. e on the SCADAPack 32 SCADAPack 350 and 4203 DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 193 Function Specifications dnpPortStatus Get communication status for a port Syntax include lt ctools h gt DND PROTOCOL STATUS dnpPortStatus COM INTERFACE ifType BOOLEAN clear Description The dnpPortStatus function returns the DNP message statistics for the specified communication port IfType specifies the communication interface Valid values are CIE Com CIF_Com2 CIF_Com3 CIF_Com4 and CIF_Lan1 If ifType does not point to a valid communications interface the function has no effect If clear is TRUE the DNP message counters are reset to zero after they are read Document Version 1 70 5 23 2012 194 Function Specifications dnpReadAddressMappingTableEntry Read DNP Address Mapping Table entry Syntax include lt ctools h gt BOOLEAN dnpReadAddressMappingTableEntry UINT16 index dnpAddressMap type pAddressMap 1 Description The dnpReadAddressMappingTableEntry function reads an entry from the DNP address mapping table pRoute is a pointer to a table entry it is written by this function The return value is TRUE if pAddressMap was successfully written or FALSE otherwise Notes DNP needs to be enabled before calling this function in order to create the DNP configuratio
293. e port is installed The default handler does nothing Notes The install_ handler function can be used to write custom communication protocols The handler is called at the completion of the receiver interrupt handler RTOS calls see functions listed in the section Real Time Operating System Functions at the start of this chapter may not be made within the interrupt handler with one exception The interrupt_signal_event RTOS call can be used to signal events To optimize performance minimize the length of messages on com3 Examples of recommended uses for com3 are for local operator display terminals and for programming and diagnostics using the IEC 61131 1 program Example See the Install Serial Port Handler Example in the Examples section Document Version 1 70 5 23 2012 303 Function Specifications installClockHandler Install Handler for Real Time Clock Syntax include lt ctools h gt void installClockHandler void function void Description The installClockHandler function installs a real time clock alarm handler function The real time clock alarm function calls this function each time a real time clock alarm occurs function specifies the handler function If function is NULL the handler is disabled Notes RTOS calls see functions listed in the section Real Time Operating System Functions at the start of this chapter may not be made within the interrupt handler with one exception The inte
294. e the DNP configuration The function returns TRUE if successful FALSE otherwise Document Version 1 70 5 23 2012 165 Function Specifications dnpCreateRoutingTable Create Routing Table Syntax include lt ctools h gt BOOLEAN dnpCreateRoutingTable UINT16 size Description This function destroys any existing DNP routing table and allocates memory for a new routing table according to the size parameter Notes DNP needs to be enabled before calling this function in order to create the DNP configuration The function returns TRUE if successful FALSE otherwise Example See the example in the dnpGetConfiguration section Document Version 1 70 5 23 2012 166 Function Specifications dnpGenerateChangeEvent Generate DNP Change Event Syntax BOOLEAN dnpGenerateChangeEvent DND POINT TYPE pointType UINT16 pointAddress 1 Description The dnpGenerateChangeEvent function generates a change event for the DNP point specified by pointType and pointAddress pointType specifies the type of DNP point Allowed values are BI_POINT binary input Al16_POINT 16 bit analog input AI32_POINT 32 bit analog input AISF_POINT short float analog input Cl16_ POINT 16 bit counter output CIl32_POINT 32 bit counter output pointAddress specifies the DNP address of the point A change event is generated for the specified point with the current time and current value and stored in the
295. e the application It is found at C Applications IEC 61131 1 Hello myApp out Add C C Program i File Name Browse E SP2 Applications IS aGRAF Hello myApp out v Write Cancel ul e Select the Write button to download to the file to the controller Executing the Program e Connect a terminal to com2 on the controller It will display the output of the program Set the communication parameters to 9600 baud 8 data bits 1 stop bit and no parity e From the C C Program Loader dialog click on the Run button to execute the program The hello world message will be displayed on the terminal e When multiple C Applications are loaded and the controller is power cycled the C Applications are restarted in the order they were first loaded to the controller Document Version 1 70 5 23 2012 32 C Program Development C Program Development Program Architecture Application Startup This section of the manual describes the process for developing end user applications in C for the SCADAPack 350 and 4203 controllers The SCADAPack C Tools are based on the GNU Compiler Collection GCC for the Arm7 processor Users will be able to create compile and debug applications using these tools There are two files associated with the startup structure appstart cpp and nvMemory h Each is described below Application Startup Function appstart cpp The start up code has the following major fun
296. e unsolicited resend time from the controller The time is in seconds and the allowed range is 0 65535 seconds A value of zero indicates that the unsolicited resend timer is disabled Document Version 1 70 5 23 2012 186 Function Specifications dnpinstallConnectionHandler Configures the connection handler for DNP Syntax include lt ctools h gt void dnpInstallConnectionHandler void handler UINT16 dnpAddress DNP_CONNECTION EVENT event Description This function installs a handler that will permit user defined actions to occur when DNP requires a connection message confirmation is received or a timeout occurs handler is a pointer to the handler function If function is NULL the handler is disabled The function has no return value Notes The handler function needs to process the event and return immediately If the required action involves waiting this needs to be done outside of the handler function See the example below for one possible implementation The application needs to disable the handler when the application ends This prevents the protocol driver from calling the handler while the application is stopped Call the dnplnstallConnectionHandler with a NULL pointer The usual method is to create a task exit handler function to do this See the example below for details The handler function has one parameter e event is DNP event that has occurred It may be one of DN
297. ease processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 379 Function Specifications ioWrite5505Outputs Write 5505 Configuration Syntax include lt ctools h gt BOOLEAN ioWrite55050utputs UINT16 moduleAddress UINT16 amp inputType 4 UINT16 inputFilter Description This function writes configuration data to the I O Table for a 5505 I O module Data are written to the module when an I O request for the module is processed moduleAddress is the address of the 5505 module Valid values are 0 to 15 inputType is a reference to an array of four UINT16 variables selecting the input range for the corresponding analog input Valid values are e 0 RTD in deg Celsius e RTD in deg Fahrenheit e 2 RTD in deg Kelvin e 3 resistance measurement in ohms inputFilter selects input filter selection is written to this variable e 0 0 5s e 1q1 is e 2 2S e 3 4s The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5505lnputs ioRead5505Outputs Example This program writes configuration data to the 5505 module at address 5 include lt ctools h gt define MY EVENT I int main void UINT16 inputType 4 Document Version 1 70 5 23 2012 380 Function Specifications UINT16 inputFilter IO STATUS io status BOOLEAN status main loop while inputFilter
298. eater than 0 numRecordElements is the number of elements in each record Valid values are any value greater than 0 Document Version 1 70 5 23 2012 589 Structures and Types e recordList is a pointer to a list of record element definitions See the dlogRecordElement type for details e securityToken is a security token that must be present on an inserted mass storage device for these logs to be copied to that device Set this to 0 to disable the token e description is a string describing the log The description is included in the header of the log files The string has to be null terminated e logName is the name of the log The log name is used to name the log files The string has to be null terminated dlogCMITime Type This structure represents the time stamps for data log records Time is measured as the number of days since January 1 1997 and the number of centiseconds since the start of the current day The time in this format can be obtained using the getClockTime function typedef struct INT32 days INT32 centiseconds dlogCMITime e days is the number of days since January 1 1997 e centiseconds is the number of hundredths of a second since the start of the current day dlogMediaStatus Type The dlogMediaStatus enumerated type indicates the status of the media used by the configured data log For non auto transfer enabled data logs the states can
299. ed The C program is erased The controller is unlocked To perform a Cold Boot use the following procedure Remove power from the controller Hold down the LED POWER button Apply power to the controller Continue holding the LED POWER button for 25 seconds until the STAT LED begins to flash on and off continuously Release the LED POWER button If the LED POWER button is released before the STAT LED begins to flash the controller will start in service mode not the cold boot mode Document Version 1 70 5 23 2012 30 Getting Started Connect to Controller Before the project can be loaded to the controller a connection or link needs to be made between the PC and the controller The serial ports are set to their default parameters when a Cold Boot is done These settings are 9600 baud 8 data bits no parity 1 stop bit Modbus RTU protocol and station address 1 The IEC 61131 1 PC PLC Link parameters define how the communication link between the PC and the target controller functions These parameters are set to match the serial port parameters To open the PC_PLC link parameters dialog e Select Link Setup from the Debug menu When selected the PC PLC Link Parameters dialog is displayed Target Slave Number H Communication port TeleBUS Driver sl Cancel Control Setup Time out seconds 1 RH Retries The Target Slave Number entry is ignored when the TeleBUS Driver is selected T
300. ed Use the hartStatus command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command A program needs to initialize the link before executing any other commands The function determines if long or short addressing is to be used by the command number Long addressing is used for all commands except commands 0 and 11 The functions hartCommand0O hartCommand1 etc are used to send commands provided by the Network Layer Document Version 1 70 5 23 2012 284 Function Specifications See Also hartStatus hartSetConfiguration hartCommandO hartCommand1 Document Version 1 70 5 23 2012 285 Function Specifications hartCommandO Read Unique Identifier Syntax include lt ctools h gt BOOLEAN hartCommand0 UINT16 module UINT16 address HART DEVICE const device Description This function reads the unique identifier of a HART device using command 0 with a short form address This is a link initialization function The function has three parameters the module number of the 5904 module 0 to 3 the short form address of the HART device 0 to 15 and a pointer toa HART_DEVICE structure The information read by command 0 is written into the HART_DEVICE structure when the response is received by the 5904 interface The function returns TRUE if the command was sent The function returns FALSE if the module number is
301. ed OFF when the Ladder Logic program is stopped If holdAoutsOnStop is TRUE then analog outputs are held at their last value when the Ladder Logic program is stopped If holdAoutsOnStop is FALSE then analog outputs go to zero when the Ladder Logic program is stopped To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request resource FLASH MEMORY flashSettingsSave CS PERMANENT release resource FLASH MEMORY See Also getOutputsInStopMode Example This program changes the output conditions to hold analog outputs at their last value when the Ladder Logic program is stopped include lt ctools h gt int main void unsigned holdDoutsOnStop unsigned holdAoutsOnStop getOutputsiInStopMode amp holdDoutsOnStop amp holdAoutsOnStop holdAoutsOnStop TRUE setOutputsInStopMode holdDoutsOnStop holdAoutsOnStop Document Version 1 70 5 23 2012 520 Function Specifications set_port Set Serial Port Configuration Syntax include lt ctools h gt void set _port FILE stream struct pconfig settings Description The set_port function sets serial port communication parameters port needs to specify one of com1 com2 or com3 settings references a serial port configuration structure Refer to the Description of the pconfig structure for an explanation of the fiel
302. ed function sets the state of the FORCE LED state may be either LED_ON or LED_OFF Notes The FORCE LED is used to indicate forced I O Use this function with care in application programs Document Version 1 70 5 23 2012 242 Function Specifications freeMemory Free Non Volatile Dynamic Memory Syntax include lt ctools h gt void freeMemory void pMemory Description The freeMemory function returns the specified memory to the system memory pool The specified memory to be returned or freed must have been allocated by a previous Call to the function allocateMemory The function has one argument a pointer to the memory to be freed Notes The DYNAMIC_MEMORY resource needs to be requested before calling this function The allocation of memory and the allocated memory are non volatile Pointers to non volatile dynamic memory need to be statically allocated in a non volatile data section Otherwise they will be initialised at reset and the non volatile dynamic memory will be lost See the Example for the function allocateMemory which demonstrates how to create a non volatile data section to save pointers to non volatile dynamic memory See Also allocateMemory Document Version 1 70 5 23 2012 243 Function Specifications getABConfiguration Get DF1 Protocol Configuration Syntax include lt ctools h gt struct ABConfiguration getABConfiguration FILE stream struct ABConfiguration ABConfig
303. ed messages are sent to this station Solicited messages must come from this station Valid values are 0 to 65534 e rtuAddress is the address of the RTU The master station must send messages to this address Valid values are 0 to 65534 e datalinkConfirm enables requesting data link layer confirmations Valid values are TRUE and FALSE e datalinkRetries is the number of times the data link layer will retry a failed message Valid values are 0 to 255 e datalinkTimeout is the length of time the data link layer will wait for a response before trying again or aborting the transmission The value is measured in milliseconds Valid values are 100 to 60000 in multiples of 100 milliseconds Document Version 1 70 5 23 2012 597 Structures and Types e operateTimeout is the length of time an operate command is valid after receiving a select command The value is measured in seconds Valid values are 1 to 6500 e applicationConfirm enables requesting application layer confirmations Valid values are TRUE and FALSE e maximumResponse is the maximum length of an application layer response Valid values are 20 to 2048 The recommended value is 2048 unless the master cannot handle responses this large e applicationRetries is the number of times the application layer will retry a transmission Valid values are 0 to 255 e applicationTimeout is the length of time the application layer will wait for a response before trying again or abo
304. ed sequence number This function returns the sequence number of the record at the start of the data log This function returns the size of a record for the specified data log The log needs to have been previously created with the datalogCreate function This function reads the configuration of the specified data log The log needs to have been previously created with the datalogCreate function This function writes a record to the specified data log The log needs to have been previously created with the datalogCreate function The ctools h file defines the following enumeration types DATALOG_CONFIGURATION DATLOG_STATUS DATALOG_VARIABLE Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Sockets API These functions provide support for the BSD 4 4 Socket API Additional Socket Extension functions are also provided These apply specifically to the SCADAPack 350 TCP IP Stack Refer to the Function Specification section for details on each function listed accept listen bind ntohl connect ntohs getpeername readv getsockname recv getsockopt recvfrom htonl rresvport htons select inet_addr send inet_aton sendto setsockopt shutdown Document Version 1 70 5 23 2012 81 Overview of Programming Functions socket Modbus UO Database The Modbus database is a user defined database that allows data to be shared between Telepace or IEC 61131 1 p
305. edentials Clears all configured usernames and passwords for the specified service Syntax include lt ctools h gt BOOLEAN clearLoginCredentials UINT32 service 1 Parameters service specifies the service for which the credentials are being cleared Description The clearLoginCredentials function removes all configured usernames and passwords from the specified service True is returned if the usernames and passwords were removed False is returned if the usernames and passwords could not be removed Notes Valid services are 0 FTP See Also setLoginCredentials getLoginCredentials Document Version 1 70 5 23 2012 114 Function Specifications clearRegAssignment Clear Register Assignment Telepace firmware only Syntax include lt ctools h gt void clearRegAssignment void Description The clearRegAssignment function erases the current Register Assignment Call this function first before using the addRegAssignment function to create a new Register Assignment To save the Register Assignment with the controller settings in flash memory so that it is loaded on controller reset call flashSettingsSave as shown in the example for addRegAssignment The lIO_SYSTEM resource must be requested before calling this function See Also addRegAssignment Example See example for addRegAssignment Document Version 1 70 5 23 2012 115 Function Specifications clearSFTranslationTable Clear
306. ee Et Modular variables A ae ee as ee Se a Bee Se pt Wi declare session as modular to reduce stack space usage static MODBUS_ SESSION masterSessionl static MODBUS SESSION masterSession2 DS a rh EEN main The main function sets up serial port then sends commands to a Modbus slave This task monitors the command status to check when the response is received This method is useful when other processing can be done while waiting for the response UINT32 mainPriority 100 UINT32 mainStack 4 UINT32 applicationGroup 0 int main void MASTER MESSAGE message BOOLEAN status UINT16 good bad struct prot settings settings struct pconfig portset request _ resource IO SYSTEM enable Modbus protocol on com2 settings type MODBUS_ RTU settings station 1 settings priority 250 settings SFMessaging FALSE set protocol com2 amp settings set communication parameters for com2 portset baud BAUD9600 portset duplex FULL portset parity NONE portset data_bits DATA8 portset stop bits STOP1 portset flow_rx RFC _MODBUS_ RTU portset flow_ tx TFC NONE portset type RS232 portset timeout 600 set_port com2 amp portset release resource IO SYSTEM start second polling task example create task master2 100 applicationGroup 4 Document Version 1 70 5 23 2012 663 Example Programs define ma
307. ef enum DLS CREATED 0 data log created DLS BADID invalid log ID DLS EXISTS log already exists DLS NOMEMORY insufficient memory for log DLS BADCONFIG invalid configuration DATALOG STATUS DATALOG_VARIABLE DialError The data log variable enumerated type is used to specify the type of variables to be recorded in the log typedef enum DLV UINT16 0 16 bit unsigned integer g DLV_INT16 16 bit signed integer DLV UINT32 32 bit unsigned integer DLV_INT32 32 bit signed integer i DLV FLOAT 32 bit floating point DLV_CMITIME 64 bit time DLV DOUBLE 64 bit floating point DLV NUMBER Op TYPES DATALOG VARIABL Fl ER The DialError enumerated type defines error responses from the dial up modem functions and may have one of the following values enum DialError DE NoError 0 Document Version 1 70 5 23 2012 587 Structures and Types DialState E BadConfig E NoModem E InitError E NoDialTone E BusyLine E CallAborted FailedToConnect E CarrierLost E NotInControl E CallCut DEED DUE a DE_NoError returns no error has occurred DE_BadConfig returns the modem configuration structure contains an error DE_NoModem returns the serial port is not configured as a modem port type must be RS232_ MODEM O
308. egisterl UINT16 startingRegister2 UINT16 startingRegister3 UINT16 startingRegister4 Description The addRegAssignment function adds one I O module to the current Register Assignment of type moduleType The following symbolic constants are valid values for module Type AIN_520xT CNTR_ emperature 5410 AIN_520xR DIAG _c AMBattery ommst atus AIN_5501 DIAG _c ontrolle rStatus AIN_5502 DIAG _f orceLE D AIN_5503 DIAG_ PConn ections AIN_5504 DIAG Modbus Status AIN_5505 DIAG_p rotocol Status AIN_5506 DIN_54 01 AIN_5521 DIN_54 02 AIN_generi DIN BA c8 03 Document Version 1 70 5 23 2012 92 Function Specifications AOUT_530 1 AOUT_530 2 AOUT_530 4 AOUT_gen eric2 AOUT_gen eric4 CNFG_590 4Modem CNFG_clea rPortCounte rs CNFG_clea rProtocolCo unters CNFG_IPS ettings CNFG_LED Power CNFG_mod buslpProtoc ol CNFG_MT CPlfSetting s CNFG_MT CPSettings CNFG_PID Block CNFG_port Settings CNFG_prot ocolExtend ed CNFG_prot ocolExtend edEx DIN_54 04 DIN_54 05 DIN_54 14 DIN_54 21 DIN_ge neric16 DIN_ge neric8 DOUT_ 5401 DOUT_ 5402 DOUT_ 5406 DOUT_ 5407 DOUT_ 5408 DOUT_ 5409 DOUT_ 5411 DOUT_ 5415 DOUT_ generic 16 DOUT_ generic 8 SCADA Pack_A OUT Document Version 1 70 5 23 2012 93 Function Specifications CNFG_prot SCADA ocolSetting Pack_lo S werlO CNFG_real SCADA TimeClock Pack_u pper
309. em to reset the timer Checksum Functions To simplify the implementation of self checking communication algorithms the C Tools provide four types of checksums additive CRC 16 CRC CCITT and byte wise exclusive OR The CRC algorithms are particularly reliable employing various polynomial methods to detect communication errors Additional types of checksums are easily implemented using library functions There are two library functions related to checksums Refer to the Function Specification section for details on each function listed checksum Calculates additive CRC 16 CRC CCITT and exclusive OR type checksums crc_reverse Calculates custom CRC type checksum using reverse CRC algorithm Document Version 1 70 5 23 2012 70 Overview of Programming Functions Serial Communication SCADAPack 350 controllers offer three RS 232 serial ports 4203 controllers have two serial ports configurable for RS 232 or RS 485 The ports are configurable for baud rate data bits stop bits parity and communication protocol Default Serial Parameters Ports are configured at reset with default parameters when the controller is powered up in SERVICE mode The ports use stored parameters when the controller is reset in the RUN mode The default parameters are listed below Baud rate SCIENCES Stop bits Hall Ha Protocol Addressing Mode Station Rx flow control Te flow contra Debugging Serial Communication Serial commu
310. en an I O request for the module is processed moduleAddress is the address of the 5606 module Valid values are 0 to 7 dinData is a reference to an array of five UCHAR variables Digital data for the 32 external and 8 internal inputs are written to this array One bit in the array represents each input point The 8 internal inputs indicate if the corresponding analog input value is over range ainData is a reference to an array of eight INT16 variables Analog data are written to this array The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5606Inputs ioRead5606Outputs Example This program displays the values of the first 8 digital inputs and the 5th analog input read from 5606 I O at address 5 include lt ctools h gt define MY EVENT 1 int main void UCHAR dinData 5 INT16 ainData 8 IO STATUS io status BOOLEAN status BOOLEAN done main loop while TRUE add module scan to queue Document Version 1 70 5 23 2012 338 Function Specifications if ioRequest MT_5606Inputs status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT read input data from last status ioRead5 606Inputs 5 check status of last scan if ioStatus MT 5606Inputs status FALSE else if status FALSE
311. enerally independent of the communication parameters of the link with a few exceptions Application programs can initiate communication with remote devices A multiple port controller can be a data concentrator for remote devices by polling remote devices on one port s and responding as a slave on another port s The protocol type communication parameters and station address are configured separately for each serial port on a controller One controller can appear as different stations on different communication networks The port configuration can be set from an application program from the IEC 61131 1 programming software or from another Modbus or DF1 compatible device Protocol Type The protocol type may be set to emulate the Modbus ASCII and Modbus RTU protocols or it may be disabled When the protocol is disabled the port functions as a normal serial port Station Number The TeleBUS protocol allows up to 254 devices on a network using standard addressing and up to 65534 devices using extended addressing Station numbers identify each device A device responds to commands addressed to it or to commands broadcast to every station The station number is in the range 1 to 254 for standard addressing and 1 to 65534 for extended addressing Address 0 indicates a command broadcast to every station and cannot be used as a station number Each serial port may have a unique station number Store and Forward Messaging Store and fo
312. ernal media in use Boolean value shows TRUE if the external media is in use FALSE otherwise Please refer to the chapters dlogTransferStatus Type and dlogMediaStatus Type for the status values DLOGS_SUCCESS is returned if the status information could be retrieved The only reason not be able to do this is because the input parameter dlogID is wrong which would result in the return value DLOGS_BADID Document Version 1 70 5 23 2012 155 Function Specifications dlogID Return the ID of an existing data log Syntax include lt ctools h gt dlogStatus dlogID UCHAR dlogName UINT32 dlogID Parameters The function has these parameters e dlogName is a null terminated string containing the name of the data log e dlogID is a pointer to a variable where the data log ID will be written if the function is successful The function returns e DLOGS_SUCCESS if the data log ID was retrieved e DLOGS_FAILURE if an error during data log ID retrieval occurred e DLOGS_WRONGPARANM if an error due to wrong parameter Description This function maps a data log name to an ID which is used for further operations to the data log To obtain the data log ID the data log under the specified name has to exist Document Version 1 70 5 23 2012 156 Function Specifications dlogNewFile Create a new data log file Syntax include lt ctools h gt dlogStatus dlogNewFile UINT32 dlogID Parameters The function has th
313. es HART_RESPONSE HART_RESULT HAR manufacturerID HAR manufacturerDeviceType HAR preamblesRequested HAR commandRevision transmitterRevision HAR softwareRevision HAR hardwareRevision HAR flags NT32 devicelID HQAQQQQaQaQA0a I D vs Be ee E en a a Ek ART DEVICE The HART_RESPONSE type is a structure containing a response from a HART slave device The command field contains the HART command number The length field contains the length of the data string to be transmitted the byte count in HART documentation The data field contains the data to be sent to the slave typedef struct hartResponse t UINT16 code UINT16 length CHAR Data HART RESPONSE e response is the response code from the device e length is the length of response data e data DATA_SIZE is the data field for the response The HART_RESULT enumeration type defines a list of results of sending a command typedef enum hartResult_t HR_NoModuleResponse 0 HR CommandPending HR_CommandSent HR Response HR _NoResponse HR WaitTransmit HART RESULT e HR_NoModuleResponse returns no response from HART modem module e HR_CommandPending returns command ready to be sent but not sent e HR _CommandSent returns command sent e HR_Response returns response received Document Version 1 70 5 23 2012 611 Structures and Types HART_SETTINGS HART_VARIABLE e HR_NoR
314. escription This function reads the next record from the data log starting at the specified sequence number The function returns the record with the specified sequence number if it is present in the log If the record no longer exists it returns the next record in the log The function has five parameters log D specifies the data log The valid range is 0 to 15 sequenceNumber is sequence number of the record to be read pSequenceNumber is a pointer to a variable to hold the sequence number of the record read pNextSequenceNumber is a pointer to a variable to hold the sequence number of the next record in the log This is normally used for the next call to this function pData is a pointer to memory to hold the data read from the log The function returns TRUE if a record is read from the log The function returns FALSE if the log ID is not valid if the log has not been created or if there are no more records in the log Notes Use the datalogReadStart function to obtain the sequence number of the oldest record in the data log The pData parameter needs to point to memory of sufficient size to hold all the data in a record It is normally necessary to call this function until it returns FALSE in order to read all the data from the log This accommodates cases where data is added to the log while it is being read If data is read from the log at a slower rate than it is logged it is possible that the sequence numbers of the records rea
315. ese parameters e dlogID is the ID of the data log The function returns e DLOGS_SUCCESS if the new data log was created e DLOGS _BADID if the data log ID is invalid Description This function creates a new data log file which becomes the active data log output file The former active file is closed and won t be used for any further output This function is useful to give the data log client the opportunity to create a new data file by its own definition not just when the defined log file size is exceeded A data log client could create daily files for example Notes The new file is not created immediately but when the first data log record is written from the data log buffer by the data log server task Records that remain in the data log buffer when this function is called are not flushed automatically To start the new file with a specific record call dlogFlush before calling this function The oldest file will be deleted if fileRingBuffer mode is enabled and the maximum number of files is reached If fileRingBuffer mode is disabled no new file will be created until older log files are deleted manually This may cause logging to stop although the space in the log buffer may still be available See Also dlogFlush dlogWrite Document Version 1 70 5 23 2012 157 Function Specifications dlogResume Resume writing to a suspended daia log file Syntax include lt ctools h gt dlogStatus dlogResume UINT32 dlog
316. espons e returns no response after all attempts e HR _WaitTransmit returns modem is not ready to transmit The HART_SETTINGS type is a structure containing the configuration for the HART modem module The useAutoPreamble field indicates if the number of preambles is set by the value in the HART_SETTINGS structure FALSE or the value in the HART_DEVICE structure TRUE The deviceType field determines if the 5904 modem is a HART primary master or secondary master device primary master is the recommended setting typedef struct hartSettings t UINT16 attempts UINT16 preambles BOOLEAN useAutoPreamble UINT16 deviceType HART SETTINGS e attempts is the number of command attempts 1 to 4 e preambles is the number of preambles to send 2 to 15 e useAutoPreamble is a flag to use the requested preambles e deviceType is the type of HART master 1 primary 0 secondary The HART_VARIABLE type is a structure containing a variable read from a HART device The structure contains three fields that are used by various commands Not all fields will be used by all commands Refer to the command specific documentation typedef struct hartVariable t float value UINT16 units UINT16 variableCode HART VARIABLE e value is the value of the variable e units are the units of measurement e variableCode is the transmitter specific variable ID 1O_CONFIG Structure The IO_CONFIG structure contains I O Syste
317. essage is received The command status will be set to MM_RSP_TIMEOUT if the response is not received within the specified timeout The application needs to wait for a status of MM_RECEIVED or MM_RSP_TIMEOUT before sending the next master message This function may be used at the same time on the same serial port as a Telepace MSTR element or IEC 61131 1 master function block Notes Refer to the communication protocol manual for more information To optimize performance minimize the length of messages on com3 Examples of recommended uses for com are for local operator display terminals and for programming and diagnostics using the IEC 61131 1 program The lIO_SYSTEM resource needs to be requested before calling this function Document Version 1 70 5 23 2012 506 Function Specifications See Also get_protocol_status clear_protocol_status master_message Example See the Example in the Example Programs chapter under the section Master Message Example Using serialModbusMaster setABConfiguration Document Version 1 70 5 23 2012 507 Function Specifications Set DF1 Protocol Configuration Syntax include lt ctools h gt UINT16 setABConfiguration FILE stream struct ABConfiguration ABConfig Description The setABConfiguration function sets DF1 protocol configuration parameters stream specifies the serial port ABConfig references a DF1protocol configuration structure Refer to the Descriptio
318. essage to Set to zero if not applicable e timeout is the maximum time the forwarding task waits for a valid response from the forward station in tenths of seconds Valid values are 0 to 65535 SFTranslationStatus TASKINFO The SFTranslationStatus structure contains information about a Store and Forward Translation table entry It is used to report information about specific table entries struct SFTranslationStatus UINT16 index UINT16 code F e index is the location in the store and forward table to which the status code applies e code is the status code It is one of SF_VALID SF_INDEX_OUT_OF_RANGE SF_NO_TRANSLATION SF_PORT_OUT_OF_RANGE GE GTATION OUT_OF_RANGE SF_ALREADY_DEFINED or SF_INVALID FORWARDING _IP macros The TASKINFO type is a structure containing information about a task Task Information Structure typedef struct taskInformation tag UINT16 taskID UINT16 priority UINT16 status UINT16 requirement UINT16 error UINT16 type TASKINFO e _taskID is the identifier of the task e priority is the execution priority of the task e status is the current execution status of the task This may be one of TS_READY TS_EXECUTING TS_WAIT_ENVELOPE TS_WAIT_EVENT TS_WAIT_MESSAGE or TS_WAIT_RESOURCE macros e requirement is used if the task is waiting for an event or resource If the status field is TS_WAIT_EVENT then requirement indicates on which event Document Version 1 70
319. et controller Each step uses separate tools To demonstrate these steps a sample program will be prepared Traditionally the first program that is run on a new C compiler is the hello world program It prints the message hello world Hey who are we to be different Document Version 1 70 5 23 2012 21 Getting Started Create a New C Application Framework Any editor may be used to write and edit the application program for the SCADAPack controllers Copy C Application Framework Review appstart cpp Edit main cpp Begin by making a copy of the C application framework using the IEC 61131 1 sample application or the Telepace sample application By default the samples are installed at C program files Control Microsystems CTools Controller Framework Applications Make a copy of either the IEC 61131 1 or Telepace folder for your application For example e Copy files from C program files Control Microsystems CTools Controller Framework Applications IEC 61131 1 e Copy files to C projects SP350 hello The appstart cpp file defines the basic settings for the application such as stack size and main task priority Applications typically can use the settings in this file without modification Open appstart cpp to review these application settings Priority of the task main Priority 100 is recommended for a continuously running task A task with priority gt 100 will never be given the CPU
320. eters and starts protocol setProtocolSettings Sets extended addressing protocol parameters for a serial port setSFTranslation Write store and forward translation table entry start_protocol Starts protocol execution based on stored parameters Communication Protocols Enumeration Types The ctools h file defines the enumeration type ADDRESS_MODE Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Communication Protocols Structures The ctools h file defines the structures Protocol Status Information Protocol Settings Extended Protocol Settings Store and Forward Message and Store and Forward Status Refer to the C Tools Structures and Types section for complete information on structures and enumeration types DNP Communication Protocol DNP the Distributed Network Protocol is a standards based communications protocol developed to achieve interoperability among systems in the electric utility oil amp gas and water waste water industries This robust flexible non proprietary protocol is based on existing open standards to work within a variety of networks The IEEE has recommended DNP for remote terminal unit to intelligent electronic device messaging DNP can also be implemented in any SCADA system for efficient and robust communications between substation computers RTUs IEDs and master stations over serial or LAN based systems DNP offers flexibility and functionalit
321. etessinneteevtvers 625 DEG ele EEEE E E ET 625 PORT CHARACTERISTICS KAEESRREEAEEEREEKSESSEESESEEEEESAEEE EUREN EAEAEEAEAEAEE A 626 PSLATUS at N EN N A tiaras ytbevavecnente vines vaynonenbevd yest vaya ENEE EE ENEE ee de 627 READS TA TU S Osten et ca vguset ca aare aea pectenet en EES arean naaar Dapena EPES ENE Eri EER 627 FOULING HE TEE 628 DF ATIRANSLATION WEE 628 SFUTRANSLATIONS EX E E EAA 629 SF Translation Statt eEeEEKAKStAKEERRREEKAESEAESERERREEKAESEALEESR ENEE AESEALEESEERNEEENEEE SEAN 630 NR le e ET 630 EE Lu e e DEE 631 TUM EE 631 ue nie seco EA ANENE 632 CUT OV Ellis os res Peat AA E R NEEE E EEE E E 632 VERSION P 2ex ruseegchegeeggretShaEERSUESEEESUEESEREEUESEREEEEASEEEREEASE ERR EASEERESEAEESESEAEEEEESEN 632 WRITES HEN RE 632 Example e Le 634 Connecting with a Remote Controller Example cccceeeceeeeeeeeeeeeeteeeeeeees 634 Create Task Example cccccccccececeneeeeeeeeeeeeeccaeeeeeeeeeeeeceaaaeeeeeeeeseteccaeeeeeees 635 DataLog Exame 637 Get Program Status Example seseeseessseerreseessnirrrttssstnrrrnnrtnssnrnnnnnsssnnnnnn 646 Get Task Status Example 00 ccececeeeeeeeeeeeeeeeeccneeeeeeeeeeeeecaaaeeeeeeeeseeessaaeeeeeees 647 Handler Function Exvample 648 Install Serial Port Handler Exame 651 Install Clock Handler Example 00 ccccceeeeeeeeeeeeeeenceeeeeeeeeeeeeaaeeeeeeeeeeeeesaaaes 652 Install Database Handler Example ssssssssssseeeesssssssirrrrsssssrrrrrnrsssssrnrrnnssssns
322. ettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Document Version 1 70 5 23 2012 435 Function Specifications mTcpSetinterfaceEx Set Modbus IP Interface Extended Settings Syntax include lt ctools h gt BOOLEAN mTcpSetInterfaceEx COM INTERFACE ifType MTCP_IF SETTINGS EX pSettings 1 Description This function sets the interface settings used for Modbus IP protocols including Enron Modbus settings The function has two parameters e ifType specifies the interface The valid value is CIF_Ethernet1 e pSettings is a pointer to a Modbus IP interface extended settings structure that contains the desired settings The function returns TRUE if the specified interface and settings are valid and FALSE otherwise To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Notes The IO_SYSTEM resource needs to be requested before calling this function with Telepace firmware The settings take effect for all new connections made thereafter on the specified interface Existing connections are not affected Document Version 1 70 5 23 2012 436 Function Specifications mTcpSetProtocol Set Modbus IP Protocol Settings Synt
323. extern C add prototypes here Document Version 1 70 5 23 2012 681 Porting Existing C Tools Applications Paste your code here e Delete the additional stub function main at the end of the file main cpp The C Tools require main to have the prototype int main void Change the syntax of main so that it returns the data type int instead of void The returned int value is not accessible to the user and so any value may be returned or none at all Replace Older C Tools Headers with ctools h If the ported application used SCADAPack C Tools version 2 12 or older the program C files will likely have include statements with C Tools header files such as protocol h primitiv h etc Replace all these C Tools include statements in all program C files with just one include statement include lt ctools h gt Replace Partially Supported and Unsupported Functions Build the Application Test the Application Existing programs may use some functions that are partially supported or unsupported on the SCADAPack 350 and 4203 controllers The program must be changed to use the new functions For a list of the functions affected refer to the sections Partially Supported C Tools Functions The SCADAPack C Tools use a command line to compile and link a C application The sample application includes the command file build bat to do this Please see the section Application Development for more details on editing build
324. f status switch cmdStatus case MM CONNECTING break case MM CONNECTED mode MIP_SEND MESSAGE break default are error codes remaining status codes mode CE break MIP_DISCONNE Document Version 1 70 5 23 2012 667 Example Programs sent successfully error codes amp cmdStatus response break case MIP SEND MESSAGE send master IP message cmdStatus mTcpMasterMessage connectID remotelIP protocolType function slaveStation slaveRegister masterRegister length timeout 1 switch cmdStatus case MM CONNECTING case MM DISCONNECTING case MM DISCONNECTED last command is still being not ready for new message break case MM SENT message send started mode MIP WAIT FOR RESPONSE break default remaining status codes are message not sent mode MIP DISCONNECT break break case MIP WAIT FOR RESPONSE check master command status status mTcpMasterStatus connectID if status switch cmdStatus case MM SENT still waiting for break case MM RECEIVED Document Version 1 70 5 23 2012 668 Example Programs response received successfully send next messag mode MIP SEND MESSAGE break default remaining status codes are error codes mode
325. f the configuration was read and FALSE if an error occurred Notes This function does not return the configuration for the Unsolicited Back Off Time Use the function dnoGetUnsolicitedBackoffTime to get the Unsolicited Back Off Time configuration See Also dnpSaveConfiguration Example The following program demonstrates how to configure DNP for operation on com2 To illustrate creation of points it uses a sequential mapping of Modbus registers to points This is not required Any mapping may be used int main void UINT16 index loop index struct prot settings settings protocol settings dnpConfiguration configuration configuration settings Xy dnpBinaryInput binaryInput binary input settings Si dnpBinaryOutput binaryOutput binary output settings Si dnpAnalogInput analogInput analog input settings xf dnpAnalogOutput analogOutput analog output settings Si dnpCounterInput counterInput counter input settings xf Stop any protocol currently active on com port 2 get_protocol com2 amp settings settings type NO PROTOCOL set protocol com2 amp settings Document Version 1 70 5 23 2012 180 Function Specifications Load the Configuration Parameters configuration configuration configuration configuration configuration configuration masterAddress rtuAddress datalinkConfirm datalinkRetries DEFAULT DLINK RE
326. face function is used to obtain the interface settings for Modbus IP protocols on the specified interface If the selected interface is invalid FALSE is returned otherwise TRUE is returned and the settings are copied to the structure pointed to by pSeitings The valid value for ifType is CIF_Ethernet1 The enumeration type COM_INTERFACE and the structure MTCP_IF_SETTINGS are described in the Structures and Types section Document Version 1 70 5 23 2012 431 Function Specifications mTcpGetinterfaceEx Get Modbus IP Interface Extended Settings Syntax include lt ctools h gt BOOLEAN mTcpGetInterfaceEx COM_INTERFACE ifType MTCP_IF SETTINGS EX pSettings 1 Description This function returns the interface settings used for Modbus IP protocols including Enron Modbus settings The function has two parameters e ifType specifies the interface The valid value is CIF_Ethernet1 e pSettings is a pointer to a Modbus IP interface extended settings structure The settings are copied to this structure The function returns TRUE if the specified interface is valid and FALSE otherwise The enumeration type COM_INTERFACE and the structure MTCP_IF_SETTINGS_EX are described in the Structures and Types section Document Version 1 70 5 23 2012 432 Function Specifications mTcpGetProtocol Get Modbus IP Protocol Settings Syntax include lt ctools h gt BOOLEAN mIcpGetProtocol IP_PROTO
327. ference Instead of executing the required I O operation immediately before returning from the function the I O operation is added to the I O System queue as an I O request and is performed by the I O System architecture in parallel with application program execution Notification of the completion of an I O request may be obtained using the ioNotification function hartlO Request a hart I O module scan The scan reads data from the 5904 interface module processes HART responses processes HART commands and writes commands and configuration data to the 5904 interface module Request all UO points to be cleared The C Tools function jiffy is replaced with the readStopwatch function This function returns the time in milliseconds Existing programs need to be modified to call the new function and to convert any timing constants to milliseconds The C Tools function setjiffy is not supported Elapsed time from a particular point can be measured by saving the time at the start of the interval rather than setting the clock to zero Document Version 1 70 5 23 2012 687 Porting Existing C Tools Applications Real Time Clock Functions The getclock function has a new syntax A clock structure is no longer returned by the function Instead a pointer to a clock structure is passed as an argument The getclock function is documented in the Function Specifications section Get Task Information Function The getTaskInfo function
328. fication section for details on each function listed These functions are supported by Telepace firmware only setOutputsInStopMode Sets the doutsinStopMode and aouts nStopMode control flags to the specified state getOutputsInStopMode Copies the values of the output control flags into the integers pointed to by doutsinStopMode and aouts InStopMode clearAllForcing Removes forcing conditions from UO database registers setForceFlag Sets the force flag s for the specified database register s getForceFlag Copies the value of the force flag for the specified database register overrideDbase Writes a value to the I O database even if the database register is currently forced Document Version 1 70 5 23 2012 66 Overview of Programming Functions Status LED and Output Macros The ctools h file defines the following macros for use with the status LED and digital output Refer to the C Tools Macros section for details on each macro listed S_MODULE_FAILURE Status LED code for I O module communication failure SG NORMAL Status LED code for normal status LED Indicators Functions An application program can control three LED indicators The RUN LED green indicates the execution status of the program The LED can be on or off It remains in the last state until changed The STAT LED yellow indicates error conditions It outputs an error code asa binary sequence The sequence repeats until a new error code is output If the er
329. fications ioRead541 4Inputs Read 5414 module inputs Syntax include lt ctools h gt BOOLEAN ioRead5414Inputs UINT16 moduleAddress UCHAR amp dinData 2 Description This function reads buffered data from the digital inouts5414 module Buffered data are updated when an I O request for the module is processed moduleAddress is the address of the 5414 module Valid values are 0 to 15 dinData is a reference to an array of two UCHAR variables Digital data for the 16 inputs are written to this array One bit in the array represents each input point See Also ioWrite54140utputs Example This program displays the values of the first 8 digital inputs include lt ctools h gt include nvMemory h define MY EVENT void main void UCHAR dinData 2 IO STATUS io_status BOOLEAN status main loop while TRUE add module scan to queue if 1oRequest MT_5414Inputs 0 status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT vead input data from last scan status ioRead5414Inputs 0 dinData Document Version 1 70 5 23 2012 324 Function Specifications check status of last scan if i1oStatus MT _5414Inputs 0 amp io status status FALSE else if io status commStatus status FALSE print data fprintf coml status u Dins
330. file built earlier For example C Applications Telepace Hello myApp out and click OK You need to use a file built using a Telepace framework with Telepace firmware Document Version 1 70 5 23 2012 29 Getting Started Executing the Program Click Write to write the file to the controller Connect a terminal to com2 on the controller It will display the output of the program Set the communication parameters to 9600 baud 8 data bits 1 stop bit and no parity From the C C Program Loader dialog click on the Run button to execute the program The hello world message will be displayed on the terminal When multiple C Applications are loaded and the controller is power cycled the C Applications are restarted in the order they were first loaded to the controller Loading and Executing the C Application Using IEC 61131 1 The IEC 61131 1 C C Program Loader transfers executable files from a PC to the controller and controls execution of programs in the controller Controller Initialization The controller should be initialized when beginning a new programming project or when it is desired to start from default conditions It is not necessary to initialize the controller before every program load To completely initialize the controller perform a Cold Boot When the controller starts in the cold boot mode The default serial communication parameters are used The IEC 61131 1 application program is eras
331. fined interval or time slice Because the time slicing is performed by the kernel of the operating system it is not necessary anymore for the tasks to call explicitely release_processor to release CPU time to other tasks of the same priority In contrary it can harm When a task expects a fair share of the CPU calling release_processor before the end of the time slice puts it immediately at the end of round robin queue Therefore the CPU time share can be significantly reduced The function release_processor still makes sense if the calling task does not have anything to do for the moment A new function sleep_processor is introduced to release CPU for a certain time Task Management Functions There are five RTOS functions for task management Refer to the Function Specification section for details on each function listed create_task Create a task and make it ready to execute end_task Terminate a task and free the resources and envelopes allocated to it end_application Terminate application program type tasks This function is used by communication protocols to stop the application program prior to loading new code installExitHandler Specify a function that is called when a task is ended with the end_task or end_application functions getTaskinfo Return information about a task Task Management Structures The ctools h file defines the structure Task Information Structure for task management information Refer to the C Tools
332. flag has been set in the flags parameter 1 is returned with the socket error being set to EWOULDBLOCK The select call may be used to determine when it is possible to send more data Parameters socketDescriptor The socket descriptor to use to send data bufferPtr The buffer to send bufferLength The length of the buffer to send toPtr The address to send the data to toLength The length of the to area pointed to by toPtr flags See below The flags parameter is formed by ORing one or more of the following MSG_DONTWAIT Don t wait for data send to complete but rather return immediately MSG_DONTROUTE The SO_DONTROUTE option is turned on for the duration of the operation Only diagnostic or routing programs use it Document Version 1 70 5 23 2012 504 Function Specifications Returns Value Meaning gt 0 Number of bytes actually sent on the socket 1 An error occurred sendto will fail if EBADF The socket descriptor is invalid ENOBUFS There was insufficient user memory available to complete the operation EHOSTUNREACH No route to destination host EMSGSIZE The socket requires that message be sent atomically and the message was too long EPROTOTYPE TCP protocol requires usage of send not sendto EWOULDBLOCK The socket is marked as non blocking and the send operation would block Document Version 1 70 5 23 2012 505 Function Specifications serialModbusMaster Send Modbus Command Synta
333. function Setting the protocol type to NO PROTOCOL ends the protocol task and frees the stack resources allocated to it Add a call to modemNotification when writing a custom protocol Extended addressing and the Enron Modbus station are available on the Modbus RTU and Modbus ASCII protocols only See the TeleBUS Protocols User Manual for details Example This code fragment sets protocol parameters for the com2 serial port include lt ctools h gt PROTOCOL SETTINGS EX settings settings type MODBUS_RTU Document Version 1 70 5 23 2012 529 Function Specifications settings station settings priority settings SFMessaging settings mode settings enronEnabled settings enronStation li 250 FALSE AM standard TRUE 4 request resource IO SYSTEM setProtocolSettingsEx com2 amp settings release resource IO SYSTEM Document Version 1 70 5 23 2012 530 Function Specifications setSFTranslation Write Store and Forward Translation Syntax include lt ctools h gt struct SFTranslationStatus setSFTranslation UINT16 index SF TRANSLATION pTranslation Description Instead of using the setSFTranslation function use the setSFTranslationEx function which supports translations with a timeout and with authentication Otherwise a default timeout of 10 seconds is set for all forwarded commands The setSFTranslation function copies the structure
334. function has no return value Document Version 1 70 5 23 2012 400 Function Specifications ipReadFriendlyListControl Get the status of the friendly IP list Syntax UCHAR ipReadFriendlyListControl void Description This function returns the status of friendly IP list control The function has no parameters The function returns TRUE if friendly IP list is enabled and FALSE otherwise See Also ipWriteFriendlyListControl Document Version 1 70 5 23 2012 401 Function Specifications ipReadFriendlylPListEntry Read one entry in the friendly IP list Syntax BOOLEAN ipReadFriendlyIPListEntry UINT16 index IP_ADDRESS pIpAddressStart IP ADDRESS pIpAddressEnd 1 Description This function reads an entry from the Friendly IP List index specifies the location in the list and needs to be less than or equal to the Friendly IP List size plpAddressStart and plpAddressStart are pointers to IP addresses they are written by this function The function retu See Also rns TRUE if successful and FALSE if the index is invalid ipReadFriendlyIPListSize ipWriteFriendlylPListEntry ipWriteFriendlylPListSize Document Version 1 70 5 23 2012 402 Function Specifications ipReadFriendlyIPListSize Read the size of the friendly IP list Syntax UINT16 ipReadFriendlyIPListSize void Description This function reads the total number of active entries in the Friendly IP List
335. function returns FALSE if the module number is invalid Notes The HART_DEVICE structure needs to be initialized using hartCommandoO or hartCommand11 The function returns immediately after the command is sent The calling program needs to wait for the response to be received Use the hartStatus command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command The code field of the HART_VARIABLE structure not changed Command 1 does not return a variable code See Also hartCommand2 hartStatus hartSetConfiguration Document Version 1 70 5 23 2012 287 Function Specifications hartCommand2 Read Primary Variable Current and Percent of Range Syntax include lt ctools h gt BOOLEAN hartCommand2 UINT16 module HART DEVICE const device HART VARIABLE pvCurrent HART VARIABLE pvPercent Description This function reads the primary variable PV as current and percent of range of a HART device using command 2 The function has four parameters the module number of the 5904 module 0 to 3 the device to be read a pointer to the PV current variable and a pointer to the PV percent variable The pvCurrent and pvPercent variables are updated when the response is received by the 5904 interface The pvCurrent and pvPercent variables must be static modular or global variables A pvCurrent and pvPercent variable should
336. g Get DNP Binary Input Configuration Syntax include lt ctools h gt BOOLEAN dnpGetBIConfig UINT16 point dnpBinaryInput pBinarylInput Description The dnpGetBlConfig function reads the configuration of a DNP binary input point The function has two parameters the point number and a pointer to a binary input point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveBlConfig Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 175 Function Specifications dnpGetBiConfigEx Read DNP Binary Input Extended Point Syntax BOOLEAN dnpGetBIConfigEx UINT16 point dnpBinaryInputEx pBinarylInput 1 Description This function reads the configuration of an extended DNP Binary Input point The function has two parameters the point number and a pointer to an extended binary input point configuration structure The function returns TRUE if the configuration was successfully read It returns FALSE if the point number is not valid if the configuration is not valid or if the DNP configuration has not been created This function supersedes dnpGetBIConfig Document Version 1 70
337. g modemAbort See Also modemAbortAll modemDial Example Refer to the Examples in the Functions Overview section Document Version 1 70 5 23 2012 418 Function Specifications modemAbortAll Unconditionally Terminate All Dial up Connections Syntax include lt ctools h gt void modemAbortAl1l1 void Description The modemAbortAll function unconditionally terminates all dial up connections connections in progress or modem initializations started by the C application The connections or initializations are terminated only if they were started from a C application Connections made from a Ladder Logic application and answered calls are not terminated This function can be used in a task exit handler Notes A pause of a few seconds is required between terminating a connection and initiating a new call This pause allows the external modem time to hang up Use this function in a task exit handler to clean up any open dial up connections or modem initializations If executing end_task from another task ends a task modem connections or initializations must be aborted in the exit handler Otherwise the reservation ID for the port remains valid No other task or Ladder Logic program may use modem functions on the port Not calling modemAbort or modemAbortAll in the task exit handler may result in the port being unavailable to any programs until the controller is reset The modem connection or initialization is aut
338. h gt BOOLEAN mTcpMasterDisconnect UINT32 connectID Description The mTcpMasterDisconnect function signals the mastering task to tell it to disconnect from the remote slave and end the task FALSE is returned if the specified connectID is invalid otherwise a TRUE is returned FALSE is also returned if the master task has not completed the last command In this case the mTcpMasterDisconnect function needs to be called repeatedly until TRUE is returned After calling the mTcpMasterDisconnect function the function mTcpMasterStatus may be used to determine the progress of the disconnect These functions may not be called after calling the function mTcpMasterClose with the same connectID The results of such a call are unpredictable as the connect D may have been re used already for a new connection After calling mTcpMasterDisconnect successfully call mTcpMasterClose to return the connection ID to the pool of available connections Example See the Example in the Example Programs chapter under the section Master IP Message Example Document Version 1 70 5 23 2012 439 Function Specifications mTcpMasterMessage Send a Modbus IP Master Message Syntax include lt ctools h gt MODBUS CMD STATUS mTcpMasterMessage UINT32 connectID IP ADDRESS remoteIP IP PROTOCOL TYPE protocolType UINT16 function UINT16 slaveStation UINT16 slaveRegister UINT16 masterRegister UINT16 length UINT16 timeout Descriptio
339. haracters in the message e The response parameter is a pointer to the first character of a buffer to hold the response The function should write the response into this buffer The buffer is 253 characters long The first character of the buffer is the function code of the message The format of the data after the function code is defined by the function code e The responseLength parameter is a pointer to the length of the response The function should set the length of the response using this pointer The length is the number of characters placed into the response buffer The function returns one of four values The first causes a normal response to be sent The others cause an exception response to be sent e NORMAL indicates the response and responseLength have been set to valid values The Modbus protocol will add the station address and checksum to this string and transmit the reply to the master station e LLEGAL_FUNCTION indicates the function code in the message was understood but the function was deemed illegal Document Version 1 70 5 23 2012 280 Function Specifications e LLEGAL_DATA_ADDRESS indicates the function code in the message was understood but that the command referenced an address that is not valid The Modbus protocol will return an Illegal Data Address exception response e ILLEGAL_DATA_VALUE indicates the function code in the message was understood but that the command included data that is not val
340. hardware is ready If queuing is enabled the characters are held in the transmit buffer until queuing is disabled If the buffer fills queuing is disabled automatically port specifies the serial port If it is not valid the function has no effect mode specifies the queuing control It may be DISABLE or ENABLE Notes Queuing is often used with communication protocols that use character timing for message framing Its uses in an application program are limited Document Version 1 70 5 23 2012 461 Function Specifications readBoolVariable Read IEC 61131 1 Boolean Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN readBoolVariable UCHAR varName UCHAR value Description This function returns the current value of the specified boolean variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the variable value is written to the unsigned char value pointed to by value If the variable is not found or if the IEC 61131 1 Symbols Status is invalid FALSE is returned and the current value is left unchanged The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application
341. he TeleBUS Driver sets the target slave number Ignore the value in this field e From the Communication port dropdown list box select TeleBUS Driver If the TeleBUS Driver is not selectable from the Communication port drop down menu then the Control Microsystems Extensions have not been installed Refer to the installation CD jacket for installation information The Time out Seconds edit box sets the length of time in seconds to wait for a response to a command It is an integer in the range 1 to 255 seconds The default value is 3 The Retries edit box sets the number of communication attempts before a message is aborted It is an integer in the range 1 to 20 The default value is 3 e Select the Setup button When selected the PC Communication Settings dialog is displayed e Click the Default button This will ensure the serial parameters for the PC are the same as the parameters on each of the serial ports e Inthe Port dropdown selection select the serial port you are using on your PC to communicate with the controller Document Version 1 70 5 23 2012 31 Getting Started e Connect com3 to the PC serial port using an RS 232 serial communication cable This cable is a null modem or computer to computer cable Loading the Application To load the Hello C application into the controller e From the Controller menu select the C C Program Loader command e Select the Add button and use the Browse button to locat
342. he allocate_envelope function obtains an envelope from the operating system If no envelope is available the task is blocked until one becomes available The allocate_envelope function returns a pointer to the envelope Notes Envelopes are used to send messages between tasks The RTOS allocates envelopes from a pool of free envelopes It returns envelopes to the pool when they are de allocated An application program needs to check that unneeded envelopes are de allocated Envelopes may be reused See Also deallocate_envelope Example include lt ctools h gt extern UINT32 other task id void taskl void letter nvelop to another task deallocate th nvelop send a message assume it will Bey letter allocate envelope letter gt destination other task id letter gt type MSG DATA letter gt data 5 send message letter receive a message from any other task UI letter receive messag process the data here deallocate envelope letter JK the rest of the task Document Version 1 70 5 23 2012 104 Function Specifications allocateMemory Allocate Non Volatile Dynamic Memory Syntax include lt ctools h gt BOOLEAN allocateMemory void ppMemory UINT32 size Description The allocateMemory function allocates the requested memory from the system memory pool The pool is a separate area of memory from the system heap Memory
343. he communication path of the master command e g the slave interface which receives the command and the forwarding interface to forward the command The response to the command is automatically returned to master through the same communication path in reverse Additional entries in the Store and Forward Table are not needed to describe the response path The lIO_SYSTEM resource needs to be requested before calling this function To save the Store and Forward Table with the controller settings in flash memory so that it is loaded on controller reset call flashSettingsSave as shown below save Store amp Forward table with controller settings request _ resource FLASH MEMORY flashSettingsSave CS_ RUN release resource FLASH MEMORY Translations may involve any combination of interfaces The interfaces may be running a Serial Modbus or Modbus IP protocol Serial Modbus Interface Serial Modbus Interface Modbus IP Interface Serial Modbus Interface Serial Modbus Interface Modbus IP Network e g com1 com2 or com3 e g Modbus TCP Modbus RTU over UDP or Modbus ASCII over UDP Modbus IP Interface Modbus IP Network e g Ethernet e g Modbus TCP Modbus RTU over UDP or Modbus ASCII over UDP Modbus IP Network as Forwarding Interface When forwarding to a TCP or UDP network the protocol type is selected for the forwardinterface in the SF_TRANSLATION structure The IP Stack automatically determine
344. he controller is reset It is a permanent storage area which is maintained during power outages Refer to the Functions Overview section for more information The IO_SYSTEM resource needs to be requested before calling this function Example include lt ctools h gt int main void request resource IO SYSTEM setdbase MODBUS 40001 102 Turn ON the first 16 coils setdbase LINEAR START COIL 255 Write to a 16 bit register setdbase LINEAR 3020 240 Document Version 1 70 5 23 2012 512 Function Specifications Write to the 12th holding register setdbase LINEAR START HOLDING 330 Write to the 12th holding register setdbase LINEAR START HOLDING 330 release resource IO SYSTEM Document Version 1 70 5 23 2012 513 Function Specifications Setdbase Handler Function User Defined Setdbase Handler Function The setdbase handler function is a user defined function that handles writing to Modbus addresses not assigned in the IEC 61131 1 Dictionary The function can have any name setdbaseHandler is used in the Description below Syntax include lt ctools h gt BOOLEAN setdbaseHandler UINT16 address INT16 value Description This function is called by the setdbase function when one of the following conditions apply e There is no IEC 61131 1 application downloaded or e There is no IEC 61131 1 variable
345. he last section e Copy user written H files if any from the SCADAPack application to the framework directory Do NOT copy the SCADAPack ctools h file or any other C Tools header files e g older SCADAPack C Tools headers such as protocol h The new ctools h is already in the framework directory e For each user written H file copied to the framework directory in step 2 make sure that the following statements are included at the top of each header file ifdef cplusplus extern C endif And also make sure that the following statements are included at the bottom of each header file ifdef cplusplus endif e Edit the SCADAPack application file that contains the function main Open this file and copy its contents beginning after the included headers and paste this into the framework file main cpp after the prototypes as shown below If there are additional headers included copy these include statements to the main cpp file next Be SSeS See eee Se See ee Se eee ee Se eee Ee See SCADAPack 350 and 4203 C Application Main Program Copyright 2006 Control Microsystems Inc Fy sh ie E EE te Sa See Se Wi include lt ctools h gt include nvMemory h 2365 2 2 EE EE EE EE Se See a eee a C Function Prototypes eS ee SS ee Se Soe ae Se ee ee ee ee Oe See Wi add prototypes here Ses Se et a ee eS Se ee Ehe SO ee ee C Function Prototypes EE pn fn eh SE pens Nu Bese og ae E in se cen eae Be
346. he log without data loss Document Version 1 70 5 23 2012 159 Function Specifications dlogSuspend Suspend writing to the data log file from the data log buffer Syntax include lt ctools h gt dlogStatus dlogSuspend UINT32 dlogID Parameters The function has these parameters e dlogID is the ID of the data log The function returns e DLOGS_SUCCESS if logging was suspended e DLOGS_BADID if the data log ID is invalid e Description This function suspends the writing to data log files and closes any open files After successful suspension removal or exchange of an external drive is safe as is moving files to another device Nevertheless further calls to dlogWrite are still allowed and will succeed as long as records fit in the buffer dlogSuspend calls dlogFlush to move data log buffer records as possible to file before the output is suspended A repeated call to dlogSuspend has no effect See Also dlogResume Document Version 1 70 5 23 2012 160 Function Specifications dlogWrite Write to a data log Syntax include lt ctools h gt dlogStatus dlogWrite UINT32 dlogID UCHAR pRecord Parameters The function has these parameters e dlogID is the ID of the data log e pRecord is a pointer to a data record to write to the log The function returns e DLOGS_ SUCCESS if the write was successful e DLOGS_BUFFERFULL if the record could not be written because of a full buffer e D
347. he specified timer variable HART Communication The HART protocol is a field bus protocol for communication with smart transmitters The HART protocol driver provides communication between SCADAPack controllers and HART devices The protocol driver uses the model 5904 HART modem for communication Four HART modem modules are supported per controller The driver allows HART transmitters to be used with C application programs and with Realflo The driver can read data from HART devices HART Command Functions The ctools h file defines the following HART command related functions Refer to the Function Specification section for details on each function listed hartlO Reads data from the 5904 interface module processes HART responses processes HART commands and writes commands and configuration data to the 5904 interface module Document Version 1 70 5 23 2012 85 Overview of Programming Functions hartCommand hartCommandO hartCommand1 hartCommand2 hartCommand3 hartCommand11 hartCommand33 hartStatus hartGetConfiguration hartSetConfiguration hartPackString hartUnpackString HART Command Macros send a HART command string and specify a function to handle the response read unique identifier using short address algorithm read primary variable read primary variable current and percent of span read primary variable current and dynamic variables read unique identifier associated with tag read specified transm
348. ibraries that are installed with C Tools Documentation of these functions is included in the installed document GNU Documentation The functions listed below are recommended for file access clearerr closedir fclose feof fflush fgetc fgets fopen fprintf fputc fputs fread fseek ftell fwrite getc gets mkdir opendir putc puts readdir remove rmdir Document Version 1 70 5 23 2012 87 Function Specifications Function Specifications This section of the user manual contains specifications for using each of the available functions The functions in the sections that follow are available for use in C programs These functions are available for use with both Telepace and IEC 61131 1 firmware unless otherwise noted Functions Supported by Telepace Only The following functions are only supported by C Tools running on Telepace firmware addRegAssignment clearRegAssignment getForceFlag getOutputsInStopMode overrideDbase setForceFlag setOutputsInStopMode Functions Supported by IEC 61131 1 Only The following functions are only supported by C Tools running on IEC 61131 1 firmware Dbase Handler Function installDbaseHandler installSetdbaseHandler readBoolVariable readintVariable readMsgVariable readRealVariable readTimerVariable read_timer_info Setdbase Handler Function writeBoolVariable writelntVariable Document Version 1 70 5 23 2012 88 Function Specifications e wri
349. id The Modbus protocol will return an Illegal Data Address exception response e FUNCTION _NOT_HANDLED must be returned by the function handler if the function was not handled If no installed handler can process the function then an ILLEGAL_FUNCTION exception response will be sent Function Codes Used The following function codes are currently used by the TeleBUS Modbus compatible protocol All other function codes are available for use For maximum compatibility with other Modbus and Modbus compatible devices it is recommended that codes in the user defined function code range be used first 6 Modbus standard Write a single holding register 86 TeleBUS extension Used by Telepace 68 TeleBUS extension Usedby Telepace 89 TeleBUS extension Used by Telepace Notes One handler function is used for all serial ports Only one port will be active at any time Therefore the function does not have to be re entrant The handler function is called from the Modbus protocol task This task may pre empt the execution of another task If there are shared resources the handler function must request and release the appropriate resources for proper operation Document Version 1 70 5 23 2012 281 Function Specifications The station address is not included in the message or response string It will be added to the response string before sending the reply The checksum is not included in the message or the respo
350. id otherwise TRUE is returned Document Version 1 70 5 23 2012 349 Function Specifications ioReadAout5303 Read Data From 2 point 5303 Analog Output Module Syntax include lt ctools h gt BOOLEAN ioReadAout5303 INT16 amp data 2 Description This function reads buffered data used for the 2 point 5303 analog output module Buffered data are written using the ioWriteAout5303 function The function has one parameter a reference to an array of two INT16 variables The buffered data are copied to the array The function needs to returns TRUE Document Version 1 70 5 23 2012 350 Function Specifications ioReadCounter4 Read Data From 4 point Counter Input Module Syntax include lt ctools h gt BOOLEAN ioReadCounter4 UINT16 moduleAddress UINT32 amp data 4 Description This function reads buffered data from the 4 point counter input module at the specified module address Buffered data are updated when an I O request for the module is processed The function has two parameters the module address and a reference to an array of four UINT32 variables If the moduleAddress is valid data are copied to the array The valid range for moduleAddress is 0 to 15 The maximum count is 4 294 967 295 Counters roll back to 0 when the maximum count is exceeded The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 351
351. id otherwise TRUE is returned See Also ioRead5505O0utputs ioWrite5505Outputs Example This program displays the values of the 16 internal digital inputs and the 4th analog input read from 5505 I O at address 5 include lt ctools h gt define MY EVENT 1 int main void UINT16 dinData float ainData 4 IO STATUS io status BOOLEAN status BOOLEAN done main loop while TRUE add module scan to queue if 1o0Request MT_5505Inputs 5 status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT vead input data from last scan Document Version 1 70 5 23 2012 330 Function Specifications status ioRead5505Inputs 5 dinData ainData check status of last scan if i1o0Status MT_ 5505Inputs 5 amp io status status FALSE else if io status commStatus status FALSE print data if done fprintf coml status Su Dins 0 to 15 X Ain 3 status dinData ainData 3 done TRUE r gf r n release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 331 Function Specifications ioRead5505Outputs Read 5505 Configuration Syntax include lt ctools h gt BOOLEAN ioRead55050utputs UINT16 moduleAddress UINT16 amp inputType 4 UINT16 G amp inputFi
352. id address types and ranges Type Address Ranges Registe r Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001 to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1 Notes Force Flags are not modified when the controller is reset Force Flags are ina permanent storage area which is maintained during power outages Refer to the I O Database and Register Assignment chapter for more information See Also setForceFlag clearAllForcing overrideDbase Example This program obtains the force flag state for register 40001 for the 16 status registers at linear address 302 i e registers 10737 to 10752 and for the holding register at linear address 1540 i e register 40005 include lt ctools h gt int main void UINT 16 flag bitmask Document Version 1 70 5 23 2012 249 Function Specifications getForceFlag MODBUS getForceFlag getForceFlag IN EAR INI EAR 40001 amp flag 302 1540 amp bitmask amp flag Document Version 1 70 5 23 2012 250 Function Specifications getForceLed Get status of Force LED Syntax include lt ctools h gt UINT16 getForceLed void Description The getForceLed function returns the status of the Force LED It returns TRUE if the LED is ON and FALSE if the LED is OFF See Also forceLed Document Version 1 70 5 23 2012 251 Function Specifications getFtpSe
353. ider Electric software or approved software with our hardware products may result in injury harm or improper operating results Failure to observe this information can result in injury or equipment damage 2011 Schneider Electric All rights reserved Document Version 1 70 5 23 2012 Table of Contents User and Reference Manual eccccceeeseeeseeeeeeeeeeeeeeeeneeseeeees 1 Tablet 2 Index oi FIQUIES ccccccceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 14 Safety Information seu veuegeuueENEEANEVUEENKRESEEEEENEKEKUNESENEEEEEEEKUNEuENe 15 About The BOOK yrs cesisssinstensusnsususneisdsusnsusunusicastansieusieusieusdensiensioesa 18 ee Ee 18 OVEIVIOW aTa Eaa Eara aaa Eaa aaa E aaa Eaa Eaa a Aaaa aama Aaaa Eaa aaia Eaa iaaa Easa iaaa 19 Technical SUPPO earar aaa aE R RERE D nE i nDia hri nnii 19 Getting Started w ciccciieccccciscicsnsscnncciecdseneaandecesiecssssceawiannsbecdeocsens 20 SCADAPack C Tools Installation seeeeeeeeeeeeeeeeeesninrrrrssserrrrnrsssssrrrrrne 20 Program Development Tutorial ccccceeceeeeeeeeeeeeccneeeeeeeeeeeeencaaeeeeeeeeeteeenaaaes 21 C Program Developme ntt cccccccesseesseeeeeeeeeeeeseeeeeeseeeeeeeeees 33 elt El E eeler 33 GNU Compiler OptlOnS ica A A O eee 44 Application Development 45 Real Time Operating System cs eeeceeeeeeeeeeeeeeeeeeeeeeeeeeeeeees 46 Task Management 46 Resource Management 47 Inter task Communicatio
354. ification MY EVENT wait event MY_EVENT check status of last scan if ioStatus MT 5606Outputs 5 amp io status status FALSE else if io status commStatus status FALSE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 386 Function Specifications ioWrite56070utputs Write 5607 Outputs Syntax include lt ctools h gt BOOLEAN ioWrite56070utputs UINT16 moduleAddress UCHAR amp doutData 2 INT16 amp aoutData 2 UINT16 amp inputType 8 UINT16 inputFilter UINT16 scanFrequency UINT16 outputType Description This function writes data to the I O table for the 10 digital outputs and 2 analog outputs of a 5607 I O module Data are written to the module when an I O request for the module is processed moduleAddress is the address of the 5607 module Valid values are 0 to 7 doutData is a reference to an array of two UCHAR variables Digital data for the 10 outputs are read from this array One bit in the array represents each output point aoutData is a reference to an array of two INT16 variables Analog data for the two analog outputs are read from this array inputType is a reference to an array of eight UINT16 variables selecting the input range for the corresponding analog input Valid values are e 0 O0to 5V e 1 0to10V e 2 0to20mA e 3 4to 2
355. in the system pool is preserved when the controller is reset The function has two arguments ppMemory a pointer to a pointer to the memory allocated and size the number of bytes of memory to be allocated The function returns TRUE if the memory was allocated and FALSE if the memory is not available Use the freeMemory function to free non volatile memory Notes The DYNAMIC_MEMORY resource needs to be requested before calling this function The allocation of memory and the allocated memory are non volatile Pointers to non volatile dynamic memory need to be statically allocated in a non volatile data section Otherwise they will be initialised at reset and the non volatile dynamic memory will be lost The example below demonstrates how to create a non volatile data section to save pointers to non volatile dynamic memory See Also freeMemory Example See the Memory Allocation Example in the Examples section Document Version 1 70 5 23 2012 105 Function Specifications bind Bind an address to an unnamed socket Syntax include lt ctools h gt int bind int socketDescriptor const struct sockaddr addressPrtr int addressLength Description bind assigns an address to an unnamed socket When a socket is created with socket it exists in an address family space but has no address assigned bind requests that the address pointed to by addressPir be assigned to the socket Clients do not normally re
356. ings port coml strcpy initSettings modemCommand F1QOV1X1 SO 1 if modemInit amp initSettings amp portID DE NoError do Allow other tasks to execute release processor Wait for the initialization to complete modemInitStatus coml portID amp status amp state while state DS Calling Terminate the initialization modemInitEnd coml portID Real Time Clock Program Example amp status The following program illustrates how the date and time can be set and displayed All fields of the clock structure need to be set with valid values for the clock to operate properly include lt ctools h gt int main void bi D TIMI now Set to 12 01 00 on January 1 1 2 r hour minute second day month year dayofweek now now now now now now now x r r 1 1 0 1 1 97 3 D r day is Wed 997 set the time set the date SG Document Version 1 70 5 23 2012 670 Example Programs WI request _ resource IO SYSTEM setclock amp now getclock amp now read the clock release resource IO SYSTEM Display current hour minute and second fprintf coml 2d 2d 2d now day now month now year fprintf com1 2d S2d r n now hour now minute Start Timed Event Example This program prints the time every 10 se
357. interface typ UINT16 slaveStation slave station address COM_INTERFACE forwardInterface forwarding interface type UINT16 forwardStation forwarding station address IP ADDRESS forwardIPAddress forwarding IP address UINT16 timeout time out SF_TRANSLATION_EX slavelnterface is the communication interface which receives the slave command message Valid interface types are 1 com1 2 com2 3 com3 100 Etherneti slaveStation is the station address used in the slave command message Valid address range is 0 to 255 in standard Modbus 0 to 65534 in extended Modbus 65535 entry cleared This station address must be different from the station address assigned to the slavelnterface forwardInterface is the communication interface from which to forward the command message as master Valid interface types are 1 com1 2 com2 3 com3 100 Modbus TCP network 101 Modbus RTU over UDP network 102 Modbus ASCII over UDP network Document Version 1 70 5 23 2012 629 Structures and Types e forwardStation is the station address of the remote slave device to forward the command message to Valid address range is 0 to 255 in standard Modbus 0 to 65534 in extended Modbus 65535 entry cleared This station address must be different from the station address assigned to the forwardInterface e forwardiPAddress is the IP address of the remote slave device to forward a Modbus IP command m
358. ion 1 70 5 23 2012 660 Example Programs void wait for response UCHAR port unsigned time UINT32 startTime struct prot Status status static unsigned long good bad startTime readStopwatch do Allow other tasks to execute release processor status get protocol status port while readStopwatch startTime lt 100 time amp amp status command MM SENT if status command MM RECEIVED good else badt fprintf coml Good 8lu Bad 8lu r good bad e eege hy er en e main The main function sets up serial ports then sends commands to a Modbus slave int main void struct prot settings settings struct pconfig portset request _ resource IO SYSTEM disable protocol on serial port 1 settings type NO PROTOCOL settings station 1 settings priority 250 settings SFMessaging FALSE set protocol coml amp settings Set communication parameters for port 1 portset baud BAUD9600 portset duplex FULL portset parity NONE portset data_bits DATA8 portset stop bits STOP1 portset flow_ rx RRC NONE portset flow tx TFC_NONE portset typ RS232 portset timeout 600 set_port coml amp portset enable Modbus protocol on serial port 2 Document Version 1 70 5 23 2012 661 Example Programs settings type MODB
359. ion returns TRUE if successful FALSE otherwise Example See the Example in the dnpGetConfiguration section Document Version 1 70 5 23 2012 228 Function Specifications end_application Terminates all Application Tasks Syntax include lt ctools h gt void end application void Description The end_application function terminates all APPLICATION type tasks created with the create_task function Stack space and resources used by the tasks are freed Notes This function is used normally by communication protocols to stop an executing application program prior to loading a new program into memory See Also end_group end_task Document Version 1 70 5 23 2012 229 Function Specifications end_group Terminates all Tasks in a Task Group Syntax include lt ctools h gt void end_group UINT16 taskGroup Description The end_group function terminates all tasks of the specified type This function should only be used with taskGroups of APPLICATION_GROUP_0O APPLICATION GROUP o Stack space and resources used by the tasks are freed Notes This function is used normally by communication protocols to stop an executing application program See Also end_application end_task Document Version 1 70 5 23 2012 230 Function Specifications end_task Terminate a Task Syntax include lt ctools h gt void end_task UINT16 task ID Description The end_task function terminates the tas
360. ion with the NULL pointer to remove the dbase handler This needs to be done when the application program is ended with an exit handler Use the installExitHandler function to install the exit handler If the Dbase handler is not removed within an exit handler it will remain installed and continue to operate until the controller power is cycled Erasing the C Program from the Initialize dialog will not remove the Dbase handler If the handler is located in a RAM based application and left installed while a different C application is downloaded the original handler will be corrupted and the system will likely crash Document Version 1 70 5 23 2012 305 Function Specifications installSetdbaseHandler Install User Defined Setdbase Handler IEC 61131 1 firmware only Syntax include lt ctools h gt void installSetdbaseHandler BOOLEAN handler UINT16 address INT16 value Description The installSetdbaseHandler function allows an extension to be defined for the setdbase function If a handler is installed it is called by the setdbase function when one of the following conditions apply e There is no IEC 61131 1 application downloaded or e There is no IEC 61131 1 variable assigned to the specified Modbus address The function installSetdbaseHandler has one parameter a pointer to a function to handle the setdbase extensions See the section Setdbase Handler Function for a full Description of the handle
361. ion writes data to the I O table for the digital output and analog output of the 4203 DR I O Data is written to the module when an I O request for the module is processed doutData is a reference to a UCHAR variable Digital data for the output is read from this variable One bit in the array represents each output point aoutData is a reference to a INT16 variable Analog data for the analog output is read from this variable The function returns TRUE if the supplied data was written to the I O table FALSE is returned if the data could not be written to the I O table See Also ioRead4203DRInputs Example This program turns on the digital output and sets the analog output to full scale on the 4203 DR include lt ctools h gt define MY EVENT 1 int main void UCHAR doutData INT16 aoutData IO STATUS io status main loop while TRUE write data to output tables for next scan doutData 0x01 aoutData 32767 iLoWrite4203DROutputs doutData aoutData add module scan to queue if 1oRequest MT_4203DROutputs 0 Document Version 1 70 5 23 2012 371 Function Specifications insert code to handle wait for scan to complete ioNotification MY_ EVENT wait event MY_EVENT check status of last scan if i1o0Status MT 4203DROutputs insert code to handle else if io status commStatus insert co
362. iption This function reads the extended DNP configuration parameters The function has one parameter a pointer to the DNP extended configuration structure The function returns TRUE if the configuration was successfully read or FALSE otherwise if the pointer is NULL or if the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration This function supersedes the dnpGetConfiguration function This function does not return the configuration for the Unsolicited Back Off Time Use the function dnoGetUnsolicitedBackoffTime to get the Unsolicited Back Off Time configuration Document Version 1 70 5 23 2012 184 Function Specifications dnpGetRuntimeStatus Get DNP Runtime Status Syntax include lt ctools h gt BOOLEAN dnpGetRuntimeStatus DNP_RUNTIME STATUS status Description The dnpGetRuntimeStatus function reads the current status of all DNP change event buffers and returns information in the status structure DNP needs to be enabled before calling this function in order to create the DNP configuration Example See the example in the dnoGetConfiguration section Document Version 1 70 5 23 2012 185 Function Specifications dnpGetUnsolicitedBackoffTime Read the DNP unsolicited resend time Syntax UINT16 dnpGetUnsolicitedBackoffTime Description The dnpGetUnsolicitedBackoffTime function reads th
363. irements are now the same for all serial ports of the SCADAPack 350 and 4203 New Flow Control MACROS To help clarify the type of Flow Control feature provided when ENABLE or DISABLE is specified four new macros have been defined RFC_MODBUS_RTU may be used in place of ENABLE Both have the value 1 RFC_NONE may be used in place of DISABLE Both have the value 0 TFC_IGNORE_CTS may be used in place of ENABLE Both have the value 1 TFC_NONE may be used in place of DISABLE Both have the value 0 Timeout Setting Not Supported Timed Events The timeout serial port setting is no longer supported for com1 and com2 The serial port timeout setting was never supported for com3 or com4 on the SCADAPack controller This setting is ignored and is fixed at 600ms for backwards compatibility Periodic timing may be desired when a continuous loop needs to be repeated at a fixed interval of time The timed event feature sets up a periodic event that is signaled by the operating system at a specified fixed interval Document Version 1 70 5 23 2012 690 Porting Existing C Tools Applications A main application task or an additional application task can be made to wait on a periodic event before executing a set of actions If the actions are completed before the next periodic event has been signaled the task is blocked while waiting for the event This blocked state allows the processor to execute other application or system tasks while it wa
364. is FALSE then digital outputs are turned OFF when the Ladder Logic program is stopped If the value pointed to by holdAoutsOnStop is TRUE then analog outputs are held at their last value when the Ladder Logic program is stopped If the value pointed to by holdAoutsOnStop is FALSE then analog outputs go to zero when the Ladder Logic program is stopped See Also setOutputsInStopMode Example See the Example for setOutputsInStopMode function Document Version 1 70 5 23 2012 255 Function Specifications getLoginCredentials Gets login credentials for a service Syntax include lt ctools h gt BOOLEAN getLoginCredentials UINT32 service UINT32 index UCHAR username UINT32 maxUsernameLength 1 Parameters service specifies the service for which the credentials are being retrieved index specifies the index for the credentials Indices are service specific username specifies the username to grant access to maxUsernameLength specifies the maximum length username that can be returned Description The getLoginCredentials function retrieves the username at the specified index for the specified service Valid services are 0 FTP Maximum username and password length is 16 bytes Only index 0 is supported The valid values of index are service specific The username returned will be NULL terminated and placed in the buffer pointed to by username True is returned if the credentials were retrieved Fal
365. is irrelevant because we don t care about the IP address of the remote master We care only that the remote master connects to the specified s avelnterface and sends a command to be forwarded The protocol type is not specified for slaveinterface All messages in any Modbus IP protocol received on slavelnterface for slaveStation will be forwarded Serial Modbus Interface as Forwarding Interface The forward PAaddress field in the SF_TRANSLATION EX structure should be set to zero when the forwardinterface field is a Serial Modbus interface Set forward PAddress to zero as follows SF_TRANSLATION EX sfTranslation sfTranslation forwardIPAddress s addr 0 See Also getSFTranslationEx checkSFTranslation clearSFTranslation Document Version 1 70 5 23 2012 536 Function Specifications setsockopt Syntax include lt ctools h gt int setsockopt int socketDescriptor int protocolLevel int optionName const char optionValue int optionLength 1 Description setsockopt is used manipulate options associated with a socket Options may exist at multiple protocol levels they are always present at the uppermost socket level When manipulating socket options the level at which the option resides and the name of the option must be specified To manipulate options at the socket level protocolLevel is specified as SOL_SOCKET To manipulate options at any other level protoco Level is the protocol n
366. it event MY_EVENT read input data from last status ioRead5607Inputs 5 check status of last scan if i1oStatus MT _5607Inputs status FALSE else if status FALSE print data fprintf com3 status u Dins 0 to 7 X Ain 4 d status dinData 0 ainData 4 scan dinData ainData 5 amp io status io_status commStatus r n l release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 343 Function Specifications ioRead56070utputs Read 5607 Outputs Syntax include lt ctools h gt BOOLEAN ioRead56070utputs UINT16 moduleAddress UCHAR amp doutData 2 INT16 amp aoutData 2 UINT16 amp inputType 8 UINT16 amp inputFilter UINT16 amp scanFrequency UINT16 SoutputType Description This function reads buffered data from the digital and analog outputs of a 5607 I O module Buffered data are written using the ioWrite5607Outputs function moduleAddress is the address of the 5607 module Valid values are 0 to 7 doutData is a reference to an array of two UCHAR variables Digital data for the 10 outputs are written to this array One bit in the array represents each output point aoutData is a reference to an array of two INT16 variables Analog data for the two analog outputs are written to this array inputType is a reference to an arr
367. itHandler UINT32 taskID FUNCPTR function Description The installExitHandler function defines a function that is called when the task specified by task D is ended function specifies the handler function If function is NULL the handler is disabled Notes The exit handler function will be called when e the task is ended by the end_task or end_group function e the end_application function is executed and the function is an APPLICATION type function e the program is stopped from the IEC 61131 1 or Telepace program and the task is an APPLICATION type function e the program is erased by the IEC 61131 1 or Telepace program The exit handler function is not called if power to the controller is removed In this case all execution stops when power is removed The application program starts from the beginning when power is reapplied Do not call any RTOS functions from the exit handler Example See the Example for startTimedEvent Document Version 1 70 5 23 2012 308 Function Specifications installModbusHandler Install User Defined Modbus Handler Syntax include lt ctools h gt void installModbusHandler UINT16 handler UCHAR UINT16 UCHAR UINT16 zi 1 Description The installModbusHandler function allows user defined extensions to standard Modbus protocol This function specifies a function to be called when a Modbus message is received for the station but is not understood by the standa
368. its This is more efficient than executing a loop that checks for a timer to expire For an example using timed events see the function startTimedEvent Reading the System Stopwatch For one time actions and timed actions that need accuracy better that a tenth of a second the system clock may be read using the function readStopwatch This function returns the system time in milliseconds and has a resolution of 10 ms The stopwatch time rolls over to 0 when it reaches the maximum value for an unsigned long int i e a UINT32 4 294 967 295 ms or about 49 7 days For example startTime readStopwatch wait for 50 ms 10 ms while readStopwatch startTimed lt 50 release_processor Refer to the section describing the function readStopwatch for other timing examples using this function Modbus Handler Functions The installModbusHandler is used to add user defined extensions to the standard Modbus protocol To uninstall a Modbus handler in a SCADAPack C application the same function is called with the NULL pointer SCADAPack 350 and 4203 C applications support the installation of multiple Modbus handlers In order to remove a specific Modbus handler the new function removeModbusHandler is used Calling installModbusHandler with the NULL pointer has no effect Unsupported C Tools Functions The following sections describe functions that are supported by the Telepace C Tools and IEC 61131 1 C Tools but
369. itten to this variable e 0 3Hz e 1 6Hz e 2 11 Hz e 3 30 Hz scanFrequency is a reference to a UINT16 variable The scan frequency selection is written to this variable e 0 60 Hz e 1 50Hz The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5506Inputs ioWrite55060utputs Document Version 1 70 5 23 2012 336 Function Specifications Example This program reads configuration data for the 5506 I O module at address 5 include lt ctools h gt int main void UINT16 inputType 8 UINT16 inputFilter UINT16 scanFrequency BOOLEAN status BOOLEAN done main loop while TRUE read output data from I O table status ioRead5506O0utputs 5 inputType inputFilter scanFrequency print data if done fprintf coml status u inputType 0 d inputFilter d scanFrequency d r n status inputType 0 inputFilter scanFrequency done TRUE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 337 Function Specifications ioRead5606Inputs Read 5606 Inputs Syntax include lt ctools h gt BOOLEAN ioRead5606Inputs UINT16 moduleAddress UCHAR amp dinData 5 INT16 amp ainData 8 Description This function reads buffered data from the digital and analog inputs of a 5606 I O module Buffered data are updated wh
370. itter variables return status of last HART command sent read HART module settings write HART module settings convert string to HART packed string convert HART packed string to string The ctools h file defines the following macro of interest to a C application DATA_SIZE HART Command Enumeration Types program Refer to the C Tools Macros section for details Maximum length of the HART command or response field The ctools h file defines one enumeration type The HART_RESULT enumeration type defines a list of results of sending a command Refer to the C Tools Structures and Types section for complete information on structures and enumeration types HART Command Structures The ctools h file defines five structures Refer to the C Tools Structures and Types section for complete information on structures and enumeration types HART_DEVICE HART_VARIABLE HART_SETTINGS HART_COMMAND HART_RESPONSE type is a structure containing information about the HART device type is a structure containing a variable read from a HART device type is a structure containing the configuration for the HART modem module type is a structure containing a command to be sent to a HART slave device type is a structure containing a response from a HART slave device Document Version 1 70 5 23 2012 86 Overview of Programming Functions File Management API File management library functions are provided by the GNU l
371. k space for a task and places the task on the ready queue function specifies the start address of the routine to be executed The task will execute immediately if its priority is lower than the current executing task priority is an execution priority between 0 and 254 for the created task The lowest priority is 254 and the highest priority is 0 The 255 task priority levels aid in scheduling task execution See the notes below for recommended priority values type specifies if the task is ended when an application program is stopped Valid values for type are SYSTEM System tasks do not terminate when the program stops applicationGroup Application tasks terminate when the program stops Use this global variable for all calls to create_task by the same application The operating system assigns a unique value to applicationGroup when it is defined in appstart cpp It is recommended that only application type tasks be created The stack parameter specifies how many stack blocks are allocated for the task Each stack block is 512 bytes The create_task function returns the task ID TID of the task created If an error occurs 1 is returned Notes Refer to the Real Time Operating System section for more information on tasks The main task and the Ladder Logic and I O scanning task have a priority of 100 If the created task is continuously running processing code create the task with a priority of 100 The scheduling algorithm of
372. k specified by task_ID Stack space and resources used by the task are freed The end_task function terminates any type task See Also end_application end_group Document Version 1 70 5 23 2012 231 Function Specifications endTimedEvent Terminate Signaling of a Regular Event Syntax include lt ctools h gt UINT16 endTimedEvent UINT16 event Description This endTimedEvent function cancels signaling of a timed event initialized by the startTimedEvent function The function returns TRUE if the event signaling was canceled The function returns FALSE if the event number is not valid or if the event was not previously initiated with the startTimedEvent function The function has no effect in these cases Notes Valid events are numbered 0 to RTOS_EVENTS 1 Any events defined in ctools h are not valid events for use in an application program Example See the Examples for startTimedEvent See Also startTimedEvent Document Version 1 70 5 23 2012 232 Function Specifications enroninstallCommandHandler Installs handler for Enron Modbus commands Syntax include lt ctools h gt void enronInstallCommandHandler UINT16 function UINT16 length UCHAR pCommand UINT16 responseSize UINT16 pResponseLength UCHAR pResponse 1 Description This function installs a handler function for Enron Modbus commands The protocol driver calls this handler function each time a command
373. l in determining how much memory needs to be allocated for a call to datalogReadNext or datalogWrite See Also See example DataLog program in the Example Programs section datalogSettings Example See the example for datalogReadStart Document Version 1 70 5 23 2012 143 Function Specifications datalogSettings Data Log Settings Function Syntax include lt ctools h gt BOOLEAN datalogSettings UINT16 logID DATALOG CONFIGURATION pLogConfiguration Description This function reads the configuration of the specified data log The log needs to have been previously created with the datalogCreate function The function has two parameters log D specifies the data log The valid range is 0 to 15 pLogConfiguration points to a structure that will hold the data log configuration The function returns TRUE if the operation succeeded The function returns FALSE if the log ID is invalid or if the data log does not exist Notes The configuration of an existing data log cannot be changed The log needs to be deleted and recreated to change the configuration See Also See example DataLog program in the Example Programs section datalogRecordSize Example See example for datalogDelete Document Version 1 70 5 23 2012 144 Function Specifications datalogWrite Write Data Log Function Syntax include lt ctools h gt BOOLEAN datalogWrite UINT16 logID UINT16 pData Description This f
374. lO CNFG_sav SCADA eTOoEEPRO Pack_L M PIO CNFG_setS SCADA erialPortDT Pack 2 R IO CNFG_stor SCADA eAndForwa Pack_1 rd 0010 SCADASE SCADA NSE_ 4203 _ Pack_5 DR 60610 CNTR_520 SCADA xCounterlIn SENSE puts 4203 _ DS SCADAPac k_33xlO moduleAddress specifies a unique address for the module For the valid range for moduleAddress refer to the list of modules in the chapter Register Assignment Reference of the Telepace Ladder Logic Reference and User Manual For module addresses com com2 com3 or com4 specify 0 1 2 or 3 respectively for moduleAddress For module address Ethernet1 specify 4 for moduleAddress For module types that have no module address e g CNFG_LEDPower specify 1 for moduleAddress For SCADAPack module types that have a module address fixed at 0 specify 0 for moduleAdadress startingRegister1 specifies the first register of any unused block of consecutive registers Refer to the list of modules in the Register Assignment Reference for the type and number of registers required for this block Data read from or written to the module is stored in this block of registers If the module type specified has more than one type of I O use startingRegister2 startingRegister3 and startingRegister4 as applicable Each start register specifies the first register of an unused block of consecutive registers for each type of input or output on the module Refer to the list of modules in the Register Assignment Reference for the mo
375. ld be ORed together CLASSO_FLAG request Class 0 Data CLASS1_FLAG request Class 1 Data CLASS2_FLAG request Class 2 Data CLASS3_FLAG request Class 3 Data The DNP slave slaveAddress needs to be configured in the DNP Master Poll Table prior to calling this function The function returns TRUE if the DNP class poll message was successfully triggered It returns FALSE if the specified slave address has not been configured in the DNP Routing Table or the DNP configuration has not been created Notes This function is only available on the SCADAPack 32 SCADAPack 350 and 4203 DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 192 Function Specifications dnpMasterClockSync Send DNP Clock Synchronization Syntax BOOLEAN dnpMasterClockSync UINT16 slaveAddress 1 Description The dnpMasterClockSync function sends a Clock Synchronization message in DNP to a DNP slave slaveAddress specifies the DNP station address of the slave The DNP slave slaveAddress needs to be configured in the DNP Master Poll Table prior to calling this function The function returns TRUE if the DNP clock sync message was successfully triggered It returns FALSE if the specified slave address has not been configured in the DNP Routing Table or the DNP configuration has not been created Notes This function is only availabl
376. le Digital data for the input is written to this array One bit in the array represents each input point ainData is a reference to an array of three INT16 variables Analog data are written to this array cinData is a reference to two UINT32 variables Counter data is written to this array The function returns FALSE if the data was read from the internal table otherwise TRUE is returned See Also ioWrite4203DSOutputs Example This program displays the values of the digital input and the 3rd analog input read from the 4203 DS I O include lt ctools h gt define MY EVENT 1 int main void UCHAR dinData INT16 ainData 5 UINT32 cinData 2 IO STATUS io status BOOLEAN status main loop while TRUE add module scan to queue if ioRequest MT_4203DSInputs 0 Document Version 1 70 5 23 2012 319 Function Specifications status FALSE else wait for scan to complete ioNotification MY EVENT wait event MY_EVENT vead input data from last scan status ioRead4203DSInputs dinData ainData cinData check status of last scan if status FALSE insert code to handle the failure here else if io0Status MT _4203DSInputs 0 amp io status insert code to handle the failure here else if io status commStatus insert code to handle the failure here else fprintf com2
377. le E b i ll 321 elle E Baler ieee eee eee ee aires 323 ioRe add4 14 le 324 Document Version 1 70 5 23 2012 ioReEadd41 5INputs wave ee dite acini 326 lee re LCE 328 del Wl EE 329 del re DEET 332 dell Te al 334 IobieadbbO pCutpute AA 336 leie eer lf 338 IOREAdSSOGOUTPUIS AEE EEEE E 340 lee ee le fN 342 ee e ge CN 344 lee LI 346 ele ln 347 ee Le 348 ee Le 349 IOREADAOUTD SOS ee henveeeebesveesstenrteeebvnviensteentenebenvtenstesetenstoeeeverteeteasteneevereest 350 IOREAUACOUNTCLA MEN 351 ele eet 352 IOREGAADIN A EN 353 Je TR In 354 Relet t 0 B lat ege A A E KESSLER eer nnn renee rrr rere rrr rer tt 356 Jose Tea EN 357 Gbale epeeee A E E E E AER eter ree SEN 358 IORGAUDOUIS Assesse ekEAESuASees SEKEKEAEEEAESEREEKENELEEEAESEEEEAEREAEEEAESEEEEEAERENEEEA KEE 359 de ele TE 360 IO READS PZOUUPUS TEE 362 Joie EE 364 JOSStGOMPIGUCATI OM EE 366 Jee EE 367 TORSIE Ee 369 LOW el EE 370 Io rtei202DPCutpute eee cece eee e cece eee eeece eee e eset eeeeaaaeeeeeeeeeeteetaaeeeeeeeeetees 371 IOWrite4203DSOUtpUtS iiaiai eee eee e rete teaaaeee sees eetteeaaaeeeeeeettneee 373 edel e 375 lOWnteS4 4 ele 377 IOWrite54 1 SOUtDUIS AA 378 JOW NILES SO 5 OUTDUIS TTT 380 IOWriteS 506 OUtOUtS AAA 382 JOW NLC S6OG OUTDUIS TEE 384 IOWrite56O 7 OUtOUtS eee eee eeeeeee cece eee eeeeeaeee eset ee eteeaaaeeeeeeeeeteeecaaeeeeeeeetnee 387 Je AA KeY 0 eee eeeee e pee cere per errr ere peer aE 390 Ielwen 391 JOW NIG A OULD ee 392 POV ILS EU Ge
378. le below contains the recommended priority values to use when porting to the SCADAPack 350 and 4203 Priority Description Equivalent Priority Priority Value for Value for SCADAPack SCADAPack 32 350 and 4203 figherProny a f o EE eo a I I IOI Toweri o o oo Oooo The argument used for application type in existing calls to create_task must be replaced with the global variable applicationGroup The operating system assigns a unique value to applicationGroup when it is defined in appStart cpp Please see the documentation for create_task in the Function Specifications section for more details Controller HO Functions The following functions are no longer supported The replacement function is indicated for each Each function is documented in the Function Specifications section Replaced with interruptInput no replacement function interruptCounter no replacement function ioReadCounterSP2 readCounter Input no replacement function Document Version 1 70 5 23 2012 676 Porting Existing C Tools Applications ioReadDin5232 no replacement function ioReadCounter5232 ioReadCounterSP2 ioRead5601 Inputs ioReadSP2Inputs ioRead5601 Outputs ioReadSP2Outputs ioWrite5601 Outputs ioWriteSP2Outputs Exit Handler Function The argument used to specify the exit handler function in existing calls to installExitHandler must be cast to the type FUNCPTR Please see the documentation for installExitHandler in the Functio
379. le the protocol on serial port 1 settings type NO_ PROTOCOL settings station 1 settings priority 250 settings SFMessaging FALSE request resource IO SYSTEM set protocol coml amp settings release resource IO SYSTEM Display the ROM version information versionInfo getVersion fprintf coml r nFirmware Information r n fprintf coml Controller type d r n versionInfo controller fprintf coml Firmware version d r n versionInfo version fprintf coml Creation date s r n versionInfo date fprintf coml Copyright s r n versionInfo copyright Document Version 1 70 5 23 2012 278 Function Specifications getWakeSource Gets Conditions for Waking from Sleep Mode Syntax include lt ctools h gt UINT32 getWakeSource void Description The getWakeSource function returns a bit mask of the active wake up sources Valid wake up sources are listed below e WS_RTC_ALARM e WS_COUNTER_1_OVERFLOW e WS_COUNTER_2_OVERFLOW e WS_COUNTER_3_OVERFLOW e WS_LED_POWER_SWITCH e WS_DIN_1_CHANGE e WS_COM3_VISION See Also setPowerMode Example The following code fragment displays the enabled wake up sources unsigned enabled nabled getWakeSource fputs Enabled wake up sources r n coml if enabled amp WS RTC ALARM fputs Real Time Clock r n coml if enabled amp W
380. letter poll message if letter NULL process the message now more code here Document Version 1 70 5 23 2012 456 Function Specifications poll_resource Test Resource Availability Syntax include lt ctools h gt BOOLEAN poll resource UINT32 resource Description The poll_resource function tests if the resource specified by resource is available If the resource is available it is given to the task The poll_resource function returns TRUE if the resource is available It returns FALSE if it is not available The current task always continues to execute Notes Refer to the Real Time Operating System section for more information on resources See Also Dol event poll_ message Document Version 1 70 5 23 2012 457 Function Specifications portindex Get Index of Serial Port Syntax include lt ctools h gt UINT16 portIndex FILE stream Description The portlIndex function returns an array index for the serial port specified by stream lt will return a value suitable for an array index in increasing order of external serial port numbers if no error occurs If the stream is not recognized SERIAL_PORTS is returned to indicate an error See Also portStream Document Version 1 70 5 23 2012 458 Function Specifications portStream Get Serial Port Corresponding to Index Syntax include lt ctools h gt FILE portStream UINT16 index
381. licationTimeout timeSynchronization BI number startAddress BI_reportingMethod NT16 BI_soebufferSize NT16 BO number startAddress UINT16 CI16 number eae Cd EO G O E Gc UINT16 CI16 startAddress CHAR CI16 reportingMethod NT16 CI16 bufferSize NT16 CI32 number UINT16 CI32 startAddress CHAR C132 reportingMethod UINT16 CI32 bufferSize CHAR C132 wordOrder UINT16 AI16 number Document Version 1 70 5 23 2012 596 Structures and Types UINT16 AI16 startAddress CHAR AI16 reportingMethod UINT16 AI16 bufferSize UINT16 AI32_ number UINT16 AI32_ startAddress CHAR AI32_ reportingMethod UINT16 AI32 bufferSize CHAR AI32 wordOrder UINT16 AISF number UINT16 AISF startAddress CHAR AISF reportingMethod UINT16 AISF bufferSize CHAR AISF wordOrder UINT16 AO16 number UINT16 A016 startAddress UINT16 AO32_ number UINT16 AO32 startAddress CHAR A032 wordOrder UINT16 AOSF number UINT16 AOSF_ startAddress CHAR AOSF wordOrder NT16 autoUnsolicitedClass1 NT16 holdTimeClass1 NT16 holdCountClass1 NT16 autoUnsolicitedClass2 NT16 holdTimeClass2 NT16 holdCountClass2 NT16 autoUnsolicitedClass3 NT16 holdTimeClass3 NT16 holdCountClass3 NT16 enableUnsolicitedOnStartup NT16 sendUnsolicitedOnStartup UINT16 level2Compliance dnpConfiguration ade HHHHHHHHHHH e masterAddress is the address of the master station Unsolicit
382. ling the function with state set to TRUE starts the task This function should only be needed in the context of the startup function appstart Document Version 1 70 5 23 2012 496 Function Specifications select Syntax include lt ctools h gt int select int numberSockets fd_set readSocketsPtr fd_set writeSocketsPtr fd_set exceptionSocketsPtr struct timeval timeOutPtr 1 Description select examines the socket descriptor sets whose addresses are passed in readSocketsPtr writeSocketsPtr and exceptionSocketsPtr to see if any of their socket descriptors are ready for reading are ready for writing or have an exceptional condition pending respectively Out of band data is the only exceptional condition The numberSockets argument specifies the number of socket descriptors to be tested Its value is the maximum socket descriptor to be tested plus one The socket descriptors from 0 to numberSockets 1 in the socket descriptor sets are examined On return select replaces the given socket descriptor sets with subsets consisting of those socket descriptors that are ready for the requested operation The return value from the call to select is the number of ready socket descriptors The socket descriptor sets are stored as bit fields in arrays of integers The following macros are provided for manipulating such file descriptor sets FD_ZERO amp fdset Initializes a socket descriptor set fdset to the n
383. lt state after 5 minutes e Set Outputs on Stop settings to Hold e Set 5904 HART modem configuration for all modems e Set Modbus TCP default configuration e Write new default data to Flash Notes This function can be used to restore the controller to its default state ioDatabaseReset has the same effect as selecting the Initialize Controller option from the Initialize command in the IEC 61131 1 program The IO_SYSTEM resource needs to be requested before calling this function Example include lt ctools h gt Document Version 1 70 5 23 2012 313 Function Specifications int main void Power Up Initialization request resource IO SYSTEM ioDatabaseReset release resource IO SYSTEM the rest of the program Document Version 1 70 5 23 2012 314 Function Specifications ioGetConfiguration Get I O Controller Configuration Syntax include lt ctools h gt IO _CONFIG amp ioGetConfiguration void Description This function returns the I O controller configuration The function has no arguments The function returns an O_CONFIG structure containing the configuration Document Version 1 70 5 23 2012 315 Function Specifications ioNotification Add I O Notification Request Syntax include lt ctools h gt BOOLEAN ioNotification UINT16 eventNumber Description This function adds a Notification Request to the I O Controller request queue The
384. lter Description This function reads configuration data from the I O Table for a 5505 I O module Configuration data are written using the ioWrite5505Outputs function moduleAddress is the address of the 5505 module Valid values are 0 to 15 inputType is a reference to an array of four UINT16 variables Analog input measurement types are written to this array Valid values are e 0 RTD in deg Celsius e 1 RTDin deg Fahrenheit e 2 RTD in deg Kelvin e 3 resistance measurement in ohms inputFilter is a reference to a UINT16 variable The input filter selection is written to this variable e 0 0 5s e 1 185 e 2 2sS e 3 4s The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5505Inputs ioWrite5505Outputs Example This program reads configuration data for the 5505 I O module at address 5 include lt ctools h gt int main void UINT16 inputType 4 Document Version 1 70 5 23 2012 332 Function Specifications UINT16 inputFilter BOOLEAN status BOOLEAN done main loop while TRUE read output data from I O table status ioRead55050utputs 5 inputType inputFilter print data if done fprintf coml status u inputType 0 d inputFilter d r n status inputType 0 inputFilter done TRUE release processor to other priority 1 tasks release processor Doc
385. lude lt ctools h gt int main void struct prot settings settings TASKINFO taskStatus Disable the protocol on serial port 1 settings type NO PROTOCOL settings station 1 settings priority 250 settings SFMessaging FALSE request _ resource IO SYSTEM set _protocol coml amp settings release resource IO SYSTEM display information about current task if getTaskInfo 0 amp taskStatus show information for valid task fprintf coml r n r nInformation about task d r n task fprintf coml Task ID OxSx r n taskStatus taskID fprintf coml Current Priority d r n taskStatus cPriority fprintf coml Normal Priority Sd r n taskStatus priority fprintf coml Task Group Sda r n taskStatus taskGroup if taskStatus requirement REQ NO WAIT fprintf coml Ready to run r n if taskStatus requirement amp REQ MQUEUE fprintf coml Waiting to receive a message r n if taskStatus requirement amp REQ RESOURCE fprintf coml Waiting for resource sd r n taskStatus requirement amp REQ MASK Document Version 1 70 5 23 2012 647 Example Programs if taskStatus requirement amp REQ EVENT fprintf coml Waiting on event number sd r n taskStatus requirement amp REQ MASK fprintf coml Error sd r n taskStatus err
386. lude lt ctools h gt struct SFTranslationStatus setSFTranslationEx UINT16 index SF_TRANSLATION EX pTranslation Description The setSFTranslationEx function copies the structure pointed to by pTranslation into the store and forward translation table at the location specified by index Valid values for index are 0 to 127 The function checks for invalid translations The translation is stored even if invalid If the userName parameter is non NULL then the Store and Forward entry will be set to use authentication with the user name set to the contents of the array pointed to by userName and the password set to the contents of the array pointed to by password Both userName and password need to point to arrays of 16 characters User names and passwords shorter than 16 characters should be padded to 16 characters with spaces If the userName parameter is NULL then no authentication information will be stored with the Store and Forward entry The SF_TRANSLATION_EX structure supports a timeout and is described in the Structures and Types section The function returns a SFTranslationStatus structure It is described in the Structures and Types section The code field of the structure is set to one of the following If there is an error the index field is set to the location of the translation that is not valid SF_VALID All translations are valid SF_NO_TRANSLATION The entry defines re transmission of the same message on the same po
387. lue 0 pMyDatabase gt statusDbase address 11001 Fl ER FALSI pMyDatabase gt statusDbase address 11001 TRUE return TRUE else if address gt 31000 amp amp address lt 31000 SAMPLE SIZE pMyDatabase gt inputDbase address 31001 value return TRUE else if address gt 41000 amp amp address lt 41000 SAMPLE SIZE pMyDatabase gt holdingDbase address 41001 value return TRUE all other addresses are not handled return FALSE Document Version 1 70 5 23 2012 656 Example Programs static void myshutdown void remove database handlers installDbaseHandler NULL installSetdbaseHandler NULL This routine initializes the custom database The database memory is allocated if application has just been downloaded The exit handler is installed and the database handlers are installed static void initializeDatabase void TASKINFO taskStatus BOOLEAN status if getProgramStatus FUNCPTR main EW PROGRAM Application has just been downloaded Any memory previously allocated has been freed automatically Allocate non volatile dynamic memory request _resourc DYNAMIC MEMORY status allocateMemory void amp pNvMemory gt pAllocatedMem MEM SIZE release resource DYNAMIC MEMORY if status TRUE
388. m configuration data typedef struct UINT16 slaveAddress UINT16 dataRate Document Version 1 70 5 23 2012 612 Structures and Types UINT16 numberOfAttempts UINT16 ledPower IO_CONFIG e _slaveAddress returns the UC address 0 slave mode disabled e dataRate returns the I O bus data rate 0 100 kHz 1 150 kHz 2 200 kHz 3 250 kHz 4 300 kHz 5 350 kHz 6 400 kHz default 7 450 kHz e numberOfAttempts returns the number of attempts 1 to 4 default 1 e ledPower returns the led power state 0 off 1 on default 10_STATUS Structure IP_ADDRESS The lO_STATUS structure contains status information from the last scan of a specific I O module typedef struct UINT16 commStatus UINT32 scanTime IO_STATUS The lIO_STATUS structure contains the following data fields e commStatus returns the communication status O failed 1 success e scanTime returns time of last scan in milliseconds according to the stop watch clock The IP Address structure defines an IPv4 address This is the standard IPv4 address structure used by sockets APIs and is also used by Modbus TCP C Tools functions struct in_addr u_long s_addr he typedef struct in addr IP_ADDRESS e s addr is a 32bit netis hostid address in network byte order IP_CONNECTION_SUMMARY The IP Connection Summary structure summarizes the number and type of active TCP IP connections typedef struct st_connectionSummary
389. mand sent using the get_protocol_status function The command field of the prot_status structure is Document Version 1 70 5 23 2012 412 Function Specifications set to MM_SENT if a master message is sent It will be set to MM_RECEIVED when the response to the message is received The command status will be set to MM_RSP_TIMEOUT if the response is not received within 10 seconds Sending a retry master message before this timeout will abort the previous message To use a timeout other than 10 seconds use the serialModbusMaster function The master_message function may be used at the same time on the same serial port as a Telepace MSTR element or IEC 61131 1 master function block Notes Refer to the communication protocol manual for more information The lIO_SYSTEM resource needs to be requested before calling this function See Also modbusSlavelD Example See the Example in the Example Programs chapter under the section Master Message Example Using Modbus Protocol Document Version 1 70 5 23 2012 413 Function Specifications memoryPoolUsage Return amount of non volatile memory in bytes Syntax UINT32 memoryPoolUsage UINT16 taskGroup Description The function has one parameter The taskGroup to report the non volatile memory usage for the task group specified by taskGroup A taskGroup of ALL_TASK_GROUPS will report the total non volatile memory allocation for all tasks The function returns the
390. mand when it is sent to the modem Refer to the section Modem Commands for suggested command strings for your modem The ModemSetup structure specifies modem initialization and dialing control parameters for the modemDial function struct ModemSetup FILE port UINT16 dialAttempts UINT16 detectTime UINT16 pauseTime UINT16 dialmethod CHAR modemCommand MODEM CMD MAX LEN 2 CHAR phoneNumber PHONE NUM MAX LEN 2 Document Version 1 70 5 23 2012 619 Structures and Types e portis the serial port where the modem is connected e dialAttempts is the number of times the controller will attempt to dial the remote controller before giving up and reporting an error e detectTime is the length of time in seconds that the controller will wait for carrier to be detected It is measured from the start of the dialing attempt e pauseTime is the length of time in seconds that the controller will wait between dialing attempts e dialmethod selects pulse or tone dialing Set dialmethod to 0 for tone dialing or 1 for pulse dialing e modemCommand is the initialization string for the modem The characters AT will be prepended to the command and a carriage returned appended to the command when it is sent to the modem Refer to the section Modem Commands for suggested command strings for your modem e phoneNumber is the phone number of the remote controller The characters ATD and the dialing method will
391. maximum period to hold Class 3 events before reporting e HoldCountClass3 is the maximum number of Class 3 events to hold before reporting e EnableUnsolicitedOnStartup enables or disables unsolicited reporting at start up e SendUnsolicitedOnStartup sends an unsolicited report at start up e level2Compliance reports only level 2 compliant data types excludes floats AO 32 e MasterAddressCount is the number of master stations e masterAddress 8 is the number of master station addresses e MaxEventsInResponse is the maximum number of change events to include in read response e PSTNDialAttempts is the maximum number of dial attempts to establish a PSTN connection e PSTNDialTimeout is the maximum time after initiating a PSTN dial sequence to wait for a carrier signal e PSTNPauseTime is the pause time between dial events e PSTNOnlinelnactivity is the maximum time after message activity to leave a PSTN connection open before hanging up e PSTNDialType is the dial type tone or pulse dialling e modeminitString 64 is the initialization string to send to the modem dnpCounterInput The dnpCounterlnput type describes a DNP counter input point This type is used for both 16 bit and 32 bit points typedef struct dnpCounterInput_type UINT16 modbusAddress UCHAR class UINT32 threshold dnpCounteriInput e modbusAddress is the address of the Modbus register number associated with the point e class is the re
392. med If the socket promises reliable delivery of data and SO_LINGER is set the system will block the process on the close of the socket attempt until it is able to transmit the data or until it decides it is unable to deliver the information a timeout period termed the linger interval is specified in the setsockopt call when SO_LINGER is requested If SO_LINGER is disabled and a close on the socket is issued the system will process the close of the socket in a manner that allows the process to continue as quickly as possible The option SO_ BROADCAST requests permission to send broadcast datagrams on the socket With protocols that support out of band data the SO_OOBINLINE option requests that out of band data be placed in the normal data input queue as received it will then be accessible with recv call without the MSG_OOB flag SO_SNDBUF and SO_RCVBUF are options that adjust the normal buffer sizes allocated for output and input buffers respectively The buffer size may be increased for high volume connections or may be decreased to limit the possible backlog of incoming data The Internet protocols place an absolute limit of 64 Kbytes on these values for UDP and TCP sockets in the default mode of operation The following options are recognized at the IP level IP_PROTOIP protocolLevel options IP_MULTICAST_IF Get the configured IP address that uniquely identifies the outgoing interface for multicast datagrams sent on this socket A zero IP
393. message received on com3 It can be used in a custom character handler see install_handler COM4_RCVR This event is used by communication protocols to signal a character or message received on com4 It can be used in a custom character handler see install_handler NEVER This event will never occur It can be used to disable a task by waiting for it to occur However to end a task it is better to use end_task This frees all resources and stack space allocated to the task Sharable I O drivers to return error information to the calling task use the error reporting functions These functions provide that an error code generated by one task is not reported in another task The errno global variable used by some functions may be modified by another task before the current task can read it Document Version 1 70 5 23 2012 51 Real Time Operating System Error Reporting Functions There are two RTOS functions for error reporting Refer to the Function Specification section for details on each function listed check_error Check the error code for the current task report_error Set the error code for the current task RTOS Example Application Program The following program is used in the explanation of the RTOS functions It creates several simple tasks that demonstrate how tasks execute A task is a C language function that has as its body an infinite loop so it continues to execute forever The main task creates two tasks Th
394. meter is formed by ORing one or more of the following MSG_DONTWAIT Don t wait for data but rather return immediately MSG_PEEK Peek at the data present on the socket the data is returned but not consumed so that a subsequent receive operation will see the same data Document Version 1 70 5 23 2012 479 Function Specifications Returns gt 0 0 1 recvfrom will fail if EBADF EINVAL EMSGSIZE EPROTOTYPE ENOBUFS EWOULDBLOCK Number of bytes actually received from the socket EOF An error occurred The socket descriptor is invalid One of the parameters is invalid The socket requires that message be received atomically and bufferLength was too small TCP protocol requires usage of recv not recvfrom There was insufficient user memory available to comp lete the operation The socket is marked as non blocking and no data is available to be read Document Version 1 70 5 23 2012 480 Function Specifications registerBulkDevOperation Register bulk device operation Syntax include lt ctools h gt BOOLEAN registerBulkDevOperation char extDriveName Description registerBulkDevOperation function registers that the removable bulk memory device is about to be used for an operation Registration is necessary prior to using the device in case the device is un mounted before the operation completes This provides that internal resources used for the bulk device are co
395. myFolder ProjectD ltem1 See Also copy xcopy Document Version 1 70 5 23 2012 571 Macro Definitions Macro Definitions AD_BATTERY Internal AD channel connected to lithium battery AIN_END specified applicationGroup Specifies an application type task All application tasks are terminated by the end_application function AT_ABSOLUTE Specifies a fixed time of day alarm AT_NONE Disables alarms BACKGROUND System event background I O requested The background I O task uses this event It should not be used in an application program Document Version 1 70 5 23 2012 572 Macro Definitions C Variable name cascade setpoint source CLASS0_FLAG Specifies a flag for enabling DNP Class 0 data CLASS1_FLAG Specifies a flag for enabling DNP Class 1 data CLASS2_FLAG Sspecifies a flag for enabling DNP Class 2 data CLASS3_FLAG Specifies a flag for enabling DNP Class 3 data CLOSED Specifies switch is in closed position COLD_BOOT Cold boot switch depressed when CPU was reset com1 Points to a file object for the com1 serial port COM1_RCVR System event indicates activity on com1 receiver The meaning depends on the character handler installed com2 Points to a file object for the com2 serial port COM2_RCVR System event indicates activity on com2 receiver The meaning depends on the character handler installed com3 Points to a file object for the com3 serial port COM3_RCVR System e
396. n Document Version 1 70 5 23 2012 195 Function Specifications dnpReadAddressMappingTableSize Read DNP Address Mapping Table size Syntax include lt ctools h gt UINT16 dnpReadAddressMappingTableSize void Description The dnpReadAddressMappingTableSize function reads the total number of entries in the DNP address mapping table The function returns the total number of entries in the DNP address mapping table Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 196 Function Specifications dnpReadMasterPollTableEntry Read DNP Master Poll Table entry Syntax include lt ctools h gt BOOLEAN dnpReadMasterPollTableEntry UINT16 index dnpMasterPoll type pMasterPoll 1 Description This function reads an entry from the DNP master poll table pMasterPoll is a pointer to a table entry it is written by this function The return value is TRUE if pMasterPoll was successfully written or FALSE otherwise Notes DNP needs to be enabled before calling this function in order to create the DNP configuration The function returns the total number of entries in the DNP routing table Document Version 1 70 5 23 2012 197 Function Specifications dnpReadMasterPollTableEntryEx Read DNP Master Poll Table Extended Entry Syntax BOOLEAN dnpReadMasterPollTableEntryEx UINT16 index DnpMas
397. n Replace main cpp Replace the sample file main cpp with the main cpp from your SCADAPack 32 C Application Edit your main cpp and make the following changes e In addition to the ctools h header you need to include the header file nvMemory h e The C Tools require main to have the prototype int main void Change the syntax of main so that it returns the data type int instead of void Note that the returned int value is not accessible to the user and so any value may be returned or none at all e Remove the function definition for abort This function is provided by the operating system e The call release_processor in the main loop can be deleted See section Operating System Scheduling for details Add Remaining C and CPP Files Copy any additional C CPP or H files from your application to the copied sample application directory Replace Partially Supported and Unsupported Functions Existing programs may use some functions that are partially supported or unsupported on the SCADAPack 350 4203 controllers The program needs to be changed to use the new functions of the SCADAPack 350 4203 controllers For a list of the functions affected refer to the sections Partially Supported C Tools Functions Document Version 1 70 5 23 2012 674 Porting Existing C Tools Applications Build the Application The SCADAPack C Tools use a command line to compile and link a C application The sample application in
398. n 50 Event Nottttceatton 50 Error Reportng 51 RTOS Example Application Program cccccccccceceeceeeeeeeeeeececeeeeeeeeeeeeenaaaes 52 Overview of Programming Functions cccccceeseeesseeeeeeeeees 60 Controller Ee e ue EEN 60 Controller VO Hardware eu fessesaveesstetstes ever aatetstes eves subst EKOS subst ee 62 SEfial COmMUNICAUO Nye EE 71 Serial Communication Protocols ccccccccceceeeeeeeeeeeeeeeccneeeeeeeeeeeecaaeeeeeeeentee 73 DNP Communication Protocol cccccceeceeeeeeeeeeeecceeeeeeeeeeeeecaaeeeeeeeeeeeeeaaaes 75 Document Version 1 70 5 23 2012 DEI Communication Protocol a rN 79 Re dee elle le EE 79 lee EH e e 79 Data LOOGING tec EE 80 SOCKEL A P LEE EE 81 Modbus l O atb eege en Pee A a a a S 82 fe Ee lun E TT 84 IEC 61131 1 Variable Access FUNCTIONS cceeeeceeeeeeeeeeeeeeeeeaeeeeeeeeeeeeenaaaes 85 HART Eormpmttnl alt ttet entsteet eg eben dee de E EE EE EE EEN 85 File Management API ii Attest beet naetined AER AER EEN 87 Function Specifications sisiiiaiiceccscdciscdnnincacsenssesdiarduansnsasucncsandenuane 88 Functions Supported by Telepace Omy 88 Functions Supported by IEC 61131 1 Only assesesseseeeseseseserressssserrrrnrsssssrnes 88 le 0 E E E E E uuu g veer ENEE ENNER 90 AadUREGASSIGNMEN sissies eshte eesti eee 92 addRegAssignmentEx EE 97 EI Un EE 103 allocate envelope ieee aE E ee 104 allocateMem Oy errre eee EEEE EEEE SEENTE EEPE HEOR A EEREN E NE
399. n The mTcpMasterMessage function builds a Modbus command message using the specified Modbus IP protocol and signals the mastering task to tell it to send the command The connectID specifies the connection ID returned by the function mTcpMasterOpen which was called to create a mastering task to service this connection The remotelP specifies the IP address of the remote slave The value of remotelP may be the same or different from the IP address used in mTcpMasterOpen or in a previous call to mTcpMasterMessage This is possible because the connect D represents the allocation of a connection from the connection pool and may be used to connect to any IP address When the IP address is changed between function calls the current connection is closed and a connection to the new IP address is automatically established It is more efficient to allocate one connectID and its associated master task for each remotelP because the connection remains connected to one IP address However if there are fewer connections available than there are remote slaves the same connectID can be used to re connect to multiple IP addresses Valid values for protocolType are IPP_ModbusTcp IPP_ModbusRtuOverUdp or IPP_ModbusAsciiOverUdp The remaining arguments are used in the same way as they are used in master_message to send a serial Modbus command e function specifies the Modbus function code Refer to the communication protocol manual for supported function
400. n Specifications checksum Calculate a Checksum Syntax include lt ctools h gt UINT16 checksum UCHAR start UCHAR end UINT16 algorithm Description The checksum function calculates a checksum on memory The memory starts at the byte pointed to by start and ends with the byte pointed to by end The algorithm may be one of ADDITIVE 16 bit byte wise sum CRC_16 CRC 16 polynomial checksum CRC_CCITT CRC CCITT polynomial checksum BYTE_EOR 8 bit byte wise exclusive OR The CRC checksums use the crc_reverse function Example This function displays two types of checksums include lt ctools h gt void checksumExample void char str This is a test UINT16 sum Display additive checksum sum checksum str str strlen str ADDITIVE fprintf coml Additive checksum u r n sum r r Display CRC 16 checksum sum checksum arr str strlen str CRC 16 fprintf coml CRC 16 checksum u r n sum Document Version 1 70 5 23 2012 108 Function Specifications checkSFTranslationTable Test for Store and Forward Configuration Errors Syntax include lt ctools h gt struct SFTranslationStatus checkSFTranslationTable void Description The checkSFTranslationTable function checks all entries in the address translation table for validity It detects the following errors The function returns a SFTranslationStatus structure Refer to the Structures and Types section for
401. n Specifications section for more details Program Status Functions The functions getProgramStatus and setProgramStatus have changed syntax To support multiple C applications these functions now have an argument to specify the application The new syntax for these functions is documented in the Function Specifications section Freeing Dynamic Memory When a C Application is ended e g by using the STOP button from the C C Program Loader memory allocated by using the malloc function is not freed automatically An exit handler must be installed to free allocated memory Please see the documentation for installExitHandler in the Function Specifications section for more details Non Volatile Data Sections The SCADAPack 350 and 4203 have a different method for declaring static non volatile memory There is still 8 kB of memory available but it needs to now be shared with all user loaded C applications Non volatile variable declarations and their pragma statements need to be removed from each source file and declared globally in the one file nvMemory h Include nvMemory h in each source file that uses non volatile variables Please see the section Non Volatile Memory for more details on editing nvMemory h and on using these variables in your source files Socket Functions The following functions are no longer supported The replacement function is indicated for each Replaced wih EE EE Modbus Handler Functions
402. n of the ABConfiguration structure for an explanation of the fields The setABConfiguration function returns TRUE if the settings were changed It returns FALSE if stream does not point to a valid serial port See Also getABConfiguration Example This code fragment changes the maximum protected address to 7000 This is the maximum address accessible by protected DEI commands received on com2 include lt ctools h gt struct ABConfiguration ABConfig getABConfiguration com2 amp ABConfig ABConfig max protected address 7000 setABConfiguration com2 amp ABConfig Document Version 1 70 5 23 2012 508 Function Specifications setBreakCondition Set a break condition on a serial port Syntax include lt ctools h gt void setBreakCondition FILE stream 1 Parameters stream is a pointer to a serial port valid serial ports are com1 com2 com3 and com4 Description The setBreakCondition function activates the break condition on the communication port specified by stream The break condition will persist until it is cleared by calling clearBreakCondition Notes If the serial port is transmitting characters when this function is called the transmission may not complete correctly No subsequent character transmissions will be possible until after clearBreakCondition has been called This function is only relevant for RS232 ports The function will have no effect on other port types See
403. n the alarm setting No change is made to the alarm settings if there is an error Notes An alarm will occur only once but remains set until disabled Use the resetClockAlarm function to acknowledge an alarm that has occurred and re enable the alarm for the same time Set the alarm type to AT_NONE to disable an alarm It is not necessary to specify the hour minute and second when disabling the alarm The IO_SYSTEM resource needs to be requested before calling this function See Also getClockAlarm Document Version 1 70 5 23 2012 511 Function Specifications setdbase Write Value to I O Database Syntax include lt ctools h gt void setdbase UINT16 type UINT16 address INT16 value Description The setdbase function writes value to the I O database type specifies the method of addressing the database address specifies the location in the database The table below shows the valid address types and ranges Type Address Ranges Register Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001 to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1 Notes If the specified register is currently forced the I O database remains unchanged When writing to LINEAR digital addresses value is a bit mask which writes data to 16 1 bit registers at once If any of these 1 bit registers is currently forced only the forced registers remain unchanged The I O database is not modified when t
404. n the priority of tasks There are 256 priority levels Level 255 is reserved for the null task This task runs when there are no other tasks available for execution Application programs can use levels 100 to 0 The main task is created at priority level 100 Tasks that are not running are held in queues The Ready Queue holds tasks that are ready to run Event queues hold tasks that are waiting for events Message queues hold tasks waiting for messages Resource queues hold tasks that are waiting for resources The envelope queue holds tasks that are waiting for envelopes The execution of the tasks is illustrated by examining the state of the queues at various points in the program These points are indicated on the program listing above The examples show only the Ready queue the Event 10 queue and the executing task These are the only queues relevant to the example This point occurs just before the main task begins The main task has not been created by the RTOS The null task has been created but is not running No task is executing Document Version 1 70 5 23 2012 55 Real Time Operating System Event 10 Queue Running Task none Figure 1 Queue Status before Execution of main Task Execution Point 2 This point occurs just after the creation of the main task It is the running task On the next instruction it will create the echoData task Ready Queue
405. name however because the variable name must be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the setdbase function The IO_SYSTEM system resource needs to be requested before calling this function Example This program writes the value 120 000 to the integer variable named Pressure include lt ctools h gt int main void BOOLEAN status request _ resource IO_ SYSTEM status writeIntVariable Pressurel 120000 release resource IO SYSTEM Document Version 1 70 5 23 2012 565 Function Specifications writeRealVariable Write to IEC 61131 1 Real Variable IEC 61131 1 firmware only Syntax include lt ctools h gt BOOLEAN writeRealVariable UCHAR varName float value Description This function writes to the specified real i e floating point variable The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the specified floating point value is written to the variable If the variable is not found or if the IEC 61131 1 Symbols Status is invalid nothing is done and FALSE is returned The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Appli
406. nction Specifications Application version major 100 minor Company Identifier Control Microsystems will maintain a list of company identifiers to keep the company IDs is unique Contact the technical support department Company ID 0 indicates an identifier is unused See Also configurationRegisterMapping Notes Application IDs for C programs are not automatically removed A task exit handler can be used to remove the ID when the C application is ended Application IDs are cleared when the controller is reset Document Version 1 70 5 23 2012 124 Function Specifications connect Syntax include lt ctools h gt int connect int socketDescriptor const struct sockaddr addressPtr int addressLength 1 Description The parameter socketDescriptor is a socket If it is of type SOCK_DGRAM connect specifies the peer with which the socket is to be associated this address is the address to which datagrams are to be sent if a receiver is not explicitly designated it is the only address from which datagrams are to be received If the socket socketDescriptor is of type SOCK_STREAM connect attempts to make a connection to another socket either local or remote The other socket is specified by addressPtr addressPir is a pointer to the IP address and port number of the remote or local socket If socketDescriptor is not bound then it will be bound to an address selected by the underlying transport provide
407. ngs dialmethod 0 strcpy dialSettings modemCommand amp F1 amp A0 amp KO amp MO amp B1 strcpy dialSettings phoneNumber 555 1212 Document Version 1 70 5 23 2012 634 Example Programs set up exit handler for this task getTaskInfo 0 amp taskStatus installExitHandler taskStatus taskID FUNCPTR myshutdown Connect to the remote controller if modemDial amp dialSettings amp portID DE NoError do Allow other tasks to execute release processor Wait for initialization to complete modemDialStatus coml portID status amp state while state DS Calling If the remote controller connected if state DS Connected Talk to remote controller here Terminate the connection modemDialEnd coml portID amp status A pause of a few seconds is required between terminating a connection and initiating a new call This pause allows the external modem time to hang up Create Task Example include lt ctools h gt define TIME TO PRINT 20 void taski void int a b while TRUE body of task 1 loop processing I O request resource IO SYSTEM a dbase MODBUS 30001 b dbase MODBUS 30002 setdbase MODBUS 40020 a b release resource IO SYSTEM Document Version 1 70 5 23 2012 635 Example Programs void task2 void while TRUE
408. ngs were read The function returns FALSE if the module number is invalid See Also hartSetConfiguration Document Version 1 70 5 23 2012 296 Function Specifications hartSetConfiguration Write HART Module Settings Syntax include lt ctools h gt BOOLEAN hartSetConfiguration UINT16 module HART SETTINGS settings Description This function writes configuration settings to a 5904 module The function has two parameters the module number of the 5904 module 0 to 3 and a settings structure The function returns TRUE if the settings were written The function returns FALSE if the module number or the settings are invalid Notes The configuration settings are stored in flash The user defined settings are used when the controller is reset in the RUN mode Default settings are used when the controller is reset in the SERVICE or COLD BOOT modes To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY See Also hartGetConfiguration Document Version 1 70 5 23 2012 297 Function Specifications hartPackString Convert String to HART Packed String Syntax include lt ctools h gt void hartPackString CHAR pPackedString const CHAR pString UINT16 sizePackedString Description This function stores an ASCI
409. ngthPtr Description recvfrom is used to receive messages from another socket recvfrom may be used to receive data on a socket whether it is in a connected state or not but not on a TCP socket socketDescriptor is a socket created with socket If fromPir is not a NULL pointer the source address of the message is filled in fromLengthPtr is a value result parameter initialized to the size of the buffer associated with fromPtr and modified on return to indicate the actual size of the address stored there The length of the message is returned If a message is too long to fit in the supplied buffer excess bytes may be discarded depending on the type of socket the message is received from see socket If no messages are available at the socket the receive call waits for a message to arrive unless the socket is non blocking or the MSG_DONTWAIT flag is set in the flags parameter in which case 1 is returned with socket error being set to EWOULDBLOCK select may be used to determine when more data arrives or and when out ofband data arrives Parameters socketDescriptor The socket descriptor to receive data from bufferPtr The buffer to put the received data into bufferLength The length of the buffer area that bufferPtr points to flags See Below fromPtr The socket the data is or to be received from fromLengthPir The length of the data area the fromPtr points to then upon return the actual length of the from data The flags para
410. nication can be difficult to debug This section describes common causes of communication failures To communicate the controller and an external device need to use the same communication parameters Check the parameters in both units If some but not all characters transmit properly you probably have a parity or stop bit mismatch between the devices The connection between two RS 232 Data Terminal Equipment DTE devices is made with a null modem cable This cable connects the transmit data output of one device to the receive data input of the other device and vice versa The controller is a DTE device This cable is described in the System Hardware Manual for your controller The connection between a DTE device and a Data Communication Equipment DCE device is made with a straight cable The transmit data output of the DTE device is connected to the transmit data input of the DCE device The receive data input of the DTE device is connected to the receive data output of the DCE device Modems are usually DCE devices This cable is described in the System Hardware Manual for your controller Many RS 232 devices require specific signal levels on certain pins Communication is not possible unless the required signals are present In the Document Version 1 70 5 23 2012 71 Overview of Programming Functions controller the CTS line needs to be at the proper level The controller will not transmit if CTS is OFF If the CTS line i
411. ns invalid slave IP address MM_BUSY returns last message is still being processed MM_ENDED returns Master connection has been released This status is only reported by the IEC 61131 1 masterIP function block It is not available from the mTcpMasterStatus function MM_CONNECT_ERROR returns error while connecting to slave IP address Document Version 1 70 5 23 2012 618 Structures and Types Modemlnit ModemSetup MM_NO_MORE_CONNECTIONS returns no more connections are available MM_BAD_CONNECTION_TYPE returns invalid connection type used in mTcpMasterMessage MM_EXCEPTION_FUNCTION Returns master message status Modbus slave returned a function exception MM_EXCEPTION_ADDRESS Returns master message status Modbus slave returned an address exception MM_EXCEPTION_VALUE Returns master message status Modbus slave returned a value exception MM_QUEUE_FULL Returns master message status Serial transmit queue is full MM_STATIONS ARE_EQUAL Returns master message status Master and slave stations are equal They must be different The ModemInit structure specifies modem initialization parameters for the modemlnit function struct ModemInit F FILE port CHAR modemCommand MODEM CMD MAX LEN 2 port is the serial port where the modem is connected modemCommand is the initialization string for the modem The characters AT will be prefixed to the command and a carriage returned suffixed to the com
412. nse string It will be added to the response string before sending the reply The maximum size of the response string is 253 bytes If a longer response length is returned the Modbus protocol will report an ILLEGAL_DATA_VALUE exception The response will not be returned See Also installModbusHandler Document Version 1 70 5 23 2012 282 Function Specifications hartlO Read and Write 5904 HART Interface Module Syntax include lt ctools h gt BOOLEAN hartIO UINT16 module Description This function reads the specified 5904 interface module It checks if a response has been received and if a corresponding command has been sent If so the response to the command is processed This function writes the specified 5904 interface module It checks if there is a new command to send If so this command is written to the 5904 interface The function has one parameter the module number of the 5904 interface 0 to 3 The I O read and write operations are added to the I O System queue The function returns TRUE if the 5904 interface responded to the previous I O request and FALSE if it did not or if the module number is not valid Notification of the completion of I O requests made by this function may be obtained using the ioNotification function See Also hartSetConfiguration hartGetConfiguration hartCommand ioNotification Document Version 1 70 5 23 2012 283 Function Specifications hartCommand
413. ntax include lt ctools h gt void modemDialEnd FILE port reserve id id enum DialError error Description The modemDialEnd function terminates a dial up connection or connection in progress port specifies the serial port the where the modem is installed id is the port reservation identifier returned by the modemDial function The function sets the variable pointed to by error If no error occurred DE_NoError is returned Any other value indicates an error Refer to the Structures and Types section for a complete Description of error codes Notes The serial port type must be set to RS232_MODEM A connection can be terminated by any of the following events Once terminated another modem function or incoming call can take control of the serial port e Execution of the modemDialEnd function e Execution of the modemAbort or modemAbortAll functions e The remote device hangs up the phone line e An accidental loss of carrier occurs due to phone line problems A pause of a few seconds is required between terminating a connection and initiating a new call This pause allows the external modem time to hang up The reservation identifier is valid until the call is terminated and another modem function or an incoming call takes control of the port The modemDialEnd function returns a DE_NotInControl error code if another modem function or incoming call is in control of the port Do not call this function in a task e
414. ntrollerStatus AIN_5502 DIAG_forceLED AIN_ 5503 DIAG_IPConnections AIN 5504 DIAG_ModbusStatus AIN 5505 DIAG_protocolStatus AIN_5506 DIN 5401 AIN_ 5521 DIN 5402 AIN_generic8 DIN_ 5403 AOUT_5301 DIN 5404 AOUT_5302 DIN 5405 AOUT_5304 DIN 5414 AOUT_generic2 DIN 5421 AOUT_generic4 DIN_generic16 CNFG_5904Modem DIN_generic8 CNFG_clearPortCounters DOUT_5401 CNFG_clearProtocolCounters DOUT_5402 CNFG_ PSettings DOUT_5406 CNFG_LEDPower DOUT_5407 CNFG_modbuslpProtocol DOUT_5408 CNFG_MTCPIfSettings DOUT_5409 CNFG_MTCPSettings DOUT_5411 CNFG_PIDBlock DOUT_5415 Document Version 1 70 5 23 2012 97 Function Specifications CNFG_portSettings CNFG_protocolExtended CNFG_protocolExtendedEx CNFG_protocolSettings CNFG_realTimeClock CNFG_saveTOoEEPROM CNFG_setSerialPortDTR CNFG_storeAndForward SCADASENSE_4203_DR CNTR_520xCounter nputs SCADAPack_5607I0 SCADAPack_35010 DOUT_generic16 DOUT_generic8 SCADAPack_AOUT SCADAPack_lowerlO SCADAPack_upperlO SCADAPack_LPIO SCADAPack_2IO SCADAPack_100IO0 SCADAPack_560610 SCADASENSE_4203_DS SCADAPack_33xlO moduleAddress specifies a unique address for the module For the valid range for moduleAddress refer to the list of modules in the chapter Register Assignment Reference of the Telepace Ladder Logic Reference and User Manual For module addresses com com2 com3 or com4 specify 0 1 2 or 3 respectively for moduleAddress For module address Ethernet specify 4 for moduleAddress For module type
415. o 5000 analog input modules or SCADAPack I O modules through the Register Assignment Input registers may also be assigned to controller internal analog inputs and to system diagnostic modules Holding Registers Document Version 1 70 5 23 2012 82 Overview of Programming Functions Holding or analog output database registers may be assigned to 5000 analog output modules or SCADAPack analog output modules through the Register Assignment Holding registers may also be assigned to system diagnostic and configuration modules Modbus I O Database Functions There are several library functions related to the Modbus database Refer to the Function Specification section for details on each function listed dbase installDbaseHandler installSetdbaseHandler Dbase Handler Function setdbase Reads a value from the database Allows an extension to be defined for the dbase function Allows an extension to be defined for the setdbase function User defined function that handles reading of Modbus addresses not assigned in the IEC 61131 1 Dictionary Writes a value to the database Setdbase Handler Function User defined function that handles writing to Modbus I O Database Macros Modbus addresses not assigned in the IEC 61131 1 Dictionary The ctools h file defines library functions for the I O database Refer to the C Tools Macros section for details on each macro listed AB Specifies Allan Bradley database addres
416. o 9999 e CI32_wordOrder is the Word Order of C132 points O LSW first 1 MSW first e Al16_number is the number of 16 bit analog input points Valid values are 0 to 9999 e Al16_startAddress is the DNP address of the first Al16 point e Al16_reportingMethod determines how 16 bit analog changes are reported e Set this to FIRST_VALUE to report the value of the first change event measured e Set this to CURRENT_VALUE to report the value of the latest change event measured e Al16_bufferSize is the number of events in the 16 bit analog input change buffer Valid values are 0 to 9999 e AI32_number is the number of 32 bit analog input points Valid values are 0 to 9999 e Al32_startAddress is the DNP address of the first Al32 point e AlI32_reportingMethod determines how 32 bit analog changes are reported e Set this to FIRST_VALUE to report the value of the first change event measured e Set this to CURRENT_VALUE to report the value of the latest change event measured Document Version 1 70 5 23 2012 603 Structures and Types e Al832_bufferSize is the number of events in the 32 bit analog input change buffer Valid values are 0 to 9999 e AI32_wordOrder is the Word Order of Al32 points O LSW first 1 MSW first e AISF_number is the number of short float Analog Inputs e AISF_startAddress is the DNP address of first AISF point e AISF_reportingMethod is the event reporting method Change Of State or Log All Even
417. o a different path then substitute the correct path here o Click OK e Click OK Installing Telepace Install Telepace as described on the jewel case liner of the Telepace Installation CD Some virus checking software may interfere with Setup If you experience difficulties with the Setup disable your virus checker and run Setup again Installing IEC 61131 1 Workbench Install IEC 61131 1 as described on the jewel case liner of the IEC 61131 1 Installation CD Some virus checking software may interfere with Setup If you experience difficulties with the Setup disable your virus checker and run Setup again Viewing Installed Components The C Tools installs the following components All files are installed by default to C program files Control Microsystems CTools e gnu C compiler for Arm7 processor is installed in the ARM7 folder e C Tools header and support files are installed in o Controller IEC 61131 1 for IEC 61131 1 firmware applications o Controller Telepace for Telepace firmware applications e Framework applications are installed in Controller Framework Applications These are described further in the product development tutorial e Documentation shortcuts are on the Start menu You need to have found them if you re reading this so we won t say any more Program Development Tutorial Program development consists of three stages writing and editing compiling and linking and loading the program into the targ
418. o by userName userName must point to an array of 16 unsigned characters The SF_TRANSLATION_EX structure supports a timeout and is described in the Structures and Types section Notes The TeleBUS Protocols User Manual describes the store and forward messaging mode See Also setSFTranslationEx clearSFTranslationTable checkSFTranslationTable Document Version 1 70 5 23 2012 269 Function Specifications getsockname Syntax include lt ctools h gt int getsockname int socketDescriptor struct sockaddr myAddressPtr int addressLengthPtr 1 Description This function returns to the caller the Local IP Address Port Number that we are using on a given socket Parameters socketDescriptor The socket descriptor that we wish to inquire about myAddressPir The pointer to the address structure where the address information will be stored addressLengthPtr The length of the address structure Returns 0 Success 1 An error occurred getsockname can fail for any of the following reasons EBADF socketDescriptor is not a valid descriptor EINVAL One of the passed parameters is not valid Document Version 1 70 5 23 2012 270 Function Specifications getsockopt Syntax include lt ctools h gt int getsockopt int socketDescriptor int protocolLevel int optionName char optionValuePtr int optionLengthPtr 1 Description getsockopt is used retrieve options associated
419. oReadAout2 ioReadAout4 ioReadAout5303 ioRead5606Outputs Read buffered data for 2 point analog output module Read buffered data for 4 point analog output module Read buffered data for 5303 analog output module Read the digital and analog outputs from a 5606 I O Module Document Version 1 70 5 23 2012 63 Overview of Programming Functions ioRead56070utputs ioWriteAout2 ioWriteAout4 ioWriteAout5303 ioWrite4203DRInputs iowrite4203DSInputs ioWrite5606Outputs ioWrite56070utputs Digital Input Functions Read the digital and analog outputs from a 5607 I O Module Write buffered data for 2 point analog output module Write buffered data for 4 point analog output module Write buffered data for 5303 analog output module Write to the outputs of a 4203 DR controller Write to the outputs of a 4203 DS controller Write to the digital and analog outputs of a 5606 I O Module Write to the digital and analog outputs of a 5607 I O Module The controller supports internal digital inputs and external digital input modules Refer to the SCADAPack 350 System Hardware Manual for further information on controller digital inputs and digital input modules There are several library functions related to digital inputs and external digital input modules Refer to the Function Specification section for details on each function listed ioRead5606Inputs ioReadDin5232 ioReadCounter5232 ioRead5414Inputs ioWrite54140Outputs ioRea
420. oaded to the controller from the program loader The status flag is set to PROGRAM_NOT_LOADED when the C program is erased The application program may modify the status flag with the setProgramStatus function See Also setProgramStatus Example See the Get Program Status Example in the Examples section Document Version 1 70 5 23 2012 261 Function Specifications get_protocol Get Protocol Configuration Syntax include lt ctools h gt struct prot_settings get protocol FILE stream struct prot_settings settings Description The get_protocol function gets the communication protocol configuration for the port If port does not point to a valid serial port the function has no effect settings must point to a protocol configuration structure prot_settings The get_protocol function copies the protocol settings into the structure pointed to by settings and returns a pointer to that structure Refer to the ctools h file for a Description of the fields in the prot_settings structure Refer to the Overview of Functions section for detailed information on communication protocols See Also set_protocol Example This program displays the protocol configuration for com1 include lt ctools h gt int main void struct prot settings settings get_protocol coml amp settings fprintf coml Type sd r n settings type fprintf coml Station d r n settings station fprintf coml Priorit
421. ocessor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 383 Function Specifications ioWrite5606Outputs Write 5606 Outputs Syntax include lt ctools h gt BOOLEAN ioWrite56060utputs UINT16 moduleAddress UCHAR amp doutData 2 INT16 amp aoutData 2 UINT16 amp inputType 8 UINT16 inputFilter UINT16 scanFrequency UINT16 outputType Description This function writes data to the I O table for the 16 digital outputs and 2 analog outputs of a 5606 I O module Data are written to the module when an I O request for the module is processed moduleAddress is the address of the 5606 module Valid values are 0 to 7 doutData is a reference to an array of two UCHAR variables Digital data for the 16 outputs are read from this array One bit in the array represents each output point aoutData is a reference to an array of two INT16 variables Analog data for the two analog outputs are read from this array inputType is a reference to an array of eight UINT16 variables selecting the input range for the corresponding analog input Valid values are e 0 0to 5V e 1 0to10V e 2 0to20mA e 3 4to 20 mA inputFilter selects input filter selection is written to this variable e 0 3Hz e 1 6Hz e 2 11 Hz e 3 30 Hz scanFrequency selects the scan frequency setting Valid values are e 0 60Hz e 1 50 Hz Document Version 1 70 5 23 2012 384 Function Specifi
422. ocol settings of the specified serial port determine the protocol type enabled by this function This function should only be needed in the context of the startup function appstart See Also set_port get_port Document Version 1 70 5 23 2012 551 Function Specifications startup_task Identify Start Up Task Syntax include lt ctools h gt struct taskInfo tag startup_task void Description The startup_task function returns the address of the system or application start up task Notes This function is used by the reset routine It is normally not used in an application program Document Version 1 70 5 23 2012 552 Function Specifications startTimedEvent Enable Signaling of a Regular Event Syntax include lt ctools h gt UINT16 startTimedEvent UINT16 event UINT16 interval Description The startTimedEvent function causes the specified event to be signaled at the specified interval interval is measured in multiples of 0 1 seconds The task that is to receive the events should use the wait_event or poll_ event functions to detect the event The function returns TRUE if the event can be signaled If interval is 0 or if the event number is not valid the function returns FALSE and no change is made to the event signaling a previously enabled event will not be changed Notes Valid events are numbered 0 to RTOS_EVENTS 1 Any events defined in primitiv h are not valid events for use
423. odes The function sets the variable pointed to by state to the current execution state of the dialing operation The state value is not valid if the error code is DE_NotInControl Refer to the dialup h section for a complete Description of state codes Notes The serial port type must be set to RS232_MODEM The port will remain in the DS_Calling state until modem initialization is complete or fails The application should wait until the state is not DS_Calling before calling the modemInitEnd function The reservation identifier is valid until the initialization is complete or terminated and another modem function or an incoming call takes control of the port Do not call this function in a task exit handler Document Version 1 70 5 23 2012 428 Function Specifications modemNotification Notify the modem handler of an important event Syntax include lt ctools h gt void modemNotification UINT16 port index Description The modemNotification function notifies the dial up modem handler that an interesting event has occurred This informs the modem handler not to disconnect an incoming call when an outgoing call is requested with modemDial This function is used with custom communication protocols The function is usually called when a message is received by the protocol although it can be called for other reasons The port_index indicates the serial port that received the message Notes The serial port type mu
424. ointed to by error If no error occurred DE_NoError is returned Any other value indicates an error Refer to the dialup h section for a complete Description of error codes Notes The serial port type must be set to RS232_MODEM Normally this function should be called once the modemInitStatus function indicates the initialization is complete The reservation identifier is valid until the initialization is complete or terminated and another modem function or an incoming call takes control of the port The modemInitEnd function returns a DE_NotInControl error code if another modem function or incoming call is in control of the port Do not call this function in a task exit handler Use modemAbort instead Document Version 1 70 5 23 2012 427 Function Specifications modeminitStatus Return Status of Dial up Modem Initialization Syntax include lt ctools h gt void modemInitStatus FILE port reserve id id enum DialError error enum DialState state Description The modemInitStatus function returns the status of a modem initialization started by the modemInit function port specifies the serial port where the modem is installed id is the port reservation identifier returned by the modemInit function The function sets the variable pointed to by error If no error occurred DE_NoError is returned Any other value indicates an error Refer to the Structures and Types section for a complete Description of error c
425. ol Get interface settings used by the Modbus IP protocols mTcpMasterOpen Allocates a connection ID and creates a task to service a Modbus IP master messaging connection mTcpMasterMessage Builds the Modbus command and sends a message to the mastering task to tell it to send the command mTcpMasterStatus Returns the master command status for the specified connection mTcpMasterDisconnect Tells a Modbus IP master task to disconnect and mTcpMasterClose Data Logging end the task Returns a master connection ID to the connection pool The SCADAPack 330 and SCADAPack 350 controllers 4203 support data logging to the internal file system and data logging to a mass storage device connected via the USB host port Data Log Functions datalogCreate datalogDelete datalogPurge This function creates a data log with the specified configuration The data log is created in the data log memory space This function destroys the specified data log The memory used by the data log is returned to the freed section This function removes records from a data log The function can remove all the records or a group of records starting with the oldest in the log Document Version 1 70 5 23 2012 80 Overview of Programming Functions datalogReadNext datalogReadStart datalogRecordSize datalogSettings datalogWrite Data Log Enumeration Types This function reads the next record from the data log starting at the specifi
426. oller The LED power returns to its default state after a user specified time period Example See the Example for the ledSetDefault function Document Version 1 70 5 23 2012 407 Function Specifications ledPower Set LED Power State Syntax include lt ctools h gt UINT16 ledPower UINT16 state Description The ledPower function sets the LED power state The LED power will remain in the state until the default time out period expires state needs to be LED_ON or LED_OFF The function returns TRUE if state is valid and FALSE if it is not Notes The LED POWER switch also controls the LED power A user may override the setting made by this function The ledSetDefault function sets the default state of the LED power This state overrides the value set by this function See Also ledPowerSwitch ledPowerSwitch Document Version 1 70 5 23 2012 408 Function Specifications ledPowerSwitch Read State of the LED Power Switch Syntax include lt ctools h gt UINT16 ledPowerSwitch void Description The ledPowerSwitch function returns the status of the led power switch The function returns FALSE if the switch is released and TRUE if the switch is pressed Notes This switch may be used by the program for user input However pressing the switch will have the side effect of changing the LED power state See Also ledPower ledSetDefault Document Version 1 70 5 23 2012 409 Function
427. om network byte order to host byte order Parameters shortValue The value to convert Returns The converted value Document Version 1 70 5 23 2012 447 Function Specifications overrideDbase Overwrite Value in Forced I O Database Telepace firmware only Syntax include lt ctools h gt BOOLEAN overrideDbase UINT16 type UINT16 address INT16 value Description The overrideDbase function writes value to the I O database even if the database register is currently forced type specifies the method of addressing the database address specifies the location in the database If the register is currently forced the register remains forced but forced to the new value If the address or addressing type is not valid the I O database is left unchanged and FALSE is returned otherwise TRUE is returned The table below shows the valid address types and ranges Type Address Ranges Register Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001 to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1 Notes When writing to LINEAR digital addresses value is a bit mask which writes data to 16 1 bit registers at once The I O database is not modified when the controller is reset It is a permanent storage area which is maintained during power outages Refer to the Functions Overview chapter for more information The IO_SYSTEM resource needs to be requested before calling this func
428. omatically terminated when IEC 61131 1 stops the C application and when the controller is rebooted This function will terminate all open dial up connections or modem initializations started by the C application even those started by other tasks The exit handler can call this function instead of multiple calls to modemAbort if all the connections or initializations were started from the same task Reservation IDs returned by the modemDial and modemInit functions are invalid after calling modemAbort or modemAbortAll See Also Example This program installs an exit handler for the main task that terminates any dial up connections made by the task This handler is not strictly necessary if IEC 61131 1 ends the main task However it demonstrates how to use the modemAbortAll function and an exit handler for another task in a more complex program include lt ctools h gt Document Version 1 70 5 23 2012 419 Function Specifications The myShutdown function aborts any active modem connections when the task is ended void myShutdown void modemAbortAll int main void TASKINFO taskStatus set up exit handler for this task getTaskInfo 0 amp taskStatus installExitHandler taskStatus taskID FUNCPTR MyShutdown while TRUE vest of main task here Allow other tasks to execute release processor Document Version 1 70 5 23 2012 420 Function Specifications
429. on Syntax include lt ctools h gt DND PROTOCOL STATUS dnpStationStatus UINT16 dnpAddress BOOLEAN clear 1 Description The dnpStationStatus function returns the DNP message statistics for a remote DNP station dnpAddress is the address of the remote DNP station Valid values are any DNP station number in the range 1 to 65532 If clear is TRUE the DNP message counters are reset to zero after they are read Document Version 1 70 5 23 2012 221 Function Specifications dnpWriteAddressMappingTableEntry Write DNP Address Mapping Table Entry Syntax include lt ctools h gt BOOLEAN dnpWriteAddressMappingTableEntry UINT16 index UINT16 dnpRemoteStationAddress CHAR dnpObjectType UINT16 dnpRemoteObjectStart UINT16 numberOfPoints UINT16 dnpLocalModbusAddress 1 Description The dnpWriteAddressMappingTableEntry function writes an entry in the DNP address mapping table The function returns TRUE if successful FALSE otherwise Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 222 Function Specifications dnpWriteMasterApplicationLayerConfig Write DNP Master Application Layer Configuration Syntax include lt ctools h gt BOOLEAN dnpWriteMasterApplicationLayerConfig UINT16 basePollInterval UINT16 mimicMode 1 Description This function writes DNP Master application layer
430. on Syntax include lt ctools h gt void setIOErrorIndication BOOLEAN state Description The setlOErrorIndication function sets the I O module error indication to the specified state If set to TRUE the I O module communication status is reported in the controller status register and Status LED If set to FALSE the I O module communication status is not reported To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request resource FLASH MEMORY flashSettingsSave CS PERMANENT release resource FLASH MEMORY Notes Refer to the 5203 4 System Manual SCADAPack 32 System Manual or SCADAPack 350 System Manual for further information on the Status LED and Status Output See Also getlOErrorIndication Document Version 1 70 5 23 2012 519 Function Specifications setOutputsInStopMode Set Outputs In Stop Mode Telepace firmware only Syntax include lt ctools h gt void setOutputsInStopMode BOOLEAN holdDoutsOnStop BOOLEAN holdAoutsOnStop 1 Description The setOutputsInStopMode function sets the holdDoutsOnStop and holdAoutsOnStop control flags to the specified state If holdDoutsOnStop is set to TRUE then digital outputs are held at their last state when the Ladder Logic program is stopped If holdDoutsOnStop is FALSE then digital outputs are turn
431. on CI32 bufferSize 0 configuration CI32 wordOrder MSW_FIRST configuration AI16 number 9517 configuration AI16 startAddress 0 configuration AI16 reportingMethod REPORT ALL EVENTS configuration AI16 bufferSize 1000 configuration AI32 number 0 configuration AI32 startAddress 100 configuration AI32 reportingMethod REPORT ALL EVENTS configuration AI32 bufferSize 0 configuration AI32 wordOrder MSW_FIRST configuration AISF number 0 configuration AISF startAddress 200 configuration AISF reportingMethod REPORT CHANGE EVENTS configuration AISF bufferSize 0 configuration AISF wordOrder MSW_FIRST Document Version 1 70 5 23 2012 643 Example Programs configuration AO16 number 20 configuration AO16 startAddress 0 configuration AO32 number 12 configuration AO32 startAddress 100 configuration A032 wordOrder MSW_FIRST configuration AOSF number Spp configuration AOSF startAddress 200 configuration AOSF wordOrder MSW_FIRST configuration autoUnsolicitedClass1l TRUE configuration holdTimeClassl 10 configuration holdCountClass1l 3 configuration autoUnsolicitedClass2 TRUE configuration holdTimeClass2 10 configuration holdCountClass2 3 configuration autoUnsolicitedClass3 TRUE configuration holdTimeClass3 10 configuration holdCo
432. on has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetBIConfig Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 210 Function Specifications dnpSaveBlConfigEx Write DNP Binary Input Extended Point Syntax BOOLEAN dnpSaveBIConfigEx UINT16 point dnpBinaryInputEx pBinarylInput 1 Description This function writes the configuration of an extended DNP Binary Input point The function has two parameters the point number and a pointer to an extended binary input point configuration structure The function returns TRUE if the configuration was successfully written It returns FALSE if the point number is not valid if the configuration is not valid or if the DNP configuration has not been created This function supersedes dnpSaveB Contfig Document Version 1 70 5 23 2012 211 Function Specifications dnpSaveBOConfig Save DNP Binary Output Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveBOConfig UINT16 point dnpBinaryOutput pBinaryOutput 1 Description The dnpSaveBOConfig function sets the configuration of a DNP binary output point The function has two parameters the point number and a pointer to a binary output point configuration structure The function returns TRUE if the configuration was written It returns FALSE
433. on value is returned User variable is of data type described below Pointer to the size of the user variable which is the size of the option data type described below It is a value result parameter and the user should set the size prior to the call Socket level protocol IP level protocol TCP level protocol Option Name SO_ACCEPTCONN SO_DONTROUTE SO_KEEPALIVE SO_LINGER SO_OOBINLINE SO_RCVBUF SO_RCVLOWAT SO_REUSEADDR SO_SNDBUF SO_SNDLOWAT IP_MULTICAST_IF IP_MULTICAST_TTL IP_TOS Option data type int int int struct linger int unsigned long unsigned long int unsigned long unsigned long struct in_addr unsigned char unsigned char Option value 0 or 1 0 or 1 0 or 1 Oor 1 Oor1 Document Version 1 70 5 23 2012 273 Function Specifications Protocol Level Option Name Option data Option value type IP_TTL unsigned char IP_PROTOTCP TCP_MAXSEG int TCP_NODELAY int Oori Returns Value Meaning 0 Successful set of option 1 An error occurred getsockopt will fail if EBADF The socket descriptor is invalid EINVAL One of the parameters is invalid ENOPROTOOPT The option is unknown at the level indicated Document Version 1 70 5 23 2012 274 Function Specifications get_status Get Serial Port Status Syntax include lt ctools h gt struct pstatus get_status FILE stream struct pstatus status Description The get_status function returns serial port error co
434. onnects to the RS 232 port with a DTE to DCE cable Consult the System Hardware Manual for your controller for details Refer to the Function Specification section for details on each function listed The dial up modem functions apply to the SCADAPack 350 controllers RS 232 ports modeminit send initialization string to dial up modem modeminitStatus read status of modem initialization operation modemInitEnd terminate modem initialization operation Document Version 1 70 5 23 2012 72 Overview of Programming Functions modemDial connect with an external device using a dial up modem modemDialStatus read status of connection with external device using a dial up modem modemDialEnd terminate connection with external device using a dial up modem modemAbort unconditionally terminate connection with external device or modem initialization used in task exit handler modemAbortAll unconditionally terminate connections with external device or modem initializations used in task exit handler modemNotification notify the dial up modem handler that an interesting event has occurred This function is usually called whenever a message is received by a protocol Dial Up Modem Macros The ctools h file defines the following macros of interest to a C application program Refer to the C Tools Macros section for details on each macro listed MODEM CMD MAN LEN Maximum length of the modem initialization command string PHONE_NUM_MAX
435. ons We sincerely hope that the reliability and flexibility afforded by this fully programmable controller enable you and your company to solve your automation projects in a cost effective and efficient manner Technical Support Support related to any part of this documentation can be directed to one of the following support centers Technical Support The Americas Available Monday to Friday 8 00am 6 30pm Eastern Standard Time Toll free within North America 1 888 226 6876 Direct Worldwide 1 613 591 1943 Email TechnicalSupport controlmicrosystems com Technical Support Europe Africa Middle East Available Monday to Friday 8 30am 5 30pm Central European Standard Time Direct Worldwide 31 71 597 1655 Email euro support controlmicrosystems com Technical Support Asia Pacific Available Monday to Friday 8 30am 5 30pm Australian Eastern Standard Time Toll free within North America 1 888 226 6876 Direct Worldwide 61 3 9249 9580 Email au support controlmicrosystems com Document Version 1 70 5 23 2012 19 Getting Started Getting Started This section of the C Tools User Manual describes the installation of C Tools and includes a Program Development Tutorial The Program Development Tutorial leads the user through the steps involved in writing compiling linking and loading a C application program SCADAPack C Tools Installation The SCADAPack C Tools install a gnu C compiler and controlle
436. op e g IO processin 9 Document Version 1 70 5 23 2012 39 C Program Development Recomme nded Use Document Version 1 70 5 23 2012 40 C Program Development mainStack applicationGroup The variable mainStack selects the stack space for the task main At least 5 stack blocks are needed when the main task calls the function fprintf The heap size is not configurable The C application has access to the entire system heap The variable applicationGroup is assigned with a unique value by the operating system to identify each user defined C application The variable applicationGroup should be used for the parameter type when calling the function create_task When an application is stopped or deleted tasks created by the same application group will be stopped pNvMemory and nvMemorySize The variables pNvMemory and nvMemorySize are declared next and changes are not required The structure NV_MEMORY is defined in the file nvMemory h and is discussed in the next section applicationType and applicationTypeLimit appstart The variables applicationType and applicationTypeLimit may be used to limit the number of instances of a C Application that may be executed on the same SCADAPack 350 and 4203 For example to load another instance of a C Application simply rename the application file before loading it to the controller By default there is no instance limit set To limit the number of instan
437. or while TRUE Allow other tasks to execute release processor Handler Function Example ee ph E SE EE EE handler c This is a sample program for the InstallModbusHandler function This sample program uses function code 71 to demonstrate a simple method for using the installModbusHandler function When the handler is installed Modbus ASCII messages using function code 71 that are received on com2 of the controller will be processed as shown in the program text To turn on digital output 00001 From a terminal send the ASCII command 014701B7 Where DI is the station address 47 is the function code in hex 01 is the command for the function code B7 is the message checksum To turn off digital output 00001 From a terminal send the ASCII command 014700B8 Where DI is the station address 47 is the function code in hex 00 is the command for the function code B8 is the message checksum include lt ctools h gt static UINT16 myModbusHandler UCHAR message UINT16 messageLength UCHAR response UINT16 responseLength Document Version 1 70 5 23 2012 648 Example Programs UCHAR pMessage UCHAR pResponse pMessage message if pMessage 71 Action for command data pMessagett if pMessage 0 request _ resource IO SYSTEM setdbase MODBUS 1 0 release resource IO SYSTEM pResponse response pResponse
438. ore that 0 1 seconds will cause background operations to not execute properly The IO_SYSTEM resource needs to be obtained before using any of the following functions readRegAssignment read the register assignment readRegAssignmentEx read the register assignment alarmin configure the alarm in parameters clearAllForcing clear all forcing flags clear_errors clear serial port error counters clear_protocol_status clear protocol status clearRegAssignment clear register assignment clearSFTranslationTable clear the Store and Forward translation table databaseRead read a value from the database databaseWrite write a value to the database dbase read a value from the database getclock read the system clock getClockAlarm read the clock alarm settings getClockTime read the system clock time ioClear clear the I O Document Version 1 70 5 23 2012 48 Real Time Operating System ioDatabaseReset ledSetDefault master_message mTcpSetinterfaceEx mTcpSetProtocol reset the database set the default LED state send a master message poll configure the Modbus TCP interface configure the Modbus TCP protocol mTcpMasterMessage send a Modbus TCP master message overrideDbase readintVariable readMsgVariable readRealVariable readTimerVariable resetClockAlarm setclock setClockAlarm setdbase setForceFlag set_port set_protocol setProtocolSettings force the database value read an integer variable read a message variable read a real v
439. ority Value for Value for SCADAPack SCADAPack 350 and 4203 P25 Higher Priority Priority Lower Priory w i Document Version 1 70 5 23 2012 683 Porting Existing C Tools Applications Exit Handler Function The argument used for application type in existing calls to create_task needs to be replaced with the global variable applicationGroup The operating system assigns a unique value to applicationGroup when it is defined in appStart cpp Please see the documentation for create_task in the Function Specifications section for more details The argument used to specify the exit handler function in existing calls to installExitHandler must be cast to the type FUNCPTR Please see the documentation for installExitHandler in the Function Specifications section for more details Program Status Functions The functions getProgramStatus and setProgramStatus have changed syntax To support multiple C applications these functions now have an argument to specify the application The new syntax for these functions is documented in the Function Specifications section Freeing Dynamic Memory When a C Application is ended e g by using the STOP button from the C C Program Loader memory allocated by using the malloc function is not freed automatically An exit handler must be installed to free allocated memory Please see the documentation for installExitHandler in the Function Specifications section for more details
440. otSettings type MODBUS_ ASCII set protocol com2 amp protSettings Configure Register Assignment clearRegAssignment addRegAssignment DIN generic8 0 10017 0 0 0 addRegAssignment DIAG protocolStatus 1 31000 0 0 0 Install Exit Handler getTaskInfo 0 amp taskStatus installExitHandler taskStatus taskID FUNCPTR myshutdown Install Modbus Handler request _ resource IO SYSTEM installModbusHandler myModbusHandler Document Version 1 70 5 23 2012 650 Example Programs release resource IO SYSTEM while TRUE release processor Install Serial Port Handler Example SCADAPack 350 C Application Main Program Copyright 2006 Control Microsystems Inc Fy include lt ctools h gt include nvMemory h define CHAR RECEIVED 11 xy void signal serial INT32 port INT32 character Si extern C add prototypes here This program displays all characters received om coml using an installed handler to signal the reception of a character int main void INT32 port 1 INT32 character struct prot_settings protocolSettings disable Protocol get_protocol com2 amp protocolSettings protocolSettings type NO PROTOCOL Document Version 1 70 5 23 2012 651 Example Programs request _ resource IO SYSTEM set protocol com2 amp protocolSettings release resourc
441. outingTableEx type describes an entry in the DNP Routing Table The DNP Routing Table is a list of routes which are maintained in ascending order of DNP addresses typedef struct RoutingTableEx type UINT16 address station address UINT16 comPort com port interface UINT16 retries number of retries UINT16 timeout timeout in milliseconds IP_ADDRESS ipAddress IP address dnpRoutingTableEx address is the DNP station address of the destination station comPort specifies the communications port interface Allowed values are 1 serial port com1 2 serial port com2 3 serial port com3 Document Version 1 70 5 23 2012 608 Structures and Types envelope 103 DNP over TCP using LAN port 104 DNP over UDP using LAN port retries is the number of times the data link layer will retry the message in the event of a failure timeout is the timeout in milliseconds ipAddress is the IP address of the destination station DNP_RUNTIME_STATUS The dnpRuntimeStatus type describes a structure for holding status information about DNP event log buffers DNP Runtime Status typedef struct dnp runtime status ay Wi KE events events UINT16 eventCountBI number of binary input events UINT16 eventCountCI16 number of 16 bit counter events UINT16 eventCountC132 number of 32 bit counter events UINT16 eventCountAI16 number of 16 bit analog input UINT1
442. p350 hello e Type make and press Enter Make will compile the two cpp files then link them into a single output file named myApp out If errors occur they will be displayed on the command line Document Version 1 70 5 23 2012 27 Getting Started Loading and Executing the C Application Using Telepace The Telepace C C Program Loader transfers executable files from a PC to the controller and controls execution of programs in the controller Controller Initialization Connect to Controller The controller should be initialized when beginning a new programming project or when it is desired to start from default conditions It is not necessary to initialize the controller before every program load To completely initialize the controller perform a Cold Boot When the controller starts in the cold boot mode e The default serial communication parameters are used e The Telepace Ladder Logic application program is erased e The C C program is erased e The controller is unlocked To perform a Cold Boot use the following procedure e Remove power from the controller e Hold down the LED POWER button e Apply power to the controller e Continue holding the LED POWER button for 25 seconds until the STAT LED begins to flash on and off continuously e Release the LED POWER button If the LED POWER button is released before the STAT LED begins to flash the controller will start in service mode not the cold boot mode
443. ple table 10 void main void variablel arrayl 0 table 0 index file2 cpp include ctools h Non volatile variables required by file2 cpp static UINT32 variable2 void functionl void variable2 This second version of these files shows how to declare these variables as non volatile To do this the declarations have been moved to the header file nvMemory h and are shown in bold below A template for nvMemory h is provided in the sample C Application This header file needs to be included in each file that accesses the non volatile variables The only undesirable effect of making certain variables non volatile is that these variables need to become global variables To access the non volatile variables in code use the pointer pNvMemory to the NV_MEMORY structure as shown below main cpp include ctools h include nvMemory h void main void pNvMemory gt variablel pNvMemory gt arrayl 0 pNvMemory gt table 0 index file2 cpp include ctools h include nvMemory h void functionl void Document Version 1 70 5 23 2012 42 C Program Development pNvMemory gt variable2 nvMemory h nvMemory h Global definitions for user variables that need to be non volatile Copyright 2006 Control Microsystems Inc F Prevent multiple inclusions ifndef NVMEMORY H define NVMEMORY H ifdef cplusplus extern
444. plicitely at the end of the round robin queue Notes Calling release_processor in all idle loops is not necessary anymore In contrary it reduces the fair share of CPU time because the CPU is given up before the end of the time slice The function release_processor still makes sense if the calling task does not have anything to do for the moment Release all resources in use by a task before releasing the processor Refer to the Real Time Operating System section for more information on tasks and task scheduling See Also request_resource Document Version 1 70 5 23 2012 483 Function Specifications release_resource Release Control of a Resource Syntax include lt ctools h gt void release resource UINT32 resource Description The release_resource function releases control of the resource specified by resource If other tasks are waiting for the resource the highest priority of these tasks is given the resource and is made ready to execute If no tasks are waiting the resource is made available and the current task continues to run Notes Refer to the Real Time Operating System section for more information on resources See Also request_resource Example See the Example for the request_resource function Document Version 1 70 5 23 2012 484 Function Specifications removeModbusHandler Removes a User Defined Modbus Handler Syntax include lt ctools h gt BOOLEAN removeMo
445. porting class for the object It may be set to CLASS _1 CLASS_2 or CLASS_3 e threshold is the amount by which the counter input value needs to change before an event will be reported for the point Document Version 1 70 5 23 2012 605 Structures and Types dnpMasterPoll The dnpMasterPoll type describes an entry in the DNP Master Poll Table typedef struct dnpMasterPoll type UINT16 dnpRemoteStationAddress UINT16 classOPollRate UINT16 class1PollRate UINT16 class2PollRate UINT16 class3PollRate UINT16 timeSyncRate UINT16 unsolicitedResponseFlags dnpMasterPoll e dnpRemoteStationAddress is the remote DNP station address e classOPollRate is the Class 0 Polling rate e class1PollRate is the Class 1 Polling rate e class2PollRate is the Class 2 Polling rate e class3PollRate is the Class 3 Polling rate e timeSyncRate is the time synchronization rate e _unsolicitedResponseFlags are the DNP Master Unsolicited Response enable flags DNP Master Poll table Extended Entry The dnpMasterPollEx type describes an extended entry in the DNP Master Poll Table typedef struct dnpMasterPollTableEx type INT16 INT16 INT16 INT16 INT16 INT16 UINT16 UINT16 UINT16 UINT16 UINT16 UINT16 INT16 INT16 INT16 UINT16 dnpRemoteStationAddress classOPollRate class1PollRate class2PollRate class3PollRate timeSyncRate unsolicitedResponseFlags class0OPollOffset classl1PollOffset
446. protocolSettingsEx t UCHAR type UINT16 station UCHAR priority UINT16 SFMessaging ADDRESS MODE mode BOOLEAN enronEnabled UINT16 enronStation PROTOCOL SETTINGS EX type is the protocol type It may be one of NO_PROTOCOL MODBUS_RTU or MODBUS_ ASCII AR FULL BCC AB_FULL_CRC AB_HALF_BCC DNP or AB_HALF_CRC macros To set the remaining settings use the function mTcpSetInterfaceEx Document Version 1 70 5 23 2012 624 Structures and Types prot_settings prot_status station is the station address of the controller Each serial port may have a different address The valid values are determined by the communication protocol This field is not used if the protocol type is NO PROTOCOL priority is the task priority of the protocol task This field is not used if the protocol type is NO PROTOCOL SFMessaging is the enable Store and Forward messaging control flag ADDRESS_MODE is the addressing mode AM standard or AM_extended enronEnabled determines if the Enron Modbus station is enabled It may be TRUE or FALSE enronStation is the station address for the Enron Modbus protocol It is used if enronEnabled is set to TRUE Valid values are 1 to 255 for standard addressing and 1 to 65534 for extended addressing The Protocol Settings structure defines settings for a communication protocol This structure differs from the extended settings in that it allows fewer settings to be specified
447. ption The dnpGetAO32Config function reads the configuration of a DNP 32 bit analog output point The function has two parameters the point number and a pointer to an analog output point configuration structure The function returns TRUE if the configuration was read It returns FALSE if the point number is not valid if the pointer is NULL or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpSaveAO32Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 173 Function Specifications dnpGetAOSFConfig Get Short Floating Point Analog Output Configuration Syntax include lt ctools h gt BOOLEAN dnpGetAOSFConfig UINT16 point dnpAnalogOutput pAnalogOutput Description The dnpGetAOSF Config function reads the configuration of a DNP short floating point analog output point The function has two parameters the point number and a pointer to a configuration structure The function returns TRUE if the configuration was successfully read or FALSE otherwise if the point number is not valid or pointer is NULL or if the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 174 Function Specifications dnpGetBiConfi
448. ption This function reads an entry from the routing table pRoute is a pointer to a table entry it is written by this function The return value is TRUE if pRoute was successfully written or FALSE otherwise Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpWriteRouting TableEntry Document Version 1 70 5 23 2012 201 Function Specifications dnpReadRoutingTableEntryEx Read Routing Table entry Syntax include lt ctools h gt BOOLEAN dnpReadRoutingTableEntryEx UINT16 index dnpRoutingTableEx entry 1 Description This function reads an extended entry from the DNP routing table index specifies the index of the entry in the table Valid values are 0 to the size of the table minus 1 pEntry is a pointer to an extended DNP routing table entry structure The entry is written to this structure The function returns TRUE if the entry was added and FALSE if the index is not valid Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Use the dnpCreateRoutingTable function to create the routing table and specify its size See Also dnpCreateRoutingTable dnpWriteRoutingTableEntryEx Document Version 1 70 5 23 2012 202 Function Specifications dnpReadRoutingTableSize Read Routing Table size Syntax include lt ctools h gt UINT16 dnpReadRoutingTableSize void Des
449. quire that an address be assigned to a socket However servers usually require that the socket be bound to a well known address The port number may be any port number between 0 and 65535 Multiple sockets cannot bind to the same port with different IP addresses as might be allowed in UNIX Parameters socketDescriptor The socket descriptor to assign an IP address and port number to addressPtr The pointer to the structure containing the address to assign addressLength The length of the address structure Returns 0 Success 1 An error occurred bind can fail for any of the following reasons EADDRINUSE The specified address is already in use EBADF socketDescriptor is not a valid descriptor EINVAL One of the passed parameters is invalid or socket is already bound EINPROGRESS bind is already running Document Version 1 70 5 23 2012 106 Function Specifications check_error Get Error Code for Current Task Syntax include lt ctools h gt UINT32 check_error void Description The check_error function returns the error code for the current task The error code is set by various I O routines when errors occur A separate error code is maintained for each task Notes Some routines in the standard C library return errors in the global variable errno This variable is not unique to a task and may be modified by another task before it can be read Document Version 1 70 5 23 2012 107 Functio
450. r Generally stream sockets may successfully connect only once datagram sockets may use connect multiple times to change their association Datagram sockets may dissolve the association by connecting to a null address Aa non blocking connect is allowed In this case if the connection has not been established the connect call will fail with a EINPROGRESS error code Additional calls to connect will fail with EALREADY error code as long as the connection has not completed When the connection has completed additional calls to connect will return with no error to indicate that the connection is now established Parameters socketDescriptor The socket descriptor to assign a name port number to addressPtr The pointer to the structure containing the address to connect to for TCP For UDP it is the default address to send to and the only address to receive from addressLength The length of the address structure Returns 0 Success 1 An error occurred connect can fail for any of the following reasons EADDRINUSE The socket address is already in use The calling program should close the socket descriptor and issue Document Version 1 70 5 23 2012 125 Function Specifications EADDRNOTAVAIL EAFNOSUPPORT EINPROGRESS EALREADY EBADF ECONNREFUSED EPERM EINVAL EISCONN EHOSTUNREACH EPROTOTYPE ETIMEDOUT another socket call to obtain a new descriptor before attempting another connect call The specified
451. r These streams are routed to the com1 serial port by default logical specifies the stream to redirect hardware specifies the hardware device which will output the data It may be one of 0 com1 1 com2 or 2 coms Notes This function has a global effect so all tasks need to agree on the routing Output streams need to be redirected to a device that supports output Input streams need to be redirected to a device that supports input The use of this function is strongly discouraged since tasks beyond the control of the C Application may make use of the streams stdout stdin and stderr This may result in data being unexpectedly added or removed from these streams Example This program segment will redirect all input output and errors to the com2 serial port include lt ctools h gt route STD_ERR 1 send errors to com2 route STD_OUT 1 send output to com2 route STD_IN 1 get input from com2 rresvport Syntax include lt ctools h gt int rresvport int portToReservePtr Document Version 1 70 5 23 2012 490 Function Specifications Description rresvport is used to create a TCP socket and bind a reserved port to the socket starting with the port to reserve given by the user The portToReservePir parameter is a value result parameter The integer pointed to by portToReservePtr is the first port number that the function attempts to bind to The caller typically initializes the st
452. r function and it s parameters If the pointer is NULL no handler is installed The installed handler is called with a Modbus address Linear addresses are converted to Modbus addresses before calling the handler Use the installDbaseHandler function to install a read access handler for the same addresses handled by the setdbase handler The C Tools functions dbase and setdbase are used by all protocols to access Modbus or Linear registers Notes Call this function with the NULL pointer to remove the setdbase handler This needs to be done when the application program is ended with an exit handler Use the installExitHandler function to install the exit handler If the Setdbase handler is not removed within an exit handler it will remain installed and continue to operate until the controller power is cycled Erasing the C Program from the Initialize dialog will not remove the Setdbase handler If the handler is located in a RAM based application and left installed while a different C application is downloaded the original handler will be corrupted and the system will likely crash Document Version 1 70 5 23 2012 306 Function Specifications See Also setdbase installDbaseHandler Example See Example for Setdbase Handler Function Document Version 1 70 5 23 2012 307 Function Specifications installExitHandler Install Handler Called when Task Ends Syntax include lt ctools h gt BOOLEAN installEx
453. r header and support files Framework applications for Telepace and IEC 61131 1 firmware are provided Any standard Editor may be used to create C applications Telepace IEC 61131 1 or Realflo applications are used to load applications into the SCADAPack controllers These installations are described in the following sections Installing SCADAPack C Tools To install the SCADAPack C Tools e Insert the SCADAPack C Tools CD into your CD drive and follow the on screen instructions The C Tools is a command line compiler Two system properties need to be set for the compiler to work To modify system properties e From the Start menu or the Desktop right click on My Computer e Select the Advanced tab e Click Environment Variables e Inthe System Variables section at the bottom add a variable as follows o Click New o In Variable Name type CTOOLS_ PATH o In Variable Value type C program files Control Microsystems CTools if you installed to a different path then substitute the correct path here o Click OK e Inthe System Variables section at the bottom modify the PATH variable as follows o Locate the PATH variable Document Version 1 70 5 23 2012 20 Getting Started o Click Edit o In Variable Value add the following at the start of the text including the semi colon at the end of the string C Program Files Control Microsystems CTools Arm7 host x86 win32 bin if you installed t
454. r no modem is connected to the controller serial port DE_InitError returns modem initialization failed the modem may be turned off DE_NoDialTone returns modem did not detect a dial tone or the S6 setting in the modem is too short DE_BusyLine returns the phone number called was busy DE_CallAborted returns a call in progress was aborted by the user DE_FailedToConnect returns the modem could not connect to the remote site DE_CarrierLost returns the connection to the remote site was lost modem reported NO CARRIER Carrier is lost for a time exceeding the S10 setting in the modem Phone lines with call waiting are very susceptible to this condition DE_NotInControl returns the serial port is in use by another modem function or has answered an incoming call DE_CallCut returns an incoming call was disconnected while attempting to dial out The DialState enumerated type defines the state of the modemDial operation and may have one of the following values enum DialState F DS_ Inactive DS Calling DS_ Connected DS Terminating DS_Inactive returns the serial port is not in use by a modem Document Version 1 70 5 23 2012 588 Structures and Types DS_Calling returns the controller is making a connection to a remote controller DS Connected returns the controller is connected to a remote controller DS_Terminating returns the controller is ending a connection to a remote controller dlogConfiguration T
455. r to TFC_NONE causes the port to use the CTS signal which is the default setting e type specifies the serial port type It is one of RS232 RS232_MODEM or RS485_ 2WIRE macros e timeout is not supported This setting is ignored and is fixed at 600ms for backwards compatibility PID DATA The PID_DATA structure contains data for a PID control calculation The structure contains input values calculation results and internal data that needs to be maintained from one execution to the next typedef struct pidData_type Document Version 1 70 5 23 2012 622 Structures and Types input values float pv float sp float gain float reset float rate float deadband float fullScale float zeroScale float manualOutput UINT32 period BOOLEAN autoMode calculation results float output BOOLEAN outOfDeadband historic data values float pvN1 float pvN2 float errorNl UINT32 lastTime PID DATA e pv isthe process value e spis the set point e gain is the gain e reset is the reset time in seconds e rate is the rate time in seconds e deadband is the deadband e fullScale is the full scale output limit e zeroScale is the zero scale output limit e manualOutput is the manual output value e period is the execution period in milliseconds e autoMode is the auto mode flag TRUE auto FALSE manual e output is the last output value e outOfDeadband is the error is outside th
456. r will add the station address checksum and message framing to the response The handler function returns the following values NORMAL Indicates protocol handler should send a normal response message Data are returned using pResponse and pResponseLength ILLEGAL_FUNCTION Indicates protocol handler should send an Illegal Function exception response message This response should be used when the function code in the command is not recognized ILLEGAL_DATA_ADDRESS Indicates protocol handler should send an Illegal Data Address exception response message This response should be used when the data address in the command is not recognized ILLEGAL_DATA_VALUE Indicates protocol handler should send an Illegal Data Value exception response message This response should be used when invalid data is found in the command If the function returns NORMAL then the protocol driver sends the response message in the buffer pointed to by pResponse If the function returns an exception response protocol driver returns the exception response to the caller The buffer pointed to by pResponse is not used Example This program installs a simple handler function include lt ctools h gt UINT16 commandHandler INT16 length HAR pCommand NT16 responseSize NT16 pResponseLength Cc I I CHAR pResponse Si E K Le C Q UCHAR command UINT16 result if a command byte was received if length gt
457. racter was received if error 0 interrupt_signal_event CHARACTER RECEIVED Prevent compiler unused variables warning generates no code character EE echoData The echoData function is a task that waits for a character to be received on coml and echoes the character back It installs a character handler for coml to generate events on the reception of characters void echoData void struct prot_settings protocolSettings struct pconfig portSettings int character Disable communication protocol get_protocol coml amp protocolSettings protocolSettings type NO PROTOCOL set protocol coml amp protocolSettings Set serial communication parameters portSettings baud BAUD9600 portSettings duplex FULL portSettings parity NONE portSettings data_bits DATA8 portSettings stop bits STOP1 portSettings flow rx RFC MODBUS_RTU portSettings flow tx TFC_NONE portSettings type RS232 portSettings timeout 600 set _port coml amp portSettings Document Version 1 70 5 23 2012 53 Real Time Operating System Install handler for received character install handler coml signalCharacter while TRUE Wait for a character to be received wait event CHARACTER RECEIVED 8 Echo the character back character fgetc coml if character EOF
458. rd Modbus protocol The installed handler function s is called only if the message is addressed to the station and the message checksum is correct The function has one parameter a pointer to a function to handle the messages See the section Handler Function for a full Description of the function and it s parameters The function has no return value Notes This function is used to create a user defined extension to the standard Modbus protocol Call the removeModbusHandler function to remove a previously installed handler This needs to be done when the application program is ended with an exit handler Use the installExitHandler function to install the exit handler If the Modbus handler is not removed within an exit handler it will remain installed and continue to operate until the controller power is cycled Changing the protocol type or Erasing the C Program from IEC 61131 1 Initialize dialog will not remove the Modbus handler If the handler is located in a RAM based application and left enabled while a different C application is downloaded the original handler will be corrupted and the system will likely not work See Also removeModbusHandler Handler Function installExitHandler Document Version 1 70 5 23 2012 309 Function Specifications installRTCHandler Install User Defined Real Time Clock Handler Syntax include lt ctools h gt void installRTCHandler void rtchandler TIME now TIME newTime
459. requests permission to send broadcast datagrams on the socket With protocols that support out of band data the SO_OOBINLINE option requests that out of band data be placed in the normal data input queue as received it will then be accessible with recv call without the MSG_OOB flag SO_SNDBUF and SO_RCVBUF are options that adjust the normal buffer sizes allocated for output and input buffers respectively The buffer size may be increased for high volume connections or may be decreased to limit the possible backlog of incoming data The Internet protocols place an absolute limit of 64 Kbytes on these values for UDP and TCP sockets in the default mode of operation The following options are recognized at the IP level IP_PROTOIP protocolLevel options IP_TOS IP type of service Default 0 IP_TTL IP Time To Live in seconds Default 64 IP_MULTICAST_TTL Change the default IP TTL for outgoing multicast datagrams IP_MULTICAST_IF Specify a configured IP address that will uniquely identify the outgoing interface for multicast datagrams sent on this socket A zero IP address parameter indicates that we want to reset a previously set outgoing interface for multicast packets sent on that socket The following options are recognized at the TCP level IP_PROTOTCP protocolLevel options Document Version 1 70 5 23 2012 538 Function Specifications TCP_MAXSEG TCP_NODELAY Parameters socketDescriptor protocolLevel optionName option
460. rnetGetMACAddress Returns Ethernet controller MAC address ipGetConnectionSummary Returns the number of connections master slave or unused ipGetInterfaceType Returns the interface that is configured to the specified local IP address Modbus IP Protocol Modbus IP is an extension of serial Modbus which defines how Modbus messages are encoded within and transported over TCP IP based networks Modbus IP protocols are just as simple to implement and flexible to apply as serial Modbus Complete information for Modbus IP and serial Modbus may be found on line at www modbus org Document Version 1 70 5 23 2012 79 Overview of Programming Functions These functions are supported on the SCADAPack 350 controllers Modbus IP Functions The ctools h file defines the following Modbus IP related functions Refer to the Function Specification section for details on each function listed mTcpSetConfig mTcpGetConfig mTcpSetinterface mTcpGetinterface mTcpSetinterfaceEx mTcpGetinterfaceEx Set Modbus IP protocol settings Get Modbus IP protocol settings Set interface settings used by the Modbus IP protocols Get interface settings used by the Modbus IP protocols Set interface settings used by the Modbus IP protocols including Enron Modbus settings Get interface settings used by the Modbus IP protocols including Enron Modbus settings mTcpSetProtocol Get interface settings used by the Modbus IP protocols mTcpGetProtoc
461. rograms C programs and communication protocols Telepace and IEC 61131 1 firmware support different ranges of Modbus Database registers The following table shows the register ranges for these firmware types Telepace IEC 61131 1 Data Type Modbus Modbus Addresses Addresses 00001 to 00001 to Coil Register 04096 09999 1 returned if variable is non zero 0 returned if variable is 0 10001 to 10001 to Status Register 14096 19999 1 returned if variable is non zero 0 returned if variable is 0 30001 to 30001 to Input Register 39999 39999 word 16 bits 40001 to 40001 to Holding Register 49999 49999 word 16 bits Modbus I O Database Register Types The I O database is divided into four types of I O registers Each of these types is initially configured as general purpose registers by the controller Coil Registers Coil or digital output database registers may be assigned to 5000 digital output modules or SCADAPack I O modules through the Register Assignment Coil registers may also be assigned to controller on board digital outputs and to system configuration modules Status Registers Status or digital input database registers may be assigned to 5000 digital input modules or SCADAPack I O modules through the Register Assignment Status registers may also be assigned to controller on board digital inputs and to system diagnostic modules Input Registers Input or analog input database registers may be assigned t
462. roller Status Code Syntax include lt ctools h gt UINT16 setStatusBit UINT16 bitMask Description The setStatusBit function sets the bits indicated by bitMask in the controller status code When the status code is non zero the STAT LED blinks a binary sequence corresponding to the code If code is zero the STAT LED turns off The function returns the value of the status register Notes The status output opens if code is non zero Refer to the System Hardware Manual for more information The binary sequence consists of short and long flashes of the error LED A short flash of 1 10th of a second indicates a binary zero A binary one is indicated by a longer flash of approximately 1 2 of a second The least significant digit is output first As few bits as possible are displayed all leading zeros are ignored There is a two second delay between repetitions The STAT LED is located on the top left hand corner of the controller board Bits 0 1 and 2 of the status code are used by the controller firmware Attempting to control these bits will result in indeterminate operation Bit 0 Module Failure Bit 1 Register Assignment Checksum Failure Bit 2 IO Queue Full Bit 3 Reduced Power Mode SCADAPack 4203 only See Also getStatusBit Document Version 1 70 5 23 2012 541 Function Specifications setStatusMode Set Source for Status LED Syntax include lt ctools h gt void setStatusMode UINT16 mode
463. roller settings Default gateway is the com3 PPP connection e IPConfig_GatewayOnCom 4 configures IP settings from controller settings Default gateway is the com4 PPP connection IP_PROTOCOL_SETTINGS The Modbus IP Protocol Settings structure defines settings for one of the Modbus IP communication protocols typedef struct st_ipProtocolSettings UINT16 UINT32 UINT32 BOOLEAN portNumber masterIdleTimeout serverlIdleTimeout serverEnabled Document Version 1 70 5 23 2012 614 Structures and Types IP PROTOCOL SETTINGS e portNumber is the TCP or UDP port number for the Modbus IP of DNP IP protocol Valid port numbers are 1 to 65535 e masterldleTimeout is the length of time in seconds that a master connection will wait for the user to send the next command before ending the connection This allows the slave device to free unused connections while the master application may retain the connection allocation Set to 0 to disable timeout and let the application close the connection Valid values are any 32 bit integer Default value is 10 seconds TCP protocols only Not used by UDP protocols e serverldleTimeout is the length of time in seconds that a server connection will wait for a message before ending the connection Set to 0 to disable timeout and let remote client close connection Valid values are any 32 bit integer Default value is 250 seconds TCP protocols only Not used by UDP pro
464. ror code is zero the status LED turns off The FORCE LED yellow indicates locked I O variables Use this function with care in application programs There are two library functions related to the LED indicators Refer to the Function Specification section for details on each function listed runLed Controls the RUN LED status forceLed Sets state of the force LED LED Power Control Functions The controller board can disable the LEDs on the controller board and I O modules to conserve power This is particularly useful in solar powered or unattended installations Refer to the hardware manual for further information on LED power control There are four library functions related to LED power control Refer to the Function Specification section for details on each function listed ledGetDefault Get default LED power state ledPower Set LED power state ledPowerSwitch Read LED power switch ledSetDefault Set default LED power state LED Power Control Structure The ctools h file defines the structure LED Power Control Structure for LED power control information Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Document Version 1 70 5 23 2012 67 Overview of Programming Functions Software Timer Functions The controller provides 32 powerful software timers which greatly simplify the task of programming time related functions Uses include e generation of time
465. rrectly released The unregisterBulkDevOperation should be called after the operation is completed Parameters extDriveName_ The mounted bulk device drive name typically bd0 Returns TRUE Registration was successful FALSE The drive name was invalid Notes The registerBulkDevOperation and unregisterBulkDevOperation should only be used with a dynamically mounted bulk device such as a USB memory stick The unregisterBulkDevOperation needs to be called with the same device drive name as the registerBulkDevOperation See Also unregisterBulkDevOperation Example include lt ctools h gt int main void if registerBulkDevOperation bd0 FALSE printf registerBulkDevOperation bd0 failed r n Copy d0 logs log1i bd0 logs log1 if unregisterBulkDevOperation bd0 FALSE Document Version 1 70 5 23 2012 481 Function Specifications printf unregisterBulkDevOperation bd0 failed r n Document Version 1 70 5 23 2012 482 Function Specifications release_processor Release Processor to other Tasks Syntax include lt ctools h gt void release processor void Description The release_processor function releases control of the CPU to other tasks Other tasks of the same priority will run Tasks of the same priority run in a round robin fashion using a time slicing mechanism release_processor puts the task ex
466. rrupt_signal_event RTOS call can be used to signal events See Also setClockAlarm Example See the Install Clock Handler Example in the Examples section Document Version 1 70 5 23 2012 304 Function Specifications installDbaseHandler Install User Defined Dbase Handler IEC 61131 1 firmware only Syntax include lt ctools h gt void installDbaseHandler BOOLEAN handler UINT16 address INT16 value Description The installDbaseHandler function allows an extension to be defined for the dbase function If a handler is installed it is called by the dbase function when one of the following conditions apply e There is no IEC 61131 1 application downloaded or e There is no IEC 61131 1 variable assigned to the specified Modbus address The function installDbaseHandler has one parameter a pointer to a function to handle the dbase extensions See the section Dbase Handler Function for a full Description of the handler function and it s parameters If the pointer is NULL no handler is installed The installed handler is always called with a Modbus address Linear addresses are converted to Modbus addresses before calling the handler Use the installSetdbaseHandler function to install a write access handler for the same addresses handled by the dbase handler The C Tools functions dbase and setdbase are used by all protocols to access Modbus or Linear registers Notes Call this funct
467. rsion 1 70 5 23 2012 236 Function Specifications ethernetGetIP Get Ethernet Controller TCP IP Settings Syntax include lt ctools h gt void ethernetGetIP IP SETTINGS pIPSettings Description The ethernetGetIP function copies the Ethernet controller TCP IP settings into the structure pointed to by p PSettings The structure IP_SETTINGS is described in the Structures and Types section See Also ethernetSetIP Document Version 1 70 5 23 2012 237 Function Specifications ethernetGetMACAddress Get Ethernet Controller MAC address Syntax include lt ctools h gt void ethernetGetMACAddress CHAR pMAC Description The ethernetGetMACAddress function copies the Ethernet controller MAC address to the array pointed to by oMAC pMAC must point to an array of 6 bytes Document Version 1 70 5 23 2012 238 Function Specifications ethernetSetIP Set Ethernet Controller TCP IP Setting Syntax include lt ctools h gt BOOLEAN ethernetSetIP Ip SETTINGS x piIPSettings Description The ethernetSetIP function copies the settings pointed to by plPSettings to the Ethernet controller settings If the settings are different from the current settings the Ethernet interface is closed and re opened with the new settings When the Ethernet interface is closed all active connections through this interface are closed The structure IP_SETTINGS is described in the Structures and Types section
468. rsion 1 70 5 23 2012 591 Structures and Types dlogStatus Type userType valued dlogRecord Variables for data log configuration dlogConfiguration dLogConfig dlogRecordElement recordElement 5 define the data log records recordElement 0 type DLOG UINT16 recordElement 0 size sizeof UINT16 recordElement 0 offset offsetof dlogRecord valuel recordElement 1 type DLOG INT32 recordElement 1 size sizeof INT32 recordElement 1 offset offsetof dlogRecord value2 recordElement 2 type DLOG DOUBLE recordElement 2 size sizeof double recordElement 2 offset offsetof dlogRecord value3 recordElement 3 type DLOG FLOAT recordElement 3 size sizeof float recordElement 3 offset offsetof dlogRecord value4 recordElement 4 type DLOG FIRST USER TYPE recordElement 4 size sizeof userType recordElement 4 offset offsetof dlogRecord valued insert the record list into the data log configuration dLogConfig recordList recordElement The dlogStatus enumerated type indicates the status of a data log operation The specific meaning may vary according to the function returning the status typedef enum dlogStatus_ type DLOGS SUCCESS operation was successful DLOGS FAILURE operation failed DLOGS INPROGRESS operation in progress DLOGS EXISTS
469. rt SF_PORT_OUT_OF_RANG One or both of the interfaces is not valid E SF_STATION_OUT_OF_R_ One or both of the stations is not valid ANGE SF_INDEX_OUT_OF_RAN The entry referenced by index does not exist in GE the table SF_INVALID_FORWARDIN The forwarding IP address is invalid G_IP Notes SF_ALREADY_DEFINED The translation already exists in the table The TeleBUS Protocols User Manual describes store and forward messaging mode Document Version 1 70 5 23 2012 534 Function Specifications Writing a translation with both stations set to station 65535 can clear a translation in the table Station 65535 is not a valid station The Modbus protocol type and communication parameters may differ between serial ports The store and forward messaging will translate the protocol messages Translations describe the communication path of the master command e g the slave interface which receives the command and the forwarding interface to forward the command The response to the command is automatically returned to master through the same communication path in reverse Additional entries in the Store and Forward Table are not needed to describe the response path The IO_SYSTEM resource needs to be requested before calling this function To save the Store and Forward Table with the controller settings in flash memory so that it is loaded on controller reset call flashSettingsSave as shown below save Store
470. rting the transmission The value is measured in milliseconds Valid values are 100 to 60000 in multiples of 100 milliseconds This value must be larger than the data link timeout e timeSynchronization defines how often the RTU will request a time synchronization from the master e Set this to NO_TIME_SYNC to disable time synchronization requests e Set this to STARTUP_TIME_SYNC to request time synchronization at start up only e Set this to 1 to 32767 to set the time synchronization period in seconds e Bl_number is the number of binary input points Valid values are 0 to 9999 e Bl_startAddress is the DNP address of the first Binary Input point e Bl_reportingMethod determines how binary inputs are reported either Change Of State or Log All Events e Bl_soeBufferSize is the Binary Input Change Event Buffer Size e BO_number is the number of binary output points Valid values are 0 to 9999 e BO_startAddress is the DNP address of the first Binary Output point e CID number is the number of 16 bit counter input points Valid values are 0 to 9999 e Cl16_startAddress is the DNP address of the first C116 point e CI16_reportingMethod determines how Cl16 inputs are reported either Change Of State or Log All Events e Cl16_bufferSize is the number of events in the 16 bit counter change buffer Valid values are 0 to 9999 e CI32_number is the number of 32 bit counter input points Valid values are 0 to 9999 e Cl32_startAddres
471. run NT16 D overrun NT16 rx buffer size NT16 rx buffer used NT16 tx buffer size NT16 tx buffer used NT16 io lines bearbecht Ch e eeh es oe HHHHHHHH framing is the number of received characters with framing errors parity is the number of received characters with parity errors c_overrun is the number of received character overrun errors b_overrun is the number of receive buffer overrun errors rx_buffer_size is the size of the receive buffer in characters rx_buffer_used is the number of characters in the receive buffer tx_buffer_size is the size of the transmit buffer in characters tx_buffer_used is the number of characters in the transmit buffer io_lines is a bit mapped field indicating the status of the I O lines on the serial port The values for these lines differ between serial ports see tables below ANDing can isolate the signals with the SIGNAL_CTS SIGNAL_DCD SIGNAL_OH SIGNAL_RING or SIGNAL_VOICE macros The READSTATUS enumerated type indicates the status of an UC bus message read and may have one of the following values enum ReadStatus RS_ success RS_selectFailed F typedef enum ReadStatus READSTATUS RS_success returns read was successful RS_selectFailed returns slave device could not be selected Document Version 1 70 5 23 2012 627 Structures and Types routingTable The routingTable structure type describes an entry in the DNP Routing Table This structure can
472. rverState Gets the state of the FTP server Syntax include lt ctools h gt BOOLEAN getFtpServerState UINT32 state 1 Parameters state specifies the parameter that the current operational state of the FTP server will be placed in The following values for state are defined e 0 FTP server disabled e 1 FTP server enabled anonymous login permitted e 2 FTP server enabled username and password required Description The getFtpServerState function gets the state of the FTP server TRUE is returned if the current state was placed in the parameter state FALSE is returned if the current state was not placed in the parameter state Notes This function is only relevant for Ethernet enabled controllers See Also setFtpServerState Document Version 1 70 5 23 2012 252 Function Specifications getHardwarelnformation Obtains the hardware type and version Syntax include lt ctools h gt BOOLEAN getHardwareInformation UCHAR majorVersion UCHAR minorVersion UCHAR hardwareType Description The getHardwarelnformation function will place the major version of the hardware into the memory pointed to by majorVersion the minor version of the hardware into the minorVersion and the hardware type in the memory pointed to by hardwareType Refer to the macros starting with HT_ for the various hardware types The function returns TRUE if the hardware version and type was placed in the passed vari
473. rward messaging allows the re transmission of messages received by a controller communication interface Messages may be re transmitted on any communication interface with or without station address translation A user defined translation table determines actions performed for each message Store and forward messaging may be enabled or disabled on each port It is disabled by default Serial Communication Protocol Functions There are several library functions related to TeleBUS communication protocol Refer to the Function Specification section for details on each function listed checkSFTranslationTable Check translation table for invalid entries clear_protocol_status Clears protocol message and error counters clearSFTranslationTable Clear store and forward translation table entries get_protocol Reads protocol parameters Document Version 1 70 5 23 2012 74 Overview of Programming Functions getProtocolSettings Reads extended addressing protocol parameters for a serial port get_protocol_status Reads protocol message and error counters getSFTranslation Read store and forward translation table entry installModbusHandler This function allows user defined extensions to standard Modbus protocol master_message Sends a protocol message to another device modbusExceptionStatus Sets response for the read exception status function modbusSlavelD Sets response for the read slave ID function set_protocol Sets protocol param
474. ryDialString 1 Description This function reads a primary and secondary dial string from an entry in the DNP routing table index specifies the index of an entry in the DNP routing table maxPrimaryDialStringLength specifies the maximum length of primaryDialString excluding the null terminator character The function uses this to limit the size of the returned string to keeps from overflowing the storage passed to the function primaryDialString returns the primary dial string of the target station It needs to point to an array of size maxPrimaryDialStringLength maxSecondaryDialStringLength specifies the maximum length of secondaryDialString excluding the null terminator character The function uses this to limit the size of the returned string to keep from overflowing the storage passed to the function secondaryDialString returns the secondary dial string of the target station It needs to point to an array of size maxSecondaryDialStringLength The function returns TRUE if the configuration was read and FALSE if an error occurred Notes This function needs to be used in conjunction with the dnpReadRoutingTableEntry function to read a complete entry in the DNP routing table Document Version 1 70 5 23 2012 200 Function Specifications dnpReadRoutingTableEntry Read Routing Table entry Syntax include lt ctools h gt BOOLEAN dnpReadRoutingTableEntry UINT16 index routingTable pRoute 1 Descri
475. s command to read the status of the command The number of attempts and the number of preambles sent are set with the hartSetConfiguration command A program needs to initialize the link before executing any other commands See Also hartCommand0 hartStatus hartSetConfiguration Document Version 1 70 5 23 2012 291 Function Specifications hartCommand33 Read Transmitter Variables Syntax include lt ctools h gt BOOLEAN hartCommand33 UINT16 module HART DEVICE const device UINT16 variableCode 4 HART VARIABLE variables Description This function reads selected variables from a HART device using command 33 The function has four parameters the module number of the 5904 module 0 to 3 the device to be read an array of codes and a pointer to an array of four HART_VARIABLE structures The variables array must be static modular or global variables An array of variables should be declared for each HART I O module in use A local variable or dynamically allocated variable may not be used because a late command response received after the variable is freed will write data over the freed variable space The variableCode array specifies which variables are to be read from the transmitter Consult the documentation for the transmitter for valid values The variables array is updated when the response is received by the 5904 interface as follows Variables 0 transmitter variable code and
476. s h gt BOOLEAN readTimerVariable UCHAR varName UINT32 value Description This function returns the current value in milliseconds of the specified timer variable The maximum value returned is 86399999 ms or 24 hours The specified timer may be active or stopped The variable is specified by its name expressed as a character string The name is case insensitive The IEC 61131 1 Dictionary also treats variable names as case insensitive If the variable is found TRUE is returned and the variable value is written to the unsigned long value pointed to by value If the variable is not found or if the IEC 61131 1 Symbols Status is invalid FALSE is returned and the current value is left unchanged The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables For better performance use the variable s network address and the dbase function The IO_SYSTEM system resource needs to be requested before calling this function See Also readintVari
477. s h gt main void TIME now request resource IO SYSTEM getclock amp now read the clock release resource IO SYSTEM fprintf coml 2d 2d 2d now day now month now year fprintf coml 2d 2d r n now hour now minute Document Version 1 70 5 23 2012 245 Function Specifications getClockAlarm Read the Real Time Clock Alarm Settings Syntax include lt ctools h gt ALARM SETTING getClockAlarm void Description The getClockAlarm function returns the alarm setting in the real time clock Notes The lIO_SYSTEM resource needs to be requested before calling this function See Also setClockAlarm Document Version 1 70 5 23 2012 246 Function Specifications getClockTime Read the Real Time Clock Syntax include lt ctools h gt void getClockTime INT32 pDays INT32 pHundredths Description The getClockTime function reads the real time clock and returns the value as the number of whole days since 01 01 1997 and the number of hundredths of a second since the start of the current day The function works for years from 01 01 1997 to 12 31 2099 then rolls over The function has two parameters a pointer to the variable to hold the days and a pointer to a variable to hold the hundredths of a second The function has no return value Notes The lO_SYSTEM resource needs to be requested before calling this function See Also getclock Document Ver
478. s is the DNP address of the first C132 point Document Version 1 70 5 23 2012 598 Structures and Types e CI32_reportingMethod determines how Cl32 inputs are reported either Change Of State or Log All Events e CI32_bufferSize is the number of events in the 32 bit counter change buffer Valid values are 0 to 9999 e CI32_wordOrder is the Word Order of C132 points O LSW first 1 MSW first e Al16_number is the number of 16 bit analog input points Valid values are 0 to 9999 e Al16_startAddress is the DNP address of the first Al16 point e Al16_reportingMethod determines how 16 bit analog changes are reported e Set this to FIRST_VALUE to report the value of the first change event measured e Set this to CURRENT_VALUE to report the value of the latest change event measured e Al16_bufferSize is the number of events in the 16 bit analog input change buffer Valid values are 0 to 9999 e Al32_number is the number of 32 bit analog input points Valid values are 0 to 9999 e Al32_startAddress is the DNP address of the first Al32 point e AlI32_reportingMethod determines how 32 bit analog changes are reported e Set this to FIRST_VALUE to report the value of the first change event measured e Set this to CURRENT_VALUE to report the value of the latest change event measured e Al32_bufferSize is the number of events in the 32 bit analog input change buffer Valid values are 0 to 9999 e AI32_wordOrder is the Word
479. s not connected the controller will force it to the proper value If an external device controls this line it needs to turn it ON for the controller to transmit Serial Communication Functions The ctools h file defines the following serial communication related functions Refer to the Function Specification section for details on each function listed clear_errors Clear serial port error counters clear_tx Clear serial port transmit buffer get_port Read serial port communication parameters getPortCharacteristics Read information about features supported by a serial port get_status Read serial port status and error counters install_handler Install serial port character received handler portindex Get array index for serial port portStream Get serial port corresponding to index queue_mode Set serial port transmitter mode route Redirect standard I O streams setDTR Control RS232 port DTR signal set_port Set serial port communication parameters Serial Communication Structures The ctools h file defines the structures Serial Port Configuration Serial Port Status and Serial Port Characteristics for serial port configuration and information Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Dial Up Modem Functions These library functions provide control of dial up modems They are used with external modems connected to a serial port An external modem normally c
480. s that have no module address e g CNFG_LEDPower specify 1 for moduleAddress For SCADAPack module types that have a module address fixed at 0 specify 0 for moduleAdadress startingRegister1 specifies the first register of any unused block of consecutive registers Refer to the list of modules in the Register Assignment Reference for the type and number of registers required for this block Data read from or written to the module is stored in this block of registers If the module type specified has more than one type of I O use startingRegister2 startingRegister3 and startingRegister4 as applicable Each start register specifies the first register of an unused block of consecutive registers for each type of input or output on the module Refer to the list of modules in the Register Assignment Reference for the module I O types Specify 0 for startingRegister2 startingRegister3 or startingRegister4 if not applicable parameters is an array of configuration parameters for the register assignment module Many modules do not use the parameters and a 0 needs to be specified for the parameters Use the addRegAssignment function to configure these modules Use parameters with the following modules 5414 I O Module parameter 0 defines the input type Valid values are 5414 I O Module parameter 1 defines the scan frequency for AC inputs Valid e 0 DC e 1 AC values are e 0 60Hz e 1 50Hz Document Version 1 70 5 23 2012 98
481. s the application start up task STARTUP_SYSTEM Specifies the system start up task Document Version 1 70 5 23 2012 60 Overview of Programming Functions Start Up Task Info Structure The ctools h file defines the structure TASKINFO for use with the startup_task function Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Program Status Information Functions There are two library functions related to controller program status information Refer to the Function Specification section for details on each function listed getProgramStatus Returns the application program execution status setProgramStatus Sets the application program execution status Controller Information Functions There are no functions related to controller information Refer to the Function Specification section for details getControllerlD Get the controller ID code Firmware Version Information Functions There is one function related to the controller firmware version Refer to the Function Specification section for details getVersion Returns controller firmware version information Firmware Version Information Structure The ctools h file defines the structure Version Information Structure for controller firmware version information Refer to the C Tools Structures and Types section for complete information on structures and enumeration types Configuration Data Flash Memory Functions
482. s the exact interface e g Ethernet1 to use when it searches the network for the forwardlPAddress Also when forwarding on a TCP or UDP network the forwarding destination IP address needs to be entered as the forward PAddress The forward PAddress is entered as an IP address string of the format 255 255 255 255 The forwardlPAddress is needed to know where to connect so that the command can be forwarded to its final destination Document Version 1 70 5 23 2012 532 Function Specifications Modbus IP Network as Slave Interface Note that there is no field for a slave IP address This information is irrelevant because we don t care about the IP address of the remote master We care only that the remote master connects to the specified slavelnterface and sends a command to be forwarded The protocol type is not specified for slaveinterface All messages in any Modbus IP protocol received on slavelnterface for slaveStation will be forwarded Serial Modbus Interface as Forwarding Interface The forwardlPAadress field in the SF_TRANSLATION structure should be set to zero when the forwardinterface field is a Serial Modbus interface Set forwardlPAddress to zero as follows SF_ TRANSLATION sfTranslation sfTranslation forwardIPAddress s addr 0 See Also getSFTranslation Document Version 1 70 5 23 2012 533 Function Specifications setSFTranslationEx Write Store and Forward Translation method 2 Syntax inc
483. sage function The receiving task may read this field to determine the source of the message e destination is the task ID of the task to receive the message It must be specified before calling the send_message function e type specifies the type of data in the data field It may be MSG_DATA MSG_POINTER or any other value defined by the application program This field is not required e data is the message data The field may contain a datum or pointer The application program determines the use of this field The HART_COMMAND type is a structure containing a command to be sent to a HART slave device The command field contains the HART command number The length field contains the length of the data string to be transmitted the byte count in HART documentation The data field contains the data to be sent to the slave typedef struct hartCommand_t UINT16 command UINT16 length CHAR data DATA SIZE HART COMMAND e command is the HART command number x e length is the number of characters in the data string e data DATA_SIZE is the data field for the command The HART_DEVICE type is a structure containing information about the HART device The information is read from the device using command 0 or command 11 The fields are identical to those read by the commands Refer to the command documentation for more information typedef struct hartDevice t Document Version 1 70 5 23 2012 610 Structures and Typ
484. scription This function deletes all data logs The memory for the logs is freed The data log IDs are marked as invalid The data log server will not collect further records Directory files are deleted if they are accessible This might be not the case if data log files were written to removable media The data log names are removed from the master log files Data Log files are not deleted If a log was created with a path the created directory still exists after the log is deleted Document Version 1 70 5 23 2012 153 Function Specifications dlogFlush Flush data log buffer contents to log file Syntax include lt ctools h gt dlogStatus dlogFlush UINT32 dlogID Parameters The function has these parameters e dlogID is the ID of the data log The function returns e DLOGS_SUCCESS if the data log was flushed This indicates that as much data was flushed as was possible to be flushed under current conditions e DLOGS _BADID if the data log ID is invalid e DLOGS_FAILURE if existing data cannot be flushed Description A dlogWrite call writes a data log record to a data log buffer This buffer is written regularly to the log file by the data log server The dlogFlush function explicitly flushes data log buffer contents to the log file The function flushes all or part of the buffer to the file depending on the current file conditions and buffer contents If files are full logging is suspended or external media is
485. se addrMode specifies the method of addressing the database address specifies the location in the database The table below shows the valid address modes and ranges Type Address Ranges Register Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001 to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1 Notes The function databaseRead returns TRUE if the requested database value was read FALSE is returned if the requested database entry could not be read If the specified register is currently forced databaseRead reads the forced register value into the memory pointed to by value The I O database is not modified when the controller is reset It is a permanent storage area which is maintained during power outages The lO_SYSTEM resource needs to be requested before calling this function See Also databaseWrite Document Version 1 70 5 23 2012 131 Function Specifications databaseWrite Write Value to I O Database Syntax include lt ctools h gt BOOLEAN databaseWrite UINT16 addrMode UINT16 address INT16 value Description The databaseWrite function writes a value to the database addrMode specifies the method of addressing the database address specifies the location in the database The table below shows the valid address modes and ranges Type Address Ranges Register Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001
486. se TRUE is returned The table below shows the valid address types and ranges Type Address Ranges Register Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001 to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1 Notes When a register s force flag is set the value of the I O database at that register is forced to its current value This register s value can only be modified by using the overrideDbase function or the Edit Force Register dialog While forced this value cannot be modified by the setdbase function protocols or Ladder Logic programs Force Flags are not modified when the controller is reset Force Flags are ina permanent storage area which is maintained during power outages The lIO_SYSTEM resource needs to be requested before calling this function See Also clearRegAssignment getForceFlag getOutputsInStopMode overrideDbase Document Version 1 70 5 23 2012 517 Function Specifications Example This program clears the force flag for register 40001 and sets the force flags for the 16 registers at linear address 302 i e registers 10737 to 10752 include lt ctools h gt int main void request resource IO SYSTEM setForceFlag MODBUS 40001 0 setForceFlag LINEAR 302 255 release resource IO SYSTEM Document Version 1 70 5 23 2012 518 Function Specifications setlOErrorIndication Set LO Module Error Indicati
487. se is returned if the service rejected the request if the service was unrecognized or if the username could not fit in the specified sized buffer See Also setLoginCredentials clearLoginCredentials Document Version 1 70 5 23 2012 256 Function Specifications getpeername Syntax include lt ctools h gt int getpeername int socketDescriptor Struct sockaddr fromAddressPtr int addressLengthPtr 1 Description This function returns to the caller the IP address Port number of the remote system that the socket is connected to Parameter Description socketDescriptor The socket descriptor that we wish to obtain this information about fromAdadressPir A pointer to the address structure that we wish to store this information into addressLengthPtr The length of the address structure Returns 0 Success 1 An error occurred getpeername can fail for any of the following reasons EBADF socketDescriptor is not a valid descriptor ENOTCONN The socket is not connected EINVAL One of the passed parameters is not valid Document Version 1 70 5 23 2012 257 Function Specifications getPortCharacteristics Get Serial Port Characteristics Syntax include lt ctools h gt BOOLEAN getPortCharacteristics FILE stream PORT CHARACTERISTICS oCharacteristics Description The getPortCharacteristics function gets information about features supported by the serial port pointed to b
488. shSettingsSave This function loads the controller settings in the indicated area or areas from flash memory The ctools h file defines the following functions for system initialization and for retrieving system information Some of these functions are primarily used in the appstart c routine having limited use in an application program Refer to the Function Specification section for details on each function listed ioClear Clears I O points ioDatabaseReset Resets the controller to default settings ioRefresh Refresh outputs with internal data ioReset Reset I O modules Controller UO Hardware This section of the manual provides an overview of the C Tools functions relating to controller signal input and output I O Analog Input Functions The controller supports internal analog inputs and external analog input modules Refer to the SCADAPack 350 System Hardware Manual or the SCADAPack 4203 Hardware Manual for further information on controller analog inputs and analog input modules There are several library functions related to internal analog inputs and analog input modules Refer to the Function Specification section for details on each function listed readBattery Read the controller RAM battery voltage Document Version 1 70 5 23 2012 62 Overview of Programming Functions readThermistor ioRead4Ain ioRead8Ain ioRead5505Inputs ioRead5505O0utputs ioRead5506Inputs ioRead5506Outputs ioWrite5505Outputs ioWrite
489. si fno builtin DARMEL I INCLUDE PATH DCPU ARMARCH4 DTOOL FAMILY gnu DTOOL gnu std c99 The next section lists the suffixes used in this make file Generally you will not have to modify this section Consult the gnu make documentation if you add files with new suffixes to your application SUFFIXES SUFFIXES cpp c o out The next section determines the targets that will be linked to check if symbols will be resolved in firmware determine intermediate link target s used to check if all symbols can be resolved in firmware stripTarget strip TARGET ifeq stripTarget SCADAPack350 4203 intermediate objects imLink SCADAPack350 0 imLink 4203 0 endif ifeq stripTarget SCADAPack350 intermediate objects imLink SCADAPack350 0 endif ifeq S stripTarget 4203 intermediate objects imLink 4203 0 endif The next section describes how to make the out file which is loaded into the controller Generally no changes will ever be required in this section The compiler options affecting this that should be changed are defined in the CFLAGS setting above rules for making out file APPLICATION NAME out imImage o intermediate objects Process CPP constructors and destructors Document Version 1 70 5 23 2012 25 Getting Started echo legho trn trene heee echo Building output file Eet EE Sse teases nmarm imImage o CTOOLS PATH
490. sing DB_BADSIZE Error code out of range address specified DB_BADTYPE Error code bad database addressing type specified DB_OK Error code no error occurred LINEAR Specifies linear database addressing MODBUS Specifies Modbus database addressing NUMAB Number of registers in the Allan Bradley database NUMCOIL Number of registers in the Modbus coil section NUMHOLDING Number of registers in the Modbus holding register section NUMINPUT Number of registers in the Modbus input registers section NUMLINEAR Number of registers in the linear database NUMSTATUS Number of registers in the Modbus status section START_COIL Start of the coil section in the linear database Document Version 1 70 5 23 2012 83 Overview of Programming Functions START_HOLDING Start of the holding registers section in the linear database START_INPUT Start of the input register section in the linear database START_STATUS Start of the status section in the linear database Register Assignment I O hardware that is used by the controller needs to be assigned to I O database registers in order for these I O points to be scanned continuously I O data may then be accessed through the I O database within the C program C programs may read data from or write data to the I O hardware through user assigned registers in the I O database The Register Assignment assigns UO database registers to user assigned registers using I O modules An I O Modul
491. sion 1 70 5 23 2012 247 Function Specifications getControllerlD Get Controller ID Syntax include lt ctools h gt void getControllerID CHAR pID Description This function writes the Controller ID to the string pointed to by p D The Controller ID is a unique ID for the controller set at the factory The pointer p D must point to a character string of length CONTROLLER_ID_LEN Example This program displays the Controller ID include lt ctools h gt int main void char ctlrID CONTROLLER ID LEN UINT16 index getControllerID ctlrID fprintf coml r nController ID for index 0 index lt CONTROLLER ID LEN index fputc ctlriID index coml Document Version 1 70 5 23 2012 248 Function Specifications getForceFlag Get Force Flag State for a Register Telepace firmware only Syntax include lt ctools h gt BOOLEAN getForceFlag UINT16 type UINT16 address UINT16 value Description The getForceFlag function copies the value of the force flag for the specified database register into the integer pointed to by value The valid range for address is determined by the database addressing type The force flag value is either 1 or 0 or a 16 bit mask for LINEAR digital addresses If the address or addressing type is not valid FALSE is returned and the integer pointed to by value is 0 otherwise TRUE is returned The table below shows the val
492. specified event number is signaled when the notification request is processed The function has one argument an event number Valid events are numbered 0 to 31 The function returns TRUE if the request was added The function returns FALSE if there is no room in the request queue or if the event number is invalid Document Version 1 70 5 23 2012 316 Function Specifications ioRead4203DRinputs Read 4203 DR Inputs Syntax include lt ctools h gt BOOLEAN ioRead4203DRInputs UCHAR amp dinData INT16 amp ainData UINT32 amp cinData 2 Description This function reads buffered data from the digital and analog input of the 4203 DR I O Buffered data are updated when an UO request for the module is processed dinData is a reference to a UCHAR variable Digital data for the input is written to this array One bit in the array represents each input point ainData is a reference to a INT16 variables Analog data are written to this array cinData is a reference to two UINT32 variables Counter data is written to this array The function returns FALSE if the data was read from the internal table otherwise TRUE is returned See Also ioWrite4203DROutputs Example This program displays the values of the digital input and the analog input read from the 4203 DR I O include lt ctools h gt define MY EVENT 1 int main void UCHAR dinData INT16 ainData UINT32 cinData 2
493. ssMapTable type UINT16 address CHAR objectType UINT16 remoteObjectStart UINT16 numberOfPoints UINT16 localModbusAddress dnpAddressMapTable e address is the DNP station address of the remote station e objectType is the DNP object type e remoteObjectStart is the DNP address of first object in the remote station e numberOfPoints is the number of points e localModbusAddress is the Modbus address of first object in local station The dnpAnaloginput type describes a DNP analog input point This type is used for both 16 bit and 32 bit points typedef struct dnpAnalogInput_type UINT16 modbusAddress UCHAR class UINT32 deadband dnpAnalogInput e modbusAddress is the address of the Modbus register number associated with the point e class is the reporting class for the object It may be set to CLASS_1 CLASS_2 or CLASS_3 e deadband is the amount by which the analog input value needs to change before an event will be reported for the point Document Version 1 70 5 23 2012 593 Structures and Types DnpAnaloginputShortFloat dnpAnalogOutput dnpBinarylnput dnpBinarylnputEx The dnpAnalogInputShortFloat type describes a DNP analog input point The format of this point complies with the IEEE 754 standard for floating point number representation This type is used for 32 bit points typedef struct dnpAnalogInputShortFloat_type UINT16 modbusAddress UCHAR eventClass float deadband dnpAn
494. sses ects tat casei ot na na ath a ee a aa a ee a ac ee 194 dnpbieadAddreseMappoing Tablet min 195 dnpReadAddressMappingTableSize ssnneeeeeeseseeieeeeeeeeenirnrrressrrrrnnsssene 196 dnpReadMasterPollTableEntry ssssseeeeeseeseiirersssssenirrrrrssssnnrrnnnsssssnrrnnnsssnt 197 dnpReadMasterPollTableEntryEXx AAA 198 dnpReadMasterPollTableSiZe cecccccceesecceeeeeenecesensecneseeseeseneeseeneeseseneees 199 dnpReadRoutingTableEntry_DialStrings ccccccceeeeeeeeeeeeeeeeeeeeeeeeeseeeeeeees 200 dnpbieadouting Tablet ngry 201 dnpbieadouting abletngrvEs 202 AnpReadRoutingTableSiZe ce eeceeceeeeceeeeeeeeeecceeeeeeeeeeeeeccaaeeeeeeeeseesenaeeeeeess 203 Document Version 1 70 5 23 2012 AnpSaveAl1 GC ong 204 dnpSaveAl2 Config nessie a a a a a s 205 dnpSaveAISFGONI Gsi EE 206 dnpGavehiTGtConfig EEN 207 dnpsaveAOs2Conliga EEN 208 AnpSaveAOSFCOonig AA 209 elle lge Lu e E 210 dnpsaveBlContigEx E 211 ANpSaVeBOGONlig DE 212 dnpsSaveClt16Conhig EE 213 AnpSaveCl32ConliG E 214 AnpSaveConfiguration EE 215 AnpSaveConfigurationEy AA 217 dnpGGavellnsolcitedGackott Time 218 dnpSendUnsolicitedResponse essseeeeeeeeseierrreesestiirrrstsssnnnrnnntnssttnnnnnnnssns 219 dnpGearchoutng Table 220 elle ten E E 221 dnpW rtieAcddreschMapping T abletntn 222 dnpWriteMasterApplicationLayerConfig eeeessssssssereeesssserirnrrssssserrrnnnssssne 223 dnpW rtiekasterboll Tablett 224 dnpWriteMas
495. st EMSGSIZE The socket requires that message to be sent atomically and the message was too long Document Version 1 70 5 23 2012 500 Function Specifications EWOULDBLOCK ENOTCONN ESHUTDOWN The socket is marked as non blocking and the send operation would block Socket is not connected User has issued a write shutdown TCP socket only Document Version 1 70 5 23 2012 501 Function Specifications send_message Send a Message to a Task Syntax include lt ctools h gt void send message envelope penv Description The send_message function sends a message to a task The envelope specified by penv contains the message destination type and data The envelope is placed in the destination task s message queue If the destination task is waiting for a message it is made ready to execute The current task is not blocked by the send_message function Notes Envelopes are obtained from the operating system with the allocate_envelope function See Also receive_message Example This program creates a task to display a message and sends a message to it include lt ctools h gt void showIt void envelope msg while TRUE msg receive message fprintf coml Message data Sld r n msg gt data deallocate_ envelope msg int main void envelope msg message pointer unsigned tid task ID tid create task showIt 100 application
496. st _ resource IO SYSTEM setdbase MODBUS CONNECTION REQUIRED 0 setdbase MODBUS MESSAGE COMPLETE 1 setdbase MODBUS MESSAGE FAILED 0 release resource IO SYSTEM break case DNP_MESSAGE TIMEOUT indicate message failed and clear other bits request _ resource IO_ SYSTEM setdbase MODBUS CONNECTION REQUIRED 0 setdbase MODBUS MESSAGE COMPLETE 0 setdbase MODBUS MESSAGE FAILED 1 release resource IO SYSTEM break default ignore invalid requests break FA Document Version 1 70 5 23 2012 189 Function Specifications This function is the main task of a user application It monitors a register from the ladder logic application When the register value changes the function signals DNP events The function has no parameters The function does not return int main void int lastConnectionState last state of connection register int currentConnectionState current state of connection register install DNP connection handler dnpInstallConnectionHandler sampleDNPHandler get the current connection state lastConnectionState dbase MODBUS CONNECTION STATUS loop forever while TRUE request resource IO SYSTEM get the current connection state currentConnectionState dbase MOD
497. st be set to RS232_MODEM The dial up connection handler stops outgoing calls from using the serial port when an incoming call is in progress and communication is active If communication stops for more than five minutes then outgoing call requests are allowed to end the incoming call This keeps the modem or the calling application from permanently disabling outgoing calls The function is used with programs that dial out through an external modem using the modemDial function It is not required where the modem is used for dialing into the controller only Document Version 1 70 5 23 2012 429 Function Specifications mTcpGetConfig Get Modbus TCP Protocol Settings Syntax include lt ctools h gt UINT16 mIcpGetConfig MTCP_CONEF IGURATION pSettings Description The mTcpGetConfig function copies the Modbus TCP protocol settings to the structure pointed to by pSettings The structure MTCP_CONFIGURATION is described in the Structures and Types section The settings are common to all connections using the Modbus TCP protocol If the Modbus TCP server is currently running 1 is returned If the server is not running O is returned Document Version 1 70 5 23 2012 430 Function Specifications mTcpGetinterface Get Modbus IP Interface Settings Syntax include lt ctools h gt BOOLEAN mTcpGetInterface COM INTERFACE ifType MTCP_IF SETTINGS pSettings Description The mTcpGetlnter
498. st char destination Description The copy function copies the file source to the path qualified file name destination If the copy operation failed then ERROR is returned OK is returned if the copy operation completed successfully See Also xcopy xdelete Document Version 1 70 5 23 2012 127 Function Specifications cre_reverse Calculate a CRC Checksum Syntax include lt ctools h gt UINT16 crc_reverse UCHAR start UCHAR end UINT16 poly UINT16 initial Description The crc_reverse function calculates a CRC type checksum on memory using the reverse algorithm The memory starts at the byte pointed to by start and ends with the byte pointed to by end The generator polynomial is specified by poly poly may be any value but needs to be carefully chosen to ensure good error detection The checksum accumulator is set to initial before the calculation is started Notes The reverse algorithm is named for the direction bits are shifted In the reverse algorithm bits are shifted towards the least significant bit This produces different checksums than the classical or forward algorithm using the same polynomials See Also checksum Document Version 1 70 5 23 2012 128 Function Specifications create_task Create a New Task Syntax include lt ctools h gt INT32 create_task void function UINT32 priority UINT32 type UINT32 stack Description The create_task function allocates stac
499. ster message to read slave analog inputs message stream com2 message function 4 message slaveStation 2 message slaveRegister 30001 message masterRegister 40001 message length 8 message timeout 30 messag ventRequest FALSE message eventNo 0 main communication loop while TRUI send a new command request _ resource IO SYSTEM status masterSessionl serialModbusMaster amp message release resource IO SYSTEM if status MM SENT waiting MM RECEIVED master2 wait for response or timeout while masterSessionl masterCmdStatus do other things here allow other tasks to execute while release processor if masterSessionl masterCmdStatus goodt badt allow other tasks to execute release processor This task sends commands to a Modbus slave using the same serial port as main Use a Document Version 1 70 5 23 2012 664 Example Programs different MODBUS SESSION structure when sharing a serial port with another master This task uses th task waits for th vent request option The completion event to free up the processor for other tasks static void master2 void ESSAG MASTER M BOOLEAN UINT16 defin message status good bad master message to copy slave digital inputs to master outputs
500. t int main void UINT16 logID recordSize pData UINT32 sequenceNumber seqNumRead nextSeqNum Select data log 10 logID 10 Find first record in data log 10 and store its sequence number in sequenceNumber SL if datalogReadStart logID amp sequenceNumber Get the size of this record Document Version 1 70 5 23 2012 141 Function Specifications if datalogRecordSize logID amp recordSize allocate memory of size recordSize pData UINT16 malloc recordSize read this record if datalogReadNext logID sequenceNumber amp seqNumRead amp nextSeqNum pData use pData to access record contents Af Document Version 1 70 5 23 2012 142 Function Specifications datalogRecordSize Data Log Record Size Function Syntax include lt ctools h gt BOOLEAN datalogRecordSize UINT16 logID UINT16 pRecordSize Description This function returns the size of a record for the specified data log The log needs to have been previously created with the datalogCreate function The function has two parameters log D specifies the data log The valid range is 0 to 15 pRecordSize points to a variable that will hold the size in bytes of each record in the log The function returns TRUE if the operation succeeded The function returns FALSE if the log ID is invalid or if the data log does not exist Notes This function is usefu
501. t Version 1 70 5 23 2012 451 Function Specifications pidinitialize Initialize PID controller data Syntax include lt ctools h gt void pidInitialize PID DATA pData Description This function initializes the PID algorithm data The function has one parameter pData is a pointer to a structure containing the PID data and outputs The function should be called once before calling the pidExecute function for the first time The structure pointed to by pData must contain valid values for sp pv and manualOutput before calling the function The function has no return value See Also pidExecute Example See the Example for pidExecute Document Version 1 70 5 23 2012 452 Function Specifications pollABSlave Poll DF1 Slave for Response Syntax include lt ctools h gt UINT16 pollABSlave FILE stream UINT16 slave Description The pollABSlave function is used to send a poll command to the slave station specified by slave in the DEI Half Duplex protocol configured for the specified port stream specifies the serial port The function returns FALSE if the slave number is invalid or if the protocol currently installed on the specified serial port is not an DF1 Half Duplex protocol Otherwise it returns TRUE and the protocol command status is set to MM_SENT Notes See the Example in the Example Programs chapter under the section Master Message Example Using DF1 Protocol The pollABSlave function
502. t Version 1 70 5 23 2012 644 Example Programs analogInput modbusAddress 30001 index analogInput eventClass CLASS 2 analogInput deadband 1 dnpSaveAI16Config configuration AI16 startAddress index amp analogInput analogInput modbusAddress 30001 index analogInput eventClass CLASS 2 analogInput deadband 1 dnpSaveAI32Config configuration AI16 startAddress index amp analogInput for index 0 index lt configuration AO16 number index t analogOutput modbusAddress 40001 index dnpSaveAO1 6Config configuration AOl6 startAddress index amp analogOutput analogOutput modbusAddress 41001 index 2 dnpSaveA032Config configuration AO32 startAddress index amp analogOutput for index 0 index lt configuration CI16 number index counterInput modbusAddress 30001 index counterInput eventClass CLASS 3 counterInput threshold 1 dnpSaveCI16Config configuration CI16 startAddress index amp counterInput for index 0 index lt configuration CI32 number index counterInput modbusAddress 30001 index 2 counterInput eventClass CLASS 3 counterInput threshold 1 dnpSaveC1I32Config configuration CI32 startAddress index amp counterInput Document Version 1 70 5 23 2012 645 Example Programs main loop while Get Program Status Example TRUE add remainder of program here release pro
503. t Version 1 70 5 23 2012 537 Function Specifications SO_RCVLOWAT The low water mark for receiving data SO_SNDLOWAT The low water mark for sending data SO_R CVBUF Set buffer size for input Default 8192 bytes SO_SNDBUF Set buffer size for output Default 8192 bytes SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind call should allow reuse of local addresses SO_KEEPALIVE enables the periodic transmission of messages on a connected socket If the connected party fails to respond to these messages the connection is considered broken SO_DONTROUTE indicates that outgoing messages should bypass the standard routing facilities Instead messages are directed to the appropriate network interface according to the network portion of the destination address SO_LINGER controls the action taken when unsent messages are queued on a socket and a close on the socket is performed If the socket promises reliable delivery of data and SO_LINGER is set the system will block the process on the close of the socket attempt until it is able to transmit the data or decides it is unable to deliver the information A timeout period termed the linger interval is specified in the setsockopt call wnen SO_LINGER is requested If SO_LINGER is disabled and a close on the socket is issued the system will process the close of the socket in a manner that allows the process to continue as quickly as possible The option SO_ BROADCAST
504. t ctools h gt BOOLEAN ioRead5607Inputs UINT16 moduleAddress UCHAR amp dinData 3 INT16 amp ainData 8 Description This function reads buffered data from the digital and analog inputs of a 5607 I O module Buffered data are updated when an I O request for the module is processed moduleAddress is the address of the 5607 module Valid values are 0 to 7 dinData is a reference to an array of three UCHAR variables Digital data for the 16 external and 8 internal inputs are written to this array One bit in the array represents each input point The 8 internal inputs indicate if the corresponding analog input value is over range ainData is a reference to an array of eight INT16 variables Analog data are written to this array The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5607O0utputs ioWrite5607 Outputs Example This program displays the values of the first 8 digital inputs and the 5th analog input read from 5607 I O at address 5 include lt ctools h gt define MY EVENT 1 void main void UCHAR dinData 3 INT16 ainData 8 IO STATUS io status BOOLEAN status main loop while TRUE add module scan to queue if ioRequest MT_5607Inputs Di Document Version 1 70 5 23 2012 342 Function Specifications status FALSE wait for scan to complete ioNotification MY_ EVENT wa
505. t increments every 10 ms The stopwatch is useful for measuring execution times or generating delays where a fine time base is required The stopwatch time rolls over to 0 when it reaches the maximum value for an unsigned long integer 4 294 967 295 ms or about 49 7 days There is one library function to access the stopwatch time Refer to the Function Specification section for details readStopwatch reads the stopwatch timer Watchdog Timer Functions A watchdog timer is a hardware device which enables rapid detection of computer hardware or software problems In the event of a major problem the CPU resets and the application program restarts The controller provides an integral watchdog timer to ensure reliable operation The watchdog timer resets the CPU if it detects a problem in either the hardware or system firmware A user program can take control of the watchdog timer so it will detect abnormal execution of the program A watchdog timer is a retriggerable time delay timer It begins a timing sequence every time it receives a reset pulse The time delay is adjusted so that regular reset pulses stops the timer from expiring If the reset pulses cease the watchdog timer expires and turns on its output signifying a malfunction The timer output in the controller resets the CPU and turns off outputs at the I O system The watchdog timer is normally reset by the operating system This is transparent to the application program Oper
506. t module e output analog output module nn Write buffered data for 4 point analog output module ioWriteDout16 Write buffered data for 16 point digital output module ioWriteDout8 Write buffered data for 8 point digital output module ioWriteSP2Outputs Write buffered data for SCADAPack 350 outputs Controller UO Functions The following functions are no longer supported The replacement function is indicated for each IEC 61131 1 I O Functions The I O System functions are used in place of the following IEC 61131 1 C Tools I O functions which are no longer supported Document Version 1 70 5 23 2012 686 Porting Existing C Tools Applications Replaced with isaWrite8Dout ioWriteDout amp isaWrite16Dout ioWriteDout16 isaWrite5601 Outputs ioWriteSP2Outputs Backwards Compatibility I O Functions The following I O related functions were available in the original release of the Telepace C Tools They were supported for backward compatibility in later versions of the Telepace C Tools but did not allow access to all I O modules They are no longer compatible with the I O system architecture These functions are replaced with equivalent I O system functions The new functions provide access to all I O modules ain Frater e OO Other I O Function Changes Jiffy Clock Functions The following C Tools I O functions are fully supported in the SCADAPack C Tools with the following dif
507. tDescriptor char bufferPtr int bufferLength int flags 1 Description send is used to transmit a message to another transport end point send may be used only when the socket is in a connected state socketDescriptor is a socket created with socket If the message is too long to pass atomically through the underlying protocol non TCP protocol then the error EMSGSIZE is returned and the message is not transmitted A return value of 1 indicates locally detected errors only A positive return value does not implicitly mean the message was delivered but rather that it was sent Blocking socket send if the socket does not have enough buffer space available to hold the message being sent send blocks Non blocking stream TCP socket send if the socket does not have enough buffer space available to hold the message being sent the send call does not block It can send as much data from the message as can fit in the TCP buffer and returns the length of the data sent If none of the message data fits then 1 is returned with socket error being set to EWOULDBLOCK Non blocking datagram socket send if the socket does not have enough buffer space available to hold the message being sent no data is being sent and 1 is returned with socket error being set to EWOULDBLOCK The select call may be used to determine when it is possible to send more data Sending Out of Band Data For Example if you have remote login application
508. tagrams to be sent to correspondents named in sendto calls Datagrams are generally received with recvfrom which returns the next datagram with its return address The operation of sockets is controlled by socket level options These options are defined in the file lt ctools h gt setsockopt and getsockopt are used to set and get options respectively Parameters family The protocol family to use for this socket currently only PF_INET is used type The type of socket protocol The layer 4 protocol to use for this socket Family Type Protocol Actual protocol PF_INET SOCK_DGRAM IPPROTO_UDP UDP PF_INET SOCK_STREAM IPPROTO_TCP TCP PF_INET SOCK_RAW IPPROTO_ICMP ICMP PF_INET SOCK_RAW IPRPTOTO_IGMP IGMP Returns New Socket Descriptor or 1 on error If an error occurred the socket error can be retrieved by calling getErrorCode socketDescriptor socket will fail if EMFILE No more sockets are available ENOBUFS There was insufficient user memory available to complete the operation EPROTONOSUPPORT The protocol type or the specified protocol is not supported within this family Document Version 1 70 5 23 2012 550 Function Specifications start_protocol Start Serial Protocol Syntax include lt ctools h gt INT16 start protocol FILE stream Description The start_protocol function enables a protocol on the specified serial port It returns TRUE if the protocol was enabled and FALSE if it was not The prot
509. tation 1234 settings priority 250 settings SFMessaging FALSE settings mode AM extended Document Version 1 70 5 23 2012 527 Function Specifications Kei ES request _ resource IO SYST setProtocolSettings com2 release resource IO SYST ER ettings gt E KEE Document Version 1 70 5 23 2012 528 Function Specifications setProtocolSettingsEx Sets extended protocol settings for a serial port Syntax include lt ctools h gt BOOLEAN setProtocolSettingsEx FILE stream PROTOCOL SETTINGS EX pSettings 1 Description The setProtocolSettingsEx function sets protocol parameters for a serial port This function supports extended addressing and Enron Modbus parameters The function has two arguments e port specifies the serial port It is one of com1 com2 or com3 e pSettings is a pointer to a PROTOCOL_SETTINGS_EX structure Refer to the description of the structure for an explanation of the parameters The function returns TRUE if the settings were changed It returns FALSE if the stream is not valid or if the protocol does not start To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Notes The IO_SYSTEM resource needs to be requested before calling this
510. teMsgVariable e writeRealVariable e writeTimerVariable Document Version 1 70 5 23 2012 89 Function Specifications accept Syntax include lt ctools h gt int accept int socketDescriptor struct sockaddr addressPtr int addressLengthPtr 1 Description The argument socketDescriptor is a socket that has been created with socket bound to an address with bind and that is listening for connections after a call to listen accept extracts the first connection on the queue of pending connections creates a new socket with the properties of socketDescriptor and allocates a new socket descriptor for the socket If no pending connections are present on the queue and the socket is not marked as non blocking accept blocks the caller until a connection is present If the socket is marked as non blocking and no pending connections are present on the queue accept returns an error as described below The accepted socket is used to send and recv data to and from the socket that it is connected to It is not used to accept more connections The original socket remains open for accepting further connections accept is used with connection based socket types currently with SOCK_STREAM Using select prior to calling accept It is possible to select a listening socket for the purpose of an accept by selecting it for a read However this will only indicate when a connect indication is pending it is still necessary to call
511. tegt ee ei ee EE 534 EE EE iit nh ne ttt ates 537 E sient aretha ee A A 541 SetstatusModes en ah ah en a ae 542 ET 543 SMUTAOW ie DEE 544 Gel 545 SIECP POCESSOF E 547 Ee Loo E 548 Ee EE 549 Start Dro vin ANANE ONEEN EEE EEE tege dh eeebt et gege 551 SIS TaSk ssi E EE AEE EENEN EE EEE EEEE EEEE 552 SARIA A a RAE T N EEEE EEEE EENE EE AEN 553 sysSerialSetRxTimeout A 554 unregisterBulkDevOperation sssssssseeeeeeeeseriirrrtesestriirnrresssrtrrrnnrnsssrrrnnnnnn 557 VI UNE 559 WO AUTO EE 560 WE sO MADOC EE 561 WO IMAM Allee eege 562 WS IT 563 Oe e E LE EE 564 wrtelntVartable EEEE 565 WIITERGAlV AM ADIOS e 566 Vue VE NET 567 WHITE TIM OPV AMADIS e 569 MOODY AEP E A E E E E E 570 MOGI EIEE PEE EA AE OE OE OAE 571 Etoile 572 AC ee eee 572 EE 572 Casha testes ets eee ba eebe bete bahe te be babe tetetete ba bees fetten 573 RRE EE EE 574 EE 575 Eet 576 E EE 576 e EE 576 Leeeeizesteeeeedeegieesgegeggdeegiee Nee eegen Nee eege eege eege ee eeeeee 576 Lge cece loelveitereles sleet ier es EE es A eR 576 NM teegeeedeesdeesieeeeedeegdee eegeeegd eege eege eege eege eegeeeeE 577 Niao e enee es Rees ee Ae eegen 579 E EE 579 Pcro velvet Rw eee Rs eeeeE 579 PRibccesdeceseestvevdecdiecstecelvssdee Ges A eege eeg eege ee EEeeE 580 OD ses ede sles eles eegene eegene eege eege eege eege ege 581 Lei eegeeedeesieesece eeedeesdeegeeeed eege egeeeed ege E EEE ee eege eege 582 MN esteeedeeedzegr eebe eeedSe E eege eege eege eege eege
512. tems CTools Arm7 gcc pdf Option Description o Level 3 optimization mapcs 32 Generate code for a processor running with a 32 bit program counter and conforming to the function calling standards for the APCS 32 bit option mlittle endian Generate code for a processor running in little endian mode march armv4 Specifies the name of the target ARM architecture as armv4 ISO C99 language standard for C fno builtin Don t recognize built in functions not begining with __builtin_ as prefix Dname Predefine name as a macro with the definition 1 Dname z definition Predefine name as a macro with definition Compile or assemble the source files but not link them Add the directory dirto the head of the list of directories to be searched for header files If you use more than one I option the directories are scanned in left to right order the standard system directories come after fdollars in identifiers Accept in identifiers Specifies the name of the output file Document Version 1 70 5 23 2012 44 C Program Development Application Development Please refer to the Program Development Tutorial for details on how to build load and execute a C Application Document Version 1 70 5 23 2012 45 Real Time Operating System Real Time Operating System Task Management Task Execution The real time operating system RTOS provides the programmer with tools for b
513. ter MT_5601 Inputs 5601 module analog and digital inputs MT _54150utputs 5415 digital output module digital outputs MT_5601Outputs 5601 module digital outputs MSG_DATA Specifies the data field in an envelope contains a data value Document Version 1 70 5 23 2012 578 Macro Definitions NO_PROTOCOL Specifies no communication protocol for the serial port code for a Modbus Handler speed NOTYPE Specifies serial port type is not known NUMAB Number of registers in the Allan Bradley database NUMCOIL Number of registers in the Modbus coil section NUMHOLDING Number of registers in the Modbus holding register section NUMINPUT Number of registers in the Modbus input register section NUMLINEAR Number of registers in the linear database NUMSTATUS Number of registers in the Modbus status section oD Species odd pariy OPEN Specifies switch is in open position Document Version 1 70 5 23 2012 579 Macro Definitions PC_FLOW_RX_RECEIVE_ST Receiver disabled after receipt of a O message PC_FLOW_RX_XON_XOFF Receiver Xon Xoff flow control PC_FLOW_TX_IGNORE_CT Transmitter flow control ignores CTS PC_FLOW_TX_XON_XOFF Transmitter Xon Xoff flow control ONR x FLOW TX OTS PC PROTOCOL RTU FRAMI Modbus RTU framing NG REDUCED CLOCK PHONE_NUM_MAX_LEN Maximum length of the phone number string PM_CPU_FULL_CLOCK The CPU is set to run at full speed PM_CPU_REDUCED_CLOC The CPU is set to run
514. terPollEx type pMasterPoll 1 Description This function is only available on the SCADAPack 32 SCADAPack 350 and 4203 This function reads an extended entry from the DNP master poll table pMasterPoll is a pointer to an extended table entry it is written by this function The return value is TRUE if pMasterPoll was successfully written or FALSE otherwise Notes This function is only available on the SCADAPack 32 SCADAPack 350 and 4203 DNP needs to be enabled before calling this function in order to create the DNP configuration This function supersedes the dnopReadMasterPollTableEntry function Document Version 1 70 5 23 2012 198 Function Specifications dnpReadMasterPollTableSize Read DNP Master Poll Table size Syntax include lt ctools h gt UINT16 dnpReadPMasterPollTableSize void Description This function reads the total number of entries in the DNP master poll table Notes DNP needs to be enabled before calling this function in order to create the DNP configuration The function returns the total number of entries in the DNP master poll table Document Version 1 70 5 23 2012 199 Function Specifications dnpReadRoutingTableEntry_DialStrings Read DNP Routing Table Entry Dial Strings Syntax BOOLEAN dnpReadRoutingTableEntry DialStrings UINT16 index UINT16 maxPrimaryDialStringLength CHAR primaryDialString UINT16 maxSecondaryDialStringLength CHAR seconda
515. terPollTableEntryEX ccccccceeceeeecceneeeeeeeeeeeeeeaeeeeeeeeeseeesaeeeeeees 225 dnpWriteRoutingTableEntry_DialString ccceeceeeeeeeeeeeeeneeeeeeeeeeeeeseeeeeeees 226 dnpWrtiebioutng Tablett 227 dnpWrtiebioutngT abletntrvEs 228 ONG APPLICA OM vvcevel steve sere ee encdeeesweuaes st vad us eauseuutst et eheseausuesesd T 229 CNC OUP EE E EE 230 QING EE 231 ONG Mi E otek eeepc E 232 enronlnstallCommandHandler ssssseessseeeeeesesssenirrrressstnrrrnrrssssnrnrnnnsssssennnn 233 NENT 237 eibemetGerMAC Address 238 ERT 239 EE ene ET 240 HASMOSUINGSSAV Eeer EERSTEN 241 tele EE 242 UE 243 QetABConfiguration siina aaa a aa a aa Tenis 244 eet 245 OStGlOCKA arin ET 246 eege 247 EE EIER ele EE EE reece carer EE 248 eeler mi fe 9 eeeeronerrecererertcerteerteerec T T TE E errr 249 EE 251 GEREEST na ree 252 QetHardwarelnformation cccccccccccceeeee cece eeeeeceaeeeeeeeeeeeeecaaeeeeeeeesseeenteeeeeees 253 GetlOErrorlNdicallon evtevie ee ee ees 254 oetCutputslnGiopMocde 255 getLoginCredentials s vee ee ea eee 256 DIEDERT 257 QetPortCharacteristics A 258 Document Version 1 70 5 23 2012 Cet PON GE 259 GEtLPOWerMOde sss iri sists fete ished ee a Na 260 gelt eu ET 261 get POLO COM EE 262 JetRTOtOCOIS EtG EE 263 g tProt lSettingS EX AA 265 eg reel E 267 eelste EE ren EE 268 g tSF Translation EX ieste atapir natania rabani taape aea bam bn ama rnein anapima Enn 269 ee NL 270 ee ee EE 271 QSL SL
516. the number of registers e timeout specifies how long in tenths of seconds to wait for a response e eventRequest requests an event to be signaled on completion If set to TRUE the eventNo will be signaled when the response is received or a timeout has occurred Set to FALSE to disable this feature e evento specifies the event to signal on completion This field is only used if eventRequest is set to TRUE MODBUS_CMD_STATUS The master command status codes have been changed from macros to the enumeration type MODBUS_CMD_STATUS The previously supported status codes have the same value as they did as a macro typedef enum modbusCmdStatus_ t SENT 0 RECEIVED NO MESSAGE BAD_ FUNCTION BAD SLAVE BAD ADDRESS BAD LENGTH PROTOCOL NOT SUPPORTED 7 ll Nu AH NON NON additional master command status codes used for Modbus TCP master messaging only CONNECTING 8 CONNECTED 9 CONNECT TIMEOUT 10 SEND_ERROR U RSP_TIMEOUT RSP_ ERROR DISCONNECTING DISCONNECTED 15 BAD CONNECT ID 16 BAD PROTOCOL TYP 17 BAD IP ADDRESS 18 BUSY 19 ENDED 20 CONNECT ERROR SE MO MORE CONNECTIONS 22 BAD CONNECTION TYPE SE MM EXCEPTION FUNCTION 24 MM EXCEPTION ADDRESS 25 EXCEPTION VALUE 26 ll m N oll ere a Ww SS Sal
517. the operating system will give each task of the same priority time slices to share the CPU For tasks such as a protocol handler that wait for an event using the wait_event or receive_message function a priority higher than 100 e g 75 may be selected without blocking other lower priority tasks The number of stack blocks required depends on the functions called within the task and the size of local variables created Tasks usually require 2 stack blocks Document Version 1 70 5 23 2012 129 Function Specifications If the fprintf function is used then at least 5 stack blocks are required Add local variable usage to these limits if large local arrays or structures are created Large structures and arrays are usually handled as static global variables within the task source file The variables are global to all functions in the task but cannot be seen by functions in other files Additional stack space may be made available by disabling unused protocol tasks See the section Program Development or the set_protocol function for more information See Also end_task Example See the Create Task Example in the Examples section Document Version 1 70 5 23 2012 130 Function Specifications databaseRead Read Value from I O Database Syntax include lt ctools h gt BOOLEAN databaseRead UINT16 addrMode UINT16 address INT16 value Description The databaseRead function reads a value from the databa
518. the specified string is written to the message variable If the variable is not found or if the IEC 61131 1 Symbols Status is invalid nothing is done and FALSE is returned The IEC 61131 1 Symbols Status is invalid if the Application TIC code download and Application Symbols download are not sharing the same symbols CRC checksum The pointer msg must point to a character string large enough to hold the maximum length declared for the specified message variable plus two length bytes and a null termination byte i e max declared length 3 When writing to the message variable all bytes are copied except the first byte max length byte and the last byte null termination byte IEC 61131 1 message variables have the following format Byte Description Location a a length as declared in IEC 61131 1 E 1 to 255 Current Length location of first null byte 0 to maximum length First message data byte C byte in message buffer max 2 Null termination byte Terminates a message having the maximum length Notes This function requires the IEC 61131 1 Application Symbols to be downloaded to the controller in addition to the Application TIC code This function provides a convenient method to access IEC 61131 1 variables by name however because the variable name needs to be looked up in the IEC 61131 1 variable list each call the performance of the function may be slow for large numbers of variables Document Version 1
519. there are no connections available or if there is an error in one of the arguments FALSE is returned and an error code is copied to the value pointed by cmdStatus The new mastering task establishes the initial connection and sends Modbus IP master messages each time mTcpMasterMessage is called Use the function mTcpMasterStatus to determine the status of the connection or master message in progress The connection ID for this master connection is copied to the value pointed to by connectID This ID needs to be used when calling the remaining master messaging API functions for this connection mTcpMasterMessage mTcpMasterStatus mTcpMasterDisconnect and mTcpMasterClose The enumeration types and structures used for the function arguments are described in the Structures and Types section Document Version 1 70 5 23 2012 442 Function Specifications Notes The functions mTcpMasterDisconnect and mTcpMasterClose needs to be called to disconnect and return this connection ID to the pool of available connections Even if the connection to the remote IP is disconnected manually or automatically after an idle timeout the connection ID remains allocated until mTcpMasterDisconnect is called to disconnect and end the mastering task and mTcpMasterClose is called to return the connection ID There are only 20 connections available for all Modbus IP master and slave connections Use the function ipGetConnectionSummary obtain the number of
520. they are loaded on controller reset call flashSettingsSave as shown below request _ resource FLASH MEMORY flashSettingsSave CS_ RUN release resource FLASH MEMORY Notes The lIO_SYSTEM resource needs to be requested before calling this function with Telepace firmware See Also mTcpGetProtocol mTcpSetInterfaceEx Document Version 1 70 5 23 2012 437 Function Specifications mTcpMasterClose Close Modbus IP Master Messaging Session Syntax include lt ctools h gt BOOLEAN mTcpMasterClose UINT32 connectID Description The mTcpMasterClose function returns the specified connectID to the pool of available connections so that it may be re used for other new connections FALSE is returned if the specified connectID is invalid or if the connection has not been disconnected otherwise TRUE is returned and the connectID is released After calling this function the function mTcpMasterStatus may no longer be called with this connectID The function mTcpMasterDisconnect needs to be called first before calling mTcpMasterClose to disconnect and end the mastering task If this is not done mTcpMasterClose returns FALSE and the connectID is not released Example See Example for Master Message Example Using mTcpMasterMessage Document Version 1 70 5 23 2012 438 Function Specifications mTcpMasterDisconnect Disconnect Modbus IP Master Connection Syntax include lt ctools
521. time synchronization requests e Set this to STARTUP_TIME_SYNC to request time synchronization at start up only e Set this to 1 to 32767 to set the time synchronization period in seconds e Bl_number is the number of binary input points Valid values are 0 to 9999 e Bl_startAddress is the DNP address of the first Binary Input point e Bl_reportingMethod determines how binary inputs are reported either Change Of State or Log All Events e Bl_soebufferSize is the Binary Input Change Event Buffer Size Document Version 1 70 5 23 2012 602 Structures and Types e BO_number is the number of binary output points Valid values are 0 to 9999 e BO_startAddress is the DNP address of the first Binary Output point e CID number is the number of 16 bit counter input points Valid values are 0 to 9999 e Cl16_startAddress is the DNP address of the first C116 point e CI16_reportingMethod determines how Cl16 inputs are reported either Change Of State or Log All Events e Cl16_bufferSize is the number of events in the 16 bit counter change buffer Valid values are 0 to 9999 e CI32_number is the number of 32 bit counter input points Valid values are 0 to 9999 e CI32_startAddress is the DNP address of the first C132 point e CI32_reportingMethod determines how C132 inputs are reported either Change Of State or Log All Events e CI32_bufferSize is the number of events in the 32 bit counter change buffer Valid values are 0 t
522. tion See Also Example include lt ctools h gt int main void request resource IO SYSTEM overrideDbase MODBUS 40001 102 overrideDbase LINEAR 302 330 Document Version 1 70 5 23 2012 448 Function Specifications release resource IO SYSTEM Document Version 1 70 5 23 2012 449 Function Specifications pidExecute Execute PID control algorithm Syntax include lt ctools h gt BOOLEAN pidExecute PID DATA pData Description This function executes the PID algorithm The function may be called as often as desired but needs to be called at least once per the value in the period field for proper operation The function has one parameter pData is a pointer to a structure containing the PID block data and outputs The function returns TRUE if the PID block executed The function returns FALSE if it was not time for execution Notes To properly initialize the PID algorithm do one of the following e Call the pidinitialize function once before calling this function the first time or e put the PID algorithm in manual mode autoMode FALSE in PID_DATA for the first call to the pidExecute function Example This Example initializes one PID control structure and executes the control algorithm continuously Input data is read from analog inputs Output data is written to analog outputs include lt ctools h gt event number to signal when I O scan
523. tions master_message Send Protocol Command Syntax include lt ctools h gt UINT16 master message FILE stream UINT16 function UINT16 slave station UINT16 slave address UINT16 master address UINT16 length Description The master_message function sends a command using a communication protocol The communication protocol task waits for the response from the slave station The current task continues execution e port specifies the serial port e function specifies the protocol function code Refer to the communication protocol manual for supported function codes e slave specifies the network address of the slave station This is also known as the slave station number e address specifies the location of data in the slave station Depending on the protocol function code data may be read or written at this location e master_address specifies the location of data in the master this controller Depending on the protocol function code data may be read or written at this location e length specifies the number or registers The master_message function returns the command status from the protocol driver MM_EXCEPTION_ FUNCTION Master message status Modbus slave returned a function exception MM_EXCEPTION_ADDRESS Master message status Modbus slave returned an address exception MM_EXCEPTION_VALUE Master message status Modbus slave returned a value exception The calling task monitors the status of the com
524. to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1 Notes The function databaseWrite returns TRUE if the requested database value was written FALSE is returned if the requested database entry could not be written The I O database is not modified when the controller is reset It is a permanent storage area which is maintained during power outages The lO_SYSTEM resource needs to be requested before calling this function See Also databaseRead Document Version 1 70 5 23 2012 132 Function Specifications datalogCreate Create Data Log Function Syntax include lt ctools h gt DATALOG_STATUS datalogCreate UINT16 oof DATALOG_CONFIGURATION pLogConfiguration Description This function creates a data log with the specified configuration The data log is created in the data log memory space The function has two parameters log D specifies the data log to be created The valid range is 0 to 15 pLogConfiguration points to a structure with the configuration for the data log The function returns the status of the operation Notes The configuration of an existing data log cannot be changed The log needs to be deleted and recreated to change the configuration All data logs are stored in memory from a pool for all data logs If there is insufficient memory the creation operation fails The function returns DLS_NOMEMORY If the data log already exists the creation operation fails The function returns DLS_E
525. to TRUE enables the watchdog Calling the function with state set to FALSE disables the watchdog Document Version 1 70 5 23 2012 561 Function Specifications wd_manual Manual Watchdog Timer Mode Syntax include lt ctools h gt void wd_manual void Description The wd_manual function takes control of the watchdog timer Notes The application program needs to retrigger the watchdog timer at least every 0 5 seconds using the wd_pulse function to avoid a controller reset Refer to the Functions Overview section for more information See Also wd enabled Example This program takes control of the watchdog timer for a critical section of code then returns it to the control of the operating system include lt ctools h gt int main void wd_manual wd_pulse code executing in less than 0 5 s wd_pulse code executing in less than 0 5 s wd_auto as much code as you wish Document Version 1 70 5 23 2012 562 Function Specifications wd_pulse Retrigger Watchdog Timer Syntax include lt ctools h gt void wd pulse void Description The wd_pulse function retriggers the watchdog timer Notes The wd_pulse function needs to execute at least every 0 5 seconds to avoida controller reset if the wd_manual function has been executed Refer to the Functions Overview section for more information Example See the Example for the wd_manu
526. tocols e serverEnabled is the enable server control flag IP_PROTOCOL_TYPE IP_SETTINGS The IP_PROTOCOL_TYPE enumerated type defines TCP IP protocols supported by the SCADAPack 350 typedef enum ipProtocol t PP None 0 IPP ModbusTcp IPP ModbusRtuOverUdp IPP ModbusAsciiOverUdp IPP DnpOverTcp IPP DnpOverUdp IP PROTOCOL TYPE ER The IP Settings structure defines IP settings for a communication interface installed on the TCP IP stack typedef struct st_IPSettings IP CONFIG MODE ipConfigMode UINT32 ipAddress 4 UINT32 gateway 4 UINT32 netMask UCHAR ipVersion Ip SETTINGS Document Version 1 70 5 23 2012 615 Structures and Types ledControl_tag e ipConfigMode are the IP configuration options See the IP_CONFIG_MODE enumeration for values supported e ipAddress is the IP address Only the first 32 bit value in this array is supported and contains IP address in form of 32 bit unsigned integer For example IP address 172 016 017 018 will be represented with following 32 bit unsigned number 172 16x256 17x256x256 18x256x256x256 303108268 e gateway is the network gateway Only the first 32 bits are supported e netMask is the subnet mask e _ipVersion is the IP version Only the value 4 is supported for IP version 4 The ledControl_tag structure defines LED power control parameters struct ledControl tag UINT16 state UINT16 time 1 e state is the default LED
527. tocols typedef enum addressMode t AM standard 0 AM extended ADDRESS MODE ER e AM standard returns standard Modbus addressing Standard addressing allows 255 stations and is compatible with standard Modbus devices e AM extended returns extended addressing Extended addressing allows 65534 stations ALARM_SETTING The ALARM_SETTING structure defines a real time clock alarm setting typedef struct alarmSetting tag UINT16 type UINT16 hour UINT16 minute UINT16 second ALARM SETTING e type specifies the type of alarm It may be the AT_NONE or AT_ABSOLUTE macro e hour specifies the hour at which the alarm will occur e minute specifies the minute at which the alarm will occur e second specifies the second at which the alarm will occur COM_INTERFACE The COM_INTERFACE enumerated type defines a communication interface type and may have one of the following values typedef enum interface t 3 EI CIF Coml CIE Com CIF Com oll Nh Document Version 1 70 5 23 2012 585 Structures and Types CIF Ethernetl 100 COM_INTERFACE COMM_ENDPOINT The COMM_ENDPOINT structure defines a communication endpoint If ethernet based protocols are not used then the ipAddress and portNumber fields should be set to 0 struct COM INTERFACE interface UINT32 stationAddress UINT32 ipAddress UINT16 portNumber UCHAR protocol COM
528. tputs UINT16 moduleAddress UCHAR amp doutData 2 Description This function writes to the I O table for the 12 output points of a 5415 relay output module Data are written to the module when an I O request for the module is processed moduleAddress is the address of the 5415 module Valid values are 0 to 15 doutData is a reference to an array of two UCHAR variables Digital data for the 12 outputs are read from this array One bit in the array represents each output point See Also ioRead54150utputs ioRead5415Inputs Example This Example turns on all the digital outputs on the 5415 I O module include lt ctools h gt include nvMemory h define MY EVENT 1 void main void UCHAR doutData 2 IO_ STATUS io status BOOLEAN status main loop while TRUE write data to output tables for next scan doutData 0 OxFF doutData 1 OxOF status ioWrite54150utputs 0 doutData add module scan to queue if i1oRequest MT_54150utputs 0 Document Version 1 70 5 23 2012 378 Function Specifications status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT read input data from last scan check status of last scan if i1o0Status MT 54150utputs 0 status FALSE else if i0 status commStatus status FALSE amp io status rel
529. ts e AISF_bufferSize is the short float Analog Input Event Buffer Size e AISF_wordOrder is the word order of AISF points O LSW first 1 MSW first e AQ16_number is the number of 16 bit analog output points Valid values are 0 to 9999 e A0Q16_startAddress is the DNP address of the first AO16 point e AQ32_number is the number of 32 bit analog output points Valid values are 0 to 9999 e AQ32_startAddress is the DNP address of the first AO32 point e AQ32_wordOrder is the Word Order of AO32 points O LSW first 1 MSW first e AOSF_number is the number of short float Analog Outputs e AOSF_startAddress is the DNP address of first AOSF point e AOSF_wordOrder is the Word Order of AOSF points O LSW first 1 MSW first e autoUnsolicitedClass1 enables or disables automatic Unsolicited reporting of Class 1 events e holdTimeClass1 is the maximum period to hold Class 1 events before reporting e holdCountClass1 is the maximum number of Class 1 events to hold before reporting e autoUnsolicitedClass2 enables or disables automatic Unsolicited reporting of Class 2 events e holdTimeClass2 is the maximum period to hold Class 2 events before reporting e holdCountClass2 is the maximum number of Class 2 events to hold before reporting e autoUnsolicitedClass3 enables or disables automatic Unsolicited reporting of Class 3 events Document Version 1 70 5 23 2012 604 Structures and Types e holdTimeClass3 is the
530. ty as the main task Therefore the main task remains the running task The auxiliary task is ready to run and it is placed on the Ready queue Event 10 Queue echoData auxiliary null Figure 5 Queue Status after Creation of auxiliary Task This point occurs just after the main task releases the processor but before the next task is selected to run The main task is added to the end of the priority 1 list in the Ready queue On the next instruction the RTOS will select the highest priority task in the Ready queue Document Version 1 70 5 23 2012 57 Real Time Operating System Execution Point 7 Execution Point 8 Ready Queue Event 10 Queue Running Task p gt none echoData auxiliary null Figure 6 Queue Status After main Task Releases Processor This point is just after the auxiliary task has started to run The main and auxiliary tasks will continue to alternate execution as each task releases the processor to the other Event 10 Queue Running Task auxiliary echoData main 255 U nullTask Figure 7 Queue Status at Start of auxiliary Task This point occurs just after a character has been received The signalCharacter function executes and signals an event The RTOS checks the event queue for the event and makes the highest priority task ready to execute In this case the echoData task is made ready The
531. ude lt ctools h gt BOOLEAN ioReadDin8 UINT16 moduleAddress UCHAR amp data Description This function reads buffered data from the 8 point digital input module at the specified module address Buffered data are updated when an I O request for the module is processed The function has two parameters the module address and a reference to an UCHAR variable If the moduleAddress is valid digital inout data are copied to the variable The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 356 Function Specifications ioReadDout16 Read Data From 16 point Digital Output Module Syntax include lt ctools h gt BOOLEAN ioReadDout16 UINT16 moduleAddress UINT16 amp data Description This function reads buffered data used for the 16 point digital output module at the specified module address Buffered data are written using the ioWriteDout16 function The function has two parameters the module address and a pointer to an UINT16 variable If the moduleAddress is valid digital inout data are copied to the variable The valid range for moduleAddress is 0 to 15 The function returns FALSE if the module address is invalid otherwise TRUE is returned Document Version 1 70 5 23 2012 357 Function Specifications ioReadDout32 Read from 32 Digital Outputs Syntax include lt ctools h gt
532. uest MT_5506Inputs Di status FALSE wait for scan to complete ioNotification MY EVENT wait event MY_EVENT vead input data from last scan status ioRead5506Inputs 5 dinData ainData check status of last scan if ioStatus MT _5506Inputs 5 amp io status status FALSE else if io status commStatus status FALSE print data if done Dins 0 to 7 X Ain 4 status dinData ainData done TRUE fprintf coml status u d r n 4 r release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 335 Function Specifications ioRead5506Outputs Read 5506 Configuration Syntax include lt ctools h gt BOOLEAN ioRead55060utputs UINT16 moduleAddress UINT16 amp inputType 8 UINT16 amp inputFilter UINT16 amp scanFrequency Description This function reads configuration data from the I O Table for a 5506 I O module Configuration data are written using the ioWrite5506Outputs function moduleAddress is the address of the 5506 module Valid values are 0 to 15 inputType is a reference to an array of eight UINT16 variables Analog input measurement types are written to this array Valid values are e 0 O0to 5V e 1 1to5V e 2 0to20mA e 3 4to 20 mA inputFilter is a reference to a UINT16 variable The input filter selection is wr
533. uilding sophisticated applications The RTOS allows pre emptive scheduling of event driven tasks to provide quick response to real world events Tasks multi task cooperatively Inter task communication and event notification functions pass information between tasks Resource functions facilitate management of non sharable resources The task management functions provide for the creation and termination of tasks Tasks are independently executing routines The RTOS uses a cooperative multi tasking scheme with pre emptive scheduling of event driven tasks The initial task the main function may create additional tasks The maximum number of tasks is limited only by available memory There are 256 task priority levels to aid in scheduling of task execution SCADAPack 350 and 4203 controllers can execute one task at a time The RTOS switches between the tasks to provide parallel execution of multiple tasks The application program can be event driven or tasks can execute round robin one after another Task execution is based upon the priority of tasks There are 256 priority levels Application programs can use levels 100 to 0 The main task is created at priority level 100 Task level 0 is the highest priority task Tasks that are not running are held in queues The Ready Queue holds tasks that are ready to run Event queues hold tasks that are waiting for events Message queues hold tasks waiting for messages Resource queues hold tasks that
534. ule scan to queue Document Version 1 70 5 23 2012 375 Function Specifications if ioRequest MT_52100utputs 0 status FALSE wait for scan to complete ioNotification MY_ EVENT wait event MY_EVENT read input data from last scan check status of last scan if ioStatus MT_52100utputs 0 amp 10 status status FALSE else if io status commStatus status FALSE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 376 Function Specifications ioWrite54140utputs Write 5414 module configuration parameter outputs Syntax include lt ctools h gt BOOLEAN ioWrite54140utputs UINT16 moduleAddress UINT16 inputType UINT16 scanFrequency Description This function writes to the I O table for the output configuration of a 5414 module Data are written to the module when an I O request for the module is processed moduleAddress is the address of the 5414 module Valid values are 0 to 15 inputType selects the input type of AC or DC Valid values are e 0 DC e 1 AC scanFrequency selects the scan frequency setting Valid values are e 0 60Hz e 1 50Hz See Also ioRead541 4Inputs Document Version 1 70 5 23 2012 377 Function Specifications ioWrite5415Outputs Write 5415 module outputs Syntax include lt ctools h gt BOOLEAN ioWrite54150u
535. ull set FD_SET fd amp fdset Includes a particular socket descriptor fd in fdset FD_CLR fd amp fdset Removes fd from fdset FD_ISSET fd amp fdset Is non zero if fdis a member of eet zero otherwise The term fd is used for BSD compatibility since select is used on both file systems and sockets under BSD Unix Parameters numberSockets Biggest socket descriptor to be tested plus one readSocketsPtr The pointer to a mask of sockets to check for a read condition writeSocketsPtr The pointer to a mask of sockets to check for a write condition exceptionSocketsPir The pointer to a mask of sockets to check for an exception condition Out of Band data timeOutPtr The pointer to a structure containing the length of time to wait for an event before exiting Document Version 1 70 5 23 2012 497 Function Specifications Returns gt 0 Number of sockets that are ready 0 Time limit exceeded 1 An error occurred If an error occurred the socket error can be retrieved by calling getErrorCode socketDescriptor select will fail if EBADF One of the socket descriptors is bad EINVAL A component of the pointed to time limit is outside the acceptable range tv_sec needs to be between 0 and 108 inclusive tv_usec needs to be greater than or equal to 0 and less than 106 Document Version 1 70 5 23 2012 498 Function Specifications send Syntax include lt ctools h gt int send int socke
536. umber of the protocol that controls the option For Example to indicate that an option is to be interpreted by the TCP protocol protoco Level is set to the TCP protocol number The parameters optionValuePtr and optionlength are used to access option values for setsockopt optionName and any specified options are passed un interpreted to the appropriate protocol module for interpretation The include file lt ctools h gt contains definitions for the options described below Most socket level options take an int pointer for option ValuePtr For setsockopt the integer value pointed to by the optionValuePir parameter should be non zero to enable a boolean option or zero if the option is to be disabled SO_LINGER uses a struct linger parameter that specifies the desired state of the option and the linger interval see below struct linger is defined in lt ctools h gt struct linger contains the following members _onoff on 1 off 0 _linger linger time in seconds The following options are recognized at the socket level SOL_SOCKET protocolLevel options SO_DONTROUTE Enable disable routing bypass for outgoing messages Default 0 SO_KEEPALIVE Enable disable keep connections alive Default 0 SO_LINGER Linger on close if data is present Default is on with 60 seconds timeout SO_OOBINLINE Enable disable reception of out of band data in band Default 0 SO_REUSEADDR Enable disable local address reuse Default 0 disable Documen
537. ument Version 1 70 5 23 2012 333 Function Specifications ioRead5506Inputs Read 5506 Inputs Syntax include lt ctools h gt BOOLEAN ioRead5506Inputs UINT16 moduleAddress UCHAR amp dinData INT16 amp ainData 8 Description This function reads buffered data from the digital and analog inputs of a 5506 I O module Buffered data are updated when an I O request for the module is processed moduleAddress is the address of the 5506 module Valid values are 0 to 15 dinData is a reference to a UCHAR variable Digital data for the 8 internal inputs are written to this variable One bit in the variable represents each input point The 8 internal inputs indicate if the corresponding analog input value is over range ainData is a reference to an array of eight INT16 variables Analog data are written to this array The function returns FALSE if the module address is invalid otherwise TRUE is returned See Also ioRead5506Outputs ioWrite5506Outputs Example This program displays the values of the 8 internal digital inputs and the 5th analog input read from 5506 I O at address 5 include lt ctools h gt define MY EVENT 1 int main void UCHAR dinData INT16 ainData 8 IO STATUS io status BOOLEAN status BOOLEAN done main loop while TRUE add module scan to queue Document Version 1 70 5 23 2012 334 Function Specifications if ioReq
538. unction Other changes take effect on existing as well as new connections The function copies settings from the structure pointed to by pSeittings to the Modbus TCP protocol configuration and returns TRUE The structure MTCP_CONFIGURATION is described in the Structures and Types section If there is an invalid setting FALSE is returned and the settings are not copied To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request resource FLASH MEMORY flashSettingsSave CS_ RUN release resource FLASH MEMORY Document Version 1 70 5 23 2012 434 Function Specifications mTcpSetinterface Set Modbus IP Interface Settings Syntax include lt ctools h gt BOOLEAN mTcpSetInterface COM INTERFACE ifType MTCP_IF SETTINGS pSettings Description The mTcpSetInterface function is used to set the interface settings used by the Modbus IP protocols If the selected interface or the settings are invalid FALSE is returned otherwise TRUE is returned and the settings are set for the specified interface The valid value for ifType is CIF_Ethernet1 The enumeration type COM_INTERFACE and the structure MTCP_IF_SETTINGS are described in the Structures and Types section To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashS
539. unction writes a record to the specified data log The log needs to have been previously created with the datalogCreate function The function has two parameters log D specifies the data log The valid range is 0 to 15 pData is a pointer to the data to be written to the log The amount of data copied using the pointer is determined by the configuration of the data log The function returns TRUE if the data is added to the log The function returns FALSE if the log ID is not valid or if the log does not exist Notes Refer to the datalogCreate function for details on the configuration of the data log If the data log is full then the oldest record in the log is replaced with this record See Also See example DataLog program in the Example Programs section datalogReadStart datalogReadNext datalogPurge Example See the example for datalogReadStart Document Version 1 70 5 23 2012 145 Function Specifications dbase Read Value from I O Database Syntax include lt ctools h gt INT16 dbase UINT16 type UINT16 address Description The dbase function reads a value from the database type specifies the method of addressing the database address specifies the location in the database The table below shows the valid address types and ranges Type Address Ranges Register Size MODBUS 00001 to NUMCOIL 10001 to 10000 NUMSTATUS 30001 to 30000 NUMINPUT 40001 to 40000 NUMHOLDING LINEAR 0 to NUMLINEAR 1
540. untClass3 3 configuration enableUnsolicitedOnStartup TRUE configuration sendUnsolicitedOnStartup FALSE configuration level2Compliance FALSE Set DNP Configuration dnpSaveConfiguration amp configuration Start DNP protocol on com port 3 get_protocol com3 amp protocolSettings protocolSettings type DNP set_protocol com3 amp protocolSettings EE Configure Binary Output Points for index 0 index lt configuration BO number index binaryOutput modbusAddressl 1 index binaryOutput modbusAddress2 1 index binaryOutput controlType NOT_PAIRED dnpSaveBOConfig configuration BO startAddress index amp binaryOutput EE Configure Binary Input Points for index 0 index lt configuration BI number index binaryInput modbusAddress 10001 index binaryInput eventClass CLASS 1 dnpSaveBIConfig configuration BI startAddress index amp binaryInput Configure 16 Bit Analog Input Points ee for index 0 index lt configuration AI16 number indext Documen
541. unters UO lines status and I O driver buffer information for stream H portis not a valid serial port the function has no effect status must point to a valid serial port status structure pstatus The get_status function copies the serial port status into the structure pointed to by status and returns a pointer to the structure seftings Refer to the Overview of Functions section for detailed information on serial ports See Also clear_errors Example This program displays the framing and parity errors for com1 include lt ctools h gt int main void struct pstatus status get_status coml amp status fprintf coml Framing d r n status framing fprintf com1 Parity Y d r n status parity Document Version 1 70 5 23 2012 275 Function Specifications getStatusBit Read Bits in Controller Status Code Syntax include lt ctools h gt UINT16 getStatusBit UINT16 bitMask Description The getStatusBit function returns the values of the bits indicated by bitMask in the controller status code Bits 0 1 and 2 of the status code are used by the controller firmware Attempting to control these bits will result in indeterminate operation Bit 0 Module Failure Bit 1 Register Assignment Checksum Failure Bit 2 IO Queue Full Bit 3 Reduced Power Mode SCADAPack 4203 only See Also setStatusBit clearStatusBit Document Version 1 70 5 23 2012 276 Function Specifications
542. ut pAnalogOutput 1 Description The dnpSaveAO16Config function sets the configuration of a DNP 16 bit analog output point The function has two parameters the point number and a pointer to an analog output point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetAO16Config Example See example in the dnpGetConfiguration function section Document Version 1 70 5 23 2012 207 Function Specifications dnpSaveAO32Config Save DNP 32 Bit Analog Output Configuration Syntax include lt ctools h gt BOOLEAN dnpSaveAO32Config UINT32 point dnpAnalogOutput pAnalogOutput 1 Description The dnpSaveAO32Config function sets the configuration of a DNP 32 bit analog output point The function has two parameters the point number and a pointer to an analog output point configuration structure The function returns TRUE if the configuration was written It returns FALSE if the point number is not valid if the configuration is not valid or if DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration See Also dnpGetAO32Config Example See
543. uts include lt ctools h gt int main void UCHAR doutData 2 INT16 aoutData 2 BOOLEAN status BOOLEAN done BOOLEAN printNow main loop while TRUE read output data from I O table status ioReadSP20utputs doutData aoutData print data when coil register 100 is selected request resource IO SYSTEM printNow dbase MODBUS 100 Document Version 1 70 5 23 2012 362 Function Specifications fprintf com1 Douts 0 to 7 done TRU Fl release resourc IO_SYSTEM if printNow if done Status Su A EN Aout 0 d r n status doutData 0 aoutData 0 else done FALSE release processor to other priority 1 tasks release processor Document Version 1 70 5 23 2012 363 Function Specifications ioRequest Add LO Module Scan Request to Request Queue Syntax include lt ctools h gt BOOLEAN ioRequest IO TYPE moduleType UINT16 moduleAddress Description This function adds to the I O Controller request queue an I O module scan request for the specified I O module The function has two arguments the module type and the module address Refer to the table below for valid I O module types and address ranges The function returns TRUE if the request was added The function returns FALSE if there is no room in the request queue or if an argument is invalid 1015
544. uts ioWrite5601 Outputs ioWrite56040utputs ioWrite5606Outputs ioWrite56070utputs ioWriteDout8 Counter Input Functions Read the digital and analog outputs from a 5606 I O Module Read buffered data from any 16 point Digital output module Read buffered data from any 32 point Digital output module Read buffered data from the 5415 digital output module Read buffered data from the 5415 digital output module Read buffered data from any 5601 I O Module Read buffered data from any 5604 I O Module Read buffered data from any 8 point Digital output module Write data to the I O tables for any 16 point Digital output module Write data to the I O tables for any 32 point Digital output module Write data to the I O table for the digital outputs of a 5415 I O Module Write data to the I O table for the digital outputs of a 5601 I O Module Write to the digital and analog outputs of SCADAPack 5604 I O Module Write to the digital and analog outputs of a 5606 I O Module Write to the digital and analog outputs of a 5606 I O Module Write data to the I O tables for any 8 point Digital output module The controller supports internal counters and external counter modules The counter registers are 32 bits for a maximum count of 4 294 967 295 They roll over to 0 on the next count The counter inputs measure the number of rising Document Version 1 70 5 23 2012 65 Overview of Programming Functions
545. veAO16Config Sets the configuration of a DNP 32 bit analog output point dnpSaveAO32Config Sets the configuration of a DNP 32 bit analog output point dnpSaveAOSFConfig Sets the configuration of a DNP 32 bit short floating analog output point dnpSaveBl Config Sets the configuration of a DNP binary input point dnpSaveBOConfig Sets the configuration of a DNP binary output point dnpSaveC h16Config Sets the configuration of a DNP 16 bit counter input point dnpSaveCl32Config Sets the configuration of a DNP 32 bit counter input point dnpSaveConfiguration Defines DNP protocol configuration parameters dnpSaveConfigurationEx Writes the extended DNP configuration parameters dnpSendUnsolicitedResponse Sends an Unsolicited Response message in DNP protocol dnpSearchRoutingTable Searches the routing table for a specific DNP address dnpStationStatus Returns the DNP message statistics for a remote DNP station dnpWriteAddressMappingTableEntry Writes an entry in the DNP address mapping table dnpWriteMasterApplicationLayerConfig Writes DNP Master application layer configuration dnpWriteMasterPollTableEntry Writes an entry in the DNP master poll table dnpWriteRoutingTableEntry Writes an entry in the DNP routing table dnpWriteRoutingTableEntryEx Writes an extended entry in the DNP routing table dnpWriteRoutingTableEntry_DialString Writes a primary and secondary dial string into an entry in the DNP routin Document
546. vent indicates activity on com3 receiver The meaning depends on the character handler installed COUNTER_CHANNELS Specifies number of 5000 counter input channels Document Version 1 70 5 23 2012 573 Macro Definitions COUNTER_END Number of last counter input channel COUNTER_START Number of first counter input channel supported second Variable name control register CRC_16 CRC 16 type CRC checksum reverse algorithm CRC_CCITT CCITT type CRC checksum reverse algorithm Macro DATA_SIZE Maximum length of the HART command or response field DATA7 Specifies 7 bit world length DATA8 Specifies 8 bit word length Variable name deadband DB_BADSIZE Error code out of range address specified DB _BADTYPE Error code bad database addressing type specified registers DCAT_C Device configuration application type is a C application DCAT_LOGIC1 Device configuration application type is the first logic application DCAT_LOGIC2 Device configuration application type is the second logic application DE_BadContfig The modem configuration structure contains an error DE_BusyLine The phone number called was busy DE_CallAborted A call in progress was aborted by the user DE_CarrierLost The connection to the remote site was lost modem reported NO CARRIER Carrier is lost for a time exceeding the S10 setting in the modem Phone lines with call waiting are very susceptible to this condition Document Version
547. ves the slave command message Valid interface types are 1 com1 2 com2 3 com3 4 com4 100 Etherneti Document Version 1 70 5 23 2012 628 Structures and Types slaveStation is the station address used in the slave command message Valid address range is 0 to 255 in standard Modbus 0 to 65534 in extended Modbus 65535 entry cleared This station address must be different from the station address assigned to the slavelnterface forwardInterface is the communication interface from which to forward the command message as master Valid interface types are 1 com1 2 com2 3 com3 4 com4 100 Modbus TCP network 101 Modbus RTU over UDP network 102 Modbus ASCII over UDP network forwardStation is the station address of the remote slave device to forward the command message to Valid address range is 0 to 255 in standard Modbus 0 to 65534 in extended Modbus 65535 entry cleared This station address must be different from the station address assigned to the forwardInterface forward PAddress is the IP address of the remote slave device to forward a Modbus IP command message to Set to zero if not applicable SF_TRANSLATION_EX The SF_TRANSLATION_EX structure contains Store and Forward Messaging translation information This is used to define an address and port translation with a timeout typedef struct st_SFTranslationEx COM INTERFACE slavelInterface slave
548. was successful and FALSE if an error occurred Document Version 1 70 5 23 2012 121 Function Specifications Register Mapping The Device configuration is stored in Modbus input 8xxxx registers as shown below The registers are read with standard Modbus commands These registers cannot be written to Device configuration registers used fixed addresses This facilitates identifying the applications in a standard manner The Device configuration registers can be enabled or disabled by entering a 0 or 1 in the Start Register They are disabled until enabled by a logic application This provides compatibility with controllers that have already used these registers for other purposes The application IDs are cleared on every controller reset Applications need to run and set the application ID for it to be valid These data types are used Unsigned 16 bit integer Unsigned 8 bit character type n n element array of specified data type The following information is stored in the device configuration 2 logic application identifiers are provided for compatibility with SCADAPack ES ER controllers that provide 2 IEC 61131 1 applications The second logic application identifier is not used with other controllers 32 application identifiers are provided to accommodate C applications in SCADAPack 330 350 controllers These registers cannot be used for other purposes in logic or C C application This includes the following uses
549. wing values if multiple values are used they should be ORed together CLASSO_FLAG enables Class 0 Unsolicited Responses CLASS1_FLAG enables Class 1 Unsolicited Responses CLASS2_FLAG enables Class 2 Unsolicited Responses CLASS3_FLAG enables Class 3 Unsolicited Responses The function returns TRUE if the DNP unsolicited resoonse message was successfully triggered It returns FALSE if any of the configured master addresses has not been configured in the DNP Routing Table or the DNP configuration has not been created Notes DNP needs to be enabled before calling this function in order to create the DNP configuration If no events are pending an empty unsolicited message will be sent Example See the example program DNP Configuration Document Version 1 70 5 23 2012 219 Function Specifications dnpSearchRoutingTable Search Routing Table Syntax include lt ctools h gt BOOLEAN dnpSearchRoutingTable UINT16 Address routingTable pRoute 1 Description This function searches the routing table for a specific DNP address pRoute is a pointer to a table entry it is written by this function The return value is TRUE if pRoute was successfully written or FALSE otherwise Notes DNP needs to be enabled before calling this function in order to create the DNP configuration Document Version 1 70 5 23 2012 220 Function Specifications dnpStationStatus Get communication status for a remote DNP stati
550. with controller settings request resource FLASH MEMORY flashSettingsSave CS PER ANENT release resource FLASH MEMORY Document Version 1 70 5 23 2012 102 Function Specifications alarmin Determine Alarm Time from Elapsed Time Syntax include lt ctools h gt ALARM SETTING alarmIn UINT16 hours UINT16 minutes UINT16 seconds Description The alarmin function calculates the alarm settings to configure a real time clock alarm to occur in hours minutes and seconds from the current time The function returns an ALARM_SETTING structure suitable for passing to the setClockAlarm function The structure specifies an absolute time alarm at the time offset specified by the call to alarmin Refer to the Structures and Types section for a description of the fields in the ALARM_SETTING structure Notes If second is greater than 60 seconds the additional time is rolled into the minutes If minute is greater than 60 minutes the additional time is rolled into the hours If the offset time is greater that one day then the alarm time will roll over within the current day The IO_SYSTEM resource needs to to be requested before calling this function See Also setClockAlarm Document Version 1 70 5 23 2012 103 Function Specifications allocate_envelope Obtain an Envelope from the RTOS Syntax include lt ctools h gt envelope allocate_envelope void Description T
551. x include lt ctools h gt BOOLEAN serialModbusMaster MASTER MESSAGE message MODBUS_ SESSION session Description The serialModbusMaster function sends a command on a serial port using a Modbus protocol The Modbus protocol task waits for the response from the slave station The current task continues execution e message points to a MASTER_MESSAGE structure defining the message parameters and serial port to use MASTER_MESSAGE is described in the Structures and Types section e session points to a MODBUS_ SESSION structure This structure is used by the Modbus protocol task Declare the MODBUS_SESSION structure as a static modular or global variable A local variable or dynamically allocated variable may not be used because a late command response received after the variable is freed will write data over the freed variable space The serialModbusMaster function returns TRUE if a valid message has been queued for transmission The function returns FALSE if the message definition is invalid or the transmission queue is full Refer to the session gt masterCmdStatus field for an error code Error codes are described in the Structures and Types section for the enum MODBUS_CMD_STATUS The calling task monitors the status of the command sent using the session gt masterCmdStatus field The masterCmdStatus field is set to MM_SENT if a master message is sent It will be set to MM_RECEIVED when the response to the m
552. ximately 1 2 of a second indicates a binary one The least significant digit is output first As few bits as possible are displayed all leading zeros are ignored There is a two second delay between repetitions The STAT LED is located on the top left hand corner of the controller board Bits 0 1 and 2 of the status code are used by the controller firmware Attempting to control these bits will result in indeterminate operation Bit 0 Module Failure Bit 1 Register Assignment Checksum Failure Bit 2 IO Queue Full Bit 3 Reduced Power Mode SCADAPack 4203 only See Also setStatusBit getStatusBit Document Version 1 70 5 23 2012 117 Function Specifications clear_tx Clear Serial Port Transmit Buffer Syntax include lt ctools h gt void clear tx FILE stream Description The clear_tx function clears the transmit buffer for the serial port specified by port f portis not a valid serial port the function has no effect Document Version 1 70 5 23 2012 118 Function Specifications close Syntax include lt ctools h gt int close int socketDescriptor 1 Description This function is used to close a socket Parameters socketDescriptor The socket descriptor to close Returns 0 Operation completed successfully 1 An error occurred close can fail for the following reasons TM_EBADF _ The socket descriptor is invalid TM_ESHUTDOWN A write shutdown has already been performed
553. xit handler Use modemAbort instead Document Version 1 70 5 23 2012 423 Function Specifications modemDialStatus Return Status of Dial up Connection Syntax include lt ctools h gt void modemDialStatus FILE port reserve id id enum DialError error enum DialState state Description The modemDialStatus function returns the status of a remote connection initiated by the modemDial function port specifies the serial port where the modem is installed id is the port reservation identifier returned by the modemDial function The function sets the variable pointed to by error If no error occurred DE_NoError is returned Any other value indicates an error Refer to the Structures and Types section for a complete Description of error codes The function sets the variable pointed to by state to the current execution state of dialing operation The state value is not valid if the error code is DE_NotInControl Refer to the dialup h section for a complete Description of state codes Notes The serial port type must be set to RS232_MODEM The reservation identifier is valid until the call is terminated and another modem function or an incoming call takes control of the port The modemDialStatus function will return a DE_NotInControl error code if another dial function or incoming call is now in control of the port Do not call this function in a task exit handler Document Version 1 70 5 23 2012 424 Fun
554. xtended Addressing Configuration Syntax include lt ctools h gt BOOLEAN setProtocolSettings FILE stream PROTOCOL SETTINGS settings 1 Description The setProtocolSettings function sets protocol parameters for a serial port This function supports extended addressing The function has two arguments port is one of com1 com2 or com3 and settings a pointer to a PROTOCOL_SETTINGS structure Refer to the Description of the structure for an explanation of the parameters The function returns TRUE if the settings were changed It returns FALSE if the stream is not valid or if the protocol does not start The lO_SYSTEM resource must be requested before calling this function To save these settings with the controller settings in flash memory so that they are loaded on controller reset call flashSettingsSave as shown below request_resource FLASH_MEMORY flashSettingsSave CS_RUN release_resource FLASH_MEMORY Notes Setting the protocol type to NO PROTOCOL ends the protocol task and frees the stack resources allocated to it Add a call to modemNotification when writing a custom protocol Extended addressing is available on the Modbus RTU and Modbus ASCII protocols only See the TeleBUS Protocols User Manual for details Example This code fragment sets protocol parameters for the com2 serial port include lt ctools h gt PROTOCOL SETTINGS settings settings type MODBUS_RTU settings s
555. y d r n settings priority Document Version 1 70 5 23 2012 262 Function Specifications getProtocolSettings Get Protocol Extended Addressing Configuration Syntax include lt ctools h gt BOOLEAN getProtocolSettings FILE stream PROTOCOL SETTINGS settings 1 Description The getProtocolSeitings function reads the protocol parameters for a serial port This function supports extended addressing The function has two parameters portis one of com1 com2 or com3 and settings a pointer to a PROTOCOL_SETTINGS structure Refer to the Description of the structure for an explanation of the parameters The function returns TRUE if the structure was changed It returns FALSE if the stream is not valid Notes Extended addressing is available on the Modbus RTU and Modbus ASCII protocols only See the TeleBUS Protocols User Manual for details Refer to the TeleBUS Protocols User Manual section for detailed information on communication protocols See Also setProtocolSettings get_protocol Example This program displays the protocol configuration for com1 include lt ctools h gt int main void PROTOCOL SETTINGS settings if getProtocolSettings coml amp settings fprintf fprintf com1 Type d r n settings type com1 Station d r n settings station fprintf com1 Address Mode d r n settings mode fprintf com1 SF Messaging d r n settings SFMessaging
556. y tertiary and fourth variables If the device does not support a variable zero is written into the value and units code for that variable The code field of both HART_VARIABLE structures is not changed The response from the HART device to command 3 does not include variable codes The units field of variable 0 is set to 39 units mA The response from the HART device to command 3 does not include units See Also hartCommand33 hartStatus hartSetConfiguration Document Version 1 70 5 23 2012 290 Function Specifications hartCommand11 Read Unique Identifier Associated with Tag Syntax include lt ctools h gt BOOLEAN hartCommand11 UINT16 module char deviceTag HART DEVICE device Description This function reads the unique identifier of a HART device using command 11 This is a link initialization function The function has three parameters the module number of the 5904 module 0 to 3 a pointer to a null terminated string containing the tag of the HART device and a pointer to a HART_DEVICE structure The information read by command 11 is written into the HART _DEVICE structure when the response is received by the 5904 interface The function returns TRUE if the command was sent The function returns FALSE if the module number is invalid Notes The function returns immediately after the command is sent The calling program needs to wait for the response to be received Use the hartStatu
557. y stream If stream does not point to a valid serial port the function has no effect and FALSE is returned otherwise TRUE is returned The getPortCharacteristics function copies the serial port characteristics into the structure pointed to by pCharacteristics Notes Refer to the Overview of Functions section for detailed information on serial ports Refer to the Structures and Types section for a Description of the fields in the PORT_CHARACTERISTICS structure See Also get_port Example include lt ctools h gt int main void PORT CHARACTERISTICS options getPortCharacteristics com3 amp options fprintf coml Dataflow options d r n options dataflow fprintf coml Protocol options d r n options protocol Document Version 1 70 5 23 2012 258 Function Specifications get_port Get Serial Port Configuration Syntax include lt ctools h gt struct pconfig get_port FILE stream struct pconfig settings Description The get_port function gets the serial port configuration for the port If portis not a valid serial port the function has no effect The get_port function copies the serial port settings into the structure pointed to by settings and returns a pointer to the structure Notes Refer to the Overview of Functions section for detailed information on serial ports Refer to the Structure and Types section for a Description of the fields in the pconfig structure See
558. y that go far beyond conventional communications protocols Among its robust and flexible features DNP 3 0 includes e Output options e Addressing for over 65 000 devices on a single link Document Version 1 70 5 23 2012 75 Overview of Programming Functions e Time synchronization and time stamped events e Broadcast messages e Data link and application layer confirmation DNP 3 0 was originally designed based on three layers of the OSI seven layer model application layer data link layer and physical layer The application layer is object based with objects provided for generic data formats The data link layer provides for several methods of retrieving data such as polling for classes and object variations The physical layer defines commonly a simple RS 232 or RS 485 interface DNP Communication Protocol Functions There are several library functions related to DNP communication protocol Refer to the Function Specification section for details on each function listed dnpClearEventLogs Deletes change events from the DNP change event buffers dnpConnectionEvent Report a DNP connection event dnpCreateAddressMappingTable Allocates memory for a new address mapping table according to the size parameter dnpCreateMasterPollTable Allocates memory for a new table according to the size parameter dnpCreateRoutingTable Allocates memory for a new routing table according to the size parameter dnpGenerateCh
559. ype This structure defines the data log configuration It is used with the dlogCreate function typedef struct dlogConfiguration type CHAR configVersion OOLEAN fileRingBuffer INT32 bufferFlushInterval INT32 bufferRecordSize INT32 fileMode INT32 numFiles I I 1 I E NT32 fileRecordSize NT32 numRecordElements ogRecordElement recordList NT32 securityToken HAR description 255 UCHAR logName 255 dlogConfiguration E ei E et ee beh e o U U configVersion is the version of the configuration structure Always set this to 1 fileRingBuffer specifies if the oldest file is deleted when a new file would exceed the maximum number of files Set to TRUE to delete the oldest file Set to FALSE to stop writing to files and halt buffer flushing when the last file is full bufferFlushInterval is the interval in seconds at which the data log server will flush the buffer to file Valid values are any value greater than 0 bufferRecordSize is the number of records in the data log buffer fileMode selects where the data log files are stored Valid values are O internal flash drive 1 internal drive with auto copy to external drive 2 internal drive with auto move to external drive 3 external drive numFiles is the maximum number of log files Valid values are any value greater than 0 fileRecordSize is the number of records in the each data log file Valid values are any value gr

SCADAPack3xx C++ Tools User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents