SCADAPack 32 C++ Tools User and Reference Manual 10/26/2012 Safety Information 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 Schneider 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. © 2012 Schneider Electric. All rights reserved. Document (Version 2.22) 10/26/2012 2 Safety Information Table of Contents Safety Information .......................................................................16 About The Book ...........................................................................19 At a Glance .......................................................................................................... 19 Overview .......................................................................................20 Technical Support ................................................................................................ 20 Getting Started .............................................................................21 SCADAPack 32 C++ Tools Installation Overview................................................ 21 Program Development Tutorial ............................................................................ 22 C++ Program Development .........................................................33 Program Architecture ........................................................................................... 33 Application Development ..................................................................................... 37 Debugging a C++ Application .............................................................................. 47 Managing Projects ............................................................................................... 49 Real Time Operating System ......................................................51 Task Management ............................................................................................... 51 Resource Management ........................................................................................ 52 IO_SYSTEM Resource ........................................................................................ 53 DYNAMIC_MEMORY Resource .......................................................................... 53 MODBUS_PARSER Resource ............................................................................ 53 Inter-task Communication .................................................................................... 53 Event Notification ................................................................................................. 54 Error Reporting..................................................................................................... 55 RTOS Example Application Program................................................................... 55 Overview of Programming Functions ........................................64 Controller Operation ............................................................................................. 64 Controller I/O Hardware ....................................................................................... 66 Serial Communication .......................................................................................... 74 Serial Communication Protocols .......................................................................... 77 DNP Communication Protocol ............................................................................. 79 PPP Communication Protocol .............................................................................. 83 DF1 Communication Protocol .............................................................................. 83 TCP/IP Communications ...................................................................................... 84 Document (Version 2.22) 10/26/2012 3 Safety Information Modbus IP Protocol .............................................................................................. 84 Sockets API .......................................................................................................... 85 Modbus I/O Database .......................................................................................... 86 Register Assignment ............................................................................................ 88 IEC 61131-3 Variable Access Functions ............................................................. 89 HART Communication ......................................................................................... 89 Function Specifications ..............................................................92 accept ................................................................................................................... 93 addRegAssignment .............................................................................................. 95 addRegAssignmentEx ......................................................................................... 98 alarmIn ............................................................................................................... 103 allocate_envelope .............................................................................................. 104 allocateMemory .................................................................................................. 105 bind .................................................................................................................... 106 check_error ........................................................................................................ 107 checksum ........................................................................................................... 108 checkSFTranslationTable .................................................................................. 109 clearAllForcing ................................................................................................... 110 clearBreakCondition ........................................................................................... 111 clear_errors ........................................................................................................ 112 clear_protocol_status ......................................................................................... 113 clearRegAssignment .......................................................................................... 114 clearSFTranslationTable .................................................................................... 115 clearStatusBit ..................................................................................................... 116 clear_tx ............................................................................................................... 117 configurationRegisterMapping ........................................................................... 118 configurationSetApplicationID ............................................................................ 119 connect ............................................................................................................... 123 crc_reverse ........................................................................................................ 125 create_task ......................................................................................................... 126 databaseRead .................................................................................................... 128 databaseWrite .................................................................................................... 129 datalogCreate..................................................................................................... 130 datalogDelete ..................................................................................................... 132 datalogPurge ...................................................................................................... 134 datalogReadNext ............................................................................................... 136 datalogReadStart ............................................................................................... 138 datalogRecordSize ............................................................................................. 140 datalogSettings .................................................................................................. 141 datalogWrite ....................................................................................................... 142 dbase ................................................................................................................. 143 Dbase Handler Function .................................................................................... 145 deallocate_envelope .......................................................................................... 146 dnpClearEventLogs............................................................................................ 147 dnpConnectionEvent .......................................................................................... 148 dnpCreateAddressMapTable ............................................................................. 149 dnpCreateMasterPollTable ................................................................................ 150 dnpCreateRoutingTable ..................................................................................... 151 Document (Version 2.22) 10/26/2012 4 Safety Information dnpGenerateChangeEvent ................................................................................ 152 dnpGenerateEventLog ....................................................................................... 153 dnpGetAI16Config.............................................................................................. 154 dnpGetAI32Config.............................................................................................. 155 dnpGetAISFConfig ............................................................................................. 156 dnpGetAO16Config ............................................................................................ 157 dnpGetAO32Config ............................................................................................ 158 dnpGetAOSFConfig ........................................................................................... 159 dnpGetBIConfig.................................................................................................. 160 dnpGetBIConfigEx ............................................................................................. 161 dnpGetBOConfig ................................................................................................ 162 dnpGetCI16Config ............................................................................................. 163 dnpGetCI32Config ............................................................................................. 164 dnpGetConfiguration .......................................................................................... 165 dnpGetConfigurationEx ...................................................................................... 169 dnpGetRuntimeStatus ........................................................................................ 170 dnpGetUnsolicitedBackoffTime.......................................................................... 171 dnpInstallConnectionHandler ............................................................................. 172 dnpMasterClassPoll ........................................................................................... 177 dnpMasterClockSync ......................................................................................... 178 dnpPortStatus .................................................................................................... 179 dnpReadAddressMappingTableEntry ................................................................ 180 dnpReadAddressMappingTableSize ................................................................. 181 dnpReadMasterPollTableEntry .......................................................................... 182 dnpReadMasterPollTableEntryEx ...................................................................... 183 dnpReadMasterPollTableSize ........................................................................... 184 dnpReadRoutingTableEntry_DialStrings ........................................................... 185 dnpReadRoutingTableEntry ............................................................................... 186 dnpReadRoutingTableEntryEx .......................................................................... 187 dnpReadRoutingTableSize ................................................................................ 188 dnpSaveAI16Config ........................................................................................... 189 dnpSaveAI32Config ........................................................................................... 190 dnpSaveAISFConfig........................................................................................... 191 dnpSaveAO16Config ......................................................................................... 192 dnpSaveAO32Config ......................................................................................... 193 dnpSaveAOSFConfig ......................................................................................... 194 dnpSaveBIConfig ............................................................................................... 195 dnpSaveBIConfigEx ........................................................................................... 196 dnpSaveBOConfig ............................................................................................. 197 dnpSaveCI16Config ........................................................................................... 198 dnpSaveCI32Config ........................................................................................... 199 dnpSaveConfiguration ....................................................................................... 200 dnpSaveConfigurationEx ................................................................................... 202 dnpSaveUnsolicitedBackoffTime ....................................................................... 203 dnpSendUnsolicitedResponse ........................................................................... 204 dnpSearchRoutingTable .................................................................................... 205 dnpStationStatus ................................................................................................ 206 dnpWriteAddressMappingTableEntry ................................................................ 207 dnpWriteMasterApplicationLayerConfig............................................................. 208 dnpWriteMasterPollTableEntry .......................................................................... 209 Document (Version 2.22) 10/26/2012 5 Safety Information dnpWriteMasterPollTableEntryEx ...................................................................... 210 dnpWriteRoutingTableEntry_DialStrings ........................................................... 211 dnpWriteRoutingTableEntry ............................................................................... 212 dnpWriteRoutingTableEntryEx ........................................................................... 213 end_application .................................................................................................. 214 end_task ............................................................................................................. 215 endTimedEvent .................................................................................................. 216 enronInstallCommandHandler ........................................................................... 217 ethernetGetIP ..................................................................................................... 221 ethernetGetMACAddress ................................................................................... 222 ethernetSetIP ..................................................................................................... 223 executeConstructors .......................................................................................... 224 executeDestructors ............................................................................................ 225 flashSettingsLoad............................................................................................... 226 flashSettingsSave .............................................................................................. 227 forceLed ............................................................................................................. 228 freeMemory ........................................................................................................ 229 getABConfiguration ............................................................................................ 230 getclock .............................................................................................................. 231 getClockAlarm .................................................................................................... 232 getClockTime ..................................................................................................... 233 getControllerID ................................................................................................... 234 getForceFlag ...................................................................................................... 235 getForceLed ....................................................................................................... 237 getIOErrorIndication ........................................................................................... 238 getOutputsInStopMode ...................................................................................... 239 getpeername ...................................................................................................... 240 getPortCharacteristics ........................................................................................ 241 get_port .............................................................................................................. 242 getProgramStatus .............................................................................................. 243 get_protocol ....................................................................................................... 244 getProtocolSettings ............................................................................................ 245 getProtocolSettingsEx ........................................................................................ 246 get_protocol_status ............................................................................................ 248 getSFTranslation ................................................................................................ 249 getSFTranslationEx............................................................................................ 250 getsockname ...................................................................................................... 251 getsockopt .......................................................................................................... 252 get_status ........................................................................................................... 259 getStatusBit ........................................................................................................ 260 getTaskInfo ........................................................................................................ 261 getVersion .......................................................................................................... 262 Handler Function ................................................................................................ 263 hartIO ................................................................................................................. 266 hartCommand .................................................................................................... 267 hartCommand0 .................................................................................................. 269 hartCommand1 .................................................................................................. 270 hartCommand2 .................................................................................................. 271 hartCommand3 .................................................................................................. 272 hartCommand11 ................................................................................................ 274 Document (Version 2.22) 10/26/2012 6 Safety Information hartCommand33 ................................................................................................ 275 hartStatus ........................................................................................................... 277 hartGetConfiguration .......................................................................................... 279 hartSetConfiguration .......................................................................................... 280 hartPackString.................................................................................................... 281 hartUnpackString ............................................................................................... 282 htonl ................................................................................................................... 283 htons .................................................................................................................. 284 inet_addr ............................................................................................................ 285 inet_aton ............................................................................................................ 286 initializeApplicationVariables .............................................................................. 287 install_handler .................................................................................................... 288 installClockHandler ............................................................................................ 289 installDbaseHandler ........................................................................................... 290 installSetdbaseHandler ...................................................................................... 291 installExitHandler ............................................................................................... 292 installModbusHandler......................................................................................... 293 installRTCHandler .............................................................................................. 294 RTCHandler Function ........................................................................................ 295 interrupt_signal_event ........................................................................................ 296 interval ................................................................................................................ 297 ioClear ................................................................................................................ 298 ioDatabaseReset................................................................................................ 299 ioGetConfiguration ............................................................................................. 301 ioNotification ....................................................................................................... 302 ioRead5414Inputs .............................................................................................. 303 ioRead5415Inputs .............................................................................................. 304 ioRead5415Outputs ........................................................................................... 305 ioRead5505Inputs .............................................................................................. 306 ioRead5505Outputs ........................................................................................... 309 ioRead5506Inputs .............................................................................................. 311 ioRead5506Outputs ........................................................................................... 313 ioRead5601Inputs .............................................................................................. 315 ioRead5601Outputs ........................................................................................... 316 ioRead5604Inputs .............................................................................................. 317 ioRead5604Outputs ........................................................................................... 318 ioRead5606Inputs .............................................................................................. 319 ioRead5606Outputs ........................................................................................... 321 ioReadAin4 ......................................................................................................... 324 ioReadAin8 ......................................................................................................... 325 ioReadAout2 ...................................................................................................... 326 ioReadAout4 ...................................................................................................... 327 ioReadAout5303 ................................................................................................ 328 ioReadCounter4 ................................................................................................. 329 ioReadCounter5232 ........................................................................................... 330 ioReadDin16 ...................................................................................................... 331 ioReadDin32 ...................................................................................................... 332 ioReadDin5232 .................................................................................................. 334 ioReadDin8 ........................................................................................................ 335 ioReadDout16 .................................................................................................... 336 Document (Version 2.22) 10/26/2012 7 Safety Information ioReadDout32 .................................................................................................... 337 ioReadDout8 ...................................................................................................... 338 IoRequest ........................................................................................................... 339 ioSetConfiguration.............................................................................................. 341 ioStatus .............................................................................................................. 342 ioSystemReset ................................................................................................... 344 ioVersion ............................................................................................................ 345 ioWrite5414Outputs ........................................................................................... 346 ioWrite5415Outputs ........................................................................................... 347 ioWrite5505Outputs ........................................................................................... 348 ioWrite5506Outputs ........................................................................................... 350 ioWrite5601Outputs ........................................................................................... 352 ioWrite5604Outputs ........................................................................................... 353 ioWrite5606Outputs ........................................................................................... 354 ioWriteAout2 ....................................................................................................... 357 ioWriteAout4 ....................................................................................................... 358 ioWriteAout5303................................................................................................. 359 ioWriteDout16 .................................................................................................... 360 ioWriteDout32 .................................................................................................... 361 ioWriteDout8 ...................................................................................................... 362 ipFindFriendlyIPAddress .................................................................................... 363 ipGetConnectionSummary ................................................................................. 364 ipGetInterfaceType............................................................................................. 365 ipInitializeFriendlyIPSettings .............................................................................. 366 ipReadFriendlyListControl .................................................................................. 367 ipReadFriendlyIPListEntry ................................................................................. 368 ipReadFriendlyIPListSize ................................................................................... 369 ipWriteFriendlyListControl .................................................................................. 370 ipWriteFriendlyIPListEntry .................................................................................. 371 ipWriteFriendlyIPListSize ................................................................................... 372 ledGetDefault ..................................................................................................... 373 ledPower ............................................................................................................ 374 ledPowerSwitch.................................................................................................. 375 ledSetDefault ...................................................................................................... 376 listen ................................................................................................................... 377 master_message................................................................................................ 378 modbusExceptionStatus .................................................................................... 380 modbusSlaveID .................................................................................................. 381 modemAbort....................................................................................................... 382 modemAbortAll................................................................................................... 383 modemDial ......................................................................................................... 385 modemDialEnd................................................................................................... 387 modemDialStatus ............................................................................................... 388 modemInit .......................................................................................................... 389 modemInitEnd .................................................................................................... 391 modemInitStatus ................................................................................................ 392 modemNotification ............................................................................................. 393 mTcpGetConfig .................................................................................................. 394 mTcpGetInterface .............................................................................................. 395 mTcpGetInterfaceEx .......................................................................................... 396 Document (Version 2.22) 10/26/2012 8 Safety Information mTcpGetProtocol ............................................................................................... 397 mTcpSetConfig .................................................................................................. 398 mTcpSetInterface ............................................................................................... 399 mTcpSetInterfaceEx........................................................................................... 400 mTcpSetProtocol................................................................................................ 401 mTcpMasterClose .............................................................................................. 402 mTcpMasterDisconnect ..................................................................................... 403 mTcpMasterMessage......................................................................................... 404 mTcpMasterOpen .............................................................................................. 406 mTcpMasterStatus ............................................................................................. 408 mTcpRunServer ................................................................................................. 409 ntohl ................................................................................................................... 410 ntohs .................................................................................................................. 411 optionSwitch ....................................................................................................... 412 overrideDbase .................................................................................................... 413 pidExecute ......................................................................................................... 415 pidInitialize ......................................................................................................... 417 pollABSlave ........................................................................................................ 418 poll_event ........................................................................................................... 419 poll_message ..................................................................................................... 420 poll_resource...................................................................................................... 421 portIndex ............................................................................................................ 422 portStream ......................................................................................................... 423 pppGetInterfaceHandle ...................................................................................... 424 pppReadSettings................................................................................................ 425 pppReadUserTableEntry ................................................................................... 426 pppReadUserTableSize ..................................................................................... 427 pppWriteSettings ................................................................................................ 428 pppWriteUserTableEntry .................................................................................... 430 pppWriteUserTableSize ..................................................................................... 431 queue_mode ...................................................................................................... 432 readBoolVariable................................................................................................ 433 readBattery......................................................................................................... 435 readIntVariable ................................................................................................... 436 readMsgVariable ................................................................................................ 438 readRealVariable ............................................................................................... 440 readStopwatch ................................................................................................... 442 readThermistor ................................................................................................... 443 readTimerVariable.............................................................................................. 444 read_timer_info .................................................................................................. 446 readv .................................................................................................................. 447 receive_message ............................................................................................... 449 recv..................................................................................................................... 450 recvfrom ............................................................................................................. 453 release_processor.............................................................................................. 455 release_resource ............................................................................................... 456 report_error ........................................................................................................ 457 request_resource ............................................................................................... 458 resetAllABSlaves................................................................................................ 459 resetClockAlarm ................................................................................................. 460 Document (Version 2.22) 10/26/2012 9 Safety Information route ................................................................................................................... 461 rresvport ............................................................................................................. 462 runBackgroundIO ............................................................................................... 463 runIOSystem ...................................................................................................... 464 runLed ................................................................................................................ 465 runMasterIpStartTask......................................................................................... 466 runTarget ............................................................................................................ 467 runTimers ........................................................................................................... 468 select .................................................................................................................. 469 send ................................................................................................................... 471 send_message ................................................................................................... 474 sendto ................................................................................................................ 476 serialModbusMaster ........................................................................................... 478 setABConfiguration ............................................................................................ 480 setBreakCondition .............................................................................................. 481 setclock .............................................................................................................. 482 setClockAlarm .................................................................................................... 483 setdbase ............................................................................................................. 484 Setdbase Handler Function ............................................................................... 486 setDTR ............................................................................................................... 487 setForceFlag ...................................................................................................... 488 setIOErrorIndication ........................................................................................... 490 setOutputsInStopMode ...................................................................................... 491 set_port .............................................................................................................. 492 setProgramStatus .............................................................................................. 494 set_protocol ........................................................................................................ 495 setProtocolSettings ............................................................................................ 496 setProtocolSettingsEx ........................................................................................ 498 setSFTranslation ................................................................................................ 500 setSFTranslationEx ............................................................................................ 503 setsockopt .......................................................................................................... 506 setStatusBit ........................................................................................................ 514 setStatusMode ................................................................................................... 515 settimer .............................................................................................................. 516 shutdown ............................................................................................................ 517 signal_event ....................................................................................................... 518 socket ................................................................................................................. 520 start_protocol ..................................................................................................... 522 startup_task ........................................................................................................ 523 startTimedEvent ................................................................................................. 524 tfBindNoCheck ................................................................................................... 525 tfBlockingState ................................................................................................... 526 tfClose ................................................................................................................ 527 tfDialerAddExpectSend ...................................................................................... 528 tfDialerAddSendExpect ...................................................................................... 530 tfFreeZeroCopyBuffer ........................................................................................ 532 tfGetPppDnsIpAddress ...................................................................................... 533 tfGetPppPeerlpAddress ..................................................................................... 534 tfGetOobDataOffset ........................................................................................... 535 tfGetSendCompltBytes ...................................................................................... 536 Document (Version 2.22) 10/26/2012 10 Safety Information tfGetSocketError ................................................................................................ 537 tfGetWaitingBytes .............................................................................................. 538 tfGetZeroCopyBuffer .......................................................................................... 539 tfInetToAscii ....................................................................................................... 540 tfIoctl ................................................................................................................... 541 tfPingClose ......................................................................................................... 543 tfPingGetStatistics .............................................................................................. 544 tfPingOpenStart.................................................................................................. 546 tfPppSetOption ................................................................................................... 548 tfRead ................................................................................................................. 552 tfRegisterSocketCB ............................................................................................ 553 tfRegisterSocketCBParam ................................................................................. 556 tfResetConnection.............................................................................................. 558 tfSendToInterface............................................................................................... 559 tfSetPppPeerIpAddress ..................................................................................... 561 tfSocketArrayWalk.............................................................................................. 562 tfUseDialer ......................................................................................................... 563 tfWrite ................................................................................................................. 564 tfZeroCopyRecv ................................................................................................. 565 tfZeroCopySend ................................................................................................. 567 timer ................................................................................................................... 569 timeoutCancel .................................................................................................... 570 timeoutRequest .................................................................................................. 571 wait_event .......................................................................................................... 574 wd_auto .............................................................................................................. 575 wd_enabled ........................................................................................................ 576 wd_manual ......................................................................................................... 577 wd_pulse ............................................................................................................ 578 writeBoolVariable ............................................................................................... 579 writeIntVariable .................................................................................................. 580 writeRealVariable ............................................................................................... 581 writeMsgVariable................................................................................................ 582 writeTimerVariable ............................................................................................. 584 writev .................................................................................................................. 586 Macro Definitions .......................................................................588 A ......................................................................................................................... 588 B ......................................................................................................................... 588 C ......................................................................................................................... 589 D ......................................................................................................................... 590 E ......................................................................................................................... 592 F ......................................................................................................................... 592 G......................................................................................................................... 592 H ......................................................................................................................... 592 I .......................................................................................................................... 593 L ......................................................................................................................... 593 M ........................................................................................................................ 593 N ......................................................................................................................... 595 O......................................................................................................................... 596 Document (Version 2.22) 10/26/2012 11 Safety Information P ......................................................................................................................... 596 R ......................................................................................................................... 596 S ......................................................................................................................... 597 T ......................................................................................................................... 598 V ......................................................................................................................... 599 W ........................................................................................................................ 599 Structures and Types ................................................................601 ABConfiguration ................................................................................................. 601 ADDRESS_MODE ............................................................................................. 601 ALARM_SETTING ............................................................................................. 601 COM_INTERFACE ............................................................................................ 602 CONNECTION_TYPE........................................................................................ 602 DATALOG_CONFIGURATION.......................................................................... 602 DATALOG_STATUS .......................................................................................... 603 DATALOG_VARIABLE ...................................................................................... 603 DialError ............................................................................................................. 603 DialState ............................................................................................................. 604 DNP_ADDRESS_MAP_TABLE ......................................................................... 604 dnpAnalogInput .................................................................................................. 605 DnpAnalogInputShortFloat ................................................................................. 605 dnpAnalogOutput ............................................................................................... 606 dnpBinaryInput ................................................................................................... 606 dnpBinaryInputEx ............................................................................................... 606 dnpBinaryOutput ................................................................................................ 606 dnpConnectionEventType .................................................................................. 607 dnpConfiguration ................................................................................................ 608 dnpConfigurationEx............................................................................................ 612 dnpCounterInput ................................................................................................ 617 dnpMasterPoll .................................................................................................... 617 DNP Master Poll table Extended Entry .............................................................. 618 dnpPointType ..................................................................................................... 619 dnpProtocolStatus .............................................................................................. 619 dnpRoutingTableEx............................................................................................ 620 DNP_RUNTIME_STATUS ................................................................................. 620 envelope ............................................................................................................. 621 HART_COMMAND ............................................................................................ 622 HART_DEVICE .................................................................................................. 622 HART_RESPONSE ........................................................................................... 623 HART_RESULT ................................................................................................. 623 HART_SETTINGS ............................................................................................. 623 HART_VARIABLE .............................................................................................. 624 IO_CONFIG Structure ........................................................................................ 624 IO_STATUS Structure........................................................................................ 625 IP_ADDRESS .................................................................................................... 625 IP_CONNECTION_SUMMARY ......................................................................... 625 IP_CONFIG_MODE Enumeration ..................................................................... 626 IP_PROTOCOL_SETTINGS ............................................................................. 626 IP_PROTOCOL_TYPE ...................................................................................... 627 Document (Version 2.22) 10/26/2012 12 Safety Information IP_SETTINGS .................................................................................................... 627 ledControl_tag .................................................................................................... 628 MASTER_MESSAGE ........................................................................................ 628 MODBUS_CMD_STATUS ................................................................................. 629 ModemInit .......................................................................................................... 631 ModemSetup ...................................................................................................... 631 MTCP_CONFIGURATION ................................................................................. 632 MTCP_IF_SETTINGS ........................................................................................ 632 MTCP_IF_SETTINGS_EX ................................................................................. 633 pconfig ................................................................................................................ 634 PID_DATA .......................................................................................................... 634 PPP_LOGIN_TYPE Enumeration ...................................................................... 636 PPP_SETTINGS Structure ................................................................................ 636 PROTOCOL_SETTINGS ................................................................................... 637 PROTOCOL_SETTINGS_EX Type ................................................................... 638 prot_settings ....................................................................................................... 638 prot_status ......................................................................................................... 639 PORT_CHARACTERISTICS ............................................................................. 640 pstatus ................................................................................................................ 640 READSTATUS ................................................................................................... 641 routingTable ....................................................................................................... 641 SF_TRANSLATION ........................................................................................... 642 SF_TRANSLATION_EX .................................................................................... 642 SFTranslationStatus........................................................................................... 643 sockaddr_in ........................................................................................................ 643 TASKINFO ......................................................................................................... 644 taskInfo_tag........................................................................................................ 645 TIME ................................................................................................................... 645 timer_info ........................................................................................................... 645 timeval ................................................................................................................ 646 VERSION ........................................................................................................... 646 WRITESTATUS ................................................................................................. 646 Example Programs ....................................................................647 Connecting with a Remote Controller Example ................................................. 647 Create Task Example......................................................................................... 649 DNP Configuration Example .............................................................................. 651 Get Program Status Example ............................................................................ 656 Get Task Status Example .................................................................................. 657 Handler Function Example ................................................................................. 659 Install Serial Port Handler Example ................................................................... 662 Install Clock Handler Example ........................................................................... 664 Install Database Handler Example..................................................................... 666 Memory Allocation Example .............................................................................. 671 Master Message Example Using Modbus Protocol ........................................... 673 Master Message Example Using DF1 Protocol ................................................. 676 Master Message Example Using serialModbusMaster...................................... 679 Master Message Example Using mTcpMasterMessage ................................... 685 Modem Initialization Example ............................................................................ 689 Document (Version 2.22) 10/26/2012 13 Safety Information Real Time Clock Program Example ................................................................... 690 Start Timed Event Example ............................................................................... 691 Timer Example Programs .................................................................................. 693 Porting Existing C Tools Applications .....................................695 Compiler Differences between Microtec Research and Hitachi ........................ 695 Add Existing Code to Framework ...................................................................... 695 Replace Older C Tools Headers with ctools.h ................................................... 696 Replace Partially Supported and Unsupported Functions ................................. 696 Build the Application........................................................................................... 696 Test the Application............................................................................................ 697 Partially Supported C Tools Functions ....................................698 I/O System Functions ......................................................................................... 698 Controller I/O Functions ..................................................................................... 699 IEC 61131-3 I/O Functions ................................................................................ 700 Backwards Compatibility I/O Functions ............................................................. 700 Other I/O Function Changes .............................................................................. 700 Jiffy Clock Functions .......................................................................................... 701 Real Time Clock Functions ................................................................................ 701 Get Task Information Function ........................................................................... 701 EEPROM/Flash Memory Functions ................................................................... 701 Controller Status Function ................................................................................. 702 Store and Forward Functions ............................................................................. 702 Non-Volatile Data Sections ................................................................................ 703 Serial Port Configuration Functions ................................................................... 703 Timers ................................................................................................................ 704 Alternative Methods for Timing .......................................................................... 705 Unsupported C Tools Functions ..............................................706 Application Checksum Function ......................................................................... 706 Sleep Functions ................................................................................................. 706 Backwards Compatibility Functions ................................................................... 706 5602 I/O Module Functions ................................................................................ 706 Boot Type Functions .......................................................................................... 707 I/O Bus Communication Functions .................................................................... 707 Document (Version 2.22) 10/26/2012 14 Safety Information Index of Figures Figure 1: Queue Status before Execution of main Task ............................... 59 Figure 2: Queue Status at Start of main Task................................................ 60 Figure 3: Queue Status after Creation of echoData Task ............................. 60 Figure 4: Queue Status After echoData Task Waits for Event...................... 61 Figure 5: Queue Status after Creation of auxiliary Task ............................... 61 Figure 6: Queue Status After main Task Releases Processor ..................... 61 Figure 7: Queue Status at Start of auxiliary Task.......................................... 62 Figure 8: Queue Status after Character Received ......................................... 62 Figure 9: Queue Status after echoData Waits for Event ............................... 63 Document (Version 2.22) 10/26/2012 15 Safety Information 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. DANGER DANGER indicates an imminently hazardous situation which, if not avoided, will result in death or serious injury. WARNING WARNING indicates a potentially hazardous situation which, if not avoided, can result in death or serious injury. CAUTION CAUTION indicates a potentially hazardous situation which, if not avoided, can result in minor or moderate. CAUTION CAUTION used without the safety alert symbol, indicates a potentially hazardous situation which, if not avoided, can result in equipment damage.. Document (Version 2.22) 10/26/2012 16 Safety Information 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. 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. CAUTION UNINTENDED EQUIPMENT OPERATION • Verify that all installation and set up procedures have been completed. • Before operational tests are performed, remove all blocks or other temporary holding means used for shipment from all component devices. • 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 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: • Remove tools, meters, and debris from equipment. • Close the equipment enclosure door. • Remove ground from incoming power lines. • Perform all start-up tests recommended by the manufacturer. OPERATION AND ADJUSTMENTS The following precautions are from the NEMA Standards Publication ICS 7.11995 (English version prevails): Document (Version 2.22) 10/26/2012 17 Safety Information • 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. • It is sometimes possible to misadjust the equipment and thus produce unsatisfactory or unsafe operation. Always use the manufacturer’s 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. • Only those operational adjustments actually required by the operator should be accessible to the operator. Access to other controls should be restricted to prevent unauthorized changes in operating characteristics. Document (Version 2.22) 10/26/2012 18 About The Book About The Book At a Glance Document Scope This manual describes the use of the SCADAPack 32 C++ Tools. Validity Notes This document is valid for all versions of the SCADAPack 32 C++ Tools. Product Related Information WARNING 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 [email protected] Document (Version 2.22) 10/26/2012 19 Overview Overview The SCADAPack 32 C++ Tools are ideal for engineers and programmers who require advanced programming tools for SCADA applications and process control. The SCADAPack 32 controller executes Telepace Ladder Logic or IEC 61131-3 and C++ application programs simultaneously, providing you with maximum flexibility in implementing your control strategy. This manual provides documentation on SCADAPack 32 C++ programming and the library of C++ language process control and SCADA functions. We strongly encourage you to read it, and to notify us if you find any errors or additional items you feel should be included in our documentation. We sincerely hope that the reliability and flexibility afforded by this fully programmable controller enable you and your company to solve your automation problems 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 [email protected] 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 [email protected] 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 [email protected] Document (Version 2.22) 10/26/2012 20 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 32 C++ Tools Installation Overview There are two separate applications that need to be installed on a PC to enable the creating, editing, compiling and linking of C/C++ programs for the SCADAPack 32 controller. The Hitachi Embedded Workshop 2, or HEW2, application is Windows based and is used in the editing, compiling, linking and debugging of C++ application programs. The SCADAPack 32 C++ Tools install the SCADAPack 32 C++ Tools library and header files. To load the C++ applications into the SCADAPack 32 controller either Telepace or IEC 61131-3 Workbench is used. Each of these installations is described in the following sections. Installing the Hitachi Embedded Workshop 4 (HEW4) If this is an upgrade installation from HEW you must uninstall HEW before proceeding with the HEW4 installation. Use the Control Panel; Uninstall Programs command to remove the previous version. Install HEW4 as described on the jewel case liner of the HEW Installation CD and install to the folder C:\Program Files\Renasas\HEW. The HEW 4 optimizer linker will generate the warning L1320 Duplicate Symbol. This warning can be suppressed by through the build -> SuperH RISC engine Standard Toolchain menu item. From there select the project link/library tab. Edit the options to include "-nomessage=1320". Multiple Versions of HEW Not Recommended. Having multiple versions of HEW installed on your computer is inadvisable. This is known to cause unpredictable crashing of any version of HEW. Installing the SCADAPack 32 C++ Tools Install HEW first before installing the SCADAPack 32 C++ Tools. Install the SCADAPack 32 C++ Tools as described on the jewel case liner of the SCADAPack 32 C++ Tools Installation CD. Select a similar location for these tools as was selected for HEW (e.g. C:\ C:\Program Files\Renasas\HEW). Document (Version 2.22) 10/26/2012 21 Getting Started The C++ Tools consist of a library and a header file. The library contains the C++ Tools functions and ctools.h contains the declarations for those functions. Constants and structures related to these functions are also defined in ctools.h. Installed location of C++ Tools: C:\Program Files\Renasas\HEW. 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 problems with the Setup, disable your virus checker and run Setup again. Installing IEC 61131-3 Workbench Install IEC 61131-3 as described on the jewel case liner of the IEC 61131-3 Installation CD. Some virus checking software may interfere with Setup. If you experience problems with the Setup, disable your virus checker and run Setup again. Program Development Tutorial Program development consists of three stages: writing and editing; compiling and linking; and loading the program into the target 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”. Create a New C++ Application Framework The Hitachi Embedded Workshop is used to write, edit, compile, and link application programs for the SCADAPack 32. A HEW2 workspace contains one or more projects. A project is an application program or a library. In this tutorial a new workspace and project is created. Start the Hitachi Embedded Workshop (HEW2) from the Windows Start Menu under Hitachi Embedded Workshop 2. The Hitachi Embedded Workshop2 is opened and the Welcome! Dialog is displayed. Document (Version 2.22) 10/26/2012 22 Getting Started In the Options: section, confirm the Create a new project workspace radio button is checked. Click the OK button to open the New Project Workspace dialog in the Hitachi Embedded Workshop and close the Welcome! Dialog. Document (Version 2.22) 10/26/2012 23 Getting Started In the Workspace Name enter MyWorkspace. In the Project Name enter MyApp. The Directory window displays the folder where the workspace files will be created. Click on the Browse button to select a different location. In the CPU family drop down list select SuperH RISC Engine. In the Tool chain drop down list select Hitachi SuperH Standard. In the Project Type choose the type of firmware in your controller. Select IEC 61131-3 Application to create an application framework for IEC 61131-3 firmware. Select Telepace Application to create an application framework for Telepace firmware. Click the OK button to create the workspace and project and to close the New Project Workspace dialog. When the New Project Workspace dialog is closed the project MyApp is displayed in the MyWorkspace workspace. The Hitachi Embedded Workshop now displays the following screen. The Hitachi Embedded Workshop 2 contains three main windows, the Workspace window on the left side, the Editor window on the right side and the Output window across the bottom. Refer to the HEW on-line help for complete details on the workspace contents. To display the application framework for the project MyApp: Document (Version 2.22) 10/26/2012 24 Getting Started Expand the project files folder by clicking on the + beside the folder. Double click the main.ccp file. The Editor window now contains the framework for the MyApp project. This framework is created whenever a new project is created in the HEW Workspace. This project file is edited for the users specific application. For this tutorial the infamous C program code to print “hello world” to serial port 1 will be added to the project. The “hello, world” message will be output to the com1 serial port of the SCADAPack 32 controller. A terminal connected to the port will display the message. The SCADAPack 32 controller normally communicates on all ports using the TeleBUS communication protocol. The first section of the program disables the com1 protocol so the serial port can be used as a normal RS-232 port. The fprintf function prints the message to the com1 serial port. Edit the main.ccp text to include the bolded text shown in the following MyApp Project section. MyApp Project /* ---------------------------------------------------------------MyApp.cpp SCADAPack 32 C++ Application Main Program Copyright 2001, Control Microsystems Inc. ---------------------------------------------------------------- */ #include <ctools.h> /* ---------------------------------------------------------------Function Prototypes ---------------------------------------------------------------- */ #ifdef __cplusplus extern "C" { #endif extern void main(void); #ifdef __cplusplus } #endif /* --------------------------------------------------------------main This routine is the main application loop. The infamous “hello, world” is printed to serial port 1. --------------------------------------------------------------*/ void main(void) { Document (Version 2.22) 10/26/2012 25 Getting Started PROTOCOL_SETTINGS settings; /* Initialize the serial port for outputting debug messages */ settings.type = NO_PROTOCOL; settings.station = 1; settings.mode = AM_standard; settings.priority = 3; settings.SFMessaging = FALSE; setProtocolSettings(com1, &settings); /* Print the message */ fprintf(com1, "hello, world\r\n"); // main loop while (TRUE) { // add remainder of program here // release processor to other priority 1 tasks release_processor(); } } Compiling the C++ Application 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 32 controller. To compile and link the MyApp project: Select Build All from the HEW2 Build menu. The HEW2 Output window will show the progress of the compiling and linking process. When the Build all is selected for the first time after installation it may take a few minutes for the compiler to complete. During this time the message: Phase SH C/C++ Library Generator starting is displayed in the Output Window. The application is successfully built if there are no Errors or Warnings displayed in the Output window. The following should appear in the Output window when the application is built successfully: Build Finished 0 Errors, 0 Warnings If Errors or Warnings are encountered correct the editing done in the MyApp project and build the application again. Long Library Generation Time Standard libraries must be built the first time any application is built using HEW. This can take up to 10 minutes on an older PC (350 MHz Pentium 2). The Document (Version 2.22) 10/26/2012 26 Getting Started libraries are built only the first time a project is compiled. Thereafter, this phase of the build takes only a few seconds. Long Linking Times The linker in HEW 2.1 takes much longer to finish running than the linker in HEW 1.1. As a result, for large projects, it is advisable that debug builds with optimizations turned off be used until an optimized build is needed. This will significantly reduce the time spent waiting for HEW 2.1 to report any linking errors. Due to the long linking times it may appear that HEW 2 has stopped responding. Before forcibly ending HEW 2.1 or aborting the link process check the “Windows Task Manager” “Process” tab to see if the linker, optlnk.exe, is using a large percentage of the CPU and check the amount of time that the linker has used the CPU. Link times of up to 7 minutes have been observed for large projects. As a result you may wish to let the linker run for a few more minutes before assuming that the link phase has caused HEW 2.1 to be non-responsive. 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 The SCADAPack 32 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 SCADAPack 32 controller starts in the cold boot mode: • The default serial communication parameters are used. • The Telepace Ladder Logic application program is erased. • The C/C++ program is erased. • The controller is unlocked. To perform a Cold Boot use the following procedure: • Remove power from the SCADAPack 32 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 SCADAPack 32 controller will start in service mode, not the cold boot mode. Document (Version 2.22) 10/26/2012 27 Getting Started Connect to Controller To connect to a controller using Telepace firmware: • Connect the cable to a serial port on the PC. • Connect the cable to the com2 serial port on the controller. • 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. 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 SCADAPack 32 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, world project into the controller: • From the Controller menu, select the C/C++ Program Loader command. • Enter C:\HEW2\MyWorkspace\MyApp\Release\MyApp.mot in the edit box for File Name. Document (Version 2.22) 10/26/2012 28 Getting Started • Click on the Write button. The file will be downloaded. Executing the Program • Connect a terminal to com1 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. Loading and Executing the C++ Application Using IEC 61131-3 The IEC 61131-3 C\C++ Program Loader transfers executable files from a PC to the controller and controls execution of programs in the controller. Controller Initialization The SCADAPack 32 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 SCADAPack 32 controller starts in the cold boot mode: • The default serial communication parameters are used. • The IEC 61131-3 application program is erased. • The C program is erased. Document (Version 2.22) 10/26/2012 29 Getting Started • The controller is unlocked. To perform a Cold Boot use the following procedure: • Remove power from the SCADAPack 32 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 SCADAPack 32 controller will start in service mode, not the cold boot mode. Connect to Controller Before the project can be loaded to the SCADAPack 32 controller a connection, or link, needs to be made between the PC and the SCADAPack 32 controller. The SCADAPack 32 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-3 PC-PLC Link parameters define how the communication link between the PC and the target controller functions. These parameters are set to match the SCADAPack 32 serial port parameters. To open the PC_PLC link parameters dialog: Select Link Setup from the Debug menu. When selected the PC-PLC Link Parameters dialog is displayed. The Target Slave Number: entry is ignored when the TeleBUS Driver is selected. The TeleBUS Driver sets the target slave number. Ignore the value in this field. From the Communication port: dropdown list-box select TeleBUS Driver. Document (Version 2.22) 10/26/2012 30 Getting Started 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. Select the Setup button. When selected the PC Communication Settings dialog is displayed. Click the Default button. This will ensure the serial parameters for the PC are the same as the parameters on each of the SCADAPack 32 serial ports. In the Port dropdown selection select the serial port you are using on your PC to communicate with the SCADAPack 32 controller. Connect SCADAPack 32 com2 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, world project into the controller: • Run the IEC 61131-3 program. • From the Tools menu select Controller and then select the C/C++ Program Loader command. • Enter C:\HEW2\MyWorkspace\MyApp\Release\MyApp.mot in the edit box for File Name. • Click on the Write button. The file will be downloaded. Executing the Program • Connect a terminal to com1 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. Document (Version 2.22) 10/26/2012 31 Getting Started • 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. Document (Version 2.22) 10/26/2012 32 C++ Program Development C++ Program Development Program Architecture This section of the manual describes the process for developing end-user applications in C++ for the SCADAPack 32 controller family. The SCADAPack 32 C++ Tools are based on the Hitachi Embedded Workshop (HEW) compiler and Hitachi Debugging Interface (HDI) emulator for the 7729 processor. Users will be able to create, compile and debug applications using these tools. Application Startup Functions There are two files associated with the startup structure: appstart.cpp and appsettings.src. Each is described below. Application Startup Settings (appsettings.src) The stack space allocated to the main task is specified in the file appsettings.src. An excerpt from this file is shown below: ; ---------------------------------------------------------------; Application Startup Settings ; ; To change the stack space allocated to the user task main(), edit ; the value assigned to stackBlocks below in hexadecimal. ; e.g. H'04 for 4 stack blocks ; ---------------------------------------------------------------startAddress: .data.l _appstart ;C++ application startup stackBlocks: .data.b H'04 ;stack blocks for main() task reservedHeader: .res.b H'1B ;reserved These are the Application Startup Settings. The first element, startAddress, defines the function appstart() as the starting address and should not need to be changed. The second element is named stackBlocks. This is the size of the stack allocated to the main task. The stack size is sufficient for most applications. Modifying this statement can change it. The value is entered in hexadecimal e.g. H'04 for 4 stack blocks. Refer to the Real Time Operating System section for more information on the stack required by tasks. Application Startup Function (appstart.app) The start-up code has the following major functions: • initialize application program variables; • control execution of the I/O system, protocols, IEC 61131-3 runtime engine and background I/O tasks; Document (Version 2.22) 10/26/2012 33 C++ Program Development • execute the main() function Source code for the appstart function is supplied with the IEC 61131-3 C Tools in appstart.cpp. The following discussion refers to statements found in this file. At the top of appstart.cpp is the macro definition for the heap size used for C++ applications. Edit this macro to adjust the area of memory allocated to application heap. The maximum heap size is the entire application space. Use the application map file to determine the unused application space available for heap, before modifying HEAPSIZE. #define HEAPSIZE 0x40000 // size of heap area The appstart function begins by initializing application variables. Initialized variables are initialized by the following function call, and non-initialized variables are zero-filled. This does not include local variables. initializeApplicationVariables(); The I/O system is started. If your application does not require any I/O and does not use com3, you can reduce the CPU load by changing TRUE to FALSE in the following statement: runIOSystem(TRUE); The communication protocols are started for each serial port, according to the stored values in the Flash, the standard values on a SERVICE boot, or the values included in ladder logic in flash. Communication on serial ports may be interrupted when a ladder logic in flash program is started. If your application program does not use the communication protocols, some or all of the following commands can be removed, to free the stack space used by the protocol tasks. Stack space is required to create additional tasks. Refer to the create_task function for more information. start_protocol(com1); start_protocol(com2); start_protocol(com3); start_protocol(com4); The Modbus/TCP server is started. If you are not using the Ethernet interface, you can free the stack space used this task by changing TRUE to FALSE in the following statement: mTcpRunServer(TRUE); The TCP/IP master messaging support task is started. If you are not using the Ethernet interface for master messaging, you can free the stack space used this task by changing TRUE to FALSE in the following statement: runMasterIpStartTask(TRUE); Document (Version 2.22) 10/26/2012 34 C++ Program Development The background I/O task is required for the dial-up modem communications and pushbutton LED power control. If you arenot using these functions, you can reduce the CPU load by changing TRUE to FALSE in the following statement: runBackgroundIO(TRUE); The IEC 61131-3 runtime engine is required for IEC 61131-3 IEC 1131 application programs. The Telepace runtime engine is required for Telepace application programs. If you are not using IEC 61131 or Telepace application programs you can reduce the CPU load by changing TRUE to FALSE in the following statement: runTarget(TRUE); If the application has any global class objects, the global class object constructors are called in the following statement: executeConstructors(); The final operation is execution of the main function. main(); If the main function returns, the task is ended. First, if the application has any global class objects, the global class object destructors are called in the following statement: executeDestructors(); Then any modem control sessions started by the application are terminated: modemAbortAll(); Then the task is ended. This will cause all other APPLICATION tasks created by main to be stopped as well. getTaskInfo(0, &taskStatus); end_task(taskStatus.taskID); The remaining code in this file is the function sbrk. This function provides support for the application heap and should not be modified. Non-Volatile Data Sections SCADAPack 32 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 nonvolatile memory allocation. See the function allocateMemory. Document (Version 2.22) 10/26/2012 35 C++ Program Development Only non-initialized variables can be created in SRAM. Initialized variables do not need to be non-volatile, since they are initialized to the same value on application startup. To create a non-volatile section in SRAM, use the following procedure: Source Code Two #pragma commands need to be placed as shown in the example below, before and after the non-volatile variable declarations in any C or C++ file. The name of the non-volatile section needs to be nonVolatile. // place these variables in SRAM section named nonVolatile #pragma section nonVolatile non-volatile variable declarations // if code or volatile variable declarations follow, then add this line #pragma section Example: // place these variables in SRAM section named nonVolatile #pragma section nonVolatile UINT32 variable1; UCHAR array1[20]; struct sample table[10]; // if code or volatile variable declarations follow, then add this line #pragma section void main(void) { } A compiler warning is generated if there are no volatile declarations or code following the last #pragma section statement. To correct the warning, remove this last #pragma section statement. Linking A linker error will occur if the section exceeds 8 Kbytes. To correct this error, declare some non-volatile variables in dynamic non-volatile memory instead using the function allocateMemory. You may check the map file for the section BnonVolatile to determine the current size of this section. The section is created BnonVolatile to indicate the section is for B-type or non-initialized type variables. The last address for the BnonVolatile section need to be less than H’14002000. Document (Version 2.22) 10/26/2012 36 C++ Program Development If other linker errors are generated after adding variables to the non-volatile section, check the following: Program code or initialized variables cannot be included in between the lines containing the #pragma commands. These will create additional code and data sections and locate them arbitrarily at the end of the last section. Check that the #pragma commands are used in the correct order and are used for non-initialized variable declarations only. Application Development The HEW2 Workspace Manager is designed to create workspaces and projects that HEW2 can modify. This removes the requirement that the user have a detailed technical knowledge of the various steps required to create workspaces and projects from within HEW2. Create a New C++ Application Framework The Hitachi Embedded Workshop is used to write, edit, compile, and link application programs for the SCADAPack 32. A HEW2 workspace contains one or more projects. A project is an application program or a library. In this tutorial a new workspace and project is created. Start the Hitachi Embedded Workshop (HEW2) from the Windows Start Menu under Hitachi Embedded Workshop 2. The Hitachi Embedded Workshop2 is opened and the Welcome! Dialog is displayed. In the Options: section the Create a new project workspace radio button allows a new project workspace to be created. The Open a recent project workspace: presents a list of recent projects that have been opened. The Browse to another project workspace allows the selection of any project workspace. Click the OK button to open a New Project Workspace dialog in the Hitachi Embedded Workshop and close the Welcome! Dialog. Document (Version 2.22) 10/26/2012 37 C++ Program Development In the Workspace Name enter MyWorkspace. In the Project Name enter MyApp. The Directory window displays the folder where the workspace files will be created. Click on the Browse button to select a different location. In the CPU family drop down list select SuperH RISC Engine. In the Tool chain drop down list select Hitachi SuperH Standard. In the Project Type choose the type of firmware in your controller. Select IEC 61131-3 Application to create an application framework for IEC 61131-3 firmware. Select Telepace Application to create an application framework for Telepace firmware. Click the OK button to create the workspace and project and to close the New Project Workspace dialog. When the New Project Workspace dialog is closed the project MyApp is displayed in the MyWorkspace workspace. The Hitachi Embedded Workshop now displays the following screen. Document (Version 2.22) 10/26/2012 38 C++ Program Development The Hitachi Embedded Workshop 2 contains three main windows, the Workspace window on the left side, the Editor window on the right side and the Output window across the bottom. Refer to the HEW on-line help for complete details on the workspace contents. To display the application framework for the project MyApp: • Expand the project files folder by clicking on the + beside the folder. • Double click the main.ccp file. • The Editor window now contains the framework for the MyApp project. This framework is created whenever a new project is created in the HEW Workspace. This project file is edited for the users specific application. To display the application framework for the project MyApp.ccp: • Expand the project files folder by clicking on the + beside the folder. • Double click the MyApp.ccp file. • The Editor window now contains the framework for the MyApp project. This framework is created whenever a new project is created in the HEW Workspace. This project file is edited for the users specific application. Loading of Projects HEW 2.1 does not automatically load all projects when a workspace is opened. Only the last project used is automatically loaded. The exception to this is when HEW decides that projects need to be converted from one tool chain to another Document (Version 2.22) 10/26/2012 39 C++ Program Development tool chain version. As a result selecting “Set as Current Project” will not operate as it did in HEW 1.1 until you have loaded the project by selecting “Load Project”. Adding Files to a Project Files can be added to a project. From the Project menu, select Add Files. The following dialog appears. See the HEW documentation for a full description. File Name specifies the name of the file. The Relative Path option specifies that the location of this file will be stored relative to the folder containing the project file. This option lets you move the project to another folder easily. We recommend that this option be used for all files. Building a C++ Application 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 32 controller. To compile and link the project: Select Build All from the HEW2 Build menu. The HEW2 Output window will show the progress of the compiling and linking process. The application is successfully built if there are no Errors or Warnings displayed in the Output window. The following should appear in the Output window when the application is built successfully: Build Finished 0 Errors, 0 Warnings Document (Version 2.22) 10/26/2012 40 C++ Program Development Long Library Generation Time Standard libraries must be built the first time any application is built using HEW. This can take up to 10 minutes on an older PC (350 MHz Pentium 2). The libraries are built only the first time a project is compiled. Thereafter, this phase of the build takes only a few seconds. Long Linking Times The linker in HEW 2.1 takes much longer to finish running than the linker in HEW 1.1. As a result, for large projects, it is advisable that debug builds with optimizations turned off be used until an optimized build is needed. This will significantly reduce the time spent waiting for HEW 2.1 to report any linking errors. Due to the long linking times it may appear that HEW 2 has stopped responding. Before forcibly ending HEW 2.1 or aborting the link process check the “Windows Task Manager” “Process” tab to see if the linker, optlnk.exe, is using a large percentage of the CPU and check the amount of time that the linker has used the CPU. Link times of up to 7 minutes have been observed for large projects. As a result you may wish to let the linker run for a few more minutes before assuming that the link phase has caused HEW 2.1 to be non-responsive. Release Build and Debug Build When an application project is built, two executable files are created. Both have the same name as the project and are located in the Release or Debug subdirectory of the project. Release Build <projectDirectory>\Release\projectName.MOT This file is the compiled and linked application optimized for speed and code size. Unless you are using the Emulator debugging interface, the Release build should be the build that is loaded into the controller using IEC 61131-3 or Telepace C/C++ Program Loader. Use this file with IEC 61131-3 or Telepace C/C++ Program Loader. <projectDirectory>\Release\projectName.ABS This file is the same as the *.MOT but includes debugging information. This file cannot be loaded with the C/C++ Program Loader. This file may be used with the Emulator debugging interface, however optimized code is confusing to step through. Use the Debug Build *.ABS file instead. Debug Build <projectDirectory>\Debug\projectName.MOT Document (Version 2.22) 10/26/2012 41 C++ Program Development This file is the compiled and linked application with no optimization. Unless you are interested in a non-optimized application, use the Release build instead. <projectDirectory>\Debug\projectName.ABS This file is the same as the *.MOT but includes debugging information. This file is used with the Emulator debugging interface only. It cannot be loaded with the C/C++ Program Loader. Use this file with Emulator debugging interface. 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 The SCADAPack 32 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 SCADAPack 32 controller starts in the cold boot mode: • The default serial communication parameters are used. • The Telepace Ladder Logic application program is erased. • The C/C++ program is erased. • The controller is unlocked. • To perform a Cold Boot use the following procedure: Remove power from the SCADAPack 32 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 SCADAPack 32 controller will start in service mode, not the cold boot mode. Connect to Controller To connect to a controller using Telepace firmware: • Connect the cable to a serial port on the PC. • Connect the cable to the com2 serial port on the controller. Document (Version 2.22) 10/26/2012 42 C++ Program Development • 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. • 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 SCADAPack 32 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, world project into the controller: • From the Controller menu, select the C/C++ Program Loader command. • Enter C:\HEW2\MyWorkspace\MyApp\Release\MyApp.mot in the edit box for File Name. Document (Version 2.22) 10/26/2012 43 C++ Program Development • Click on the Write button. The file will be downloaded. Executing the Program • Connect a terminal to com1 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. Loading and Executing a C++ Application Using IEC 61131-3 The IEC 61131-3 C\C++ Program Loader transfers executable files from a PC to the controller and controls execution of programs in the controller. Controller Initialization The SCADAPack 32 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 SCADAPack 32 controller starts in the cold boot mode: • The default serial communication parameters are used. • The IEC 61131-3 application program is erased. • The C program is erased. Document (Version 2.22) 10/26/2012 44 C++ Program Development • The controller is unlocked. To perform a Cold Boot use the following procedure: • Remove power from the SCADAPack 32 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 SCADAPack 32 controller will start in service mode, not the cold boot mode. Connect to Controller Before the project can be loaded to the SCADAPack 32 controller a connection, or link, needs to be made between the PC and the SCADAPack 32 controller. The SCADAPack 32 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-3 PC-PLC Link parameters define how the communication link between the PC and the target controller functions. These parameters are set to match the SCADAPack 32 serial port parameters. To open the PC_PLC link parameters dialog: • Select Link Setup from the Debug menu. • When selected the PC-PLC Link Parameters dialog is displayed. • The Target Slave Number: entry is ignored when the TeleBUS Driver is selected. The TeleBUS Driver sets the target slave number. Ignore the value in this field. • From the Communication port: dropdown list-box select TeleBUS Driver. Document (Version 2.22) 10/26/2012 45 C++ Program Development 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. • Select the Setup button. When selected the PC Communication Settings dialog is displayed. • o Click the Default button. This will ensure the serial parameters for the PC are the same as the parameters on each of the SCADAPack 32 serial ports. o In the Port dropdown selection select the serial port you are using on your PC to communicate with the SCADAPack 32 controller. Connect any SCADAPack 32 serial port to the PC serial port using an RS232 serial communication cable. This cable is a null modem or computer to computer cable. Loading the Application To load the hello, world project into the controller: • Run the IEC 61131-3 program. • From the Tools menu select Controller and then select the C/C++ Program Loader command. • Enter C:\HEW2\MyWorkspace\MyApp\Release\MyApp.mot in the edit box for File Name. • Click on the Write button. The file will be downloaded. Document (Version 2.22) 10/26/2012 46 C++ Program Development Executing the Program • Connect a terminal to com1 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. Debugging a C++ Application The following sections describe the procedure that allows the user to sourcelevel debug a C++ application. HDI Emulator The Hitachi Debugging Interface (HDI) for the SH7729 E10A Emulator provides a step-level debugging interface. The user may use this interface to debug a C++ application running directly in a SCADAPack 32 controller. The E10A hardware and the HDI software needs to be installed in the user PC. Remove power from the controller whenever installing or removing the Emulator cable from the controller P9 connector. Not following this procedure may damage the controller. User Procedure After debugging is complete, remember to load the Release build of the application using the C++ Program Loader. The Release build is optimized for performance. The Release build is the recommended build for final loading into the controller. Load the Debug build of the application using the C++ Program Loader. Do not run the program after downloading. Remove power from the SCADAPack 32 controller. The emulator cable cannot be installed or removed while the controller is powered. Doing so may damage the controller and/or the emulator. Install the emulator interface cable to the controller at socket P9. (The controller execution is unpredictable when operated outside of an HDI Debugger session with the emulator cable still attached.) Install the ground jumper on the emulator interface into the DGND pins on the controller board. Install the small pushbutton switch onto J6. The controller may now be powered ON. The application might begin executing on power up. However, execution is re-started at the start of the debug session in step 8. To ensure the application isn’t started until the debug session, wait until step 7 before powering ON the controller. Start the HDI for SH7729 E10A Emulator. The application opens with the Select Session dialog. Document (Version 2.22) 10/26/2012 47 C++ Program Development Select the bullet for “Create a new session on:” and from the drop down box, select the item SH7729 E10A Emulator little endian and the button OK. The following dialog appears: In the Driver: window select the E10A driver you are using. Then click the close button to close this dialog. If not already done, apply power to the controller now. To ensure the application isn’t started until the debug session, wait until this step before powering ON the controller. Short the jumper J6, by pressing the switch installed in step 5, to reset the controller and select OK from this dialog. If the shorting of J6 is not done cleanly, HDI will freeze until a timeout message occurs in about 10 seconds. From the View menu select Command Line. If HDI appears to be frozen, wait for a timeout message in about 10 seconds. From the Command Line window, select the leftmost icon, Batch File. A Browse dialog is displayed. In the application project directory select the batch file, Debug Application.hdc and select the Open button. The batch file will execute and scroll onto the command line window. This batch file needs to load the same Debug build of the application that was loaded with C++ Program Loader in step 1. The batch file is complete when the last command, rs pc a0000000, appears. Close the command line window. The application is now ready to be debugged. Refer to the HDI On-line documentation for debugging features. Document (Version 2.22) 10/26/2012 48 C++ Program Development To start the OS and application select Go from the Run menu. If at anytime, mistakes are made in the procedure, the debug session may be restarted by selecting Initialize from the File menu. The same reset prompt of step 8 appears. Return to the start of step 8. When debugging is complete, remove power from the controller. With controller power OFF, remove the Emulator interface cable from the controller. The controller execution is unpredictable when operated outside of an HDI Debugger session with the Emulator still attached. Load the Release build of the application using the C++ Program Loader. HDI Timeout after Resetting Switch J6 If shorting jumper J6 is not done cleanly, HDI will freeze until a timeout occurs in about 10 seconds. If this has occurred, wait for the timeout message: Select the Restart Target button. The reset prompt appears. Return to the start of step 8 in the procedure above and reset jumper J6 again. Managing Projects Upgrading HEW 1 Workspaces and Projects HEW 1 workspaces and projects need to be updated to compile them with HEW 2. Once updated, the workspace cannot be opened in HEW 1. However, the source files are unchanged. The following procedure is recommended. HEW workspaces also can be upgraded by opening the workspace in HEW 2 and following the on-screen prompts. However, HEW 2 does not update some SCADAPack 32 specific settings and files. The following procedure ensures all project settings and files are correct. To update a project: • Create a backup copy of the existing project. • Create a new workspace and application framework. • Copy all of the source files (.C, .CPP, .H, etc.) except for appstart.cpp, from your old project folder into your new project folder. • From the HEW2 Project menu, select the Add Files command. Add the source files to the project. • If your old project did not include a main.cpp file, remove this file from the project using the Remove Files command on the Project menu. • Remove the line that reads extern void main(void); from the file that contains the main function. This eliminates a warning that states the linkage specification is not allowed. • If you modified appstart.cpp in your old project, then merge the changes from it into the appstart.cpp in the new project. Document (Version 2.22) 10/26/2012 49 C++ Program Development • Build the new application. Correct any warnings and errors that occur. The HEW 2 compiler detects more warning and error conditions so code that previously compiled without warnings may not in HEW 2. Adding a Project to an Existing Workspace A HEW2 workspace can hold several related projects. To add a project to an existing workspace: • Open an existing workspace. • From the Project menu, select Insert Project. • Select New Project and click on OK. • In Name enter a name for the project. • The Directory is updated automatically. Usually it does not have to be changed. To place the project files in a different folder, click on Browse. • In the Project Type choose the type of firmware in your controller. • o Select IEC 61131-3 Application to create an application framework for IEC 61131-3 firmware. o Select Telepace Application to create an application framework for Telepace firmware. Click on OK to create the workspace and project. Deleting a Project If there is only one project in the workspace, simply delete the workspace directory. To delete a project from a workspace containing multiple projects, do the following: • In HEW2, open the workspace containing the project to be deleted. • Set the current project to any project other than the one to be deleted. • In the workspace window, highlight the project name to be deleted. • Right click the mouse and select Remove Project from the menu displayed. The project is erased from the workspace window. • Select Save Workspace from the File menu. • You may now manually delete the project directory from the workspace directory. Moving a Workspace When a workspace is moved and re-opened, HEW2 displays a message telling you that the workspace has been moved. Select Yes to continue opening the workspace. HEW automatically corrects the pathnames in the workspace and project files. Document (Version 2.22) 10/26/2012 50 Real Time Operating System Real Time Operating System The real time operating system (RTOS) provides the programmer with tools for building sophisticated applications. The RTOS allows pre-emptive scheduling of event driven tasks to provide quick response to real-world events. Tasks multitask cooperatively. Inter-task communication and event notification functions pass information between tasks. Resource functions facilitate management of non-sharable resources. Task Management 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 RTOS supports up to 16 tasks. There are 5 task priority levels to aid in scheduling of task execution. Task Execution SCADAPack 32 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 5 priority levels. Level 0 is reserved for the null task. This task runs when there are no other tasks available for execution. Application programs can use levels 1 to 4. The main task is created at priority level 1. Task level 4 if the highest priority task. Tasks that are not running are held in queues. The Ready Queue holds all 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. 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 prevent 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 Document (Version 2.22) 10/26/2012 51 Real Time Operating System needed resource. At this point Task L is returned to its original priority. Task H will obtain the resource now that it is available. This does not prevent 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. 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 all 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 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. 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. poll_resource Request access to a resource. Continue execution if the resource is not available release_resource Free a resource for use by other tasks. Document (Version 2.22) 10/26/2012 52 Real Time Operating System IO_SYSTEM Resource The IO_SYSTEM resource regulates access to all functions using the I/O system. C application programs, ladder logic programs, communication protocols and background I/O operations share the I/O system. It is imperative the resource is obtained to prevent a conflict, as protocols and background operations are interrupt driven. Retaining control of the resource for more that 0.1 seconds will cause background operations not to execute properly. DYNAMIC_MEMORY Resource The DYNAMIC_MEMORY resource regulates access to all memory allocation functions. These functions allocate memory from the system heap. The heap is shared amongst all tasks. The allocation functions are non-reentrant. The DYNAMIC_MEMORY resource needs to be obtained before using any of the following functions. calloc allocates data space dynamically free frees dynamically allocated memory malloc allocates data space dynamically realloc changes the size of dynamically allocated space MODBUS_PARSER Resource This resource is used by Modbus communication protocol drivers to allocate access to the common message parser by tasks for each serial port. This resource is of no interest to an application program. 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. 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. Document (Version 2.22) 10/26/2012 53 Real Time Operating System deallocate_envelope Return a message envelope to the free pool maintained by the RTOS. Inter-task Communication Structures The ctools.h file defines the structure Message Envelope Structure for intertask communication information. Refer to the C Tools Structures and Types section for complete information on structures and enumeration types. Event Notification 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. wait_event Wait for an event to occur. 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_event Signal that an event has occurred from an interrupt handler. This function can 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. System Events 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). Document (Version 2.22) 10/26/2012 54 Real Time Operating System 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 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. Error Reporting Sharable I/O drivers to return error information to the calling task use the error reporting functions. These functions ensure 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. 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. The 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 – Document (Version 2.22) 10/26/2012 55 Real Time Operating System 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. /* ------------------------------------------------------------------SCADAPack 32 Real Time Operating System Sample Copyright (c) 1998-2002, Control Microsystems Inc. This program creates several simple tasks for demonstration of the functionality of the real time operation system. ------------------------------------------------------------------- */ #include <stdio.h> #include <ctools.h> /* ------------------------------------------------------------------Constants ------------------------------------------------------------------- */ #define CHARACTER_RECEIVED 10 /* ------------------------------------------------------------------signalCharacter The signalCharacter function signals an event when a character is received. This function must be called from an interrupt handler. ------------------------------------------------------------------- */ void signalCharacter(UINT16 character, UINT16 error) { /* If there was no error, signal that a character was received */ if (error == 0) { interrupt_signal_event(CHARACTER_RECEIVED); } /* Prevent compiler unused variables warning (generates no code) */ character; } /* ------------------------------------------------------------------echoData Document (Version 2.22) 10/26/2012 56 Real Time Operating System The echoData function is a task that waits for a character to be received on com1 and echoes the character back. It installs a character handler for com1 to generate events on the reception of characters. ------------------------------------------------------------------- */ 3 void echoData(void) { struct prot_settings protocolSettings; struct pconfig portSettings; int character; /* Disable communication protocol */ get_protocol(com1, &protocolSettings); protocolSettings.type = NO_PROTOCOL; set_protocol(com1, &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(com1, &portSettings); /* Install handler for received character */ install_handler(com1, signalCharacter); while (TRUE) { /* Wait for a character to be received */ 4 9 wait_event(CHARACTER_RECEIVED); 8 /* Echo the character back */ character = fgetc(com1); if (character == EOF) { // clear overflow error flag to re-enable com1 clearerr(com1); } fputc(character, com1); } Document (Version 2.22) 10/26/2012 57 Real Time Operating System } /* ------------------------------------------------------------------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. ------------------------------------------------------------------- */ void auxiliary(void) 7 { while (TRUE) { /* ... add application specific code here ... */ /* Allow other tasks of this priority to run */ release_processor(); } } /* ------------------------------------------------------------------main This function creates two tasks: one at priority three and one at priority 1 to demonstrate the functions of the RTOS. ------------------------------------------------------------------- */ 1 void main(void) 2 { /* Create serial communication task */ create_task(echoData, 3, APPLICATION, 3); /* Create a task - same priority as main() task */ create_task(auxiliary, 1, APPLICATION, 2); 5 while (TRUE) { /* ... add application specific code here ... */ /* Allow other tasks of this priority to execute */ 6 Document (Version 2.22) 10/26/2012 58 Real Time Operating System release_processor(); } } Explanation of Task Execution SCADAPack 32 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 upon the priority of tasks. There are 5 priority levels. Level 0 is reserved for the null task. This task runs when there are no other tasks available for execution. Application programs can use levels 1 to 4. The main task is created at priority level 1. Tasks that are not running are held in queues. The Ready Queue holds all 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. Execution Point 1 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. Ready Queue Event 10 Queue 4 4 3 3 2 2 1 1 0 null() Running Task none 0 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. Document (Version 2.22) 10/26/2012 59 Real Time Operating System Ready Queue Event 10 Queue 4 4 3 3 2 2 1 1 0 null() Running Task main() 0 Figure 2: Queue Status at Start of main Task Execution Point 3 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 4 4 3 3 2 2 1 main() 1 0 null() 0 Running Task echoData() Figure 3: Queue Status after Creation of echoData Task Execution Point 4 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. Document (Version 2.22) 10/26/2012 60 Real Time Operating System Event 10 Queue Ready Queue 4 4 3 3 2 2 1 1 null() 0 Running Task main() echoData() 0 Figure 4: Queue Status After echoData Task Waits for Event Execution Point 5 This point occurs just after the creation of the auxiliary task. This task is the same priority 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. Ready Queue Event 10 Queue 4 4 3 3 2 2 1 auxiliary() 1 0 null() 0 Running Task main() echoData() Figure 5: Queue Status after Creation of auxiliary Task Execution Point 6 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. Ready Queue Event 10 Queue 4 4 3 3 2 2 1 auxiliary() 0 null() main() Running Task none echoData() 1 0 Figure 6: Queue Status After main Task Releases Processor Document (Version 2.22) 10/26/2012 61 Real Time Operating System Execution Point 7 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. Ready Queue Event 10 Queue 4 4 3 3 2 2 1 main() 1 0 nullTask() 0 Running Task auxiliary() echoData() Figure 7: Queue Status at Start of auxiliary Task Execution Point 8 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 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. Ready Queue Event 10 Queue 4 4 3 3 2 2 1 main() 0 null() auxiliary() Running Task echoData() 1 0 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. Document (Version 2.22) 10/26/2012 62 Real Time Operating System Ready Queue Event 10 Queue 4 4 3 3 2 2 1 auxiliary() 1 0 null() 0 Running Task main() echoData() Figure 9: Queue Status after echoData Waits for Event Document (Version 2.22) 10/26/2012 63 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 detailed explanations of the Functions, Macros, Structure and Types described here. Controller Operation This section of the manual provides an overview of the IEC 61131-3 functions relating to controller operation. These functions are provided in addition to the run-time library supplied with the Hitachi Embedded Workshop. Start Up Functions 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. runBackgroundIO Starts or stops the Background I/O task. runTarget Starts or stops the run-time engine task. initializeApplicationVariables Initializes user application variables. runIOSystem 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. runMasterIpStartTask Starts or stops the Modbus/TCP Master support task. runBackgroundIO Starts or stops background I/O task (e.g. Dialup support, pushbutton LED power control). runTarget Starts or stops the run-time engine (Ladder Logic or IEC 61131-3) executeConstructors Execute all user-created global class object constructors. executeDestructors Execute all user-created global class object destructors. Start Up Macros 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. Document (Version 2.22) 10/26/2012 64 Overview of Programming Functions STARTUP_APPLICATION STARTUP_SYSTEM Specifies the application start up task. Specifies the system start up task. 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. getControllerID 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 SCADAPack 32 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 CS_OPTIONS CS_PERMANENT always always Saved settings loaded on Service and Run Boot. Ethernet MAC address Controller factory options. Controller type, IP address, Gateway, Network mask, IP Configuration mode, Lock state and password, I/O Document (Version 2.22) 10/26/2012 65 Overview of Programming Functions CS_RUN Replaced with default settings on Cold Boot. System settings, I/O error indication setting Saved settings loaded on Run Boot. Telepace Firmware only: Register assignment, Outputs on stop settings Serial port settings, Serial protocol settings, Modbus/TCP settings, HART I/O settings, LED power settings, Store and forward table Default settings loaded on Service Boot. 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. flashSettingsSave This function loads the controller settings in the indicated area or areas from flash memory. System Functions 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 all I/O points ioDatabaseReset Resets the controller to default settings. ioRefresh Refresh outputs with internal data ioReset Reset all I/O modules Controller I/O Hardware This section of the manual provides an overview of the IEC 61131-3 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 32 System Hardware Manual for further information on controller analog inputs and analog input modules. Document (Version 2.22) 10/26/2012 66 Overview of Programming Functions 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. readThermistor Read the controller ambient temperature sensor. ioRead4Ain read 4 analog inputs into I/O database. ioRead8Ain read 8 analog inputs into I/O database. ioRead5505Inputs Read the digital and analog inputs from a 5505 I/O Module. ioRead5505Outputs Read the configuration data from a 5505 I/O Module. ioRead5506Inputs Read the digital and analog inputs from a 5506 I/O Module. ioRead5506Outputs Read the configuration data from a 5506 I/O Module. ioWrite5505Outputs Write the configuration data to a 5505 I/O Module. ioWrite5506Outputs Write the configuration data to a 5506 I/O Module. ioRead5601Inputs Read the digital and analog inputs from a SCADAPack 5601 I/O Module. ioRead5604Inputs Read the digital and analog inputs from a SCADAPack 5604 I/O Module. ioRead5606Inputs Read the digital and analog inputs from a 5606 I/O Module. ioRead5606Outputs Read the digital and analog outputs from a 5606 I/O Module. Analog Output Functions The controller supports external analog output modules. Refer to the SCADAPack 32 System 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. ioRead5606Outputs Read the digital and analog outputs from a 5606 I/O Module. ioReadAout2 Read buffered data for 2 point analog output module ioReadAout4 Read buffered data for 4 point analog output module ioReadAout5303 Read buffered data for 5303 analog output module ioWriteAout2 Write buffered data for 2 point analog output module ioWriteAout4 Write buffered data for 4 point analog output module ioWriteAout5303 Write buffered data for 5303 analog output module Document (Version 2.22) 10/26/2012 67 Overview of Programming Functions ioWrite5606Outputs Write to the digital and analog outputs of a 5606 I/O Module. Digital Input Functions The controller supports internal digital inputs and external digital input modules. Refer to the SCADAPack 32 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 Read the digital and analog inputs from a 5606 I/O Module. ioReadDin5232 Read buffered data from the 5232 digital inputs ioReadCounter5232 Read buffered data from the 5232 counter inputs. ioRead5414Inputs Read buffered data from the 5414 Digital input module. ioWrite5414Outputs Write 5414 module configuration parameters. ioReadDin16 Read buffered data from any 16 point Digital input module. ioReadDin32 Read buffered data from any 32 point Digital input module. ioRead5601Inputs Read buffered data from the digital and analog inputs of a 5601 I/O module. ioRead5604Inputs Read the digital and analog inputs from a SCADAPack 5604 I/O Module. ioReadDin8 Read buffered data from any 8 point Digital input module. Digital Output Functions The controller supports external digital output modules. Refer to the SCADAPack 32 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 Read the digital and analog inputs from a 5606 I/O Module. ioReadDout16 Read buffered data from any 16 point Digital output module. ioReadDout32 Read buffered data from any 32 point Digital output module. ioRead5415Inputs Read buffered data from the 5415 digital output module. Document (Version 2.22) 10/26/2012 68 Overview of Programming Functions ioRead5415Outputs Read buffered data from the 5415 digital output module. ioRead5601Outputs Read buffered data from any 5601 I/O Module. ioRead5604Outputs Read buffered data from any 5604 I/O Module. ioReadDout8 Read buffered data from any 8 point Digital output module. ioWriteDout16 Write data to the I/O tables for any 16 point Digital output module. ioWriteDout32 Write data to the I/O tables for any 32 point Digital output module. ioWrite5415Outputs Write data to the I/O table for the digital outputs of a 5415 I/O Module. ioWrite5601Outputs Write data to the I/O table for the digtal outputs of a 5601 I/O Module (SCADAPack 32 lower I/O module). ioWrite5604Outputs Write to the digital and analog outputs of SCADAPack 5604 I/O Module. ioWrite5606Outputs Write to the digital and analog outputs of a 5606 I/O Module. ioWriteDout8 Write data to the I/O tables for any 8 point Digital output module. Counter Input Functions 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 inputs. Refer to the SCADAPack 32 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 all 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. Document (Version 2.22) 10/26/2012 69 Overview of Programming Functions Refer to the SCADAPack 32 System 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. 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 S_NORMAL Status LED code for normal status I/O Forcing Functions There are six library functions related to I/O forcing. Refer to the Function Specification section for details on each function listed. These functions are supported by Telepace firmware only. setOutputsInStopMode Sets the doutsInStopMode and aoutsInStopMode control flags to the specified state. getOutputsInStopMode Copies the values of the output control flags into the integers pointed to by doutsInStopMode and aoutsInStopMode clearAllForcing Removes all forcing conditions from all I/O 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 Options Switches Functions The controller has three option switches located under the cover of the controller module. These switches are labeled OPTION 1,2, 3 and 4. The option switches are user defined except when a SCADAPack 32 I/O module or SCADAPack 32 AOUT module used. In this case option switches 1 and 2 select the analog ranges. Refer to the SCADAPack 32 System Hardware Manual for further information on option switches. Document (Version 2.22) 10/26/2012 70 Overview of Programming Functions There is one library function related to the controller option switches. Refer to the Function Specification section for details. optionSwitch Read option switch states. 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 as a binary sequence. The sequence repeats until a new error code is output. If the error code is zero, the status LED turns off. The FORCE LED (yellow) indicates locked I/O variables. 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, the upper and lower I/O modules and the 5000 I/O modules to conserve power. This is particularly useful in solar powered or unattended installations. Refer to the SCADAPack 32 System 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. Software Timer Functions The controller provides 32 powerful software timers, which greatly simplify the task of programming time-related functions. Uses include: generation of time delays timing of process events such as tank fill times Document (Version 2.22) 10/26/2012 71 Overview of Programming Functions generation of time-based interrupts to schedule regular activities 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 provided 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. 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. Document (Version 2.22) 10/26/2012 72 Overview of Programming Functions 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 that 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 readStopwatch 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 prevent 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 all outputs at the I/O system. The watchdog timer is normally reset by the operating system. This is transparent to the application program. Operating in such a fashion, the watchdog timer detects any hardware or firmware problems. 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. Document (Version 2.22) 10/26/2012 73 Overview of Programming Functions 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 must 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 system 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 bytewise exclusive-OR. The CRC algorithms are particularly reliable, employing various polynomial methods to detect nearly all 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. Serial Communication The SCADAPack 32 family of controllers offers three or four RS-232 serial ports. The ports are configurable for baud rate, data bits, stop bits, parity and communication protocol. To optimize performance, minimize the length of messages on com3. Examples of recommended use for com3 are for local operator display terminals, and for programming and diagnostics using the IEC 61131-3 program. Document (Version 2.22) 10/26/2012 74 Overview of Programming Functions Default Serial Parameters All 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. Parameter com1 com2 Com3 Com4 Baud rate Parity Data bits Stop bits Duplex Protocol Addressing Mode Station Rx flow control Tx flow control Type 9600 none 8 1 full Modbus RTU Standard 9600 none 8 1 full Modbus RTU Standard 9600 None 8 1 Half Modbus RTU Standard 9600 None 8 1 full Modbus RTU Standard 1 Modbus RTU 1 Modbus RTU 1 Modbus RTU 1 Modbus RTU none none none none RS-232 RS-232 RS-232 RS-232 Debugging Serial Communication Serial communication can be difficult to debug. This section describes the 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 controller the CTS line needs to be at the proper level. The controller will not transmit if CTS is OFF. If the CTS line is not connected, the controller will force it Document (Version 2.22) 10/26/2012 75 Overview of Programming Functions 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 connects 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. modemInit modemInitStatus modemInitEnd send initialization string to dial-up modem. read status of modem initialization operation. terminate modem initialization operation. modemDial connect with an external device using a dial-up modem. modemDialStatus read status of connection with external device using a dial-up modem. Document (Version 2.22) 10/26/2012 76 Overview of Programming Functions 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_MAX_LEN Maximum length of the modem initialization command string PHONE_NUM_MAX_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 32 controllers. Additional TeleBUS commands provide remote programming and diagnostics capability. The TeleBUS protocols provide full 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. 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 generally independent of the communication parameters of the link, with a few exceptions. Document (Version 2.22) 10/26/2012 77 Overview of Programming Functions 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-3 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 all stations. 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 all stations, and cannot be used as a station number. Each serial port may have a unique station number. Store and Forward Messaging Store and forward 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 userdefined 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 all store and forward translation table entries. get_protocol getProtocolSettings get_protocol_status Document (Version 2.22) 10/26/2012 Reads protocol parameters. Reads extended addressing protocol parameters for a serial port. Reads protocol message and error counters. 78 Overview of Programming Functions 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. modbusSlaveID Sets response for the read slave ID function. set_protocol Sets protocol parameters and starts protocol. setProtocolSettings Sets extended addressing protocol parameters for a serial port. setSFTranslation start_protocol Write store and forward translation table entry. 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 & gas, water/waste water and security 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 reliable communications between substation computers, RTUs, IEDs and master stations; over serial or LAN-based systems. DNP offers flexibility and functionality that go far beyond conventional communications protocols. Among its robust and flexible features DNP 3.0 includes: • Output options • Addressing for over 65,000 devices on a single link • Time synchronization and time-stamped events • Broadcast messages Document (Version 2.22) 10/26/2012 79 Overview of Programming Functions • 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 most 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 most commonly a simple RS232 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 all change events from the DNP change event buffers. dnpConnectionEvent Report a DNP connection event dnpCreateAddressMapTable 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. dnpGenerateChangeEvent Generates a change event for the DNP point. dnpGenerateEventLog Generates a change event for the DNP point. dnpGetAI16Config Reads the configuration of a DNP 16-bit analog input point. dnpGetAI32Config Reads the configuration of a DNP 32-bit analog input point. dnpGetAISFConfig 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. dnpGetCI16Config Reads the configuration of a DNP 16-bit counter input point. dnpGetCI32Config Reads the configuration of a DNP 32-bit counter input point. dnpGetBIConfig Reads the configuration of a DNP binary input point. Document (Version 2.22) 10/26/2012 80 Overview of Programming Functions dnpGetBIConfigEx Reads the configuration of an extended DNP Binary Input point. dnpGetBOConfig Reads the configuration of a DNP binary output point. dnpGetCI16Config Reads the configuration of a DNP 16-bit counter input point. dnpGetCI32Config 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 all DNP change event buffers. dnpInstallConnectionHandler 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, to a 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 poll table. Reads an entry from the DNP master 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 routing table. Reads an extended entry from the DNP dnpReadRoutingTableEntry_DialStrings Reads a primary and secondary dial string from an entry in the DNP routing table. dnpReadRoutingTableSize table. dnpSaveAI16Config Document (Version 2.22) 10/26/2012 Reads the total number of entries in the routing Sets the configuration of a DNP 16-bit analog input point. 81 Overview of Programming Functions dnpSaveAI32Config Sets the configuration of a DNP 32-bit analog input point. dnpSaveAISFConfig Sets the configuration of a DNP 32-bit short floating analog input point dnpSaveAO16Config 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. dnpSaveBIConfig Sets the configuration of a DNP binary input point. dnpSaveBOConfig Sets the configuration of a DNP binary output point. dnpSaveCI16Config Sets the configuration of a DNP 16-bit counter input point. dnpSaveCI32Config 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 layer configuration. dnpWriteMasterPollTableEntry table. dnpWriteRoutingTableEntry Writes DNP Master application Writes an entry in the DNP master poll Writes an entry in the DNP routing table. dnpWriteRoutingTableEntryEx routing table. Writes an extended entry in the DNP dnpWriteRoutingTableEntry_DialStrings Writes a primary and secondary dial string into an entry in the DNP routing Document (Version 2.22) 10/26/2012 82 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. PPP Communication Protocol PPP, the Point-to-Point Network Protocol, is a standards-based communications protocol developed to achieve interoperability among systems. PPP Communication Protocol Functions There are several library functions related to PPP communication protocol. Refer to the Function Specification section for details on each function listed. pppGetInterfaceHandle Returns PPP interface handle for the specified serial port. pppReadSettings Reads the PPP settings for the specified serial port. pppReadUserTableEntry Reads the entry at index from the PPP username table. pppReadUserTableSize Returns the number of entries in the PPP username table. pppWriteSettings Writes the PPP settings for the specified serial port. pppWriteUserTableEntry table. Writes an entry at index into the PPP username pppWriteUserTableSize Writes the size of the PPP username table. PPP Communication Protocol Structures and Types The ctools.h file defines the structure PPP_LOGIN_TYPE and enumerated type PPP_STRUCTURE. Refer to the C Tools Structures and Types section for complete information on structures and enumeration types. DF1 Communication Protocol The TeleBUS DF1 protocol supports the DF1 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 pollABSlave Document (Version 2.22) 10/26/2012 Reads DF1 protocol configuration parameters. Requests a response from a slave controller using the half-duplex version of the protocol. 83 Overview of Programming Functions resetAllABSlaves Clears responses from the response buffers of halfduplex slave controllers. setABConfiguration Defines DF1 protocol configuration parameters. TCP/IP Communications The SCADAPack 32 and SCADAPack 32P controllers have one 10BaseT Ethernet port. 10BaseT is a single communications channel running at 10MHz over unshielded, twisted - pair cabling. TCP/IP Functions 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. ethernetGetMACAddress 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/. 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 Set Modbus IP protocol settings. mTcpGetConfig Get Modbus IP protocol settings. mTcpSetInterface Set interface settings used by the Modbus IP protocols. mTcpGetInterface Get interface settings used by the Modbus IP protocols. mTcpSetInterfaceEx Set interface settings used by the Modbus IP protocols including Enron Modbus settings. mTcpGetInterfaceEx Get interface settings used by the Modbus IP protocols including Enron Modbus settings. mTcpSetProtocol Get interface settings used by the Modbus IP protocols. mTcpGetProtocol Get interface settings used by the Modbus IP protocols. Document (Version 2.22) 10/26/2012 84 Overview of Programming Functions 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 end the task. mTcpMasterClose Returns a master connection ID to the connection pool. 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 SCADPack32 TCP/IP Stack. Refer to the Function Specification section for details on each function listed. accept tfIoctl bind tfRead connect tfWrite getpeername writev getsockname tfBindNoCheck getsockopt tfBlockingState htonl tfFreeZeroCopyBuffer htons tfGetOobDataOffset inet_addr tfGetSocketError inet_aton tfGetSendCompltBytes listen tfGetWaitingBytes ntohl tfGetZeroCopyBuffer ntohs tfInetToAscii readv tfResetConnection recv tfSocketArrayWalk recvfrom tfZeroCopyRecv rresvport tfZeroCopyRecvFrom select tfZeroCopySend send tfZeroCopySendTo sendto tfRegisterSocketCB Document (Version 2.22) 10/26/2012 85 Overview of Programming Functions setsockopt tfRegisterSocketCBParam shutdown tfPingOpenStart socket tfPingClose tfClose tfPingGetStatistics tfGetPppDnsIpAddress tfGetPppPeerIpAddress tfPppSetOption tfSetPppPeerIpAddress tfUseDialer tfDialerAddSendExpect tfDialerAddExpectSend Modbus I/O Database The Modbus database is a user-defined database that allows data to be shared between Telepace or IEC 61131-3 programs, C++ programs and communication protocols. Telepace and IEC 61131-3 firmware support different ranges of Modbus Database registers. The following table shows the register ranges for these firmware types. Telepace Modbus Addresses IEC 61131-3 Modbus Addresses Data Type 00001 to 04096 00001 to 09999 10001 to 14096 10001 to 19999 30001 to 39999 30001 to 39999 40001 to 49999 40001 to 49999 Coil Register 1 returned if variable is non-zero; 0 returned if variable is 0 Status Register 1 returned if variable is non-zero; 0 returned if variable is 0 Input Register word (16 bits) Holding Register 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 I/O 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. Document (Version 2.22) 10/26/2012 86 Overview of Programming Functions Status Registers Status, or digital input, database registers may be assigned to 5000 I/O 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 to 5000 I/O 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 Holding, or analog output, database registers may be assigned to 5000 I/O 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 Reads a value from the database. installDbaseHandler Allows an extension to be defined for the dbase function. installSetdbaseHandler Allows an extension to be defined for the setdbase function. Dbase Handler Function User-defined function that handles reading of Modbus addresses not assigned in the IEC 61131-3 Dictionary. setdbase Writes a value to the database. Setdbase Handler Function User-defined function that handles writing to Modbus addresses not assigned in the IEC 61131-3 Dictionary. Modbus I/O Database Macros 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 addressing. 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. Document (Version 2.22) 10/26/2012 87 Overview of Programming Functions 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. 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 All 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 userassigned registers in the I/O database. The Register Assignment assigns I/O database registers to user-assigned registers using I/O modules. An I/O Module can refer to an actual I/O hardware module (e.g. 5401 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 prevents 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 Document (Version 2.22) 10/26/2012 Adds one I/O module to the current Register Assignment. 88 Overview of Programming Functions getIOErrorIndication Gets the control flag for the I/O module error indication getOutputsInStopMode Gets the control flags for state of Outputs in Ladders Stop Mode setIOErrorIndication 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 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. 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-3 Variable Access Functions Variables declared in an IEC 61131-3 application are accessed from a C application using the IEC 61131-3 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. writeIntVariable Writes to the specified integer variable. writeRealVariable Writes to the specified real variable. writeMsgVariable Writes to the specified message variable. writeTimerVariable Writes to the specified timer variable. HART Communication The HART ® protocol is a field bus protocol for communication with smart transmitters. Document (Version 2.22) 10/26/2012 89 Overview of Programming Functions The HART protocol driver provides communication between Micro16 and SCADAPack 32 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. hartIO Reads data from the 5904 interface module, processes HART responses, processes HART commands, and writes commands and configuration data to the 5904 interface module. hartCommand send a HART command string and specify a function to handle the response hartCommand0 read unique identifier using short-address algorithm hartCommand1 read primary variable hartCommand2 read primary variable current and percent of span hartCommand3 read primary variable current and dynamic variables hartCommand11 read unique identifier associated with tag hartCommand33 read specified transmitter variables hartStatus return status of last HART command sent hartGetConfiguration read HART module settings hartSetConfiguration write HART module settings hartPackString convert string to HART packed string hartUnpackString convert HART packed string to string HART Command Macros The ctools.h file defines the following macro of interest to a C application program. Refer to the C Tools Macros section for details. DATA_SIZE Maximum length of the HART command or response field. HART Command Enumeration Types 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. Document (Version 2.22) 10/26/2012 90 Overview of Programming Functions 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. The HART_DEVICE type is a structure containing information about the HART device. The HART_VARIABLE type is a structure containing a variable read from a HART device. The HART_SETTINGS type is a structure containing the configuration for the HART modem module. The HART_COMMAND type is a structure containing a command to be sent to a HART slave device. The HART_RESPONSE type is a structure containing a response from a HART slave device. Document (Version 2.22) 10/26/2012 91 Function Specifications Function Specifications This section of the user manual contains specifications for using each of the available functions. Document (Version 2.22) 10/26/2012 92 Function Specifications accept Syntax include <ctools.h> int accept ( int socketDescriptor, struct sockaddr * addressPtr, int * addressLengthPtr ); Function 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 accept. Using tfRegisterSocketCB (prior to calling accept): Alternatively, the user could issue a tfregisterSocketCB call on the listening socket with a TM_CB_ACCEPT event flag to get an asynchronous notification of an incoming connection request. Again, this will only indicate that a connection request is pending; it is still necessary to call accept after having received the asynchronous notification. 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. Document (Version 2.22) 10/26/2012 93 Function Specifications Returns New Socket Descriptor or –1 on error. If accept fails, the errorCode can be retrieved with tfGetSocketError (socketDescriptor) which will return one of the following error codes: TM_EBADF The socket descriptor is invalid. TM_EINVAL addressPtr was a null pointer. TM_EINVAL addressLengthPtr was a null pointer. TM_EINVAL The value of addressLengthPtr was too small. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_EPERM Cannot call accept without calling listen first. TM_EOPNOTSUPP The referenced socket is not of type SOCK_STREAM. TM_EPROTO A protocol error has occurred; for example, the connection has already been released. TM_EWOULDBLOCK The socket is marked as non-blocking and no connections are present to be accepted. Document (Version 2.22) 10/26/2012 94 Function Specifications addRegAssignment Add Register Assignment (Telepace firmware only) Syntax #include <ctools.h> BOOLEAN addRegAssignment( UINT16 moduleType, UINT16 moduleAddress, UINT16 startingRegister1, 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 moduleType: AIN_520xTemperature AIN_520xRAMBattery AIN_5501 AIN_5502 AIN_5503 AIN_5504 AIN_5521 AIN_generic8 AOUT_5301 AOUT_5302 AOUT_5304 AOUT_generic2 AOUT_generic4 CNFG_5904Modem CNFG_clearPortCounters CNFG_clearProtocolCounters CNFG_IPSettings CNFG_LEDPower CNFG_modbusIpProtocol CNFG_MTCPIfSettings CNFG_MTCPSettings CNFG_PIDBlock CNFG_portSettings CNFG_protocolExtended CNFG_protocolExtendedEx CNFG_protocolSettings Document (Version 2.22) 10/26/2012 DIAG_controllerStatus DIAG_forceLED DIAG_IPConnections DIAG_ModbusStatus DIAG_protocolStatus DIN_520xDigitalInputs DIN_520xInterruptInput DIN_520xOptionSwitches DIN_5401 DIN_5402 DIN_5403 DIN_5404 DIN_5405 DIN_5414 DIN_5421 DIN_generic16 DIN_generic8 DIN_SP32OptionSwitches DOUT_5401 DOUT_5402 DOUT_5406 DOUT_5407 DOUT_5408 DOUT_5409 DOUT_5411 DOUT_5415 95 Function Specifications CNFG_realTimeClock DOUT_generic16 CNFG_saveToEEPROM DOUT_generic8 CNFG_setSerialPortDTR SCADAPack_AOUT CNFG_storeAndForward SCADAPack_lowerIO CNTR_520xCounterInputs SCADAPack_upperIO CNTR_5410 SCADAPack_LPIO CNFG_DeviceConfig SCADAPack_100IO DIAG_commStatus SCADAPack_5604IO SCADAPack_5604V1 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 com1, 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 moduleAddress. 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. 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 I/O activity. To obtain error checking that prevents 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 Document (Version 2.22) 10/26/2012 96 Function Specifications 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 IO_SYSTEM resource needs to be requested before calling this function. See Also clearRegAssignment Example #include <ctools.h> void main(void) { request_resource(IO_SYSTEM); /* Create the Register Assignment */ clearRegAssignment(); addRegAssignment(SCADAPack_lowerIO, 0, 1, 10001, 30001, 0); addRegAssignment(SCADAPack_AOUT, 0, 40001, 0,0, 0); addRegAssignment(AOUT_5302, 1, 40003, 0, 0, 0); addRegAssignment(DIAG_forceLED, -1, 10017, 0,0, 0); addRegAssignment(DIAG_controllerStatus, -1, 30009, 0, 0, 0); addRegAssignment(DIAG_protocolStatus, 2, 30010,0, 0, 0); release_resource(IO_SYSTEM); // save register assignment with controller settings request_resource(FLASH_MEMORY); flashSettingsSave(CS_PERMANENT); release_resource(FLASH_MEMORY); } Document (Version 2.22) 10/26/2012 97 Function Specifications addRegAssignmentEx Add Extended Register Assignment (Telepace firmware only) Syntax #include <ctools.h> BOOLEAN addRegAssignmentEx( UINT16 moduleType, UINT16 moduleAddress, UINT16 startingRegister1, UINT16 startingRegister2, UINT16 startingRegister3, UINT16 startingRegister4, UINT16 parameters[16] ); 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 AIN_520xRAMBattery AIN_5501 AIN_5502 AIN_5503 AIN_5504 AIN_5521 AIN_generic8 AOUT_5301 AOUT_5302 AOUT_5304 AOUT_generic2 AOUT_generic4 CNFG_5904Modem CNFG_clearPortCounters CNFG_clearProtocolCounters CNFG_IPSettings CNFG_LEDPower CNFG_modbusIpProtocol CNFG_MTCPIfSettings CNFG_MTCPSettings CNFG_PIDBlock CNFG_portSettings CNFG_protocolExtended CNFG_protocolExtendedEx CNFG_protocolSettings Document (Version 2.22) 10/26/2012 DIAG_controllerStatus DIAG_forceLED DIAG_IPConnections DIAG_ModbusStatus DIAG_protocolStatus DIN_520xDigitalInputs DIN_520xInterruptInput DIN_520xOptionSwitches DIN_5401 DIN_5402 DIN_5403 DIN_5404 DIN_5405 DIN_5414 DIN_5421 DIN_generic16 DIN_generic8 DIN_SP32OptionSwitches DOUT_5401 DOUT_5402 DOUT_5406 DOUT_5407 DOUT_5408 DOUT_5409 DOUT_5411 DOUT_5415 98 Function Specifications CNFG_realTimeClock DOUT_generic16 CNFG_saveToEEPROM DOUT_generic8 CNFG_setSerialPortDTR SCADAPack_AOUT CNFG_storeAndForward SCADAPack_lowerIO CNTR_520xCounterInputs SCADAPack_upperIO CNTR_5410 SCADAPack_LPIO CNFG_DeviceConfig SCADAPack_100IO DIAG_commStatus SCADAPack_5604IO SCADAPack_5604V1 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 com1, 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 moduleAddress. 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. Most 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: • 0 = DC • 1 = AC 5414 I/O Module: parameter [1] defines the scan frequency for AC inputs. Valid values are: • 0 = 60 Hz • 1 = 50 Hz 5505 I/O Module: parameters[0] to [3] define the analog input type for the corresponding input. Valid values are: • 0 = RTD in deg Celsius Document (Version 2.22) 10/26/2012 99 Function Specifications • 1 = RTD in deg Fahrenheit • 2 = RTD in deg Kelvin • 3 = resistance measurement in ohms. 5505 I/O Module: parameters[4] defines the analog input filter. Valid values are: • 0 = 0.5 s • 1=1s • 2=2s • 3=4s 5506 I/O Module: parameters[0] to [7] define the analog input type for the corresponding input. Valid values are: • 0 = 0 to 5 V input • 1 = 1 to 5 V input • 2 = 0 to 20 mA input • 3 = 4 to 20 mA input 5506 I/O Module: parameters[8] defines the analog input filter. Valid values are: • 0 = < 3 Hz (maximum filter) • 1 = 6 Hz • 2 = 11 Hz • 3 = 30 Hz (minimum filter) 5506 I/O Module: parameters[9] defines the scan frequency. Valid values are: • 0 = 60 Hz • 1 = 50 Hz 5606 I/O Module: parameters[0] to [7] define the analog input type for the corresponding input. Valid values are: • 0 = 0 to 5 V input • 1 = 1 to 5 V input • 2 = 0 to 20 mA input • 3 = 4 to 20 mA input 5606 I/O Module: parameters[8] defines the analog input filter. Valid values are: • 0 = < 3 Hz (maximum filter) • 1 = 6 Hz • 2 = 11 Hz Document (Version 2.22) 10/26/2012 100 Function Specifications • 3 = 30 Hz (minimum filter) 5606 I/O Module: parameters[9] defines the scan frequency. Valid values are: • 0 = 60 Hz • 1 = 50 Hz 5606 I/O Module: parameters[10] defines the analog output type. Valid values are: • 0 = 0 to 20 mA output • 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. 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 prevents 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 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 <ctools.h> void main(void) { UINT16 parameters[16]; Document (Version 2.22) 10/26/2012 101 Function Specifications request_resource(IO_SYSTEM); /* Create the Register Assignment */ clearRegAssignment(); /* add a 5606 module */ parameters[0] = 0; // 0 to 5 V parameters[1] = 0; // 0 to 5 V parameters[2] = 0; // 0 to 5 V parameters[3] = 0; // 0 to 5 V 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_5606IO, 0, 1, 10001, 30001, 40001, parameters); release_resource(IO_SYSTEM); // save register assignment with controller settings request_resource(FLASH_MEMORY); flashSettingsSave(CS_PERMANENT); release_resource(FLASH_MEMORY); } Document (Version 2.22) 10/26/2012 102 Function Specifications alarmIn Determine Alarm Time from Elapsed Time Syntax #include <ctools.h> 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 be requested before calling this function. See Also setClockAlarm Document (Version 2.22) 10/26/2012 103 Function Specifications allocate_envelope Obtain an Envelope from the RTOS Syntax #include <ctools.h> envelope *allocate_envelope(void); Description The 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 deallocated. Envelopes may be reused. See Also deallocate_envelope Example #include <ctools.h> extern UINT32 other_task_id; void task1(void) { envelope *letter; /* send a message to another task */ /* assume it will deallocate the envelope */ letter = allocate_envelope(); letter->destination = other_task_id; letter->type = MSG_DATA; letter->data = 5; send_message(letter); /* receive a message from any other task */ letter = receive_message(); /* ... process the data here */ deallocate_envelope(letter); /* ... the rest of the task */ } Document (Version 2.22) 10/26/2012 104 Function Specifications allocateMemory Allocate Non-Volatile Dynamic Memory Syntax #include <ctools.h> 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 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 nonvolatile data section. Otherwise they will be initialised at reset and the nonvolatile 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 2.22) 10/26/2012 105 Function Specifications bind Bind an address to an unnamed socket Syntax #include <ctools.h> int bind( int socketDescriptor, const struct sockaddr * addressPtr, int addressLength); Function 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 addressPtr be assigned to the socket. Clients do not normally require 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. Binding to the TM_WILD_PORT port number allows a server to listen for incoming connection requests on all the ports. 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: TM_EADDRINUSE The specified address is already in use. TM_EBADF socketDescriptor is not a valid descriptor. TM_EINVAL One of the passed parameters is invalid, or socket is already bound. TM_EINPROGRESS bind is already running. Document (Version 2.22) 10/26/2012 106 Function Specifications check_error Get Error Code for Current Task Syntax #include <ctools.h> 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. See Also report_error Document (Version 2.22) 10/26/2012 107 Function Specifications checksum Calculate a Checksum Syntax #include <ctools.h> 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 CRC_16 CRC_CCITT BYTE_EOR 16 bit byte-wise sum CRC-16 polynomial checksum CRC-CCITT polynomial checksum 8 bit byte-wise exclusive OR The CRC checksums use the crc_reverse function. Example This function displays two types of checksums. #include <ctools.h> void checksumExample(void) { char str[] = "This is a test"; UINT16 sum; /* Display additive checksum */ sum = checksum(str, str+strlen(str), ADDITIVE); printf("Additive checksum: %u\r\n", sum); /* Display CRC-16 checksum */ sum = checksum(str, str+strlen(str), CRC_16); printf("CRC-16 checksum: %u\r\n", sum); } Document (Version 2.22) 10/26/2012 108 Function Specifications checkSFTranslationTable Test for Store and Forward Configuration Errors Syntax #include <ctools.h> 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 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. Result code Meaning SF_VALID SF_NO_TRANSLATION All translations are valid The entry defines re-transmission of the same message on the same port One or both of the interfaces is not valid SF_PORT_OUT_OF_RANG E SF_STATION_OUT_OF_R ANGE SF_ALREADY_DEFINED SF_INVALID_FORWARDIN G_IP One or both of the stations is not valid The translation already exists in the table The forwarding IP address is invalid. Notes The TeleBUS Protocols User Manual describes store and forward messaging mode. See Also checkSFTranslationTable Example See the example for the setSFTranslationEx function. Document (Version 2.22) 10/26/2012 109 Function Specifications clearAllForcing Clear All Forcing (Telepace firmware only) Syntax #include <ctools.h> void clearAllForcing(void); Description The clearAllForcing function removes all forcing conditions from all I/O database registers. The IO_SYSTEM resource needs to be requested before calling this function. See Also setForceFlag, getForceFlag, overrideDbase Document (Version 2.22) 10/26/2012 110 Function Specifications clearBreakCondition Clear a break condition on a serial port. Syntax #include <ctools.h> void clearBreakCondition( FILE *stream ); Parameters stream is a pointer to a serial port; valid serial ports are com1, com2, com3, 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 2.22) 10/26/2012 111 Function Specifications clear_errors Clear Serial Port Error Counters Syntax #include <ctools.h> void clear_errors(FILE *stream); Description The clear_errors function clears the serial port error counters for the serial port specified by stream. If stream does not point to a valid serial port the function has no effect. The IO_SYSTEM resource needs to be requested before calling this function. Document (Version 2.22) 10/26/2012 112 Function Specifications clear_protocol_status Clear Protocol Counters Syntax #include <ctools.h> void clear_protocol_status(FILE *stream); Description The clear_protocol_status function clears the error and message counters for the serial port specified by stream. If stream does not point to a valid serial port the function has no effect. The IO_SYSTEM resource needs to be requested before calling this function. Document (Version 2.22) 10/26/2012 113 Function Specifications clearRegAssignment Clear Register Assignment (Telepace firmware only) Syntax #include <ctools.h> 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 IO_SYSTEM resource needs to be requested before calling this function. See Also addRegAssignment Example See example for addRegAssignment. Document (Version 2.22) 10/26/2012 114 Function Specifications clearSFTranslationTable Clear Store and Forward Translation Configuration Syntax #include <ctools.h> 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 checkSFTranslationTable Document (Version 2.22) 10/26/2012 115 Function Specifications clearStatusBit Clear Bits in Controller Status Code Syntax #include <ctools.h> 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 approximately 1/2 of a second indicates a binary one. The least significant digit is output first. As few bits as possible are displayed, 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. See Also setStatusBit, getStatusBit Document (Version 2.22) 10/26/2012 116 Function Specifications clear_tx Clear Serial Port Transmit Buffer Syntax #include <ctools.h> void clear_tx(FILE *stream); Description The clear_tx function clears the transmit buffer for the serial port specified by stream. If stream does not point to a valid serial port the function has no effect. Document (Version 2.22) 10/26/2012 117 Function Specifications configurationRegisterMapping Enable or disable mapping of device configuration registers. Syntax #include <ctools.h> void configurationRegisterMapping( BOOLEAN enabled ); 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 2.22) 10/26/2012 118 Function Specifications configurationSetApplicationID Set an application ID. Syntax #include <ctools.h> BOOLEAN configurationSetApplicationID( UINT16 applicationType, UINT16 action, UINT16 companyID, UINT16 application, UINT16 version ); Description This function stores or removes an application ID in the device configuration data. The device configuration 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. • DCAT_LOGIC1: Device configuration application type is the first logic application. • DCAT_LOGIC2: Device configuration application type is the second logic application. • 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. • 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). • 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. Document (Version 2.22) 10/26/2012 119 Function Specifications 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 was successful, and FALSE if an error occurred. Register Mapping The Device configuration is stored in Modbus input (3xxxx) 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. Data Type Description uint uchar type[n] Unsigned 16–bit integer Unsigned 8–bit character 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-3 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. Register Data Type Description 39800 uchar[8] 39808 39809 39810 39813 39816 uint uint uint[3] uint[3] uint 39817 39820 39823 39826 uint[3] uint[3] uint[3] uint[3] Controller ID (padded with nulls = 0), first byte in lowest register, one byte per register. Firmware version (major*100 + minor) Firmware version build number (if applicable) Logic application 1 identifier (see format below) Logic application 2 identifier (see format below) Number of applications identifiers used (0 to 32) Identifiers are listed sequentially starting with identifier 1. Unused identifiers will return 0. Application identifier 1 (see format below) Application identifier 2 (see format below) Application identifier 3 (see format below) Application identifier 4 (see format below) Document (Version 2.22) 10/26/2012 120 Function Specifications Register Data Type Description 39829 39832 39835 39838 39841 39844 39847 39850 39853 39856 39859 39862 39865 39868 39871 39874 39877 39880 39883 39886 39889 39892 39895 39898 39901 39904 39907 39910 39913 to 39999 uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] uint[3] Application identifier 5 (see format below) Application identifier 6 (see format below) Application identifier 7 (see format below) Application identifier 8 (see format below) Application identifier 9 (see format below) Application identifier 10 (see format below) Application identifier 11 (see format below) Application identifier 12 (see format below) Application identifier 13 (see format below) Application identifier 14 (see format below) Application identifier 15 (see format below) Application identifier 16 (see format below) Application identifier 17 (see format below) Application identifier 18 (see format below) Application identifier 19 (see format below) Application identifier 20 (see format below) Application identifier 21 (see format below) Application identifier 22 (see format below) Application identifier 23 (see format below) Application identifier 24 (see format below) Application identifier 25 (see format below) Application identifier 26 (see format below) Application identifier 27 (see format below) Application identifier 28 (see format below) Application identifier 29 (see format below) Application identifier 30 (see format below) Application identifier 31 (see format below) Application identifier 32 (see format below) Reserved for future expansion Application Identifier The application identifier is formatted as follows. Data Type Description uint uint uint Company ID (see below) Application number (0 to 65535) Application version (major*100 + minor) Document (Version 2.22) 10/26/2012 121 Function Specifications Company Identifier Control Microsystems will maintain a list of company identifiers to ensure the company ID 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 2.22) 10/26/2012 122 Function Specifications connect Syntax #include <ctools.h> int connect ( int socketDescriptor, const struct sockaddr * addressPtr, int addressLength ); Function 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. addressPtr 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 provider. 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. A non –blocking connect is allowed. In this case, if the connection has not been established, the connect call will fail with a TM_EINPROGRESS error code. Additional calls to connect will fail with TM_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. Non-blocking connect and select: Alternatively, the user could call select after having issued connect with the write mask for that socket descriptor to check when the connection completes. Non-blocking connect and tfRegisterSocketCB: Alternatively, the user could have issued a tfregisterSocketCB call with a TM_CB_CONNECT_COMPLT event flag prior to issuing a non-blocking connect, to get an asynchronous notification of the completion of the connect call. 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. Document (Version 2.22) 10/26/2012 123 Function Specifications Returns 0 Success -1 An error occurred. connect can fail for any of the following reasons: TM_EADDRINUSE The socket address is already in use. The calling program should close the socket descriptor, and issue another socket call to obtain a new descriptor before attempting another connect call. TM_EADDRNOTAVAIL The specified address is not available on the remote / local machine. TM_EAFNOSUPPORT Addresses in the specified address family cannot be used with this socket. TM_EINPROGRESS The socket is non-blocking and the current connection attempt has not yet been completed. TM_EALREADY The socket is non-blocking and a previous connection attempt has not yet been completed. TM_EBADF socketDescriptor is not a valid descriptor. TM_ECONNREFUSED 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. TM_EPERM Cannot call connect after listen call. TM_EINVAL One of the parameters is invalid TM_EISCONN 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. TM_EHOSTUNREACH No route to the host we want to connect to. TM_EPROTOTYPE The socket referred to by addressPtr 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). TM_ETIMEDOUT 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 2.22) 10/26/2012 124 Function Specifications crc_reverse Calculate a CRC Checksum Syntax #include <ctools.h> 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 for 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 2.22) 10/26/2012 125 Function Specifications create_task Create a New Task Syntax #include <ctools.h> INT32 create_task(void *function, UINT32 priority, UINT32 type, UINT32 stack); Description The create_task function allocates stack 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 higher than the current task. priority is an execution priority between 1 and 4 for the created task. The 4 task priority levels aid in scheduling task execution. 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 APPLICATION application tasks terminate when the program stops 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 256 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 1. If the created task is continuously running processing code, create the task with a priority of 1 and call release_processor periodically; otherwise the remaining priority 1 tasks will be blocked from executing. For tasks such as a protocol handler, that wait for an event using the wait_event or receive_message function, a priority greater than 1 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. Most tasks require 2 stack blocks. If any of the printf functions are used, then at least 4 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 best 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.) Document (Version 2.22) 10/26/2012 126 Function Specifications 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 2.22) 10/26/2012 127 Function Specifications databaseRead Read Value from I/O Database Syntax #include <ctools.h> BOOLEAN databaseRead(UINT16 addrMode, UINT16 address, INT16 * value); Description The databaseRead function reads a value from 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 to 40000 + NUMHOLDING 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR 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 IO_SYSTEM resource needs to be requested before calling this function. See Also databaseWrite Document (Version 2.22) 10/26/2012 128 Function Specifications databaseWrite Write Value to I/O Database Syntax #include <ctools.h> 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 to 40000 + NUMHOLDING 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR 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 IO_SYSTEM resource needs to be requested before calling this function. See Also databaseRead Document (Version 2.22) 10/26/2012 129 Function Specifications datalogCreate Create Data Log Function Syntax #include <ctools.h> DATALOG_STATUS datalogCreate( UINT16 logID, 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. logID 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_EXISTS. 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 datalogDelete datalogSettings Example This program creates a data log and writes one record to it. #include <ctools.h> /* Structure used to copy one record into data log */ struct dataRecord { UINT16 value1; INT32 value2; double value3; float value4; Document (Version 2.22) 10/26/2012 130 Function Specifications float value5; }; void main(void) { UINT16 logID; DATALOG_CONFIGURATION dLogConfig; /* log configuration */ struct dataRecord data; /* sample record */ /* Assign a number to the data log */ logID = 10; /* Fill in the log configuration structure */ dLogConfig.records = 200; dLogConfig.fields = 5; dLogConfig.typesOfFields[0] = DLV_UINT16; dLogConfig.typesOfFields[1] = DLV_INT32; dLogConfig.typesOfFields[2] = DLV_DOUBLE; dLogConfig.typesOfFields[3] = DLV_FLOAT; dLogConfig.typesOfFields[4] = DLV_FLOAT; /* Assign some data for the log */ data.value1 = 100; data.value2 = 200; data.value3 = 30000; data.value4 = 40; data.value5 = 50; if(datalogCreate(logID, &dLogConfig) == DLS_CREATED) { /* Start writing records in log */ if(datalogWrite(logID, (UINT16 *)&data) ) { /* one record was written in data log */ } } } Document (Version 2.22) 10/26/2012 131 Function Specifications datalogDelete Delete Data Log Function Syntax #include <ctools.h> BOOLEAN datalogDelete(UINT16 logID); Description This function destroys the specified data log. The memory used by the data log is returned to the freed. The function has one parameter. logID 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. See Also datalogCreate Example 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 <ctools.h> void main(void) { UINT16 logID; DATALOG_CONFIGURATION dLogConfig; /* Select logID #10 */ logID = 10; /* Read the configuration of logID #10 */ if(datalogSettings(logID, &dLogConfig)) { if(dLogConfig.typesOfFields[0] == DLV_INT16) { /* Wrong type. Delete log and create new one */ if(datalogDelete(logID) ) { /* Re-enter the log configuration */ dLogConfig.records = 200; dLogConfig.fields = 5; dLogConfig.typesOfFields[0] = DLV_UINT16; dLogConfig.typesOfFields[1] = DLV_INT32; dLogConfig.typesOfFields[2] = DLV_DOUBLE; dLogConfig.typesOfFields[3] = DLV_FLOAT; dLogConfig.typesOfFields[4] = DLV_FLOAT; Document (Version 2.22) 10/26/2012 132 Function Specifications datalogCreate(logID, &dLogConfig); } else { /* could not delete log */ } } } else { /* Could not read settings */ } } Document (Version 2.22) 10/26/2012 133 Function Specifications datalogPurge Purge Data Log Function Syntax #include <ctools.h> BOOLEAN datalogPurge( UINT16 logID, 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. logID 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 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 datalogReadStart, datalogReadNext, datalogWrite Example #include <ctools.h> void main(void) { UINT16 logID; UINT32 sequenceNumber; BOOLEAN purgeAll; /* select data log to be purged */ logID = 10; /* set flag to purge only part of data log */ purgeAll = FALSE; Document (Version 2.22) 10/26/2012 134 Function Specifications /* 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 2.22) 10/26/2012 135 Function Specifications datalogReadNext Read Data Log Next Function This function returns the next record in the data log. Syntax #include <ctools.h> BOOLEAN datalogReadNext( UINT16 logID, UINT32 sequenceNumber, UINT32 * pSequenceNumber, UINT32 * pNextSequenceNumber, UINT16 * pData); Description 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. logID 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 read 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 2.22) 10/26/2012 136 Function Specifications See Also datalogReadStart, datalogPurge, datalogWrite Example See the example for datalogReadStart. Document (Version 2.22) 10/26/2012 137 Function Specifications datalogReadStart Read Data Log Start Function Syntax #include <ctools.h> BOOLEAN datalogReadStart( UINT16 logID, 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. logID 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 datalogReadNext, datalogPurge, datalogWrite Example #include <ctools.h> #include <stdlib.h> void 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 */ if(datalogReadStart(logID, &sequenceNumber)) { /* Get the size of this record */ if(datalogRecordSize(logID, &recordSize)) { /* allocate memory of size recordSize */ pData = (UINT16 *)malloc(recordSize); Document (Version 2.22) 10/26/2012 138 Function Specifications /* read this record */ if(datalogReadNext(logID, sequenceNumber, &seqNumRead, &nextSeqNum, pData)) { /* use pData to access record contents */ } } } } Document (Version 2.22) 10/26/2012 139 Function Specifications datalogRecordSize Data Log Record Size Function Syntax #include <ctools.h> 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. logID 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 useful in determining how much memory needs to be allocated for a call to datalogReadNext or datalogWrite. See Also datalogCreate, datalogSettings Example See the example for datalogReadStart. Document (Version 2.22) 10/26/2012 140 Function Specifications datalogSettings Data Log Settings Function Syntax #include <ctools.h> 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. logID 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 datalogCreate, datalogRecordSize Example See example for datalogDelete. Document (Version 2.22) 10/26/2012 141 Function Specifications datalogWrite Write Data Log Function Syntax #include <ctools.h> BOOLEAN datalogWrite( UINT16 logID, UINT16 * pData); Description This function 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. logID 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 datalogReadStart, datalogReadNext, datalogPurge Example See the example for datalogCreate. Document (Version 2.22) 10/26/2012 142 Function Specifications dbase Read Value from I/O Database Syntax #include <ctools.h> 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 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR 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 IO_SYSTEM resource needs to be requested before calling this function. See Also setdbase Example #include <ctools.h> void 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 2.22) 10/26/2012 143 Function Specifications a = dbase(LINEAR, START_STATUS); /* Read 6th input register */ a = dbase(LINEAR, START_INPUT + 5); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 144 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-3 Dictionary. The function can have any name; dbaseHandler is used in the description below. Syntax #include <ctools.h> BOOLEAN dbaseHandler( UINT16 address, INT * value ) Description This function is called by the dbase function when one of the following conditions apply: • There is no IEC 61131-3 application downloaded, or • There is no IEC 61131-3 variable assigned to the specified Modbus address. The function has two parameters: The address parameter is the Modbus address to be read. 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 ensures that only one task may call the handler at a time. Therefore, the function does not have to be reentrant. 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 2.22) 10/26/2012 145 Function Specifications deallocate_envelope Return Envelope to the RTOS Syntax #include <ctools.h> 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 Example See the example for the allocate_envelope function. Document (Version 2.22) 10/26/2012 146 Function Specifications dnpClearEventLogs Clear DNP Event Log Syntax #include <ctools.h> BOOLEAN dnpClearEventLogs(void); Description The dnpClearEventLogs function deletes all change events from the DNP change event buffers, for all point types. Document (Version 2.22) 10/26/2012 147 Function Specifications dnpConnectionEvent Report a DNP connection event Syntax #include <ctools.h> void dnpConnectionEvent( UINT16 dnpAddress, DNP_CONNECTION_EVENT event); Description The dnpConnectionEvent function is used to report a change in connection status to DNP. 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 dnpInstallConnectionHandler example. Document (Version 2.22) 10/26/2012 148 Function Specifications dnpCreateAddressMapTable Create DNP Address Mapping Table Syntax: #include <ctools.h> BOOLEAN dnpCreateAddressMapTable ( UINT16 size, CHAR enableMapChangeEvents); Description The dnpCreateAddressMapTable 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 2.22) 10/26/2012 149 Function Specifications dnpCreateMasterPollTable Create DNP Master Poll Table Syntax #include <ctools.h> 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 create the DNP configuration. The function returns TRUE if successful, FALSE otherwise. Document (Version 2.22) 10/26/2012 150 Function Specifications dnpCreateRoutingTable Create Routing Table Syntax #include <ctools.h> 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. Document (Version 2.22) 10/26/2012 151 Function Specifications dnpGenerateChangeEvent Generate DNP Change Event Syntax BOOLEAN dnpGenerateChangeEvent( DNP_POINT_TYPE pointType, UINT16 pointAddress ); 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 AI16_POINT 16 bit analog input AI32_POINT 32 bit analog input AISF_POINT short float analog input CI16_POINT 16 bit counter output CI32_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 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 2.22) 10/26/2012 152 Function Specifications dnpGenerateEventLog Generates a change event for the DNP point Syntax #include <ctools.h> BOOLEAN dnpGenerateEventLog( 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 2.22) 10/26/2012 153 Function Specifications dnpGetAI16Config Get DNP 16-bit Analog Input Configuration Syntax #include <ctools.h> BOOLEAN dnpGetAI16Config( UINT16 point, dnpAnalogInput * pAnalogInput); Description The dnpGetAI16Config 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 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 2.22) 10/26/2012 154 Function Specifications dnpGetAI32Config Get DNP 32-bit Analog Input Configuration Syntax #include <ctools.h> BOOLEAN dnpGetAI32Config( UINT32 point, dnpAnalogInput * pAnalogInput); Description The dnpGetAI32Config 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 dnpSaveAI32Config Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 155 Function Specifications dnpGetAISFConfig Get Short Floating Point Analog Input Configuration Syntax #include <ctools.h> BOOLEAN dnpGetAISFConfig ( UINT16 point, dnpAnalogInput *pAnalogInput); Description The dnpGetAISFConfig function reads 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 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 2.22) 10/26/2012 156 Function Specifications dnpGetAO16Config Get DNP 16-bit Analog Output Configuration Syntax #include <ctools.h> 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 2.22) 10/26/2012 157 Function Specifications dnpGetAO32Config Get DNP 32-bit Analog Output Configuration Syntax #include <ctools.h> BOOLEAN dnpGetAO32Config( UINT32 point, dnpAnalogOutput * pAnalogOutput); Description 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 2.22) 10/26/2012 158 Function Specifications dnpGetAOSFConfig Get Short Floating Point Analog Output Configuration Syntax #include <ctools.h> BOOLEAN dnpGetAOSFConfig ( UINT16 point, dnpAnalogOutput *pAnalogOutput); Description The dnpGetAOSFConfig 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 2.22) 10/26/2012 159 Function Specifications dnpGetBIConfig Get DNP Binary Input Configuration Syntax #include <ctools.h> BOOLEAN dnpGetBIConfig( UINT16 point, dnpBinaryInput * pBinaryInput); Description The dnpGetBIConfig 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 dnpSaveBIConfig Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 160 Function Specifications dnpGetBIConfigEx Read DNP Binary Input Extended Point Syntax BOOLEAN dnpGetBIConfigEx( UINT16 point, dnpBinaryInputEx *pBinaryInput ); 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 2.22) 10/26/2012 161 Function Specifications dnpGetBOConfig Get DNP Binary Output Configuration Syntax #include <ctools.h> 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 2.22) 10/26/2012 162 Function Specifications dnpGetCI16Config Get DNP 16-bit Counter Input Configuration Syntax #include <ctools.h> BOOLEAN dnpGetCI16Config( UINT16 point, dnpCounterInput * pCounterInput); Description The dnpGetCI16Config 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. Notes DNP needs to be enabled before calling this function in order to create the DNP configuration. See Also dnpSaveCI16Config Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 163 Function Specifications dnpGetCI32Config Get DNP 32-bit Counter Input Configuration Syntax #include <ctools.h> BOOLEAN dnpGetCI32Config( UINT32 point, dnpCounterInput * pCounterInput); Description The dnpGetCI32Config 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 dnpSaveCI32Config Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 164 Function Specifications dnpGetConfiguration Get DNP Configuration Syntax #include <ctools.h> 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 if 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 dnpGetUnsolicitedBackoffTime 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. void main(void) { UINT16 index; /* loop index */ struct prot_settings settings; /* protocol settings */ dnpConfiguration configuration; /* configuration settings */ dnpBinaryInput binaryInput; /* binary input settings */ dnpBinaryOutput binaryOutput; /* binary output settings */ dnpAnalogInput analogInput; /* analog input settings */ dnpAnalogOutput analogOutput; /* analog output settings */ dnpCounterInput counterInput; /* counter input settings */ /* Stop any protocol currently active on com port 2 */ get_protocol(com2,&settings); settings.type = NO_PROTOCOL; set_protocol(com2,&settings); /* Load the Configuration Parameters */ configuration.masterAddress = DEFAULT_DNP_MASTER; configuration.rtuAddress = DEFAULT_DNP_RTU; configuration.datalinkConfirm = TRUE; configuration.datalinkRetries = DEFAULT_DLINK_RETRIES; Document (Version 2.22) 10/26/2012 165 Function Specifications configuration.datalinkTimeout = DEFAULT_DLINK_TIMEOUT; configuration.operateTimeout configuration.applicationConfirm configuration.maximumResponse configuration.applicationRetries configuration.applicationTimeout configuration.timeSynchronization = = = = = = DEFAULT_OPERATE_TIMEOUT; TRUE; DEFAULT_MAX_RESP_LENGTH; DEFAULT_APPL_RETRIES; DEFAULT_APPL_TIMEOUT; TIME_SYNC; configuration.BI_number configuration.BI_cosBufferSize configuration.BI_soeBufferSize configuration.BO_number configuration.CI16_number configuration.CI16_bufferSize configuration.CI32_number configuration.CI32_bufferSize configuration.AI16_number configuration.AI16_reportingMethod configuration.AI16_bufferSize configuration.AI32_number configuration.AI32_reportingMethod configuration.AI32_bufferSize configuration.AO16_number configuration.AO32_number = = = = = = = = = = = = = = = = 8; DEFAULT_COS_BUFF; DEFAULT_SOE_BUFF; 8; 24; 48; 12; 24; 24; CURRENT_VALUE; 24; 12; CURRENT_VALUE; 12; 8; 8; configuration.unsolicited = TRUE; configuration.holdTime configuration.holdCount = DEFAULT_HOLD_TIME; = DEFAULT_HOLD_COUNT; dnpSaveConfiguration(&configuration); /* Start DNP protocol on com port 2 */ get_protocol(com2,&settings); settings.type = DNP; set_protocol(com2,&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 < configuration.BO_number; index++) { binaryOutput.modbusAddress1 = 1 + index; binaryOutput.modbusAddress2 = 1 + index; binaryOutput.controlType = NOT_PAIRED; dnpSaveBOConfig(index, &binaryOutput); } /* Configure Binary Input Points */ for (index = 0;index < configuration.BI_number; index++) Document (Version 2.22) 10/26/2012 166 Function Specifications { binaryInput.modbusAddress = 10001 + index; binaryInput.class = CLASS_1; binaryInput.eventType = COS; dnpSaveBIConfig(index, &binaryInput); } /* Configure 16 Bit Analog Input Points */ for (index = 0; index < configuration.AI16_number; index++) { analogInput.modbusAddress = 30001 + index; analogInput.class = CLASS_2; analogInput.deadband = 1; dnpSaveAI16Config(index, &analogInput); } /* Configure32 Bit Analog Input Points */ for (index = 0; index < configuration.AI32_number; index++) { analogInput.modbusAddress = 30001 + index * 2; analogInput.class = CLASS_2; analogInput.deadband = 1; dnpSaveAI32Config(index,&analogInput); } /* Configure 16 Bit Analog Output Points */ for (index = 0;index < configuration.AO16_number; index++) { analogOutput.modbusAddress = 40001 + index; dnpSaveAO16Config(index, &analogOutput); } /* Configure 32 Bit Analog Output Points */ for (index = 0; index < configuration.AO32_number; index++) { analogOutput.modbusAddress = 40101 + index * 2; dnpSaveAO32Config(index, &analogOutput); } /* Configure 16 Bit Counter Input Points */ for (index = 0; index < configuration.CI16_number; index++) { counterInput.modbusAddress = 30001 + index; counterInput.class = CLASS_3; counterInput.threshold = 1; dnpSaveCI16Config(index, &counterInput); } /* Configure 32 bit Counter Input Points */ for (index = 0; index < configuration.CI32_number; index++) Document (Version 2.22) 10/26/2012 167 Function Specifications { counterInput.modbusAddress = 30001 + index * 2; counterInput.class = CLASS_3; counterInput.threshold = 1; dnpSaveCI32Config(index, &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 2.22) 10/26/2012 168 Function Specifications dnpGetConfigurationEx Read DNP Extended Configuration Syntax BOOLEAN dnpGetConfigurationEx ( dnpConfigurationEx *pDnpConfigurationEx ); Description 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 dnpGetUnsolicitedBackoffTime to get the Unsolicited Back Off Time configuration. Document (Version 2.22) 10/26/2012 169 Function Specifications dnpGetRuntimeStatus Get DNP Runtime Status Syntax: #include <ctools.h> 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. Document (Version 2.22) 10/26/2012 170 Function Specifications dnpGetUnsolicitedBackoffTime Get DNP Unsolicited Back Off Time Syntax: #include <ctools.h> UINT16 dnpGetUnsolicitedBackoffTime(); Description: The dnpGetUnsolicitedBackoffTime function reads the unsolicited back off 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 back off timer is disabled. Document (Version 2.22) 10/26/2012 171 Function Specifications dnpInstallConnectionHandler Configures the connection handler for DNP Syntax #include <ctools.h> 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 dnpInstallConnectionHandler 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. • event is DNP event that has occurred. It may be one of DNP_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 2.22) 10/26/2012 172 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. • 10001 turns on when a connection is requested by DNP for unsolicited reporting. • 10002 turns on when the unsolicited report is complete. • 10003 turns on when the unsolicited report is fails. • The ladder logic program turns on register 1 when the connection is complete and turns off the register when the connection is broken. /* -----------------------------------------------------------------dnp.c Demonstration program for using the DNP connection handler. Copyright 2001, Control Microsystems Inc. ------------------------------------------------------------------ */ /* -----------------------------------------------------------------Include Files ------------------------------------------------------------------ */ #include <ctools.h> /* -----------------------------------------------------------------Constants ------------------------------------------------------------------ */ #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 CONNECTION_STATUS 1 /* connection status register */ /* -----------------------------------------------------------------Private Functions ------------------------------------------------------------------ */ /* -----------------------------------------------------------------sampleDNPHandler Document (Version 2.22) 10/26/2012 173 Function Specifications 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. The function takes a variable of type DNP_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). The function does not return any values. ------------------------------------------------------------------ */ static void sampleDNPHandler(DNP_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 */ request_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; } Document (Version 2.22) 10/26/2012 174 Function Specifications } /* -----------------------------------------------------------------Public Functions ------------------------------------------------------------------ */ /* -----------------------------------------------------------------main 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. ------------------------------------------------------------------ */ void 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(MODBUS, CONNECTION_STATUS); /* if the state has changed */ if (currentConnectionState != lastConnectionState) { /* if the connection is active */ if (currentConnectionState) { /* Inform DNP that a connection exists */ dnpConnectionEvent(DNP_CONNECTED); /* clear the request flag */ setdbase(MODBUS, CONNECTION_REQUIRED, 0); } Document (Version 2.22) 10/26/2012 175 Function Specifications else { /* Inform DNP that the connection is closed */ dnpConnectionEvent(DNP_DISCONNECTED); /* clear the message flags */ 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(); } } Document (Version 2.22) 10/26/2012 176 Function Specifications dnpMasterClassPoll Send DNP Class Poll Syntax BOOLEAN dnpMasterClassPoll( UINT16 slaveAddress, UINT16 classFlags ); 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 should be ORed together: CLASS0_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 available on the SCADAPack 32 only. DNP needs to be enabled before calling this function in order to create the DNP configuration. Document (Version 2.22) 10/26/2012 177 Function Specifications dnpMasterClockSync Send DNP Clock Synch Syntax BOOLEAN dnpMasterClockSync( UINT16 slaveAddress ); 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 available on the SCADAPack 32 only. DNP needs to be enabled before calling this function in order to create the DNP configuration. Document (Version 2.22) 10/26/2012 178 Function Specifications dnpPortStatus Get communication status for a port Syntax #include <ctools.h> DNP_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 CIF_Com1, 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 2.22) 10/26/2012 179 Function Specifications dnpReadAddressMappingTableEntry Read DNP Address Mapping Table entry Syntax #include <ctools.h> BOOLEAN dnpReadAddressMappingTableEntry ( UINT16 index, dnpAddressMap_type *pAddressMap ); 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 configuration. Document (Version 2.22) 10/26/2012 180 Function Specifications dnpReadAddressMappingTableSize Read DNP Address Mapping Table size Syntax #include <ctools.h> 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 2.22) 10/26/2012 181 Function Specifications dnpReadMasterPollTableEntry Read DNP Master Poll Table entry Syntax #include <ctools.h> BOOLEAN dnpReadMasterPollTableEntry ( UINT16 index, dnpMasterPoll_type *pMasterPoll ); 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 2.22) 10/26/2012 182 Function Specifications dnpReadMasterPollTableEntryEx Read DNP Master Poll Table Extended Entry Syntax BOOLEAN dnpReadMasterPollTableEntryEx ( UINT16 index, DnpMasterPollEx_type *pMasterPoll ); Description This function is available on the SCADAPack 32 only. 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 available on the SCADAPack 32 only. DNP needs to be enabled before calling this function in order to create the DNP configuration. This function supersedes the dnpReadMasterPollTableEntry function. Document (Version 2.22) 10/26/2012 183 Function Specifications dnpReadMasterPollTableSize Read DNP Master Poll Table size Syntax #include <ctools.h> 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 2.22) 10/26/2012 184 Function Specifications dnpReadRoutingTableEntry_DialStrings Read DNP Routing Table Entry Dial Strings Syntax BOOLEAN dnpReadRoutingTableEntry_DialStrings( UINT16 index, UINT16 maxPrimaryDialStringLength, CHAR *primaryDialString, UINT16 maxSecondaryDialStringLength, CHAR *secondaryDialString ); 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 prevent 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 prevent 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 2.22) 10/26/2012 185 Function Specifications dnpReadRoutingTableEntry Read Routing Table entry Syntax #include <ctools.h> BOOLEAN dnpReadRoutingTableEntry( UINT16 index, routingTable *pRoute ); Description 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 dnpWriteRoutingTableEntry Document (Version 2.22) 10/26/2012 186 Function Specifications dnpReadRoutingTableEntryEx Read Routing Table entry Syntax #include <ctools.h> BOOLEAN dnpReadRoutingTableEntryEx( UINT16 index, dnpRoutingTableEx entry ); 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 2.22) 10/26/2012 187 Function Specifications dnpReadRoutingTableSize Read Routing Table size Syntax #include <ctools.h> UINT16 dnpReadRoutingTableSize (void); Description 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 2.22) 10/26/2012 188 Function Specifications dnpSaveAI16Config Save DNP 16-Bit Analog Input Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveAI16Config( UINT16 point, dnpAnalogInput * pAnalogInput ); Description The dnpSaveAI16Config 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 2.22) 10/26/2012 189 Function Specifications dnpSaveAI32Config Save DNP 32-Bit Analog Input Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveAI32Config( UINT32 point, dnpAnalogInput * pAnalogInput ); Description The dnpSaveAI32Config 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 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 dnpGetAI32Config Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 190 Function Specifications dnpSaveAISFConfig Save Short Floating Point Analog Input Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveAISFConfig ( UINT16 point, dnpAnalogInput *pAnalogInput; ); Description The dnpSaveAISFConfig 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 2.22) 10/26/2012 191 Function Specifications dnpSaveAO16Config Save DNP 16-Bit Analog Output Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveAO16Config( UINT16 point, dnpAnalogOutput * pAnalogOutput ); 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 2.22) 10/26/2012 192 Function Specifications dnpSaveAO32Config Save DNP 32-Bit Analog Output Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveAO32Config( UINT32 point, dnpAnalogOutput * pAnalogOutput ); 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 example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 193 Function Specifications dnpSaveAOSFConfig Save Short Floating Point Analog Output Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveAOSFConfig ( UINT16 point, dnpAnalogOutput *pAnalogOutput; ); 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 2.22) 10/26/2012 194 Function Specifications dnpSaveBIConfig Save DNP Binary Input Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveBIConfig( UINT16 point, dnpBinaryInput * pBinaryInput ); Description The dnpSaveBIConfig 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 configuration 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 2.22) 10/26/2012 195 Function Specifications dnpSaveBIConfigEx Write DNP Binary Input Extended Point Syntax BOOLEAN dnpSaveBIConfigEx( UINT16 point, dnpBinaryInputEx *pBinaryInput ); 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 dnpSaveBIConfig. Document (Version 2.22) 10/26/2012 196 Function Specifications dnpSaveBOConfig Save DNP Binary Output Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveBOConfig( UINT16 point, dnpBinaryOutput * pBinaryOutput ); 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 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 2.22) 10/26/2012 197 Function Specifications dnpSaveCI16Config Save DNP 16-Bit Counter Input Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveCI16Config( UINT16 point, dnpCounterInput * pCounterInput ); Description The dnpSaveCI16Config 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 dnpGetCI16Config Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 198 Function Specifications dnpSaveCI32Config Save DNP 32-Bit Counter Input Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveCI32Config( UINT32 point, dnpCounterInput * pCounterInput ); Description The dnpSaveCI32Config 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 dnpGetCI32Config Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 199 Function Specifications dnpSaveConfiguration Save DNP Configuration Syntax #include <ctools.h> BOOLEAN dnpSaveConfiguration( dnpConfiguration * pConfiguration ); 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 dnpSaveUnsolicitedBackoffTime to save the Unsolicited Back Off Time configuration. The following parameters cannot be changed if DNP is enabled. The function will not make 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. BI_number BI_cosBufferSize BI_soeBufferSize BO_number CI16_number CI16_bufferSize CI32_number CI32_bufferSize AI16_number AI16_reportingMethod AI16_bufferSize AI32_number AI32_reportingMethod AI32_bufferSize Document (Version 2.22) 10/26/2012 200 Function Specifications AO16_number AO32_number The following parameters can be changed when DNP is enabled. masterAddress; rtuAddress; datalinkConfirm; datalinkRetries; datalinkTimeout; operateTimeout applicationConfirm maximumResponse applicationRetries applicationTimeout timeSynchronization unsolicited holdTime holdCount See Also dnpGetConfiguration Example See example in the dnpGetConfiguration function section. Document (Version 2.22) 10/26/2012 201 Function Specifications dnpSaveConfigurationEx Write DNP Extended Configuration Syntax BOOLEAN dnpSaveConfigurationEx ( dnpConfigurationEx *pDnpConfigurationEx ); 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 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 dnpSaveConfiguration function. This function does not write the configuration for the Unsolicited Back Off Time. Use the function dnpSaveUnsolicitedBackoffTime to save the Unsolicited Back Off Time configuration. Document (Version 2.22) 10/26/2012 202 Function Specifications dnpSaveUnsolicitedBackoffTime Save DNP Unsolicited Back Off Time Syntax: BOOLEAN dnpSaveUnsolicitedBackoffTime ( UINT16 backoffTime ); Description: The dnpSaveUnsolicitedBackoffTime function writes the unsolicited back off 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 back off 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 2.22) 10/26/2012 203 Function Specifications dnpSendUnsolicitedResponse Send DNP Unsolicited Response Syntax BOOLEAN dnpSendUnsolicitedResponse( UINT16 classFlags ); 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 following values; if multiple values are used they should be ORed together: CLASS0_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 response 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 2.22) 10/26/2012 204 Function Specifications dnpSearchRoutingTable Search Routing Table Syntax #include <ctools.h> BOOLEAN dnpSearchRoutingTable ( UINT16 Address routingTable *pRoute ); 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 2.22) 10/26/2012 205 Function Specifications dnpStationStatus Get communication status for a remote DNP station Syntax #include <ctools.h> DNP_PROTOCOL_STATUS dnpStationStatus( UINT16 dnpAddress, BOOLEAN clear ); 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 2.22) 10/26/2012 206 Function Specifications dnpWriteAddressMappingTableEntry Write DNP Address Mapping Table Entry Syntax #include <ctools.h> BOOLEAN dnpWriteAddressMappingTableEntry ( UINT16 index, UINT16 dnpRemoteStationAddress; CHAR dnpObjectType; UINT16 dnpRemoteObjectStart; UINT16 numberOfPoints; UINT16 dnpLocalModbusAddress; ); 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 2.22) 10/26/2012 207 Function Specifications dnpWriteMasterApplicationLayerConfig Write DNP Master Application Layer Configuration Syntax #include <ctools.h> BOOLEAN dnpWriteMasterApplicationLayerConfig( UINT16 basePollInterval, UINT16 mimicMode ); Description This function writes DNP Master application layer 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 2.22) 10/26/2012 208 Function Specifications dnpWriteMasterPollTableEntry Write DNP Master Poll Table Entry Syntax #include <ctools.h> BOOLEAN dnpWriteMasterPollTableEntry ( UINT16 index, UINT16 dnpAddress, UINT16 class0PollRate; UINT16 class1PollRate; UINT16 class2PollRate; UINT16 class3PollRate; UINT16 timeSyncRate; UINT16 unsolicitedResponseFlags; ); 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 2.22) 10/26/2012 209 Function Specifications dnpWriteMasterPollTableEntryEx Write DNP Master Poll Table Extended Entry Syntax BOOLEAN dnpWriteMasterPollTableEntryEx ( UINT16 index, DnpMasterPollEx_type *pMasterPoll ); 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 available on the SCADAPack 32 only. DNP needs to be enabled before calling this function in order to create the DNP configuration. This function supersedes the dnpWriteMasterPollTableEntry function. Document (Version 2.22) 10/26/2012 210 Function Specifications dnpWriteRoutingTableEntry_DialStrings Write DNP Routing Table Entry Dial Strings Syntax BOOLEAN dnpWriteRoutingTableEntry_DialStrings( UINT16 index, UINT16 primaryDialStringLength, CHAR *primaryDialString, UINT16 secondaryDialStringLength, CHAR *secondaryDialString ); 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 2.22) 10/26/2012 211 Function Specifications dnpWriteRoutingTableEntry Write Routing Table Entry Syntax #include <ctools.h> BOOLEAN dnpWriteRoutingTableEntry( UINT16 index, UINT16 address, UINT16 comPort, UINT16 retries, UINT16 timeout ); 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. Document (Version 2.22) 10/26/2012 212 Function Specifications dnpWriteRoutingTableEntryEx Write Routing Table Entry with Extended Information Syntax #include <ctools.h> BOOLEAN dnpWriteRoutingTableEntryEx( UINT16 index, UINT16 address, UINT16 comPort, UINT16 retries, UINT16 timeout, IP_ADDRESS ipaddress ); 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 function returns TRUE if successful, FALSE otherwise. Document (Version 2.22) 10/26/2012 213 Function Specifications end_application Terminates all Application Tasks Syntax #include <ctools.h> 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 create_task, end_task Document (Version 2.22) 10/26/2012 214 Function Specifications end_task Terminate a Task Syntax #include <ctools.h> void end_task(UINT16 task_ID); Description The end_task function terminates the task specified by task_ID. Stack space and resources used by the task are freed. The end_task function terminates both APPLICATION and SYSTEM type tasks. See Also create_task Document (Version 2.22) 10/26/2012 215 Function Specifications endTimedEvent Terminate Signaling of a Regular Event Syntax #include <ctools.h> 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 31. 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 2.22) 10/26/2012 216 Function Specifications enronInstallCommandHandler Installs handler for Enron Modbus commands. Syntax #include <ctools.h> void enronInstallCommandHandler( UINT16 (* function)( UINT16 length, UCHAR * pCommand, UINT16 responseSize, UINT16 * pResponseLength, UCHAR * pResponse ) ); Description This function installs a handler function for Enron Modbus commands. The protocol driver calls this handler function each time a command 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 prevents 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. • length is the number of characters in the command message. • 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. • responseSize is the size of the response buffer in characters. • 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. • 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 must start with the function code and end with the last Document (Version 2.22) 10/26/2012 217 Function Specifications data byte. The protocol driver will add the station address, checksum, and message framing to the response. The handler function returns the following values. Value Description NORMAL Indicates protocol handler should send a normal response message. Data are returned using pResponse and pResponseLength. 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. 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. 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. ILLEGAL_FUNCTION ILLEGAL_DATA_ADDRESS ILLEGAL_DATA_VALUE 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 <ctools.h> /* ----------------------------------------------------This function processes Enron Modbus commands. ----------------------------------------------------- */ UINT16 commandHandler( UINT16 length, UCHAR * pCommand, UINT16 responseSize, UINT16 * pResponseLength, UCHAR * pResponse ) { UCHAR command; UINT16 result; /* if a command byte was received */ if (length >= 1) Document (Version 2.22) 10/26/2012 218 Function Specifications { /* get the command byte */ command = pCommand[0]; switch (command) { /* read unit status command */ case 7: /* if the response buffer is large enough */ if (responseSize > 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 */ enronInstallCommandHandler(NULL); } void main(void) { Document (Version 2.22) 10/26/2012 219 Function Specifications TASKINFO thisTask; /* install handler to execute when this task ends */ thisTask = getTaskInfo(0); installExitHandler(thisTask.taskID, mainExitHandler); /* install handler for Enron Modbus */ enronInstallCommandHandler(commandHandler); /* infinite loop of main task */ while (TRUE) { /* add application code here */ } } Document (Version 2.22) 10/26/2012 220 Function Specifications ethernetGetIP Get Ethernet Controller TCP/IP Settings Syntax #include <ctools.h> void ethernetGetIP( IP_SETTINGS * pIPSettings ); Description The ethernetGetIP function copies the Ethernet controller TCP/IP settings into the structure pointed to by pIPSettings. The structure IP_SETTINGS is described in the Structures and Types section. See Also ethernetSetIP Document (Version 2.22) 10/26/2012 221 Function Specifications ethernetGetMACAddress Get Ethernet Controller MAC address. Syntax #include <ctools.h> void ethernetGetMACAddress( CHAR * pMAC ); Description The ethernetGetMACAddress function copies the Ethernet controller MAC address to the array pointed to by pMAC. pMAC needs to point to an array of 6 bytes. Document (Version 2.22) 10/26/2012 222 Function Specifications ethernetSetIP Set Ethernet Controller TCP/IP Settings Syntax #include <ctools.h> BOOLEAN ethernetSetIP( IP_SETTINGS * pIPSettings ); Description The ethernetSetIP function copies the settings pointed to by pIPSettings 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. 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 2.22) 10/26/2012 223 Function Specifications executeConstructors Execute Global Class Object Constructors. Syntax #include <ctools.h> void executeConstructors( void ); Description This function executes all global class object constructors defined in the user C++ application. This function should be called before executing the user C++ application. This function should only be needed in the context of the startup function appstart. Document (Version 2.22) 10/26/2012 224 Function Specifications executeDestructors Execute Global Class Object Destructors. Syntax #include <ctools.h> void executeDestructors( void ); Description This function executes all global class object destructors defined in the user C++ application. This function should be called after the user C++ application ends. This function should only be needed in the context of the startup function appstart. Document (Version 2.22) 10/26/2012 225 Function Specifications flashSettingsLoad Load Controller Settings from Flash Syntax #include <ctools.h> 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 2.22) 10/26/2012 226 Function Specifications flashSettingsSave Save Controller Settings to Flash Syntax #include <ctools.h> BOOLEAN flashSettingsSave(UINT32 areaFlags); Description This function stores 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 CS_OPTIONS CS_PERMANENT always always Saved settings loaded on Service and Run Boot. Ethernet MAC address Controller factory options. Controller type, IP address, Gateway, Network mask, IP Configuration mode, Lock state and password, I/O System settings CS_RUN Replaced with default settings on Cold Boot. Saved settings loaded on Run Boot. Default settings loaded on Service Boot. Serial port settings, Serial protocol settings, Modbus/TCP settings, HART I/O settings, LED power settings, Replaced with default settings on Cold Boot. Notes The FLASH_MEMORY resource needs to be requested before calling this function. Document (Version 2.22) 10/26/2012 227 Function Specifications forceLed Set State of Force LED Syntax #include <ctools.h> void forceLed(UINT16 state); Description The forceLed 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. Document (Version 2.22) 10/26/2012 228 Function Specifications freeMemory Free Non-Volatile Dynamic Memory Syntax #include <ctools.h> 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 needs to 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 needs to be statically allocated in a non-volatile data section. Otherwise they will be initialised at reset and the nonvolatile 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 2.22) 10/26/2012 229 Function Specifications getABConfiguration Get DF1 Protocol Configuration Syntax #include <ctools.h> struct ABConfiguration *getABConfiguration(FILE *stream, struct ABConfiguration *ABConfig); Description The getABConfiguration function gets the DF1 protocol configuration parameters for the stream. If stream does not point to a valid serial port the function has no effect. ABConfig needs to 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 <ctools.h> void main(void) { struct ABConfiguration ABConfig; getABConfiguration(com1, &ABConfig); printf("Min protected address: %u\r\n", ABConfig.min_protected_address); printf("Max protected address: %u\r\n", ABConfig.max_protected_address); } Document (Version 2.22) 10/26/2012 230 Function Specifications getclock Read the Real Time Clock Syntax #include <ctools.h> 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 IO_SYSTEM resource needs to be requested before calling this function. See Also setclock, getClockTime Example This program displays the current date and time. #include <ctools.h> main(void) { TIME now; request_resource(IO_SYSTEM); getclock(&now); /* read the clock */ release_resource(IO_SYSTEM); printf("%2d/%2d/%2d", now.day, now.month, now.year); printf("%2d:%2d\r\n",now.hour, now.minute); } Document (Version 2.22) 10/26/2012 231 Function Specifications getClockAlarm Read the Real Time Clock Alarm Settings Syntax #include <ctools.h> ALARM_SETTING getClockAlarm(void); Description The getClockAlarm function returns the alarm setting in the real time clock. Notes The IO_SYSTEM resource needs to be requested before calling this function. See Also setClockAlarm Document (Version 2.22) 10/26/2012 232 Function Specifications getClockTime Read the Real Time Clock Syntax #include <ctools.h> void getClockTime(INT32 * pDays, INT32 * pHundredths); Description The getClockTime function reads the read time clock and returns the value as the number of whole days since 01/01/97 and the number of hundredths of a second since the start of the current day. The function works for 100 years from 01/01/97 to 12/31/96 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 IO_SYSTEM resource needs to be requested before calling this function. See Also setclock, getclock Document (Version 2.22) 10/26/2012 233 Function Specifications getControllerID Get Controller ID Syntax #include <ctools.h> void getControllerID(CHAR * pID) Description This function writes the Controller ID to the string pointed to by pID. The Controller ID is a unique ID for the controller set at the factory. The pointer pID needs to point to a character string of length CONTROLLER_ID_LEN. Example This program displays the Controller ID. #include <ctools.h> void main(void) { char ctlrID[CONTROLLER_ID_LEN]; UINT16 index; getControllerID(ctlrID); fprintf(com1, "\r\nController ID : "); for (index=0; index<CONTROLLER_ID_LEN; index++) { fputc(ctlrID[index], com1); } } Document (Version 2.22) 10/26/2012 234 Function Specifications getForceFlag Get Force Flag State for a Register (Telepace firmware only) Syntax #include <ctools.h> 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 valid 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 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR Notes Force Flags are not modified when the controller is reset. Force Flags are in a 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 <ctools.h> void main(void) { UINT 16 flag, bitmask; getForceFlag(MODBUS, 40001, &flag); Document (Version 2.22) 10/26/2012 235 Function Specifications getForceFlag(LINEAR, 302, &bitmask); getForceFlag(LINEAR, 1540, &flag); } Document (Version 2.22) 10/26/2012 236 Function Specifications getForceLed Get status of Force LED Syntax #include <ctools.h> 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 2.22) 10/26/2012 237 Function Specifications getIOErrorIndication Get I/O Module Error Indication Syntax #include <ctools.h> BOOLEAN getIOErrorIndication(void); Description The getIOErrorIndication 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 I/O module communication status is not reported. Notes Refer to the SCADAPack 32 Hardware User Manual for further information on the Status LED and Status Output. See Also setIOErrorIndication Document (Version 2.22) 10/26/2012 238 Function Specifications getOutputsInStopMode Get Outputs In Stop Mode (Telepace firmware only) Syntax #include <ctools.h> void getOutputsInStopMode( BOOLEAN *holdDoutsOnStop, BOOLEAN *holdAoutsOnStop ); Description The getOutputsInStopMode function copies the values of the output control flags into the integers pointed to by doutsInStopMode 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 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 2.22) 10/26/2012 239 Function Specifications getpeername Syntax #include <ctools.h> int getpeername ( int socketDescriptor, Struct sockaddr * fromAddressPtr, int * addressLengthPtr ); Function 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. fromAddressPtr 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: TM_EBADF socketDescriptor is not a valid descriptor. TM_ENOTCONN The socket is not connected. TM_EINVAL One of the passed parameters is not valid. Document (Version 2.22) 10/26/2012 240 Function Specifications getPortCharacteristics Get Serial Port Characteristics Syntax #include <ctools.h> BOOLEAN getPortCharacteristics(FILE *stream, PORT_CHARACTERISTICS *pCharacteristics); Description The getPortCharacteristics function gets information about features supported by the serial port pointed to by 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 <ctools.h> void main(void) { PORT_CHARACTERISTICS options; getPortCharacteristics(com3, &options); fprintf(com1, "Dataflow options: %d\r\n", options.dataflow); fprintf(com1, "Protocol options: %d\r\n", options.protocol); } Document (Version 2.22) 10/26/2012 241 Function Specifications get_port Get Serial Port Configuration Syntax #include <ctools.h> struct pconfig *get_port(FILE *stream, struct pconfig *settings); Description The get_port function gets the serial port configuration for the stream. If stream does not point to 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 Also set_port Example #include <ctools.h> void main(void) { struct pconfig settings; get_port(com1, &settings); printf("Baud rate: %d\r\n", settings.baud); printf("Duplex: %d\r\n", settings.duplex); } Document (Version 2.22) 10/26/2012 242 Function Specifications getProgramStatus Get Program Status Flag Syntax #include <ctools.h> UINT16 getProgramStatus( void ); Description The getProgramStatus function returns the application program status flag. The status flag is set to NEW_PROGRAM when the C program is erased, or downloaded to the controller from the program loader. 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 2.22) 10/26/2012 243 Function Specifications get_protocol Get Protocol Configuration Syntax #include <ctools.h> struct prot_settings *get_protocol(FILE *stream, struct prot_settings *settings); Description The get_protocol function gets the communication protocol configuration for the stream. If stream does not point to a valid serial port the function has no effect. settings needs to 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 <ctools.h> void main(void) { struct prot_settings settings; get_protocol(com1, &settings); printf("Type: %d\r\n", settings.type); printf("Station: %d\r\n", settings.station); printf("Priority: %d\r\n", settings.priority); } Document (Version 2.22) 10/26/2012 244 Function Specifications getProtocolSettings Get Protocol Extended Addressing Configuration Syntax #include <ctools.h> BOOLEAN getProtocolSettings( FILE * stream, PROTOCOL_SETTINGS * settings ); Description The getProtocolSettings function reads the protocol parameters for a serial port. This function supports extended addressing. The function has two parameters: stream is one of com1, com2, com3 or com4; 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 <ctools.h> Document (Version 2.22) 10/26/2012 245 Function Specifications getProtocolSettingsEx Reads extended protocol settings for a serial port. Syntax #include <ctools.h> BOOLEAN getProtocolSettingsEx( FILE * stream, PROTOCOL_SETTINGS_EX * pSettings ); Description The getProtocolSettingsEx function gets protocol parameters for a serial port. This function supports extended addressing and Enron Modbus parameters. The function has two arguments: • stream specifies the serial port. It is one of com1, com2, com3 or com4. • 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 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 <ctools.h> void main(void) { PROTOCOL_SETTINGS_EX settings; if (getProtocolSettingsEx(com1, &settings) { printf("Type: %d\r\n", settings.type); printf("Station: %d\r\n", settings.station); printf("Address Mode: %d\r\n", settings.mode); printf("SF: %d\r\n", settings.SFMessaging); printf("Priority: %d\r\n", settings.priority); printf("Enron: %d\r\n", settings.enronEnabled); printf("Enron station: %d\r\n", settings.enronStation); Document (Version 2.22) 10/26/2012 246 Function Specifications } else { printf(“Serial port is not valid\r\n”); } } Document (Version 2.22) 10/26/2012 247 Function Specifications get_protocol_status Get Protocol Information Syntax #include <ctools.h> struct prot_status get_protocol_status(FILE *stream); Description The get_protocol_status function returns the protocol error and message counters for stream. If 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 <ctools.h> void main(void) { struct prot_status status; status = get_protocol_status(com2); printf("Checksum: %d\r\n", status.checksum_errors); } Document (Version 2.22) 10/26/2012 248 Function Specifications getSFTranslation Read Store and Forward Translation Syntax #include <ctools.h> void getSFTranslation(UINT16 index, SF_TRANSLATION * pTranslation); Description Instead of using the getSFTranslation function use the getSFTranslationEx function, which supports translations with a timeout. 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 2.22) 10/26/2012 249 Function Specifications getSFTranslationEx Read Store and Forward Translation method 2 Syntax #include <ctools.h> 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. 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 2.22) 10/26/2012 250 Function Specifications getsockname Syntax #include <ctools.h> int getsockname ( int socketDescriptor, struct sockaddr * myAddressPtr, int * addressLengthPtr ); Function 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. myAddressPtr 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: TM_EBADF socketDescriptor is not a valid descriptor. TM_EINVAL One of the passed parameters is not valid. Document (Version 2.22) 10/26/2012 251 Function Specifications getsockopt Syntax #include <ctools.h> int getsockopt ( int socketDescriptor, int protocolLevel, int optionName, char * optionValuePtr, int * optionLengthPtr ); Function Description getsockopt is used retrieve options associated with a socket. Options may exist at multiple protocol levels; they are present at the uppermost “socket” level. When manipulating socket options, the level at which the option resides and the name of the option needs to be specified. To manipulate options at the “socket” level, protocolLevel is specified as SOL_SOCKET. To manipulate options at any other level, protocolLevel 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 optionValuePtr and optionLengthPtr identify a buffer in which the value(s) for the requested option(s) are to be returned. For getsockopt, optionLengthPtr 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 uninterpreted to the appropriate protocol module for interpretation. The include file <ctools.h> 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 <ctools.h>. struct linger contains the following members: l_onoff on = 1 / off = 0 l_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 2.22) 10/26/2012 252 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. TM_SO_RCVCOPY TCP socket: fraction use of a receive buffer below which we try and append to a previous receive buffer in the socket receive queue. UDP socket: fraction use of a receive buffer below which we try and copy to a new receive buffer, if there is already at least a buffer in the receive queue. This is to avoid keeping large pre-allocated receive buffers, which the user has not received yet, in the socket receive queue. Default value is 4 (25%). TM_SO_SNDAPPEND TCP socket only. Threshold in bytes of ‘send’ buffer below, which we try and append, to previous ‘send’ buffer in the TCP send queue. Only used with send, not with tfZeroCopySend. This is to try to regroup lots of partially empty small buffers in the TCP send queue waiting to be ACKED by the peer; otherwise we could run out of memory, since the remote TCP will delay sending ACKs. Care should be taken not to use tfZeroCopySend when sending small buffers, since we do not try to regroup small buffers with tfZeroCopySend. Default value is 4000 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 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 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). Document (Version 2.22) 10/26/2012 253 Function Specifications The following options are recognized at the IP level. IP_PROTOIP protocolLevel options IPO_MULTICAST_IF Get the configured IP address that uniquely identifies 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. IPO_MULTICAST_TTL Get the default IP TTL for outgoing multicast datagrams. IPO_SRCADDR Get the IP source address for the Connection. IPO_TOS IP type of service. Default 0 IPO_TTL IP Time To Live in seconds. Default 64. The following options are recognized at the TCP level. IP_PROTOTCP protocolLevel options TCP_KEEPALIVE Get the idle time in seconds for a TCP connection, before it starts sending keep alive probes. Keep alive probes will be sent only if the SO_KEEPALIVE socket option is enabled. Default 7,200 seconds. TCP_MAXRT Get the amount of time in seconds before the connection is broken once TCP starts retransmitting, or probing a zero window when the peer does not respond. A TCP_MAXRT value of 0 means the system default, and 1 means retransmit forever. Unless the TCP_MAXRT value is –1 (wait forever), the connection can also be broken if the number of maximum retransmission TM_TCP_MAX_REXMIT has been reached. See TM_TCP_MAX_REXMIT below. Default 0. (which means use system default of TM_TCP_MAX_REXMIT times network computed round trip time for an established connection. For a non established connection, since there is no computed round trip time yet, the connection can be broken when either 75 seconds , or when TM_TCP_MAX_REXMIT times default network round trip time have elapsed, whichever occurs first). TCP_MAXSEG 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. TCP_NODELAY If this option value is non-zero, the Nagle algorithm that buffers the sent data inside the TCP is disabled. Useful Document (Version 2.22) 10/26/2012 254 Function Specifications to allow client’s TCP to send small packets as soon as possible (like mouse clicks). Default 0. TCP_NOPUSH If this option value is non-zero, then TCP delays sending any TCP data until a full sized segment is buffered in the TCP buffers. Useful for applications that send continuous big chunks of data and know that more data will be sent such as FTP. (Normally, the TCP code sends a non full-sized segment, only if it empties the TCP buffer). Default 0. TCP_STDURG If this option value is zero, then the urgent data pointer points to the last bye of urgent data + 1, like in Berkeley systems. Default 1 (urgent pointer points to last byte of urgent data as specified in RFC1122). *TM_TCP_SEL_ACK If this option value is zero, then TCP selective Acknowledgment options are disabled. Default 1. *TM_TCPWND_SCALE If this option value is non-zero, then the TCP window scale option is enabled. Default 0. *TM_TCP_TS If this option value is non-zero, then the TCP time stamp option is enabled. Default 0. TM_TCP_SLOW_START If this option value is non-zero, then the TCP slow start algorithm is enabled. Default 1. TM_TCPDELAY_ACK Get the TCP delay ack time in milliseconds. Default 200 milliseconds. TM_TCPMAX_REXMIT Get the maximum number of retransmissions without any response from the remote before TCP gives up and aborts the connection. See also TCP_MAXRT above. Default 12. TM_TCP_KEEPALIVE_CNT Get the maximum number of keep alive probes without any response from the remote before TCP gives up and aborts the connection. See also TCP_KEEPALIVE above. Default 8. TM_TCPFINWT2TIME Get the maximum amount of time TCP will wait for the remote side to close after it initiated a close. Default 600 seconds. TM_TCP2MSLTIME Get the maximum amount of time TCP will wait in the TIME WAIT state once it has initiated a close of the connection. Default 60 seconds. TM_TCP_RTO_DEF Get the TCP default retransmission timeout value in milliseconds. Used when no network round trip time has been computed yet. Default 3,000 milliseconds. TM_TCP_RTO_MIN Get the minimum retransmission timeout in milliseconds. The network computed retransmission timeout is bound Document (Version 2.22) 10/26/2012 255 Function Specifications by TM_TCP_RTO_MIN and TM_TCP_RTO_MAX. Default 100 milliseconds. TM_TCPRTO_MAX Get the maximum retransmission timeout in milliseconds. The network computed retransmission timeout is bound by TM_TCPRTO_MIN and TM_RTO_MAX. Default 64,000 milliseconds. TM_TCPPROBE_MIN Get the minimum window probe timeout interval in milliseconds. The network computed window probe timeout is bound by TM_TCP_PROBE _MIN and TM_TCP_PROBE _MAX. Default 500 milliseconds. TM_TCP_PROBE_MAX Get the maximum window probe timeout interval in milliseconds. The network computed window probe timeout is bound by TM_TCP_PROBE _MIN and TM_TCP_PROBE _MAX. Default 60,000 milliseconds. TM_TCP_KEEPALIVE_INTV Get the interval between Keep Alive probes in seconds. See TM_TCP_KEEPALIVE_CNT. Default 75 seconds. Parameters socketDescriptor The socket descriptor to get the option from. protocolLevel The protocol to get the option from. See below. optionName The option to get. See above and below. optionValuePtr The pointer to a user variable into which the option value is returned. User variable is of data type described below. optionLengthPtr Pointer to the size of the user variable, which is the size of the option data type, described below. It is a valueresult parameter, and the user should set the size prior to the call. SOL_SOCKET Socket level protocol IP_PROTOIP IP level protocol IP_PROTOTCP TCP level protocol. Protocol Level Option Name SOL_SOCKET SO_ACCEPTCONN SO_DONTROUTE SO_KEEPALIVE SO_LINGER SO_OOBINLINE SO_RCVBUF SO_RCVLOWAT Document (Version 2.22) 10/26/2012 Option data type int int int struct linger int unsigned long unsigned long Option value 0 or 1 0 or 1 0 or 1 0 or 1 256 Function Specifications Protocol Level IP_PROTOIP IP_PROTOTCP Option Name SO_REUSEADDR SO_SNDBUF SO_SNDLOWAT TM_SO_RCVCOPY TM_SO_SNDAPPEND IPO_MULTICAST_IF IPO_MULTICAST_TTL IPO_TOS IPO_TTL IPO_SRCADDR TCP_KEEPALIVE TCP_MAXRT TCP_MAXSEG TCP_NODELAY TCP_NOPUSH TCP_STDURG TM_TCP_2MSLTIME TM_TCP_DELAY_ACK TM_TCP_FINWT2TIME TM_TCP_KEEPALIVE_ CNT TM_TCP_KEEPALIVE_I NTV TM_TCP_MAX_REXMIT TM_TCP_PROBE_MAX TM_TCP_PROBE_MIN TM_TCP_RTO_DEF TM_TCP_RTO_MAX TM_TCP_RTO_MIN TM_TCP_SEL_ACK TM_TCP_SLOW_STAR T TM_TCP_TS TM_TCP_WND_SCALE Option data type int unsigned long unsigned long unsigned int unsigned int struct in_addr unsigned char unsigned char unsigned char ttUserIpAddre ss int int int int int int 0 or 1 int int int int Option value 0 or 1 0 or 1 0 or 1 int int unsigned long unsigned long unsigned long unsigned long unsigned long int int 0 or 1 0 or 1 int int 0 or 1 0 or 1 Returns Value Meaning 0 Successful set of option -1 An error occurred getsockopt will fail if: Document (Version 2.22) 10/26/2012 257 Function Specifications TM_EBADF The socket descriptor is invalid TM_EINVAL One of the parameters is invalid TM_ ENOPROTOOPT The option is unknown at the level indicated. Document (Version 2.22) 10/26/2012 258 Function Specifications get_status Get Serial Port Status Syntax #include <ctools.h> struct pstatus *get_status(FILE *stream, struct pstatus *status); Description The get_status function returns serial port error counters, I/O lines status and I/O driver buffer information for stream. If stream does not point to a valid serial port the function has no effect. status needs to 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 settings. 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 <ctools.h> void main(void) { struct pstatus status; get_status(com1, &status); printf("Framing: %d\r\n", status.framing); printf("Parity: %d\r\n", status.parity); } Document (Version 2.22) 10/26/2012 259 Function Specifications getStatusBit Read Bits in Controller Status Code Syntax #include <ctools.h> UINT16 getStatusBit(UINT16 bitMask); Description The getStatusBit function returns the values of the bits indicated by bitMask in the controller status code. See Also setStatusBit, clearStatusBit Document (Version 2.22) 10/26/2012 260 Function Specifications getTaskInfo Get Information on a Task Syntax #include <ctools.h> TASKINFO getTaskInfo(UINT32 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 taskID 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 2.22) 10/26/2012 261 Function Specifications getVersion Get Firmware Version Information Syntax #include <ctools.h> 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 <ctools.h> void main(void) { struct prot_settings settings; VERSION versionInfo; /* Disable the protocol on serial port 1 */ settings.type = NO_PROTOCOL; settings.station = 1; settings.priority = 3; settings.SFMessaging = FALSE; request_resource(IO_SYSTEM); set_protocol(com1, &settings); release_resource(IO_SYSTEM); /* Display the ROM version information */ versionInfo = getVersion(); fprintf(com1, "\r\nFirmware Information\r\n"); fprintf(com1, " Controller type: versionInfo.controller); fprintf(com1, " Firmware version: versionInfo.version); fprintf(com1, " Creation date: fprintf(com1, " Copyright: versionInfo.copyright); } Document (Version 2.22) 10/26/2012 %d\r\n", %d\r\n", %s\r\n", versionInfo.date); %s\r\n", 262 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 <ctools.h> UINT16 handler( UCHAR * message, UINT16 messageLength, UCHAR * response, UINT16 * responseLength ); 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. • 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. • The messageLength parameter is the number of characters in the message. • 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. • 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 needs to return one of four values. The first causes a normal response to be sent. The others cause an exception response to be sent. • 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. • ILLEGAL_FUNCTION indicates the function code in the message was not understood. The handler function needs to return this value for all function Document (Version 2.22) 10/26/2012 263 Function Specifications codes it does not process. The Modbus protocol will return an Illegal Function exception response. • ILLEGAL_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. • ILLEGAL_DATA_VALUE indicates the function code in the message was understood, but that the command included data that is not valid. The Modbus protocol will return an Illegal Data Address exception response. Function Codes Used The following function codes are currently used by the TeleBUS Modbuscompatible 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. Code Type Description 1 2 3 4 5 6 7 15 16 17 65 66 67 68 69 70 Modbus standard Modbus standard Modbus standard Modbus standard Modbus standard Modbus standard Modbus standard Modbus standard Modbus standard Modbus standard TeleBUS extension TeleBUS extension TeleBUS extension TeleBUS extension TeleBUS extension TeleBUS extension Read coil registers from I/O database Read status registers from I/O database Read holding registers from I/O database Read input registers from I/O database Write a single coil register Write a single holding register Read exception status Write multiple coil registers Write multiple holding registers Report slave identification string Used by Telepace Used by Telepace Used by Telepace Used by Telepace Used by Telepace 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 preempt the execution of another task. If there are shared resources, the handler function needs to request and release the appropriate resources to ensure proper operation. The station address is not included in the message or response string. It will be added to the response string before sending the reply. Document (Version 2.22) 10/26/2012 264 Function Specifications The checksum is not included in the message or the response 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 2.22) 10/26/2012 265 Function Specifications hartIO Read and Write 5904 HART Interface Module Syntax #include <ctools.h> 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 2.22) 10/26/2012 266 Function Specifications hartCommand Send Command using HART Interface Module Syntax #include <ctools.h> BOOLEAN hartCommand( UINT16 module, HART_DEVICE * const device, HART_COMMAND * const command, void (* processResponse)( UINT16, HART_RESPONSE) ); 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 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. 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. Document (Version 2.22) 10/26/2012 267 Function Specifications The functions hartCommand0, hartCommand1, etc. are used to send commands provided by the Network Layer. See Also hartStatus, hartSetConfiguration, hartCommand0, hartCommand1 Document (Version 2.22) 10/26/2012 268 Function Specifications hartCommand0 Read Unique Identifier Syntax #include <ctools.h> 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 to a 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 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 2.22) 10/26/2012 269 Function Specifications hartCommand1 Read Primary Variable Syntax #include <ctools.h> BOOLEAN hartCommand1(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 needs to 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 function returns FALSE if the module number is invalid. Notes The HART_DEVICE structure needs to be initialized using hartCommand0 or hartCommand11. The function returns immediately after the command is sent. The calling program must 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 2.22) 10/26/2012 270 Function Specifications hartCommand2 Read Primary Variable Current and Percent of Range Syntax #include <ctools.h> 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 needs to be static modular or global variables. A pvCurrent and pvPercent variable 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 function returns FALSE if the module number is invalid. Notes The HART_DEVICE structure needs to be initialized using hartCommand0 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 2.22) 10/26/2012 271 Function Specifications hartCommand3 Read Primary Variable Current and Dynamic Variables Syntax #include <ctools.h> BOOLEAN hartCommand3(UINT16 module, HART_DEVICE * const device, HART_VARIABLE * variables); Description This function reads 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 needs to 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. Variable Contains variables[0] variables[1] variables[2] variables[3] variables[4] primary variable current primary variable secondary variable tertiary variable 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 hartCommand0 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 2.22) 10/26/2012 272 Function Specifications Not all devices return primary, secondary, 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 2.22) 10/26/2012 273 Function Specifications hartCommand11 Read Unique Identifier Associated with Tag Syntax #include <ctools.h> 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 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 hartCommand0, hartStatus, hartSetConfiguration Document (Version 2.22) 10/26/2012 274 Function Specifications hartCommand33 Read Transmitter Variables Syntax #include <ctools.h> 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 needs to 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. Variable Contains variables[0] transmitter variable, code and units specified by variableCode[0] transmitter variable, code and units specified by variableCode[1] transmitter variable, code and units specified by variableCode[2] transmitter variable, code and units specified by variableCode[3] variables[1] variables[2] variables[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 hartCommand0 or hartCommand11. The pointer variables needs to point to an array with at least four elements. Document (Version 2.22) 10/26/2012 275 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 2.22) 10/26/2012 276 Function Specifications hartStatus Return Status of Last HART Command Sent Syntax #include <ctools.h> 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 determine 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. Result Status code HART interface module is not communicating Command ready to be sent Command sent to device Response received HR_NoModuleResponse not used HR_CommandPending not used HR_CommandSent current attempt number HR_Response No valid response received after all attempts made HR_NoResponse HART interface module is not ready to transmit HR_WaitTransmit response code from HART device (see Notes) 0=no response from HART device. Other = error response code from HART device (see Notes) not used 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. • 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 2.22) 10/26/2012 277 Function Specifications as defined by the HART protocol specifications. Consult the documentation for the HART device for more information. Bit Description 6 5 4 3 2 1 0 vertical parity error overrun error framing error longitudinal parity error reserved – always 0 buffer overflow Undefined • If 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. Code Description 32 Busy – the device is performing a function that cannot be interrupted by this command Command not Implemented – the command is not defined for this device. 64 • 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. Bit Description 7 6 5 4 field device malfunction configuration changed cold start more status available (use command 48 to read) primary variable analog output fixed primary variable analog output saturated non-primary variable out of limits primary variable out of limits 3 2 1 0 See Also hartSetConfiguration Document (Version 2.22) 10/26/2012 278 Function Specifications hartGetConfiguration Read HART Module Settings Syntax #include <ctools.h> 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 settings were read. The function returns FALSE if the module number is invalid. See Also hartSetConfiguration Document (Version 2.22) 10/26/2012 279 Function Specifications hartSetConfiguration Write HART Module Settings Syntax #include <ctools.h> 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 2.22) 10/26/2012 280 Function Specifications hartPackString Convert String to HART Packed String Syntax #include <ctools.h> void hartPackString(CHAR * pPackedString, const CHAR * pString, UINT16 sizePackedString); Description This function stores an ASCII 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 2.22) 10/26/2012 281 Function Specifications hartUnpackString Convert HART Packed String to String Syntax #include <ctools.h> 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 2.22) 10/26/2012 282 Function Specifications htonl Syntax #include <ctools.h> unsigned long htonl(unsigned long longValue); Function 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 2.22) 10/26/2012 283 Function Specifications htons Syntax #include <ctools.h> unsigned short htons(unsigned short shortValue); Function 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 2.22) 10/26/2012 284 Function Specifications inet_addr Syntax #include <ctools.h> unsigned long inet_addr(char * ipAddressDottedStringPtr); Function Description This function converts an IP address from the decimal dotted notation to an unsigned long. Parameters ipAddressDottedStringPtr The dotted string (i.e. “208.229.201.4”) Returns Value Meaning -1 Error Other The IP Address in Network Byte Order. Document (Version 2.22) 10/26/2012 285 Function Specifications inet_aton Syntax #include <ctools.h> unsigned long inet_addr(char * ipAddressDottedStringPtr); Function Description This function converts an IP address from the decimal dotted notation to an unsigned long. Parameters ipAddressDottedStringPtr The dotted string (i.e. “208.229.201.4”) Returns 0 Error Other The IP Address in Network Byte Order. Document (Version 2.22) 10/26/2012 286 Function Specifications initializeApplicationVariables Initialize User Application Variables Syntax #include <ctools.h> void initializeApplicationVariables(void); Description This function initializes all variables declared in the user application. Variables declared with initialized values are initialized by this function. All remaining variables are zero-filled by this function. This does not apply to local variables. This function should only be needed in the context of the startup function appstart. Document (Version 2.22) 10/26/2012 287 Function Specifications install_handler Install Serial Port Handler Syntax #include <ctools.h> void install_handler(FILE *stream, void *function(UINT, UINT)); 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 received character. The second argument is an error flag. A nonzero value indicates an error. If function is NULL, the default handler for the 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-3 program. Example See the Install Serial Port Handler Example in the Examples section. Document (Version 2.22) 10/26/2012 288 Function Specifications installClockHandler Install Handler for Real Time Clock Syntax #include <ctools.h> 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 interrupt_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 2.22) 10/26/2012 289 Function Specifications installDbaseHandler Install User Defined Dbase Handler (IEC 61131-3 firmware only) Syntax #include <ctools.h> void installDbaseHandler ( BOOLEAN (* handler)(UINT16 address, int *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: There is no IEC 61131-3 application downloaded, or There is no IEC 61131-3 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 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 function 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. Document (Version 2.22) 10/26/2012 290 Function Specifications installSetdbaseHandler Install User Defined Setdbase Handler (IEC 61131-3 firmware only) Syntax #include <ctools.h> void installSetdbaseHandler ( BOOLEAN (* handler)(UINT16 address, int 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: There is no IEC 61131-3 application downloaded, or There is no IEC 61131-3 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 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 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. See Also setdbase, installDbaseHandler Example See example for Setdbase Handler Function. Document (Version 2.22) 10/26/2012 291 Function Specifications installExitHandler Install Handler Called when Task Ends Syntax #include <ctools.h> BOOLEAN installExitHandler(UINT32 taskID, void (*function)(void)); Description The installExitHandler function defines a function that is called when the task, specified by taskID, is ended. function specifies the handler function. If function is NULL, the handler is disabled. Notes The exit handler function will be called when: • the task is ended by the end_task function • the end_application function is executed and the function is an APPLICATION type function • the program is stopped from the IEC 61131-3 program and the task is an APPLICATION type function • the C program is erased by the IEC 61131-3 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. RTOS functions cannot be called from the exit handler. Example See the example for startTimedEvent. Document (Version 2.22) 10/26/2012 292 Function Specifications installModbusHandler Install User Defined Modbus Handler Syntax #include <ctools.h> void installModbusHandler( UINT16 (* handler)(UCHAR *, UINT16, UCHAR *, UINT16 *) ); 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 standard Modbus protocol. The installed handler function 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. If the pointer is NULL, no function is called for non-standard messages. The function has no return value. Notes This function is used to create a user-defined extension to the standard Modbus protocol. Call this function with the NULL pointer to disable processing of non-standard Modbus 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 Modbus 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 IEC 61131-3 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. See Also Handler Function Document (Version 2.22) 10/26/2012 293 Function Specifications installRTCHandler Install User Defined Real-Time-Clock Handler Syntax #include <ctools.h> void installRTCHandler( void (* rtchandler)(TIME *now, TIME *new) ); 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. See Also RTCHandler Function, installExitHandler Document (Version 2.22) 10/26/2012 294 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 <ctools.h> void rtchandler(TIME *now, TIME *new); 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. • The now parameter is a pointer to the structure containing the time when the message was received. • 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 IO_SYSTEM resource (e.g. setclock), there is no need to request or release the resource. This function cannot request or release the IO_SYSTEM resource. See Also installRTCHandler Document (Version 2.22) 10/26/2012 295 Function Specifications interrupt_signal_event Signal Event in Interrupt Handler Syntax #include <ctools.h> void interrupt_signal_event(UINT32 event_number); Description The interrupt_signal_event function is used in an interrupt handler to signal events. The 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 255 occurrences of an event will be recorded. The current task is blocked of there is a higher priority task waiting for the event. Notes Refer to the Real Time Operating System section for more information on events. This function can only be used within an interrupt handler. Valid events are numbered 0 to 31. Any events defined in ctools.h. are not valid events for use in an application program. Document (Version 2.22) 10/26/2012 296 Function Specifications interval Set Timer Tick Interval Syntax #include <ctools.h> void interval(UINT16 timer, UINT16 value); Description The interval function sets the tick interval for timer to value. Tick intervals are measured in multiples of 0.1 second. If the timer number is invalid, the task's error code is set to TIMER_BADTIMER. Notes To enable support for timers, the function runTimers needs to be called once before using any of the timer functions (settimer, timer, interval, or read_timer_info). Example Set timer 5 to count 12 seconds using 1.0 s ticks. interval(5, 10); /* 1.0 s ticks */ settimer(5, 12); /* time = 12 seconds */ Set timer 5 to count 12 seconds using 0.1 s ticks. interval(5, 1); /* 0.1 s ticks */ settimer(5, 120); /* time = 12 seconds */ Document (Version 2.22) 10/26/2012 297 Function Specifications ioClear Turn Off all Outputs Syntax #include <ctools.h> void ioClear(void) Description The ioClear function turns off all outputs as follows. a reset of all I/O modules is added to the I/O System queue; • analog outputs are set to 0; • 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 IO_SYSTEM resource needs to be requested before calling this function. Document (Version 2.22) 10/26/2012 298 Function Specifications ioDatabaseReset Initialize I/O Database with Default Values Syntax #include <ctools.h> void ioDatabaseReset(void); Description The ioDatabaseReset function resets the target controller to default settings. • Configuration parameters are reset to the default values. • Communication status counters are reset to zero. • Output I/O points are cleared. • Locked variables are unlocked. • Clear all I/O forcing • Clear all I/O points • Set all database locations to zero • Set I/O database for real-time clock to current time • Clear real time clock alarm settings • Configure serial ports with default parameters • Configure serial ports with default protocols • Clear serial port event counters • Clear store and forward configuration • Enable LED power by default and return to default state after 5 minutes • Set Outputs on Stop settings to Hold • Set 5904 HART modem configuration for all modems • Set Modbus/TCP default configuration • 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-3 program. The IO_SYSTEM resource needs to be requested before calling this function. Example #include <ctools.h> Document (Version 2.22) 10/26/2012 299 Function Specifications void main(void) { /* Power Up Initialization */ request_resource(IO_SYSTEM); ioDatabaseReset(); release_resource(IO_SYSTEM); /* ... the rest of the program */ } Document (Version 2.22) 10/26/2012 300 Function Specifications ioGetConfiguration Get I/O Controller Configuration Syntax #include <ctools.h> IO_CONFIG& ioGetConfiguration(void) Description This function returns the I/O controller configuration. The function has no arguments. The function returns an IO_CONFIG structure containing the configuration. Document (Version 2.22) 10/26/2012 301 Function Specifications ioNotification Add I/O Notification Request Syntax #include <ctools.h> BOOLEAN ioNotification(UINT16 eventNumber) Description This function adds a Notification Request to the I/O Controller request queue. The 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 2.22) 10/26/2012 302 Function Specifications ioRead5414Inputs Read 5414 module inputs. Syntax #include <ctools.h> BOOLEAN ioRead5414Inputs( UINT16 moduleAddress, UCHAR (&dinData)[2] ) Description This function reads buffered data from the digital inputs5414 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 ioWrite5414Outputs Document (Version 2.22) 10/26/2012 303 Function Specifications ioRead5415Inputs Read 5415 module inputs Syntax #include <ctools.h> BOOLEAN ioRead5415Inputs( UINT16 moduleAddress, UCHAR &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 ioWrite5415Outputs, ioRead5415Outputs Document (Version 2.22) 10/26/2012 304 Function Specifications ioRead5415Outputs Read 5415 module outputs Syntax #include <ctools.h> BOOLEAN ioRead5415Outputs( UINT16 moduleAddress, UCHAR (&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 ioWrite5415Outputs 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 ioWrite5415Outputs, ioRead5415Inputs Document (Version 2.22) 10/26/2012 305 Function Specifications ioRead5505Inputs Read 5505 Inputs Syntax #include <ctools.h> BOOLEAN ioRead5505Inputs( UINT16 moduleAddress, UINT16 &dinData, float (&ainData)[4] ) Description This function reads buffered data from the digital and analog inputs of a 5505 I/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 Function 0 OFF = channel 0 RTD is good ON = channel 0 RTD is open or PWR input is off OFF = channel 0 data in range ON = channel 0 data is out of range OFF = channel 0 RTD is using 3-wire measurement ON = channel 0 RTD is using 4-wire measurement reserved for future use OFF = channel 1 RTD is good ON = channel 1 RTD is open or PWR input is off OFF = channel 1 data in range ON = channel 1 data is out of range OFF = channel 1 RTD is using 3-wire measurement ON = channel 1 RTD is using 4-wire measurement reserved for future use OFF = channel 2 RTD is good ON = channel 2 RTD is open or PWR input is off OFF = channel 2 data in range ON = channel 2 data is out of range OFF = channel 2 RTD is using 3-wire measurement ON = channel 2 RTD is using 4-wire measurement reserved for future use 1 2 3 4 5 6 7 8 9 10 11 Document (Version 2.22) 10/26/2012 306 Function Specifications 12 OFF = channel 3 RTD is good ON = channel 3 RTD is open or PWR input is off OFF = channel 3 data in range ON = channel 3 data is out of range OFF = channel 3 RTD is using 3-wire measurement ON = channel 3 RTD is using 4-wire measurement Reserved for future use 13 14 15 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 invalid; otherwise TRUE is returned. See Also ioRead5505Outputs, 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 <ctools.h> #define MY_EVENT 1 void 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 (!ioRequest(MT_5505Inputs, 5)) { status = FALSE; } // wait for scan to complete ioNotification(MY_EVENT); wait_event(MY_EVENT); // read input data from last scan status = ioRead5505Inputs(5, dinData, ainData); // check status of last scan if (!ioStatus(MT_5505Inputs, 5, &io_status)) { Document (Version 2.22) 10/26/2012 307 Function Specifications status = FALSE; } else if (!io_status.commStatus) { status = FALSE; } // print data when option switch 4 is selected if (optionSwitch(4)) { if (!done) { fprintf(com4, "status = %u,\ Dins 0 to 15 = %X, Ain 3 = %f\r\n", status, dinData, ainData[3]); done = TRUE; } } else { done = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 308 Function Specifications ioRead5505Outputs Read 5505 Configuration Syntax #include <ctools.h> BOOLEAN ioRead5505Outputs( UINT16 moduleAddress, UINT16 (&inputType)[4], UINT16 &inputFilter ) 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 • 0 = RTD in deg Celsius • 1 = RTD in deg Fahrenheit • 2 = RTD in deg Kelvin • 3 = resistance measurement in ohms. inputFilter is a reference to a UINT16 variable. The input filter selection is written to this variable. • 0 = 0.5 s • 1=1s • 2=2s • 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 <ctools.h> void main(void) { UINT16 inputType[4]; Document (Version 2.22) 10/26/2012 309 Function Specifications UINT16 inputFilter; BOOLEAN status; BOOLEAN done; // main loop while (TRUE) { // read output data from I/O table status = ioRead5505Outputs(5, inputType, inputFilter); // print data when option switch 4 is selected if (optionSwitch(4)) { if (!done) { fprintf(com4, "status = %u, inputType 0 = %d, inputFilter = %d\r\n", status, inputType[0], inputFilter); done = TRUE; } } else { done = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 310 Function Specifications ioRead5506Inputs Read 5506 Inputs Syntax #include <ctools.h> BOOLEAN ioRead5506Inputs( UINT16 moduleAddress, UCHAR &dinData, INT16 (&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 <ctools.h> #define MY_EVENT 1 void 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 2.22) 10/26/2012 311 Function Specifications if (!ioRequest(MT_5506Inputs, 5)) { status = FALSE; } // wait for scan to complete ioNotification(MY_EVENT); wait_event(MY_EVENT); // read input data from last scan status = ioRead5506Inputs(5, dinData, ainData); // check status of last scan if (!ioStatus(MT_5506Inputs, 5, &io_status)) { status = FALSE; } else if (!io_status.commStatus) { status = FALSE; } // print data when option switch 4 is selected if (optionSwitch(4)) { if (!done) { fprintf(com4, "status = %u,\ Dins 0 to 7 = %X, Ain 4 = %d\r\n", status, dinData, ainData[4]); done = TRUE; } } else { done = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 312 Function Specifications ioRead5506Outputs Read 5506 Configuration Syntax #include <ctools.h> BOOLEAN ioRead5506Outputs( UINT16 moduleAddress, UINT16 (&inputType)[8], UINT16 &inputFilter, UINT16 &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 • 0 = 0 to 5V • 1 = 1 to 5 V • 2 = 0 to 20 mA • 3 = 4 to 20 mA. inputFilter is a reference to a UINT16 variable. The input filter selection is written to this variable. • 0 = 3 Hz • 1 = 6 Hz • 2 = 11 Hz • 3 = 30 Hz scanFrequency is a reference to a UINT16 variable. The scan frequency selection is written to this variable. • 0 = 60 Hz • 1 = 50 Hz The function returns FALSE if the module address is invalid; otherwise TRUE is returned. See Also ioRead5506Inputs, ioWrite5506Outputs Document (Version 2.22) 10/26/2012 313 Function Specifications Example This program reads configuration data for the 5506 I/O module at address 5. #include <ctools.h> void 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 = ioRead5506Outputs(5, inputType, inputFilter, scanFrequency); // print data when option switch 4 is selected if (optionSwitch(4)) { if (!done) { fprintf(com4, "status = %u, inputType 0 = %d, inputFilter = %d, scanFrequency = %d \r\n", status, inputType[0], inputFilter, scanFrequency); done = TRUE; } } else { done = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 314 Function Specifications ioRead5601Inputs Read 5601 Inputs Syntax #include <ctools.h> BOOLEAN ioRead5601Inputs(UINT16 & dinData, INT16 (&ainData)[8]) Description This function reads buffered data from the digital and analog inputs of a 5601 I/O module (SCADAPack 32 lower I/O module). Buffered data are updated when an I/O request for the module is processed. The function has two parameters: a reference to a UINT16 variable for the digital data, and a reference to an array of eight INT16 variables for the analog data. Digital input data are copied to the variable referenced to by dinData. Analog input data are copied to the array referenced to by ainDataArray. The function always returns TRUE. See Also ioRead5604Inputs, ioWrite5604Outputs Document (Version 2.22) 10/26/2012 315 Function Specifications ioRead5601Outputs Read 5601 Outputs Syntax #include <ctools.h> BOOLEAN ioRead5601Outputs(UINT16 & data) Description This function reads buffered data used for the 12 digital outputs of a 5601 I/O module (SCADAPack 32 lower I/O module). Buffered data are written using the ioWrite5601Outputs function. The function has one parameter: a reference to a UINT16 variable to hold the digital data. Digital output data are copied to the variable. The 12 least significant bits correspond to the 12 digital outputs. The function always returns TRUE. See Also ioRead5604Outputs, ioWrite5604Outputs Document (Version 2.22) 10/26/2012 316 Function Specifications ioRead5604Inputs Read 5604 Inputs Syntax #include <ctools.h> BOOLEAN ioRead5604Inputs( UCHAR (&dinData)[5], INT16 (&ainData)[10]) Description This function reads buffered data from the digital and analog inputs of a 5604 I/O module. Buffered data are updated when an I/O request for the module is processed. dinData is a reference to an array of five UCHAR variables. Digital data for the 35 inputs are written to this array. One bit in the array represents each input point. ainData is a reference to an array of ten INT16 variables. Analog data are written to this array. The function always returns TRUE. See Also ioRead5604Outputs, ioWrite5604Outputs Document (Version 2.22) 10/26/2012 317 Function Specifications ioRead5604Outputs Read 5604 Outputs Syntax #include <ctools.h> BOOLEAN ioRead5604Outputs( UCHAR (&doutData)[5], INT16 (&aoutData)[2]) Description This function reads buffered data from the digital and analog outputs of a 5604 I/O module. Buffered data are written using the ioWrite5604Outputs function. doutData is a reference to an array of five UCHAR variables. Digital data for the 34 outputs are written to this array. One bit in the array represents each input point. ainData is a reference to an array of two INT16 variables. Analog data are written to this array. The function always returns TRUE. See Also ioRead5604Inputs, ioWrite5604Outputs Document (Version 2.22) 10/26/2012 318 Function Specifications ioRead5606Inputs Read 5606 Inputs Syntax #include <ctools.h> BOOLEAN ioRead5606Inputs( UINT16 moduleAddress, UCHAR (&dinData)[5], INT16 (&ainData)[8] ) Description This function reads buffered data from the digital and analog inputs of a 5606 I/O module. Buffered data are updated when 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 <ctools.h> #define MY_EVENT 1 void 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 2.22) 10/26/2012 319 Function Specifications if (!ioRequest(MT_5606Inputs, 5)) { status = FALSE; } // wait for scan to complete ioNotification(MY_EVENT); wait_event(MY_EVENT); // read input data from last scan status = ioRead5606Inputs(5, dinData, ainData); // check status of last scan if (!ioStatus(MT_5606Inputs, 5, &io_status)) { status = FALSE; } else if (!io_status.commStatus) { status = FALSE; } // print data when option switch 4 is selected if (optionSwitch(4)) { if (!done) { fprintf(com4, "status = %u,\ Dins 0 to 7 = %X, Ain 4 = %d\r\n", status, dinData[0], ainData[4]); done = TRUE; } } else { done = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 320 Function Specifications ioRead5606Outputs Read 5606 Outputs Syntax #include <ctools.h> BOOLEAN ioRead5606Outputs( UINT16 moduleAddress, UCHAR (&doutData)[2], INT16 (&aoutData)[2], UINT16 (&inputType)[8], UINT16 &inputFilter, UINT16 &scanFrequency, UINT16 &outputType ) 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 • 0 = 0 to 5V • 1 = 0 to 10 V • 2 = 0 to 20 mA • 3 = 4 to 20 mA. inputFilter is a reference to a UINT16 variable. The input filter selection is written to this variable. • 0 = 3 Hz • 1 = 6 Hz • 2 = 11 Hz • 3 = 30 Hz scanFrequency is a reference to a UINT16 variable. The scan frequency selection is written to this variable. • 0 = 60 Hz Document (Version 2.22) 10/26/2012 321 Function Specifications • 1 = 50 Hz outputType is a reference to a UINT16 variable. The analog output type is written to this variable. • 0 = 0 to 20 mA • 1 = 4 to 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 <ctools.h> 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 = ioRead5606Outputs(5, doutData, aoutData, inputType, inputFilter, scanFrequency, outputType); // print data when option switch 4 is selected if (optionSwitch(4)) { if (!done) { fprintf(com4, "status = %u, Douts 0 to 7 = %X, Aout 0 = %d\r\n", status, doutData[0], aoutData[0]); done = TRUE; } } else { done = FALSE; Document (Version 2.22) 10/26/2012 322 Function Specifications } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 323 Function Specifications ioReadAin4 Read Data From 4-point Analog Input Module Syntax #include <ctools.h> BOOLEAN ioReadAin4(UINT16 moduleAddress, INT16 (&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 2.22) 10/26/2012 324 Function Specifications ioReadAin8 Read Data From 8-point Analog Input Module Syntax #include <ctools.h> BOOLEAN ioReadAin8(UINT16 moduleAddress, INT16 (&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 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 address is invalid; otherwise TRUE is returned. Document (Version 2.22) 10/26/2012 325 Function Specifications ioReadAout2 Read Data From 2-point Analog Output Module Syntax #include <ctools.h> BOOLEAN ioReadAout2(UINT16 moduleAddress, INT16 (&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 2.22) 10/26/2012 326 Function Specifications ioReadAout4 Read Data From 4-point Analog Output Module Syntax #include <ctools.h> BOOLEAN ioReadAout4(UINT16 moduleAddress, INT16 (&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 invalid; otherwise TRUE is returned. Document (Version 2.22) 10/26/2012 327 Function Specifications ioReadAout5303 Read Data From 2-point 5303 Analog Output Module Syntax #include <ctools.h> BOOLEAN ioReadAout5303(INT16 (&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 always returns TRUE. Document (Version 2.22) 10/26/2012 328 Function Specifications ioReadCounter4 Read Data From 4-point Counter Input Module Syntax #include <ctools.h> BOOLEAN ioReadCounter4(UINT16 moduleAddress, UINT32 (&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 2.22) 10/26/2012 329 Function Specifications ioReadCounter5232 Read Data From the 5232 Counter Inputs Syntax #include <ctools.h> BOOLEAN ioReadCounter5232 (UINT32 (&data)[4]) Description This function reads buffered data from the 5232 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 four 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 always returns TRUE. Document (Version 2.22) 10/26/2012 330 Function Specifications ioReadDin16 Read Data From 16-point Digital Input Module Syntax #include <ctools.h> BOOLEAN ioReadDin16(UINT16 moduleAddress, UINT16 & 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 2.22) 10/26/2012 331 Function Specifications ioReadDin32 Read 32 Digital Inputs Syntax #include <ctools.h> BOOLEAN ioReadDin32(UINT16 moduleAddress, UINT32 & 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 <ctools.h> #define IO_NOTIFICATION 0 void 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(com1, "Point Value"); for (point = 0; point < 32; point++) { fprintf(com1, "\n\r%d ", point); Document (Version 2.22) 10/26/2012 332 Function Specifications putchar(dinData & 0x0001 ? '1' :'0'); dinData >>= 1; } } Document (Version 2.22) 10/26/2012 333 Function Specifications ioReadDin5232 Read Data From 5232 Digital Inputs Syntax #include <ctools.h> BOOLEAN ioReadDin5232(UCHAR & data) Description This function reads buffered data from the 5232 digital inputs. Buffered data are updated when an I/O request for the module is processed. The function has one parameter: a reference to an UCHAR variable. Digital input data are copied to the variable. The four least significant data bits correspond to the four digital inputs. The function always returns TRUE. Document (Version 2.22) 10/26/2012 334 Function Specifications ioReadDin8 Read Data From 8-point Digital Input Module Syntax #include <ctools.h> BOOLEAN ioReadDin8(UINT16 moduleAddress, UCHAR & 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 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 2.22) 10/26/2012 335 Function Specifications ioReadDout16 Read Data From 16-point Digital Output Module Syntax #include <ctools.h> BOOLEAN ioReadDout16(UINT16 moduleAddress, UINT16 & 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 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 2.22) 10/26/2012 336 Function Specifications ioReadDout32 Read from 32 Digital Outputs Syntax #include <ctools.h> BOOLEAN ioReadDout32( UINT16 moduleAddress, UINT32 & 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, ioReadDout32 Document (Version 2.22) 10/26/2012 337 Function Specifications ioReadDout8 Read Data From 8-point Digital Output Module Syntax #include <ctools.h> BOOLEAN ioReadDout8(UINT16 moduleAddress, UCHAR & 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 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 2.22) 10/26/2012 338 Function Specifications IoRequest Add I/O Module Scan Request to Request Queue Syntax #include <ctools.h> 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. I/O Module Type Address Range MT_Ain4 MT_Ain8 MT_Aout2 MT_Aout4 MT_Din8 MT_Din16 MT_Dout8 MT_Dout16 MT_Counter4 MT_5601Inputs MT_5601Outputs MT_5904Inputs MT_5904Outputs MT_CounterSP2 MT_SP2Inputs MT_SP2Outputs MT_Dout32 MT_Din32 MT_5604Inputs MT_5604Outputs MT_Aout4_Checksum MT_4203DRInputs MT_4203DROutputs MT_4203DSInputs 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 not applicable not applicable 0 to 3 0 to 3 not applicable not applicable not applicable 0 to 15 0 to 15 not applicable not applicable 0 to 15 not applicable not applicable not applicable Document (Version 2.22) 10/26/2012 339 Function Specifications I/O Module Type Address Range MT_4203DSOutputs MT_410Inputs MT_5210Inputs MT_5210Outputs MT_5607Inputs MT_5607Outputs MT_5414Inputs MT_5414Outputs MT_5415Inputs MT_5415Outputs MT_5411Inputs MT_5411Outputs MT_5606Inputs MT_5606Outputs MT_5506Inputs MT_5506Outputs MT_5505Inputs MT_5505Outputs not applicable not applicable not applicable not applicable 0 to 7 0 to 7 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 7 0 to 7 0 to 15 0 to 15 0 to 15 0 to 15 Document (Version 2.22) 10/26/2012 340 Function Specifications ioSetConfiguration Set I/O Controller Configuration Syntax #include <ctools.h> BOOLEAN ioSetConfiguration(const IO_CONFIG & 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 IO_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 2.22) 10/26/2012 341 Function Specifications ioStatus Read Status of Last Scan of Specified I/O Module Syntax #include <ctools.h> 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 IO_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. I/O Module Type Address Range MT_Ain4 MT_Ain8 MT_Aout2 MT_Aout4 MT_Din8 MT_Din16 MT_Dout8 MT_Dout16 MT_Counter4 MT_5601Inputs MT_5601Outputs MT_5904Inputs MT_5904Outputs MT_CounterSP2 MT_SP2Inputs MT_SP2Outputs MT_Dout32 MT_Din32 MT_5604Inputs MT_5604Outputs MT_Aout4_Checksum MT_4203DRInputs 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 not applicable not applicable 0 to 3 0 to 3 not applicable not applicable not applicable 0 to 15 0 to 15 not applicable not applicable 0 to 15 not applicable Document (Version 2.22) 10/26/2012 342 Function Specifications I/O Module Type Address Range MT_4203DROutputs MT_4203DSInputs MT_4203DSOutputs MT_410Inputs MT_5210Inputs MT_5210Outputs MT_5607Inputs MT_5607Outputs MT_5414Inputs MT_5414Outputs MT_5415Inputs MT_5415Outputs MT_5411Inputs MT_5411Outputs MT_5606Inputs MT_5606Outputs MT_5506Inputs MT_5506Outputs MT_5505Inputs MT_5505Outputs not applicable not applicable not applicable not applicable not applicable not applicable 0 to 7 0 to 7 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 15 0 to 7 0 to 7 0 to 15 0 to 15 0 to 15 0 to 15 Document (Version 2.22) 10/26/2012 343 Function Specifications ioSystemReset Add Reset Request to I/O Controller Request Queue Syntax #include <ctools.h> 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 I/O 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 2.22) 10/26/2012 344 Function Specifications ioVersion Get the I/O Controller Firmware Version Syntax #include <ctools.h> BOOLEAN ioVersion(UINT16 & pVersion) Description This function returns the I/O controller firmware version. The version is read from the I/O controller at initialization. The function has one argument: a reference to an UINT16 value to which the firmware version is copied if it is available. The function 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 2.22) 10/26/2012 345 Function Specifications ioWrite5414Outputs Write 5414 module configuration parameter outputs Syntax #include <ctools.h> BOOLEAN ioWrite5414Outputs( 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. • 0 = DC • 1 = AC scanFrequency selects the scan frequency setting. Valid values are. • 0 = 60 Hz • 1 = 50 Hz See Also ioRead5414Inputs Document (Version 2.22) 10/26/2012 346 Function Specifications ioWrite5415Outputs Write 5415 module outputs Syntax #include <ctools.h> BOOLEAN ioWrite5415Outputs( UINT16 moduleAddress, UCHAR (&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 ioRead5415Outputs, ioRead5415Inputs Document (Version 2.22) 10/26/2012 347 Function Specifications ioWrite5505Outputs Write 5505 Configuration Syntax #include <ctools.h> BOOLEAN ioWrite5505Outputs( UINT16 moduleAddress, UINT16 (&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 • 0 = RTD in deg Celsius • 1 = RTD in deg Fahrenheit • 2 = RTD in deg Kelvin • 3 = resistance measurement in ohms. inputFilter selects input filter selection is written to this variable. • 0 = 0.5 s • 1=1s • 2=2s • 3=4s The function returns FALSE if the module address is invalid; otherwise TRUE is returned. See Also ioRead5505Inputs, ioRead5505Outputs Example This program writes configuration data to the 5505 module at address 5. #include <ctools.h> #define MY_EVENT 1 void main(void) { UINT16 inputType[4]; Document (Version 2.22) 10/26/2012 348 Function Specifications UINT16 inputFilter; IO_STATUS io_status; BOOLEAN status; // main loop while (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 = ioWrite5505Outputs(5, inputType, inputFilter); // add module scan to queue if (!ioRequest(MT_5505Outputs, 5)) { status = FALSE; } // wait for scan to complete ioNotification(MY_EVENT); wait_event(MY_EVENT); // check status of last scan if (!ioStatus(MT_5505Outputs, 5, &io_status)) { status = FALSE; } else if (!io_status.commStatus) { status = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 349 Function Specifications ioWrite5506Outputs Write 5506 Configuration Syntax #include <ctools.h> BOOLEAN ioWrite5506Outputs( UINT16 moduleAddress, UINT16 (&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 • 0 = 0 to 5V • 1 = 1 to 5 V • 2 = 0 to 20 mA • 3 = 4 to 20 mA. inputFilter selects input filter selection is written to this variable. • 0 = 3 Hz • 1 = 6 Hz • 2 = 11 Hz • 3 = 30 Hz scanFrequency selects the scan frequency setting. Valid values are. • 0 = 60 Hz • 1 = 50 Hz The function returns FALSE if the module address is invalid; otherwise TRUE is returned. See Also ioRead5506Inputs, ioRead5506Outputs Example This program writes configuration data to the 5506 module at address 5. Document (Version 2.22) 10/26/2012 350 Function Specifications #include <ctools.h> #define MY_EVENT 1 void main(void) { UINT16 inputType[8]; UINT16 inputFilter; UINT16 scanFrequency; IO_STATUS io_status; BOOLEAN status; // main loop while (TRUE) { /* 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] = 3; inputType[7] = 3; /* set filter and frequency */ inputFilter = 3; // minimum filter scanFrequency = 0; // 60 Hz status = ioWrite5506Outputs(5, inputType, inputFilter, scanFrequency); // add module scan to queue if (!ioRequest(MT_5506Outputs, 5)) { status = FALSE; } // wait for scan to complete ioNotification(MY_EVENT); wait_event(MY_EVENT); // check status of last scan if (!ioStatus(MT_5506Outputs, 5, &io_status)) { status = FALSE; } else if (!io_status.commStatus) { status = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 351 Function Specifications ioWrite5601Outputs Write 5601 Outputs Syntax #include <ctools.h> BOOLEAN ioWrite5601Outputs(UINT16 data) Description This function writes data to the I/O table for the 12 digital outputs of a 5601 I/O module (SCADAPack 32 lower I/O module). Data are written to the module when an I/O request for the module is processed. The function has one parameter: the data to be written. Data are read from the 16-bit data value and written to the I/O table. The least significant 12 bits are used. The valid range for moduleAddress is 0 to 15. The function always returns TRUE. See Also ioRead5604Outputs, ioWrite5604Outputs Document (Version 2.22) 10/26/2012 352 Function Specifications ioWrite5604Outputs Write 5604 Outputs Syntax #include <ctools.h> BOOLEAN ioWrite5604Outputs( UCHAR doutData[5], INT16 aoutData[2]) Description This function writes data to the I/O table for the 34 digital outputs and 2 analog outputs of a 5604 I/O module. Data are written to the module when an I/O request for the module is processed. doutData is a reference to an array of five UCHAR variables. Digital data for the 34 outputs are written to the I/O table from this array. One bit in the array represents each output point. For digital I/O points used as digital inputs, write a 0 for the corresponding point in the doutData array. ainData is a reference to an array of two INT16 variables. Analog data are written to the I/O table from this array. The function always returns TRUE. See Also ioRead5604Outputs, ioRead5604Inputs Document (Version 2.22) 10/26/2012 353 Function Specifications ioWrite5606Outputs Write 5606 Outputs Syntax #include <ctools.h> BOOLEAN ioWrite5606Outputs( UINT16 moduleAddress, UCHAR (&doutData)[2], INT16 (&aoutData)[2], UINT16 (&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 • 0 = 0 to 5V • 1 = 0 to 10 V • 2 = 0 to 20 mA • 3 = 4 to 20 mA. inputFilter selects input filter selection is written to this variable. • 0 = 3 Hz • 1 = 6 Hz • 2 = 11 Hz • 3 = 30 Hz scanFrequency selects the scan frequency setting. Valid values are. • 0 = 60 Hz • 1 = 50 Hz Document (Version 2.22) 10/26/2012 354 Function Specifications outputType selects the analog output type setting. Valid values are. • 0 = 0 to 20 mA • 1 = 4 to 20 mA. 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 <ctools.h> #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 doutData[0] = doutData[1] = aoutData[0] = aoutData[1] = to output tables for next scan 0xFF; 0xFF; 32767; 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] = 3; 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 2.22) 10/26/2012 355 Function Specifications status = ioWrite5606Outputs(5, doutData, aoutData, inputType, inputFilter, scanFrequency, outputType); // add module scan to queue if (!ioRequest(MT_5606Outputs, 5)) { status = FALSE; } // wait for scan to complete ioNotification(MY_EVENT); wait_event(MY_EVENT); // check status of last scan if (!ioStatus(MT_5606Outputs, 5, &io_status)) { status = FALSE; } else if (!io_status.commStatus) { status = FALSE; } // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 356 Function Specifications ioWriteAout2 Write Data to 2-Point Analog Output Module Syntax #include <ctools.h> BOOLEAN ioWriteAout2(UINT16 moduleAddress, INT16 (&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 function has two parameters: the module address, and a reference to an array 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 function returns TRUE if the data was written. The function returns FALSE if the module address is invalid. Document (Version 2.22) 10/26/2012 357 Function Specifications ioWriteAout4 Write Data to 4-Point Analog Output Module Syntax #include <ctools.h> BOOLEAN ioWriteAout4(UINT16 moduleAddress, INT16 (&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. Call ioRequest with the module type MT_Aout4 for analog output modules without checksum support. All modules can use this module type. 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 <ctools.h> void 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 module address 0 */ ioWriteAout4(0, dataArray); ioRequest(MT_Aout4, 0); } Document (Version 2.22) 10/26/2012 358 Function Specifications ioWriteAout5303 Write Data to 5303 Analog Output Module Syntax #include <ctools.h> BOOLEAN ioWriteAout5303(INT16 (&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 always returns TRUE. Document (Version 2.22) 10/26/2012 359 Function Specifications ioWriteDout16 Write Data to 16-Point Digital Output Module Syntax #include <ctools.h> 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 2.22) 10/26/2012 360 Function Specifications ioWriteDout32 Write to 32 Digital Outputs Syntax #include <ctools.h> 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 ioWriteDout8, ioWriteDout16 Example This program turns ON the 32 digital outputs of a 32-point Digital Output Module at module address 0. #include <ctools.h> void main(void) { /* Write data to digital output module */ ioWriteDout32(0, 0xFFFFFFFF); ioRequest(MT_Dout32, 0); } Document (Version 2.22) 10/26/2012 361 Function Specifications ioWriteDout8 Write Data to 8-Point Digital Output Module Syntax #include <ctools.h> 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 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 2.22) 10/26/2012 362 Function Specifications ipFindFriendlyIPAddress 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 2.22) 10/26/2012 363 Function Specifications ipGetConnectionSummary Get Summary of Active TCP/IP Connections Syntax #include <ctools.h> 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, 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. 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 2.22) 10/26/2012 364 Function Specifications ipGetInterfaceType Get Interface Type from IP Address Syntax #include <ctools.h> BOOLEAN ipGetInterfaceType( IP_ADDRESS localIP, COM_INTERFACE * pIfType ); Description The function ipGetInterfaceType determines the interface that is configured to the specified local IP address, localIP. 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. Document (Version 2.22) 10/26/2012 365 Function Specifications ipInitializeFriendlyIPSettings Reset the friendly IP list Syntax void ipInitializeFriendlyIPSettings(void); Description This function deletes all Friendly IP List entries and disables the Friendly IP List. The function has no parameters. The function has no return value. Document (Version 2.22) 10/26/2012 366 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 2.22) 10/26/2012 367 Function Specifications ipReadFriendlyIPListEntry Read one entry in the friendly IP list. Syntax BOOLEAN ipIpReadFriendlyIPListEntry( UINT16 index, IP_ADDRESS *pIpAddressStart IP_ADDRESS *pIpAddressEnd ); 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. pIpAddressStart and pIpAddressStart are pointers to IP addresses; they are written by this function. The function returns TRUE if successful and FALSE if the index is invalid. See Also ipReadFriendlyIPListSize, ipWriteFriendlyIPListEntry, ipWriteFriendlyIPListSize Document (Version 2.22) 10/26/2012 368 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. 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 ipReadFriendlyIPListEntry, ipWriteFriendlyIPListEntry, ipWriteFriendlyIPListSize Document (Version 2.22) 10/26/2012 369 Function Specifications ipWriteFriendlyListControl Enable or disable the friendly IP list. Syntax BOOLEAN ipWriteFriendlyListControl( BOOLEAN state ); 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 2.22) 10/26/2012 370 Function Specifications ipWriteFriendlyIPListEntry Write one entry in the friendly IP list. Syntax BOOLEAN ipWriteFriendlyIPListEntry( UINT16 index, IP_ADDRESS ipAddressStart, IP_ADDRESS ipAddressEnd ); 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 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 ipReadFriendlyIPListSize, ipReadFriendlyIPListEntry, ipWriteFriendlyIPListSize Document (Version 2.22) 10/26/2012 371 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 ipReadFriendlyIPListSize, ipReadFriendlyIPListEntry, ipWriteFriendlyIPListEntry, ipReadFriendlyListControl, ipWriteFriendlyListControl Document (Version 2.22) 10/26/2012 372 Function Specifications ledGetDefault Read LED Power Control Parameters Syntax #include <ctools.h> 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 controller. The LED power returns to its default state after a user specified time period. Example See the example for the ledSetDefault function. Document (Version 2.22) 10/26/2012 373 Function Specifications ledPower Set LED Power State Syntax #include <ctools.h> 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, ledGetDefault, ledSetDefault Document (Version 2.22) 10/26/2012 374 Function Specifications ledPowerSwitch Read State of the LED Power Switch Syntax #include <ctools.h> 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 2.22) 10/26/2012 375 Function Specifications ledSetDefault Set Default Parameters for LED Power Control Syntax #include <ctools.h> 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 ledControl 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 <ctools.h> void main(void) { struct ledControl_tag ledControl; request_resource(IO_SYSTEM); /* Turn LEDS off after 20 minutes */ ledControl.time = 20; ledControl.state = LED_OFF; ledSetDefault(ledControl); release_resource(IO_SYSTEM); /* ... the reset of the program */ } Document (Version 2.22) 10/26/2012 376 Function Specifications listen Syntax #include <ctools.h> int listen ( int socketDescriptor, int backLog ); Function 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 TM_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: TM_EADDRINUSE The address is currently used by another socket. TM_ EBADF The socket descriptor is invalid. TM_ EOPNOTSUPP The socket is not of a type that supports the operation listen. Document (Version 2.22) 10/26/2012 377 Function Specifications master_message Send Protocol Command Syntax #include <ctools.h> 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. • stream specifies the serial port. • function specifies the protocol function code. Refer to the communication protocol manual for supported function codes. • slave specifies the network address of the slave station. This is also known as the slave station number. • 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. • 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. • length specifies the number or registers. The master_message function returns the command status from the protocol driver. Value Description MM_SENT MM_BAD_FUNCTION MM_BAD_SLAVE MM_BAD_ADDRESS MM_BAD_LENGTH MM_EXCEPTION_FUNCTION message transmitted to slave function is not recognized slave station number is not valid slave or master database address not valid too many or too few registers specified Master message status: Modbus slave returned a function exception. Master message status: Modbus slave returned an address exception. Master message status: Modbus slave returned a value exception. MM_EXCEPTION_ADDRESS MM_EXCEPTION_VALUE The calling task monitors the status of the command sent using the get_protocol_status function. The command field of the prot_status structure is Document (Version 2.22) 10/26/2012 378 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-3 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 com3 are for local operator display terminals, and for programming and diagnostics using the IEC 61131-3 program. The IO_SYSTEM resource needs to be requested before calling this function. Use of the master_message function while ladder logic in flash is being started may result in a truncated or lost command. Building retry logic into the C program or delaying the transmission of master_message until the ladder logic program has started is recommended. See Also clear_protocol_status, get_protocol_status, serialModbusMaster Example See the example in the Example Programs chapter under the section Master Message Example Using Modbus Protocol. Document (Version 2.22) 10/26/2012 379 Function Specifications modbusExceptionStatus Set Response to Protocol Command Syntax #include <ctools.h> 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 modbusSlaveID Document (Version 2.22) 10/26/2012 380 Function Specifications modbusSlaveID Set Response to Protocol Command Syntax #include <ctools.h> void modbusSlaveID(UCHAR *string, UINT16 length); Description The modbusSlaveID 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 needs to 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 2.22) 10/26/2012 381 Function Specifications modemAbort Unconditionally Terminate Dial-up Connection Syntax #include <ctools.h> void modemAbort(FILE *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 need 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-3 stops the C application and when the controller is rebooted. Reservation IDs returned by the modemDial and modemInit functions on this port are invalid after calling modemAbort. See Also modemAbortAll, modemDial, modemDialEnd, modemDialStatus, modemInit, modemInitEnd, modemInitStatus, modemNotification Example Refer to the examples in the Functions Overview section. Document (Version 2.22) 10/26/2012 382 Function Specifications modemAbortAll Unconditionally Terminate All Dial-up Connections Syntax #include <ctools.h> void modemAbortAll(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 need 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-3 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 modemAbort, modemDial, modemDialEnd, modemDialStatus, modemInit, modemInitEnd, modemInitStatus, modemNotification 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-3 ends the main task. However, it demonstrates how to use the Document (Version 2.22) 10/26/2012 383 Function Specifications modemAbortAll function and an exit handler for another task in a more complex program. #include <ctools.h> /* -------------------------------------------The shutdown function aborts any active modem connections when the task is ended. -------------------------------------------- */ void shutdown(void) { modemAbortAll(); } void main(void) { TASKINFO taskStatus; /* set up exit handler for this task */ getTaskInfo(0, &taskStatus); installExitHandler(taskStatus.taskID, shutdown); while(TRUE) { /* rest of main task here */ /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 384 Function Specifications modemDial Connect to a Remote Dial-up Controller Syntax #include <ctools.h> 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 all 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 ensures 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 pause 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 reenabled. 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 a modemInit 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 problems with the modem or the calling application from permanently disabling outgoing calls. Document (Version 2.22) 10/26/2012 385 Function Specifications 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-3 program. This function cannot be called in a task exit handler. See Also modemAbort, modemAbortAll, modemDialEnd, modemDialStatus, modemInit, modemInitEnd, modemInitStatus, modemNotification Example Refer to the examples in the Connecting with a Remote Controller Example section. Document (Version 2.22) 10/26/2012 386 Function Specifications modemDialEnd Terminate Dial-up Connection Syntax #include <ctools.h> 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 needs to 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. Execution of the modemDialEnd function. Execution of the modemAbort or modemAbortAll functions. The remote device hangs up the phone line. 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. This fuinction cannot be called in a task exit handler. Use modemAbort instead. See Also modemAbort, modemAbortAll, modemDial, modemDialStatus, modemInit, modemInitEnd, modemInitStatus, modemNotification Document (Version 2.22) 10/26/2012 387 Function Specifications modemDialStatus Return Status of Dial-up Connection Syntax #include <ctools.h> 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 needs to 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. This function cannot be called in a task exit handler. See Also modemAbort, modemAbortAll, modemDial, modemDialEnd, modemInit, modemInitEnd, modemInitStatus, modemNotification Document (Version 2.22) 10/26/2012 388 Function Specifications modemInit Initialize Dial-up Modem Syntax #include <ctools.h> enum DialError modemInit(struct ModemInit *configuration, reserve_id *id); Description The modemInit 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 modemInit function may be active on each serial port. The modemInit function handles all 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 ensures 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 needs to be set to RS232_MODEM. The modemInitStatus function returns the status of the connection attempt initiated by modemInit. The modemInitEnd function terminates initialization of the modem. If a communication protocol is active on the serial port, the protocol will be disabled 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 a modemDial 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-3 program. This function cannot be called in a task exit handler. Document (Version 2.22) 10/26/2012 389 Function Specifications See Also modemAbort, modemAbortAll, modemDial, modemDialEnd, modemDialStatus, modemInitEnd, modemInitStatus, modemNotification Example Refer to the example in the Modem Initialization Example section. Document (Version 2.22) 10/26/2012 390 Function Specifications modemInitEnd Abort Initialization of Dial-up Modem Syntax #include <ctools.h> void modemInitEnd(FILE *port, reserve_id id, enum DialError *error); Description The modemInitEnd 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 pointed 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 needs to 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. This function cannot be called in a task exit handler. Use modemAbort instead. See Also modemAbort, modemAbortAll, modemDial, modemDialEnd, modemDialStatus, modemInit, modemInitStatus, modemNotification Document (Version 2.22) 10/26/2012 391 Function Specifications modemInitStatus Return Status of Dial-up Modem Initialization Syntax #include <ctools.h> 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 codes. 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 needs to 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. This function cannot be called in a task exit handler. See Also modemAbort, modemAbortAll, modemDial, modemDialEnd, modemDialStatus, modemInit, modemInitEnd, modemNotification Document (Version 2.22) 10/26/2012 392 Function Specifications modemNotification Notify the modem handler of an important event Syntax #include <ctools.h> 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 needs to be set to RS232_MODEM. Use the portIndex function to obtain the index of the serial port. The dial-up connection handler prevents 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 prevents problems with 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. See Also modemAbort, modemAbortAll, modemDial, modemDialEnd, modemDialStatus, modemInit, modemInitEnd, modemInitStatus Document (Version 2.22) 10/26/2012 393 Function Specifications mTcpGetConfig Get Modbus/TCP Protocol Settings Syntax #include <ctools.h> UINT16 mTcpGetConfig(MTCP_CONFIGURATION * 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, 0 is returned. See Also mTcpSetConfig Document (Version 2.22) 10/26/2012 394 Function Specifications mTcpGetInterface Get Modbus IP Interface Settings Syntax #include <ctools.h> BOOLEAN mTcpGetInterface( COM_INTERFACE ifType, MTCP_IF_SETTINGS * pSettings ); Description The mTcpGetInterface 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 pSettings. 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. See Also mTcpSetInterface Document (Version 2.22) 10/26/2012 395 Function Specifications mTcpGetInterfaceEx Get Modbus IP Interface Extended Settings Syntax #include <ctools.h> BOOLEAN mTcpGetInterfaceEx( COM_INTERFACE ifType, MTCP_IF_SETTINGS_EX * pSettings ); Description This function returns the interface settings used for Modbus IP protocols, including Enron Modbus settings. The function has two parameters: ifType specifies the interface. The valid value is CIF_Ethernet1. 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. See Also mTcpSetInterfaceEx, mTcpSetInterface, mTcpGetInterface Document (Version 2.22) 10/26/2012 396 Function Specifications mTcpGetProtocol Get Modbus IP Protocol Settings Syntax #include <ctools.h> BOOLEAN mTcpGetProtocol(IP_PROTOCOL_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 2.22) 10/26/2012 397 Function Specifications mTcpSetConfig Set Modbus/TCP Protocol Settings Syntax #include <ctools.h> BOOLEAN mTcpSetConfig(MTCP_CONFIGURATION * pSettings); Description The mTcpSetConfig function is used to configure settings common to all connections using the Modbus/TCP protocol. All 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 function. All other changes take effect on existing as well as new connections. The function copies settings from the structure pointed to by pSettings 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); See Also mTcpGetConfig Document (Version 2.22) 10/26/2012 398 Function Specifications mTcpSetInterface Set Modbus IP Interface Settings Syntax #include <ctools.h> 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 flashSettingsSave as shown below. request_resource(FLASH_MEMORY); flashSettingsSave(CS_RUN); release_resource(FLASH_MEMORY); See Also mTcpGetInterface Document (Version 2.22) 10/26/2012 399 Function Specifications mTcpSetInterfaceEx Set Modbus IP Interface Extended Settings Syntax #include <ctools.h> BOOLEAN mTcpSetInterfaceEx( COM_INTERFACE ifType, MTCP_IF_SETTINGS_EX * pSettings ); Description This function sets the interface settings used for Modbus IP protocols, including Enron Modbus settings. The function has two parameters: ifType specifies the interface. The valid value is CIF_Ethernet1. 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. See Also mTcpGetInterfaceEx, mTcpSetInterface, mTcpGetInterface Document (Version 2.22) 10/26/2012 400 Function Specifications mTcpSetProtocol Set Modbus IP Protocol Settings Syntax #include <ctools.h> BOOLEAN mTcpSetProtocol(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. All 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 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. See Also mTcpGetProtocol, mTcpSetInterfaceEx Document (Version 2.22) 10/26/2012 401 Function Specifications mTcpMasterClose Close Modbus IP Master Messaging Session Syntax #include <ctools.h> 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. See Also mTcpMasterOpen, mTcpMasterMessage, mTcpMasterStatus, mTcpMasterDisconnect Example See example for mTcpMasterMessage. Document (Version 2.22) 10/26/2012 402 Function Specifications mTcpMasterDisconnect Disconnect Modbus IP Master Connection Syntax #include <ctools.h> 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 connectID 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. See Also mTcpMasterOpen, mTcpMasterMessage, mTcpMasterStatus, Example See example for mTcpMasterMessage. Document (Version 2.22) 10/26/2012 403 Function Specifications mTcpMasterMessage Send a Modbus IP Master Message Syntax #include <ctools.h> 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); Description 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 remoteIP specifies the IP address of the remote slave. The value of remoteIP 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 connectID 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 remoteIP 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: • function specifies the Modbus function code. Refer to the communication protocol manual for supported function codes. • slaveStation specifies the network address of the slave station. This is also known as the slave station number. • slaveRegister specifies a Modbus register in the slave station. Depending on the protocol function code, data may be read or written at this location. • 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. • length specifies the number of registers. Document (Version 2.22) 10/26/2012 404 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/IP 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 always 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. See Also mTcpMasterOpen, mTcpMasterStatus, mTcpMasterDisconnect, Example See the example in the Example Programs chapter under the section Master IP Message Example. Document (Version 2.22) 10/26/2012 405 Function Specifications mTcpMasterOpen Open a Modbus IP Master Connection Syntax #include <ctools.h> BOOLEAN mTcpMasterOpen( IP_ADDRESS remoteIP, IP_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 remoteIP is attempted. However, the connection ID and master task are not restricted to just one remoteIP. The currently connected IP address may be disconnected and connected to a different IP address any time mTcpMasterMessage is called with a different remoteIP 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 appType: 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 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 2.22) 10/26/2012 406 Function Specifications Notes The functions mTcpMasterDisconnect and mTcpMasterClose must 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 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. See Also mTcpMasterMessage, mTcpMasterStatus, mTcpMasterDisconnect, Example See example for mTcpMasterMessage. Document (Version 2.22) 10/26/2012 407 Function Specifications mTcpMasterStatus Modbus IP Master Command Status Syntax #include <ctools.h> 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. See Also mTcpMasterOpen, mTcpMasterMessage, mTcpMasterDisconnect, Example See example for mTcpMasterMessage. Document (Version 2.22) 10/26/2012 408 Function Specifications mTcpRunServer Run Modbus IP Servers Syntax #include <ctools.h> 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. See Also mTcpGetConfig Document (Version 2.22) 10/26/2012 409 Function Specifications ntohl Syntax #include <ctools.h> unsigned long ntohl (unsigned long longValue); Function 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 2.22) 10/26/2012 410 Function Specifications ntohs Syntax #include <ctools.h> unsigned short ntohs(unsigned short shortValue); Function Description This function converts a short value from network byte order to host byte order. Parameters shortValue The value to convert Returns The converted value. Document (Version 2.22) 10/26/2012 411 Function Specifications optionSwitch Read State of Controller Option Switches Syntax #include <ctools.h> UINT16 optionSwitch(UINT16 option); Description The optionSwitch function returns the state of the controller option switch specified by option. option may be 1, 2, 3 or 4. The function returns OPEN if the switch is in the open position. It returns CLOSED if the switch is in the closed position. Notes The option switches are located under the cover of the controller module. All options are user defined. However, when a SCADAPack 32 I/O module is placed in the Register Assignment, option switch 1 selects the input range for analog inputs on this module. Option switch 3 selects the line frequency option for digital and analog input processing on this module. When the SCADAPack 32 AOUT module is placed in the Register Assignment, option switch 2 selects the output range for analog outputs on this module. Refer to the SCADAPack 32 System Hardware Manual for further information on option switches. Document (Version 2.22) 10/26/2012 412 Function Specifications overrideDbase Overwrite Value in Forced I/O Database (Telepace firmware only) Syntax #include <ctools.h> 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 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR 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 function. See Also getForceFlag, setForceFlag, clearAllForcing Example #include <ctools.h> void main(void) { request_resource(IO_SYSTEM); overrideDbase(MODBUS, 40001, 102); Document (Version 2.22) 10/26/2012 413 Function Specifications overrideDbase(LINEAR, 302, 330); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 414 Function Specifications pidExecute Execute PID control algorithm. Syntax #include <ctools.h> 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. Call the pidInitialize function once before calling this function the first time, or put the PID algorithm in manual mode (autoMode = FALSE in PID_DATA) for the first call to the pidExecute function. See Also pidInitialize 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 <ctools.h> // event number to signal when I/O scan completes #define IO_COMPLETE 0 void main(void) { INT16 ainData[4]; INT16 aoutData[4]; PID_DATA pidData; BOOLEAN executed; // // // // analog input data analog output data PID algorithm data indicates if PID executed // read analog input ioRequest(MT_Ain4, 0); ioNotification(IO_COMPLETE); wait_event(IO_COMPLETE); Document (Version 2.22) 10/26/2012 415 Function Specifications ioReadAin4(0, ainData); // get initial process value from analog input pidData.pv = ainData[0]; // configure PID block pidData.sp = pidData.gain = pidData.reset = pidData.rate = pidData.deadband = pidData.fullScale = pidData.zeroScale = pidData.manualOutput = pidData.period = pidData.autoMode = 1000; 1; 100; 0; 10; 32767; 0; 0; 1000; TRUE; // initialize the PID block pidInitialize(&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 executed = pidExecute(&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 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 416 Function Specifications pidInitialize Initialize PID controller data. Syntax #include <ctools.h> 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 needs to 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 2.22) 10/26/2012 417 Function Specifications pollABSlave Poll DF1 Slave for Response Syntax #include <ctools.h> 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 DF1 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 is used in the sample polling function "poll_for_response" shown in this example. See Also master_message, resetAllABSlaves Example This program segment polls slave station 9 for a response communicating on the com2 serial port. #include <ctools.h> pollABSlave(com2, 9); Document (Version 2.22) 10/26/2012 418 Function Specifications poll_event Test for Event Occurrence Syntax #include <ctools.h> 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 continues to execute. Notes Refer to the Real Time Operating System section for more information on events. Valid events are numbered 0 to 31. Any events defined in ctools.h are not valid events for use in an application program. See Also startTimedEvent Example This program implements a somewhat inefficient transfer of data between com1 and com2. (It would be more efficient to test for EOF from getc). #include <ctools.h> void main(void) { while(TRUE) { if (poll_event(COM1_RCVR)) fputc(getc(com1), com2); if (poll_event(COM2_RCVR)) fputc(getc(com2), com1); /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 419 Function Specifications poll_message Test for Received Message Syntax #include <ctools.h> 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 continues to execute. Notes Refer to the Real Time Operating System section for more information on messages. See Also allocate_envelope, send_message Example This task performs a function continuously, and processes received messages (from higher priority tasks) when they are received. #include <ctools.h> void task(void) { envelope *letter; while(TRUE) { letter=poll_message(); if (letter != NULL) /* process the message now */ /* more code here */ } } Document (Version 2.22) 10/26/2012 420 Function Specifications poll_resource Test Resource Availability Syntax #include <ctools.h> 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 continues to execute. Notes Refer to the Real Time Operating System section for more information on resources. See Also request_resource, release_resource Document (Version 2.22) 10/26/2012 421 Function Specifications portIndex Get Index of Serial Port Syntax #include <ctools.h> UINT16 portIndex(FILE *stream); Description The portIndex function returns an array index for the serial port specified by stream. It returns 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 2.22) 10/26/2012 422 Function Specifications portStream Get Serial Port Corresponding to Index Syntax #include <ctools.h> FILE *portStream(UINT16 index); 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 2.22) 10/26/2012 423 Function Specifications pppGetInterfaceHandle Read PPP Interface Handle Syntax: #include <ctools.h> ttUserInterface pppGetInterfaceHandle(FILE * stream); Description: This function returns the PPP interface handle for the specified serial port. This function is for use with PPP C Tools functions that require an interface handle. Document (Version 2.22) 10/26/2012 424 Function Specifications pppReadSettings Read PPP Setings Syntax: #include <ctools.h> BOOLEAN pppReadSettings ( FILE * stream, PPP_SETTINGS *settings ); Description: This function reads the PPP settings for the specified serial port. settings is a pointer to a PPP_SETTINGS structure; it is written by this function. The PPP_SETTINGS structure is described in the Structures and Types section. The return value is TRUE if settings is successfully written, otherwise FALSE is returned. Example: See the example for pppWriteSettings. Document (Version 2.22) 10/26/2012 425 Function Specifications pppReadUserTableEntry Read PPP User Table Entry Syntax: #include <ctools.h> BOOLEAN pppReadUserTableEntry ( UCHAR index, CHAR * username, CHAR * password ); Description: This function reads the entry at index from the PPP username table. The valid range for index is 0 to 19. username needs to point to a 17-byte character array. password needs to point to a 17-byte character array. The contents of these arrays are written by this function. The username and password are copied to the respective array as a null-terminated string. The return value is TRUE if username and password are successfully written, otherwise FALSE is returned. Document (Version 2.22) 10/26/2012 426 Function Specifications pppReadUserTableSize Read PPP User Table Size Syntax #include <ctools.h> BOOLEAN pppWriteUserTableSize (UCHAR size); Description This function writes the size of the PPP username table. The maximum size is 20 usernames. When the size is written the previous username table is erased. The function returns TRUE if successful, otherwise FALSE is returned. Notes To save the username table with the controller settings in flash memory so that it is loaded on controller reset, call flashSettingsSave as shown below. // save username table with controller settings request_resource(FLASH_MEMORY); flashSettingsSave(CS_PERMANENT); release_resource(FLASH_MEMORY); Document (Version 2.22) 10/26/2012 427 Function Specifications pppWriteSettings Write PPP Settings Syntax: #include <ctools.h> BOOLEAN pppWriteSettings ( FILE * stream, PPP_SETTINGS *settings ); Description: This function writes the PPP settings for the specified serial port. settings is a pointer to a PPP_SETTINGS structure. The PPP_SETTINGS structure is described in the Structures and Types section. The return value is TRUE if the settings are written successfully, otherwise FALSE is returned. Notes To save the PPP Settings with the controller settings in flash memory so that they are loaded on controller reset, call flashSettingsSave as shown in the example below. Example: The example program writes the PPP settings for com1. #include <ctools.h> void main( void ) { PPP_SETTINGS pppSettings; // read the current PPP settings pppReadSettings(com1, &pppSettings); // modify settings pppSettings.serverEnabled = TRUE; pppSettings.ipVersion = 4; pppSettings.ipAddress[0] = inet_addr(“10.10.10.1”); pppSettings.subnetMask = inet_addr(“255.255.255.255”); pppSettings.remoteIpAddress[0] = inet_addr(“10.10.10.2”); pppSettings.autoRemoteIpAddress = FALSE; pppSettings.allowRemoteIpRequest = FALSE; pppSettings.idleTimeout = 30; pppSettings.authentication = LOGIN_CHAP; // write the PPP settings pppWriteSettings(com1, &pppSettings); // save PPP settings with controller settings Document (Version 2.22) 10/26/2012 428 Function Specifications request_resource(FLASH_MEMORY); flashSettingsSave(CS_PERMANENT); release_resource(FLASH_MEMORY); } Document (Version 2.22) 10/26/2012 429 Function Specifications pppWriteUserTableEntry Write PPP User Table Entry Syntax: #include <ctools.h> BOOLEAN pppWriteUserTableEntry ( UCHAR index, CHAR * username, CHAR * password ); Description: This function writes an entry at index into the PPP username table. The valid range for index is 0 to 19. username is a pointer to a null-terminated string. The maximum length of the string may be 16 characters. Any printable alphanumeric characters may be used for username. The minimum length is 1 character. password is a pointer to a null-terminated string. The maximum length of the string may be 16 characters. The password string contains the result of the actual password factored with a hashing algorithm. The original password string needs to be any printable alphanumeric characters. The minimum length is 1 character. The return value is TRUE if the entry is written successfully, otherwise FALSE is returned. Notes To save the username table with the controller settings in flash memory so that it is loaded on controller reset, call flashSettingsSave as shown in the example below. Document (Version 2.22) 10/26/2012 430 Function Specifications pppWriteUserTableSize Write PPP User Table Size Syntax #include <ctools.h> UCHAR pppReadUserTableSize(void); Description: This function returns the number of entries in the PPP username table. Document (Version 2.22) 10/26/2012 431 Function Specifications queue_mode Control Serial Data Transmission Syntax #include <ctools.h> 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 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. stream 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 2.22) 10/26/2012 432 Function Specifications readBoolVariable Read IEC 61131-3 Boolean Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 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-3 Symbols Status is invalid, FALSE is returned and the current value is left unchanged. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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 dbase Example This program displays the contents of the boolean variable named “Switch1”. #include <ctools.h> void main(void) { BOOLEAN status; UCHAR char value; request_resource(IO_SYSTEM); status = readBoolVariable("Switch1", &value); release_resource(IO_SYSTEM); printf("status = %u, Switch1 = %d\r\n", status, value); Document (Version 2.22) 10/26/2012 433 Function Specifications } Document (Version 2.22) 10/26/2012 434 Function Specifications readBattery Read Lithium Battery Voltage Syntax #include <ctools.h> 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 <ctools.h> if (readBattery() < 2500) { fprintf(com1, “Battery Voltage is low\r\n”); } Document (Version 2.22) 10/26/2012 435 Function Specifications readIntVariable Read IEC 61131-3 Integer Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 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-3 Symbols Status is invalid, FALSE is returned and the current value is left unchanged. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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 dbase Example This program displays the contents of the integer variable named “Temperature”. #include <ctools.h> void main(void) { BOOLEAN status; INT32 value; request_resource(IO_SYSTEM); status = readIntVariable("Temperature", &value); release_resource(IO_SYSTEM); printf("status = %u, Temp = %ld\r\n", status, value); Document (Version 2.22) 10/26/2012 436 Function Specifications } Document (Version 2.22) 10/26/2012 437 Function Specifications readMsgVariable Read IEC 61131-3 Message Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 Dictionary also treats variable names as case insensitive). 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-3 Symbols Status is invalid, FALSE is returned and the buffer is left unchanged. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share 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-3 message variables have the following format: Byte Location Description 0 Maximum length as declared in IEC 61131-3 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 1 2 … max + 1 max + 2 Last byte in message buffer Null termination byte (Terminates a message having the maximum length.) Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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. Document (Version 2.22) 10/26/2012 438 Function Specifications The IO_SYSTEM system resource needs to be requested before calling this function. See Also dbase Example This program displays the contents of the message variable named “msgData” of maximum length 20. #include <ctools.h> void main(void) { BOOLEAN status; UCHAR msg[23]; request_resource(IO_SYSTEM); status = readMsgVariable("msgData", msg); release_resource(IO_SYSTEM); printf("status = %u, max length = %d, current length = %d, message = %s\r\n", status, msg[0], msg[1], msg + 2); } Document (Version 2.22) 10/26/2012 439 Function Specifications readRealVariable Read IEC 61131-3 Real Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 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-3 Symbols Status is invalid, FALSE is returned and the current value is left unchanged. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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 dbase Example This program displays the contents of the real variable named “Flow”. #include <ctools.h> void main(void) { BOOLEAN status; float value; request_resource(IO_SYSTEM); status = readRealVariable("Flow", &value); release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 440 Function Specifications printf("status = %u, Flow = %f\r\n", status, value); } Document (Version 2.22) 10/26/2012 441 Function Specifications readStopwatch Read Stopwatch Timer Syntax #include <ctools.h> UINT32 readStopwatch(void) Description The readStopwatch function reads the stopwatch timer. The stopwatch time is in ms and has a resolution of 10 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 <ctools.h> void main(void) { UINT32 startTime, endTime; startTime = readStopwatch(); /* operation to be timed */ endTime = readStopwatch(); printf("Execution time = %lu ms\r\n", endTime - startTime); } Document (Version 2.22) 10/26/2012 442 Function Specifications readThermistor Read Controller Ambient Temperature Syntax #include <ctools.h> 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 <ctools.h> void checkTemperature(void) { INT16 temperature; temperature = readThermistor(T_FAHREHEIT); if (temperature < 0) fprintf(com1, “It’s COLD!!!\r\n”); else if (temperature > 90) fprintf(com1, “It’s HOT!!!\r\n”); } Document (Version 2.22) 10/26/2012 443 Function Specifications readTimerVariable Read IEC 61131-3 Timer Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> BOOLEAN readTimerVariable(unsigned char * varName, unsigned long * 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-3 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-3 Symbols Status is invalid, FALSE is returned and the current value is left unchanged. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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 dbase Example This program displays the contents of the timer variable named “Time1”. #include <ctools.h> void main(void) { BOOLEAN status; UINT32 value; request_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 444 Function Specifications status = readTimerVariable("Time1", &value); release_resource(IO_SYSTEM); printf("status = %u, Time1 = %lu\r\n", status, value); } Document (Version 2.22) 10/26/2012 445 Function Specifications read_timer_info Get Timer Status Syntax #include <ctools.h> struct timer_info read_timer_info(UINT16 index); Description The read_timer_info function gets status information for the timer specified by index. The read_timer_info function returns a timer_info structure with information about the specified timer. Refer to the description of the timer_info structure for information about the fields. Notes To enable support for timers, the function runTimers needs to be called once before using any of the timer functions (settimer, timer, interval, or read_timer_info). Document (Version 2.22) 10/26/2012 446 Function Specifications readv Syntax #include <ctools.h> int readv ( int socketDescriptor, struct iovec * iov, int iovcnt ); Function Description readv functions as a scatter read because the received data can be placed in multiple buffers. readv attempts to read data from the socket socketDescriptor and places the input data into the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1]. The iovec structure contains the following members: caddr_t iov_base; int iov_len; Each iovec entry specifies the base address and length of an area in memory where data should be placed. readv always fills one buffer completely before proceeding to the next. On success, readv returns the number of bytes actually read and placed in the buffer; this number may be less than the total of all of the iov_len values. A value of 0 is returned when an end-of-file has been reached. Parameters socketDescriptor The socket descriptor to read data from iov The list of buffers to put the received data into iovcnt The number of buffers in the list. Returns >0 Number of bytes actually read from the socket. 0 EOF -1 An error occurred readv will fail if: TM_EBADF The socket descriptor is invalid TM_EINVAL The iovcnt is 0 or less than 0. The sum of the iov_len values overflowed an integer TM_ENOBUFS There was insufficient user memory available to complete the operation TM_ EWOULDBLOCK The socket is marked as non-blocking and no data is available to be read. Document (Version 2.22) 10/26/2012 447 Function Specifications TM_ESHUTDOWN The peer has closed the connection and there is no more data to read (TCP socket only) TM_ENOTCONN Socket is not connected. Document (Version 2.22) 10/26/2012 448 Function Specifications receive_message Receive a Message Syntax #include <ctools.h> envelope *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 poll_message Example This task waits for messages, then prints their contents. The envelopes received are returned to the operating system. #include <ctools.h> void show_message(void) { envelope *msg; while (TRUE) { msg = receive_message(); printf("Message data %ld\r\n", msg->data); deallocate_envelope(msg); } } Document (Version 2.22) 10/26/2012 449 Function Specifications recv Syntax #include <ctools.h> int recv ( int socketDescriptor, char * bufferPtr, int bufferLength, int flags ); Function 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 TM_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 forced stopping is to allow us to execute the SOIOCATMARK tfIoctl to determine when we are at the out-of-band byte mark. Alternatively, tfGetOobDataOffset can be used instead of tfIoctl to determine the offset of the out-of-band data byte. When we are at the mark, recv with the MSG_OOB flag set can read the out-of-band data byte. Note that the user needs to either use select or tfRegisterSocketCB 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-ofband 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-ofband data will be read in line with the other data. Again, recv will not read past Document (Version 2.22) 10/26/2012 450 Function Specifications the position of the out-of-band mark in a single recv request. Again, tfIoctl with the SOIOCATMARK, or tfGetOobDataOffset can be used to determine where the last received out-of-band byte is in the stream. Note that the user needs to either use select or tfRegisterSocketCB in order to know when out-of-band data has arrived, or is arriving. select may be used to determine when more data arrives, or/and when out-ofband data arrives. tfRegisterSocketCB may be used to asynchronously determine when more data arrives, or/and when out-of-band 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 The flags parameter is formed by ORing one or more of the following: MSG_DONTWAIT Don’t wait for data, but rather return immediately MSG_OOB Read any “out-of-band” data present on the socket rather than the regular “in-band” data 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. Returns >0 Number of bytes actually received from the socket. 0 EOF -1 An error occurred recv will fail if: TM_EBADF The socket descriptor is invalid TM_ENOBUFS There was insufficient user memory available to complete the operation TM_ EMSGSIZE The socket requires that message be received atomically, and bufferLength was too small TM_EWOULDBLOCK 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 TM_ESHUTDOWN The remote socket has closed the connection, and there is no more data to be received (TCP socket only) Document (Version 2.22) 10/26/2012 451 Function Specifications TM_EINVAL 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 TM_ENOTCONN Socket is not connected. Document (Version 2.22) 10/26/2012 452 Function Specifications recvfrom Syntax #include <ctools.h> int recvfrom( int socketDescriptor, char * bufferPtr, int bufferLength, int flags, struct sockaddr * fromPtr, int * fromLengthPtr); Function 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 fromPtr 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 outofband data arrives. tfRegisterSocketCB may be used to asynchronously determine when more data arrives, or/and when out-of-band 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 fromLengthPtr The length of the data area the fromPtr points to then upon return the actual length of the from data The flags parameter 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 2.22) 10/26/2012 453 Function Specifications Returns >0 Number of bytes actually received from the socket. 0 EOF -1 An error occurred recvfrom will fail if: TM_EBADF The socket descriptor is invalid. TM_EINVAL One of the parameters is invalid. TM_ EMSGSIZE The socket requires that message be received atomically, and bufferLength was too small. TM_EPROTOTYPE TCP protocol requires usage of recv, not recvfrom. TM_ENOBUFS There was insufficient user memory available to comp lete the operation. TM_EWOULDBLOCK The socket is marked as non-blocking and no data is available to be read. Document (Version 2.22) 10/26/2012 454 Function Specifications release_processor Release Processor to other Tasks Syntax #include <ctools.h> 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, as each releases the processor to the next. Notes The release_processor function needs to be called in all idle loops of a program to allow other tasks to execute. 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 release_resource Document (Version 2.22) 10/26/2012 455 Function Specifications release_resource Release Control of a Resource Syntax #include <ctools.h> 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, poll_resource Example See the example for the request_resource function. Document (Version 2.22) 10/26/2012 456 Function Specifications report_error Set Task Error Code Syntax #include <ctools.h> 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 2.22) 10/26/2012 457 Function Specifications request_resource Obtain Control of a Resource Syntax #include <ctools.h> void request_resource(UINT32 resource); Description The request_resource function obtains control of the resource specified by resource. If 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, poll_resource Example This code fragment obtains the dynamic memory resource, allocates some memory, and releases the resource. #include <ctools.h> 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 2.22) 10/26/2012 458 Function Specifications resetAllABSlaves Erase All DF1 Slave Responses Syntax #include <ctools.h> 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 DF1 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. See the example in the Example Programs chapter under the section Master Message Example Using DF1 Protocol. The resetAllABSlaves 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 <ctools.h> resetAllABSlaves(com2); Document (Version 2.22) 10/26/2012 459 Function Specifications resetClockAlarm Acknowledge and Reset Real Time Clock Alarm Syntax #include <ctools.h> 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 2.22) 10/26/2012 460 Function Specifications route Redirect Standard I/O Streams Syntax #include <ctools.h> void route(FILE *logical, FILE *hardware); Description The route function redirects the I/O streams associated with stdout, stdin, and stderr. These streams are routed to the com1 serial port. logical specifies the stream to redirect. hardware specifies the hardware device which will output the data. It may be one of com1, com2, com3 or com4. 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. Example This program segment will redirect all input, output and errors to the com2 serial port. #include <ctools.h> route(stderr, com2); route(stdout, com2); route(stdin, com2); Document (Version 2.22) 10/26/2012 /* send errors to com2 */ /* send output to com2 */ /* get input from com2 */ 461 Function Specifications rresvport Syntax #include <ctools.h> int rresvport(int * portToReservePtr); Function 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 portToReservePtr 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 starting 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 TM_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 >= 0 Valid socket descriptor -1 An error occurred. If an error occurred, the socket error can be retrieved by calling tfGetSocketError and using TM_SOCKET_ERROR as the socket descriptor parameter. rresvport will fail if: TM_EAGAIN The TCP/IP stack could not find any port number available between IPPORT_RESERVEDSTART and the port number to reserve. TM_EINVAL Bad parameter; pointer is null or port number to reserve is less than IPPORT_RESERVEDSTART (600). Document (Version 2.22) 10/26/2012 462 Function Specifications runBackgroundIO Run Background I/O Task Syntax #include <ctools.h> void runBackgroundIO( BOOLEAN state ); Description The runBackgroundIO 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 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 2.22) 10/26/2012 463 Function Specifications runIOSystem Run I/O System Syntax #include <ctools.h> BOOLEAN runIOSystem( BOOLEAN state ); Description The runIOSystem 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. If the requested stopping or starting of the I/O System task(s) was successful TRUE is returned, otherwise FALSE is returned. This function should only be needed in the context of the startup function appstart. Document (Version 2.22) 10/26/2012 464 Function Specifications runLed Control Run LED State Syntax #include <ctools.h> 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 LED_OFF turn on run LED 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 ladder logic is installed in the controller, this function should not be used by a C program. Example #include <ctools.h> void main(void) { runLed(LED_ON); /* program is running */ /* ... the rest of the code */ } Document (Version 2.22) 10/26/2012 465 Function Specifications runMasterIpStartTask Run TCP/IP Master Message Support Task Syntax #include <ctools.h> void runMasterIpStartTask( BOOLEAN state ); Description The runMasterIpStartTask 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. Document (Version 2.22) 10/26/2012 466 Function Specifications runTarget Start the Run-Time Engine Syntax #include <ctools.h> 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-3 firmware this is the IEC 61131-3 IEC 1131 run-time engine. Calling the function with the argument state set to FALSE stops the run-time engine 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 2.22) 10/26/2012 467 Function Specifications runTimers Start timerTask Syntax #include <ctools.h> void runTimers(BOOLEAN state); Description The runTimers function is used to start or stop the Timer support task. This function needs to be called with the argument TRUE prior to using the functions settimer, timer, interval, or read_timer_info. Calling the function with state set to TRUE enables timer support. Calling the function with state set to FALSE disables timer support. Document (Version 2.22) 10/26/2012 468 Function Specifications select Syntax #include <ctools.h> int select ( int numberSockets, fd_set * readSocketsPtr, fd_set * writeSocketsPtr, fd_set * exceptionSocketsPtr, struct timeval * timeOutPtr ); Function 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(&fdset); Initializes a socket descriptor set ( fdset) to the null set. FD_SET(fd, &fdset); Includes a particular socket descriptor fd in fdset. FD_CLR(fd, &fdset); Removes fd from fdset. FD_ISSET(fd, &fdset); Is non-zero if fd is a member of fdset, 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. exceptionSocketsPtr The pointer to a mask of sockets to check for an exception condition: Out of Band data. Document (Version 2.22) 10/26/2012 469 Function Specifications timeOutPtr The pointer to a structure containing the length of time to wait for an event before exiting. Returns >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 tfGetSocketError and using TM_SOCKET_ERROR as the socket descriptor parameter. select will fail if: TM_EBADF One of the socket descriptors is bad. TM_ EINVAL A component of the pointed-to time limit is outside the acceptable range: tv_sec needs to be between 0 and 10^8, inclusive. tv_usec needs to be greater than or equal to 0, and less than 10^6. Document (Version 2.22) 10/26/2012 470 Function Specifications send Syntax #include <ctools.h> int send ( int socketDescriptor, char * bufferPtr, int bufferLength, int flags ); Function 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 TM_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 TM_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 TM_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, 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. Outof-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-ofband 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 2.22) 10/26/2012 471 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-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 must also support “outof-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 >=0 Number of bytes actually sent on the socket -1 An error occurred. send will fail if: TM_EBADF The socket descriptor is invalid. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_EHOSTUNREACH Non-TCP socket only. No route to destination host. TM_ EMSGSIZE Document (Version 2.22) 10/26/2012 The socket requires that message to be sent atomically, and the message was too long. 472 Function Specifications TM_EWOULDBLOCK The socket is marked as non-blocking and the send operation would block. TM_ENOTCONN Socket is not connected. TM_ESHUTDOWN User has issued a write shutdown or a tfClose call (TCP socket only). Document (Version 2.22) 10/26/2012 473 Function Specifications send_message Send a Message to a Task Syntax #include <ctools.h> 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 poll_message, allocate_envelope Example This program creates a task to display a message and sends a message to it. #include <ctools.h> void showIt(void) { envelope *msg; while (TRUE) { msg = receive_message(); printf("Message data %ld\r\n", msg->data); deallocate_envelope(msg); } } void main(void) { envelope *msg; unsigned tid; /* message pointer */ /* task ID */ tid = create_task(showIt, 2, APPLICATION, 1); msg = allocate_envelope(); msg->destination = tid; msg->type = MSG_DATA; msg->data = 1002; Document (Version 2.22) 10/26/2012 474 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 2.22) 10/26/2012 475 Function Specifications sendto Syntax #include <trsocket.h> int sendto ( int socketDescriptor, char * bufferPtr, int bufferLength, int flags, const struct sockaddr * toPtr, int toLength ); Function 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 TM_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 flag has been set in the flags parameter, –1 is returned with the socket error being set to TM_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 2.22) 10/26/2012 476 Function Specifications Returns Value Meaning >=0 Number of bytes actually sent on the socket -1 An error occurred sendto will fail if: TM_EBADF The socket descriptor is invalid. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_EHOSTUNREACH No route to destination host. TM_ EMSGSIZE The socket requires that message be sent atomically, and the message was too long. TM_EPROTOTYPE TCP TM_EWOULDBLOCK Document (Version 2.22) 10/26/2012 protocol requires usage of send not sendto. The socket is marked as non-blocking and the send operation would block. 477 Function Specifications serialModbusMaster Send Modbus Command Syntax #include <ctools.h> 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. • 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. • 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->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>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 message 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-3 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 com3 are for local operator display terminals, and for programming and diagnostics using the IEC 61131-3 program. The IO_SYSTEM resource needs to be requested before calling this function. Document (Version 2.22) 10/26/2012 478 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. Document (Version 2.22) 10/26/2012 479 Function Specifications setABConfiguration Set DF1 Protocol Configuration Syntax #include <ctools.h> 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 description 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 DF1 commands received on com2. #include <ctools.h> struct ABConfiguration ABConfig; getABConfiguration(com2, &ABConfig); ABConfig.max_protected_address = 7000; setABConfiguration(com2, &ABConfig); Document (Version 2.22) 10/26/2012 480 Function Specifications setBreakCondition Set a break condition on a serial port. Syntax #include <ctools.h> void setBreakCondition( FILE *stream ); 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 Also clearBreakCondition Document (Version 2.22) 10/26/2012 481 Function Specifications setclock Set Real Time Clock Syntax #include <ctools.h> 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 need 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 <ctools.h> void daylight(void) { TIME now; request_resource(IO_SYSTEM); getclock(&now); now.hour = now.hour + 1 % 24; setclock(&now); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 482 Function Specifications setClockAlarm Set the Real Time Clock Alarm Syntax #include <ctools.h> 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 in 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 reenable 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 getclock Document (Version 2.22) 10/26/2012 483 Function Specifications setdbase Write Value to I/O Database Syntax #include <ctools.h> 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 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR 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 the 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 <ctools.h> void 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 2.22) 10/26/2012 484 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 2.22) 10/26/2012 485 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-3 Dictionary. The function can have any name; setdbaseHandler is used in the description below. Syntax #include <ctools.h> BOOLEAN setdbaseHandler( UINT16 address, INT16 value ) Description This function is called by the setdbase function when one of the following conditions apply: There is no IEC 61131-3 application downloaded, or There is no IEC 61131-3 variable assigned to the specified Modbus address. The function has two parameters: The address parameter is the Modbus address to be written. 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 needs to be requested before calling setdbase, which calls this handler. Requesting the IO_SYSTEM resource ensures 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 2.22) 10/26/2012 486 Function Specifications setDTR Control RS232 Port DTR Signal Syntax #include <ctools.h> void setDTR(FILE *stream, UINT16 state); Description The setDTR function sets the status of the DTR signal line for the communication port specified by stream. 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 deasserted states. This function is only useful on RS232 ports. The function has no effect if the serial port is not an RS232 port. Document (Version 2.22) 10/26/2012 487 Function Specifications setForceFlag Set Force Flag State for a Register (Telepace firmware only) Syntax #include <ctools.h> 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; 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 0 to NUMLINEAR-1 1 bit 1 bit 16 bit 16 bit 16 bit LINEAR 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 in a permanent storage area, which is maintained during power outages. The IO_SYSTEM resource needs to be requested before calling this function. See Also getForceFlag, clearAllForcing, overrideDbase 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 <ctools.h> void main(void) Document (Version 2.22) 10/26/2012 488 Function Specifications { request_resource(IO_SYSTEM); setForceFlag(MODBUS, 40001, 0); setForceFlag(LINEAR, 302, 255); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 489 Function Specifications setIOErrorIndication Set I/O Module Error Indication Syntax #include <ctools.h> void setIOErrorIndication(BOOLEAN state); Description The setIOErrorIndication 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 or the SCADAPack 32 System Manual for further information on the Status LED and Status Output. See Also getIOErrorIndication Document (Version 2.22) 10/26/2012 490 Function Specifications setOutputsInStopMode Set Outputs In Stop Mode (Telepace firmware only) Syntax #include <ctools.h> void setOutputsInStopMode( BOOLEAN holdDoutsOnStop, BOOLEAN holdAoutsOnStop ); 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 turned 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 <ctools.h> void main(void) { unsigned holdDoutsOnStop; unsigned holdAoutsOnStop; getOutputsInStopMode( &holdDoutsOnStop, holdAoutsOnStop = TRUE; setOutputsInStopMode( holdDoutsOnStop, } Document (Version 2.22) 10/26/2012 &holdAoutsOnStop); holdAoutsOnStop); 491 Function Specifications set_port Set Serial Port Configuration Syntax #include <ctools.h> void set_port(FILE *stream, struct pconfig *settings); Description The set_port function sets serial port communication parameters. stream must specify one of com1, com2, com3 or com4. settings references a serial port configuration structure. Refer to the description of the pconfig structure for an explanation of the fields. 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. 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-3 program. 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 <ctools.h> struct pconfig settings; get_port(com2, &settings); settings.baud = BAUD19200; request_resource(IO_SYSTEM); set_port(com2, &settings); release_resource(IO_SYSTEM); This code fragment sets com2 to the same settings as com1. #include <ctools.h> struct pconfig settings; Document (Version 2.22) 10/26/2012 492 Function Specifications request_resource(IO_SYSTEM); set_port(com2, get_port(com1, &settings)); release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 493 Function Specifications setProgramStatus Set Program Status Flag Syntax #include <ctools.h> void setProgramStatus( 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. Notes There are two 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. See Also getProgramStatus Example See the example for getProgramStatus. Document (Version 2.22) 10/26/2012 494 Function Specifications set_protocol Set Communication Protocol Configuration Syntax #include <ctools.h> INT16 set_protocol(FILE *stream, struct prot_settings *settings); Description The set_protocol function sets protocol parameters. stream needs to specify one of com1, com2, com3 or com4. 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. Be sure to add a call to modemNotification when writing a custom protocol. See Also get_protocol, modemNotification Example This code fragment changes the station number of the com2 protocol to 4. #include <ctools.h> struct prot_settings settings; get_protocol(com2, &settings); settings.station = 4; request_resource(IO_SYSTEM); set_protocol(com2, &settings); release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 495 Function Specifications setProtocolSettings Set Protocol Extended Addressing Configuration Syntax #include <ctools.h> BOOLEAN setProtocolSettings( FILE * stream, PROTOCOL_SETTINGS * settings ); Description The setProtocolSettings function sets protocol parameters for a serial port. This function supports extended addressing. The function has two arguments: stream is one of com1, com2, com3 or com4; 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 IO_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. See Also getProtocolSettings, get_protocol, set_protocol, modemNotification Example This code fragment sets protocol parameters for the com2 serial port. #include <ctools.h> PROTOCOL_SETTINGS settings; settings.type Document (Version 2.22) 10/26/2012 = MODBUS_RTU; 496 Function Specifications settings.station settings.priority settings.SFMessaging settings.mode = = = = 1234; 3; FALSE; AM_extended; request_resource(IO_SYSTEM); setProtocolSettings(com2, &settings); release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 497 Function Specifications setProtocolSettingsEx Sets extended protocol settings for a serial port. Syntax #include <ctools.h> BOOLEAN setProtocolSettingsEx( FILE * stream, PROTOCOL_SETTINGS_EX * pSettings ); 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: • stream specifies the serial port. It is one of com1, com2, com3 or com4. • 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 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. See Also getProtocolSettingsEx, getProtocolSettings, start_protocol, get_protocol, get_protocol_status, set_protocol, modemNotification Example This code fragment sets protocol parameters for the com2 serial port. Document (Version 2.22) 10/26/2012 498 Function Specifications #include <ctools.h> PROTOCOL_SETTINGS_EX settings; settings.type = settings.station = settings.priority = settings.SFMessaging = settings.mode = settings.enronEnabled = settings.enronStation = MODBUS_RTU; 1; 3; FALSE; AM_standard; TRUE; 4; request_resource(IO_SYSTEM); setProtocolSettingsEx(com2, &settings); release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 499 Function Specifications setSFTranslation Write Store and Forward Translation Syntax #include <ctools.h> 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. Otherwise a default timeout of 10 seconds is set for all forwarded commands. The setSFTranslation 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 always 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. Result code Meaning SF_VALID SF_NO_TRANSLATION All translations are valid The entry defines re-transmission of the same message on the same port One or both of the serial port indexes is not valid One or both of the stations is not valid SF_PORT_OUT_OF_RANG E SF_STATION_OUT_OF_R ANGE SF_ALREADY_DEFINED SF_INDEX_OUT_OF_RAN GE SF_INVALID_FORWARDIN G_IP The translation already exists in the table The entry referenced by index does not exist in the table The forwarding IP address is invalid. 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 2.22) 10/26/2012 500 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 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 are not needed in the Store and Forward Table 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 & 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. Slave Interface Forwarding Interface Serial Modbus Interface: e.g. com1, com2, com3, or com4 Modbus IP Interface: e.g. Ethernet1 Serial Modbus Interface: e.g. com1, com2, com3, or com4 Serial Modbus Interface: e.g. com1, com2, com3, or com4 Serial Modbus Interface: e.g. com1, com2, com3, or com4 Modbus IP Network: e.g. Modbus/TCP, Modbus RTU over UDP, or Modbus ASCII over UDP Modbus IP Network: e.g. Modbus/TCP, Modbus RTU over UDP, or Modbus ASCII over UDP Modbus IP Interface: e.g. Ethernet1 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 determines the exact interface (e.g. Ethernet1) to use when it searches the network for the forwardIPAddress. Also, when forwarding on a TCP or UDP network, the forwarding destination IP address needs to be entered as the forwardIPAddress. The forwardIPAddress is entered as an IP address string of the format 255.255.255.255. The Document (Version 2.22) 10/26/2012 501 Function Specifications forwardIPAddress is needed to know where to connect so that the command can be forwarded to its final destination. Modbus IP Network as Slave Interface 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 slaveInterface and sends a command to be forwarded. The protocol type is not specified for slaveInterface. All messages in any Modbus IP protocol received on slaveInterface for slaveStation will be forwarded. Serial Modbus Interface as Forwarding Interface The forwardIPAddress field in the SF_TRANSLATION structure should be set to zero when the forwardInterface field is a Serial Modbus interface. Set forwardIPAddress to zero as follows: SF_TRANSLATION sfTranslation; sfTranslation.forwardIPAddress.s_addr = 0; See Also getSFTranslation, checkSFTranslationTable, checkSFTranslationTable Document (Version 2.22) 10/26/2012 502 Function Specifications setSFTranslationEx Write Store and Forward Translation method 2 Syntax #include <ctools.h> 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 always stored even if invalid. 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. Result code Meaning SF_VALID SF_NO_TRANSLATION All translations are valid The entry defines re-transmission of the same message on the same port One or both of the interfaces is not valid SF_PORT_OUT_OF_RANG E SF_STATION_OUT_OF_R ANGE SF_ALREADY_DEFINED SF_INDEX_OUT_OF_RAN GE SF_INVALID_FORWARDIN G_IP One or both of the stations is not valid The translation already exists in the table The entry referenced by index does not exist in the table The forwarding IP address is invalid. Notes The TeleBUS Protocols User Manual describes 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. The Modbus protocol type and communication parameters may differ between serial ports. The store and forward messaging will translate the protocol messages. Document (Version 2.22) 10/26/2012 503 Function Specifications 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 are not in the Store and Forward Table 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 & 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. Slave Interface Forwarding Interface Serial Modbus Interface: e.g. com1, com2, com3, or com4 Modbus IP Interface: e.g. Ethernet1 Serial Modbus Interface: e.g. com1, com2, com3, or com4 Serial Modbus Interface: e.g. com1, com2, com3, or com4 Serial Modbus Interface: e.g. com1, com2, com3, or com4 Modbus IP Network: e.g. Modbus/TCP, Modbus RTU over UDP, or Modbus ASCII over UDP Modbus IP Network: e.g. Modbus/TCP, Modbus RTU over UDP, or Modbus ASCII over UDP Modbus IP Interface: e.g. Ethernet1 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 forwardIPAddress. Also, when forwarding on a TCP or UDP network, the forwarding destination IP address must be entered as the forwardIPAddress. The forwardIPAddress is entered as an IP address string of the format 255.255.255.255. The forwardIPAddress is needed to know where to connect so that the command can be forwarded to its final destination. Document (Version 2.22) 10/26/2012 504 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 slaveInterface and sends a command to be forwarded. The protocol type is not specified for slaveInterface. All messages in any Modbus IP protocol received on slaveInterface for slaveStation will be forwarded. Serial Modbus Interface as Forwarding Interface The forwardIPAddress field in the SF_TRANSLATION_EX structure should be set to zero when the forwardInterface field is a Serial Modbus interface. Set forwardIPAddress to zero as follows: SF_TRANSLATION_EX sfTranslation; sfTranslation.forwardIPAddress.s_addr = 0; See Also getSFTranslationEx, checkSFTranslation, clearSFTranslation Document (Version 2.22) 10/26/2012 505 Function Specifications setsockopt Syntax #include <ctools.h> int setsockopt ( int socketDescriptor, int protocolLevel, int optionName, const char * optionValue, int optionLength ); Function 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 needs to be specified. To manipulate options at the “socket” level, protocolLevel is specified as SOL_SOCKET. To manipulate options at any other level, protocolLevel 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. The parameters optionValuePtr and optionlength are used to access option values for setsockopt. optionName and any specified options are passed uninterpreted to the appropriate protocol module for interpretation. The include file <ctools.h> contains definitions for the options described below. Most socket-level options take an int pointer for optionValuePtr. For setsockopt, the integer value pointed to by the optionValuePtr 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 <ctools.h>. struct linger contains the following members: l_onoff on = 1/off = 0 l_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. Document (Version 2.22) 10/26/2012 506 Function Specifications SO_REUSEADDR Enable/disable local address reuse. Default 0 (disable). 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. TM_SO_RCVCOPY TCP socket: fraction use of a receive buffer below which we try and append to a previous receive buffer in the socket receive queue. UDP socket: fraction use of a receive buffer below which we try and copy to a new receive buffer, if there is already at least a buffer in the receive queue. This is to avoid keeping large pre-allocated receive buffers, which the user has not received yet, in the socket receive queue. Default value is 4 (25%) TM_SO_SNDAPPEND TCP socket only. Threshold in bytes of ‘send’ buffer below, which we try and append, to previous ‘send’ buffer in the TCP send queue. Only used with send, not with tfZeroCopySend. This is to try and regroup lots of partially empty small buffers in the TCP send queue waiting to be ACKED by the peer; otherwise we could run out of memory, since the remote TCP will delay sending ACKs. Note that care should be taken not to use tfZeroCopySend when sending small buffers, since we do not try and regroup small buffers with tfZeroCopySend. Default value is 4000 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 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). Document (Version 2.22) 10/26/2012 507 Function Specifications The following options are recognized at the IP level: IP_PROTOIP protocolLevel options IPO_TOS IP type of service. Default 0. IPO_TTL IP Time To Live in seconds. Default 64. IPO_SRCADDR Our IP source address. Default is first multi-home IP address on the outgoing interface. IPO_MULTICAST_TTL Change the default IP TTL for outgoing multicast datagrams IPO_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 IPO_ADD_MEMBERSHIP Add group multicast IP address to given interface (see struct ip_mreq data type below) IPO_DROP_MEMBERSHIP Delete group multicast IP address from given interface (see struct ip_mreq data type below). ip_mreq structure definition struct ip_mreq { struct in_addr imr_multiaddr; struct in_addr imr_interface }; ip_mreq structure Members imr_multiaddr IP host group address that the user wants to join/leave imr_interface IP address of the local interface that the host group address is to be joined on, or is to leave from If imr_interface is zero, then the default local interface selected with fSetDefaultMcastInterface will be used instead. The following options are recognized at the TCP level. Options marked with an asterix can only be changed prior to establishing a TCP connection. IP_PROTOTCP protocolLevel options TCP_KEEPALIVE Document (Version 2.22) 10/26/2012 Sets the idle time in seconds for a TCP connection, before it starts sending keep alive probes. It cannot be set below the default value. Note that keep alive probes will be sent only if the SO_KEEPALIVE socket option is enabled. Default 7,200 seconds. 508 Function Specifications TCP_MAXRT Sets the amount of time in seconds before the connection is broken, once TCP starts retransmitting, or probing a zero window, when the peer does not respond. A TCP_MAXRT value of 0 means to use the system default, and -1 means to retransmit forever. If a positive value is specified, it may be rounded-up to the connection next retransmission time. Note that unless the TCP_MAXRT value is –1 (wait forever), the connection can also be broken if the number of maximum retransmissions TM_TCP_MAX_REXMIT has been reached. See TM_TCP_MAX_REXMIT below. Default 0 (Which means use system default of TM_TCP_MAX_REXMIT times network computed round trip time for an established connection; for a non established connection, since there is no computed round trip time yet, the connection can be broken when either 75 seconds , or when TM_TCP_MAX_REXMIT times default network round trip time have elapsed, whichever occurs first). TCP_MAXSEG Sets the maximum TCP segment size sent on the network. Note that 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. Note: 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. Note also that the TCP_MAXSEG value cannot be set below 64 bytes. Default value is IP MTU minus 40 bytes. TCP_NODELAY 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. TCP_NOPUSH Set this option value to a non-zero value, to force TCP to delay sending any TCP data until a full sized segment is buffered in the TCP buffers. Useful for applications that send continuous big chunks of data like FTP, and know that more data is coming. (Normally the TCP code sends Document (Version 2.22) 10/26/2012 509 Function Specifications a non full-sized segment, only if it empties the TCP buffer). Default 0 TCP_STDURG Set this option value to a zero value, if the peer is a Berkeley system since Berkeley systems set the urgent data pointer to point to last byte of urgent data+1. Default 1 (urgent pointer points to last byte of urgent data as specified in RFC1122). *TM_TCP_SEL_ACK Set this option value to a non-zero value, to enable sending the TCP selective Acknowledgment option. Default 0 *TM_TCP_WND_SCALE Set this option value to a non-zero value, to enable sending the TCP window scale option. Default 0 *TM_TCP_TS Set this option value to a non-zero value, to enable sending the Time stamp option. Default 0 TM_TCP_SLOW_START Set this option value to zero, to disable the TCP slow start algorithm. Default 1 TM_TCP_DELAY_ACK Sets the TCP delay ack time in milliseconds. Default 200 milliseconds. TM_TCP_MAX_REXMIT Sets the maximum number of retransmissions without any response from the remote, before TCP gives up and aborts the connection. See also TCP_MAXRT above. Default 12 TM_TCP_KEEPALIVE_CNT Sets the maximum numbers of keep alive probes without any response from the remote, before TCP gives up and aborts the connection. See also TCP_KEEPALIVE above. Default 8 TM_TCP_FINWT2TIME Sets the maximum amount of time TCP will wait for the remote side to close, after it initiated a close. Default 600 seconds TM_TCP_2MSLTIME Sets the maximum amount of time TCP will wait in the TIME WAIT state, once it has initiated a close of the connection. Default 60 seconds TM_TCP_RTO_DEF Sets the TCP default retransmission timeout value in milliseconds, used when no network round trip time has been computed yet. Default 3,000 milliseconds TM_TCP_RTO_MIN Sets the minimum retransmission timeout in milliseconds. The network computed retransmission timeout is bound by TM_TCP_RTO_MIN and TM_TCP_RTO_MAX. Default 100 milliseconds. TM_TCP_RTO_MAX Sets the maximum retransmission timeout in milliseconds. The network computed retransmission timeout is bound by TM_TCP_RTO_MIN and TM_RTO_MAX. Default 64,000 milliseconds Document (Version 2.22) 10/26/2012 510 Function Specifications TM_TCP_PROBE_MIN Sets the minimum window probe timeout interval in milliseconds. The network computed window probe timeout is bound by TM_TCP_PROBE _MIN and TM_TCP_PROBE _MAX. Default 500 milliseconds TM_TCP_PROBE_MAX Sets the maximum window probe timeout interval in milliseconds. The network computed window probe timeout is bound by TM_TCP_PROBE _MIN and TM_TCP_PROBE _MAX. Default 60,000 milliseconds TM_TCP_KEEPALIVE_INTV Sets the interval between Keep Alive probes in seconds. See TM_TCP_KEEPALIVE_CNT. This value cannot be changed after a connection is established, and cannot be bigger than 120 seconds. Default 75 seconds. Parameters socketDescriptor The socket descriptor to set the options on. protocolLevel The protocol to set the option on. See below. optionName The name of the option to set. See below and above. optionValuePtr The pointer to a user variable from which the option value is set. User variable is of data type described below. optionLength The size of the user variable. It is the size of the option data type described below. ProtocolLevel SOL_SOCKET Socket level protocol. IP_PROTOIP IP level protocol. IP_PROTOTCP TCP level protocol. ProtocolLevel Option Name SOL_SOCKET SO_DONTROUTE SO_KEEPALIVE SO_LINGER SO_OOBINLINE SO_RCVBUF SO_RCVLOWAT SO_REUSEADDR SO_SNDBUF SO_SNDLOWAT TM_SO_RCVCOPY Document (Version 2.22) 10/26/2012 Option data type int int struct linger int unsigned long unsigned long int unsigned long unsigned long unsigned int Option value 0 or 1 0 or 1 0 or 1 0 or 1 511 Function Specifications ProtocolLevel IP_PROTOIP IP_PROTOTCP Option Name TM_SO_SNDAPPEND IPO_TOS IPO_TTL IPO_SRCADDR IPO_MULTICAST_TTL IPO_MULTICAST_IF IPO_ADD_MEMBERSHIP IPO_DROP_MEMBERSHIP TCP_KEEPALIVE TCP_MAXRT TCP_MAXSEG TCP_NODELAY TCP_NOPUSH TCP_STDURG TM_TCP_2MSLTIME TM_TCP_DELAY_ACK TM_TCP_FINWT2TIME TM_TCP_KEEPALIVE_CN T TM_TCP_KEEPALIVE_INT V TM_TCP_MAX_REXMIT TM_TCP_PROBE_MAX TM_TCP_PROBE_MIN TM_TCP_RTO_DEF TM_TCP_RTO_MAX TM_TCP_RTO_MIN TM_TCP_SEL_ACK TM_TCP_SLOW_START TM_TCP_TS TM_TCP_WND_SCALE Option data type unsigned int unsigned char unsigned char ttUserIpAddre ss unsigned char struct in_addr struct ip_mreq struct ip_mreq int int int int int int int int int int Option value 0 or 1 0 or 1 0 or 1 int int unsigned long unsigned long unsigned long unsigned long unsigned long int int int int 0 or 1 0 or 1 0 or 1 0 or 1 Returns 0 Successful set of option -1 An error occurred setsockopt will fail if: TM_EBADF The socket descriptor is invalid TM_EINVAL One of the parameters is invalid Document (Version 2.22) 10/26/2012 512 Function Specifications TM_ ENOPROTOOPT The option is unknown at the level indicated. TM_EPERM Option cannot be set after the connection has been established. TM_ENETDOWN Specified interface not configured yet TM_EADDRINUSE Multicast host group already added to the interface TM_ENOBUF Not enough memory to add new multicast entry. TM_ENOENT Attempted to delete a non-existent multicast entry on the specified interface. Document (Version 2.22) 10/26/2012 513 Function Specifications setStatusBit Set Bits in Controller Status Code Syntax #include <ctools.h> 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, 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. See Also clearStatusBit, getStatusBit Document (Version 2.22) 10/26/2012 514 Function Specifications setStatusMode Set Source for Status LED Syntax #include <ctools.h> void setStatusLed(UINT16 mode); 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 2.22) 10/26/2012 515 Function Specifications settimer Set a Timer Syntax #include <ctools.h> void settimer(UINT16 index, UINT16 value); Description The settimer function loads value into timer specified by index. The timer counts down at the timer interval frequency. The settimer function can reset a timer before it has finished counting down. Notes To enable support for timers, the function runTimers needs to be called once before using any of the timer functions (settimer, timer, interval, or read_timer_info). Document (Version 2.22) 10/26/2012 516 Function Specifications shutdown Syntax #include <ctools.h> int shutdown ( int socketDescriptor, int howToShutdown ); Function Description Shutdown a socket in read, write, or both directions determined by the parameter howToShutdown. Parameters socketDescriptor The socket to shutdown howToShutdown 0 = Read 1 = Write 2 = Both Direction: Returns 0 Success -1 An error occurred shutdown will fail if: TM_EBADF The socket descriptor is invalid TM_EINVAL One of the parameters is invalid TM_ ENOPROTOOPT The option is unknown at the level indicated. Document (Version 2.22) 10/26/2012 517 Function Specifications signal_event Signal Occurrence of Event Syntax #include <ctools.h> 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 255 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 31. Any events defined in ctools.h are not valid events for use in an application program. See Also timer, wait_event Example This program creates a task to wait for an event, then signals the event. #include <ctools.h> void task1(void) { while(TRUE) { wait_event(20); printf("Event 20 occurred\r\n"); } } void main(void) { create_task(task1, 3, APPLICATION, 4); while(TRUE) { /* body of main task loop */ /* The body of this main task is intended solely for signaling the event waited for by task1. Normally main would be busy with more important things to do otherwise the code in Document (Version 2.22) 10/26/2012 518 Function Specifications task1 could be executed within main’s wait loop */ settimer(0, 10); /* 1 second interval */ while (timer(0)) /* wait for 1 s */ { /* Allow other tasks to execute */ release_processor(); } signal_event(20); } } Document (Version 2.22) 10/26/2012 519 Function Specifications socket Syntax #include <ctools.h> int socket ( int family, int type, int protocol ); Function Description socket creates an endpoint for communication and returns a descriptor. The family parameter specifies 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 <ctools.h>. If 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 connectionbased 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 TM_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 particular 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 Document (Version 2.22) 10/26/2012 520 Function Specifications socket should be performed. The communications protocols used to implement a 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 TM_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 datagrams 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 <ctools.h>. 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 protocol Type Protocol Actual 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 tfGetSocketError and using TM_SOCKET_ERROR as the socket descriptor parameter. socket will fail if: TM_ EMFILE No more sockets are available TM_ENOBUFS There was insufficient user memory available to complete the operation TM_ EPROTONOSUPPORT supported within this family. Document (Version 2.22) 10/26/2012 The protocol type or the specified protocol is not 521 Function Specifications start_protocol Start Serial Protocol Syntax #include <ctools.h> 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 protocol 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 2.22) 10/26/2012 522 Function Specifications startup_task Identify Start Up Task Syntax #include <ctools.h> void *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 2.22) 10/26/2012 523 Function Specifications startTimedEvent Enable Signaling of a Regular Event Syntax #include <ctools.h> 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 31. Any events defined in ctools.h are not valid events for use 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 example below shows a simple method using the installExitHandler function. See Also endTimedEvent Document (Version 2.22) 10/26/2012 524 Function Specifications tfBindNoCheck Syntax #include <ctools.h> int tfBindNoCheck ( int socketDescriptor, const struct sockaddr * addressPtr, int addressLength ); Function Description tfBindNoCheck 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. tfBindNoCheck requests that the address pointed to by addressPtr be assigned to the socket. Clients do not normally require 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 needs to be less than 32768 (TM_SOC_NO_INDEX), or could be 0xFFFF (TM_WILD_PORT). Binding to the TM_WILD_PORT port number allows a server to listen for incoming connection requests on all the ports. Multiple sockets cannot bind to the same port with different IP addresses (as might be allowed in UNIX). This function is similar to bind, except that bind checks that the address that the user wants to bind to is a valid configured address on an interface; tfBindNoCheck does not check for that, and allows the user to bind to any IP address. 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 tfBindNoCheck can fail for any of the following reasons: TM_EADDRINUSE The specified address is already in use. TM_EBADF socketDescriptor is not a valid descriptor. TM_EINVAL One of the passed parameters is invalid, or socket is already bound. TM_EINPROGRESS tfBindNoCheck is already running. Document (Version 2.22) 10/26/2012 525 Function Specifications tfBlockingState Syntax #include <ctools.h> int tfBlockingState ( int socketDescriptor, int blockingState ); Function Description This function is used to set blocking or non-blocking on a socket as the default mode of operation. This can be overridden with the MSG_DONTWAIT flags on subsequent calls. The tfIoctl call with the FIONBIO request can be used instead of the tfBlockingState call. Parameters socketDescriptor The socket descriptor to set the non-blocking flag on. blockingState One of the following: TM_BLOCKING_OFF TM_BLOCKING_ON Returns 0 Success -1 Error tfBlockingState can fail for the following reason: TM_ EBADF The socket descriptor is invalid. TM_EINVAL blockingState parameter is invalid. Document (Version 2.22) 10/26/2012 526 Function Specifications tfClose Syntax #include <ctools.h> int tfClose ( int socketDescriptor ); Function Description This function is used to close a socket. It is not called close to avoid confusion with an embedded kernel file system call. Parameters socketDescriptor The socket descriptor to close Returns 0 Operation completed successfully -1 An error occurred tfClose can fail for the following reasons: TM_EBADF The socket descriptor is invalid. TM_ESHUTDOWN A write shutdown has already been performed on the socket (TCP socket only). TM_EALREAY A previous tfClose 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 Document (Version 2.22) 10/26/2012 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). 527 Function Specifications tfDialerAddExpectSend Syntax #include <ctools.h> int tfDialerAddExpectSend ( ttUserInterface interfaceHandle, char TM_FAR * sendString, char TM_FAR * expectString, char TM_FAR * errorString, int numRetries, int timeout, unsigned char flags ); Function Description This function adds an expect-send pair to the dialer (client waits for the server to send a string, and then sends a string in response). When the dialer reaches this phase, it waits for the remote host to send a string. If this string matches expectString, sendString is sent back in response and the dialer moves to the next state. If the received string matches errorString, this phase is aborted, and if M_DIALER_FAIL_ON_ERROR is set in flags, the entire dialing session is terminated with an error. The dialer will wait for expectString or errorString for a time equal to timeout in seconds. If the number of retries specified by numRetries has not been exhausted when this time elapses, the dialer will begin waiting again. When the retry limit has been reached, the dialer will abort the session and return with an error. Parameters interfaceHandle Interface handle used in previous call totfUseDialer; this specifies the device to dial upon. sendString String to send when the ‘expectString’ is received from the peer expectString String to send to peer immediately. errorString String that, if received from the peer, indicates an error. numRetries Number of times to retry sending ‘sendString’ before failing. timeout Amount of times (in seconds) between timeouts flags Only one flag is currently defined: TM_DIALER_FAIL_ON_ERROR. This flag causes the dialer to immediately return if the error string is received. Document (Version 2.22) 10/26/2012 528 Function Specifications Normally, the dialer would simply attempt to resend the previous string. Returns TM_ENOERROR Expect/send string added successfully. TM_EINVAL Bad interface handle. TM_EINVAL Timeout value is zero TM_EINVAL Bad send/expect strings TM_ENOMEM Insufficient memory to add expect/send strings. Document (Version 2.22) 10/26/2012 529 Function Specifications tfDialerAddSendExpect Syntax #include <ctools.h> int tfDialerSendExpect ( ttUserInterface interfaceHandle, char TM_FAR * sendString, char TM_FAR * expectString, char TM_FAR * errorString, int numRetries, int timeout, unsigned char flags ); Function Description This function adds a send-expect pair to the dialer (local peer sends a string and waits for the remote peer to respond). When the dialer reaches this phase, it will send sendString to the remote peer and waits for its response. If this response matches expectString, the dialer successfully moves to the next state. However, if the received string matches errorString the dialer will abort this phase, and if TM_DIALER_FAIL_ON_ERROR is set in flags the entire dialing session will be aborted with an error. After sending sendString, the dialer will wait for a time equal to timeout in seconds. If the number of retries specified by numRetries has not been exhausted when this time elapses, the dialer will resend sendString and repeat this process. When the retry limit has been reached, the dialer will abort the session and return with an error. Parameters InterfaceHandle Interface handle used in previous call to tfUseDialer; this specifies the device to dial upon. sendString String to send when the ‘expectString’ is received from the peer. errorString String that, if received from the peer, indicates an error. numRetries Number of times to retry sending ‘sendString’ before failing. timeout flags Document (Version 2.22) 10/26/2012 Amount of times (in seconds) between timeouts Only one flag is currently defined: TM_DIALER_FAIL_ON_ERROR. This flag causes the dialer to immediately return if the error string is received. Normally, the dialer would simply attempt to resend the previous string. 530 Function Specifications Returns TM_ENOERROR Expect/send string added successfully. TM_EINVAL Bad interface handle. TM_EINVAL Timeout value is zero. TM_EINVAL Bad send/expect strings. TM_ENOMEM Insufficient memory to add expect/send strings. Document (Version 2.22) 10/26/2012 531 Function Specifications tfFreeZeroCopyBuffer Syntax #include <ctools.h> int tfFreeZeroCopyBuffer ( ttUserMessage bufferHandle ); Function Description This function is used to free a zero copy buffer that was allocated via tfGetZeroCopyBuffer, tfZeroCopyRecv, or tfZeroCopyRecvFrom. Parameters bufferHandle The buffer handle of the buffer to free. Returns 0 Success -1 Error. The buffer did not belong to the user. Document (Version 2.22) 10/26/2012 532 Function Specifications tfGetPppDnsIpAddress Syntax #include <ctools.h> int tfGetPppDnsIpAddress ( ttUserInterface interfaceHandle, ttUserIpAddress tM_FAR *dnsIpAddressPtr, int flag ); Function Description This function is used to return the DNS Addresses as negotiated by the remote PPP server. This function can only be used with PPP devices. If no DNS address is negotiated, the IP address returned will be 0.0.0.0. Parameters interface handle The interface handle to get the DNS IPaddress from. DnsIpAddressPtr The pointer to the buffer where the DNS IP address will be stored Flag One of the following: TM_DNS_PRIMARY or TM_DNS_SECONDARY Returns 0 Success TM_EINVAL One of the parameters is null or the device is a LAN device TM_ENETDOWN Interface is not configured Document (Version 2.22) 10/26/2012 533 Function Specifications tfGetPppPeerlpAddress Syntax #include <ctools.h> int tfGetPppPeerIpAddress ( ttUserInterface interfaceHandle, ttIpAddress * ifIpAddress ); Function Description This function is used to get the PPP address that the remote PPP has used (respectively SLIP address of the remote SLIP). This function should be called after tfOpenInterface has completed successfully. If a default gateway (resp. a static route) needs to be added for that interface, then the retrieved IP address should be used to add a default gateway (resp. should be used as the gateway to add a static route) through the corresponding interface. Parameters interfaceHandle The interface Handle to get the Peer IP address from. ifIpAddressPtr The pointer to the buffer where the Peer PPP IP address will be stored into. Returns 0 Success TM_EINVAL device. One of the parameters is null, or the device is a LAN TM_ENETDOWN Interface is not configured. Document (Version 2.22) 10/26/2012 534 Function Specifications tfGetOobDataOffset Syntax #include <ctools.h> int tfGetOobDataOffset(int socketDescriptor); Function Description This function is used to get the offset of the out of band data sitting in the receive queue. This allows the user to determine where the out of band data is located in the stream. The tfIoctl call with the SOIOCATMARK request can be used instead of the tfGetOobDataOffset call, but the tIfoctl call only tells us whether we are at the out-of-band byte mark, whereas the tfGetOobDataOffset call gives us the offset to the out-of-band byte. See recv call for out-of-band data description. Parameters socketDescriptor The socket descriptor to get the number of bytes in the data stream to the out-of-band data offset. Returns Number of out of band offset, –1 if call failed tfGetOobDataOffset can fail for the following reasons: TM_ EBADF The socket descriptor is invalid. TM_EINVAL No Out of Band Data is waiting to be read. Document (Version 2.22) 10/26/2012 535 Function Specifications tfGetSendCompltBytes Syntax #include <ctools.h> int tfGetSendCompltBytes(int socketDescriptor); Function Description This function is used to get the number of sent bytes that have been acked by the peer on a TCP socket since the last call to tfGetSendCompltBytes. Note that if this function is called too soon after sending the bytes, this may not be sufficient time for the sent bytes to be acked by the peer. Parameters socketDescriptor The socket number to check on the amount of bytes acked by the peer. Returns >=0 Number of bytes that have been sent to, and acked by the TCP peer. -1 An error has occurred tfGetSendCompltBytes can fail for the following reasons: TM_ EBADF The socket descriptor is invalid. TM_EOPNOTSUPP The socket is not a TCP socket. Document (Version 2.22) 10/26/2012 536 Function Specifications tfGetSocketError Syntax #include <ctools.h> int tfGetSocketError(int socketDescriptor); Function Description This function is used when any socket call fails (TM_SOCKET_ERROR), to get the error value back. This call has been added to allow for the lack of a perprocess errno value that is lacking in most embedded real-time kernels. Parameters socketDescriptor The socket descriptor to get the error on. Returns The last errno value for a socket Document (Version 2.22) 10/26/2012 537 Function Specifications tfGetWaitingBytes Syntax #include <ctools.h> int tfGetWaitingBytes(int socketDescriptor); Function Description This function is used to get the number of bytes waiting to be read on a socket. The tfIoctl call with the FIONREAD request can be used instead. Parameters socketDescriptor The socket number to check on the amount of waiting bytes Returns >=0 Number of bytes waiting to be read -1 An error has occurred. tfGetWaitingBytes can fail for the following reason: TM_ EBADF Document (Version 2.22) 10/26/2012 The socket descriptor is invalid.. 538 Function Specifications tfGetZeroCopyBuffer Syntax #include <ctools.h> ttUserMessage tfGetZeroCopyBuffer(int size, char ** dataPtrPtr); Function Description This function is used to get a Zero Copy Buffer. This buffer can then be used with tfZeroCopySend and tfZeroCopySendTo for zero copy send functions. This is a TRUE zero copy if the device driver supports DMA sending. Parameters size The size of the buffer to be used for the zero copy. dataPtrPtr Pointer to a pointer that is the beginning of the user’s data area. This is where the user can store the data to be sent. Returns The Zero Copy buffer or (ttUserMessage *) 0 if not successful tfGetZeroCopyBuffer will fail for the following reason: There was insufficient user memory available to complete the operation. Document (Version 2.22) 10/26/2012 539 Function Specifications tfInetToAscii Syntax #include <ctools.h> ttUserMessage tfInetToAscii(unsigned long ipAddress,char * outputBuffer); Function Description This function is used to convert an IP address to the dotted string notation. Parameters ipAddress The IP address to convert outputBuffer A character buffer to store the result into. It is the caller’s responsibility to ensure that there is ample room in the buffer for the null terminated string. The output will never be longer than 16 bytes. Returns Nothing. Document (Version 2.22) 10/26/2012 540 Function Specifications tfIoctl Syntax #include <ctools.h> int tfIoctl ( int socketDescriptor, unsigned long request, int * argumentPtr ); Function Description This function is used to set/clear nonblocking I/O, to get the number of bytes to read, or to check whether the specified socket’s read pointer is currently at the out of band mark. It is not called ioctl to avoid confusion with an embedded kernel file system call. Request Description FIONBIO Set/clear nonbllocking I/O: if the int cell pointed to by argumentPtr contains a non-zero value, then the specified socket non-blocking flag is turned on. If it contains a zero value, then the specified socket nonblocking flag is turned off. See also tfBlockingState. FIONREAD Stores in the int cell pointed to by argumentPtr the number of bytes available to read from the socket descriptor. See also tfGetWaitingBytes. SIOCATMARK Stores in the int cell pointed to by argumentPtr a nonzero value if the specified socket’s read pointer is currently at the out-of-band mark, zero otherwise. See revc call for a description of out-of-band data. See also tfGetOobDataOffset. Example Given a valid socketDescriptor, the following code will turn on the socket’s nonblocking I/O flag. int argValue; argValue = 1; tfIoctl(socketDescriptor, FIONBIO, &argValue); Parameters socketDescriptor T he socket descriptor we want to perform the ioctl request on. request FIONBIO, FIONREAD, or SIOCATMARK Document (Version 2.22) 10/26/2012 541 Function Specifications argumentPtr A pointer to an int cell in which to store the request parameter or request result. Returns 0 Success. -1 An error has occured. tfioctl can fail for the following reasons: TM_EBADF The socket descriptor is invalid. TM_EINVAL Request is not one of FIONBIO, FIONREAD, or SOIOCATMARK. Document (Version 2.22) 10/26/2012 542 Function Specifications tfPingClose Syntax #include <ctools.h> int tfPingClose(int socketDescriptor); Function Description This function stops the sending of any PING echo requests and closes the ICMP socket that had been opened via tfPingOpenStart. Parameters socketDescriptor An ICMP PING socket descriptor as returned by tfPingOpenStart Returns Value Meaning 0 Success -1 An error occurred If tfPingClose fails, the associated error code can be retrieved using tfGetSocketError (socketDescriptor): TM_EBADF Document (Version 2.22) 10/26/2012 socketDescriptor is not a valid descriptor. 543 Function Specifications tfPingGetStatistics Syntax #include <ctools.h> int tfPingGetStatistics ( int socketDescriptor, ttPingInfoPtr pingInfoPtr ); Function Description This function gets Ping statistics in the ttPingInfo structure that pingInfoPtr points to. socketDescriptor should match the socket descriptor returned by a call to tfPingOpenStart. pingInfoPtr needs to point to a ttPingInfo structure allocated by the user. Parameters socketDescriptor tfPingOpenStart. The socket descriptor as returned by a previous call to pingInfoPtr The pointer to an empty structure where the results of the PING connection will be copied upon success of the call. (See below for details.) ttPingInfo Data structure: Field pgiTransmitted data type unsigned long pgiReceived unsigned long pgiDuplicated unsigned long pgiLastRtt unsigned long pgiMaxRtt unsigned long pgiMinRtt unsigned long pgiAvrRtt unsigned long pgiSumRtt unsigned long Document (Version 2.22) 10/26/2012 Description Number of transmitted PING echo request packets so far Number of received PING echo reply packets so far (not including duplicates) Number of duplicated received PING echo reply packets so far. Round trip time in milliseconds of the last PING request/reply. Maximum round trip time in milliseconds of the PING request/ reply packets. Minimum round trip time in milliseconds of the PING request/reply packets. Average round trip time in milliseconds of the PING request/reply packets. Sum of all round trip times in milliseconds of the PING request/reply packets. 544 Function Specifications Field pgiSendErrorCode pgiRecvErrorCode data type int int Description PING send request error code if any. PING recv error code if any (including ICMP error from the network). Returns 0 Success -1 An error occurred If tfPingGetStatistics fails, the associated error code can be retrieved using tfGetSocketError (socketDescriptor): TM_EBADF socketDescriptor is not a valid descriptor. TM_EINVAL pingInfoPtr is a NULL pointer TM_EINVAL socketDescriptor was not opened with tfPingOpenStart Document (Version 2.22) 10/26/2012 545 Function Specifications tfPingOpenStart Syntax #include <ctools.h> int tfPingOpenStart ( char * remoteHostNamePtr, int pingInterval, int pingDataLength, ttPingCBFuncPtr pingUserCBFuncPtr ); Function Description This function opens an ICMP socket and starts sending PING echo requests to a remote host as specified by the remoteHostName parameter. PING echo requests are sent every pingInterval seconds. The PING length (not including IP and ICMP headers) is given by the pingDataLength parameter. If the pingUserCBFuncPtr parameter is non-null, the function it points to is called for each received PING echo reply or ICMP error message, with the socket descriptor returned by tfPingOpenStart passed as a parameter. To get the PING connection results and statistics, the user needs to call tfPingGetStatistics. To stop the system from sending PING echo requests and to close the ICMP socket, the user needs to call tfPingClose. Parameters remoteHostNamePtr Pointer to character array containing a dotted decimal IP address. pingInterval Interval in seconds between PING echo requests. If set to zero, defaults to 1 second. pingDataLength User Data length of the PING echo request. If set to zero, defaults to 56 bytes. If set to a value between 1, and 3, defaults to 4 bytes..Appendix A Miscellaneous API A3 pingUserCBFuncPtr Pointer to a user function to be called upon receiving a network PING echo reply, or an ICMP error message, with the socket descriptor as returned by tfPingOpenStart passed as a parameter. Can be set to null function pointer if the user does not wish to be notified of incoming network traffic. Returns New ICMP Socket Descriptor or TM_SOCKET_ERROR (-1) on error If tfPingOpenStart fails, the errorCode can be retrieved with tfGetSocketError (TM_SOCKET_ERROR): TM_EINVAL remoteHostNamePtr was a null pointer TM_EINVAL pingInterval was negative Document (Version 2.22) 10/26/2012 546 Function Specifications TM_EINVAL pingDataLength was negative of bigger than 65535, maximum value allowed by the IP protocol. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_EMSGSIZE pingDataLength exceeds socket send queue limit, or pingDataLength exceeds the IP MTU, and fragmentation is not allowed. TM_EHOSTUNREACH No route to remote host. Example with a non null function pointer #include <ctools.h> void tfPingUserCB (int socketDescriptor); .. socketDescriptor = tfPingOpenStart (“192.168.0.2”, 0, 0, tfPingUserCB); Example with a null function pointer #include <ctools.h> .. socketDescriptor = tfPingOpenStart (“127.0.0.1”, 0, 0, ttPingCBFuncPtr)0); Document (Version 2.22) 10/26/2012 547 Function Specifications tfPppSetOption Syntax #include <ctools.h> int tfPppSetOption ( ttUserInterface interfaceHandle, int protocolLevel, int remoteLocalFlag, int optionName, const char * optionValuePtr, int optionLength ); Function Description This function is used to set the PPP options that we wish to negotiate as well as those options that we will allow. This allows us to change the link away from the default parameters described in RFC1661. Parameters interfaceHandle The Interface handle to set these options for protocolLevel The protocol which this option should be applied. Current supported protocols are: TM_PPP_LCP_PROTOCOL TM_PPP_IPCP_PROTOCOL TM_PPP_PAP_PROTOCOL TM_PPP_CHAP_PROTOCOL remoteLocalFlag This flag describes whether the option is for what we want to use for our side if the link (TM_PPP_OPT_WANT) or if it what we will allow the remote side to use (TM_PPP_OPT_ALLOW) optionName The name of the option (see below) optionValuePtr The value of the option (see below) optionLength The length of the option (see below) LCP (TM_PPP_LCP_PROTOCOL): Option Nam Len Meaning TM_LCP_ADDRCONTROL_COMP 1 A boolean value specifiying whether address field compression should be used. Default: OFF Document (Version 2.22) 10/26/2012 548 Function Specifications TM_LCP_PROTOCOL_COMP 1 A boolean value specifying whether protocol field compression should be used. Default: OFF TM_LCP_MAGIC_NUMBER specify a magic number. 1 A boolean value indicating whether to Default: OFF TM_LCP_MAX_FAILURES 1 Sets the maximum number of LCP configuration failures. This determines the maximum number of configuration NAKs that will be sent before we reject an option. Default: 5 TM_LCP_MAX_RECV_UNIT 2 Specifies the largest MRU that we will allow and the default MRU that we want to use. Default: 1500 TM_LCP_ACCM 4 Specifies the async control character map that we want to use, and if we want to allow the remote side to be able to set his ACCM. Default: 0xffffffff TM_LCP_AUTH_PROTOCOL 2 The protocol to use when authenticating to our peer, and vice versa (e.g. PAP or CHAP). Possible value are TM_PPP_PAP_PROTOCOL and TM_PPP_CHAP_PROTOCOL. Default: No Authentication TM_LCP_TERM_RETRY 1 Sets the maximum number of Terminate equests that the local peer will send (without receiving a Terminate Ack) before terminating the connection. Default: 3 TM_LCP_CONFIG_RETRY 1 Sets the maximum number of LCP config requests that will be sent without receiving a LCP ack/nak/reject. remoteLocalFlag has no effect. Default: 10 TM_LCP_TIMEOUT 1 Sets the LCP retransmission timeout in seconds. Default: 3 second IPCP (TM_PPP_IPCP_PROTOCOL): Option Nam Len Meaning TM_IPCP_COMP_PROTOCOL 2 Specifies the type of compression to use over the link. Currently, only VJ TCP/IP header compression is available which is defined as TM_PPP_COMP_TCP_PROTOCOL Document (Version 2.22) 10/26/2012 549 Function Specifications Default: No Compression TM_IPCP_MAX_FAILURES 1 Sets the maximum number of IPCP configuration failures. This determines the maximum number of configuration NAKs that will be sent before we reject an option. Default: 5 TM_IPCP_VJ_SLOTS 1 The number of slots used to store state information for each side of a VJ compressed link. This value is determined by the maximum number of concurrent TCP sessions that you will have. Default: 1 slot. TM_IPCP_IP_ADDRESS 4 Specifies if we want to allow the remote to set their IP address. Please see “setting a peer PPP IP address” below for explanations. Default: Don’t Allow TM_IPCP_DNS_PRI 4 Specifies the IP addresses of the Primary DNS Server we will allow the remote to use or the Primary DNS server that we ant to us. Se the section setting a PPP IP Address Default: Don’t Allow TM_IPCP_DNS_SEC 4 Specifies the IP Address of the Secondary DNS server we will allow the remote to use or the Secondary DNS server that we want touse. Se the section setting a PPP IP Address. Default: Don’t Allow PPP (PPP_PROTOCOL): Option Nam Len Meaning TM_PPP_SEND_BUFFER_SIZE 2 Length of data buffered by the PPP link layer (but not beyond the end of a packet) before the device driver send function is called. Default: 1 byte TM_IPCP_RETRY 1 Sets the maximum number of IPCP config requests that will be sent without receiving a IPCP nak/ack/reject. remoteLocalFlag has no effect. Default: 10 TM_IPCP_TIMEOUT 1 Sets the IPCP retransmission timeout value (in seconds). remoteLocalFlag has no effect. Default: 1 Second TM_PPP_PROTOCOL: Document (Version 2.22) 10/26/2012 550 Function Specifications Option Nam Len Meaning TM_PPP_SEND_BUFFER_SIZE 2 Length of data buffered by the PPP link layer (but not beyond the end of a packet) before the device driver send function is called. Default: 1 byte Document (Version 2.22) 10/26/2012 551 Function Specifications tfRead Syntax #include <ctools.h> int tfRead ( int socketDescriptor, char * bufferPtr, int bufferLength ); Function Description tfRead is used to receive messages from another socket. It is not called read to avoid confusion with an embedded kernel file system call. It operates identically to recv, except that it does not have any flag parameter, and hence does not support out-of-band data, or overwriting the blocking state of the socket for the duration of the call. 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 Returns >0 Number of bytes actually received from the socket 0 EOF 1 -1 An error occurred. tfread will fail if: TM_EBADF The socket descriptor is invalid. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_ EMSGSIZE The socket requires that message be received atomically, and bufferLength was too small. TM_EWOULDBLOCK The socket is marked as non-blocking and no data is available to be read. TM_ESHUTDOWN The remote socket has closed the connection, and there is no more data to be read (TCP socket only). TM_ENOTCONN Socket is not connected. TM_EINVAL One of the parameter is invalid.. Document (Version 2.22) 10/26/2012 552 Function Specifications tfRegisterSocketCB Syntax #include <ctools.h> int tfRegisterSocketCB ( int socketDescriptor, ttUserSocketCBFuncPtr socketCBFuncPtr, int eventFlags ); Function Description This function is used to register a function call upon completion of one of more socket events. This allows the user to issue non-blocking calls, and get a call back upon completion of one or more socket events as described in the table below. The call back function will be called repeatedly each time one or more of the events registered for occur until the user cancel the event(s) with another call to tfRegisterSocketCB with a new event flag value. For example, if the user register for a recv event (TM_CB_RECV), then the call back function will be called, in the context of the receive task, every time a packet is received from the network and queued in the socket receive queue. Most of the call back calls will be made in the context of the receive task. TM_CB_SOCKET_ERROR, TM_CB_RESET, TM_CB_CLOSE_COMPLETE events call backs could be made in the context of an application task or the receive task. In all the other events, call backs will be made in the context of the receive task. Therefore processing should be kept at a minimum in the call back function. In a multi-tasking environment, the user call back function should set a flag or increase a counter and signal the user application task. Function prototype for the user supplied socket call back function: void SocketCBFunc ( int socketDescriptor, int eventFlags ); Example To register for incoming data, incoming out-of-band data and remote close event notifications on socket descriptor sd: retCode = tfRegisterSocketCB (sd,socketCBFunc, TM_CB_RECV|TM_CB_RECV_OO B|TM_CB_REMOTE_CLOSE); Parameters socketDescriptor Document (Version 2.22) 10/26/2012 The socket descriptor to register the call back for. 553 Function Specifications sockettCBFuncPtr The function pointers of the user function to call when one or more of the registered events occur. See below for function prototype. eventFlags One or more of the flags described below and OR’ed together. EventFlags TM_CB_CONNECT_COMPLT Register for a connection complete call back (TCP socket only). TM_CB_ACCEPT Register for a call back when a remote host has established a connection to our listening server (TCP socket only). TM_CB_RECV Register for a call back when incoming data has arrived from our peer. TM_CB_RECV_OOB Register for a call back when out-of-band data has arrived from our peer (TCP socket only). TM_CB_SEND_COMPLT Register for a call back when the data that we are sending has been acked by the peer host (TCP socket only). TM_CB_REMOTE_CLOSE Register for a call back when our peer has shutdown the connection (TCP socket only). TM_CB_SOCKET_ERROR Register for a call back when an error occured on the connection. TM_CB_RESET Register for a call back when the peer has sent a reset on the connection (TCP socket only). TM_CB_CLOSE_COMPLT Register for a call back when the user issued close has completed (TCP socket only). TM_CB_WRITE_READY Indicates that there is more room on the send queue. The user can now send more data on the connection given by the socketDescriptor. When one or more of these events occur, the Treck stack calls the user supplied call back function socketCBFunc(socketDescriptor, eventFlags), where socketDescriptor is the socket descriptor as given by the user in tfRegisterSocketCB, and eventFlags contain one or more of the events specified by the user, that have occured. Described below are the action(s) to be taken by the user in the user supplied call back function upon receiving any one of the socket events: EventFlags TM_CB_CONNECT_COMPLT Non-blocking connect issued earlier by the user has now completed, and the connection is established with the peer on the socketDescriptor. The user is now Document (Version 2.22) 10/26/2012 554 Function Specifications able to send and recv data on the connection given by the socketDescriptor. TM_CB_ACCEPT A remote host has established a connection to the listening server socketDescriptor. The user can now issue an accept call to retrieve the socket descriptor of the newly established connection. TM_CB_RECV Incoming data has arrived on the connection given by socketDescriptor. The user can now issue any of the allowed recv calls for the protocol associated with the socket to retrieve the incoming data. TM_CB_RECV_OOB Incoming out-of-band data has arrived on the connection given by socketDescriptor. The user can use the appropriate method to retrieve the out of band data as described in the recv section above. TM_CB_SEND_COMPLT Some sent data has been received, and acked by the peer. The user can issue tfGetSendCompltBytes to retrieve the actual amount of bytes that have been received and acked since the last call to tfGetSendCompltBytes. TM_CB_REMOTE_CLOSE Our peer has shutdown the connection (sent a FIN). No more new data will be coming. The user needs to empty its receive queue using any of the recv calls and then close the connection (using tfClose). TM_CB_WRITE_READY Indicates that there is more room on the send queue. The user can now send more data on the connection given by the socketDescriptor. TM_CB_SOCKET_ERROR An error has occured on the connection. The user can issue a send or recv call to retrieve the error as described in the send and recv sections. Note that recv will return all outstanding incoming data before returning the error. The user should then issue tfClose to close the connection. TM_CB_RESET The peer has sent a RESET. The user needs to issue tfClose to close the socket. TM_CB_CLOSE_COMPLT The user issued tfClose has now completed. Returns 0 Success -1 An error has occurred tfRegisterSocketCB will fail if: TM_EBADF The socket descriptor is invalid. TM_EINVAL socketCBFuncPtr is NULL and eventFlags is non-zero. Document (Version 2.22) 10/26/2012 555 Function Specifications tfRegisterSocketCBParam Syntax #include <ctools.h> int tfRegisterSocketCBParam ( int socketDescriptor, ttUserSocketCBParamFuncPtr socketCBParamFuncPtr, void * socketUserPtr, int eventFlags ); Function Description This function is similar to tfRegisterSocketCB, and like tfRegisterSocketCB, it is used to register a function call upon completion of one of more socket events. It also allows the user to specify a user parameter that will be passed as a parameter to the call back function. Function prototype for the user supplied socket call back function: void socketCBParamFunc ( int socketDescriptor, void * socketUserPtr, int eventFlags ); Parameters socketDescriptor The socket descriptor to register the call back for sockettCBFuncPtr The function pointers of the user function to be called when one or more of the registered events occur. See below for function prototype. socketUserPtr A user pointer, that will be passes by the call back function. eventFlags One or more of the flags as described in the tfRegisterSocketCB section and OR’ed together. When one or more of these events occur, the Treck stack calls the user supplied call back function socketCBParamFunc (socketDescriptor, socketUserPtr, eventFlags), where socketDescriptor is the socket descriptor as given by the user in fRegisterSocketCBParam, socketUserPtr is the user pointer as given by the user in tfRegisterSocketCBParam, and eventFlags contain one or more of the events specified by the user, that have occurred. The action(s) to be taken by the user in the user supplied call back function upon receiving any one of the socket events are described in the tfRegisterSocketCB section. Returns 0 Success Document (Version 2.22) 10/26/2012 556 Function Specifications -1 An error has occurred. tfRegisterSocketParamCB will fail if TM_EBADF The socket descriptor is invalid. TM_EINVAL socketCBFuncPtr is NULL and eventFlags is non-zero. Document (Version 2.22) 10/26/2012 557 Function Specifications tfResetConnection Syntax #include <ctools.h> int tfResetConnection ( int socketDescriptor ); Function Description This function is used to abort a connection on a socket. It only works with TCP (STREAM) sockets and sends a RST and discards all outstanding data. Parameters socketDescriptor The socket descriptor to Reset Returns 0 Operation completed successfully -1 An error occurred tfResetConnection can fail for the following reasons: TM_EINVAL One of the parameters is invalid TM_EBADF The socket descriptor is invalid TM_EPROTONOSUPP The socket is not a STREAM socket. Document (Version 2.22) 10/26/2012 558 Function Specifications tfSendToInterface Syntax #include <ctools.h> int tfSendToInterface ( int socketDescriptor, char * bufferPtr, int bufferLength, int flags, const struct sockaddr * toPtr, int toLength, ttUserInterface interfaceHandle, unsigned char mhomeIndex ); Function Description tfSendToInterface is used to transmit a message to another transport end-point. tfSendToInterface 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 toPtr 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 TM_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, tfSendToInterface blocks. If it is in non-blocking mode or the MSG_DONTWAIT flag has been set in the flags parameter, –1 is returned with the socket error being set to TM_EWOULDBLOCK. The select call may be used to determine when it is possible to send more data. If tfSendToInterface is used on an Ethernet interface with the interface configured temporarily with a zero IP address (TM_DEV_IP_USER_BOOT flag), then the only allowed destination IP addresses are either limited broadcast (i.e. all F’s), or multicast addresses. 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 InterfaceHandle Interface to send the data through mhomeIndex Multihome index on the configured interface. Document (Version 2.22) 10/26/2012 559 Function Specifications 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. Returns >=0 Number of bytes actually sent on the socket -1 An error occurred tfSendToInterface will fail if: TM_EBADF The socket descriptor is invalid. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_EHOSTUNREACH No route to destination host. TM_ EMSGSIZE The socket requires that message be sent atomically, and the message was too long. TM_EPROTOTYPE TCP protocol requires usage of send not tfSendToInterface. TM_EWOULDBLOCK Document (Version 2.22) 10/26/2012 The socket is marked as non-blocking and the send operation would block. 560 Function Specifications tfSetPppPeerIpAddress Syntax #include <ctools.h> int tfSetPppPeerIpAddress ( ttUserInterface interfaceHandle, ttIpAddress ifIpAddress ); Function Description This function is used to set a default remote PPP/SLIP IPaddress. This IP address will be used as the default remote point to point IP address, in case no remote IP address is negotiated with PPP (see tfPppSetOption), or for SLIP. If no IP address is set with this function, (and no IP address is negotiated with the remote PPP for PPP), then the local IP address + 1 will be used as the default IP address for the remote PPP (or SLIP) for outing purposes (see tfGetPppPeerIpAddress). tfSetPppPeerIpAddress can only be called between tfAddInterface (or tfCloseInterface) and tfOpenInterface. Parameters interfaceHandle The interface handle to update the Peer IP address in. ifIpAddress The IP address to use for routing purposes for the remote PPP system Returns 0 Success TM_EINVAL The interface handle is null, or the device is a LAN device. TM_EISCONN PPP connection is already established Document (Version 2.22) 10/26/2012 561 Function Specifications tfSocketArrayWalk Syntax #include <ctools.h> int tfSocketArrayWalk ( ttWalkCBFuncPtr callBackFuncPtr, ttUserVoidPtr argPtr ); Function Description This function is used to walk the list of open sockets, calling the user supplied call back function, passing the socket descriptor, and user argument argPtr, to it until we reach the end of the list, or the user call back function returns an error whichever comes first. Return error value from the call back function to the user. Parameters callBackFuncPtr The function pointer to the user function to call for each open socket. See below for function prototype. argPtr User pointer to be passed back to the call back function. Function prototype for the user supplied call back function: int callBackFunc ( int socketDescriptor, ttUserVoidPtr argPtr ); Returns 0 Success Other As returned by the user call back function. Document (Version 2.22) 10/26/2012 562 Function Specifications tfUseDialer Syntax #include <ctools.h> int tfUseDialer ( ttUserInterface interfaceHandle, ttUserLnkNotifyFuncPtr notifyFuncPtr ); Function Description Enables and initializes the dialer. This does not start the dialer, but simply initializes it – the dialing will occur when tfOpenInterface is called. This should only be enabled on a serial interface running PPP/SLIP, and should be called before any calls to tfDialerAddSendExpect or tfDialerAddExpectSend are made. The notification function is used to monitor the status of the dialer. The prototype of the notification function is myDialerNotify( ttUserInterface interfaceHandle, int flags ); The notification function will only be called when the dialer has finished (either successfully or unsucessfully). There are two possible values for the flags parameter: TM_DIALER_OPEN_COMPLETE The dialer has completed the dialing session successfully. TM_DIALER_OPEN_FAILED The dialer encountered an error and aborted the session. Parameters InterfaceHandle Interface to enable the dialer on notifyFuncPtr User’s function to be called to notify of status of dialer Returns TM_ENOERROR Dialer successfully initialized TM_EINVAL Bad interface handle TM_EALREADY Dialer already initialized TM_ENOMEM Insufficient memory to initialize dialer Document (Version 2.22) 10/26/2012 563 Function Specifications tfWrite Syntax #include <ctools.h> int tfWrite ( int socketDescriptor, char * bufferPtr, int bufferLength ); Function Description tfWrite is used to transmit a message to another transport end-point. It is not called write to avoid confusion with an embedded kernel file system call. It operates identically to send, except that it does not have any flags parameter, and hence does not support sending out-of-band data, or overwriting the blocking state of the socket for the duration of the call. Parameters socketDescriptor The socket descriptor to use to send data. bufferPtr The buffer to send. bufferLength The length of the buffer to send. Returns >=0 Number of bytes actually sent on the socket. -1 An error occurred. tfWrite will fail if: TM_EBADF The socket descriptor is invalid. TM_ENOBUFS There was insufficient user memory available to comp lete the operation. TM_EHOSTUNREACH Non-TCP socket only. No route to destination host. TM_ EMSGSIZE The socket requires that message to be sent atomically, and the message was too long. TM_EWOULDBLOCK The socket is marked as non-blocking and the write operation would block. Document (Version 2.22) 10/26/2012 564 Function Specifications tfZeroCopyRecv Syntax #include <ctools.h> int tfZeroCopyRecv ( int socketDescriptor, ttUserMessage * bufferHandlePtr, char ** dataPtrPtr, int maxBufferLength, int flags ); Function Description This function is used to recv a zero copy message. It operates identically to recv with the exception that it takes a zero copy buffer handle as a parameter and puts the beginning of the data into a passed pointer. However, it does not support the MSG_OOB flag, since there is only one byte of out-of-band data, and it would be inefficient to use the tfZeroCopyRecv in that case. To recv out-ofband data, the recv call should be used instead. The user needs to call tfFreeZeroCopyBuffer in order to free the buffer after the user has finished with it. Parameters socketDescriptor The socket descriptor to send data to. bufferHandlePtr The zero copy buffer that contains the message dataPtrPtr A pointer to a char pointer where the start of the data is stored. maxBufferLength The length of the message flags See below. The flags parameter 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. Returns 0 EOF >0 Number of bytes received -1 An error has occurred. tfZeroCopyRecv will fail if: TM_EBADF Document (Version 2.22) 10/26/2012 The socket descriptor is invalid. 565 Function Specifications TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_ EMSGSIZE The socket requires that message be received atomically, and bufferLength was too small. TM_EWOULDBLOCK The socket is marked as non-blocking or the MSG_DONTWAIT flag is used and no data is available to be read. TM_ESHUTDOWN The remote socket has closed the connection, and there is no more data to be received. (TCP socket only). TM_EINVAL One of the parameter is invalid. TM_ENOTCONN Socket is not connected. Document (Version 2.22) 10/26/2012 566 Function Specifications tfZeroCopySend Syntax #include <ctools.h> int tfZeroCopySend ( int socketDescriptor, ttUserMessage bufferHandle, int bufferLength, int flags ); Function Description This function is used to send a zero copy message. It operates identically to send with the exception that it takes a zero copy buffer handle as a parameter, and with the exception that it sends either the whole buffer or nothing. Once tfZeroCopySend is called, the caller does NOT own the buffer and it is freed by the TCP/IP stack, except when if fails with a TM_EWOULDBLOCK error code, in which case the user can either try and send the buffer at a later time, or free the zero copy buffer using tfFreeZeroCopyBuffer. Parameters socketDescriptor The socket descriptor to send data to bufferHandle The zero copy buffer obtained from tfGetZeroCopyBuffer bufferLength The length of the message 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-ofband data. MSG_DONTROUTE The SO_DONTROUTE option is turned on for the duration of the operation. Only diagnostic or routing programs use it. Returns >=0 Number of bytes sent -1 An error has occurred Document (Version 2.22) 10/26/2012 567 Function Specifications tfZeroCopySend will fail if: TM_EBADF The socket descriptor is invalid TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_EHOSTUNREACH Non-TCP socket only. No route to destination host. TM_ EMSGSIZE For a TCP socket in non-blocking mode, or for a UDP socket, the buffer length exceeds the socket send queue size. TM_EWOULDBLOCK The socket is marked as non-blocking and the buffer length exceeds the available space left in the send queue. TM_ENOTCONN Socket is not connected. TM_ESHUTDOWN User has issued a write shutdown or a tfClose call. (TCP socket only) TM_EFAULT bufferHandle does not correspond to a zero copy buffer. Document (Version 2.22) 10/26/2012 568 Function Specifications timer Read a Timer Syntax #include <ctools.h> UINT16 timer(UINT16 index) Description The timer function returns the time remaining in timer specified by index. The index needs to be in the range 0 to 31 (this number can be changed by changing TIMER_MAX macro). A zero value means that the timer has finished counting down. If the timer number is invalid, the function returns 0 and the task's error code is set to TIMER_BADTIMER. Notes To enable support for timers, the function runTimers needs to be called once before using any of the timer functions (settimer, timer, interval, or read_timer_info). Document (Version 2.22) 10/26/2012 569 Function Specifications timeoutCancel Cancel Timeout Notification Function Syntax #include <ctools.h> UINT32 timeoutCancel(UINT32 timeoutID); Description This function cancels a timeout notification that was requested with the timeoutRequest function. No notification will be sent. The envelope provided when the request was made is de-allocated. The function has one parameter: the ID of the timeout request. This is the value returned by the timeoutRequest function. The function returns TRUE if the request was cancelled and FALSE if the timeout ID is not currently active. Notes The function will return FALSE if the timeout notification has already been made. In this case the envelope will not be de-allocated as it has already been given to the destination task. That task is responsible for de-allocating the envelope. This function cannot be called from a task exit handler. See installExitHandler function for details of exit handlers. See Also timeoutRequest Example See the example for the timeoutRequest function. Document (Version 2.22) 10/26/2012 570 Function Specifications timeoutRequest Request Timeout Notification Function Syntax #include <ctools.h> UINT32 timeoutRequest(UINT32 delay, envelope * pEnvelope); Description This function requests a timeout notification. A message is sent to the task specified in the envelope after the specified delay. A task receives the message using the receive_message or poll_message function. The envelope received by the receiving task has the following characteristics. The source field is set to the task ID of the task that called timeoutRequest. The message type field is set to MSG_TIMEOUT. The message data is set to the timeout ID. The function has two parameters: the length of time in tenths of a second before the timeout occurs, and a pointer to an envelope. The resolution of the delay is – 0.1/+0 seconds. The notification message is sent delay-1 to delay tenths of a second after the function call. The function returns the ID of the timeout request. This can be used to identify and cancel the timeout. The timeout ID changes with each call to the function. Although the ID will eventually repeat, it is sufficiently unique to allow the timeout notification to be identified. This can be useful in identifying notifications received by a task and matching them with requests. Notes Do not de-allocate the envelope passed to timeoutRequest in the calling function. After a call to timeoutRequest either use timeoutCancel to free the envelope if the timeout has not occurred yet, or call deallocate_envelope in the destination task after the envelope has been delivered. The timeout may be cancelled using the timeoutCancel function. The task that receives the notification message needs to de-allocate the envelope after receiving it. No checking is done on the task ID. The caller needs to check it is valid. If the delay is zero, the message is sent immediately, provided an envelope is available. This function cannot be called from a task exit handler. See installExitHandler function for details of exit handlers. See Also timeoutCancel Document (Version 2.22) 10/26/2012 571 Function Specifications Example This example shows a task that acts on messages received from other tasks and when a timeout occurs. The task waits for a message for up to 10 seconds. If it does not receive one, it proceeds with other processing anyway. The task shows how to deal with notifications from older timeout requests. These occur when the notification was send before the timeout was cancelled. The task ignores timeout notifications that don’t match the last timeout request. #include <ctools.h> void aTask(void) { envelope * pEnvelope; TASKINFO thisTask; unsigned timeoutID; unsigned done; /* get the task ID for this task */ thisTask = getTaskInfo(0); while (TRUE) { /* allocate an envelope and address it to this task */ pEnvelope = allocate_envelope(); pEnvelope->destination = thisTask.taskID; /* request a timeout in 10 seconds */ timeoutID = timeoutRequest(100, pEnvelope); done = FALSE; while (!done) { /* wait for a message or a timeout */ pEnvelope = receive_message(); /* determine the message type */ if (pEnvelope->type == MSG_TIMEOUT) { /* does it match the last request? */ if (pEnvelope->data == timeoutID) { /* accept the timeout */ done = TRUE; } } else { /* cancel the timeout */ timeoutCancel(timeoutID); done = TRUE; /* process message from other task here */ } Document (Version 2.22) 10/26/2012 572 Function Specifications /* return the envelope to the RTOS */ deallocate_envelope(pEnvelope); } /* proceed with rest of task’s actions here */ } } Document (Version 2.22) 10/26/2012 573 Function Specifications wait_event Wait for an Event Syntax #include <ctools.h> 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 Operating System section for more information on events. Valid events are numbered 0 to 31. Any events defined in ctools.h are not valid events for use in an application program. See Also startTimedEvent Example See the example for the signal_event function. Document (Version 2.22) 10/26/2012 574 Function Specifications wd_auto Automatic Watchdog Timer Mode Syntax #include <ctools.h> 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 2.22) 10/26/2012 575 Function Specifications wd_enabled Enable Watchdog Syntax #include <ctools.h> 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 to TRUE enables the watchdog. Calling the function with state set to FALSE disables the watchdog. Document (Version 2.22) 10/26/2012 576 Function Specifications wd_manual Manual Watchdog Timer Mode Syntax #include <ctools.h> void wd_manual(void); Description The wd_manual function takes control of the watchdog timer. Notes The application program must retrigger the watchdog timer at least every 0.5 seconds using the wd_pulse function, to prevent an controller reset. Refer to the Functions Overview section for more information. See Also wd_auto, wd_pulse Example This program takes control of the watchdog timer for a section of code, then returns it to the control of the operating system. #include <ctools.h> void 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 2.22) 10/26/2012 577 Function Specifications wd_pulse Retrigger Watchdog Timer Syntax #include <ctools.h> 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 prevent an controller reset, if the wd_manual function has been executed. Refer to the Functions Overview section for more information. See Also wd_auto Example See the example for the wd_manual function Document (Version 2.22) 10/26/2012 578 Function Specifications writeBoolVariable Write to IEC 61131-3 Boolean Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 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-3 Symbols Status is invalid, nothing is done and FALSE is returned. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share 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-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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. See Also setdbase Example This program writes a TRUE state to the boolean variable named “Switch1”. #include <ctools.h> void main(void) { BOOLEAN status; request_resource(IO_SYSTEM); status = writeBoolVariable("Switch1", TRUE); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 579 Function Specifications writeIntVariable Write to IEC 61131-3 Integer Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 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-3 Symbols Status is invalid, nothing is done and FALSE is returned. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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. See Also setdbase Example This program writes the value 120,000 to the integer variable named “Pressure1”. #include <ctools.h> void main(void) { BOOLEAN status; request_resource(IO_SYSTEM); status = writeIntVariable("Pressure1", 120000); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 580 Function Specifications writeRealVariable Write to IEC 61131-3 Real Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 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-3 Symbols Status is invalid, nothing is done and FALSE is returned. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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. See Also setdbase Example This program writes the value 25.607 to the real variable named “Flowrate”. #include <ctools.h> void main(void) { BOOLEAN status; request_resource(IO_SYSTEM); status = writeRealVariable("Flowrate", 25.607); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 581 Function Specifications writeMsgVariable Write to IEC 61131-3 Message Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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-3 Dictionary also treats variable names as case insensitive). If the variable is found, TRUE is returned and the specified string is written to the message variable. If the variable is not found or if the IEC 61131-3 Symbols Status is invalid, nothing is done and FALSE is returned. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share 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). 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-3 message variables have the following format: Byte Location Description 0 Maximum length as declared in IEC 61131-3 Dictionary (1 to 255) Current Length = location of first null byte (0 to maximum length) First message data byte 1 2 … max + 1 max + 2 Last byte in message buffer Null termination byte (Terminates a message having the maximum length.) Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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. Document (Version 2.22) 10/26/2012 582 Function Specifications The IO_SYSTEM system resource needs to be requested before calling this function. See Also setdbase 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 <ctools.h> void main(void) { BOOLEAN status; unsigned char msg[13]; msg[0] = 10; msg[1] = 7; msg[2] = 'W'; msg[3] = 'a'; msg[4] = 'r'; msg[5] = 'n'; msg[6] = 'i'; msg[7] = 'n'; msg[8] = 'g'; msg[9] = 0; msg[10] = 0; msg[11] = 0; msg[12] = 0; request_resource(IO_SYSTEM); status = writeMsgVariable("TextData", msg); release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 583 Function Specifications writeTimerVariable Write to IEC 61131-3 Timer Variable (IEC 61131-3 firmware only) Syntax #include <ctools.h> 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 value 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 61131-3 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-3 Symbols Status is invalid, nothing is done and FALSE is returned. The IEC 61131-3 Symbols Status is invalid if the Application TIC code download and Application Symbols download do not share the same symbols CRC checksum. Notes This function requires the IEC 61131-3 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-3 variables by name; however, because the variable name needs to be looked up in the IEC 61131-3 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. See Also setdbase Example This program writes the value 10000 ms to the timer variable named “Delay”. #include <ctools.h> void main(void) { BOOLEAN status; request_resource(IO_SYSTEM); status = writeTimerVariable("Delay", 10000); Document (Version 2.22) 10/26/2012 584 Function Specifications release_resource(IO_SYSTEM); } Document (Version 2.22) 10/26/2012 585 Function Specifications writev Syntax #include <ctools.h> int writev ( int socketDescriptor, const struct iovec * iov, int iovcnt ); Function Description writev functions as a scatter write because the written data can be placed in multiple buffers. writev attempts to write data to the socket socketDescriptor by gathering the data from into the iovcnt buffers specified by the members of the iov array: iov[0], iov[1], ..., iov[iovcnt-1]. The iovec structure contains the following members: caddr_t iov_base; int iov_len; Each iovec entry specifies the base address and length of an area in memory from where data should be gathered. writev always reads one buffer completely before proceeding to the next. On success, writev return the number of bytes actually written; this number may be less than the total of all of the iov_len values if there is not enough space on the send queues. Parameters socketDescriptor The socket descriptor to write data to. iov The list of buffers to gather and send the data from. iovcnt The number of buffers in the list. Returns >=0 Number of bytes actually written -1 An error occurred. writev will fail if: TM_EBADF The socket descriptor is invalid. TM_EINVAL The iovcnt is 0 or less than 0. The sum of the iov_len values overflowed an integer. TM_ENOBUFS There was insufficient user memory available to complete the operation. TM_ EMSGSIZE The socket requires that message to be sent atomically, and the message was too long. Document (Version 2.22) 10/26/2012 586 Function Specifications TM_ EWOULDBLOCK The socket is marked as non-blocking and all the data could not be written. TM_ENOTCONN The socket is not connected. TM_ESHUTDOWN The user has issued a write shutdown call or a tfClose call (TCP socket only). Document (Version 2.22) 10/26/2012 587 Macro Definitions Macro Definitions A Macro Definition AD_BATTERY AT_ABSOLUTE AT_NONE Internal AD channel connected to lithium battery Internal AD channel connected to thermistor Additive checksum Number of last analog input channel. Number of first analog input channel. Error code: bad analog input channel specified. If defined indicates analog I/O supported. Error code: input device did not respond. Variable name: alarm output address Number of last analog output channel. Number of first analog output channel. Specifies an application type task. All application tasks are terminated by the end_application function. Specifies a fixed time of day alarm. Disables alarms Macro Definition BACKGROUND System event: background I/O requested. The background I/O task uses this event. It should not be used in an application program. Controller type bit mask Specifies 110-baud port speed. Specifies 115200-baud port speed. Specifies 1200-baud port speed. Specifies 150-baud port speed. AD_THERMISTOR ADDITIVE AIN_END AIN_START AIO_BADCHAN AIO_SUPPORTED AIO_TIMEOUT AO AOUT_END AOUT_START APPLICATION B BASE_TYPE_MASK BAUD110 BAUD115200 BAUD1200 BAUD150 Document (Version 2.22) 10/26/2012 588 Macro Definitions Macro Definition BAUD19200 BAUD2400 BAUD300 BAUD38400 BAUD4800 BAUD57600 BAUD600 BAUD75 BAUD9600 BYTE_EOR Specifies 19200-baud port speed. Specifies 2400-baud port speed. Specifies 300-baud port speed. Specifies 38400-baud port speed. Specifies 4800-baud port speed. Specifies 57600-baud port speed. Specifies 600-baud port speed. Specifies 75-baud port speed. Specifies 9600-baud port speed. Byte-wise exclusive OR checksum Macro Definition CA CLASS0_FLAG Variable name: cascade setpoint source Specifies a flag for enabling DNP Class 0 data Specifies a flag for enabling DNP Class 1 data Sspecifies a flag for enabling DNP Class 2 data Specifies a flag for enabling DNP Class 3 data Specifies switch is in closed position Cold-boot switch depressed when CPU was reset. Points to a file object for the com1 serial port. System event: indicates activity on com1 receiver. The meaning depends on the character handler installed. Points to a file object for the com2 serial port. System event: indicates activity on com2 receiver. The meaning depends on the character handler installed. Points to a file object for the com3 serial port. C CLASS1_FLAG CLASS2_FLAG CLASS3_FLAG CLOSED COLD_BOOT com1 COM1_RCVR com2 COM2_RCVR com3 Document (Version 2.22) 10/26/2012 589 Macro Definitions Macro Definition COM3_RCVR System event: indicates activity on com3 receiver. The meaning depends on the character handler installed. Points to a file object for the com4serial port. System event: indicates activity on com4 receiver. The meaning depends on the character handler installed. Specifies number of 5000 I/O module counter input channels Number of last counter input channel Number of first counter input channel If defined indicates counter I/O hardware supported. Frequency of the system clock in cycles per second Variable name: control register CRC-16 type CRC checksum (reverse algorithm) CCITT type CRC checksum (reverse algorithm) com4 COM4_RCVR COUNTER_CHANNELS COUNTER_END COUNTER_START COUNTER_SUPPORTED CPU_CLOCK_RATE CR CRC_16 CRC_CCITT D Macro Definition DATA_SIZE Maximum length of the HART command or response field. Specifies 7 bit world length. Specifies 8 bit word length. Variable name: deadband Error code: out of range address specified Error code: bad database addressing type specified Error code: no error occurred Add the ID to the configuration registers. Remove the ID from the configuration registers. Device configuration application type is a C application Device configuration application type is the first logic application DATA7 DATA8 DB DB_BADSIZE DB_BADTYPE DB_OK DCA_ADD DCA_REMOVE DCAT_C DCAT_LOGIC1 Document (Version 2.22) 10/26/2012 590 Macro Definitions Macro Definition DCAT_LOGIC2 Device configuration application type is the second logic application The modem configuration structure contains an error The phone number called was busy A call in progress was aborted by the user 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. The modem could not connect to the remote site Modem initialization failed (the modem may be turned off) Modem did not detect a dial tone or the S6 setting in the modem is too short. No error has occurred 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. The serial port is in use by another modem function or has answered an incoming call. Number of last regular digital input channel. Number of first regular digital input channel If defined indicates digital I/O hardware supported. Specifies flow control is disabled. Specifies the DNP protocol for the serial port Variable name: decrease output Number of last regular digital output channel. Number of first regular digital output channel The controller is making a connection to a remote controller The controller is connected to a remote controller The serial port is not in use by a modem The controller is ending a connection to a DE_BadConfig DE_BusyLine DE_CallAborted DE_CarrierLost DE_FailedToConnect DE_InitError DE_NoDialTone DE_NoError DE_NoModem DE_NotInControl DIN_END DIN_START DIO_SUPPORTED DISABLE DNP DO DOUT_END DOUT_START DS_Calling DS_Connected DS_Inactive DS_Terminating Document (Version 2.22) 10/26/2012 591 Macro Definitions Macro Definition DYNAMIC_MEMORY remote controller. System resource: all memory allocation functions such as malloc and alloc. Macro Definition ENABLE ER EVEN EX EXTENDED_DIN_END Specifies flow control is enabled. Variable name: error Specifies even parity. Variable name: automatic execution period Number of last extended digital input channel. Number of first extended digital input channel Number of last extended digital output channel. Number of first extended digital output channel E EXTENDED_DIN_START EXTENDED_DOUT_END EXTENDED_DOUT_START F Macro Definition FIRMWARE_VERSION FOPEN_MAX FORCE_MULTIPLE_COILS FORCE_SINGLE_COIL FULL Controller firmware version number Redefinition of macro from stdio.h Modbus function code Modbus function code Specifies full duplex. Macro Definition GASFLOW Gas Flow calculation firmware option G H Document (Version 2.22) 10/26/2012 592 Macro Definitions Macro Definition HALF Specifies half duplex. Macro Definition IO_SYSTEM System resource for all I/O hardware functions. Macro Definition LED_OFF LED_ON LINEAR LOAD_MULTIPLE_REGISTER S LOAD_SINGLE_REGISTER Specifies LED is to be turned off. Specifies LED is to be turned on. Specifies linear database addressing. Modbus function code I L Modbus function code M Macro Definition MAX_NUMBER_OF_LOGS MAX_NUMBER_OF_FIELDS The maximum number of data logs. The maximum number of fields in a data log record. The maximum task priority. Master message status: invalid database address Master message status: DF1 slave error: addressing problem or memory protect rungs (value = 80) Master message status: invalid function code Master message status: invalid message length Master message status: invalid slave station address MAX_PRIORITY MM_BAD_ADDRESS MM_BAD_ADDRESS_OR_LEN GTH MM_BAD_FUNCTION MM_BAD_LENGTH MM_BAD_SLAVE Document (Version 2.22) 10/26/2012 593 Macro Definitions Macro Definition MM_CMD_ACKED Master message status: DF1 half duplex command has been ACKed by slave Master may now send poll command (value = 10) Master message status: DF1 slave response was an EOT message (value = 7) Master message status: Modbus slave returned a function exception. Master message status: Modbus slave returned an address exception. Master message status: Modbus slave returned a value exception. Master message status: DF1 slave error: illegal command or format (value = 16) Master message status: no message was sent. Master message status: selected protocol is not supported. Master message status: response was received. Master message status: message was sent. Master message status: DF1 slave response did not match command sent (value = 8) Specifies Modbus database addressing. Specifies the Modbus ASCII protocol emulation for the serial port. System resource: Modbus protocol message parser. Specifies the Modbus RTU protocol emulation for the serial port. Maximum length of the modem initialization command string System event: new modem message generated. Specifies the data field in an envelope contains a data value. Specifies the data field in an envelope contains a pointer. Four channel analog input module Eight channel analog input module MM_EOT MM_EXCEPTION_FUNCTION MM_EXCEPTION_ADDRESS MM_EXCEPTION_VALUE MM_ILLEGAL_CMD MM_NO_MESSAGE MM_PROTOCOL_NOT_SUPPO RTED MM_RECEIVED MM_SENT MM_WRONG_RSP MODBUS MODBUS_ASCII MODBUS_PARSER MODBUS_RTU MODEM_CMD_MAX_LEN MODEM_MSG MSG_DATA MSG_POINTER MT_Ain4 MT_Ain8 Document (Version 2.22) 10/26/2012 594 Macro Definitions Macro Definition MT_Aout2 MT_Aout4 MT_Din8 MT_Din16 MT_Dout8 MT_Dout16 MT_Counter4 MT_5414Inputs MT_5414Outputs MT_5415Inputs MT_5415Outputs MT_5601Inputs MT_5601Outputs MT_5904Inputs MT_5904Outputs MT_Counter5232 MT_Din5232 MT_Aout5303 MT_Dout32 MT_Din32 MT_5604Inputs MT_5604Outputs MT_Aout4_Checksum Two channel analog output module Four channel analog output module Eight channel digital input module Sixteen channel digital input module Eight channel digital output module Sixteen channel digital output module Four channel counter input module 5414 digital input module inputs 5414 digital input module outputs 5415 digital output module digital inputs 5415 digital output module digital outputs 5601 module analog and digital inputs 5601 module digital outputs HART interface inputs HART interface outputs 5232 controller board counter inputs 5232 controller board digital inputs 5303 four channel analog output module Thirty two channel digital output module Thirty two channel digital input module 5604 module analog and digital inputs 5604 module digital outputs Four channel analog output module with checksum. This module type can only be used with analog output modules with checksum support. N Macro Definition NEVER NEW_PROGRAM NO_ERROR NO_PROTOCOL System event: this event will never occur. Application program is newly loaded. Error code: indicates no error has occurred. Specifies no communication protocol for the serial port. Specifies no parity. Specifies the normal Modbus response type code for a Modbus Handler Specifies serial port type is not known. NONE NORMAL NOTYPE Document (Version 2.22) 10/26/2012 595 Macro Definitions Macro Definition NUMAB Number of registers in the Allan-Bradley database. Number of registers in the Modbus coil section. Number of registers in the Modbus holding register section. Number of registers in the Modbus input register section. Number of registers in the linear database. Number of registers in the Modbus status section. NUMCOIL NUMHOLDING NUMINPUT NUMLINEAR NUMSTATUS O Macro Definition ODD OPEN Specifies odd parity. Specifies switch is in open position Macro Definition PC_FLOW_RX_RECEIVE_ST OP PC_FLOW_RX_XON_XOFF PC_FLOW_TX_IGNORE_CTS PC_FLOW_TX_XON_XOFF PC_PROTOCOL_RTU_FRAMI NG PHONE_NUM_MAX_LEN PROGRAM_EXECUTED PPP Receiver disabled after receipt of a message. Receiver Xon/Xoff flow control. Transmitter flow control ignores CTS. Transmitter Xon/Xoff flow control. Modbus RTU framing. Macro Definition READ_COIL_STATUS READ_EXCEPTION_STATUS Modbus function code Modbus function code P Maximum length of the phone number string Application program has been executed. Specifies the PPP Protocol for the serial port. R Document (Version 2.22) 10/26/2012 596 Macro Definitions Macro Definition READ_HOLDING_REGISTER READ_INPUT_REGISTER READ_INPUT_STATUS READSTATUS REPORT_SLAVE_ID RFC_MODBUS_RTU RS485_4WIRE RUN Modbus function code Modbus function code Modbus function code enum ReadStatus Modbus function code Flow control type, may be used in place of ENABLE Flow control type, may be used in place of DISABLE RX flow control type used for the PPP protocol. Specifies serial port is an RS-232 port. Specifies serial port is RS232 and uses CD for collision avoidance. Specifies serial port is an RS-232 dial-up modem. Specifies serial port is a 4 wire RS-485 port. Run/Service switch is in RUN position. Macro Definition S_MODULE_FAILURE Status LED code for I/O module communication failure Status LED code for normal status SCADAPack 32 controller SCADAPack 32 LIGHT controller SCADAPack 32 PLUS controller Number of serial ports. Run/Service switch is in SERVICE position. Result code: translation is already defined in the table Result code: invalid translation table index Result code: entry does not define a translation Result code: serial port is not valid Result code: station number is not valid RFC_NONE RFC_QUEUED RS232 RS232_COLLISION_AVOIDAN CE RS232_MODEM S S_NORMAL SCADAPACK 32 SCADAPACK 32_LIGHT SCADAPACK 32_PLUS SERIAL_PORTS SERVICE SF_ALREADY_DEFINED SF_INDEX_OUT_OF_RANGE SF_NO_TRANSLATION SF_PORT_OUT_OF_RANGE SF_STATION_OUT_OF_RAN GE SF_TABLE_SIZE Document (Version 2.22) 10/26/2012 Number of entries in the store and forward table 597 Macro Definitions Macro Definition SF_VALID SIGNAL_CTS SIGNAL_CTS SIGNAL_DCD SIGNAL_DCD SIGNAL_OFF SIGNAL_OH SIGNAL_OH SIGNAL_ON SIGNAL_RING SIGNAL_RING SIGNAL_VOICE SIGNAL_VOICE SLEEP_MODE_SUPPORTED SMARTWIRE_5201_5202 STACK_SIZE START_COIL Result code: translation is valid I/O line bit mask: clear to send signal Matches status of CTS input. I/O line bit mask: carrier detect signal Matches status of DCD input. Specifies a signal is de-asserted I/O line bit mask: off hook signal Not supported – forced low (1). Specifies a signal is asserted I/O line bit mask: ring signal Not supported – forced low (0). I/O line bit mask: voice/data switch signal Not supported – forced low (0). Defined if sleep function is supported SmartWIRE 5201 and 5202 controllers Size of the machine stack. Start of the coils section in the linear database. Start of the holding register section in the linear database. Start of the input register section in the linear database. Start of the status section in the linear database. Specifies the application start up task. START_HOLDING START_INPUT START_STATUS STARTUP_ APPLICATION STARTUP_SYSTEM STOP1 STOP2 SYSTEM Specifies the system start up task. Specifies 1 stop bit. Specifies 2 stop bits. Specifies a system type task. System tasks are not terminated by the end_application function. T Macro Definition T_CELSIUS T_FAHRENHEIT Specifies temperatures in degrees Celsius Specifies temperatures in degrees Fahrenheit Document (Version 2.22) 10/26/2012 598 Macro Definitions Macro Definition T_KELVIN T_RANKINE TELESAFE_6000_16EX TELESAFE_MICRO_16 TFC_IGNORE_CTS Specifies temperatures in degrees Kelvin Specifies temperatures in degrees Rankine TeleSAFE 6000-16EX controller TeleSAFE Micro16 controller Flow control type, may be used in place of ENABLE Flow control type, may be used in place of DISABLE Error code: invalid timer interval Error code: invalid timer Number of last valid software timer. Task status indicating task is executing. Task status indicating task is ready to execute Task status indicating task is blocked waiting for a resource Task status indicating task is blocked waiting for an envelope Task status indicating task is blocked waiting for an event Task status indicating task is blocked waiting for a message TFC_NONE TIMER_BADINTERVAL TIMER_BADTIMER TIMER_MAX TS_EXECUTING TS_READY TS_WAIT_ RESOURCE TS_WAIT_ENVELOPE TS_WAIT_EVENT TS_WAIT_MESSAGE V Macro Definition VI_DATE_SIZE Number of characters in version information date field Macro Definition WRITESTATUS WS_ALL WS_COUNTER_0_OVERFLO W WS_COUNTER_1_OVERFLO W WS_COUNTER_2_OVERFLO enum WriteStatus All wake up sources enabled Bit mask to enable counter 0 overflow as wake up source Bit mask to enable counter 1 overflow as wake up source Bit mask to enable counter 2 overflow as W Document (Version 2.22) 10/26/2012 599 Macro Definitions Macro Definition W WS_INTERRUPT_INPUT wake up source Bit mask to enable interrupt input as wake up source Bit mask to enable LED power switch as wake up source No wake up source enabled Bit mask to enable real time clock as wake up source Undefined wake up source WS_LED_POWER_SWITCH WS_NONE WS_REAL_TIME_CLOCK WS_UNDEFINED Document (Version 2.22) 10/26/2012 600 Structures and Types Structures and Types ABConfiguration The ABConfiguration structure defines settings for DF1 communication protocol. /* DF1 Protocol Configuration */ struct ABConfiguration { unsigned min_protected_address; unsigned max_protected_address; }; • min_protected_address is the minimum allowable DF1 physical 16-bit address allowed in all protected commands. The default value is 0. • max_protected_address is the maximum allowable DF1 physical 16-bit address allowed in all protected commands. The default value is NUMAB. ADDRESS_MODE The ADDRESS_MODE enumerated type describes addressing modes for communication protocols. typedef enum addressMode_t { AM_standard = 0, AM_extended } ADDRESS_MODE; AM_standard returns standard Modbus addressing. Standard addressing allows 255 stations and is compatible with standard Modbus devices 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; • type specifies the type of alarm. It may be the AT_NONE or AT_ABSOLUTE macro. • hour specifies the hour at which the alarm will occur. • minute specifies the minute at which the alarm will occur. Document (Version 2.22) 10/26/2012 601 Structures and Types • 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 { CIF_Com1 = 1, CIF_Com2 = 2, CIF_Com3 = 3, CIF_Com4 = 4, CIF_Ethernet1 = 100 } COM_INTERFACE; 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-3, // master task connection created for an IEC 61131-3 masterip FB CT_MasterCApp, // master task connection created for a C/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/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. typedef struct datalogConfig_type { UINT16 records; /* # of records */ UINT16 fields; /* # of fields per record */ DATALOG_VARIABLE typesOfFields[MAX_NUMBER_OF_FIELDS]; } Document (Version 2.22) 10/26/2012 602 Structures and Types DATALOG_CONFIGURATION; DATALOG_STATUS The data log status enumerated type is used to report status information. typedef enum { DLS_CREATED = 0, DLS_BADID, DLS_EXISTS, DLS_NOMEMORY, DLS_BADCONFIG, } DATALOG_STATUS; /* /* /* /* /* data log created */ invalid log ID */ log already exists */ insufficient memory for log */ invalid configuration */ DATALOG_VARIABLE 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, DLV_INT16, DLV_UINT32, DLV_INT32, DLV_FLOAT, DLV_CMITIME, DLV_DOUBLE, DLV_NUMBER_OF_TYPES } DATALOG_VARIABLE; /* /* /* /* /* /* /* 16 16 32 32 32 64 64 bit bit bit bit bit bit bit unsigned integer */ signed integer */ unsigned integer */ signed integer */ floating point */ time */ floating point */ DialError 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, DE_BadConfig, DE_NoModem, DE_InitError, DE_NoDialTone, DE_BusyLine, DE_CallAborted, DE_FailedToConnect, DE_CarrierLost, DE_NotInControl DE_CallCut }; • DE_NoError returns no error has occurred • DE_BadConfig returns the modem configuration structure contains an error Document (Version 2.22) 10/26/2012 603 Structures and Types • DE_NoModem returns the serial port is not configured as a modem (port type needs to be RS232_MODEM). Or 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. DialState The DialState enumerated type defines the state of the modemDial operation and may have one of the following values. enum DialState { DS_Inactive, DS_Calling, DS_Connected, DS_Terminating }; • DS_Inactive returns the serial port is not in use by a modem • 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. DNP_ADDRESS_MAP_TABLE The dnpAddressMapTable type describes an entry in the DNP Address Mapping Table. typedef struct dnpAddressMapTable_type { Document (Version 2.22) 10/26/2012 604 Structures and Types UINT16 address; CHAR objectType; UINT16 remoteObjectStart; UINT16 numberOfPoints; UINT16 localModbusAddress; } dnpAddressMapTable; • address is the DNP station address of the remote station. • objectType is the DNP object type. • remoteObjectStart is the DNP address of first object in the remote station. • numberOfPoints is the number of points. • localModbusAddress is the Modbus address of first object in local station. dnpAnalogInput 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; • modbusAddress is the address of the Modbus register number associated with the point. • class is the reporting class for the object. It may be set to CLASS_1, CLASS_2 or CLASS_3. • deadband is the amount by which the analog input value needs to change before an event will be reported for the point. DnpAnalogInputShortFloat 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; } dnpAnalogInputShortFloat; • modbusAddress is the address of the Modbus register number associated with the point. • eventClass is the reporting class for the object. It may be set to CLASS_1, CLASS_2 or CLASS_3. Document (Version 2.22) 10/26/2012 605 Structures and Types • deadband is the amount by which the analog input value needs to change before an event will be reported for the point. dnpAnalogOutput 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; • modbusAddress is the address of the Modbus register associated with the point. dnpBinaryInput The dnpBinaryInput type describes a DNP binary input point. typedef struct dnpBinaryInput_type { UINT16 modbusAddress; UCHAR class; } dnpBinaryInput; • 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. dnpBinaryInputEx The dnpBinaryInputEx type describes an extended DNP Binary Input point. typedef struct dnpBinaryInputEx_type { UINT16 modbusAddress; UCHAR eventClass; UCHAR debounce; } dnpBinaryInputEx; • 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. dnpBinaryOutput The dnpBinaryOutput type describes a DNP binary output point. typedef struct dnpBinaryOutput_type { UINT16 modbusAddress1; UINT16 modbusAddress2; Document (Version 2.22) 10/26/2012 606 Structures and Types UCHAR controlType; } dnpBinaryOutput; • modbusAddress1 is the address of the first Modbus register associated with the point. This field is always used. • modbusAddress2 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, DNP_DISCONNECTED, DNP_CONNECTION_REQUIRED, DNP_MESSAGE_COMPLETE, DNP_MESSAGE_TIMEOUT } DNP_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. • 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 DNP_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. Document (Version 2.22) 10/26/2012 607 Structures and Types • 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. dnpConfiguration The dnpConfiguration type describes the DNP parameters. typedef struct dnpConfiguration_type { UINT16 masterAddress; UINT16 rtuAddress; CHAR datalinkConfirm; CHAR datalinkRetries; UINT16 datalinkTimeout; UINT16 operateTimeout; UCHAR applicationConfirm; UINT16 maximumResponse; UCHAR applicationRetries; UINT16 applicationTimeout; INT16 timeSynchronization; UINT16 BI_number; UINT16 BI_startAddress; CHAR BI_reportingMethod; UINT16 BI_soebufferSize; UINT16 BO_number; UINT16 BO_startAddress; UINT16 CI16_number; UINT16 CI16_startAddress; CHAR CI16_reportingMethod; UINT16 CI16_bufferSize; UINT16 CI32_number; UINT16 CI32_startAddress; CHAR CI32_reportingMethod; UINT16 CI32_bufferSize; CHAR CI32_wordOrder; UINT16 AI16_number; 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 AO16_startAddress; UINT16 AO32_number; UINT16 AO32_startAddress; Document (Version 2.22) 10/26/2012 608 Structures and Types CHAR AO32_wordOrder; UINT16 AOSF_number; UINT16 AOSF_startAddress; CHAR AOSF_wordOrder; UINT16 autoUnsolicitedClass1; UINT16 holdTimeClass1; UINT16 holdCountClass1; UINT16 autoUnsolicitedClass2; UINT16 holdTimeClass2; UINT16 holdCountClass2; UINT16 autoUnsolicitedClass3; UINT16 holdTimeClass3; UINT16 holdCountClass3; UINT16 enableUnsolicitedOnStartup; UINT16 sendUnsolicitedOnStartup; UINT16 level2Compliance; } dnpConfiguration; • masterAddress is the address of the master station. Unsolicited messages are sent to this station. Solicited messages need to come from this station. Valid values are 0 to 65534. • rtuAddress is the address of the RTU. The master station needs to send messages to this address. Valid values are 0 to 65534. • datalinkConfirm enables requesting data link layer confirmations. Valid values are TRUE and FALSE. • datalinkRetries is the number of times the data link layer will retry a failed message. Valid values are 0 to 255. • 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. • 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. • applicationConfirm enables requesting application layer confirmations. Valid values are TRUE and FALSE. • 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. • applicationRetries is the number of times the application layer will retry a transmission. Valid values are 0 to 255. • 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 needs to be larger than the data link timeout. Document (Version 2.22) 10/26/2012 609 Structures and Types • timeSynchronization defines how often the RTU will request a time synchronization from the master. • Set this to NO_TIME_SYNC to disable time synchronization requests. • Set this to STARTUP_TIME_SYNC to request time synchronization at start up only. • Set this to 1 to 32767 to set the time synchronization period in seconds. • BI_number is the number of binary input points. Valid values are 0 to 9999. • BI_startAddress is the DNP address of the first Binary Input point. • BI_reportingMethod determines how binary inputs are reported either Change Of State or Log All Events. • BI_soeBufferSize is the Binary Input Change Event Buffer Size. • BO_number is the number of binary output points. Valid values are 0 to 9999. • BO_startAddress is the DNP address of the first Binary Output point. • CI16_number is the number of 16-bit counter input points. Valid values are 0 to 9999. • CI16_startAddress is the DNP address of the first CI16 point. • CI16_reportingMethod determines how CI16 inputs are reported either Change Of State or Log All Events. • CI16_bufferSize is the number of events in the 16-bit counter change buffer. Valid values are 0 to 9999. • CI32_number is the number of 32-bit counter input points. Valid values are 0 to 9999. • CI32_startAddress is the DNP address of the first CI32 point. • CI32_reportingMethod determines how CI32 inputs are reported either Change Of State or Log All Events. • CI32_bufferSize is the number of events in the 32-bit counter change buffer. Valid values are 0 to 9999. • CI32_wordOrder is the Word Order of CI32 points (0=LSW first, 1=MSW first). • AI16_number is the number of 16-bit analog input points. Valid values are 0 to 9999. • AI16_startAddress is the DNP address of the first AI16 point. • AI16_reportingMethod determines how 16-bit analog changes are reported. Set this to FIRST_VALUE to report the value of the first change event measured. Document (Version 2.22) 10/26/2012 610 Structures and Types Set this to CURRENT_VALUE to report the value of the latest change event measured. • AI16_bufferSize is the number of events in the 16-bit analog input change buffer. Valid values are 0 to 9999. • AI32_number is the number of 32-bit analog input points. Valid values are 0 to 9999. • AI32_startAddress is the DNP address of the first AI32 point. • AI32_reportingMethod determines how 32-bit analog changes are reported. Set this to FIRST_VALUE to report the value of the first change event measured. Set this to CURRENT_VALUE to report the value of the latest change event measured. • AI32_bufferSize is the number of events in the 32-bit analog input change buffer. Valid values are 0 to 9999. • AI32_wordOrder is the Word Order of AI32 points (0=LSW first, 1=MSW first) • AO16_number is the number of 16-bit analog output points. Valid values are 0 to 9999. • AO16_startAddress is the DNP address of the first AO16 point. • AO32_number is the number of 32-bit analog output points. Valid values are 0 to 9999. • AO32_startAddress is the DNP address of the first AO32 point. • AO32_wordOrder is the Word Order of AO32 points (0=LSW first, 1=MSW first) • AOSF_number is the number of short float Analog Outputs. • AOSF_startAddress is the DNP address of first AOSF point. • AOSF_wordOrder is the Word Order of AOSF points (0=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. Document (Version 2.22) 10/26/2012 611 Structures and Types • 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 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. dnpConfigurationEx The dnpConfigurationEx type includes extra parameters in the DNP Configuration. typedef struct dnpConfigurationEx_type { UINT16 rtuAddress; UCHAR datalinkConfirm; UCHAR datalinkRetries; UINT16 datalinkTimeout; UINT16 operateTimeout; UCHAR applicationConfirm; UINT16 maximumResponse; UCHAR applicationRetries; UINT16 applicationTimeout; INT16 timeSynchronization; UINT16 BI_number; UINT16 BI_startAddress; UCHAR BI_reportingMethod; UINT16 BI_soeBufferSize; UINT16 BO_number; UINT16 BO_startAddress; UINT16 CI16_number; UINT16 CI16_startAddress; UCHAR CI16_reportingMethod; UINT16 CI16_bufferSize; UINT16 CI32_number; UINT16 CI32_startAddress; Document (Version 2.22) 10/26/2012 612 Structures and Types UCHAR CI32_reportingMethod; UINT16 CI32_bufferSize; UCHAR CI32_wordOrder; UINT16 AI16_number; UINT16 AI16_startAddress; UCHAR AI16_reportingMethod; UINT16 AI16_bufferSize; UINT16 AI32_number; UINT16 AI32_startAddress; UCHAR AI32_reportingMethod; UINT16 AI32_bufferSize; UCHAR AI32_wordOrder; UINT16 AISF_number; UINT16 AISF_startAddress; UCHAR AISF_reportingMethod; UINT16 AISF_bufferSize; UCHAR AISF_wordOrder; UINT16 AO16_number; UINT16 AO16_startAddress; UINT16 AO32_number; UINT16 AO32_startAddress; UCHAR AO32_wordOrder; UINT16 AOSF_number; UINT16 AOSF_startAddress; UCHAR AOSF_wordOrder; UINT16 autoUnsolicitedClass1; UINT16 holdTimeClass1; UINT16 holdCountClass1; UINT16 autoUnsolicitedClass2; UINT16 holdTimeClass2; UINT16 holdCountClass2; UINT16 autoUnsolicitedClass3; UINT16 holdTimeClass3; UINT16 holdCountClass3; UINT16 enableUnsolicitedOnStartup; UINT16 sendUnsolicitedOnStartup; UINT16 level2Compliance; UINT16 masterAddressCount; UINT16 masterAddress[MAX_MASTER_ADDRESS_COUNT8]; UINT16 maxEventsInResponse; UINT16 PSTNDialAttempts; UINT16 PSTNDialTimeout; UINT16 PSTNPauseTime; UINT16 PSTNOnlineInactivity; UINT16 PSTNDialType; char modemInitString[MAX_DIAL_PREFIX_SIZE]; } dnpConfigurationEx; • rtuAddress is the address of the RTU. The master station needs to send messages to this address. Valid values are 0 to 65534. • datalinkConfirm enables requesting data link layer confirmations. Valid values are TRUE and FALSE. • datalinkRetries is the number of times the data link layer will retry a failed message. Valid values are 0 to 255. Document (Version 2.22) 10/26/2012 613 Structures and Types • 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. • 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. • applicationConfirm enables requesting application layer confirmations. Valid values are TRUE and FALSE. • 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. • applicationRetries is the number of times the application layer will retry a transmission. Valid values are 0 to 255. • 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 needs to be larger than the data link timeout. • timeSynchronization defines how often the RTU will request a time synchronization from the master. • Set this to NO_TIME_SYNC to disable time synchronization requests. • Set this to STARTUP_TIME_SYNC to request time synchronization at start up only. • Set this to 1 to 32767 to set the time synchronization period in seconds. • BI_number is the number of binary input points. Valid values are 0 to 9999. • BI_startAddress is the DNP address of the first Binary Input point. • BI_reportingMethod determines how binary inputs are reported either Change Of State or Log All Events. • BI_soebufferSize is the Binary Input Change Event Buffer Size. • BO_number is the number of binary output points. Valid values are 0 to 9999. • BO_startAddress is the DNP address of the first Binary Output point. • CI16_number is the number of 16-bit counter input points. Valid values are 0 to 9999. • CI16_startAddress is the DNP address of the first CI16 point. • CI16_reportingMethod determines how CI16 inputs are reported either Change Of State or Log All Events. • CI16_bufferSize is the number of events in the 16-bit counter change buffer. Valid values are 0 to 9999. Document (Version 2.22) 10/26/2012 614 Structures and Types • CI32_number is the number of 32-bit counter input points. Valid values are 0 to 9999. • CI32_startAddress is the DNP address of the first CI32 point. • CI32_reportingMethod determines how CI32 inputs are reported either Change Of State or Log All Events. • CI32_bufferSize is the number of events in the 32-bit counter change buffer. Valid values are 0 to 9999. • CI32_wordOrder is the Word Order of CI32 points (0=LSW first, 1=MSW first). • AI16_number is the number of 16-bit analog input points. Valid values are 0 to 9999. • AI16_startAddress is the DNP address of the first AI16 point. • AI16_reportingMethod determines how 16-bit analog changes are reported. Set this to FIRST_VALUE to report the value of the first change event measured. Set this to CURRENT_VALUE to report the value of the latest change event measured. • AI16_bufferSize is the number of events in the 16-bit analog input change buffer. Valid values are 0 to 9999. • AI32_number is the number of 32-bit analog input points. Valid values are 0 to 9999. • AI32_startAddress is the DNP address of the first AI32 point. • AI32_reportingMethod determines how 32-bit analog changes are reported. Set this to FIRST_VALUE to report the value of the first change event measured. Set this to CURRENT_VALUE to report the value of the latest change event measured. • AI32_bufferSize is the number of events in the 32-bit analog input change buffer. Valid values are 0 to 9999. • AI32_wordOrder is the Word Order of AI32 points (0=LSW first, 1=MSW first) • AISF_number is the number of short float Analog Inputs. • AISF_startAddress is the DNP address of first AISF point. • AISF_reportingMethod is the event reporting method, Change Of State or Log All Events. • AISF_bufferSize is the short float Analog Input Event Buffer Size. Document (Version 2.22) 10/26/2012 615 Structures and Types • AISF_wordOrder is the word order of AISF points (0=LSW first, 1=MSW first) */ • AO16_number is the number of 16-bit analog output points. Valid values are 0 to 9999. • AO16_startAddress is the DNP address of the first AO16 point. • AO32_number is the number of 32-bit analog output points. Valid values are 0 to 9999. • AO32_startAddress is the DNP address of the first AO32 point. • AO32_wordOrder is the Word Order of AO32 points (0=LSW first, 1=MSW first) • AOSF_number is the number of short float Analog Outputs. • AOSF_startAddress is the DNP address of first AOSF point. • AOSF_wordOrder is the Word Order of AOSF points (0=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. • HoldCountClass3 is the maximum number of Class 3 events to hold before reporting. • EnableUnsolicitedOnStartup enables or disables unsolicited reporting at start-up. • SendUnsolicitedOnStartup sends an unsolicited report at start-up. • level2Compliance reports only level 2 compliant data types (excludes floats, AO-32). Document (Version 2.22) 10/26/2012 616 Structures and Types • MasterAddressCount is the number of master stations. • masterAddress[MAX_MASTER_ADDRESS_COUNT] is the arrey that holds addresses of master stations. • maxEventsInResponse is the maximum number of change events to include in read response. • PSTNDialAttempts is the maximum number of dial attempts to establish a PSTN connection. • PSTNDialTimeout is the maximum time after initiating a PSTN dial sequence to wait for a carrier signal. • PSTNPauseTime is the pause time between dial events. • PSTNOnlineInactivity is the maximum time after message activity to leave a PSTN connection open before hanging up. • PSTNDialType is the dial type: tone or pulse dialling. • modemInitString[MAX_DIAL_PREFIX_SIZE] is the initialization string to send to the modem. dnpCounterInput The dnpCounterInput 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; } dnpCounterInput; • modbusAddress is the address of the Modbus register number associated with the point. • class is the reporting class for the object. It may be set to CLASS_1, CLASS_2 or CLASS_3. • threshold is the amount by which the counter input value needs to change before an event will be reported for the point. dnpMasterPoll The dnpMasterPoll type describes an entry in the DNP Master Poll Table. typedef struct dnpMasterPoll_type { UINT16 dnpRemoteStationAddress; UINT16 class0PollRate; UINT16 class1PollRate; UINT16 class2PollRate; UINT16 class3PollRate; UINT16 timeSyncRate; Document (Version 2.22) 10/26/2012 617 Structures and Types UINT16 unsolicitedResponseFlags; } dnpMasterPoll; • dnpRemoteStationAddress is the remote DNP station address. • class0PollRate 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. DNP Master Poll table Extended Entry The dnpMasterPollEx type describes an extended entry in the DNP Master Poll Table. typedef struct dnpMasterPollTableEx_type { INT16 dnpRemoteStationAddress; INT16 class0PollRate; INT16 class1PollRate; INT16 class2PollRate; INT16 class3PollRate; INT16 timeSyncRate; UINT16 unsolicitedResponseFlags; UINT16 class0PollOffset; UINT16 class1PollOffset; UINT16 class2PollOffset; UINT16 class3PollOffset; UINT16 timeSyncOffset; INT16 class1MaxEvents; INT16 class2MaxEvents; INT16 class3MaxEvents; UINT16 saveIINFlagsRegister; } dnpMasterPollTableEx; • dnpRemoteStationAddress is the remote DNP station address. • class0PollRate 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. Document (Version 2.22) 10/26/2012 618 Structures and Types • TimeSyncRate is the time synchronisation rate. • unsolicitedResponseFlags are the flags for enabling Unsolicited Responses. • class0PollOffset 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. • saveIINFlagsRegister. dnpPointType The enumerated type DNP_POINT_TYPE includes all allowed DNP data point types. typedef enum dnpPointType { BI_POINT=0, /* binary input */ AI16_POINT, /* 16 bit analog input */ AI32_POINT, /* 32 bit analog input */ AISF_POINT, /* short float analog input */ AILF_POINT, /* long float analog input */ CI16_POINT, /* 16 bit counter output */ CI32_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 */ } DNP_POINT_TYPE; dnpProtocolStatus The dnpPrototocolStatus structure contains status information for DNP message transactions. struct dnpPrototocolStatus { UINT16 successes; UINT16 failures; UINT16 failuresSinceLastSuccess; UINT16 formatErrors; UINT16 framesReceived; UINT16 framesSent; UINT16 messagesReceived; UINT16 messagesSent; Document (Version 2.22) 10/26/2012 619 Structures and Types }; 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. • commandStatus is the status of the last protocol command sent. dnpRoutingTableEx The dnpRoutingTableEx 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 4 = serial port com4 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. Document (Version 2.22) 10/26/2012 620 Structures and Types /* DNP Runtime Status */ typedef struct dnp_runtime_status { UINT16 eventCountBI; /* number of binary input events */ UINT16 eventCountCI16; /* number of 16-bit counter events */ UINT16 eventCountCI32; /* number of 32-bit counter events */ UINT16 eventCountAI16; /* number of 16-bit analog input events */ UINT16 eventCountAI32; /* number of 32-bit analog input events */ 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 */ } DNP_RUNTIME_STATUS; • eventCountBI is number of binary input events. • eventCountCI16 is number of 16-bit counter events. • eventCountCI32 is number of 32-bit counter events. • eventCountAI16 is number of 16-bit analog input events. • eventCountAI32 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. • eventCountClass3 is the class 3 event counter. envelope The envelope type is a structure containing a message envelope. Envelopes are used for inter-task communication. 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; • 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. • source is the task ID of the task sending the message. This field is specified automatically by the send_message function. The receiving task may read this field to determine the source of the message. Document (Version 2.22) 10/26/2012 621 Structures and Types • destination is the task ID of the task to receive the message. It needs to be specified before calling the send_message function. • 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. • data is the message data. The field may contain a datum or pointer. The application program determines the use of this field. HART_COMMAND 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; • command is the HART command number. • length is the number of characters in the data string. • data[DATA_SIZE] is the data field for the command. HART_DEVICE 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 { UCHAR manufacturerID; UCHAR manufacturerDeviceType; UCHAR preamblesRequested; UCHAR commandRevision; UCHAR transmitterRevision; UCHAR softwareRevision; UCHAR hardwareRevision; UCHAR flags; UINT32 deviceID; } HART_DEVICE; Document (Version 2.22) 10/26/2012 622 Structures and Types HART_RESPONSE 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 * pData; } HART_RESPONSE; • response is the response code from the device. • length is the length of response data. • data[DATA_SIZE] is the data field for the response. HART_RESULT 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; • HR_NoModuleResponse returns no response from HART modem module. • HR_CommandPending returns command ready to be sent, but not sent. • HR_CommandSent returns command sent. • HR_Response returns response received. • HR_NoResponse returns no response after all attempts. • HR_WaitTransmit returns modem is not ready to transmit. HART_SETTINGS 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 Document (Version 2.22) 10/26/2012 623 Structures and Types 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; • attempts is the number of command attempts (1 to 4). • preambles is the number of preambles to send (2 to 15). • useAutoPreamble is a flag to use the requested preambles. • deviceType is the type of HART master (1 = primary; 0 = secondary). HART_VARIABLE 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; • value is the value of the variable. • units are the units of measurement. • variableCode is the transmitter specific variable ID. IO_CONFIG Structure The IO_CONFIG structure contains I/O System configuration data. typedef struct{ UINT16 slaveAddress; UINT16 dataRate; UINT16 numberOfAttempts; UINT16 ledPower; }IO_CONFIG; 2 slaveAddress returns the I C address, 0 = slave mode disabled dataRate returns the I/O bus data rate • 0 = 100 kHz ; Document (Version 2.22) 10/26/2012 624 Structures and Types • 1 = 150 kHz; • 2 = 200 kHz; • 3 = 250 kHz; • 4 = 300 kHz; • 5 = 350 kHz; • 6 = 400 kHz (default); • 7 = 450 kHz; numberOfAttempts returns the number of attempts, 1 to 4 (default = 1) ledPower returns the led power state, 0 = off, 1 = on (default) IO_STATUS Structure The IO_STATUS structure contains status information from the last scan of a specific I/O module. typedef struct{ UINT16 commStatus; UINT32 scanTime; }IO_STATUS; The IO_STATUS structure contains the following data fields. • commStatus returns the communication status, 0=failed, 1=success • scanTime returns time of last scan in milliseconds according to the stop watch clock IP_ADDRESS 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; }; typedef struct in_addr • IP_ADDRESS; 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 { UINT32 slaveConnections; Document (Version 2.22) 10/26/2012 625 Structures and Types UINT32 masterConnections; UINT32 unusedConnections; } IP_CONNECTION_SUMMARY; • slaveConnections is the number of active slave TCP/IP connections. • masterConnections is the number of active master TCP/IP connections. • unusedConnections is the number of unused TCP/IP connections available. IP_CONFIG_MODE Enumeration The IP_CONFIG_MODE enumeration defines IP configuration options. typedef enum ipConfigMode_t { IPConfig_CtrlSettings = IPConfig_GatewayOnLAN = IPConfig_GatewayOnCom1 = IPConfig_GatewayOnCom2 = IPConfig_GatewayOnCom3 = IPConfig_GatewayOnCom4 = } IP_CONFIG_MODE; 0, 0, 1, 2, 3, 4 • IPConfig_CtrlSettings configures IP settings from controller settings. Default gateway is on LAN subnet. IP_SETTINGS defines gateway address. Same as IPConfig_GatewayOnLAN. • IPConfig_GatewayOnLAN configures IP settings from controller settings. Default gateway is on LAN subnet. IP_SETTINGS defines gateway address. Same as IPConfig_CtrlSettings. • IPConfig_GatewayOnCom1 configures IP settings from controller settings. Default gateway is the com1 PPP connection. • IPConfig_GatewayOnCom2 configures IP settings from controller settings. Default gateway is the com2 PPP connection. • IPConfig_GatewayOnCom3 configures IP settings from controller settings. Default gateway is the com3 PPP connection. • IPConfig_GatewayOnCom4 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 portNumber; UINT32 masterIdleTimeout; Document (Version 2.22) 10/26/2012 626 Structures and Types UINT32 BOOLEAN serverIdleTimeout; serverEnabled; } IP_PROTOCOL_SETTINGS; • portNumber is the TCP or UDP port number for the Modbus IP of DNP IP protocol. Valid port numbers are 1 to 65535. • masterIdleTimeout 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. • serverIdleTimeout 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 protocols. • serverEnabled is the enable server control flag. IP_PROTOCOL_TYPE The IP_PROTOCOL_TYPE enumerated type defines TCP/IP protocols supported by the SCADAPack 32. typedef enum ipProtocol_t { PP_None = 0, IPP_ModbusTcp, IPP_ModbusRtuOverUdp, IPP_ModbusAsciiOverUdp, IPP_DnpOverTcp, IPP_DnpOverUdp } IP_PROTOCOL_TYPE; IP_SETTINGS 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 2.22) 10/26/2012 627 Structures and Types • ipConfigMode are the IP configuration options. See the IP_CONFIG_MODE enumeration for values supported. • ipAddress is the IP address. Only the first 32-bits are supported. • gateway is the network gateway. Only the first 32-bits are supported. • netMask is the subnet mask. • ipVersion is the IP version. Only the value 4 is supported for IP version 4. ledControl_tag The ledControl_tag structure defines LED power control parameters. struct ledControl_tag { UINT16 state; UINT16 time; }; • state is the default LED state. It is either the LED_ON or LED_OFF macro. • 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; • stream is the serial port to send the command message. Valid values are: com1, com2, com3, com4. • function specifies the Modbus function code. Refer to the communication protocol manual for supported function codes. • slaveStation specifies the address of the slave station. • 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. Document (Version 2.22) 10/26/2012 628 Structures and Types • 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. • length specifies the number of registers. • timeout specifies how long in tenths of seconds to wait for a response. • 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. • eventNo 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 { MM_SENT = MM_RECEIVED = MM_NO_MESSAGE = MM_BAD_FUNCTION = MM_BAD_SLAVE = MM_BAD_ADDRESS = MM_BAD_LENGTH = MM_PROTOCOL_NOT_SUPPORTED = // additional master command // master messaging only MM_CONNECTING = MM_CONNECTED = MM_CONNECT_TIMEOUT = MM_SEND_ERROR = MM_RSP_TIMEOUT = MM_RSP_ERROR = MM_DISCONNECTING = MM_DISCONNECTED = MM_BAD_CONNECT_ID = MM_BAD_PROTOCOL_TYPE = MM_BAD_IP_ADDRESS = MM_BUSY = MM_ENDED = MM_CONNECT_ERROR = MM_NO_MORE_CONNECTIONS = MM_BAD_CONNECTION_TYPE = MM_EXCEPTION_FUNCTION = MM_EXCEPTION_ADDRESS = MM_EXCEPTION_VALUE = MM_QUEUE_FULL = MM_STATIONS_ARE_EQUAL = 0, 1, 2, 3, 4, 5, 6, 7, status codes used for Modbus IP 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28 } MODBUS_CMD_STATUS; Document (Version 2.22) 10/26/2012 629 Structures and Types • 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 returns 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-3 masterIP function block. It is not available from the mTcpMasterStatus function. • MM_CONNECT_ERROR returns error while connecting to slave IP address. • MM_NO_MORE_CONNECTIONS returns no more connections are available. • MM_BAD_CONNECTION_TYPE returns invalid connection type used in mTcpMasterMessage. Document (Version 2.22) 10/26/2012 630 Structures and Types • 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 needs to be different. ModemInit The ModemInit structure specifies modem initialization parameters for the modemInit function. struct ModemInit { 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 command when it is sent to the modem. Refer to the section Modem Commands for suggested command strings for your modem. ModemSetup 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]; }; • port is the serial port where the modem is connected. • dialAttempts is the number of times the controller will attempt to dial the remote controller before giving up and reporting an error. Document (Version 2.22) 10/26/2012 631 Structures and Types • 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. • pauseTime is the length of time in seconds that the controller will wait between dialing attempts. • dialmethod selects pulse or tone dialing. Set dialmethod to 0 for tone dialing or 1 for pulse dialing. • 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. • phoneNumber is the phone number of the remote controller. The characters ATD and the dialing method will 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; • 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. • masterIdleTimeout 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. • 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. MTCP_IF_SETTINGS The Modbus IP Interface Settings structure defines the interface settings when using any Modbus IP protocol on the specified interface. typedef struct st_MTcpIfSettings Document (Version 2.22) 10/26/2012 632 Structures and Types { UINT16 UCHAR BOOLEAN station; addrMode; sfMessaging; } MTCP_IF_SETTINGS; • 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. • addrMode is the addressing mode, AM_standard or AM_extended. Default value is AM_standard. • 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; • 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. • addrMode is the addressing mode, AM_standard or AM_extended. Default value is AM_standard. • 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. • 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. Document (Version 2.22) 10/26/2012 633 Structures and Types 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; }; • baud is the communication speed. It is one of the BAUDxxx macros. • duplex is either the FULL or HALF macro. • parity is one of NONE, EVEN or ODD macros. • data_bits is the word length. It is either the DATA7 or DATA8 macro. • stop_bits in the number of stop bits transmitted. It is either the STOP1 or STOP2 macro. • flow_rx specifies flow control on the receiver. It is either the RFC_MODBUS_RTU (=ENABLE), RFC_NONE (=DISABLE) or RFC_QUEUED macro macro. If the Modbus RTU protocol is used, set flow_rx to RFC_MODBUS_RTU. For the PPP protocol, set flow_rx to RFC_QUEUED. For the Modbus ASCII protocol or any other protocol, set flow_rx to RFC_NONE. • 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 parameter to TFC_NONE causes the port to use the CTS signal, which is the default setting. • type specifies the serial port type. It is one of RS232 or RS232_MODEM macros. • 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 { /* input values */ float pv; Document (Version 2.22) 10/26/2012 634 Structures and Types 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 errorN1; UINT32 lastTime; } PID_DATA; • pv is the process value • sp is the set point • gain is the gain • reset is the reset time in seconds • rate is the rate time in seconds • deadband is the deadband • fullScale is the full scale output limit • zeroScale is the zero scale output limit • manualOutput is the manual output value • period is the execution period in milliseconds • autoMode is the auto mode flag: TRUE = auto, FALSE = manual • output is the last output value • outOfDeadband is the error is outside the deadband • pvN1 is the process value from n-1 iteration • pvN2 is the process value from n-2 iteration • errorN1 is the error from n-1 iteration • lastTime is the time of last execution Document (Version 2.22) 10/26/2012 635 Structures and Types PPP_LOGIN_TYPE Enumeration The PPP_LOGIN_TYPE enumeration defines the PPP login authentication type. typedef enum pppLogin_t { LOGIN_NONE = 0, LOGIN_PAP, LOGIN_CHAP } PPP_LOGIN_TYPE; • LOGIN_NONE selects no login authentication. • LOGIN_PAP selects Password Authentication Protocol (PAP). • LOGIN_CHAP selects Challenge-Handshake Authentication Protocol (CHAP). PPP_SETTINGS Structure The PPP_SETTINGS structure defines the PPP settings for a serial port. typedef struct st_pppSettings { BOOLEAN serverEnabled; UCHAR ipVersion; UINT32 ipAddress[4]; UINT32 subnetMask; UINT32 remoteIpAddress[4]; BOOLEAN allowRemoteIpRequest UINT16 idleTimeout; PPP_LOGIN_TYPE authentication; BOOLEAN userLogEnabled; BOOLEAN autoRemoteIpAddress; } PPP_SETTINGS; • serverEnabled is the enable PPP server control flag. Set this flag to TRUE to allow auto answer of incoming PPP connections. • ipVersion is the IP version. Only the value 4 is supported for IP version 4. • ipAddress is the IP address assigned to the local controller serial port. Only the first 32-bits are supported. The IP address needs to be different from the LAN port IP address, and different from the IP address of any other serial port configured for PPP protocol. An IP address of 255.255.255.255 is invalid, and any IP address with the high 3 bits set (E0 00 00 00h) is also invalid. All other IP addresses are valid. • subnetMask is the local subnet mask. The default value is 255.255.255.255. • remoteIpAddress is the default IP address that will be assigned to the remote end of the PPP connection, unless the remote requests its own IP address and allowRemoteIpRequest is set to TRUE. Only the first 32-bits are Document (Version 2.22) 10/26/2012 636 Structures and Types supported. An IP address of 255.255.255.255 is invalid. All other IP addresses are valid. Recommended value is local ipAddress + 1. This field is ignored if autoRemoteIpAddress is set to TRUE. • autoRemoteIpAddress. Selects how the remote IP address is assigned to the remote end of the PPP connection. If this flag is set to TRUE, the remote IP address is set to local ipAddress + 1. If this flag is set to FALSE, the remote IP address is set to the value remoteIpAddress. The default value is TRUE. • allowRemoteIpRequest selects whether the remote end of the PPP connection may request its IP address. If this flag is set and the remote does not request its own IP address, then the IP address is assigned to remoteIpAddress. The default value is FALSE. • idleTimeout selects the time in minutes after which the PPP connection will be closed if there has been no activity. Selecting an idleTimeout of 0 disables the idle timeout. The default value is 30 minutes. • authentication selects the type of authentication used for the user login during the PPP connection. Available values are LOGIN_NONE, LOGIN_PAP, or LOGIN_CHAP. The default authentication is LOGIN_CHAP. • userLogEnabled. This setting is currently unavailable. 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 or PPP macros. When the type is set to PPP, the remaining settings in this structure are ignored. 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. Document (Version 2.22) 10/26/2012 637 Structures and Types • 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 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, AB_FULL_BCC, AB_FULL_CRC, AB_HALF_BCC, DNP or AB_HALF_CRC or PPP macros. When the type is set to PPP, the remaining settings in this structure are ignored. 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, 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. prot_settings 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. struct prot_settings { UCHAR type; UCHAR station; UCHAR priority; UINT16 SFMessaging; }; Document (Version 2.22) 10/26/2012 638 Structures and Types • type is the protocol type. It may be one of NO_PROTOCOL, MODBUS_RTU, MODBUS_ASCII, AB_FULL_BCC, AB_HALF_BCC, AB_FULL_CRC, AB_HALF_CRC, DNP or PPP macros. When the type is set to PPP, the remaining settings in this structure are ignored. 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. prot_status The prot_status structure contains protocol status information. struct prot_status { UINT16 command_errors; UINT16 format_errors; UINT16 checksum_errors; UINT16 cmd_received; UINT16 cmd_sent; UINT16 rsp_received; UINT16 rsp_sent; UINT16 command; INT16 task_id; UINT16 stored_messages; UINT16 forwarded_messages; }; • 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. • 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. Document (Version 2.22) 10/26/2012 639 Structures and Types 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. pstatus The pstatus structure contains serial port status information. struct pstatus { UINT16 framing; UINT16 parity; UINT16 c_overrun; UINT16 b_overrun; UINT16 rx_buffer_size; UINT16 rx_buffer_used; UINT16 tx_buffer_size; UINT16 tx_buffer_used; UINT16 io_lines; }; • 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. Document (Version 2.22) 10/26/2012 640 Structures and Types • 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. READSTATUS 2 The READSTATUS enumerated type indicates the status of an I C bus message read and may have one of the following values. enum ReadStatus { RS_success, RS_selectFailed }; typedef enum ReadStatus READSTATUS; • RS_success returns read was successful. • RS_selectFailed returns slave device could not be selected routingTable The routingTable structure type describes an entry in the DNP Routing Table. This structure can 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; 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 4 = serial port com4 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. Document (Version 2.22) 10/26/2012 641 Structures and Types 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; UINT16 slaveStation; COM_INTERFACE forwardInterface; UINT16 forwardStation; IP_ADDRESS forwardIPAddress; } SF_TRANSLATION; // // // // // slave interface type slave station address forwarding interface type forwarding station address forwarding IP address • slaveInterface is the communication interface, which receives the slave command message. Valid interface types are: 1 = com1, 2 = com2, 3 = com3, 4= com4, 100 = Ethernet1. • 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 needs to be different from the station address assigned to the slaveInterface. • 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 needs to be different from the station address assigned to the forwardInterface. • forwardIPAddress 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 slaveInterface; UINT16 slaveStation; COM_INTERFACE forwardInterface; UINT16 forwardStation; IP_ADDRESS forwardIPAddress; UINT16 timeout; } SF_TRANSLATION_EX; Document (Version 2.22) 10/26/2012 // // // // // // slave interface type slave station address forwarding interface type forwarding station address forwarding IP address time-out 642 Structures and Types • slaveInterface is the communication interface which receives the slave command message. Valid interface types are: 1 = com1, 2 = com2, 3 = com3, 4= com4, 100 = Ethernet1. • 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 needs to be different from the station address assigned to the slaveInterface. • 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 needs to be different from the station address assigned to the forwardInterface. • forwardIPAddress is the IP address of the remote slave device to forward a Modbus IP command message to. Set to zero if not applicable. • 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 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; }; • index is the location in the store and forward table to which the status code applies. • code is the status code. It is one of SF_VALID, SF_INDEX_OUT_OF_RANGE, SF_NO_TRANSLATION, SF_PORT_OUT_OF_RANGE, SF_STATION_OUT_OF_RANGE, SF_ALREADY_DEFINED or SF_INVALID_FORWARDING_IP macros. sockaddr_in The sockaddr_in type is a structure containing information about a socket address. struct sockaddr_in { u_char sin_len; u_char sin_family; Document (Version 2.22) 10/26/2012 643 Structures and Types u_short sin_port; struct in_addr sin_addr; char sin_zero[8]; }; • sin_len is length of struct sockaddr_in. It is typically set using: sin_len = sizeof(struct sockaddr_in) • sin_family tells sockets which protocol family to use. For IPv4, the constant AF_INET should always be passed in. • sin_port tells what 16-bit port number will be associated with the socket. • sin_addr is 32-bit IP address that will be associated with the socket. It is an unsigned lomg integer in network byte order. The structure in_addr is defined as: strruct in_addr { u_long s_addr; }; • sin_zero[8] is unused and it should be filled with zeros. TASKINFO 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; • taskID is the identifier of the task. • priority is the execution priority of the task. • status is the current execution status 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. • 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 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 APPLICATION. Document (Version 2.22) 10/26/2012 644 Structures and Types taskInfo_tag The taskInfo_tag structure contains start up task information. struct taskInfo_tag { void *address; UINT16 stack; UINT16 identity; }; • 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) TIME The TIME structure contains time and date for reading or writing the real time clock. struct clock { UINT16 year; UINT16 month; UINT16 day; UINT16 dayofweek; UINT16 hour; UINT16 minute; UINT16 second; UINT16 hundredth; } TIME; • year is the current year. It is two digits in the range 00 to 99. • month is the current month. It is in the range 1 to 12. • day is the current day. It is in the range 1 to 31. • dayofweek is the current day of the week. It is in the range 1 to 7. 1 = Sunday, 2 = Monday…7 = Saturday. • 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 current hundredth of a second. It is in the range 00 to 99. timer_info The timer_info structure contains information about a timer. struct timer_info { UINT16 time; UINT16 interval; Document (Version 2.22) 10/26/2012 645 Structures and Types UINT16 interval_remaining; }; • time is the time remaining in the timer in ticks. • interval is the length of a timer tick in 10ths of a second. • interval_remaining is the time remaining in the interval count down register in 10ths of a second. timeval struct timeval { long tv_sec; long tv_usec; }; /* Number of Seconds */ /* Number of micro seconds */ VERSION The Firmware Version Information Structure holds information about the firmware. typedef struct versionInfo_tag { UINT16 version; UINT16 controller; CHAR date[VI_DATE_SIZE + 1]; CHAR copyright[VI_STRING_SIZE + 1]; } VERSION; • version is the firmware version number. • controller is target controller for the firmware. • date is a string containing the date the firmware was created. • copyright is a string containing Control Microsystems copyright information. WRITESTATUS 2 The WRITESTATUS enumerated type indicates the status of an I C bus message read and may have one of the following values. enum WriteStatus { WS_success, WS_selectFailed, WS_noAcknowledge }; typedef enum WriteStatus WRITESTATUS; • WS_success returns write was successful • WS_selectFailed returns slave could not be selected • WS_noAcknowledge returns slave failed to acknowledge data Document (Version 2.22) 10/26/2012 646 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 <ctools.h> #include <string.h> /* -------------------------------------------The shutdown function aborts any active modem connections when the task is ended. -------------------------------------------- */ void shutdown(void) { modemAbort(com1); } void 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(com1, &portSettings); release_resource(IO_SYSTEM); /* Configure US Robotics modem */ dialSettings.port = com1; dialSettings.dialAttempts = 3; dialSettings.detectTime = 60; dialSettings.pauseTime = 30; dialSettings.dialmethod = 0; strcpy(dialSettings.modemCommand, "&F1 &A0 &K0 &M0 &B1"); strcpy(dialSettings.phoneNumber, "555-1212"); Document (Version 2.22) 10/26/2012 647 Example Programs /* set up exit handler for this task */ getTaskInfo(0, &taskStatus); installExitHandler(taskStatus.taskID, shutdown); /* Connect to the remote controller */ if (modemDial(&dialSettings, &portID) == DE_NoError) { do { /* Allow other tasks to execute */ release_processor(); /* Wait for initialization to complete */ modemDialStatus(com1, portID, &status, &state); } while (state == DS_Calling); /* If the remote controller connected */ if (state == DS_Connected) { /* Talk to remote controller here */ } /* Terminate the connection */ modemDialEnd(com1, portID, &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. Document (Version 2.22) 10/26/2012 648 Example Programs Create Task Example #include <ctools.h> #define TIME_TO_PRINT 20 void task1(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); /* Allow other tasks to execute */ release_processor(); } } void task2(void) { while(TRUE) { /* body of task 2 loop - event handler */ wait_event(TIME_TO_PRINT); printf("It’s time for a coffee break\r\n"); } } /* -------------------------------------------The shutdown function stops the signalling of TIME_TO_PRINT events when application is stopped. -------------------------------------------- */ void shutdown(void) { endTimedEvent(TIME_TO_PRINT); } void main(void) { TASKINFO taskStatus; /* continuos processing task at priority 1 */ create_task(task1, 1, APPLICATION, 2); /* event handler needs larger stack for printf function */ create_task(task2, 3, APPLICATION, 4); /* set up task exit handler to stop Document (Version 2.22) 10/26/2012 649 Example Programs signalling of events when this task ends */ getTaskInfo(0, &taskStatus); installExitHandler(taskStatus.taskID, shutdown); /* start timed event to occur every 10 sec */ startTimedEvent(TIME_TO_PRINT, 100); interval(0, 10); while(TRUE) { /* body of main task loop */ /* other processing code */ /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 650 Example Programs DNP Configuration Example /* ------------------------------------------------------------------SCADAPack 32 C++ Application Main Program Copyright 2001 - 2003, Control Microsystems Inc. The following program demonstrates how to configure DNP for operation on com4 of the SCDAPack 32. ------------------------------------------------------------------ */ #include <ctools.h> /* ------------------------------------------------------------------C++ Function Prototypes ------------------------------------------------------------------ */ // add prototypes here /* ------------------------------------------------------------------C Function Prototypes ------------------------------------------------------------------ */ extern "C" { // add prototypes here } /* ------------------------------------------------------------------main This routine is the main application loop. ------------------------------------------------------------------ */ void main(void) { //-----------------------------------------------------------------// Variable declaration //-----------------------------------------------------------------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 Document (Version 2.22) 10/26/2012 651 Example Programs dnpAnalogOutput analogOutput; // analog output settings dnpCounterInput counterInput; // conter input settings //-----------------------------------------------------------------// Stop any protocol currently active on com port 4 //-----------------------------------------------------------------get_protocol(com4, &protocolSettings); protocolSettings.type = NO_PROTOCOL; set_protocol(com4, &protocolSettings); //-----------------------------------------------------------------// Load DNP Configuration Parameters //-----------------------------------------------------------------configuration.masterAddress = 100; configuration.rtuAddress = 1; configuration.datalinkConfirm = FALSE; configuration.datalinkRetries = DEFAULT_DLINK_RETRIES; configuration.datalinkTimeout = DEFAULT_DLINK_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 = 1701; configuration.BI_startAddress = 0; configuration.BI_reportingMethod = REPORT_ALL_EVENTS; configuration.BI_soeBufferSize = 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; configuration.CI32_bufferSize = 0; configuration.CI32_wordOrder = MSW_FIRST; configuration.AI16_number = 751; 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 2.22) 10/26/2012 652 Example Programs configuration.AO16_number = 20; configuration.AO16_startAddress = 0; configuration.AO32_number = 12; configuration.AO32_startAddress = 100; configuration.AO32_wordOrder = MSW_FIRST; configuration.AOSF_number = 0; configuration.AOSF_startAddress = 200; configuration.AOSF_wordOrder = MSW_FIRST; configuration.autoUnsolicitedClass1 = TRUE; configuration.holdTimeClass1 = 10; configuration.holdCountClass1 = 3; configuration.autoUnsolicitedClass2 = TRUE; configuration.holdTimeClass2 = 10; configuration.holdCountClass2 = 3; configuration.autoUnsolicitedClass3 = TRUE; configuration.holdTimeClass3 = 10; configuration.holdCountClass3 = 3; configuration.enableUnsolicitedOnStartup = TRUE; configuration.sendUnsolicitedOnStartup = FALSE; configuration.level2Compliance = FALSE; //-----------------------------------------------------------------// Set DNP Configuration //-----------------------------------------------------------------dnpSaveConfiguration(&configuration); //------------------------------------------------------------// Start DNP protocol on com port 4 //------------------------------------------------------------get_protocol(com4, &protocolSettings); protocolSettings.type = DNP; set_protocol(com4, &protocolSettings); //------------------------------------------------------------// Configure Binary Output Points //------------------------------------------------------------for (index = 0; index < configuration.BO_number; index++) { binaryOutput.modbusAddress1 = 1 + index; binaryOutput.modbusAddress2 = 1 + index; binaryOutput.controlType = NOT_PAIRED; dnpSaveBOConfig(configuration.BO_startAddress + index, &binaryOutput); } //------------------------------------------------------------// Configure Binary Input Points //------------------------------------------------------------for (index = 0; index < configuration.BI_number; index++) { binaryInput.modbusAddress = 10001 + index; binaryInput.eventClass = CLASS_1; Document (Version 2.22) 10/26/2012 653 Example Programs dnpSaveBIConfig(configuration.BI_startAddress + index, &binaryInput); } //------------------------------------------------------------// Configure 16 Bit Analog Input Points //------------------------------------------------------------for (index = 0; index < configuration.AI16_number; index++) { analogInput.modbusAddress = 30001 + index; analogInput.eventClass = CLASS_2; analogInput.deadband = 1; dnpSaveAI16Config(configuration.AI16_startAddress + index, &analogInput); } //------------------------------------------------------------// Configure 32 Bit Analog Input Points //------------------------------------------------------------for (index = 0; index < configuration.AI32_number; index++) { analogInput.modbusAddress = 30001 + index; analogInput.eventClass = CLASS_2; analogInput.deadband = 1; dnpSaveAI32Config(configuration.AI16_startAddress + index, &analogInput); } //------------------------------------------------------------// Configure 16 Bit Analog Output Points //------------------------------------------------------------for (index = 0; index < configuration.AO16_number; index++) { analogOutput.modbusAddress = 40001 + index; dnpSaveAO16Config(configuration.AO16_startAddress + index, &analogOutput); } //------------------------------------------------------------// Configure 32 Bit Analog Output Points //------------------------------------------------------------for (index = 0; index < configuration.AO32_number; index++) { analogOutput.modbusAddress = 41001 + index * 2; dnpSaveAO32Config(configuration.AO32_startAddress + index, &analogOutput); } //------------------------------------------------------------// Configure 16 Bit Counter Input Points //------------------------------------------------------------- Document (Version 2.22) 10/26/2012 654 Example Programs for (index = 0; index < configuration.CI16_number; index++) { counterInput.modbusAddress = 30001 + index; counterInput.eventClass = CLASS_3; counterInput.threshold = 1; dnpSaveCI16Config(configuration.CI16_startAddress + index, &counterInput); } //------------------------------------------------------------// Configure 32 Bit Counter Input Points //------------------------------------------------------------for (index = 0; index < configuration.CI32_number; index++) { counterInput.modbusAddress = 30001 + index * 2; counterInput.eventClass = CLASS_3; counterInput.threshold = 1; dnpSaveCI32Config(configuration.CI32_startAddress + index, &counterInput); } // main loop while (TRUE) { // add remainder of program here // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 655 Example Programs Get Program Status Example 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 <ctools.h> #define HI_ALARM 41000 #define ALARM_OUTPUT 1026 #define SCAN_EVENT 0 void main( void ) { if (getProgramStatus() == 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(PROGRAM_EXECUTED); } while (TRUE) { INT16 ain[8]; // analog input module data /* Scan ain module */ ioRequest(MT_Ain8, 0); ioNotification(SCAN_EVENT); wait_event(SCAN_EVENT); ioReadAin8(0, ain); /* Test input against alarm limits */ request_resource(IO_SYSTEM); if (ain[0] > dbase(MODBUS, HI_ALARM)) { setdbase(MODBUS, ALARM_OUTPUT, 1); } else { setdbase(MODBUS, ALARM_OUTPUT, 0); } release_resource(IO_SYSTEM); /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 656 Example Programs Get Task Status Example The following program displays information about all valid tasks. The maximum task ID in the system is 64. void main(void) { PROTOCOL_SETTINGS settings; if (getProtocolSettings(com1, &settings) { printf("Type: %d\r\n", settings.type); printf("Station: %d\r\n", settings.station); printf("Address Mode: %d\r\n", settings.mode); printf("SF Messaging: %d\r\n", settings.SFMessaging); printf("Priority: %d\r\n", settings.priority); } else { printf(“Serial port is not valid\r\n”); } } #include <string.h> #include <ctools.h> void main(void) { struct prot_settings settings; TASKINFO taskStatus; unsigned task; char state[6][20]; char type[2][20]; /* Set up state strings */ strcpy(state[TS_READY], "Ready"); strcpy(state[TS_EXECUTING], "Executing"); strcpy(state[TS_WAIT_EVENT], "Waiting for Event"); /* Set up type strings */ strcpy(type[APPLICATION], "Application"); strcpy(type[SYSTEM], "System"); strcpy(state[TS_WAIT_ENVELOPE], "Waiting for Envelope"); strcpy(state[TS_WAIT_MESSAGE], "Waiting for Message"); strcpy(state[TS_WAIT_RESOURCE], "Waiting for Resource"); /* Disable the protocol on serial port 1 */ settings.type = NO_PROTOCOL; settings.station = 1; settings.priority = 3; settings.SFMessaging = FALSE; request_resource(IO_SYSTEM); set_protocol(com1, &settings); release_resource(IO_SYSTEM); /* display information about all tasks */ Document (Version 2.22) 10/26/2012 657 Example Programs for (task = 0; task <= 64; task++) { if (getTaskInfo(task, &taskStatus)) { /* show information for valid task */ fprintf(com1, "\r\n\r\nInformation about task %d:\r\n", task); fprintf(com1, " Task ID: %d\r\n", taskStatus.taskID); fprintf(com1, " Priority: %d\r\n", taskStatus.priority); fprintf(com1, " Status: %s\r\n", tate[taskStatus.status]); if (taskStatus.status == TS_WAIT_EVENT) { fprintf(com1, " Event: %d\r\n", taskStatus.requirement); } if (taskStatus.status == TS_WAIT_RESOURCE) { fprintf(com1, " Resource: %d\r\n", taskStatus.requirement); } fprintf(com1, " Error: %d\r\n", taskStatus.error); fprintf(com1, " Type: %s\r\n", type[taskStatus.type]); } } while (TRUE) { /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 658 Example Programs Handler Function Example /* ----------------------------------------------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 Where; 01 is the station address 47 is the function code in hex 01 is the command for the function code B7 is the message checksum :014701B7 To turn off digital output 00001: From a terminal send the ASCII command :014700B8 Where; 01 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 <ctools.h> static unsigned myModbusHandler( UCHAR * message, UINT16 messageLength, UCHAR * response, UINT16 * responseLength ) { UCHAR * pMessage; UCHAR * pResponse; pMessage = message; if (*pMessage == 71) { /* Action for command data */ pMessage++; if (*pMessage == 0) { request_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 659 Example Programs setdbase(MODBUS, 1, 0); release_resource(IO_SYSTEM); pResponse = response; *pResponse pResponse++; *pResponse pResponse++; *pResponse pResponse++; *pResponse pResponse++; = 71; = 'O'; = 'F'; = 'F'; *responseLength = 4; return NORMAL; } if (*pMessage == 1) { request_resource(IO_SYSTEM); setdbase(MODBUS, 1, 1); release_resource(IO_SYSTEM); pResponse = response; *pResponse = 71; pResponse++; *pResponse = 'O'; pResponse++; *pResponse = 'N'; pResponse++; *responseLength = 3; return NORMAL; } } } static void shutdown(void) { installModbusHandler(NULL); } /* ----------------------------------------------main This routine is the modbus slave application. Serial port com2 is configured for Modbus ASCII Register Assignment is configured. The modbus handler is installed. The exit handler is installed. -------------------------------------------- */ void main(void) { Document (Version 2.22) 10/26/2012 protocol. 660 Example Programs 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, &portSettings); get_protocol(com2, &protSettings); protSettings.station = 1; protSettings.type = MODBUS_ASCII; set_protocol(com2, &protSettings); /* Configure Register Assignment */ clearRegAssignment(); addRegAssignment(DIN_generic8, 0, 10017, 0, 0, 0); addRegAssignment(SCADAPack 32_lowerIO,0, 1, 10001, 30001, 0); addRegAssignment(DIAG_protocolStatus,1,31000, 0, 0, 0); /* Install Modbus Handler */ request_resource(IO_SYSTEM); installModbusHandler(myModbusHandler); release_resource(IO_SYSTEM); /* Install Exit Handler */ getTaskInfo(0, &taskStatus); installExitHandler(taskStatus.taskID, shutdown); while(TRUE) { release_processor(); } } Document (Version 2.22) 10/26/2012 661 Example Programs Install Serial Port Handler Example #include <ctools.h> #define CHAR_RECEIVED 11 /* -------------------------------------------signal This routine signals an event when a character is received on com1. If there is an error, the character is ignored. -------------------------------------------- */ void signal(UINT16 character, UINT16 error) { if (error == 0) interrupt_signal_event( CHAR_RECEIVED ); character; } /* -------------------------------------------main This program displays all characters received on com1 using an installed handler to signal the reception of a character. -------------------------------------------- */ void main(void) { struct pconfig portSettings; struct prot_settings protocolSettings; int character; /* Disable RX flow control */ get_port(com1, &portSettings); portSettings.flow_rx = RFC_NONE; request_resource(IO_SYSTEM); set_port(com1, &portSettings); release_resource(IO_SYSTEM); /* Disable protocol */ get_protocol(com1, &protocolSettings); protocolSettings.type = NO_PROTOCOL; request_resource(IO_SYSTEM); set_protocol(com1, &protocolSettings); release_resource(IO_SYSTEM); /* Enable character handler */ install_handler(com1, signal); Document (Version 2.22) 10/26/2012 662 Example Programs /* Print each character as it is received */ while (TRUE) { wait_event(CHAR_RECEIVED); character = fgetc(com1); if (character == EOF) { // clear overflow error flag to re-enable com1 clearerr(com1); } fputs("character: ", com1); fputc(character, com1); fputs("\r\n", com1); } } Document (Version 2.22) 10/26/2012 663 Example Programs Install Clock Handler Example /* -------------------------------------------This program demonstrates how to call a function at a specific time of day. -------------------------------------------- */ #include <ctools.h> #define ALARM_EVENT 20 /* -------------------------------------------This function signals an event when the alarm occurs. -------------------------------------------- */ 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(); release_resource(IO_SYSTEM); fprintf(com1, "It’s quitting time!\r\n"); } } void 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 = 3; settings.SFMessaging = FALSE; request_resource(IO_SYSTEM); set_protocol(com1, &settings); release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 664 Example Programs /* Install clock handler function */ installClockHandler(alarmHandler); /* Create task for processing alarm events */ create_task(processAlarms, 3, APPLICATION, 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) { /* body of main task loop */ /* other processing code */ /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 665 Example Programs Install Database Handler Example /* ------------------------------------------------------------This is a sample IEC 61131-3 application for the installDbaseHandler and installSetdbaseHandler functions. This sample program demonstrates database handlers for the Modbus registers: 1001 11001 31001 41001 to 1100 to 11100 to 31100 to 41100 This database is allocated in non-volatile memory. 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-3 variable. Note that these database access functions are used by C++ applications and by all protocols. ------------------------------------------------------------ */ #include <ctools.h> #include <string.h> // place these variables in SRAM section named BnonVolatile #pragma section nonVolatile // pointer to allocated non-volatile memory void * pAllocatedMem; // use the default section names (P, B, C, D, and R) #pragma section #define SAMPLE_SIZE #define SCAN_EVENT_NO 100 0 // custom Modbus database structure struct myDatabase { BOOLEAN coilDbase[SAMPLE_SIZE]; BOOLEAN statusDbase[SAMPLE_SIZE]; INT16 inputDbase[SAMPLE_SIZE]; INT16 holdingDbase[SAMPLE_SIZE]; }; #define MEM_SIZE (sizeof(struct myDatabase)) /* -----------------------------------------------------------This is the dbase handler. ------------------------------------------------------------ */ static BOOLEAN dbaseHandler( UINT16 address, /* Modbus register address */ INT16 *value /* pointer to value at address */ ) Document (Version 2.22) 10/26/2012 666 Example Programs { struct myDatabase * pMyDatabase; // pointer to custom database pMyDatabase = (struct myDatabase *) pAllocatedMem; if (pMyDatabase == NULL) { // database could not be allocated return FALSE; } if ((address > 1000) && (address <= 1000 + SAMPLE_SIZE)) { *value = pMyDatabase->coilDbase[address - 1001]; return TRUE; } else if ((address > 11000)&&(address <= 11000 + SAMPLE_SIZE)) { *value = pMyDatabase->statusDbase[address - 11001]; return TRUE; } else if ((address > 31000)&&(address <= 31000 + SAMPLE_SIZE)) { *value = pMyDatabase->inputDbase[address - 31001]; return TRUE; } else if ((address > 41000)&&(address <= 41000 + SAMPLE_SIZE)) { *value = pMyDatabase->holdingDbase[address - 41001]; return TRUE; } else { /* all other addresses are not handled */ return FALSE; } } /* -----------------------------------------------------------This is the setdbase handler. ------------------------------------------------------------ */ static BOOLEAN setdbaseHandler( UINT16 address, /* Modbus register address */ INT16 value /* value to write at address */ ) { struct myDatabase * pMyDatabase; // pointer to custom database pMyDatabase = (struct myDatabase *) pAllocatedMem; if (pMyDatabase == NULL) { // database could not be allocated return FALSE; } if ((address > 1000) && (address <= 1000 + SAMPLE_SIZE)) { Document (Version 2.22) 10/26/2012 667 Example Programs if (value == 0) { pMyDatabase->coilDbase[address - 1001] = FALSE; } else { pMyDatabase->coilDbase[address - 1001] = TRUE; } return TRUE; } else if ((address > 11000) && (address <= 11000 + SAMPLE_SIZE)) { if (value == 0) { pMyDatabase->statusDbase[address - 11001] = FALSE; } else { pMyDatabase->statusDbase[address - 11001] = TRUE; } return TRUE; } else if ((address > 31000)&&(address <= 31000 + SAMPLE_SIZE)) { pMyDatabase->inputDbase[address - 31001] = value; return TRUE; } else if ((address > 41000)&&(address <= 41000 + SAMPLE_SIZE)) { pMyDatabase->holdingDbase[address - 41001] = value; return TRUE; } else { /* all other addresses are not handled */ return FALSE; } } /* -----------------------------------------------------------This is the exit handler. ------------------------------------------------------------ */ static void shutdown(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) Document (Version 2.22) 10/26/2012 668 Example Programs { TASKINFO taskStatus; BOOLEAN status; if (getProgramStatus() == NEW_PROGRAM) { // Application has just been downloaded. Any memory // previously allocated has been freed automatically. // Allocate non-volatile dynamic memory. request_resource(DYNAMIC_MEMORY); status = allocateMemory((void **)&pAllocatedMem, MEM_SIZE); release_resource(DYNAMIC_MEMORY); if (status == TRUE) { // set program status so memory is not re-allocated // until next program download setProgramStatus(PROGRAM_EXECUTED); // zero-fill new custom database memset(pAllocatedMem, 0, MEM_SIZE); } else { // memory could not be allocated pAllocatedMem = NULL; } } // install exit handler to remove the custom database // if the application is stopped or erased getTaskInfo(0, &taskStatus); installExitHandler(taskStatus.taskID, shutdown); // 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. ------------------------------------------------------------ */ void 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) { Document (Version 2.22) 10/26/2012 669 Example Programs // write data to Output tables ioWrite5601Outputs(doutData); // add I/O requests to the I/O System queue ioRequest(MT_5601Inputs, 0); ioRequest(MT_5601Outputs, 0); // this event signals completion of preceding i/o requests ioNotification(SCAN_EVENT_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<8; index++) { setdbase(MODBUS, 31001 + index, ainData[index]); } // copy Din data to the for (index=0; index<16; { if (dinData & 0x01) { setdbase(MODBUS, } else { setdbase(MODBUS, } dinData >>= 1; } database index++) 11001 + index, 1); 11001 + index, 0); // get 12 DOUT points from the database for (index=0; index<12; index++) { doutData <<= 1; if (dbase(MODBUS, 1012 - index)) { doutData |= 1; } } release_resource(IO_SYSTEM); // release processor to other priority 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 670 Example Programs 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 locating the section BnonVolatile used in this example. #include <ctools.h> // place these variables in SRAM section named BnonVolatile #pragma section nonVolatile // pointer to allocated non-volatile memory void * pAllocatedMem; // use the default section names (P, B, C, D, and R) #pragma section struct myTable { UINT32 data[100]; }; #define MEM_SIZE (sizeof(struct myTable)) void main( void ) { BOOLEAN status; struct myTable * pTable; status = TRUE; if (getProgramStatus() == NEW_PROGRAM) { // Application has just been downloaded. request_resource(DYNAMIC_MEMORY); status = allocateMemory((void **)&pAllocatedMem, MEM_SIZE); release_resource(DYNAMIC_MEMORY); if (status == TRUE) { // set program status so memory is not re-allocated // until application is downloaded again setProgramStatus(PROGRAM_EXECUTED); } } // use non-volatile memory for table structure pTable = (struct myTable *) pAllocatedMem; while (TRUE) { if (status == TRUE) { // pTable is used in remainder of program // ... Document (Version 2.22) 10/26/2012 671 Example Programs } else { // print error message } // Allow other tasks to execute release_processor(); } } Document (Version 2.22) 10/26/2012 672 Example Programs 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. -------------------------------------------- */ #include <ctools.h> /* -------------------------------------------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. -------------------------------------------- */ void wait_for_response(FILE *stream, unsigned time) { struct prot_status status; static unsigned long good, bad; interval(0, 1); settimer(0, time); do { /* Allow other tasks to execute */ release_processor(); status = get_protocol_status(stream); } while (timer(0) && status.command == MM_SENT); if (status.command == MM_RECEIVED) good++; else bad++; fprintf(com1, "Good: %8lu Bad: %8lu\r", good, bad); } /* -------------------------------------------main The main function sets up serial ports then sends commands to a Modbus slave. -------------------------------------------- */ void main(void) { struct prot_settings settings; Document (Version 2.22) 10/26/2012 673 Example Programs struct pconfig portset; request_resource(IO_SYSTEM); /* disable protocol on serial port 1 */ settings.type = NO_PROTOCOL; settings.station = 1; settings.priority = 3; settings.SFMessaging = FALSE; set_protocol(com1, &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 = RFC_NONE; portset.flow_tx = TFC_NONE; portset.type = RS232; portset.timeout = 600; set_port(com1, &portset); /* enable Modbus protocol on serial port 2 */ settings.type = MODBUS_ASCII; settings.station = 2; settings.priority = 3; settings.SFMessaging = FALSE; set_protocol(com2, &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.type = RS485_4WIRE; portset.timeout = 600; set_port(com2, &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, 17, 8); release_resource(IO_SYSTEM); wait_for_response(com2, 10); Document (Version 2.22) 10/26/2012 674 Example Programs /* Transfer inputs to slave outputs */ request_resource(IO_SYSTEM); master_message(com2, 15, 1, 1, 10009, 8); release_resource(IO_SYSTEM); wait_for_response(com2, 10); /* Allow other tasks to execute */ release_processor(); } } Document (Version 2.22) 10/26/2012 675 Example Programs Master Message Example Using DF1 Protocol Full Duplex Using the same example program above for the Modbus protocol, apply the following calling format for the master_message function. This code fragment uses the protected write command (function=0) to transmit 13 (length=13) 16-bit registers to slave station 10 (slave=10). The data will be read from registers 127 to 139 (master_address=127), and stored into registers 180 to 192 (address=180) in the slave station. The command will be transmitted on com2 (stream=com2). master_message(com2, 0, 10, 180, 127, 13); This code fragment uses the unprotected read command (function=1) to read 74 (length=74) 16-bit registers from slave station 37 (slave=37). The data will be read from registers 300 to 373 in the slave (address=300), and stored in registers 400 to 473 in the master (master_address=400). The command will be transmitted on com2 (stream=com2). master_message(com2, 1, 37, 300, 400, 74); This code fragment will send specific bits from a single 16-bit register in the master to slave station 33. The unprotected bit write command (function=5) will be used. Bits 0,1,7,12 and 15 of register 100 (master_address=100) will be sent to register 1432 (address=1432) in the slave. The length parameter is used as a bit mask and is evaluated as follows: bitmask = 1001 0000 1000 0011 in binary = 9083 in hexadecimal = 36,995 in decimal Therefore the command, sent on com2, is: master_message(com2, 5, 33, 1432, 100, 36995); Half Duplex The example program is the same as for Full Duplex except that instead of waiting for a response after calling master_message, the slave must be polled for a response. Add the following function poll_for_response to the example program above and call it instead of wait_for_response: /* -------------------------------------------poll_for_response The poll_for_response function polls the specified slave for a response to a master message sent on the serial port specified by Document (Version 2.22) 10/26/2012 676 Example Programs stream. It returns when the correct response is received, or when the period specified by time (in tenths of a second) expires. -------------------------------------------- */ void poll_for_response(FILE *stream, unsigned slave, unsigned time) { struct prot_status status; unsigned done; static unsigned long good, bad; /* set timeout timer */ interval( 0, 10 ); settimer( 0, time ); do { /* wait until command status changes or timer expires */ do { status = get_protocol_status( stream ); release_processor(); } while(timer(0)&& (status.command==MM_SENT)); /* command has been ACKed, send poll */ if (status.command == MM_CMD_ACKED) { pollABSlave(stream, slave); done = FALSE; } /* response/command mismatch, poll again */ else if (status.command == MM_WRONG_RSP) { pollABSlave(stream, slave); done = FALSE; } /* correct response was received */ else if (status.command == MM_RECEIVED) { good++; done = TRUE; } /* timer has expired or status is MM_EOT */ else { bad++; done = TRUE; } } while (!done); fprintf(com1, "Good: %8lu bad); Document (Version 2.22) 10/26/2012 Bad: %8lu\r", good, 677 Example Programs } Document (Version 2.22) 10/26/2012 678 Example Programs Master Message Example Using serialModbusMaster This program sends master messages on com2 demonstrating two methods using the function serialModbusMaster. /* -------------------------------------------SCADAPack 32 C++ Application Main Program Copyright 2001 - 2003, Control Microsystems Inc. -------------------------------------------- */ #include <ctools.h> // function prototypes static void master2(void); /* -------------------------------------------Modular variables -------------------------------------------- */ // declare session as modular to reduce stack space usage static MODBUS_SESSION masterSession1; static MODBUS_SESSION masterSession2; /* -------------------------------------------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. -------------------------------------------- */ void main(void) { Document (Version 2.22) 10/26/2012 679 Example Programs 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 = 3; settings.SFMessaging = FALSE; set_protocol(com2, &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, &portset); release_resource(IO_SYSTEM); // start second polling task example create_task(master2, 1, APPLICATION, 4); // define master message to read slave Document (Version 2.22) 10/26/2012 680 Example Programs // analog inputs message.stream = com2; message.function message.slaveStation = 4; = 2; message.slaveRegister = 30001; message.masterRegister = 40001; message.length = 8; message.timeout = 30; message.eventRequest = FALSE; message.eventNo = 0; // main communication loop while (TRUE) { // send a new command request_resource(IO_SYSTEM); status = serialModbusMaster(&message, &masterSession1); release_resource(IO_SYSTEM); if(status) { // wait for response or timeout while(masterSession1.masterCmdStatus == MM_SENT) { // do other things here... // allow other tasks to execute while waiting release_processor(); } if(masterSession1.masterCmdStatus == MM_RECEIVED) { Document (Version 2.22) 10/26/2012 681 Example Programs good++; } else { bad++; } } // allow other tasks to execute release_processor(); } } /* -------------------------------------------master2 This task sends commands to a Modbus slave using the same serial port as main(). Use a different MODBUS_SESSION structure when sharing a serial port with another master. This task uses the event request option. The task waits for the completion event to free up the processor for other tasks. -------------------------------------------- */ static void master2(void) { MASTER_MESSAGE message; BOOLEAN status; UINT16 good, bad; // define master message to copy slave // digital inputs to master outputs Document (Version 2.22) 10/26/2012 682 Example Programs message.stream = com2; message.function message.slaveStation = 2; = 2; message.slaveRegister = 10001; message.masterRegister = 1; message.length = 8; message.timeout = 30; message.eventRequest = TRUE; message.eventNo = 1; // main communication loop while (TRUE) { // send a new command request_resource(IO_SYSTEM); status = serialModbusMaster(&message, &masterSession2); release_resource(IO_SYSTEM); if(status) { // wait for completion event when response or // timeout has occurred wait_event(1); if(masterSession2.masterCmdStatus == MM_RECEIVED) { good++; } else { bad++; } Document (Version 2.22) 10/26/2012 683 Example Programs } // allow other tasks to execute release_processor(); } } Document (Version 2.22) 10/26/2012 684 Example Programs Master Message Example Using mTcpMasterMessage This program sends master messages on the LAN interface using Modbus/TCP protocol. /* -------------------------------------------SCADAPack 32 C++ Application Main Program Copyright 2001 - 2004, Control Microsystems Inc. -------------------------------------------- */ #include <ctools.h> // 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; /* -------------------------------------------main This routine is the main application loop. -------------------------------------------- */ void main(void) { MIP_MODE mode; IP_SETTINGS ipSettings; IP_ADDRESS remoteIP; IP_PROTOCOL_TYPE protocolType; CONNECTION_TYPE appType; UINT16 timeout; UINT32 connectID; MODBUS_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(&ipSettings); // master IP command definition remoteIP.s_addr = inet_addr("172.16.3.8"); // destination IP address Document (Version 2.22) 10/26/2012 685 Example Programs protocolType appType timeout seconds function holding registers slaveStation slaveRegister masterRegister length = IPP_ModbusTcp; = CT_MasterCApp; = 30; // tenths of = 3; // read = = = = 1; 40155; 40001; 2; // main loop mode = MIP_OPEN_CONNECTION; while (TRUE) { switch(mode) { case MIP_OPEN_CONNECTION: { // open a connection status = mTcpMasterOpen( remoteIP, protocolType, appType, timeout, &connectID, &cmdStatus ); if (status) { mode = MIP_CONNECTING; } } break; case MIP_CONNECTING: { // check master command status status = mTcpMasterStatus(connectID, &cmdStatus); if (status) { switch (cmdStatus) { case MM_CONNECTING: break; case MM_CONNECTED: mode = MIP_SEND_MESSAGE; break; default: // remaining status codes are error codes mode = MIP_DISCONNECT; break; } } } break; Document (Version 2.22) 10/26/2012 686 Example Programs case MIP_SEND_MESSAGE: { // send master IP message cmdStatus = mTcpMasterMessage( connectID, remoteIP, protocolType, function, slaveStation, slaveRegister, masterRegister, length, timeout ); switch (cmdStatus) { case MM_CONNECTING: case MM_DISCONNECTING: case MM_DISCONNECTED: // last command is still being sent; // not ready for new message break; case MM_SENT: // message send started successfully mode = MIP_WAIT_FOR_RESPONSE; break; default: // remaining status codes are error codes // message not sent mode = MIP_DISCONNECT; break; } } break; case MIP_WAIT_FOR_RESPONSE: { // check master command status status = mTcpMasterStatus(connectID, &cmdStatus); if (status) { switch (cmdStatus) { case MM_SENT: // still waiting for response break; case MM_RECEIVED: // response received successfully; send next message mode = MIP_SEND_MESSAGE; break; default: // remaining status codes are error codes mode = MIP_DISCONNECT; Document (Version 2.22) 10/26/2012 687 Example Programs 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 1 tasks release_processor(); } } Document (Version 2.22) 10/26/2012 688 Example Programs 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 <ctools.h> #include <string.h> void main(void) { struct ModemInit initSettings; reserve_id portID; enum DialError status; enum DialState state; struct pconfig portSettings; /* Configure serial port 1 */ 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(com1, &portSettings); release_resource(IO_SYSTEM); /* Initialize Hayes modem to answer incoming calls */ initSettings.port = com1; strcpy(initSettings.modemCommand, " F1Q0V1X1 S0=1"); if (modemInit(&initSettings, &portID) == DE_NoError) { do { /* Allow other tasks to execute */ release_processor(); /* Wait for the initialization to complete */ modemInitStatus(com1, portID, &status, &state); } while (state == DS_Calling); /* Terminate the initialization */ modemInitEnd(com1, portID, &status); } } Document (Version 2.22) 10/26/2012 689 Example Programs Real Time Clock Program Example The following program illustrates how the date and time can be set and displayed. All fields of the clock structure needs to be set with valid values for the clock to operate properly. #include <ctools.h> void main(void) { TIME now; /* Set to 12:01:00 on January 1, 1994 */ now.hour now.minute now.second now.day now.month now.year now.dayofweek = = = = = = = 12; 1; 0; 1; 1; 94; 6; /* set the time */ /* set the date */ /* day is Sat. */ request_resource(IO_SYSTEM); setclock(&now); getclock(&now); /* read the clock */ release_resource(IO_SYSTEM); /* Display current hour, minute and second */ printf("%2d/%2d/%2d", now.day, now.month, now.year); printf("%2d:%2d\r\n",now.hour, now.minute); } Document (Version 2.22) 10/26/2012 690 Example Programs Start Timed Event Example This program prints the time every 10 seconds. #include <string.h> #include <ctools.h> #define TIME_TO_PRINT 15 /* -------------------------------------------The shutdown function stops the signalling of TIME_TO_PRINT events. -------------------------------------------- */ void shutdown(void) { endTimedEvent(TIME_TO_PRINT); } /* -------------------------------------------The main function sets up signalling of a timed event, then waits for that event. The time is printed each time the event occurs. -------------------------------------------- */ void 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 = 3; settings.SFMessaging = FALSE; request_resource(IO_SYSTEM); set_protocol(com1, &settings); release_resource(IO_SYSTEM); /* set up task exit handler to stop signalling of events when this task ends */ getTaskInfo(0, &taskStatus); installExitHandler(taskStatus.taskID, shutdown); /* start timed event */ startTimedEvent(TIME_TO_PRINT, 100); while (TRUE) { wait_event(TIME_TO_PRINT); request_resource(IO_SYSTEM); getclock(&now); release_resource(IO_SYSTEM); fprintf(com1, "Time %02u:%02u:%02u\r\n", now.hour, now.minute, now.second); Document (Version 2.22) 10/26/2012 691 Example Programs } } Document (Version 2.22) 10/26/2012 692 Example Programs Timer Example Programs Example 1: Turn on a digital output assigned to coil register 1 and wait 5 seconds before turning it off. runTimers(TRUE); interval(0,10); /* timer 0 tick rate = 1 second */ request_resource(IO_SYSTEM); setdbase(MODBUS, 1, 1); /* turn on output */ release_resource(IO_SYSTEM); settimer(0,5); /* load timer 0 with 5 seconds */ while(timer(0)) /* wait until time expires */ { /* Allow other tasks to execute */ release_processor(); } request_resource(IO_SYSTEM); setdbase(MODBUS, 1, 0); /* shut off output */ release_resource(IO_SYSTEM); Example 2: Time the duration a contact is on but wait in loop to measure time. Contact is assigned to status register 10001. interval(0,1); /* tick rate = 0.1 second */ request_resource(IO_SYSTEM); if (dbase(MODBUS, 10001)) /* test if contact is on */ { settimer(0,63000); /* start timer */ while(dbase(MODBUS, 10001)) /* wait for turn off */ { /* Allow other tasks to execute */ release_resource(IO_SYSTEM); release_processor(); request_resource(IO_SYSTEM); } printf("time period = %u\r\n",63000-timer(0)); } release_resource(IO_SYSTEM); Example 3: Open valve to fill tank and print alarm message if not full in 1 minute. Contact is assigned to status register 10001. Valve is controlled by coil register 1. interval(0,10); /* timer 0 tick rate = 1 second */ request_resource(IO_SYSTEM); setdbase(MODBUS, 1, 1); /* open valve */ settimer(0,60); /* set timer for 1 minute */ /* tank not full if contact is off */ while((dbase(MODBUS, 10001)== 0) && timer(0)) { /* Allow other tasks to execute */ release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 693 Example Programs release_processor(); request_resource(IO_SYSTEM); } if (dbase(MODBUS, 10001)== 0) puts("tank is not filling!!\r\n"); else puts("tank full\r\n"); setdbase(MODBUS, 1, 0); /* close valve */ release_resource(IO_SYSTEM); Document (Version 2.22) 10/26/2012 694 Porting Existing C Tools Applications Porting Existing C Tools Applications Existing C Tools applications are highly compatible with the SCADAPack 32 C++ Tools. However changes are necessary. The following guide describes the steps in porting an application. Compiler Differences between Microtec Research and Hitachi Some standard libraries and their corresponding header files not included with the Hitachi compiler. See Appendix A, section A.2 of the SuperH RISC engine C/C++ Compiler User’s Manual for details. (The appendix states the libraries are not supported, it should state the library functions are not supported.) Existing programs using these functions need to be rewritten or the user needs to implement the functions. In some cases there are C++ Tools functions that can be used in place of these functions. 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. Signed bit fields are sign extended when assigned to other variables in the Hitachi compiler but are not in the Microtec compiler. This may cause problems in programs that assumed the bit fields would not be sign extended. The programs should use unsigned types for bit fields if this is not desired. Add Existing Code to Framework 1. Copy all user-written *.C files from the 520x application to the project directory created in the last section. 2. Copy user-written *.H files, if any, from the 520x application to the project directory. Do NOT copy the 520x ctools.h file or any other C Tools header files (e.g. older 520x C Tools headers such as protocol.h). The SCADAPack 32 ctools.h is already in the project directory. 3. For each user-written *.H file copied to the project 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 } Document (Version 2.22) 10/26/2012 695 Porting Existing C Tools Applications #endif 4. The application file containing the function main()needs to be a C++ file. Rename this file to a *.CPP file. Add the following prototype to the top of this file: /* ----------------------------------------------------------Function Prototypes ----------------------------------------------------------- */ #ifdef __cplusplus extern "C" { #endif extern void main(void); #ifdef __cplusplus } #endif 5. From HEW, select Add Files from the Project menu. The Add Files dialog is displayed. 6. Select each C and CPP file copied in step 1. The selected files are added to the project. 7. Remove the file <projectName>.cpp from the project using Remove Files from the Project menu. This file contains the function main() for the empty application which is no longer needed. 8. You may delete <projectName>.cpp from the project directory. Replace Older C Tools Headers with ctools.h If the ported application was using 520x C Tools version 2.12 or older, the program 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 files with just one include statement: include <ctools.h> Replace Partially Supported and Unsupported Functions Existing programs may use some functions that are partially supported or unsupported on the SCADAPack 32 controller. The program needs to be changed to use the new functions of the SCADAPack 32 controller. For a list of the functions affected refer to the sections Partially Supported C Tools Functions and Unsupported C Tools Functions. Build the Application Build the application using the HEW build command. This will compile all files and link the object files into an executable program. Document (Version 2.22) 10/26/2012 696 Porting Existing C Tools Applications Check for compiler errors. If you missed converting some functions or forgot to include the C++ Tools header file the compiler may find errors in the code. The C++ Tools contain both C and C++ API functions. In order to call C++ functions from a source file, the source file needs to be a *.CPP file. If an existing *.C file needs to be renamed to a *.CPP file, remove the *.C file from the HEW project and add the newly named *.CPP file using the Project menu. Check for linker errors. If the linker cannot find a C++ Tools API function check if it is supported on SCADAPack 32 controllers. You may have missed converting some functions. If the linker cannot find a function from your program, check that you have added all source code modules to the project. When there are no errors, load the program into the SCADAPack 32 controller using the IEC 61131-3 or Telepace C/C++ Program Loader. The application executable file is a *.MOT file located in the Release directory of the application project as follows: <workspaceName>\<projectName>\Release\<projectName>.MOT Test the Application This step is specific to the application. It needs to be tested to confirm it operates correctly on the SCADAPack 32 controller. • SCADAPack 32 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. • 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. Document (Version 2.22) 10/26/2012 697 Partially Supported C Tools Functions Partially Supported C Tools Functions The following sections describe functions that are supported by the Telepace C Tools and IEC 61131-3 C Tools but are only partially supported by the SCADAPack 32 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 C Tools Applications to the SCADAPack 32. I/O System Functions The SCADAPack 32 uses a new I/O system architecture. I/O operations can be performed in parallel with application program execution. This improves the performance of IEC 61131-3 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 application program can also synchronize with the I/O controller to determine when a set of I/O requests is complete. Existing application programs must be rewritten to use the new I/O system functions. Most I/O System functions are C++ functions. In order to call C++ functions from a source file, the source file needs to be a *.CPP file. If an existing *.C file needs to be renamed to a *.CPP file, remove the *.C file from the HEW project and add the newly named *.CPP file using the Project menu. The following is a list of the I/O System functions. Each function is documented in the Function Specifications section. C++ Function Description ioSetConfiguration ioGetConfiguration ioVersion ioNotification ioSystemReset ioRequest ioStatus ioReadAin4 ioReadAin8 Set I/O controller configuration Get I/O controller configuration Get I/O controller firmware version Request notification Request reset of all I/O modules Request I/O module scan Read I/O module status Read buffered data from 4 point analog input module Read buffered data from 8 point analog input module Document (Version 2.22) 10/26/2012 698 Partially Supported C Tools Functions C++ Function Description ioReadAout2 ioReadAout4 ioReadAout5303 ioReadCounter4 ioReadCounter5232 ioReadDin16 ioReadDin5232 ioReadDin8 ioReadDout16 ioReadDout8 ioRead5601Inputs ioRead5601Outputs ioWriteAout2 ioWriteAout4 ioWriteAout5303 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 buffered data from 4 point counter input module Read buffered data from 5232 counters Read buffered data from 16 point digital input module Read buffered data from 5232 digital inputs Read buffered data from 8 point digital input module Read buffered data for 16 point digital output module Read buffered data for 8 point digital output module Read buffered data from 5601 inputs Read buffered data for 5601 outputs 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 buffered data for 16 point digital output module Write buffered data for 8 point digital output module Write buffered data for 5601 outputs ioWriteDout16 ioWriteDout8 ioWrite5601Outputs Controller I/O Functions The following functions are no longer supported. The replacement function is indicated for each. Function Replaced with interruptInput interruptCounter ioReadDin5232 ioReadCounter5232 Document (Version 2.22) 10/26/2012 699 Partially Supported C Tools Functions readCounter readCounterInput readInternalAD ioReset ioRefresh ioReadCounter5232 ioReadDin5232 readBattery, readThermistor ioSystemReset functions in the ioWrite group IEC 61131-3 I/O Functions The I/O System functions are used in place of the following IEC 61131-3 C Tools I/O functions which are no longer supported. Function Replaced with isaRead4Ain isaRead8Ain isaRead4Counter isaRead8Din isaRead16Din isaRead5601Inputs isaWrite2Aout isaWrite4Aout isaWrite5303Aout isaWrite8Dout isaWrite16Dout isaWrite5601Outputs ioReadAin4 ioReadAin8 ioReadCounter4 ioReadDin8 ioReadDin16 ioRead5601Inputs ioWriteAout2 ioWriteAout4 ioWriteAout5303 ioWriteDout8 ioWriteDout16 ioWrite5601Outputs 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. Function Replaced with dout din aout ain functions in the ioWrite group functions in the ioRead group functions in the ioWrite group functions in the ioRead group Other I/O Function Changes The following C Tools I/O functions are fully supported in the SCADAPack 32 C++ Tools with the following difference. Instead of executing the required I/O Document (Version 2.22) 10/26/2012 700 Partially Supported C Tools Functions 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. Function Description hartIO 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 I/O points to be cleared. ioClear Jiffy Clock Functions The C Tools function jiffy is replaced with the readStopwatch function. This function returns the time in milliseconds. Existing programs needs 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. 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 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 32 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. Function Replaced with load save flashSettingsLoad flashSettingsSave Document (Version 2.22) 10/26/2012 701 Partially Supported C Tools Functions 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. Function Description getSFTranslation setSFTranslation Read Store and Forward Translation 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; }; This structure is replaced with the structure, SF_TRANSLATION, 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 slaveInterface; UINT16 slaveStation; COM_INTERFACE forwardInterface; UINT16 forwardStation; IP_ADDRESS forwardIPAddress; } SF_TRANSLATION; // // // // // slave interface type slave station address forwarding interface type forwarding station address forwarding IP address 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. Set slaveInterface field = portA + 1 portA field Document (Version 2.22) 10/26/2012 702 Partially Supported C Tools Functions Item to be replaced portB field stationA field stationB field Replacement (1 = com1, 2 = com2, 3 = com3, 4= com4, 100 = Ethernet1) Set forwardInterface field = portB + 1 (1 = com1, 2 = com2, 3 = com3, 4= com4, 100 = Ethernet1) slaveStation 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 (slaveInterface and slaveStation) and the forwarding master interface (forwardInterface, forwardStation and forwardIPAddress, if applicable). 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 the master through the same communication path in reverse. The getSFTranslation and setSFTranslation functions are documented in the Function Specifications section. Non-Volatile Data Sections 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 32. SCADAPack 32 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 nonvolatile memory allocation. See the function allocateMemory. To create a non-volatile section, refer to the section Non-Volatile Data Sections. Serial Port Configuration Functions Default Settings for Com1 and Com2 The default settings for Com1 and Com2 have changed. All four serial ports of the SCADAPack 32 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. Document (Version 2.22) 10/26/2012 703 Partially Supported C Tools Functions Rx Flow Control 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 32 needs to have Rx Flow Control set to RFC_MODBUS_RTU (or ENABLE) when the Modbus RTU protocol is used. Rx Flow Control needs to be set to RFC_NONE (or DISABLE) when the Modbus ASCII or any other protocol is used. Rx and Tx Flow Control requirements are now the same for all four serial ports of the SCADAPack 32. New Flow Control MACROS To help clarify the type of Flow Control feature provided when ENABLE or DIABLE 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 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. Com4 Performance Notes The C Tools documentation uses the recommendation below repeatedly concerning com3 and com4. The reference to com4 has been removed from this recommendation. The SCADAPack 32 com4 may be used in the same way as com1 and com2. “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-3 program.” Timers The timer functions (settimer, timer, interval, and read_timer_info) are not supported in the SCADAPack 32 firmware. Instead, these functions are provided in the C++ Tools library and perform the same functionality as before: Function Description interval read_timer_info settimer Set timer tick interval in tenths of seconds. Read information about a software timer Set a timer. Timers count down from the set value to zero. Document (Version 2.22) 10/26/2012 704 Partially Supported C Tools Functions timer Read the time period remaining in a timer The only change required before using these functions is an initialization step which creates the timer support task. The new function, runTimers, starts the timer task. To enable support for timers, the function runTimers needs to be called once before using any of the timer functions (settimer, timer, interval, or read_timer_info). Alternative Methods for Timing If the overhead of the timer task is undesired, two alternative methods supported by the firmware exist for user timing: the functions timedEvents and readStopwatch. Timed Events 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. 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 waits. 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) < 50) { release_processor(); } Refer to the section describing the function readStopwatch for other timing examples using this function. Document (Version 2.22) 10/26/2012 705 Unsupported C Tools Functions Unsupported C Tools Functions The following sections describe functions that are supported by the Telepace C Tools and IEC 61131-3 C Tools but are not supported by the SCADAPack 32 C++ Tools. Refer to these sections when porting existing C Tools Applications to the SCADAPack 32. Application Checksum Function A checksum is no longer used for the C++ application. The C Tools function applicationChecksum is not supported. Sleep Functions The sleep feature is not supported. The following C Tools functions are not supported. Function sleep getWakeSource SetWakeSource Backwards Compatibility Functions These functions were supported in previous 520x C Tools for backwards compatibility, however they were stubs. The following C Tools functions are not supported. Function setSFMapping getSFMapping 5602 I/O Module Functions The 5602 I/O module is not supported by the SCADAPack 32 controller. The following C Tools functions that access this module are not supported. Function ioRead5602Inputs ioWrite5602Outputs isaRead5602Inputs isaWrite5602Outputs Document (Version 2.22) 10/26/2012 706 Unsupported C Tools Functions Boot Type Functions These functions are not useful to C++ Applications. The following C Tools functions are not supported. Function setBootType getBootType I/O Bus Communication Functions The SCADAPack 32 I/O System does not support these C Tools functions. 2 These functions provide user access to third party I C 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 Document (Version 2.22) 10/26/2012 707
* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project
advertisement
© 2021