SCADAPack32 C Tools User_Manual

SCADAPack32 C Tools User_Manual
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
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement