SCADAPack 300 & 4203 C++ Tools

SCADAPack 300 & 4203 C++ Tools
SCADAPack 300 & 4203 C++
Tools
User and Reference Manual
5/19/2011
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.
© 2010 Schneider Electric. All rights reserved.
Document (Version 1.61) 5/19/2011
Table of Contents
Safety Information .......................................................................14
About The Book ...........................................................................17
At a Glance .......................................................................................................... 17
Overview .......................................................................................18
Getting Started .............................................................................19
SCADAPack C++ Tools Installation ..................................................................... 19
Program Development Tutorial ............................................................................ 20
C++ Program Development .........................................................32
Program Architecture ........................................................................................... 32
GNU Compiler Options ........................................................................................ 43
Application Development ..................................................................................... 44
Real Time Operating System ......................................................45
Task Management ............................................................................................... 45
Resource Management ........................................................................................ 46
Inter-task Communication .................................................................................... 49
Event Notification ................................................................................................. 49
Error Reporting..................................................................................................... 50
RTOS Example Application Program................................................................... 51
Overview of Programming Functions ........................................59
Controller Operation ............................................................................................. 59
Controller I/O Hardware ....................................................................................... 61
Serial Communication .......................................................................................... 70
Serial Communication Protocols .......................................................................... 72
DNP Communication Protocol ............................................................................. 74
DF1 Communication Protocol .............................................................................. 78
TCP/IP Communications ...................................................................................... 78
Modbus IP Protocol .............................................................................................. 78
Data Log to File .................................................................................................... 79
Sockets API .......................................................................................................... 80
Modbus I/O Database .......................................................................................... 81
Register Assignment ............................................................................................ 83
IEC 61131-1 Variable Access Functions ............................................................. 84
Document (Version 1.61) 5/19/2011
2
HART Communication ......................................................................................... 84
File Management API........................................................................................... 86
Function Specifications ..............................................................87
Functions Supported by Telepace Only ............................................................... 87
Functions Supported by IEC 61131-1 Only ......................................................... 87
accept ................................................................................................................... 89
addRegAssignment .............................................................................................. 91
addRegAssignmentEx ......................................................................................... 96
alarmIn ............................................................................................................... 102
allocate_envelope .............................................................................................. 103
allocateMemory .................................................................................................. 104
bind .................................................................................................................... 105
check_error ........................................................................................................ 106
checksum ........................................................................................................... 107
checkSFTranslationTable .................................................................................. 108
clearAllForcing ................................................................................................... 109
clearBreakCondition ........................................................................................... 110
clear_errors ........................................................................................................ 111
clear_protocol_status ......................................................................................... 112
clearLoginCredentials ........................................................................................ 113
clearRegAssignment .......................................................................................... 114
clearSFTranslationTable .................................................................................... 115
clearStatusBit ..................................................................................................... 116
clear_tx ............................................................................................................... 117
close ................................................................................................................... 118
configurationRegisterMapping ........................................................................... 119
configurationSetApplicationID ............................................................................ 120
connect ............................................................................................................... 124
copy .................................................................................................................... 126
crc_reverse ........................................................................................................ 127
create_task ......................................................................................................... 128
databaseRead .................................................................................................... 130
databaseWrite .................................................................................................... 131
datalogCreate ..................................................................................................... 132
datalogDelete ..................................................................................................... 134
datalogPurge ...................................................................................................... 136
datalogReadNext ............................................................................................... 138
datalogReadStart ............................................................................................... 140
datalogRecordSize ............................................................................................. 142
datalogSettings .................................................................................................. 143
datalogWrite ....................................................................................................... 144
dbase ................................................................................................................. 145
Dbase Handler Function .................................................................................... 147
deallocate_envelope .......................................................................................... 148
dlogCreate .......................................................................................................... 149
dlogDelete .......................................................................................................... 151
dlogDeleteAll ...................................................................................................... 152
dlogFlush ............................................................................................................ 153
Document (Version 1.61) 5/19/2011
3
dlogGetStatus .................................................................................................... 154
dlogID ................................................................................................................. 155
dlogNewFile ....................................................................................................... 156
dlogResume ....................................................................................................... 157
dlogSpace .......................................................................................................... 158
dlogSuspend ...................................................................................................... 159
dlogWrite ............................................................................................................ 160
dnpClearEventLogs............................................................................................ 161
dnpConnectionEvent .......................................................................................... 162
dnpCreateAddressMappingTable ...................................................................... 163
dnpCreateMasterPollTable ................................................................................ 164
dnpCreateRoutingTable ..................................................................................... 165
dnpGenerateChangeEvent ................................................................................ 166
dnpGenerateEventLog ....................................................................................... 167
dnpGetAI16Config.............................................................................................. 168
dnpGetAI32Config.............................................................................................. 169
dnpGetAISFConfig ............................................................................................. 170
dnpGetAO16Config ............................................................................................ 171
dnpGetAO32Config ............................................................................................ 172
dnpGetAOSFConfig ........................................................................................... 173
dnpGetBIConfig .................................................................................................. 174
dnpGetBIConfigEx ............................................................................................. 175
dnpGetBOConfig ................................................................................................ 176
dnpGetCI16Config ............................................................................................. 177
dnpGetCI32Config ............................................................................................. 178
dnpGetConfiguration .......................................................................................... 179
dnpGetConfigurationEx ...................................................................................... 183
dnpGetRuntimeStatus ........................................................................................ 184
dnpGetUnsolicitedBackoffTime.......................................................................... 185
dnpInstallConnectionHandler ............................................................................. 186
dnpMasterClassPoll ........................................................................................... 191
dnpMasterClockSync ......................................................................................... 192
dnpPortStatus .................................................................................................... 193
dnpReadAddressMappingTableEntry ................................................................ 194
dnpReadAddressMappingTableSize ................................................................. 195
dnpReadMasterPollTableEntry .......................................................................... 196
dnpReadMasterPollTableEntryEx ...................................................................... 197
dnpReadMasterPollTableSize ........................................................................... 198
dnpReadRoutingTableEntry_DialStrings ........................................................... 199
dnpReadRoutingTableEntry ............................................................................... 200
dnpReadRoutingTableEntryEx .......................................................................... 201
dnpReadRoutingTableSize ................................................................................ 202
dnpSaveAI16Config ........................................................................................... 203
dnpSaveAI32Config ........................................................................................... 204
dnpSaveAISFConfig........................................................................................... 205
dnpSaveAO16Config ......................................................................................... 206
dnpSaveAO32Config ......................................................................................... 207
dnpSaveAOSFConfig ......................................................................................... 208
dnpSaveBIConfig ............................................................................................... 209
dnpSaveBIConfigEx ........................................................................................... 210
Document (Version 1.61) 5/19/2011
4
dnpSaveBOConfig ............................................................................................. 211
dnpSaveCI16Config ........................................................................................... 212
dnpSaveCI32Config ........................................................................................... 213
dnpSaveConfiguration ....................................................................................... 214
dnpSaveConfigurationEx ................................................................................... 216
dnpSaveUnsolicitedBackoffTime ....................................................................... 217
dnpSendUnsolicitedResponse ........................................................................... 218
dnpSearchRoutingTable .................................................................................... 219
dnpStationStatus ................................................................................................ 220
dnpWriteAddressMappingTableEntry ................................................................ 221
dnpWriteMasterApplicationLayerConfig............................................................. 222
dnpWriteMasterPollTableEntry .......................................................................... 223
dnpWriteMasterPollTableEntryEx ...................................................................... 224
dnpWriteRoutingTableEntry_DialString ............................................................. 225
dnpWriteRoutingTableEntry ............................................................................... 226
dnpWriteRoutingTableEntryEx ........................................................................... 227
end_application .................................................................................................. 228
end_group .......................................................................................................... 229
end_task ............................................................................................................. 230
endTimedEvent .................................................................................................. 231
enronInstallCommandHandler ........................................................................... 232
ethernetGetIP ..................................................................................................... 236
ethernetGetMACAddress ................................................................................... 237
ethernetSetIP ..................................................................................................... 238
flashSettingsLoad............................................................................................... 239
flashSettingsSave .............................................................................................. 240
forceLed ............................................................................................................. 241
freeMemory ........................................................................................................ 242
getABConfiguration ............................................................................................ 243
getclock .............................................................................................................. 244
getClockAlarm .................................................................................................... 245
getClockTime ..................................................................................................... 246
getControllerID ................................................................................................... 247
getForceFlag ...................................................................................................... 248
getForceLed ....................................................................................................... 250
getFtpServerState .............................................................................................. 251
getHardwareInformation .................................................................................... 252
getIOErrorIndication ........................................................................................... 253
getOutputsInStopMode ...................................................................................... 254
getLoginCredentials ........................................................................................... 255
getpeername ...................................................................................................... 256
getPortCharacteristics ........................................................................................ 257
get_port .............................................................................................................. 258
getPowerMode ................................................................................................... 259
getProgramStatus .............................................................................................. 260
get_protocol ....................................................................................................... 261
getProtocolSettings ............................................................................................ 262
getProtocolSettingsEx ........................................................................................ 264
get_protocol_status ............................................................................................ 266
getSFTranslation ................................................................................................ 267
Document (Version 1.61) 5/19/2011
5
getSFTranslationEx............................................................................................ 268
getsockname ...................................................................................................... 269
getsockopt .......................................................................................................... 270
get_status ........................................................................................................... 274
getStatusBit ........................................................................................................ 275
getTaskInfo ........................................................................................................ 276
getVersion .......................................................................................................... 277
getWakeSource.................................................................................................. 278
Handler Function ................................................................................................ 279
hartIO ................................................................................................................. 282
hartCommand .................................................................................................... 283
hartCommand0 .................................................................................................. 285
hartCommand1 .................................................................................................. 286
hartCommand2 .................................................................................................. 287
hartCommand3 .................................................................................................. 288
hartCommand11 ................................................................................................ 290
hartCommand33 ................................................................................................ 291
hartStatus ........................................................................................................... 293
hartGetConfiguration .......................................................................................... 295
hartSetConfiguration .......................................................................................... 296
hartPackString.................................................................................................... 297
hartUnpackString ............................................................................................... 298
htonl ................................................................................................................... 299
htons .................................................................................................................. 300
inet_addr ............................................................................................................ 301
install_handler .................................................................................................... 302
installClockHandler ............................................................................................ 303
installDbaseHandler ........................................................................................... 304
installSetdbaseHandler ...................................................................................... 305
installExitHandler ............................................................................................... 307
installModbusHandler......................................................................................... 308
installRTCHandler .............................................................................................. 309
RTCHandler Function ........................................................................................ 310
ioClear ................................................................................................................ 311
ioDatabaseReset................................................................................................ 312
ioGetConfiguration ............................................................................................. 314
ioNotification ....................................................................................................... 315
ioRead4203DRInputs ......................................................................................... 316
ioRead4203DSInputs ......................................................................................... 318
ioRead5210Inputs .............................................................................................. 320
ioRead5210Outputs ........................................................................................... 322
ioRead5414Inputs .............................................................................................. 323
ioRead5415Inputs .............................................................................................. 325
ioRead5415Outputs ........................................................................................... 327
ioRead5505Inputs .............................................................................................. 328
ioRead5505Outputs ........................................................................................... 331
ioRead5506Inputs .............................................................................................. 333
ioRead5506Outputs ........................................................................................... 335
ioRead5606Inputs .............................................................................................. 337
ioRead5606Outputs ........................................................................................... 339
Document (Version 1.61) 5/19/2011
6
ioRead5607Inputs .............................................................................................. 341
ioRead5607Outputs ........................................................................................... 343
ioReadAin4 ......................................................................................................... 345
ioReadAin8 ......................................................................................................... 346
ioReadAout2 ...................................................................................................... 347
ioReadAout4 ...................................................................................................... 348
ioReadAout5303 ................................................................................................ 349
ioReadCounter4 ................................................................................................. 350
ioReadCounterSP2 ............................................................................................ 351
ioReadDin16 ...................................................................................................... 352
ioReadDin32 ...................................................................................................... 353
ioReadDin8 ........................................................................................................ 355
ioReadDout16 .................................................................................................... 356
ioReadDout32 .................................................................................................... 357
ioReadDout8 ...................................................................................................... 358
ioReadSP2Inputs ............................................................................................... 359
ioReadSP2Outputs ............................................................................................ 361
ioRequest ........................................................................................................... 363
ioSetConfiguration.............................................................................................. 365
ioStatus .............................................................................................................. 366
ioSystemReset ................................................................................................... 368
ioVersion ............................................................................................................ 369
ioWrite4203DROutputs ...................................................................................... 370
ioWrite4203DSOutputs ...................................................................................... 372
ioWrite5210Outputs ........................................................................................... 374
ioWrite5414Outputs ........................................................................................... 376
ioWrite5415Outputs ........................................................................................... 377
ioWrite5505Outputs ........................................................................................... 379
ioWrite5506Outputs ........................................................................................... 381
ioWrite5606Outputs ........................................................................................... 383
ioWrite5607Outputs ........................................................................................... 386
ioWriteAout2 ....................................................................................................... 389
ioWriteAout4 ....................................................................................................... 390
ioWriteAout5303................................................................................................. 391
ioWriteDout16 .................................................................................................... 392
ioWriteDout32 .................................................................................................... 393
ioWriteDout8 ...................................................................................................... 394
ioWriteSP2Outputs............................................................................................. 395
ipFindFriendlyIPAddress .................................................................................... 397
ipGetConnectionSummary ................................................................................. 398
ipGetInterfaceType............................................................................................. 399
ipReadFriendlyListControl .................................................................................. 400
ipReadFriendlyIPListEntry ................................................................................. 401
ipReadFriendlyIPListSize ................................................................................... 402
ipWriteFriendlyListControl .................................................................................. 403
ipWriteFriendlyIPListEntry .................................................................................. 404
ipWriteFriendlyIPListSize ................................................................................... 405
ledGetDefault ..................................................................................................... 406
ledPower ............................................................................................................ 407
ledPowerSwitch .................................................................................................. 408
Document (Version 1.61) 5/19/2011
7
ledSetDefault ...................................................................................................... 409
listen ................................................................................................................... 410
master_message................................................................................................ 411
memoryPoolUsage............................................................................................. 413
memoryPoolSize ................................................................................................ 414
modbusExceptionStatus .................................................................................... 415
modbusSlaveID .................................................................................................. 416
modemAbort ....................................................................................................... 417
modemAbortAll................................................................................................... 418
modemDial ......................................................................................................... 420
modemDialEnd................................................................................................... 422
modemDialStatus ............................................................................................... 423
modemInit .......................................................................................................... 424
modemInitEnd .................................................................................................... 426
modemInitStatus ................................................................................................ 427
modemNotification ............................................................................................. 428
mTcpGetConfig .................................................................................................. 429
mTcpGetInterface .............................................................................................. 430
mTcpGetInterfaceEx .......................................................................................... 431
mTcpGetProtocol ............................................................................................... 432
mTcpSetConfig .................................................................................................. 433
mTcpSetInterface ............................................................................................... 434
mTcpSetInterfaceEx........................................................................................... 435
mTcpSetProtocol................................................................................................ 436
mTcpMasterClose .............................................................................................. 437
mTcpMasterDisconnect ..................................................................................... 438
mTcpMasterMessage......................................................................................... 439
mTcpMasterOpen .............................................................................................. 441
mTcpMasterStatus ............................................................................................. 443
mTcpRunServer ................................................................................................. 444
ntohl ................................................................................................................... 445
ntohs .................................................................................................................. 446
overrideDbase .................................................................................................... 447
pidExecute ......................................................................................................... 449
pidInitialize ......................................................................................................... 451
pollABSlave ........................................................................................................ 452
poll_event ........................................................................................................... 453
poll_message ..................................................................................................... 455
poll_resource...................................................................................................... 456
portIndex ............................................................................................................ 457
portStream ......................................................................................................... 458
queryStack ......................................................................................................... 459
queue_mode ...................................................................................................... 460
readBoolVariable ................................................................................................ 461
readBattery......................................................................................................... 463
readInputVoltage ................................................................................................ 464
readIntVariable ................................................................................................... 465
readMsgVariable ................................................................................................ 467
readRealVariable ............................................................................................... 469
readStopwatch ................................................................................................... 471
Document (Version 1.61) 5/19/2011
8
readThermistor ................................................................................................... 472
readTimerVariable.............................................................................................. 473
receive_message ............................................................................................... 475
recv..................................................................................................................... 476
recvfrom ............................................................................................................. 478
registerBulkDevOperation .................................................................................. 480
release_processor.............................................................................................. 482
release_resource ............................................................................................... 483
removeModbusHandler ...................................................................................... 484
report_error ........................................................................................................ 485
request_resource ............................................................................................... 486
resetAllABSlaves................................................................................................ 487
resetClockAlarm ................................................................................................. 488
route ................................................................................................................... 489
runBackgroundIO ............................................................................................... 491
runIOSystem ...................................................................................................... 492
runLed ................................................................................................................ 493
runMasterIpStartTask......................................................................................... 494
runTarget ............................................................................................................ 495
select .................................................................................................................. 496
send ................................................................................................................... 498
send_message ................................................................................................... 501
sendto ................................................................................................................ 503
serialModbusMaster ........................................................................................... 505
Set DF1 Protocol Configuration ......................................................................... 507
setBreakCondition .............................................................................................. 508
setclock .............................................................................................................. 509
setClockAlarm .................................................................................................... 510
setdbase ............................................................................................................. 511
Setdbase Handler Function ............................................................................... 513
setDTR ............................................................................................................... 514
setFtpServerState .............................................................................................. 515
setForceFlag ...................................................................................................... 516
setIOErrorIndication ........................................................................................... 518
setOutputsInStopMode ...................................................................................... 519
set_port .............................................................................................................. 520
setLoginCredentials ........................................................................................... 522
setPowerMode ................................................................................................... 523
setProgramStatus .............................................................................................. 524
set_protocol ........................................................................................................ 525
setProtocolSettings ............................................................................................ 526
setProtocolSettingsEx ........................................................................................ 528
setSFTranslation ................................................................................................ 530
setSFTranslationEx ............................................................................................ 533
setsockopt .......................................................................................................... 536
setStatusBit ........................................................................................................ 540
setStatusMode ................................................................................................... 541
setWakeSource .................................................................................................. 542
shutdown ............................................................................................................ 543
signal_event ....................................................................................................... 544
Document (Version 1.61) 5/19/2011
9
sleep_processor ................................................................................................. 546
sleepMode .......................................................................................................... 547
socket ................................................................................................................. 548
start_protocol ..................................................................................................... 550
startup_task ........................................................................................................ 551
startTimedEvent ................................................................................................. 552
sysSerialSetRxTimeout ...................................................................................... 553
unregisterBulkDevOperation .............................................................................. 556
wait_event .......................................................................................................... 558
wd_auto .............................................................................................................. 559
wd_enabled ........................................................................................................ 560
wd_manual ......................................................................................................... 561
wd_pulse ............................................................................................................ 562
writeBoolVariable ............................................................................................... 563
writeIntVariable .................................................................................................. 564
writeRealVariable ............................................................................................... 565
writeMsgVariable ................................................................................................ 566
writeTimerVariable ............................................................................................. 568
xcopy .................................................................................................................. 569
xdelete ................................................................................................................ 570
Macro Definitions .......................................................................571
A ......................................................................................................................... 571
B ......................................................................................................................... 571
C ......................................................................................................................... 572
D ......................................................................................................................... 573
E ......................................................................................................................... 574
F ......................................................................................................................... 575
G......................................................................................................................... 575
H ......................................................................................................................... 575
I .......................................................................................................................... 575
L ......................................................................................................................... 575
M ........................................................................................................................ 576
N ......................................................................................................................... 578
O......................................................................................................................... 578
P ......................................................................................................................... 578
R ......................................................................................................................... 579
S ......................................................................................................................... 580
T ......................................................................................................................... 581
V ......................................................................................................................... 582
W ........................................................................................................................ 582
Structures and Types ................................................................584
ADDRESS_MODE ............................................................................................. 584
ALARM_SETTING ............................................................................................. 584
COM_INTERFACE ............................................................................................ 584
COMM_ENDPOINT ........................................................................................... 585
CONNECTION_TYPE........................................................................................ 585
Document (Version 1.61) 5/19/2011
10
DATALOG_CONFIGURATION .......................................................................... 585
DATALOG_STATUS .......................................................................................... 586
DATALOG_VARIABLE ...................................................................................... 586
DialError ............................................................................................................. 586
DialState ............................................................................................................. 587
dlogConfiguration Type ...................................................................................... 588
dlogCMITime Type ............................................................................................. 589
dlogMediaStatus Type ....................................................................................... 589
dlogRecordElement Type .................................................................................. 589
dlogStatus Type ................................................................................................. 591
dlogTransferStatus Type .................................................................................... 591
DNP_ADDRESS_MAP_TABLE ......................................................................... 592
dnpAnalogInput .................................................................................................. 592
DnpAnalogInputShortFloat ................................................................................. 593
dnpAnalogOutput ............................................................................................... 593
dnpBinaryInput ................................................................................................... 593
dnpBinaryInputEx ............................................................................................... 593
dnpBinaryOutput ................................................................................................ 594
dnpConnectionEventType .................................................................................. 594
dnpConfiguration ................................................................................................ 595
dnpConfigurationEx............................................................................................ 599
dnpCounterInput ................................................................................................ 604
dnpMasterPoll .................................................................................................... 605
DNP Master Poll table Extended Entry .............................................................. 605
dnpPointType ..................................................................................................... 606
dnpProtocolStatus .............................................................................................. 607
dnpRoutingTableEx............................................................................................ 607
DNP_RUNTIME_STATUS ................................................................................. 608
envelope ............................................................................................................. 608
HART_COMMAND ............................................................................................ 609
HART_DEVICE .................................................................................................. 609
HART_RESPONSE ........................................................................................... 610
HART_RESULT ................................................................................................. 610
HART_SETTINGS ............................................................................................. 611
HART_VARIABLE .............................................................................................. 611
IO_CONFIG Structure ........................................................................................ 611
IO_STATUS Structure........................................................................................ 612
IP_ADDRESS .................................................................................................... 612
IP_CONNECTION_SUMMARY ......................................................................... 612
IP_CONFIG_MODE Enumeration ..................................................................... 613
IP_PROTOCOL_SETTINGS ............................................................................. 613
IP_PROTOCOL_TYPE ...................................................................................... 614
IP_SETTINGS .................................................................................................... 614
ledControl_tag .................................................................................................... 615
MASTER_MESSAGE ........................................................................................ 615
MODBUS_CMD_STATUS ................................................................................. 616
ModemInit .......................................................................................................... 618
ModemSetup ...................................................................................................... 618
MTCP_CONFIGURATION ................................................................................. 619
MTCP_IF_SETTINGS ........................................................................................ 620
Document (Version 1.61) 5/19/2011
11
MTCP_IF_SETTINGS_EX ................................................................................. 620
pconfig ................................................................................................................ 621
PID_DATA .......................................................................................................... 621
PROTOCOL_SETTINGS ................................................................................... 623
PROTOCOL_SETTINGS_EX Type ................................................................... 623
prot_settings ....................................................................................................... 624
prot_status ......................................................................................................... 624
PORT_CHARACTERISTICS ............................................................................. 625
pstatus ................................................................................................................ 626
READSTATUS ................................................................................................... 626
routingTable ....................................................................................................... 627
SF_TRANSLATION ........................................................................................... 627
SF_TRANSLATION_EX .................................................................................... 628
SFTranslationStatus........................................................................................... 629
TASKINFO ......................................................................................................... 629
taskInfo_tag........................................................................................................ 630
TIME ................................................................................................................... 630
timer_info ........................................................................................................... 631
timeval ................................................................................................................ 631
VERSION ........................................................................................................... 631
WRITESTATUS ................................................................................................. 631
Example Programs ....................................................................633
Connecting with a Remote Controller Example ................................................. 633
Create Task Example......................................................................................... 634
DataLog Example............................................................................................... 636
Get Program Status Example ............................................................................ 645
Get Task Status Example .................................................................................. 646
Handler Function Example ................................................................................. 647
Install Serial Port Handler Example ................................................................... 650
Install Clock Handler Example ........................................................................... 651
Install Database Handler Example ..................................................................... 653
Memory Allocation Example .............................................................................. 658
Master Message Example Using Modbus Protocol ........................................... 659
Master Message Example Using serialModbusMaster...................................... 661
Master Message Example Using mTcpMasterMessage ................................... 665
Modem Initialization Example ............................................................................ 668
Real Time Clock Program Example ................................................................... 669
Start Timed Event Example ............................................................................... 670
Porting Existing C Tools Applications .....................................672
Porting SCADAPack 32 C++ Applications to the SCADAPack 350 and 4203 .. 672
Partially Supported C++ Tools Functions .......................................................... 674
Unsupported C++ Tools Functions .................................................................... 677
Porting SCADAPack C Applications to the SCADAPack 350 and 4203 ........... 679
Document (Version 1.61) 5/19/2011
12
Index of Figures
Figure 1: Queue Status before Execution of main Task ..................................... 55
Figure 2: Queue Status at Start of main Task .................................................... 55
Figure 3: Queue Status after Creation of echoData Task .................................. 56
Figure 4: Queue Status After echoData Task Waits for Event ........................... 56
Figure 5: Queue Status after Creation of auxiliary Task ..................................... 56
Figure 6: Queue Status After main Task Releases Processor ........................... 57
Figure 7: Queue Status at Start of auxiliary Task ............................................... 57
Figure 8: Queue Status after Character Received ............................................. 58
Figure 9: Queue Status after echoData Waits for Event .................................... 58
Document (Version 1.61) 5/19/2011
13
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.
Document (Version 1.61) 5/19/2011
14
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..
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.
Document (Version 1.61) 5/19/2011
15
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):

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 1.61) 5/19/2011
16
About The Book
About The Book
At a Glance
Document Scope
This manual describes C++ Tools for SCADAPack 300 and 4203 controllers.
Validity Notes
This document is valid for all SCADAPack 300 and 4203 firmware versions.
Product Related Information
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 1.61) 5/19/2011
17
Overview
Overview
The SCADAPack C++ Tools are ideal for engineers and programmers who
require advanced programming tools for SCADA applications and process
control. The SCADAPack controllers execute Telepace Ladder Logic or IEC
61131-1 and up to 32 C++ application programs simultaneously, providing you
with maximum flexibility in implementing your control strategy.
This manual provides documentation on SCADAPack C++ programming and the
library of C++ language process control and SCADA functions.
We sincerely hope that the reliability and flexibility afforded by this fully
programmable controller enable you and your company to solve your automation
projects in a cost effective and efficient manner.
Technical Support
Support related to any part of this documentation can be directed to one of the
following support centers.
Technical Support: The Americas
Available Monday to Friday 8:00am – 6:30pm Eastern Standard Time
Toll free within North America
1-888-226-6876
Direct Worldwide
+1 (613) 591-1943
Email
[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 1.61) 5/19/2011
18
Getting Started
Getting Started
This section of the C++ Tools User Manual describes the installation of C++
Tools and includes a Program Development Tutorial. The Program Development
Tutorial leads the user through the steps involved in writing, compiling, linking
and loading a C++ application program.
SCADAPack C++ Tools Installation
The SCADAPack C++ Tools install a gnu C++ compiler and controller header
and support files. Framework applications for Telepace and IEC 61131-1
firmware are provided.
Any standard Editor may be used to create C++ applications.
Telepace, IEC 61131-1, or Realflo applications are used to load applications into
the SCADAPack controllers.
These installations are described in the following sections.
Installing SCADAPack C++ Tools
To install the SCADAPack C++ Tools:

Insert the SCADAPack C++ Tools CD into your CD drive and follow the onscreen instructions.
The C++ Tools is a command line compiler. Two system properties need to be
set for the compiler to work.
To modify system properties:

From the Start menu or the Desktop, right click on My Computer.

Select the Advanced tab.

Click Environment Variables.

In the System Variables section (at the bottom) add a variable as follows:

o
Click New.
o
In Variable Name type CTOOLS_PATH.
o
In Variable Value type C:\program files\Control Microsystems\CTools
(if you installed to a different path, then substitute the correct path
here)
o
Click OK.
In the System Variables section (at the bottom) modify the PATH variable as
follows:
o
Document (Version 1.61) 5/19/2011
Locate the PATH variable.
19
Getting Started

o
Click Edit.
o
In Variable Value add the following at the start of the text, including
the semi-colon at the end of the string:
C:\Program Files\Control Microsystems\CTools\Arm7\host\x86win32\bin;
(if you installed to a different path, then substitute the correct path
here)
o
Click OK.
Click OK.
Installing Telepace
Install Telepace as described on the jewel case liner of the Telepace Installation
CD.
Some virus checking software may interfere with Setup. If you experience
difficulties with the Setup, disable your virus checker and run Setup again.
Installing IEC 61131-1 Workbench
Install IEC 61131-1 as described on the jewel case liner of the IEC 61131-1
Installation CD.
Some virus checking software may interfere with Setup. If you experience
difficulties with the Setup, disable your virus checker and run Setup again.
Viewing Installed Components
The C++ Tools installs the following components. All files are installed by default
to C:\program files\Control Microsystems\CTools.

gnu C++ compiler for Arm7 processor is installed in the ARM7 folder

C++ Tools header and support files are installed in:
o
Controller/IEC 61131-1 for IEC 61131-1 firmware applications
o
Controller/Telepace for Telepace firmware applications

Framework applications are installed in Controller/Framework Applications.
These are described further in the product development tutorial.

Documentation shortcuts are on the Start menu. You need to have found
them if you‟re reading this so we won‟t say any more.
Program Development Tutorial
Program development consists of three stages: writing and editing; compiling and
linking; and loading the program into the 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”. Hey, who are we to be different?
Document (Version 1.61) 5/19/2011
20
Getting Started
Create a New C++ Application Framework
Any editor may be used to write and edit the application program for the
SCADAPack controllers.
Copy C++ Application Framework
Begin by making a copy of the C++ application framework using the IEC 61131-1
sample application or the Telepace sample application. By default the samples
are installed at C:\program files\Control
Microsystems\CTools\Controller\Framework Applications. Make a copy of either
the IEC 61131-1 or Telepace folder for your application.
For example:

Copy files from C:\program files\Control
Microsystems\CTools\Controller\Framework Applications\IEC 61131-1.

Copy files to C:\projects\SP350\hello
Review appstart.cpp
The appstart.cpp file defines the basic settings for the application, such as stack
size, and main task priority. Applications typically can use the settings in this file
without modification.
Open appstart.cpp to review these application settings:
...
// Priority of the task main().
// Priority 100 is recommended for a continuously running task.
// A task with priority > 100 will never be given the CPU.
// See manual for details.
UINT32 mainPriority = 100;
// Stack space allocated to the task main().
// Note that at least 10 stack blocks are needed when calling
fprintf().
UINT32 mainStack = 10;
// Application group assigned to the task main().
// A unique value is assigned by the system to the
applicationGroup
// for this application. Use this variable in calls to
create_task()
// by this application. See manual for details.
UINT32 applicationGroup = 0;
...
Edit main.cpp
For this tutorial the C code to print “hello world” to serial port 2 will be added to
the main task. The “hello, world” message will be output to the com2 serial port of
the controller. A terminal connected to the port will display the message.
The fprintf function prints the message to the com2 serial port.
Document (Version 1.61) 5/19/2011
21
Getting Started
Edit the main.cpp text and add the text shown in bold in the following section.
int main(void)
{
// add program initialization here
// Print the message
fprintf(com2, "hello, world\r\n");
// main loop
while (TRUE)
{
// add remainder of program here
}
}
Compiling the C++ Application
Once the editing of the project is completed the application needs to be compiled
and linked. This produces an executable file that can be loaded into the
SCADAPack 350 or 4203 controller.
Review makefile
The C++ tools use the gnu make utility to build applications. Application builds
are managed by a make file. For the simplest applications, no modifications of
the makefile are needed. This section may be skimmed the first time through, but
contains information that will be usefull for building more sophisticated
applications.
The makefile is designed to build a application for both the SCADAPack 350 and
4203 controllers. Command line options allow the application to be targeted for a
specific controller, if the application code contains functions that are specific to
the controller.
Open the file makefile in the application folder. The file shown below is from the
IEC 61131-1 application framework.
# ---------------------------------------------------------------# makefile
#
# Make file for SCADAPack 350 / 4203 C Tools application for
# IEC 61131-1 firmware
# Copyright 2007 Control Microsystems Inc.
#
# usage:
#
make
- makes application for all
controllers
#
make TARGET=SCADAPack350 - makes application for SCADAPack
350 controller
#
make TARGET=4203
- makes application for 4203
controller
#
make clean
- deletes all output files
# ----------------------------------------------------------------
Document (Version 1.61) 5/19/2011
22
Getting Started
The first section of the file sets the name of the output file.
The default name is myApp. You should modify this for you
application.
# ---------------------------------------------------------------# set the name of the output file here
# ---------------------------------------------------------------APPLICATION_NAME = myApp
The next section lists all the object files in the application.
There is one object file corresponding to each C or CPP source
file. The framework has two files. You should add additional files
here.
# ---------------------------------------------------------------# list all object files here
# ---------------------------------------------------------------objects = appstart.o main.o
The next section sets the default list of controllers for which the application is
made. The targets in this list are used when make is typed on the command line
without arguments. The default list can be overridded by specifying targets on the
command line. The application is linked against symbol files for the firmware for
these target controllers.
# ---------------------------------------------------------------# list the default target controllers here
# ---------------------------------------------------------------TARGET = SCADAPack350 4203
The C Tools and include paths are set in the next section. The paths are taken
from the environment variable you set during installation. If the variable is not
present, they default to the standard paths. You don‟t need to do anything to this
section.
# ---------------------------------------------------------------# set location of C Tools files
# ---------------------------------------------------------------# take the C Tools path from the environment, or set default if
it's not there (default may not be correct for all installations)
ifeq ($(strip $(CTOOLS_PATH)),)
CTOOLS_PATH = C:\Program Files\Control Microsystems\CTools
endif
# ---------------------------------------------------------------# set location of IEC 61131-1 specific files
# ---------------------------------------------------------------INCLUDE_PATH = $(CTOOLS_PATH)\Controller\IEC 61131-1
Document (Version 1.61) 5/19/2011
23
Getting Started
The next section sets the default compiler flags. You can add to or modify these
flags. Change the default options with care, as many are required for correct
operation. The flags are described in the gnu C++ compiler manual.
# ---------------------------------------------------------------# compiler flags
# ---------------------------------------------------------------CFLAGS = -O3 -mapcs-32 -mlittle-endian -march=armv4 -ansi -fnobuiltin -DARMEL -I"$(INCLUDE_PATH)" -DCPU=ARMARCH4 DTOOL_FAMILY=gnu -DTOOL=gnu -std=c99
The next section lists the suffixes used in this make file. Generally you will not
have to modify this section. Consult the gnu make documentation if you add files
with new suffixes to your application.
# ---------------------------------------------------------------# list of file suffixes used in this makefile
# ---------------------------------------------------------------.SUFFIXES:
.SUFFIXES: .cpp .c .o .out
The next section determines the targets that will be linked to check if symbols will
be resolved in firmware.
#
#
#
#
---------------------------------------------------------------determine intermediate link target(s) used to check
if all symbols can be resolved in firmware
----------------------------------------------------------------
stripTarget = $(strip $(TARGET))
ifeq ($(stripTarget),SCADAPack350 4203)
intermediate_objects = imLink_SCADAPack350.o imLink_4203.o
endif
ifeq ($(stripTarget),SCADAPack350)
intermediate_objects = imLink_SCADAPack350.o
endif
ifeq ($(stripTarget),4203)
intermediate_objects = imLink_4203.o
endif
The next section describes how to make the .out file which is loaded into the
controller. Generally no changes will ever be required in this section. The
compiler options affecting this that should be changed are defined in the
CFLAGS setting above.
# ---------------------------------------------------------------# rules for making .out file
# ---------------------------------------------------------------$(APPLICATION_NAME).out : imImage.o $(intermediate_objects)
# Process CPP constructors and destructors
Document (Version 1.61) 5/19/2011
24
Getting Started
@echo
@echo [email protected] Building output file
@echo -------------------nmarm imImage.o | "$(CTOOLS_PATH)\Arm7\tcl\bin\tclsh84.exe"
"$(CTOOLS_PATH)\Arm7\host\x86-win32\bin\munch.tcl" -c arm > ctdt.c
ccarm $(CFLAGS) -c -fdollars-in-identifiers ctdt.c -o
ctdt.o
# Link downloadable application.
ccarm -I. -r -nostdlib -Wl,-X -Wl,-EL -T
"$(CTOOLS_PATH)\Arm7\target\h\tool\gnu\ldscripts\link.OUT"
imImage.o ctdt.o -o $(APPLICATION_NAME).out
# Clean up temporary files
del ctdt.c ctdt.o
The next sections describe how to make the intermediate objects and check that
symbols will be resolved when the application is loaded into the controller.
Generally no changes will ever be required in this section.
# ---------------------------------------------------------------# rules for making intermediate objects
# ---------------------------------------------------------------imImage.o: $(objects)
# Merge all object files into one
ccarm -I. -r -nostdlib -Wl,-X -Wl,-EL -Wl $(objects) -o
imImage.o
# ---------------------------------------------------------------# link with controller specific CTools library to check for
unresolved externals
# ---------------------------------------------------------------imLink_SCADAPack350.o: imImage.o
@echo
@echo [email protected] Checking for unresolved externals with SCADAPack 350
CTools library
@echo ----------------------------------------------------ldarm -e0 imImage.o "$(INCLUDE_PATH)\SCADAPack_350_IEC
61131-1_Firmware_Image" -o imLink_SCADAPack350.o
imLink_4203.o: imImage.o
@echo
@echo [email protected] Checking for unresolved externals with 4203 library
@echo ----------------------------------------------------ldarm -e0 imImage.o "$(INCLUDE_PATH)\SCADASense_4203_IEC
61131-1_Firmware_Image" -o imLink_4203.o
Document (Version 1.61) 5/19/2011
25
Getting Started
The next section lists the dependencies of the object files on header and source
files. Add additional header files and source files here. The ctools.h file is not
added to the list of dependencies.
# ---------------------------------------------------------------# list all source file dependencies here
# ---------------------------------------------------------------appstart.o: appstart.cpp nvMemory.h
main.o:
main.cpp nvMemory.h
The next section contains the rules for compiling files. Generally no changes will
ever be required in this section. The compiler options affecting this that should be
changed are defined in the CFLAGS setting above
# ---------------------------------------------------------------# rules for making files
# --------------------------------------------------------------%.o : %.c
ccarm $(CFLAGS) -c $< -o [email protected]
%.o : %.cpp
ccarm $(CFLAGS) -c $< -o [email protected]
The next section contains the rules for cleaning out output files from a folder. Use
make clean to start over from a clean slate and compile files again. If you add
additional types of output files, you will need to modify this section.
# ---------------------------------------------------------------# clean up all output files
# ---------------------------------------------------------------.PHONY: clean
clean:
del *.o
del *.out
Build the Application
The gnu C++ compiler is a command line compiler. To build the application:


Open a command prompt from a shortcut or use this procedure:
o
Click Start > Run.
o
In Open type cmd and click OK.
Switch to the folder containing the project.
o

For example type cd c:\projects\sp350\hello
Type make and press Enter
Make will compile the two cpp files, then link them into a single output file named
myApp.out. If errors occur, they will be displayed on the command line.
Document (Version 1.61) 5/19/2011
26
Getting Started
Loading and Executing the C++ Application Using Telepace
The Telepace C\C++ Program Loader transfers executable files from a PC to the
controller and controls execution of programs in the controller.
Controller Initialization
The controller should be initialized when beginning a new programming project or
when it is desired to start from default conditions. It is not necessary to initialize
the controller before every program load.
To completely initialize the controller, perform a Cold Boot.
When the controller starts in the cold boot mode:

The default serial communication parameters are used.

The 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 controller.

Hold down the LED POWER button.

Apply power to the controller.

Continue holding the LED POWER button for 25 seconds until the STAT LED
begins to flash on and off continuously.

Release the LED POWER button.
If the LED POWER button is released before the STAT LED begins to flash the
controller will start in service mode, not the cold boot mode.
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 com3 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.
Document (Version 1.61) 5/19/2011
27
Getting Started
Use the drop down selector for the Port box to select the PC serial port being
used.
Once the desired serial communication parameters have been set click on the
OK button.
The serial ports are set to their default parameters when a Cold Boot is done.
These settings are 9600-baud, 8 data bits, no parity, 1 stop bit, Modbus RTU
protocol, and station address 1.
Loading the Application
To load the Hello C++ application into the controller:

Select Controller > C/C++ Program Loader.

Click Add.

Click Browse.

Locate the application file built earlier. For example
C:\Applications\Telepace\Hello\myApp.out and click OK. You need to use a
file built using a Telepace framework with Telepace firmware.
Document (Version 1.61) 5/19/2011
28
Getting Started

Click Write to write the file to the controller.
Executing the Program

Connect a terminal to com2 on the controller. It will display the output of the
program. Set the communication parameters to 9600 baud, 8 data bits, 1
stop bit, and no parity.

From the C/C++ Program Loader dialog, click on the Run button to execute
the program.
The “hello, world” message will be displayed on the terminal.

When multiple C++ Applications are loaded and the controller is power
cycled, the C++ Applications are restarted in the order they were first loaded
to the controller.
Loading and Executing the C++ Application Using IEC 61131-1
The IEC 61131-1 C\C++ Program Loader transfers executable files from a PC to
the controller and controls execution of programs in the controller.
Controller Initialization
The controller should be initialized when beginning a new programming project or
when it is desired to start from default conditions. It is not necessary to initialize
the controller before every program load.
To completely initialize the controller, perform a Cold Boot.
When the controller starts in the cold boot mode:

The default serial communication parameters are used.

The IEC 61131-1 application program is erased.

The C program is erased.

The controller is unlocked.
To perform a Cold Boot use the following procedure:

Remove power from the controller.

Hold down the LED POWER button.

Apply power to the controller.

Continue holding the LED POWER button for 25 seconds until the STAT LED
begins to flash on and off continuously.

Release the LED POWER button.
If the LED POWER button is released before the STAT LED begins to flash the
controller will start in service mode, not the cold boot mode.
Document (Version 1.61) 5/19/2011
29
Getting Started
Connect to Controller
Before the project can be loaded to the controller a connection, or link, needs to
be made between the PC and the controller.
The serial ports are set to their default parameters when a Cold Boot is done.
These settings are 9600-baud, 8 data bits, no parity, 1 stop bit, Modbus RTU
protocol, and station address 1.
The IEC 61131-1 PC-PLC Link parameters define how the communication link
between the PC and the target controller functions. These parameters are set to
match the serial port parameters.
To open the PC_PLC link parameters dialog:

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.
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 serial ports.

In the Port dropdown selection select the serial port you are using on your
PC to communicate with the controller.
Document (Version 1.61) 5/19/2011
30
Getting Started

Connect com3 to the PC serial port using an RS-232 serial communication
cable. This cable is a null modem or computer-to-computer cable.
Loading the Application
To load the Hello C++ application into the controller:

From the Controller menu, select the C/C++ Program Loader command.

Select the Add button and use the Browse button to locate the application. It
is found at: C:\Applications\IEC 61131-1\Hello\myApp.out.

Select the Write button to download to the file to the controller.
Executing the Program

Connect a terminal to com2 on the controller. It will display the output of the
program. Set the communication parameters to 9600 baud, 8 data bits, 1
stop bit, and no parity.

From the C/C++ Program Loader dialog, click on the Run button to execute
the program.
The “hello, world” message will be displayed on the terminal.

When multiple C++ Applications are loaded and the controller is power
cycled, the C++ Applications are restarted in the order they were first loaded
to the controller.
Document (Version 1.61) 5/19/2011
31
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 350 and 4203 controllers. The
SCADAPack C++ Tools are based on the GNU Compiler Collection (GCC) for
the Arm7 processor. Users will be able to create, compile and debug applications
using these tools.
Application Startup
There are two files associated with the startup structure: appstart.cpp and
nvMemory.h. Each is described below.
Application Startup Function (appstart.cpp)
The start-up code has the following major functions:

initialize application program variables;

execute the main() function
Source code for the appstart function is supplied with the C++ Tools sample
application in the file appstart.cpp. The following discussion refers to statements
found in this file. At the top of appstart.cpp are initialized global variables used to
configure settings for the main task.
/* --------------------------------------------------------------Global Variables
--------------------------------------------------------------*/
// These parameters are used when the task main() is created.
// Priority of the task main().
// Priority 100 is recommended for a continuously running task.
// A task with priority > 100 will never be given the CPU.
// See manual for details.
UINT32 mainPriority = 100;
// Stack space allocated to the task main().
// Note that at least 5 stack blocks are needed when calling
fprintf().
UINT32 mainStack = 5;
// Application group assigned to the task main().
// A unique value is assigned by the system to the
applicationGroup
// for this application. Use this variable in all calls to
create_task()
// by this application. See manual for details.
Document (Version 1.61) 5/19/2011
32
C++ Program Development
UINT32 applicationGroup = 0;
// Pointer to static non-volatile data.
// Define the structure NV_MEMORY in nvMemory.h
NV_MEMORY * pNvMemory = NULL;
// Size of structure in static non-volatile memory
UINT32 nvMemorySize = sizeof(NV_MEMORY);
// applicationType and applicationTypeLimit may be used to limit
// the number of executable instances of this application.
// Valid values for applicationType are 0 to 65535. Default type
is 0.
// Valid values for applicationTypeLimit are 0 to 32.
// Default limit is 0 which = no limit
UINT32 applicationType
= 0; // valid types : 0 to 65535
UCHAR applicationTypeLimit = 0; // valid limits: 0 to 32; 0 = no
limit
mainPRiority
The variable mainPriority selects the priority for the task main. The task main is
declared in the file main.cpp. There are 255 priority levels, and the highest
priority task has a priority of 0. The table below lists the recommended priority
values to use with the SCADAPack 350 and 4203. The logic application executes
in a continuous loop at priority 100. This means that a task selected with priority
> 100 will not be given the CPU. Priority 100 is suitable for C++ Applications.
Document (Version 1.61) 5/19/2011
33
C++ Program Development
P
r
i
o
r
i
t
y
P
r
i
o
r
i
t
y
D
e
s
c
r
i
p
t
i
o
n
V
a
l
u
e
Recomme
nded Use
f
o
r
S
C
A
D
A
P
a
c
k
3
5
0
a
n
d
4
2
0
3
H
i
g
h
e
r
2
5
Not
recomme
nded
P
Document (Version 1.61) 5/19/2011
34
C++ Program Development
P
r
i
o
r
i
t
y
P
r
i
o
r
i
t
y
D
e
s
c
r
i
p
t
i
o
n
V
a
l
u
e
Recomme
nded Use
f
o
r
S
C
A
D
A
P
a
c
k
3
5
0
a
n
d
4
2
0
3
r
i
o
r
i
t
y
Document (Version 1.61) 5/19/2011
35
C++ Program Development
P
r
i
o
r
i
t
y
P
r
i
o
r
i
t
y
D
e
s
c
r
i
p
t
i
o
n
V
a
l
u
e
Recomme
nded Use
f
o
r
S
C
A
D
A
P
a
c
k
3
5
0
a
n
d
4
2
0
3
Document (Version 1.61) 5/19/2011
5
0
Serial
protocol
tasks
7
5
IP
protocol
tasks or
other
36
C++ Program Development
P
r
i
o
r
i
t
y
P
r
i
o
r
i
t
y
D
e
s
c
r
i
p
t
i
o
n
V
a
l
u
e
Recomme
nded Use
f
o
r
S
C
A
D
A
P
a
c
k
3
5
0
a
n
d
4
2
0
3
blocking
task (e.g.
wait_even
t called
each
loop)
L
Document (Version 1.61) 5/19/2011
1
Any
37
C++ Program Development
P
r
i
o
r
i
t
y
P
r
i
o
r
i
t
y
D
e
s
c
r
i
p
t
i
o
n
V
a
l
u
e
Recomme
nded Use
f
o
r
S
C
A
D
A
P
a
c
k
3
5
0
a
n
d
4
2
0
3
o
w
e
r
P
r
i
Document (Version 1.61) 5/19/2011
0
0
continuou
sly
running
loop (e.g.
I/O
processin
g)
38
C++ Program Development
P
r
i
o
r
i
t
y
P
r
i
o
r
i
t
y
D
e
s
c
r
i
p
t
i
o
n
V
a
l
u
e
Recomme
nded Use
f
o
r
S
C
A
D
A
P
a
c
k
3
5
0
a
n
d
4
2
0
3
o
r
i
t
y
Document (Version 1.61) 5/19/2011
39
C++ Program Development
mainStack
The variable mainStack selects the stack space for the task main. At least 5
stack blocks are needed when the main task calls the function fprintf. The heap
size is not configurable. The C++ application has access to the entire system
heap.
applicationGroup
The variable applicationGroup is assigned with a unique value by the operating
system to identify each user-defined C++ application. The variable
applicationGroup should be used for the parameter type when calling the function
create_task. When an application is stopped or deleted, tasks created by the
same application group will be stopped.
pNvMemory and nvMemorySize
The variables pNvMemory and nvMemorySize are declared next and changes
are not required. The structure NV_MEMORY is defined in the file nvMemory.h
and is discussed in the next section.
applicationType and applicationTypeLimit
The variables applicationType and applicationTypeLimit may be used to limit the
number of instances of a C++ Application that may be executed on the same
SCADAPack 350 and 4203. For example, to load another instance of a C++
Application, simply rename the application file before loading it to the controller.
By default, there is no instance limit set. To limit the number of instances to one,
for example, select a unique value for applicationType and set
applicationTypeLimit = 1.
appstart
The appstart function is the entry point for the C++ Application. This function
begins by initializing the global pointer to static non-volatile data. The main task
is called next. If the main task returns, the application including tasks created by
main is ended.
Non-Volatile Memory (nvMemory.h)
C++ Applications may declare variables as non-volatile by locating them in
SRAM. There is 8 KB of SRAM available for static non-volatile variables. And if
this is not enough, up to 1 MB of SRAM is available for dynamic non-volatile
memory allocation. For more details see the function allocateMemory.
Only non-initialized variables are defined as non-volatile. Initialized variables are
not need to be non-volatile, since they are initialized to the same value on
application startup.
The following example describes the procedure for declaring non-volatile
variables. Consider the following C++ Application defined in the two files:
main.cpp and file2.cpp.
Version 1
The first version of these files defines which non-volatile variables are required
for each file. Local and module variables would normally exist as well.
Document (Version 1.61) 5/19/2011
40
C++ Program Development
main.cpp:
#include "ctools.h"
// Non-volatile variables required by main.cpp
static UINT32 variable1;
static UCHAR array1[20];
static struct sample table[10];
void main(void)
{
variable1 = array1[0] * table[0].index;
}
file2.cpp:
#include "ctools.h"
// Non-volatile variables required by file2.cpp
static UINT32 variable2;
void function1(void)
{
variable2++;
}
Version 2
This second version of these files shows how to declare these variables as nonvolatile. To do this the declarations have been moved to the header file
nvMemory.h and are shown in bold below. A template for nvMemory.h is
provided in the sample C++ Application. This header file needs to be included in
each file that accesses the non-volatile variables.
The only undesirable effect of making certain variables non-volatile is that these
variables need to become global variables. To access the non-volatile variables
in code use the pointer, pNvMemory, to the NV_MEMORY structure as shown
below.
main.cpp:
#include "ctools.h"
#include "nvMemory.h"
void main(void)
{
pNvMemory–>variable1 = pNvMemory–>array1[0] *
pNvMemory–>table[0].index;
}
file2.cpp:
#include "ctools.h"
#include "nvMemory.h"
void function1(void)
Document (Version 1.61) 5/19/2011
41
C++ Program Development
{
pNvMemory–>variable2++;
}
nvMemory.h:
/* --------------------------------------------------------------nvMemory.h
Global definitions for user variables that need to be nonvolatile.
Copyright 2006, Control Microsystems Inc.
--------------------------------------------------------------*/
/* Prevent multiple inclusions */
#ifndef NVMEMORY_H
#define NVMEMORY_H
#ifdef __cplusplus
extern "C"
{
#endif
// -------------------------------------------------------// Include-files
// -------------------------------------------------------#include "ctools.h"
/* --------------------------------------------------------------Variables located in Static Non-Volatile Memory
--------------------------------------------------------------*/
// Add fields to this global structure for variables used in your
// application file(s) that need to be non-volatile. Include
// nvMemory.h in all files that use the variable pNvMemory to
access
// NV memory.
typedef struct s_nvMemory
{
UCHAR dummyVariable;
// Add fields here for variables used in your application
// file(s) that need to be non-volatile.
// Non-volatile variables required by main.cpp
UINT32 variable1;
UCHAR array1[20];
struct sample table[10];
// Non-volatile variables required by file2.cpp
float variable2;
}NV_MEMORY;
// Pointer to static non-volatile data
Document (Version 1.61) 5/19/2011
42
C++ Program Development
extern NV_MEMORY * pNvMemory;
#ifdef __cplusplus
}
#endif
#endif // NVMEMORY_H
GNU Compiler Options
The GNU C++ compiler is installed with the C++ Tools. The build.bat file included
in the sample C++ application uses the following command line for compiling:
ccarm -O3 -mapcs-32 -mlittle-endian -march=armv4 -ansi
-fno-builtin -DARMEL -I"%CTOOLS_PATH%" -DCPU=ARMARCH4
-DTOOL_FAMILY=gnu -DTOOL=gnu -std=c99 -c main.cpp
These compiler options are described in the table below. The complete list of
compiler options is may be found in the document Using the GNU Compiler
Collection (GCC) which is installed with the compiler at C:\Program Files\Control
Microsystems\CTools\Arm7\gcc.pdf.
Option
Description
-O3
-mapcs-32
Level 3 optimization
Generate code for a processor running with a 32-bit
program counter, and conforming to the function
calling standards for the APCS 32-bit option.
Generate code for a processor running in littleendian mode.
-mlittle-endian
-march=armv4
-ansi -std=c99
-fno-builtin
-Dname
-Dname=definition
-c
-Idir
-fdollars-in-identifiers
-ofile
Document (Version 1.61) 5/19/2011
Specifies the name of the target ARM architecture
as armv4.
ISO C99 language standard for C++
Don‟t recognize built-in functions not begining with
„__builtin_‟ as prefix.
Predefine name as a macro with the definition 1.
Predefine name as a macro with definition.
Compile or assemble the source files, but not link
them.
Add the directory dir to the head of the list of
directories to be searched for header files. If you
use more than one „-I‟ option, the directories are
scanned in left-to-right order; the standard system
directories come after.
Accept „$‟ in identifiers.
Specifies the name of the output file.
43
C++ Program Development
Application Development
Please refer to the Program Development Tutorial for details on how to build,
load and execute a C++ Application.
Document (Version 1.61) 5/19/2011
44
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 maximum
number of tasks is limited only by available memory. There are 256 task priority
levels to aid in scheduling of task execution.
Task Execution
SCADAPack 350 and 4203 controllers can execute one task at a time. The
RTOS switches between the tasks to provide parallel execution of multiple tasks.
The application program can be event driven, or tasks can execute round-robin
(one after another).
Task execution is based upon the priority of tasks. There are 256 priority levels.
Application programs can use levels 100 to 0. The main task is created at priority
level 100. Task level 0 is the highest priority task.
Tasks that are not running are held in queues. The Ready Queue holds tasks
that are ready to run. Event queues hold tasks that are waiting for events.
Message queues hold tasks waiting for messages. Resource queues hold tasks
that are waiting for resources. The envelope queue holds tasks that are waiting
for envelopes.
Priority Inversion Prevention
When a higher priority task, Task H, requests a resource, which is already
obtained by a lower priority task, Task L, the higher priority task, is blocked until
Task L releases the resource. If Task L is unable to execute to the point where its
releases the resource, Task H will remain blocked. This is called a Priority
Inversion.
To keep this from occurring, the prevention method known as Priority Inheritance
has been implemented. In the example already described, the lower priority task,
Task L, is promoted to the priority of Task H until it releases the needed
resource. At this point Task L is returned to its original priority. Task H will obtain
the resource now that it is available.
Document (Version 1.61) 5/19/2011
45
Real Time Operating System
This does not stop deadlocks that occur when each task requests a resource that
the other has already obtained. This “deadly embrace” is a design error in the
application program.
Operating System Scheduling
The operating system supports a round-robin scheduling algorithm combined
with pre-emptive priority scheduling. It shares the CPU fairly among ready tasks
of the same priority. Round-robin scheduling uses time slicing to achieve fair
allocation of the CPU to tasks with the same priority. Each task, in a group of
tasks with the same priority, executes for a defined interval or time slice.
Because the time slicing is performed by the kernel of the operating system, it is
not necessary anymore for the tasks to call explicitely release_processor to
release CPU time to other tasks of the same priority. In contrary it can harm.
When a task expects a fair share of the CPU, calling release_processor before
the end of the time slice puts it immediately at the end of round-robin-queue.
Therefore the CPU time share can be significantly reduced. The function
release_processor still makes sense if the calling task does not have anything to
do for the moment.
A new function sleep_processor is introduced to release CPU for a certain time.
Task Management Functions
There are five RTOS functions for task management. Refer to the Function
Specification section for details on each function listed.
create_task
Create a task and make it ready to execute.
end_task
Terminate a task and free the resources and envelopes
allocated to it.
end_application
Terminate application program type tasks. This function
is used by communication protocols to stop the
application program prior to loading new code.
installExitHandler
Specify a function that is called when a task is ended
with the end_task or end_application functions.
getTaskInfo
Return information about a task.
Task Management Structures
The ctools.h file defines the structure Task Information Structure for task
management information. Refer to the C Tools Structures and Types section for
complete information on structures and enumeration types.
Resource Management
The resource management functions arbitrate access to non-sharable resources.
These resources include physical devices such as serial ports, and software that
is not re-entrant.
Document (Version 1.61) 5/19/2011
46
Real Time Operating System
The RTOS defines nine system resources, which are used by components of the
I/O drivers, memory allocation functions and communication protocols.
An application program may define other resources as required. Take care not to
duplicate any of the resource numbers declared in ctools.h as system resources.
Resource Management Functions
There are three RTOS functions for resource management. Refer to the Function
Specification section for details on each function listed.
request_resource
Request access to a resource and wait if the resource is
not available.
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.
IO_SYSTEM Resource
The IO_SYSTEM resource regulates access to functions using the I/O system. C
application programs, ladder logic programs, communication protocols and
background I/O operations share the I/O system. It is imperative the resource is
obtained to avoid a conflict, as protocols and background operations are interrupt
driven. Retaining control of the resource for more that 0.1 seconds will cause
background operations to not execute properly.
The IO_SYSTEM resource needs to be obtained before using any of the
following functions.
readRegAssignment
read the register assignment
readRegAssignmentEx read the register assignment
alarmIn
configure the alarm in parameters
clearAllForcing
clear all forcing flags
clear_errors
clear serial port error counters
clear_protocol_status clear protocol status
clearRegAssignment clear register assignment
clearSFTranslationTable clear the Store and Forward translation table
databaseRead
read a value from the database
databaseWrite
write a value to the database
dbase
read a value from the database
getclock
read the system clock
getClockAlarm
read the clock alarm settings
getClockTime
read the system clock time
ioClear
clear the I/O
Document (Version 1.61) 5/19/2011
47
Real Time Operating System
ioDatabaseReset
reset the database
ledSetDefault
set the default LED state
master_message
send a master message poll
mTcpSetInterfaceEx
configure the Modbus/TCP interface
mTcpSetProtocol
configure the Modbus/TCP protocol
mTcpMasterMessage send a Modbus/TCP master message
overrideDbase
force the database value
readIntVariable
read an integer variable
readMsgVariable
read a message variable
readRealVariable
read a real variable
readTimerVariable
read a timer variable
resetClockAlarm
reset the clock alarm
setclock
set the system clock
setClockAlarm
set the clock alarm
setdbase
set a database register
setForceFlag
set the forcing flag
set_port
set the serial port
set_protocol
set the protocol for an interface
setProtocolSettings
set the protocol settings
setProtocolSettingsEx set the protocol settings
setSFTranslation
configure Store and Forward translation
setSFTranslationEx
configure Store and Forward translation
writeBoolVariable
write a Boolean variable
writeIntVariable
write an Integer variable
writeRealVariable
write a Real variable
writeMsgVariable
write a Message variable
writeTimerVariable
write a Timer variable
DYNAMIC_MEMORY Resource
The DYNAMIC_MEMORY resource regulates access to memory allocation
functions. These functions allocate memory from the system heap. The heap is
shared amongst tasks. The allocation functions are non-reentrant.
The DYNAMIC_MEMORY resource needs to be obtained before using any of the
following functions.
Document (Version 1.61) 5/19/2011
48
Real Time Operating System
calloc
allocates data space dynamically
free
frees dynamically allocated memory
malloc
allocates data space dynamically
realloc
changes the size of dynamically allocated space
Inter-task Communication
The inter-task communication functions pass information between tasks. These
functions can be used for data exchange and task synchronization. Messages
are queued by the RTOS until the receiving task is ready to process the data.
Inter-task Communication Functions
There are five RTOS functions for inter-task communication. Refer to the
Function Specification section for details on each function listed.
send_message
Send a message envelope to another task.
receive_message
Read a received message from the task's message
queue or wait if the queue is empty.
poll_message
Read a received message from the task's message
queue. Continue execution of the task if the queue is
empty.
allocate_envelope
Obtain a message envelope from free pool maintained
by the RTOS, or wait if none is available.
deallocate_envelope
Return a message envelope to the free pool maintained
by the RTOS.
Inter-task Communication Structures
The ctools.h file defines the structure Message Envelope Structure for inter-task
communication information. Refer to the C Tools Structures and Types section
for complete information on structures and enumeration types.
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
Document (Version 1.61) 5/19/2011
Wait for an event to occur.
49
Real Time Operating System
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 should only be called from within
an interrupt handler.
There are two support functions, which are not part of the RTOS that may be
used with events.
startTimedEvent
Enables signaling of an event at regular intervals.
endTimedEvent
Terminates signaling of a regular event.
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).
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 provide that an error code generated by one
task is not reported in another task. The errno global variable used by some
functions may be modified by another task, before the current task can read it.
Document (Version 1.61) 5/19/2011
50
Real Time Operating System
Error Reporting Functions
There are two RTOS functions for error reporting. Refer to the Function
Specification section for details on each function listed.
check_error
Check the error code for the current task.
report_error
Set the error code for the current task.
RTOS Example Application Program
The following program is used in the explanation of the RTOS functions. It
creates several simple tasks that demonstrate how tasks execute. A task is a C
language function that has as its body an infinite loop so it continues to execute
forever.
The main task creates two tasks. 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 –
signalCharacter – that signals an event each time a character is received. This
function is hooked into the receiver interrupt handler for the serial port.
The execution of this program is explained in the Explanation of Task Execution
section.
/* --------------------------------------------------------------Real Time Operating System Sample
Copyright (c) 2006, Control Microsystems Inc.
This program creates several simple tasks for demonstration of
the
functionality of the real time operation system.
--------------------------------------------------------------*/
#include <stdio.h>
#include <ctools.h>
/* --------------------------------------------------------------Constants
------------------------------------------------------------*/
#define CHARACTER_RECEIVED 10
/* --------------------------------------------------------------signalCharacter
Document (Version 1.61) 5/19/2011
51
Real Time Operating System
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
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);
Document (Version 1.61) 5/19/2011
52
Real Time Operating System
/* 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);
}
}
/* --------------------------------------------------------------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)
Document (Version 1.61) 5/19/2011
53
Real Time Operating System
2
{
/* Create serial communication task */
create_task(echoData, 3, applicationGroup, 3);
/* Create a task - same priority as main() task */
create_task(auxiliary, 1, applicationGroup, 2);
5
while (TRUE)
{
/* ... add application specific code here ... */
/* Allow other tasks of this priority to execute */
6
release_processor();
}
}
Explanation of Task Execution
SCADAPack 350 and 4203 controllers can execute one task at a time. The Real
Time Operating System (RTOS) switches between the tasks to provide parallel
execution of multiple tasks. The application program can be event driven, or
tasks can execute round-robin (one after another). This program illustrates both
types of execution.
Task execution is based upon the priority of tasks. There are 256 priority levels.
Level 255 is reserved for the null task. This task runs when there are no other
tasks available for execution. Application programs can use levels 100 to 0. The
main task is created at priority level 100.
Tasks that are not running are held in queues. The Ready Queue holds tasks
that are ready to run. Event queues hold tasks that are waiting for events.
Message queues hold tasks waiting for messages. Resource queues hold tasks
that are waiting for resources. The envelope queue holds tasks that are waiting
for envelopes.
The execution of the tasks is illustrated by examining the state of the queues at
various points in the program. These points are indicated on the program listing
above. The examples show only the Ready queue, the Event 10 queue and the
executing task. These are the only queues relevant to the example.
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.
Document (Version 1.61) 5/19/2011
54
Real Time Operating System
Ready Queue
Event 10 Queue
25
25
50
50
75
75
100
100
255
null()
Running Task
none
255
Figure 1: Queue Status before Execution of main Task
Execution Point 2
This point occurs just after the creation of the main task. It is the running task. On
the next instruction it will create the echoData task.
Ready Queue
Event 10 Queue
25
25
50
50
75
75
100
100
255
null()
Running Task
main()
255
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
25
25
50
50
75
75
100
main()
100
255
null()
255
Document (Version 1.61) 5/19/2011
Running Task
echoData()
55
Real Time Operating System
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.
Ready Queue
Event 10 Queue
25
25
50
50
75
75
100
100
255
null()
Running Task
main()
echoData()
255
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
25
25
50
50
75
75
100
auxiliary()
100
255
null()
255
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.
Document (Version 1.61) 5/19/2011
56
Real Time Operating System
Ready Queue
Event 10 Queue
25
25
50
50
75
75
100
auxiliary()
255
null()
main()
Running Task
none
echoData()
100
255
Figure 6: Queue Status After main Task Releases Processor
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
25
25
50
50
75
75
100
255
main()
100
nullTask()
255
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.
Document (Version 1.61) 5/19/2011
57
Real Time Operating System
Ready Queue
Event 10 Queue
25
25
50
50
75
75
100
main()
255
null()
auxiliary()
Running Task
echoData()
100
255
Figure 8: Queue Status after Character Received
Execution Point 9
This point occurs just after the echoData task waits for the character-received
event. It is placed on the event 10 queue. The highest priority task on the ready
queue – main – is given the processor and executes.
Ready Queue
Event 10 Queue
25
25
50
50
75
75
100
255
auxiliary()
100
null()
255
Running Task
main()
echoData()
Figure 9: Queue Status after echoData Waits for Event
Document (Version 1.61) 5/19/2011
58
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 functions relating to
controller operation.
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-1)
executeConstructors Execute user-created global class object constructors.
executeDestructors
Execute 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.
STARTUP_APPLICATION
STARTUP_SYSTEM
Document (Version 1.61) 5/19/2011
Specifies the application start up task.
Specifies the system start up task.
59
Overview of Programming Functions
Start Up Task Info Structure
The ctools.h file defines the structure TASKINFO for use with the startup_task
function. Refer to the C Tools Structures and Types section for complete
information on structures and enumeration types.
Program Status Information Functions
There are two library functions related to controller program status information.
Refer to the Function Specification section for details on each function listed.
getProgramStatus
Returns the application program execution status.
setProgramStatus
Sets the application program execution status.
Controller Information Functions
There are no functions related to controller information. Refer to the Function
Specification section for details.
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 350 and 4203 controllers use flash memory to store controller
settings. The flash memory functions have one parameter: flags indicating which
areas to store into flash. A sum of more than one area may be selected. Valid
flags are listed below and defined in ctools.h.
Area Flag
Loaded on Reset
Controller Settings in this
Area
CS_ETHERNET
CS_OPTIONS
CS_PERMANENT
always
always
Saved settings loaded
on Service and Run
Boot.
Replaced with default
settings on Cold 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, I/O error indication
setting
Telepace Firmware only:
Document (Version 1.61) 5/19/2011
60
Overview of Programming Functions
Area Flag
CS_RUN
Loaded on Reset
Controller Settings in this
Area
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
Saved settings loaded
on Run Boot.
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 I/O points
ioDatabaseReset
Resets the controller to default settings.
ioRefresh
Refresh outputs with internal data
ioReset
Reset I/O modules
Controller I/O Hardware
This section of the manual provides an overview of the C Tools functions relating
to controller signal input and output (I/O).
Analog Input Functions
The controller supports internal analog inputs and external analog input modules.
Refer to the SCADAPack 350 System Hardware Manual or the SCADAPack
4203 Hardware Manual for further information on controller analog inputs and
analog input modules.
There are several library functions related to internal analog inputs and analog
input modules. Refer to the Function Specification section for details on each
function listed.
readBattery
Document (Version 1.61) 5/19/2011
Read the controller RAM battery voltage.
61
Overview of Programming Functions
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.
ioRead5607Inputs
Read the digital and analog inputs from a 5607 I/O
Module.
ioRead5607Outputs
Read the digital and analog outputs from a 5607 I/O
Module.
ioRead4203DRInputs Read the inputs from a 4203 DR controller
ioRead4203DSInputs Read the inputs from a 4203 DS controller
Analog Output Functions
The controller supports external analog output modules. Refer to the
SCADAPack 350 System Hardware Manual or the SCADAPack 4203 Hardware
Manual for further information on these modules.
There are three library functions related to analog output modules. Refer to the
Function Specification section for details on each function listed.
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
ioRead5606Outputs
Read the digital and analog outputs from a 5606 I/O
Module.
Document (Version 1.61) 5/19/2011
62
Overview of Programming Functions
ioRead5607Outputs
Read the digital and analog outputs from a 5607 I/O
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
ioWrite4203DRInputs Write to the outputs of a 4203 DR controller
iowrite4203DSInputs Write to the outputs of a 4203 DS controller
ioWrite5606Outputs
Write to the digital and analog outputs of a 5606 I/O
Module.
ioWrite5607Outputs
Write to the digital and analog outputs of a 5607 I/O
Module.
Digital Input Functions
The controller supports internal digital inputs and external digital input modules.
Refer to the SCADAPack 350 System Hardware Manual for further information
on controller digital inputs and digital input modules.
There are several library functions related to digital inputs and external digital
input modules. Refer to the Function Specification section for details on each
function listed.
ioRead5606Inputs
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.
ioRead5606Outputs
Read the digital and analog outputs from a 5606 I/O
Module.
ioRead5607Outputs
Read the digital and analog outputs from a 5607 I/O
Module.
ioReadDin8
Read buffered data from any 8 point Digital input
module.
Document (Version 1.61) 5/19/2011
63
Overview of Programming Functions
Digital Output Functions
The controller supports external digital output modules. Refer to the SCADAPack
350 System Hardware Manual for further information on controller digital output
modules.
There are several library functions related to digital output modules. Refer to the
Function Specification section for details on each function listed.
ioRead5606Inputs
Read the digital and analog outputs 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.
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 digital outputs of a
5601 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
ioWrite5607Outputs
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
Document (Version 1.61) 5/19/2011
64
Overview of Programming Functions
inputs. Refer to the SCADAPack 350 System Hardware Manual for further
information on controller counter inputs and counter input modules.
There are three library functions related to counters. Refer to the Function
Specification section for details on each function listed.
ioReadCounter5232
Read buffered data from the 5232 counter inputs.
ioReadCounter4
Read buffered data from any 4 point Counter input
module.
Status LED and Output Functions
The status LED and output indicate alarm conditions. The STAT LED blinks and
the STATUS output opens when an alarm occurs. The STAT LED turns off and
the STATUS output closes when alarms clear.
The STAT LED blinks a binary sequence indicating alarm codes. The sequences
consist of long and short flashes, followed by an off delay of 1 second. The
sequence then repeats. The sequence may be read as the Controller Status
Code.
Refer to the SCADAPack 350 System Hardware Manual or the SCADAPack
4203 Hardware Manual for further information on the status LED and digital
output.
There are three library functions related to the status LED and digital output.
Refer to the Function Specification section for details on each function listed.
clearStatusBit
Clears bits in controller status code.
getStatusBit
Gets the bits in controller status code.
setStatusBit
Sets the bits in controller status code.
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 forcing conditions from 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
Document (Version 1.61) 5/19/2011
65
Overview of Programming Functions
Status LED and Output Macros
The ctools.h file defines the following macros for use with the status LED and
digital output. Refer to the C Tools Macros section for details on each macro
listed.
S_MODULE_FAILURE Status LED code for I/O module communication failure
S_NORMAL
Status LED code for normal status
LED Indicators Functions
An application program can control three LED indicators.
The RUN LED (green) indicates the execution status of the program. The LED
can be on or off. It remains in the last state until changed.
The STAT LED (yellow) indicates error conditions. It outputs an error code 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. Use this function with
care in application programs.
There are two library functions related to the LED indicators. Refer to the
Function Specification section for details on each function listed.
runLed
Controls the RUN LED status.
forceLed
Sets state of the force LED.
LED Power Control Functions
The controller board can disable the LEDs on the controller board and I/O
modules to conserve power. This is particularly useful in solar powered or
unattended installations. Refer to the hardware manual for further information on
LED power control.
There are four library functions related to LED power control. Refer to the
Function Specification section for details on each function listed.
ledGetDefault
Get default LED power state
ledPower
Set LED power state
ledPowerSwitch
Read LED power switch
ledSetDefault
Set default LED power state
LED Power Control Structure
The ctools.h file defines the structure LED Power Control Structure for LED
power control information. Refer to the C Tools Structures and Types section for
complete information on structures and enumeration types.
Document (Version 1.61) 5/19/2011
66
Overview of Programming Functions
Software Timer Functions
The controller provides 32 powerful software timers, which greatly simplify the
task of programming time-related functions. Uses include:

generation of time delays

timing of process events such as tank fill times

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.
Document (Version 1.61) 5/19/2011
67
Overview of Programming Functions
alarmIn
Returns absolute time of alarm given elapsed time
getclock
Read the real time clock.
getClockAlarm
Reads the real time clock alarm settings.
getClockTime
Read the real time clock.
installClockHandler
Installs a handler for real time clock alarms.
resetClockAlarm
Resets the real time clock alarm so it will recur at the
same time next day.
setclock
Set the real time clock.
setClockAlarm
Sets real time clock alarm.
Real Time Clock Structures
The ctools.h file defines the structures Real Time Clock Structure and Alarm
Settings Structure for real time clock information. Refer to the C Tools Structures
and Types section for complete information on structures and enumeration types.
Stopwatch Timer Functions
The stopwatch is a counter 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 Function
Specification section for details.
readStopwatch
reads the stopwatch timer.
Watchdog Timer Functions
A watchdog timer is a hardware device, which enables rapid detection of
computer hardware or software problems. In the event of a major problem, the
CPU resets and the application program restarts.
The controller provides an integral watchdog timer to ensure reliable operation.
The watchdog timer resets the CPU if it detects a problem in either the hardware
or system firmware. A user program can take control of the watchdog timer, so it
will detect abnormal execution of the program.
A watchdog timer is a retriggerable, time delay timer. It begins a timing sequence
every time it receives a reset pulse. The time delay is adjusted so that regular
reset pulses stops the timer from expiring. If the reset pulses cease, the
watchdog timer expires and turns on its output, signifying a malfunction. The
timer output in the controller resets the CPU and turns off outputs at the I/O
system.
The watchdog timer is normally reset by the operating system. This is
transparent to the application program. Operating in such a fashion, the
watchdog timer detects any hardware or firmware problems.
Document (Version 1.61) 5/19/2011
68
Overview of Programming Functions
The watchdog timer can detect failure of an application program. The program
takes control of the timer, and resets it regularly. If unexpected operation of the
program occurs, the reset pulses cease, and the watchdog timer resets the CPU.
The program restarts from the beginning.
There are three library functions related to the watchdog timer. Refer to the
Function Specification section for details on each function listed.
wd_auto
Gives control of the watchdog timer to the operating
system (default).
wd_manual
Gives control of the watchdog timer to an application
program.
wd_pulse
Generates a watchdog reset pulse.
A watchdog reset pulse needs to be generated at least every 500 ms. The CPU
resets, and program execution starts from the beginning of the program, if the
watchdog timer is not reset.
Watchdog Timer Program Example
The following program segment shows how the watchdog timer could be used to
detect the failure of a section of a program.
wd_manual(); /* take control of watchdog timer */
do {
/* program code */
wd_pulse();
/* reset the watchdog timer */
}
while (condition)
wd_auto();
/* return control to OS */
Pass control of the watchdog timer back to the operating system before stopping
a program, or switching to another task that expects the operating 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 communication errors. Additional types of
checksums are easily implemented using library functions.
There are two library functions related to checksums. Refer to the Function
Specification section for details on each function listed.
checksum
Calculates additive, CRC-16, CRC-CCITT and
exclusive-OR type checksums
crc_reverse
Calculates custom CRC type checksum using reverse
CRC algorithm.
Document (Version 1.61) 5/19/2011
69
Overview of Programming Functions
Serial Communication
SCADAPack 350 controllers offer three RS-232 serial ports. 4203 controllers
have two serial ports, configurable for RS-232 or RS-485. The ports are
configurable for baud rate, data bits, stop bits, parity and communication
protocol.
Default Serial Parameters
Ports are configured at reset with default parameters when the controller is
powered up in SERVICE mode. The ports use stored parameters when the
controller is reset in the RUN mode. The default parameters are listed below.
Parameter
com1
com2
Com3
Baud rate
Parity
Data bits
Stop bits
Duplex
Protocol
Addressing Mode
Station
Rx flow control
Tx flow control
9600
none
8
1
full
Modbus RTU
Standard
1
Modbus RTU
none
9600
none
8
1
full
Modbus RTU
Standard
1
Modbus RTU
none
9600
None
8
1
Half
Modbus RTU
Standard
1
Modbus RTU
none
Debugging Serial Communication
Serial communication can be difficult to debug. This section describes common
causes of communication failures.
To communicate, the controller and an external device need to use the same
communication parameters. Check the parameters in both units.
If some but not all characters transmit properly, you probably have a parity or
stop bit mismatch between the devices.
The connection between two RS-232 Data Terminal Equipment (DTE) devices is
made with a null-modem cable. This cable connects the transmit data output of
one device to the receive data input of the other device – and vice versa. The
controller is a DTE device. This cable is described in the System Hardware
Manual for your controller.
The connection between a DTE device and a Data Communication Equipment
(DCE) device is made with a straight cable. The transmit data output of the DTE
device is connected to the transmit data input of the DCE device. The receive
data input of the DTE device is connected to the receive data output of the DCE
device. Modems are usually DCE devices. This cable is described in the System
Hardware Manual for your controller.
Many RS-232 devices require specific signal levels on certain pins.
Communication is not possible unless the required signals are present. In the
Document (Version 1.61) 5/19/2011
70
Overview of Programming Functions
controller the CTS line needs to be at the proper level. The controller will not
transmit if CTS is OFF. If the CTS line is not connected, the controller will force it
to the proper value. If an external device controls this line, it needs to turn it ON
for the controller to transmit.
Serial Communication Functions
The ctools.h file defines the following serial communication related functions.
Refer to the Function Specification section for details on each function listed.
clear_errors
Clear serial port error counters.
clear_tx
Clear serial port transmit buffer.
get_port
Read serial port communication parameters.
getPortCharacteristics Read information about features supported by a serial
port.
get_status
Read serial port status and error counters.
install_handler
Install serial port character received handler.
portIndex
Get array index for serial port
portStream
Get serial port corresponding to index
queue_mode
Set serial port transmitter mode.
route
Redirect standard I/O streams.
setDTR
Control RS232 port DTR signal.
set_port
Set serial port communication parameters.
Serial Communication Structures
The ctools.h file defines the structures Serial Port Configuration, Serial Port
Status and Serial Port Characteristics for serial port configuration and
information. Refer to the C Tools Structures and Types section for complete
information on structures and enumeration types.
Dial-Up Modem Functions
These library functions provide control of dial-up modems. They are used with
external modems connected to a serial port. An external modem normally
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.
The dial-up modem functions apply to the SCADAPack 350 controllers RS-232
ports.
modemInit
modemInitStatus
modemInitEnd
Document (Version 1.61) 5/19/2011
send initialization string to dial-up modem.
read status of modem initialization operation.
terminate modem initialization operation.
71
Overview of Programming Functions
modemDial
connect with an external device using a dial-up
modem.
modemDialStatus
read status of connection with external device using a
dial-up modem.
modemDialEnd
terminate connection with external device using a dial-up
modem.
modemAbort
unconditionally terminate connection with external
device or modem initialization (used in task exit handler).
modemAbortAll
unconditionally terminate connections with external
device or modem initializations (used in task exit
handler).
modemNotification
notify the dial-up modem handler that an interesting
event has occurred. This function is usually called
whenever a message is received by a protocol.
Dial-Up Modem Macros
The ctools.h file defines the following macros of interest to a C application
program. Refer to the C Tools Macros section for details on each macro listed.
MODEM_CMD_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 controllers. Additional TeleBUS
commands provide remote programming and diagnostics capability.
The TeleBUS protocols provide access to the I/O database in the controller. The
I/O database contains user-assigned registers and general purpose registers.
Assigned registers map directly to the I/O hardware or system parameter in the
controller. General purpose registers can be used by ladder logic and C
application programs to store processed information, and to receive information
from a remote device.
Document (Version 1.61) 5/19/2011
72
Overview of Programming Functions
The TeleBUS protocols operate on a wide variety of serial data links. These
include RS-232 serial ports, RS-485 serial ports, radios, leased line modems,
and dial up modems. The protocols are generally independent of the
communication parameters of the link, with a few exceptions.
Application programs can initiate communication with remote devices. A multiple
port controller can be a data concentrator for remote devices, by polling remote
devices on one port(s) and responding as a slave on another port(s).
The protocol type, communication parameters and station address are
configured separately for each serial port on a controller. One controller can
appear as different stations on different communication networks. The port
configuration can be set from an application program, from the IEC 61131-1
programming software, or from another Modbus or DF1 compatible device.
Protocol Type
The protocol type may be set to emulate the Modbus ASCII and Modbus RTU
protocols, or it may be disabled. When the protocol is disabled, the port functions
as a normal serial port.
Station Number
The TeleBUS protocol allows up to 254 devices on a network using standard
addressing and up to 65534 devices using extended addressing. Station
numbers identify each device. A device responds to commands addressed to it,
or to commands broadcast to every station.
The station number is in the range 1 to 254 for standard addressing and 1 to
65534 for extended addressing. Address 0 indicates a command broadcast to
every station, and cannot be used as a station number. Each serial port may
have a unique station number.
Store and Forward Messaging
Store and 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 store and forward translation table entries.
get_protocol
Reads protocol parameters.
Document (Version 1.61) 5/19/2011
73
Overview of Programming Functions
getProtocolSettings
Reads extended addressing protocol parameters for a
serial port.
get_protocol_status
Reads protocol message and error counters.
getSFTranslation
Read store and forward translation table entry.
installModbusHandler This function allows user-defined extensions to standard
Modbus protocol.
master_message
Sends a protocol message to another device.
modbusExceptionStatus
Sets response for the read exception status
function.
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
Write store and forward translation table entry.
start_protocol
Starts protocol execution based on stored parameters.
Communication Protocols Enumeration Types
The ctools.h file defines the enumeration type ADDRESS_MODE. Refer to the C
Tools Structures and Types section for complete information on structures and
enumeration types.
Communication Protocols Structures
The ctools.h file defines the structures Protocol Status Information, Protocol
Settings, Extended Protocol Settings, Store and Forward Message and Store and
Forward Status. Refer to the C Tools Structures and Types section for complete
information on structures and enumeration types.
DNP Communication Protocol
DNP, the Distributed Network Protocol, is a standards-based communications
protocol developed to achieve interoperability among systems in the electric
utility, oil & gas and water/waste water industries. This robust, flexible nonproprietary protocol is based on existing open standards to work within a variety
of networks. The IEEE has recommended DNP for remote terminal unit to
intelligent electronic device messaging. DNP can also be implemented in any
SCADA system for efficient and robust communications between substation
computers, RTUs, IEDs and master stations; over serial or LAN-based systems.
DNP offers flexibility and 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
Document (Version 1.61) 5/19/2011
74
Overview of Programming Functions

Time synchronization and time-stamped events

Broadcast messages

Data link and application layer confirmation
DNP 3.0 was originally designed based on three layers of the OSI seven-layer
model: application layer, data link layer and physical layer. The application layer
is object-based with objects provided for generic data formats. The data link layer
provides for several methods of retrieving data such as polling for classes and
object variations. The physical layer defines commonly a simple RS-232 or RS485 interface.
DNP Communication Protocol Functions
There are several library functions related to DNP communication protocol. Refer
to the Function Specification section for details on each function listed.
dnpClearEventLogs
Deletes change events from the DNP change event
buffers.
dnpConnectionEvent Report a DNP connection event
dnpCreateAddressMappingTable
Allocates memory for a new address
mapping table according to the „size‟ parameter.
dnpCreateMasterPollTable
Allocates memory for a new table according to
the „size‟ parameter.
dnpCreateRoutingTable
Allocates memory for a new routing table
according to the „size‟ parameter.
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.
Document (Version 1.61) 5/19/2011
75
Overview of Programming Functions
dnpGetBIConfig
Reads the configuration of a DNP binary input point.
dnpGetBIConfigEx
Reads the configuration of an extended DNP Binary
Input point.
dnpGetBOConfig
Reads the configuration of a DNP binary output point.
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 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_DialString
Reads a primary and secondary
dial string from an entry in the DNP routing table.
dnpReadRoutingTableSize
table.
dnpSaveAI16Config
Document (Version 1.61) 5/19/2011
Reads the total number of entries in the routing
Sets the configuration of a DNP 16-bit analog input
point.
76
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_DialString
Writes a primary and secondary
dial string into an entry in the DNP routin
Document (Version 1.61) 5/19/2011
77
Overview of Programming Functions
DNP Communication Protocol Structures and Types
The ctools.h file defines the structures DNP Configuration, Binary Input Point,
Binary Output Point, Analog Input Point, Analog Output Point and Counter Input
Point. Refer to the C Tools Structures and Types section for complete
information on structures and enumeration types.
DF1 Communication Protocol
The TeleBUS 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
Reads DF1 protocol configuration parameters.
pollABSlave
Requests a response from a slave controller using the
half-duplex version of the protocol.
resetAllABSlaves
Clears responses from the response buffers of halfduplex slave controllers.
setABConfiguration
Defines DF1 protocol configuration parameters.
TCP/IP Communications
The SCADAPack 350 and SCADAPack 357 controllers have one 10/100BaseT
Ethernet port.
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/.
Document (Version 1.61) 5/19/2011
78
Overview of Programming Functions
These functions are supported on the SCADAPack 350 controllers.
Modbus IP Functions
The ctools.h file defines the following Modbus IP related functions. Refer to the
Function Specification section for details on each function listed.
mTcpSetConfig
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.
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.
Data Log to File
The SCADAPack 330 and SCADAPack 350 controllers 4203 support data
logging to the internal file system and data logging to a mass storage device
connected via the USB host port.
Data Log Functions
dlogCreate
Create a data log using the specified configuration.
dlogDelete
Delete a data log and associated resources except log
files.
dlogDeleteAll
Delete data logs and associated resources except log
files.
dlogID
Return the ID of an existing data log.
dlogWrite
Write to a data log.
dlogSpace
Return the space available in the data log buffer.
Document (Version 1.61) 5/19/2011
79
Overview of Programming Functions
dlogFlush
Flush data log buffer contents to log file.
dlogNewFile
Create a new data log file.
dlogSuspend
Suspend writing to the data log file from the data log
buffer.
dlogResume
Resume writing to a suspended data log file.
dlogGetStatus
Return the auto transfer and media status information of
a data log.
Data Log Enumeration Types
The ctools.h file defines the following enumeration types:
dlogStatus Type
dlogTransferStatus Type
dlogConfiguration Type
dlogRecordElement Type
dlogCMITime Type
Refer to the C Tools Structures and Types section for complete information on
structures and enumeration types.
Sockets API
These functions provide support for the BSD 4.4 Socket API. Additional Socket
Extension functions are also provided. These apply specifically to the
SCADAPack 350 TCP/IP Stack.
Refer to the Function Specification section for details on each function listed.
accept
listen
bind
ntohl
connect
ntohs
getpeername
readv
getsockname
recv
getsockopt
recvfrom
htonl
rresvport
htons
select
inet_addr
send
inet_aton
sendto
setsockopt
shutdown
socket
Document (Version 1.61) 5/19/2011
80
Overview of Programming Functions
Modbus I/O Database
The Modbus database is a user-defined database that allows data to be shared
between Telepace or IEC 61131-1 programs, C++ programs and communication
protocols.
Telepace and IEC 61131-1 firmware support different ranges of Modbus
Database registers. The following table shows the register ranges for these
firmware types.
Telepace
Modbus
Addresses
IEC 61131-1
Modbus
Addresses
Data Type
00001 to
04096
00001 to
09999
10001 to
14096
10001 to
19999
30001 to
39999
40001 to
49999
30001 to
39999
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 digital output
modules or SCADAPack I/O modules through the Register Assignment. Coil
registers may also be assigned to controller on-board digital outputs and to
system configuration modules.
Status Registers
Status, or digital input, database registers may be assigned to 5000 digital input
modules or SCADAPack I/O modules through the Register Assignment. Status
registers may also be assigned to controller on-board digital inputs and to system
diagnostic modules.
Input Registers
Input, or analog input, database registers may be assigned to 5000 analog input
modules or SCADAPack I/O modules through the Register Assignment. Input
registers may also be assigned to controller internal analog inputs and to system
diagnostic modules.
Holding Registers
Document (Version 1.61) 5/19/2011
81
Overview of Programming Functions
Holding, or analog output, database registers may be assigned to 5000 analog
output modules or SCADAPack analog output modules through the Register
Assignment. Holding registers may also be assigned to system diagnostic and
configuration modules.
Modbus I/O Database Functions
There are several library functions related to the Modbus database. Refer to the
Function Specification section for details on each function listed.
dbase
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-1
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-1
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.
MODBUS
Specifies Modbus database addressing.
NUMAB
Number of registers in the Allan-Bradley database.
NUMCOIL
Number of registers in the Modbus coil section.
NUMHOLDING
Number of registers in the Modbus holding register
section.
NUMINPUT
Number of registers in the Modbus input registers
section.
NUMLINEAR
Number of registers in the linear database.
NUMSTATUS
Number of registers in the Modbus status section.
START_COIL
Start of the coil section in the linear database.
Document (Version 1.61) 5/19/2011
82
Overview of Programming Functions
START_HOLDING
Start of the holding registers section in the linear
database.
START_INPUT
Start of the input register section in the linear database.
START_STATUS
Start of the status section in the linear database.
Register Assignment
I/O hardware that is used by the controller needs to be assigned to I/O database
registers in order for these I/O points to be scanned continuously. I/O data may
then be accessed through the I/O database within the C program. C programs
may read data from, or write data to the I/O hardware through user- assigned
registers in the I/O database.
The Register Assignment assigns 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 stops invalid register assignments, use
the Telepace Register Assignment dialog to initially build the Register
Assignment. The Register Assignment can then be saved in a Ladder Logic file
(e.g. filename.lad) and downloaded with the C program.
Register Assignment Functions
There are several library functions related to register assignment. Refer to the
Function Specification section for details on each function listed.
clearRegAssignment Erases the current Register Assignment.
addRegAssignment
Adds one I/O module to the current Register
Assignment.
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.
Document (Version 1.61) 5/19/2011
83
Overview of Programming Functions
Register Assignment Structure
The ctools.h file defines the structure RegAssign. Refer to the C Tools Structures
and Types section for complete information on structures and enumeration types.
IEC 61131-1 Variable Access Functions
Variables declared in an IEC 61131-1 application are accessed from a C
application using the IEC 61131-1 variable access functions listed below. Refer
to the Function Specification section for details on each function listed.
readBoolVariable
Returns the current value of the specified boolean
variable.
readIntVariable
Returns the current value of the specified integer
variable.
readRealVariable
Returns the current value of the specified real variable.
readMsgVariable
Returns the current value of the specified message
variable.
readTimerVariable
Returns the current value of the specified timer variable.
writeBoolVariable
Writes to the specified boolean variable.
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.
The HART protocol driver provides communication between SCADAPack
controllers and HART devices. The protocol driver uses the model 5904 HART
modem for communication. Four HART modem modules are supported per
controller.
The driver allows HART transmitters to be used with C application programs and
with Realflo. The driver can read data from HART devices.
HART Command Functions
The ctools.h file defines the following HART command related functions. Refer to
the Function Specification section for details on each function listed.
hartIO
Document (Version 1.61) 5/19/2011
Reads data from the 5904 interface module, processes
HART responses, processes HART commands, and
writes commands and configuration data to the 5904
interface module.
84
Overview of Programming Functions
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.
HART Command Structures
The ctools.h file defines five structures. Refer to the C Tools Structures and
Types section for complete information on structures and enumeration types.
HART_DEVICE
type is a structure containing information about the
HART device.
HART_VARIABLE
type is a structure containing a variable read from a
HART device.
HART_SETTINGS
type is a structure containing the configuration for the
HART modem module.
HART_COMMAND
type is a structure containing a command to be sent to a
HART slave device.
HART_RESPONSE
type is a structure containing a response from a HART
slave device.
Document (Version 1.61) 5/19/2011
85
Overview of Programming Functions
File Management API
File management library functions are provided by the GNU libraries that are
installed with C++ Tools. Documentation of these functions is included in the
installed document “GNU Documentation”.
The functions listed below are recommended for file access:
clearerr
closedir
fclose
feof
fflush
fgetc
fgets
fopen
fprintf
fputc
fputs
fread
fseek
ftell
fwrite
getc
gets
mkdir
opendir
putc
puts
readdir
remove
rmdir
Document (Version 1.61) 5/19/2011
86
Function Specifications
Function Specifications
This section of the user manual contains specifications for using each of the
available functions. The functions in the sections that follow are available for use
in C++ programs. These functions are available for use with both Telepace and
IEC 61131-1 firmware unless otherwise noted.
Functions Supported by Telepace Only
The following functions are only supported by C++ Tools running on Telepace
firmware:

addRegAssignment

clearRegAssignment

getForceFlag

getOutputsInStopMode

overrideDbase

setForceFlag

setOutputsInStopMode
Functions Supported by IEC 61131-1 Only
The following functions are only supported by C++ Tools running on IEC 61131-1
firmware:

Dbase Handler Function

installDbaseHandler

installSetdbaseHandler

readBoolVariable

readIntVariable

readMsgVariable

readRealVariable

readTimerVariable

read_timer_info

Setdbase Handler Function

writeBoolVariable

writeIntVariable
Document (Version 1.61) 5/19/2011
87
Function Specifications

writeMsgVariable

writeRealVariable

writeTimerVariable
Document (Version 1.61) 5/19/2011
88
Function Specifications
accept
Syntax
include <ctools.h>
int accept
(
int socketDescriptor,
struct sockaddr * addressPtr,
int * addressLengthPtr
);
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.
Parameters
socketDescriptor
The socket descriptor that was created with socket and
bound to with bind and is listening for connections with listen.
addressPtr
The structure to write the incoming address into.
addressLengthPtr
Initially, it contains the amount of space pointed to by
addressPtr. On return it contains the length in bytes of the address returned.
Returns
New Socket Descriptor or –1 on error.
If accept fails, the errorCode can be retrieved with
getErrorCode(socketDescriptor) which will return one of the following error
codes:
EBADF
The socket descriptor is invalid.
EINVAL addressPtr was a null pointer.
Document (Version 1.61) 5/19/2011
89
Function Specifications
EINVAL
addressLengthPtr was a null pointer.
EINVAL
The value of addressLengthPtr was too small.
ENOBUFS
operation.
There was insufficient user memory available to complete the
EPERM
Cannot call accept without calling listen first.
EOPNOTSUPP
The referenced socket is not of type SOCK_STREAM.
EPROTO
A protocol error has occurred; for example, the connection has
already been released.
EWOULDBLOCK
The socket is marked as non-blocking and no
connections are present to be accepted.
Document (Version 1.61) 5/19/2011
90
Function Specifications
addRegAssignment
Add Register Assignment (Telepace firmware only)
Syntax
#include <ctools.h>
BOOLEAN addRegAssignment(
UINT16 moduleType,
INT16 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:
Document (Version 1.61) 5/19/2011
AIN_520xT
emperature
CNTR_
5410
AIN_520xR
AMBattery
DIAG_c
ommSt
atus
AIN_5501
DIAG_c
ontrolle
rStatus
AIN_5502
DIAG_f
orceLE
D
AIN_5503
DIAG_I
PConn
ections
AIN_5504
DIAG_
Modbus
Status
AIN_5505
DIAG_p
rotocol
Status
AIN_5506
DIN_54
01
AIN_5521
DIN_54
02
AIN_generi
c8
DIN_54
03
91
Function Specifications
Document (Version 1.61) 5/19/2011
AOUT_530
1
DIN_54
04
AOUT_530
2
DIN_54
05
AOUT_530
4
DIN_54
14
AOUT_gen
eric2
DIN_54
21
AOUT_gen
eric4
DIN_ge
neric16
CNFG_590
4Modem
DIN_ge
neric8
CNFG_clea
rPortCounte
rs
DOUT_
5401
CNFG_clea
rProtocolCo
unters
DOUT_
5402
CNFG_IPS
ettings
DOUT_
5406
CNFG_LED
Power
DOUT_
5407
CNFG_mod
busIpProtoc
ol
DOUT_
5408
CNFG_MT
CPIfSetting
s
DOUT_
5409
CNFG_MT
CPSettings
DOUT_
5411
CNFG_PID
Block
DOUT_
5415
CNFG_port
Settings
DOUT_
generic
16
CNFG_prot
ocolExtend
ed
DOUT_
generic
8
CNFG_prot
ocolExtend
edEx
SCADA
Pack_A
OUT
92
Function Specifications
CNFG_prot
ocolSetting
s
SCADA
Pack_lo
werIO
CNFG_real
TimeClock
SCADA
Pack_u
pperIO
CNFG_sav
eToEEPRO
M
SCADA
Pack_L
PIO
CNFG_setS
erialPortDT
R
SCADA
Pack_2
IO
CNFG_stor
eAndForwa
rd
SCADA
Pack_1
00IO
SCADASE
NSE_4203_
DR
SCADA
Pack_5
606IO
CNTR_520
xCounterIn
puts
SCADA
SENSE
_4203_
DS
SCADAPac
k_33xIO
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.
Document (Version 1.61) 5/19/2011
93
Function Specifications
Notes
Up to 150 modules may be added to the Register Assignment. If the Register
Assignment is full or if an incorrect value is specified for any argument this
function returns FALSE; otherwise TRUE is returned.
Output registers specified for certain CNFG type modules are initialized with the
current parameter values when the module is added to the Register Assignment
(e.g. CNFG_realTimeClock).
Call clearRegAssignment first before using the addRegAssignment function
when creating a new Register Assignment.
Duplicate or overlapping register assignments are not checked for by this
function. Overlapping register assignments may result in unpredictable I/O
activity.
To obtain error checking that avoids invalid register assignments such as these,
use the Telepace Register Assignment dialog to build the Register Assignment.
Then save the Register Assignment in a Ladder Logic file (e.g. filename.lad) and
download it with the C program, or transfer the Register Assignment to the C
program using the clearRegAssignment and addRegAssignment functions.
To save the Register Assignment with the controller settings in flash memory so
that it is loaded on controller reset, call flashSettingsSave as shown in the
example below.
The IO_SYSTEM resource needs to be requested before calling this function.
See Also
clearRegAssignment
Example
#include <ctools.h>
int main(void)
{
request_resource(IO_SYSTEM);
/* Create the Register Assignment */
clearRegAssignment();
addRegAssignment(SCADAPack_2IO, 0, 1,
10001, 30001, 40001);
addRegAssignment(AOUT_5302, 1, 40003, 0, 0, 0);
addRegAssignment(DIAG_forceLED, -1, 10017, 0, 0, 0);
addRegAssignment(DIAG_controllerStatus, -1,
30009, 0, 0,
0);
addRegAssignment(DIAG_protocolStatus, 2, 30010, 0, 0, 0);
release_resource(IO_SYSTEM);
// save register assignment with controller settings
Document (Version 1.61) 5/19/2011
94
Function Specifications
request_resource(FLASH_MEMORY);
flashSettingsSave(CS_PERMANENT);
release_resource(FLASH_MEMORY);
}
Document (Version 1.61) 5/19/2011
95
Function Specifications
addRegAssignmentEx
Add Register Assignment (Telepace firmware only)
Syntax
#include <ctools.h>
BOOLEAN addRegAssignmentEx(
UINT16 moduleType,
INT16 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_5505
AIN_5506
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
Document (Version 1.61) 5/19/2011
CNTR_5410
DIAG_commStatus
DIAG_controllerStatus
DIAG_forceLED
DIAG_IPConnections
DIAG_ModbusStatus
DIAG_protocolStatus
DIN_5401
DIN_5402
DIN_5403
DIN_5404
DIN_5405
DIN_5414
DIN_5421
DIN_generic16
DIN_generic8
DOUT_5401
DOUT_5402
DOUT_5406
DOUT_5407
DOUT_5408
DOUT_5409
DOUT_5411
DOUT_5415
96
Function Specifications
CNFG_portSettings
DOUT_generic16
CNFG_protocolExtended
DOUT_generic8
CNFG_protocolExtendedEx
SCADAPack_AOUT
CNFG_protocolSettings
SCADAPack_lowerIO
CNFG_realTimeClock
SCADAPack_upperIO
CNFG_saveToEEPROM
SCADAPack_LPIO
CNFG_setSerialPortDTR
SCADAPack_2IO
CNFG_storeAndForward
SCADAPack_100IO
SCADASENSE_4203_DR
SCADAPack_5606IO
CNTR_520xCounterInputs
SCADASENSE_4203_DS
SCADAPack_5607IO
SCADAPack_33xIO
SCADAPack_350IO
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. Many modules do not use the parameters and a 0 needs to be specified
for the parameters. Use the addRegAssignment function to configure these
modules. Use parameters with the following modules.
5414 I/O Module: parameter [0] defines the input type. Valid values are:

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
Document (Version 1.61) 5/19/2011
97
Function Specifications
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

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)
Document (Version 1.61) 5/19/2011
98
Function Specifications

1 = 6 Hz

2 = 11 Hz

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
5607 I/O Module: parameters[0] to [7] define the analog input type for the
corresponding input. The remaining parameters are not used. Valid values are:

0 = 0 to 5 V input

1 = 0 to 10 V input

2 = 0 to 20 mA input

3 = 4 to 20 mA input
5607 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)
5607 I/O Module: parameters[9] defines the scan frequency. Valid values are:

0 = 60 Hz

1 = 50 Hz
5607 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.
Document (Version 1.61) 5/19/2011
99
Function Specifications
Output registers specified for certain CNFG type modules are initialized with the
current parameter values when the module is added to the Register Assignment
(e.g. CNFG_realTimeClock).
Call clearRegAssignment first before using the addRegAssignmentEx function
when creating a new Register Assignment.
Duplicate or overlapping register assignments are not checked for by this
function. Overlapping register assignments may result in unpredictable I/O
activity.
To obtain error checking that avoids invalid 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>
int main(void)
{
UINT16 parameters[16];
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);
Document (Version 1.61) 5/19/2011
100
Function Specifications
// save register assignment with controller settings
request_resource(FLASH_MEMORY);
flashSettingsSave(CS_PERMANENT);
release_resource(FLASH_MEMORY);
}
Document (Version 1.61) 5/19/2011
101
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 to be requested before calling this function.
See Also
setClockAlarm
Document (Version 1.61) 5/19/2011
102
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 1.61) 5/19/2011
103
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 1.61) 5/19/2011
104
Function Specifications
bind
Bind an address to an unnamed socket
Syntax
#include <ctools.h>
int bind(
int socketDescriptor,
const struct sockaddr * addressPtr,
int addressLength);
Description
bind assigns an address to an unnamed socket. When a socket is created with
socket, it exists in an address family space but has no address assigned. bind
requests that the address pointed to by 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.
Multiple sockets cannot bind to the same port with different IP addresses (as
might be allowed in UNIX)
Parameters
socketDescriptor
number to.
addressPtr
The socket descriptor to assign an IP address and port
The pointer to the structure containing the address to assign.
addressLength The length of the address structure.
Returns
0
Success
-1
An error occurred
bind can fail for any of the following reasons:
EADDRINUSE The specified address is already in use.
EBADF
socketDescriptor is not a valid descriptor.
EINVAL
bound.
One of the passed parameters is invalid, or socket is already
EINPROGRESS
Document (Version 1.61) 5/19/2011
bind is already running.
105
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.
Document (Version 1.61) 5/19/2011
106
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);
fprintf(com1,"Additive checksum: %u\r\n", sum);
/* Display CRC-16 checksum */
sum = checksum(str, str+strlen(str), CRC_16);
fprintf(com1,"CRC-16 checksum: %u\r\n", sum);
}
Document (Version 1.61) 5/19/2011
107
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
clearSFTranslationTable
Example
See the example for the setSFTranslationEx function.
Document (Version 1.61) 5/19/2011
108
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 must be requested before calling this function.
See Also
setForceFlag, getForceFlag, overrideDbase
Document (Version 1.61) 5/19/2011
109
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 1.61) 5/19/2011
110
Function Specifications
clear_errors
Clear Serial Port Error Counters
Syntax
#include <ctools.h>
void clear_errors(UCHAR port);
Description
The clear_errors function clears the serial port error counters for the serial port
specified by port. If port is not a valid serial port the function has no effect.
The IO_SYSTEM resource needs to be requested before calling this function.
Document (Version 1.61) 5/19/2011
111
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 port. If port is not a valid serial port the function has no
effect.
The IO_SYSTEM resource needs to be requested before calling this function.
Document (Version 1.61) 5/19/2011
112
Function Specifications
clearLoginCredentials
Clears all configured usernames and passwords for the specified service
Syntax
#include <ctools.h>
BOOLEAN clearLoginCredentials(
UINT32 service
);
Parameters
service specifies the service for which the credentials are being cleared.
Description
The clearLoginCredentials function removes all configured usernames and
passwords from the specified service. True is returned if the usernames and
passwords were removed. False is returned if the usernames and passwords
could not be removed.
Notes
Valid services are:
0 = FTP
See Also
setLoginCredentials, getLoginCredentials
Document (Version 1.61) 5/19/2011
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 must be requested before calling this function.
See Also
addRegAssignment
Example
See example for addRegAssignment.
Document (Version 1.61) 5/19/2011
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 1.61) 5/19/2011
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 – all leading zeros are ignored.
There is a two-second delay between repetitions.
The STAT LED is located on the top left hand corner of the controller board.
Bits 0, 1 and 2 of the status code are used by the controller firmware. Attempting
to control these bits will result in indeterminate operation.
See Also
setStatusBit, getStatusBit
Document (Version 1.61) 5/19/2011
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
port. If port is not a valid serial port the function has no effect.
Document (Version 1.61) 5/19/2011
117
Function Specifications
close
Syntax
#include <ctools.h>
int close
(
int socketDescriptor
);
Description
This function is used to close a socket.
Parameters
socketDescriptor
The socket descriptor to close
Returns
0
Operation completed successfully
-1
An error occurred
close can fail for the following reasons:
TM_EBADF
The socket descriptor is invalid.
TM_ESHUTDOWN
A write shutdown has already been performed on the
socket (TCP socket only).
TM_EALREAY A previous close call is already in progress.
TM_ECONNABORTED The TCP connection was reset because the linger option
was on with a timeout value of 0 (TCP socket only).
TM_ETIMEDOUT
The linger option was on with a non-zero timeout value,
and the linger timeout expired before the TCP close handshake with the remote
host could complete (blocking TCP socket only).
Document (Version 1.61) 5/19/2011
118
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 1.61) 5/19/2011
119
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.
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.
Document (Version 1.61) 5/19/2011
120
Function Specifications
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-1 applications. The second logic application identifier is not
used with other controllers. 32 application identifiers are provided to
accommodate C applications in SCADAPack 330/350 controllers.
These registers cannot be used for other purposes in logic or C/C++ application.
This includes the following uses:

masterMessage function that uses 39800 to 39999 as destination registers.

setForceFlag function that use 39800 to 39999 as destination registers.

Any registerAssignment that uses registers 39800 to 39999.
Register
Data Type
Description
39800
uchar[8]
39808
39809
39810
39813
39816
uint
uint
uint[3]
uint[3]
uint
39817
39820
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)
Document (Version 1.61) 5/19/2011
121
Function Specifications
Register
Data Type
Description
39823
39826
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]
uint[3]
uint[3]
Application identifier 3 (see format below)
Application identifier 4 (see format below)
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
Company ID (see below)
Application number (0 to 65535)
Document (Version 1.61) 5/19/2011
122
Function Specifications
uint
Application version (major*100 + minor)
Company Identifier
Control Microsystems will maintain a list of company identifiers to keep the
company IDs is unique. Contact the technical support department.
Company ID 0 indicates an identifier is unused.
See Also
configurationRegisterMapping
Notes
Application IDs for C programs are not automatically removed. A task exit
handler can be used to remove the ID when the C application is ended.
Application IDs are cleared when the controller is reset.
Document (Version 1.61) 5/19/2011
123
Function Specifications
connect
Syntax
#include <ctools.h>
int connect
(
int socketDescriptor,
const struct sockaddr * addressPtr,
int addressLength
);
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.
Aa non –blocking connect is allowed. In this case, if the connection has not been
established, the connect call will fail with a EINPROGRESS error code.
Additional calls to connect will fail with EALREADY error code, as long as the
connection has not completed. When the connection has completed, additional
calls to connect will return with no error to indicate that the connection is now
established.
Parameters
socketDescriptor
The socket descriptor to assign a name (port number) to.
addressPtr
The pointer to the structure containing the address to
connect to for TCP. For UDP it is the default address to
send to and the only address to receive from.
addressLength The length of the address structure.
Returns
0
Success
-1
An error occurred.
connect can fail for any of the following reasons:
EADDRINUSE
Document (Version 1.61) 5/19/2011
The socket address is already in use. The calling
program should close the socket descriptor, and issue
124
Function Specifications
another socket call to obtain a new descriptor before
attempting another connect call.
EADDRNOTAVAIL
The specified address is not available on the remote /
local machine.
EAFNOSUPPORT
Addresses in the specified address family cannot be
used with this socket.
EINPROGRESS
The socket is non-blocking and the current connection
attempt has not yet been completed.
EALREADY
The socket is non-blocking and a previous connection
attempt has not yet been completed.
EBADF
socketDescriptor is not a valid descriptor.
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.
EPERM
Cannot call connect after listen call.
EINVAL
One of the parameters is invalid
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.
EHOSTUNREACH
No route to the host we want to connect to.
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).
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 1.61) 5/19/2011
125
Function Specifications
copy
Copy a File
Syntax
#include <ctools.h>
STATUS copy(const char* source, const char* destination);
Description
The copy function copies the file source to the path qualified file name
destination.
If the copy operation failed then ERROR is returned. OK is returned if the copy
operation completed successfully.
See Also
xcopy, xdelete
Document (Version 1.61) 5/19/2011
126
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 to ensure good error
detection. The checksum accumulator is set to initial before the calculation is
started.
Notes
The reverse algorithm is named for the direction bits are shifted. In the reverse
algorithm, bits are shifted towards the least significant bit. This produces different
checksums than the classical, or forward algorithm, using the same polynomials.
See Also
checksum
Document (Version 1.61) 5/19/2011
127
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 lower than the current
executing task.
priority is an execution priority between 0 and 254 for the created task. The
lowest priority is 254, and the highest priority is 0. The 255 task priority levels aid
in scheduling task execution. See the notes below for recommended priority
values.
type specifies if the task is ended when an application program is stopped. Valid
values for type are:
SYSTEM
System tasks do not terminate when the program stops.
applicationGroup
Application tasks terminate when the program stops.
Use this global variable for all calls to create_task by the
same application. The operating system assigns a
unique value to applicationGroup when it is defined in
appstart.cpp.
It is recommended that only application type tasks be created.
The stack parameter specifies how many stack blocks are allocated for the task.
Each stack block is 512 bytes.
The create_task function returns the task ID (TID) of the task created. If an error
occurs, -1 is returned.
Notes
Refer to the Real Time Operating System section for more information on tasks.
The main task and the Ladder Logic and I/O scanning task have a priority of 100.
If the created task is continuously running processing code, create the task with a
priority of 100. The scheduling algorithm of the operating system will give each
task of the same priority time slices to share the CPU.
For tasks such as a protocol handler, that wait for an event using the wait_event
or receive_message function, a priority higher than 100 (e.g. 75) may be selected
without blocking other lower priority tasks.
The number of stack blocks required depends on the functions called within the
task, and the size of local variables created. Tasks usually require 2 stack blocks.
Document (Version 1.61) 5/19/2011
128
Function Specifications
If the fprintf function is used, then at least 5 stack blocks are required. Add local
variable usage to these limits, if large local arrays or structures are created.
Large structures and arrays are usually handled as static global variables within
the task source file. (The variables are global to all functions in the task, but
cannot be seen by functions in other files.)
Additional stack space may be made available by disabling unused protocol
tasks. See the section Program Development or the set_protocol function for
more information.
See Also
end_task
Example
See the Create Task Example in the Examples section.
Document (Version 1.61) 5/19/2011
129
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 1.61) 5/19/2011
130
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 1.61) 5/19/2011
131
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
See example DataLog program in the Example Programs section.
datalogDelete, datalogSettings
Example
This program creates a data log and writes one record to it.
#include <ctools.h>
/* Structure used to copy one record into data log */
struct dataRecord
{
Document (Version 1.61) 5/19/2011
132
Function Specifications
UINT16
INT32
double
float
float
value1;
value2;
value3;
value4;
value5;
};
int 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 1.61) 5/19/2011
133
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.
Example
See example DataLog program in the Example Programs section.
This program shows the only way to change the configuration of an existing log,
which is to delete the log and recreate the data log.
#include <ctools.h>
int 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;
Document (Version 1.61) 5/19/2011
134
Function Specifications
dLogConfig.typesOfFields[3] =
DLV_FLOAT;
dLogConfig.typesOfFields[4] =
DLV_FLOAT;
datalogCreate(logID, &dLogConfig);
}
else
{
/* could not delete log */
}
}
}
else
{
/* Could not read settings */
}
}
Document (Version 1.61) 5/19/2011
135
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
See example DataLog program in the Example Programs section.
datalogReadStart, datalogReadNext, datalogWrite
Example
#include <ctools.h>
int main(void)
{
UINT16 logID;
UINT32 sequenceNumber;
BOOLEAN purgeAll;
Document (Version 1.61) 5/19/2011
136
Function Specifications
/* select data log to be purged */
logID = 10;
/* set flag to purge only part of data log */
purgeAll = FALSE;
/* purge the oldest 150 records */
sequenceNumber = 150;
if(datalogPurge(logID, purgeAll, sequenceNumber))
{
/* Successful at purging the first 150 records of
log. */
/* Start writing records again. */
}
/* To purge the entire data log, set flag to TRUE */
purgeAll = TRUE;
/* call function with same parameters */
if( datalogPurge(logID, purgeAll, sequenceNumber) )
{
/* Successful at purging the entire data log. */
/* Start writing records again. */
}
}
Document (Version 1.61) 5/19/2011
137
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 1.61) 5/19/2011
138
Function Specifications
See Also
See example DataLog program in the Example Programs section.
datalogReadStart, datalogPurge, datalogWrite
Example
See the example for datalogReadStart.
Document (Version 1.61) 5/19/2011
139
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
See example DataLog program in the Example Programs section.
datalogReadNext, datalogPurge, datalogWrite
Example
#include <ctools.h>
#include <stdlib.h>
int main(void)
{
UINT16 logID, recordSize, *pData;
UINT32 sequenceNumber, seqNumRead, nextSeqNum;
/* Select data log #10 */
logID = 10;
/* Find first record in data log #10 and store
its sequence number in sequenceNumber
*/
if(datalogReadStart(logID, &sequenceNumber))
{
/* Get the size of this record */
Document (Version 1.61) 5/19/2011
140
Function Specifications
if(datalogRecordSize(logID, &recordSize))
{
/* allocate memory of size recordSize */
pData = (UINT16 *)malloc(recordSize);
/* read this record */
if(datalogReadNext(logID, sequenceNumber,
&seqNumRead, &nextSeqNum, pData))
{
/* use pData to access record contents
*/
}
}
}
}
Document (Version 1.61) 5/19/2011
141
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
See example DataLog program in the Example Programs section.
datalogSettings
Example
See the example for datalogReadStart.
Document (Version 1.61) 5/19/2011
142
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
See example DataLog program in the Example Programs section.
datalogRecordSize
Example
See example for datalogDelete.
Document (Version 1.61) 5/19/2011
143
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
See example DataLog program in the Example Programs section.
datalogReadStart, datalogReadNext, datalogPurge
Example
See the example for datalogReadStart.
Document (Version 1.61) 5/19/2011
144
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>
int main(void)
{
int a;
request_resource(IO_SYSTEM);
/* Read Modbus status input point */
a = dbase(MODBUS, 10001);
/* Read 16 bit register */
a = dbase(LINEAR, 3020);
/* Read 16 bit register beginning at first
status register */
Document (Version 1.61) 5/19/2011
145
Function Specifications
a = dbase(LINEAR, START_STATUS);
/* Read 6th input register */
a = dbase(LINEAR, START_INPUT + 5);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
146
Function Specifications
Dbase Handler Function
User Defined Dbase Handler Function
The dbase handler function is a user-defined function that handles reading of
Modbus addresses not assigned in the IEC 61131-1 Dictionary. The function can
have any name; dbaseHandler is used in the description below.
Syntax
#include <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-1 application downloaded, or

There is no IEC 61131-1 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 allows that only one task may
call the handler at a time. Therefore, the function does not have to be re-entrant.
An array may be defined to store the current values for all Modbus addresses
handled by this function. See the section Data Storage if a non-initialized data
array is required.
See Also
installDbaseHandler
Document (Version 1.61) 5/19/2011
147
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 1.61) 5/19/2011
148
Function Specifications
dlogCreate
Create a data log using the specified configuration.
Syntax
#include <ctools.h>
dlogStatus dlogCreate(
dlogConfiguration *pConfiguration,
UINT32 *dlogID
)
Parameters
The function has these parameters:

pConfiguration is a pointer to a data log configuration structure containing the
data log configuration. See the description of the configuration structure for
details on the parameters that can be configured in the data log.

dlogID is a pointer to a variable where the data log ID will be written if the
function is successful. If the pointer is NULL, the creation of the data log will
fail and the function will return DLOGS_FAILURE.
The function returns:

DLOGS_SUCCESS if the log could be created. Valid dlogID returned as
output parameter.

DLOGS_EXISTS if a log exists with same configuration parameters. Valid
dlogID returned as output parameter.

DLOGS_DIFFERENT if a log with the same name exists with different
parameters. The dlogID is not valid.

DLOGS_NOMEMORY if the log could not be created due to lack of memory.
The dlogID is not valid.

DLOGS_INVALID if the configuration data is not valid. The dlogID is not
valid.

DLOGS_FAILURE if an error occurred during creation of the log. The dlogID
is not valid.

DLOGS_WRONGPARAM if an error occurred due to a wrong parameter.
Description
A data log has to be created before any client can log data records. The
configuration structure contains a data log name. It is a string which is used to
build the log file names. Each data log name has to be unique; a data log
creation will fail if one already exists with the same name. A data log name can
also contain a path. Therefore it is possible to have log files with the same prefix
naming but in different directories (e.g. “DIR1/LOG1” and “DIR2/LOG1”). The
Document (Version 1.61) 5/19/2011
149
Function Specifications
relative data log name will be combined with the drive name depending on the
configuration.
The dlogCreate call creates a data log instance. The data log specific buffer,
configuration and run time data are allocated in dynamic non-volatile memory.
Data log files are not created – these are created as needed by the data log
server.
If dlogCreate is called for an existing data log, the configuration parameters are
compared. If they are the same, the function returns a valid dlogID with a warning
return value (DLOGS_EXISTS). If they are different, the function returns with the
error DLOGS_DIFFERENT.
Data Log data is stored in non-volatile memory. If this memory cannot be
allocated dlogCreate returns DLOGS_NOMEMORY.
dlogCreate returns in an output parameter a data log ID which is used for further
operations on the data log. A newly created data log won‟t reuse a recently
deleted ID, although the ID will eventually recycle if enough logs are created.
Document (Version 1.61) 5/19/2011
150
Function Specifications
dlogDelete
Delete a data log and all associated resources except log files
Syntax
#include <ctools.h>
dlogStatus dlogDelete(UINT32 dlogID)
Parameters
The function has these parameters:

dlogID is the ID of the data log to be deleted.
The function returns:

DLOGS_SUCCESS if the data log was deleted

DLOGS_BADID if the data log ID is not valid.

DLOGS_FAILURE if the data log could not be deleted.
Description
This function deletes a data log. The memory for the log is freed. The data log ID
is marked as invalid. The data log server will not collect further records for this
log ID. The directory file is deleted if it is accessible. This might be not the case if
data log files were written to removable media. The data log name is removed
from the master log file.
Data Log files are not deleted. If the log was created with a path, the created
directory still exists after the log is deleted.
Document (Version 1.61) 5/19/2011
151
Function Specifications
dlogDeleteAll
Delete all data logs and all associated resources except log files
Syntax
#include <ctools.h>
dlogStatus dlogDeleteAll()
Parameters
The function has no parameters.
The function returns:

DLOGS_SUCCESS if all data logs were deleted

DLOGS_FAILURE if all data logs could not be deleted
Description
This function deletes all data logs. The memory for the logs is freed. The data log
IDs are marked as invalid. The data log server will not collect further records.
Directory files are deleted if they are accessible. This might be not the case if
data log files were written to removable media. The data log names are removed
from the master log files.
Data Log files are not deleted. If a log was created with a path, the created
directory still exists after the log is deleted.
Document (Version 1.61) 5/19/2011
152
Function Specifications
dlogFlush
Flush data log buffer contents to log file
Syntax
#include <ctools.h>
dlogStatus dlogFlush(UINT32 dlogID)
Parameters
The function has these parameters:

dlogID is the ID of the data log.
The function returns:

DLOGS_SUCCESS if the data log was flushed. This indicates that as much
data was flushed as was possible to be flushed under current conditions.

DLOGS_BADID if the data log ID is invalid.

DLOGS_FAILURE if existing data cannot be flushed
Description
A dlogWrite call writes a data log record to a data log buffer. This buffer is written
regularly to the log file by the data log server. The dlogFlush function explicitly
flushes data log buffer contents to the log file.
The function flushes all or part of the buffer to the file, depending on the current
file conditions and buffer contents. If files are full, logging is suspended, or
external media is removed, the flush might not remove any records from the
buffer. If this is the case, the function returns DLOGS_FAILURE.
The file remains open after flushing. To close a file in preparation for moving it or
removing external media, use the dlogSuspend function.
See Also
dlogSuspend
Document (Version 1.61) 5/19/2011
153
Function Specifications
dlogGetStatus
Return the auto transfer and media status information of a data log
Syntax
#include <ctools.h>
dlogStatus dlogGetStatus(UINT32 dlogID, dlogTransferStatus
*transferStatus, dlogMediaStatus *mediaStatus, BOOLEAN
*extMediaInUse
)
Parameters
The function has these parameters:

dlogID is the ID of the data log.

transferStatus is a pointer to memory where the transfer status is written to.

mediaStatus is a pointer to memory where the media status is written to.

extMediaInUse is a pointer to memory where it is written if the external media
is in use or not.
The function returns:

DLOGS_SUCCESS if status information was retrieved.

DLOGS_BADID if the data log ID is invalid.
Description
This function returns the transfer status, media status, and “external media in
use” information of a particular data log. The transfer status indicates the result
or the progress of a recent triggered auto-transfer to a removable mass storage
device. The media status indicates the presence of log media and if it provides
space for dlog operations. The “external media in use“ Boolean value shows
TRUE if the external media is in use, FALSE otherwise. Please refer to the
chapters dlogTransferStatus Type and dlogMediaStatus Type for the status
values.
DLOGS_SUCCESS is returned if the status information could be retrieved. The
only reason not be able to do this is because the input parameter dlogID is
wrong, which would result in the return value DLOGS_BADID.
Document (Version 1.61) 5/19/2011
154
Function Specifications
dlogID
Return the ID of an existing data log
Syntax
#include <ctools.h>
dlogStatus dlogID(
UCHAR * dlogName,
UINT32 * dlogID
)
Parameters
The function has these parameters:

dlogName is a null-terminated string containing the name of the data log.

dlogID is a pointer to a variable where the data log ID will be written if the
function is successful.
The function returns:

DLOGS_SUCCESS if the data log ID was retrieved

DLOGS_FAILURE if an error during data log ID retrieval occurred

DLOGS_WRONGPARAM if an error due to wrong parameter
Description
This function maps a data log name to an ID which is used for further operations
to the data log. To obtain the data log ID the data log under the specified name
has to exist.
Document (Version 1.61) 5/19/2011
155
Function Specifications
dlogNewFile
Create a new data log file
Syntax
#include <ctools.h>
dlogStatus dlogNewFile(UINT32 dlogID)
Parameters
The function has these parameters:

dlogID is the ID of the data log.
The function returns:

DLOGS_SUCCESS if the new data log was created.

DLOGS_BADID if the data log ID is invalid.
Description
This function creates a new data log file which becomes the active data log
output file. The former active file is closed and won‟t be used for any further
output.
This function is useful to give the data log client the opportunity to create a new
data file by its own definition, not just when the defined log file size is exceeded.
A data log client could create daily files, for example.
Notes
The new file is not created immediately but when the first data log record is
written from the data log buffer by the data log server task. Records that remain
in the data log buffer when this function is called are not flushed automatically.
To start the new file with a specific record, call dlogFlush before calling this
function.
The oldest file will be deleted if fileRingBuffer mode is enabled and the maximum
number of files is reached. If fileRingBuffer mode is disabled no new file will be
created until older log files are deleted manually. This may cause logging to stop
(although the space in the log buffer may still be available).
See Also
dlogFlush, dlogWrite
Document (Version 1.61) 5/19/2011
156
Function Specifications
dlogResume
Resume writing to a suspended data log file
Syntax
#include <ctools.h>
dlogStatus dlogResume(UINT32 dlogID)
Parameters
The function has these parameters:

dlogID is the ID of the data log.
The function returns:

DLOGS_SUCCESS if logging was resumed.

DLOGS_BADID if the data log ID is invalid.
Description
This function resumes writing to a previously suspended data log.
If external media is configured for the data log the first connected drive name is
retrieved. If data log configuration files are not present they are created
immediately. The data log file is created when the first data log record is written
from the log buffer.
A dlogResume call on an already active data log has no impact.
See Also
dlogSuspend
Document (Version 1.61) 5/19/2011
157
Function Specifications
dlogSpace
Return the space available in the data log buffer
Syntax
#include <ctools.h>
dlogStatus dlogSpace(
UINT32 dlogID,
UINT32 * pBufferRecords
)
Parameters
The function has these parameters:

dlogID is the ID of the data log.

pBufferRecords is a pointer a variable to hold the number of records in the
buffer.
The function returns:

DLOGS_SUCCESS if the number of records was returned.

DLOGS_BADID if the data log ID is invalid.

DLOGS_WRONGPARAM if an error due to wrong parameter happened

DLOGS_FAILURE if an unexpected error happened.
Description
This function returns the number of records remaining in the data log buffer for
the log. This determines how many records the data log server can be written to
the log without data loss.
Document (Version 1.61) 5/19/2011
158
Function Specifications
dlogSuspend
Suspend writing to the data log file from the data log buffer
Syntax
#include <ctools.h>
dlogStatus dlogSuspend(UINT32 dlogID)
Parameters
The function has these parameters:

dlogID is the ID of the data log.
The function returns:

DLOGS_SUCCESS if logging was suspended.

DLOGS_BADID if the data log ID is invalid.

Description
This function suspends the writing to data log files and closes any open files.
After successful suspension removal or exchange of an external drive is safe, as
is moving files to another device. Nevertheless further calls to dlogWrite are still
allowed and will succeed as long as records fit in the buffer.
dlogSuspend calls dlogFlush to move data log buffer records as possible to file
before the output is suspended.
A repeated call to dlogSuspend has no effect.
See Also
dlogResume
Document (Version 1.61) 5/19/2011
159
Function Specifications
dlogWrite
Write to a data log
Syntax
#include <ctools.h>
dlogStatus dlogWrite(
UINT32 dlogID,
UCHAR * pRecord
)
Parameters
The function has these parameters:

dlogID is the ID of the data log.

pRecord is a pointer to a data record to write to the log.
The function returns:

DLOGS_SUCCESS if the write was successful.

DLOGS_BUFFERFULL if the record could not be written because of a full
buffer

DLOGS_BADID if the data log ID is not valid.

DLOGS_FAILURE if the record could not be written due to a run-time error.
Description
This function writes a record to the data log specified by dlogID. Memory is
copied from the pointer address to the data log buffer. The data is packed as it is
written to the buffer. Gaps due to structure alignments are not written. Packing is
performed using the size and offset information specified during data log
creation.
dlogWrite stores a record sequence number at the start of the record in the
buffer. A CRC16 value is computed for the data including the heading sequence
number and stored at the end of the record.
The data log buffer is flushed regularly to data log files by the data log server
task.
See Also
dlogFlush
Document (Version 1.61) 5/19/2011
160
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 1.61) 5/19/2011
161
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 1.61) 5/19/2011
162
Function Specifications
dnpCreateAddressMappingTable
Create DNP Address Mapping Table
Syntax
#include <ctools.h>
BOOLEAN dnpCreateAddressMappingTable (
UINT16 size,
CHAR enableMapChangeEvents);
Description
The dnpCreateAddressMappingTable function destroys any existing DNP
address mapping table, and allocates memory for a new address mapping table
according to the „size‟ parameter.
Notes
DNP needs to be enabled before calling this function in order to create the DNP
configuration.
The function returns TRUE if successful, FALSE otherwise.
Document (Version 1.61) 5/19/2011
163
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 1.61) 5/19/2011
164
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.
Example
See the example in the dnpGetConfiguration section.
Document (Version 1.61) 5/19/2011
165
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 1.61) 5/19/2011
166
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 1.61) 5/19/2011
167
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 1.61) 5/19/2011
168
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 1.61) 5/19/2011
169
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 1.61) 5/19/2011
170
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 1.61) 5/19/2011
171
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 1.61) 5/19/2011
172
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 1.61) 5/19/2011
173
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 1.61) 5/19/2011
174
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 1.61) 5/19/2011
175
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 1.61) 5/19/2011
176
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 1.61) 5/19/2011
177
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 1.61) 5/19/2011
178
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.
int main(void)
{
UINT16 index;
struct prot_settings settings;
dnpConfiguration configuration;
*/
dnpBinaryInput binaryInput;
*/
dnpBinaryOutput binaryOutput;
*/
dnpAnalogInput analogInput;
*/
dnpAnalogOutput analogOutput;
*/
dnpCounterInput counterInput;
*/
/* loop index */
/* protocol settings */
/* configuration settings
/* binary input settings
/* binary output settings
/* analog input settings
/* analog output settings
/* counter input settings
/* Stop any protocol currently active on com port 2 */
get_protocol(com2,&settings);
settings.type = NO_PROTOCOL;
set_protocol(com2,&settings);
Document (Version 1.61) 5/19/2011
179
Function Specifications
/* Load the Configuration Parameters */
configuration.masterAddress
= DEFAULT_DNP_MASTER;
configuration.rtuAddress
= DEFAULT_DNP_RTU;
configuration.datalinkConfirm
= TRUE;
configuration.datalinkRetries
=
DEFAULT_DLINK_RETRIES;
configuration.datalinkTimeout
=
DEFAULT_DLINK_TIMEOUT;
configuration.operateTimeout
DEFAULT_OPERATE_TIMEOUT;
configuration.applicationConfirm
configuration.maximumResponse
DEFAULT_MAX_RESP_LENGTH;
configuration.applicationRetries
configuration.applicationTimeout
configuration.timeSynchronization
=
= TRUE;
=
= 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++)
Document (Version 1.61) 5/19/2011
180
Function Specifications
{
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++)
{
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++)
Document (Version 1.61) 5/19/2011
181
Function Specifications
{
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++)
{
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 1.61) 5/19/2011
182
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 1.61) 5/19/2011
183
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.
Example
See the example in the dnpGetConfiguration section
Document (Version 1.61) 5/19/2011
184
Function Specifications
dnpGetUnsolicitedBackoffTime
Read the DNP unsolicited resend time.
Syntax
UINT16 dnpGetUnsolicitedBackoffTime();
Description
The dnpGetUnsolicitedBackoffTime function reads the unsolicited resend time
from the controller.
The time is in seconds; and the allowed range is 0-65535 seconds. A value of
zero indicates that the unsolicited resend timer is disabled.
Document (Version 1.61) 5/19/2011
185
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 1.61) 5/19/2011
186
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
This function is the user defined DNP connection handler. It will
be called by internal DNP routines when a connection is required,
when confirmation of a message is received, and when a
communication timeout occurs.
Document (Version 1.61) 5/19/2011
187
Function Specifications
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;
}
}
/* --------------------------------------------------------------Public Functions
--------------------------------------------------------------*/
Document (Version 1.61) 5/19/2011
188
Function Specifications
/* --------------------------------------------------------------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.
--------------------------------------------------------------*/
int main(void)
{
int lastConnectionState;
/* last state of connection
register */
int currentConnectionState;
/* current state of
connection register */
/* install DNP connection handler */
dnpInstallConnectionHandler(sampleDNPHandler);
/* get the current connection state */
lastConnectionState = dbase(MODBUS, CONNECTION_STATUS);
/* loop forever */
while (TRUE)
{
request_resource(IO_SYSTEM);
/* get the current connection state */
currentConnectionState = dbase(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);
}
else
{
/* Inform DNP that the connection is
closed */
dnpConnectionEvent(DNP_DISCONNECTED);
/* clear the message flags */
Document (Version 1.61) 5/19/2011
189
Function Specifications
setdbase(MODBUS, MESSAGE_COMPLETE, 0);
setdbase(MODBUS, MESSAGE_FAILED, 0);
}
/* save the new state */
lastConnectionState = currentConnectionState;
}
/* release the processor so other tasks can run */
release_resource(IO_SYSTEM);
release_processor();
}
}
Document (Version 1.61) 5/19/2011
190
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 only available on the SCADAPack 32, SCADAPack 350 and
4203.
DNP needs to be enabled before calling this function in order to create the DNP
configuration.
Document (Version 1.61) 5/19/2011
191
Function Specifications
dnpMasterClockSync
Send DNP Clock Synchronization
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 only available on the SCADAPack 32, SCADAPack 350 and
4203.
DNP needs to be enabled before calling this function in order to create the DNP
configuration.
Document (Version 1.61) 5/19/2011
192
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 1.61) 5/19/2011
193
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 1.61) 5/19/2011
194
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 1.61) 5/19/2011
195
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 1.61) 5/19/2011
196
Function Specifications
dnpReadMasterPollTableEntryEx
Read DNP Master Poll Table Extended Entry
Syntax
BOOLEAN dnpReadMasterPollTableEntryEx (
UINT16 index,
DnpMasterPollEx_type *pMasterPoll
);
Description
This function is only available on the SCADAPack 32, SCADAPack 350 and
4203.
This function reads an extended entry from the DNP master poll table.
pMasterPoll is a pointer to an extended table entry; it is written by this function.
The return value is TRUE if pMasterPoll was successfully written or FALSE
otherwise.
Notes
This function is only available on the SCADAPack 32, SCADAPack 350 and
4203.
DNP needs to be enabled before calling this function in order to create the DNP
configuration.
This function supersedes the dnpReadMasterPollTableEntry function.
Document (Version 1.61) 5/19/2011
197
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 1.61) 5/19/2011
198
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 keeps from overflowing the storage passed to the function.
primaryDialString returns the primary dial string of the target station. It needs to
point to an array of size maxPrimaryDialStringLength.
maxSecondaryDialStringLength specifies the maximum length of
secondaryDialString excluding the null-terminator character. The function uses
this to limit the size of the returned string to keep from overflowing the storage
passed to the function.
secondaryDialString returns the secondary dial string of the target station. It
needs to point to an array of size maxSecondaryDialStringLength.
The function returns TRUE if the configuration was read and FALSE if an error
occurred.
Notes
This function needs to be used in conjunction with the
dnpReadRoutingTableEntry function to read a complete entry in the DNP routing
table.
Document (Version 1.61) 5/19/2011
199
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 1.61) 5/19/2011
200
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 1.61) 5/19/2011
201
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 1.61) 5/19/2011
202
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 1.61) 5/19/2011
203
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 1.61) 5/19/2011
204
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 1.61) 5/19/2011
205
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 1.61) 5/19/2011
206
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 1.61) 5/19/2011
207
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 1.61) 5/19/2011
208
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 1.61) 5/19/2011
209
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 1.61) 5/19/2011
210
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 1.61) 5/19/2011
211
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 1.61) 5/19/2011
212
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 1.61) 5/19/2011
213
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 1.61) 5/19/2011
214
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 1.61) 5/19/2011
215
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 does not write the configuration for the Unsolicited Back Off Time.
Use the function dnpSaveUnsolicitedBackoffTime to save the Unsolicited Back
Off Time configuration.
This function supersedes the dnpSaveConfiguration function.
Document (Version 1.61) 5/19/2011
216
Function Specifications
dnpSaveUnsolicitedBackoffTime
Set the DNP unsolicited resend time.
Syntax
BOOLEAN dnpSaveUnsolicitedBackoffTime (
UINT16 backoffTime
);
Description
The dnpSaveUnsolicitedBackoffTime function writes the unsolicited resend time
to the controller.
The time is in seconds; and the allowed range is 0-65535 seconds. A value of
zero indicates that the unsolicited resend timer is disabled.
The function returns TRUE if the function was successful. It returns FALSE if the
DNP configuration has not been created.
Document (Version 1.61) 5/19/2011
217
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 1.61) 5/19/2011
218
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 1.61) 5/19/2011
219
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 1.61) 5/19/2011
220
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 1.61) 5/19/2011
221
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 1.61) 5/19/2011
222
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 1.61) 5/19/2011
223
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 only available on the SCADAPack 32, SCADAPack 350 and
4203.
DNP needs to be enabled before calling this function in order to create the DNP
configuration.
This function supersedes the dnpWriteMasterPollTableEntry function.
Document (Version 1.61) 5/19/2011
224
Function Specifications
dnpWriteRoutingTableEntry_DialString
Write DNP Routing Table Entry Dial Strings
Syntax
BOOLEAN dnpWriteRoutingTableEntry_DialStrings(
UINT16 index,
UINT16 primaryDialStringLength,
CHAR *primaryDialString,
UINT16 secondaryDialStringLength,
CHAR *secondaryDialString
);
Description
This function writes a primary and secondary dial string into an entry in the DNP
routing table.
index specifies the index of an entry in the DNP routing table.
primaryDialStringLength specifies the length of primaryDialString excluding the
null-terminator character.
primaryDialString specifies the dial string used when dialing the target station.
This string is used on the first attempt.
secondaryDialStringLength specifies the length of secondaryDialString excluding
the null-terminator character.
secondaryDialString specifies the dial string to be used when dialing the target
station. It is used for the next attempt if the first attempt fails.
The function returns TRUE if the configuration was written and FALSE if an error
occurred.
Notes
This function needs to be used in conjunction with the
dnpWriteRoutingTableEntry function to write a complete entry in the DNP routing
table.
Document (Version 1.61) 5/19/2011
225
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.
Example
See the example in the dnpGetConfiguration section.
Document (Version 1.61) 5/19/2011
226
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.
Example
See the Example in the dnpGetConfiguration section.
Document (Version 1.61) 5/19/2011
227
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
end_group, end_task
Document (Version 1.61) 5/19/2011
228
Function Specifications
end_group
Terminates all Tasks in a Task Group
Syntax
#include <ctools.h>
void end_group(UINT16 taskGroup);
Description
The end_group function terminates all tasks of the specified type. This function
should only be used with taskGroups of APPLICATION_GROUP_0 –
APPLICATION_GROUP_9. Stack space and resources used by the tasks are
freed.
Notes
This function is used normally by communication protocols to stop an executing
application program.
See Also
end_application, end_task
Document (Version 1.61) 5/19/2011
229
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 any type
task.
See Also
end_application, end_group
Document (Version 1.61) 5/19/2011
230
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 RTOS_EVENTS - 1. Any events defined in
ctools.h are not valid events for use in an application program.
Example
See the Examples for startTimedEvent.
See Also
startTimedEvent
Document (Version 1.61) 5/19/2011
231
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
stops the protocol driver from calling the handler while the application is stopped.
Call the enronInstallCommmandHandler with a NULL pointer. The usual method
is to create a task exit handler function to do this. See the Example below for
details.
The handler function has five parameters.

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 needs to start with the function code and end with the last
Document (Version 1.61) 5/19/2011
232
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)
{
/* get the command byte */
Document (Version 1.61) 5/19/2011
233
Function Specifications
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);
}
int main(void)
{
TASKINFO thisTask;
Document (Version 1.61) 5/19/2011
234
Function Specifications
/* install handler to execute when this task ends */
thisTask = getTaskInfo(0);
installExitHandler(thisTask.taskID, (FUNCPTR)
mainExitHandler);
/* install handler for Enron Modbus */
enronInstallCommandHandler(commandHandler);
/* infinite loop of main task */
while (TRUE)
{
/* add application code here */
}
}
Document (Version 1.61) 5/19/2011
235
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 1.61) 5/19/2011
236
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 must point to an array of 6
bytes.
Document (Version 1.61) 5/19/2011
237
Function Specifications
ethernetSetIP
Set Ethernet Controller TCP/IP Setting
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 1.61) 5/19/2011
238
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 1.61) 5/19/2011
239
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 1.61) 5/19/2011
240
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. Use this function with care in
application programs.
Document (Version 1.61) 5/19/2011
241
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 must have been allocated by
a previous call to the function allocateMemory.
The function has one argument: a pointer to the memory to be freed.
Notes
The DYNAMIC_MEMORY resource needs to be requested before calling this
function.
The allocation of memory and the allocated memory are non-volatile.
Pointers to non-volatile dynamic memory need to be statically allocated in a nonvolatile 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 1.61) 5/19/2011
242
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 must point to a DF1 protocol configuration structure.
The getABConfiguration function copies the DF1 configuration parameters into
the ABConfig structure and returns a pointer to it.
See Also
setABConfiguration
Example
This program displays the DF1 configuration parameters for com1.
#include <ctools.h>
int main(void)
{
struct ABConfiguration ABConfig;
getABConfiguration(com1, &ABConfig);
fprintf(com1,"Min protected address:
ABConfig.min_protected_address);
fprintf(com1,"Max protected address:
ABConfig.max_protected_address);
%u\r\n",
%u\r\n",
}
Document (Version 1.61) 5/19/2011
243
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
getClockTime, setclock
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);
fprintf(com1,"%2d/%2d/%2d", now.day, now.month, now.year);
fprintf(com1,"%2d:%2d\r\n",now.hour, now.minute);
}
Document (Version 1.61) 5/19/2011
244
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 1.61) 5/19/2011
245
Function Specifications
getClockTime
Read the Real Time Clock
Syntax
#include <ctools.h>
void getClockTime(INT32 * pDays, INT32 * pHundredths);
Description
The getClockTime function reads the real time clock and returns the value as the
number of whole days since 01/01/1997 and the number of hundredths of a
second since the start of the current day. The function works for years from
01/01/1997 to 12/31/2099 then rolls over.
The function has two parameters: a pointer to the variable to hold the days and a
pointer to a variable to hold the hundredths of a second.
The function has no return value.
Notes
The IO_SYSTEM resource needs to be requested before calling this function.
See Also
getclock
Document (Version 1.61) 5/19/2011
246
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
must point to a character string of length CONTROLLER_ID_LEN.
Example
This program displays the Controller ID.
#include <ctools.h>
int 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 1.61) 5/19/2011
247
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>
int main(void)
{
UINT 16 flag, bitmask;
Document (Version 1.61) 5/19/2011
248
Function Specifications
getForceFlag(MODBUS, 40001, &flag);
getForceFlag(LINEAR, 302, &bitmask);
getForceFlag(LINEAR, 1540, &flag);
}
Document (Version 1.61) 5/19/2011
249
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 1.61) 5/19/2011
250
Function Specifications
getFtpServerState
Gets the state of the FTP server.
Syntax
#include <ctools.h>
BOOLEAN getFtpServerState(
UINT32* state
);
Parameters
state specifies the parameter that the current operational state of the FTP server
will be placed in. The following values for state are defined:

0 = FTP server disabled

1 = FTP server enabled, anonymous login permitted

2 = FTP server enabled, username and password required
Description
The getFtpServerState function gets the state of the FTP server. TRUE is
returned if the current state was placed in the parameter state. FALSE is
returned if the current state was not placed in the parameter state.
Notes
This function is only relevant for Ethernet enabled controllers.
See Also
setFtpServerState
Document (Version 1.61) 5/19/2011
251
Function Specifications
getHardwareInformation
Obtains the hardware type and version
Syntax
#include <ctools.h>
BOOLEAN getHardwareInformation(UCHAR* majorVersion, UCHAR*
minorVersion, UCHAR* hardwareType);
Description
The getHardwareInformation function will place the major version of the
hardware into the memory pointed to by majorVersion, the minor version of the
hardware into the minorVersion, and the hardware type in the memory pointed to
by hardwareType. Refer to the macros starting with HT_ for the various hardware
types.
The function returns TRUE if the hardware version and type was placed in the
passed variables. Otherwise FALSE is returned.
Notes
This function is currently only supported on the SCADAPack 350 and 4203
Document (Version 1.61) 5/19/2011
252
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 5203/4 System Manual, SCADAPack 32 System Manual, or the
SCADAPack 350 System Manual for further information on the Status LED and
Status Output.
See Also
setIOErrorIndication
Document (Version 1.61) 5/19/2011
253
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 1.61) 5/19/2011
254
Function Specifications
getLoginCredentials
Gets login credentials for a service
Syntax
#include <ctools.h>
BOOLEAN getLoginCredentials(
UINT32 service,
UINT32 index,
UCHAR* username,
UINT32 maxUsernameLength
);
Parameters
service specifies the service for which the credentials are being retrieved.
index specifies the index for the credentials. Indices are service specific.
username specifies the username to grant access to.
maxUsernameLength specifies the maximum length username that can be
returned.
Description
The getLoginCredentials function retrieves the username at the specified index
for the specified service.
Valid services are:
0 = FTP. Maximum username and password length is 16 bytes. Only index 0 is
supported.
The valid values of index are service specific. The username returned will be
NULL terminated and placed in the buffer pointed to by username.
True is returned if the credentials were retrieved. False is returned if the service
rejected the request, if the service was unrecognized, or if the username could
not fit in the specified sized buffer.
See Also
setLoginCredentials, clearLoginCredentials
Document (Version 1.61) 5/19/2011
255
Function Specifications
getpeername
Syntax
#include <ctools.h>
int getpeername
(
int socketDescriptor,
Struct sockaddr * fromAddressPtr,
int * addressLengthPtr
);
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:
EBADF
socketDescriptor is not a valid descriptor.
ENOTCONN
The socket is not connected.
EINVAL
One of the passed parameters is not valid.
Document (Version 1.61) 5/19/2011
256
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>
int 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 1.61) 5/19/2011
257
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 port. If port is not a
valid serial port the function has no effect.
The get_port function copies the serial port settings into the structure pointed to
by settings and returns a pointer to the structure.
Notes
Refer to the Overview of Functions section for detailed information on serial
ports.
Refer to the Structure and Types section for a Description of the fields in
the pconfig structure.
See Also
set_port
Example
#include <ctools.h>
int main(void)
{
struct pconfig settings;
get_port(com1, &settings);
fprintf(com1,"Baud rate: %d\r\n", settings.baud);
fprintf(com1,"Duplex:
%d\r\n", settings.duplex);
}
Document (Version 1.61) 5/19/2011
258
Function Specifications
getPowerMode
Get Current Power Mode
Syntax
#include <ctools.h>
BOOLEAN getPowerMode(UCHAR* cpuPower, UCHAR* lan, UCHAR* usbHost);
Description
The getPowerMode function places the current state of the CPU, LAN, USB
peripheral port, and USB host port in the passed parameters. The following table
lists the possible return values and their meaning.
Macro
Meaning
PM_CPU_FULL
PM_CPU_REDUCED
PM_CPU_SLEEP
PM_LAN_ENABLED
PM_LAN_DISABLED
PM_USB_HOST_ENABLED
PM_USB_HOST_DISABLED
PM_UNAVAILABLE
The CPU is set to run at full speed
The CPU is set to run at a reduced speed
The CPU is set to sleep mode
The LAN is enabled
The LAN is disabled
The USB host port is enabled
The USB host port is disabled
The status of the device could not be read.
The function always returns TRUE.
The application program may set the current power mode with the
setPowerMode function.
See Also
setPowerMode, setWakeSource, getWakeSource
Document (Version 1.61) 5/19/2011
259
Function Specifications
getProgramStatus
Get Program Status Flag
Syntax
#include <ctools.h>
UINT16 getProgramStatus(FUNCPTR entryPoint);
Description
The getProgramStatus function returns the application program status flag of the
program specified by entryPoint. The passed parameter should always be in the
function main. The status flag is set to NEW_PROGRAM when the C program
downloaded to the controller from the program loader. The status flag is set to
PROGRAM_NOT_LOADED when the C program is erased.
The application program may modify the status flag with the setProgramStatus
function.
See Also
setProgramStatus
Example
See the Get Program Status Example in the Examples section.
Document (Version 1.61) 5/19/2011
260
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
port. If port does not point to a valid serial port the function has no effect. settings
must point to a protocol configuration structure, prot_settings.
The get_protocol function copies the protocol settings into the structure pointed
to by settings and returns a pointer to that structure.
Refer to the ctools.h file for a Description of the fields in the prot_settings
structure.
Refer to the Overview of Functions section for detailed information on
communication protocols.
See Also
set_protocol
Example
This program displays the protocol configuration for com1.
#include <ctools.h>
int main(void)
{
struct prot_settings settings;
get_protocol(com1, &settings);
fprintf(com1,"Type:
%d\r\n", settings.type);
fprintf(com1,"Station: %d\r\n", settings.station);
fprintf(com1,"Priority: %d\r\n", settings.priority);
}
Document (Version 1.61) 5/19/2011
261
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: port is one of com1, com2 or com3; and
settings, a pointer to a PROTOCOL_SETTINGS structure. Refer to the
Description of the structure for an explanation of the parameters.
The function returns TRUE if the 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>
int main(void)
{
PROTOCOL_SETTINGS settings;
if (getProtocolSettings(com1, &settings)
{
fprintf(com1,"Type: %d\r\n", settings.type);
fprintf(com1,"Station: %d\r\n", settings.station);
fprintf(com1,"Address Mode: %d\r\n", settings.mode);
fprintf(com1,"SF Messaging: %d\r\n",
settings.SFMessaging);
fprintf(com1,"Priority: %d\r\n", settings.priority);
}
else
Document (Version 1.61) 5/19/2011
262
Function Specifications
{
fprintf(com1,“Serial port is not valid\r\n”);
}
}
Document (Version 1.61) 5/19/2011
263
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 setProtocolSettingsEx function sets protocol parameters for a serial port.
This function supports extended addressing and Enron Modbus parameters.
The function has two arguments:

port specifies the serial port. It is one of com1, com2 or com3.

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>
int main(void)
{
PROTOCOL_SETTINGS_EX settings;
if (getProtocolSettingsEx(com1, &settings)
{
fprintf(com1,"Type: %d\r\n", settings.type);
fprintf(com1,"Station: %d\r\n", settings.station);
fprintf(com1,"Address Mode: %d\r\n", settings.mode);
fprintf(com1,"SF: %d\r\n", settings.SFMessaging);
fprintf(com1,"Priority: %d\r\n", settings.priority);
fprintf(com1,"Enron: %d\r\n", settings.enronEnabled);
fprintf(com1,"Enron station: %d\r\n",
Document (Version 1.61) 5/19/2011
264
Function Specifications
settings.enronStation);
}
else
{
fprintf(com1,“Serial port is not valid\r\n”);
}
}
Document (Version 1.61) 5/19/2011
265
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>
int main(void)
{
struct prot_status status;
status = get_protocol_status(com2);
fprintf(com1,"Checksum: %d\r\n", status.checksum_errors);
}
Document (Version 1.61) 5/19/2011
266
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 and authentication.
The getSFTranslation function copies the entry from the store and forward
translation table at index to the structure pointed to by pTranslation. If index is
invalid, a disabled table entry is copied. The disabled table entry has both station
fields set to 65535.
The SF_TRANSLATION structure is described in the Structures and Types
section. manual.
Notes
The TeleBUS Protocols User Manual describes store and forward messaging
mode.
See Also
setSFTranslation, clearSFTranslationTable, checkSFTranslationTable
Document (Version 1.61) 5/19/2011
267
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. If the userName parameter is non-NULL then the user name
used for authentication purposes will be copied into the array pointed to by
userName. userName must point to an array of 16 unsigned characters.
The SF_TRANSLATION_EX structure supports a timeout and is described in the
Structures and Types section.
Notes
The TeleBUS Protocols User Manual describes the store and forward messaging
mode.
See Also
setSFTranslationEx, clearSFTranslationTable, checkSFTranslationTable
Document (Version 1.61) 5/19/2011
268
Function Specifications
getsockname
Syntax
#include <ctools.h>
int getsockname
(
int socketDescriptor,
struct sockaddr * myAddressPtr,
int * addressLengthPtr
);
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:
EBADF
socketDescriptor is not a valid descriptor.
EINVAL
One of the passed parameters is not valid.
Document (Version 1.61) 5/19/2011
269
Function Specifications
getsockopt
Syntax
#include <ctools.h>
int getsockopt
(
int socketDescriptor,
int protocolLevel,
int optionName,
char * optionValuePtr,
int * optionLengthPtr
);
Description
getsockopt is used retrieve options associated with a socket. Options may exist
at multiple protocol levels; they are always present at the uppermost “socket”
level. When manipulating socket options, the level at which the option resides
and the name of the option must be specified. To manipulate options at the
“socket” level, protocolLevel is specified as SOL_SOCKET. To manipulate
options at any other level, 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 un-interpreted 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 1.61) 5/19/2011
270
Function Specifications
SO_REUSEADDR
Enable/disable local address reuse. Default 0 (disable).
SO_RCVLOWAT
The low water mark for receiving.
SO_SNDLOWAT
The low water mark for sending.
SO_RCVBUF
The buffer size for input. Default is 8192 bytes.
SO_SNDBUF
The buffer size for output. Default is 8192 bytes.
SO_REUSEADDR indicates that the rules used in validating addresses supplied
in a bind call should allow reuse of local addresses. SO_KEEPALIVE enables the
periodic transmission of messages (every 2 hours) on a connected socket. If the
connected party fails to respond to these messages, the connection is
considered broken. SO_DONTROUTE indicates that outgoing messages should
bypass the standard routing facilities. Instead, messages are directed to the
appropriate network interface according to the network portion of the destination
address. SO_LINGER controls the action taken when unsent messages are
queued on a socket and a close on the socket is 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).
The following options are recognized at the IP level.
IP_PROTOIP protocolLevel options
IP_MULTICAST_IF
Get the configured IP address that uniquely identifies the
outgoing interface for multicast datagrams sent on this
socket. A zero IP address parameter indicates that we
want to reset a previously set outgoing interface for
multicast packets sent on that socket.
IP_MULTICAST_TTL
Get the default IP TTL for outgoing multicast datagrams.
IP_TOS
IP type of service. Default 0
IP_TTL
IP Time To Live in seconds. Default 64.
The following options are recognized at the TCP level.
IP_PROTOTCP protocolLevel options
Document (Version 1.61) 5/19/2011
271
Function Specifications
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
to allow client‟s TCP to send small packets as soon as
possible (like mouse clicks). Default 0.
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
SO_REUSEADDR
SO_SNDBUF
SO_SNDLOWAT
IP_MULTICAST_IF
IP_MULTICAST_TTL
IP_TOS
IP_PROTOIP
Document (Version 1.61) 5/19/2011
Option data
type
int
int
int
struct linger
int
unsigned long
unsigned long
int
unsigned long
unsigned long
struct in_addr
unsigned char
unsigned char
Option value
0 or 1
0 or 1
0 or 1
0 or 1
0 or 1
272
Function Specifications
Protocol Level
Option Name
IP_PROTOTCP
IP_TTL
TCP_MAXSEG
TCP_NODELAY
Option data
type
unsigned char
int
int
Option value
0 or 1
Returns
Value
Meaning
0
Successful set of option
-1
An error occurred
getsockopt will fail if:
EBADF
The socket descriptor is invalid
EINVAL
One of the parameters is invalid
ENOPROTOOPT
The option is unknown at the level indicated.
Document (Version 1.61) 5/19/2011
273
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 port is not a valid serial port the function
has no effect. status must point to a valid serial port status structure, pstatus.
The get_status function copies the serial port status into the structure pointed to
by status and returns a pointer to the structure 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>
int main(void)
{
struct pstatus status;
get_status(com1, &status);
fprintf(com1,"Framing: %d\r\n", status.framing);
fprintf(com1,"Parity: %d\r\n", status.parity);
}
Document (Version 1.61) 5/19/2011
274
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 1.61) 5/19/2011
275
Function Specifications
getTaskInfo
Get Information on a Task
Syntax
#include <ctools.h>
BOOLEAN getTaskInfo(INT32 taskID, TASKINFO *pTaskInfo);
Description
The getTaskInfo function returns information about the task specified by taskID. If
taskID is 0 the function returns information about the current task. The function
copies task information to the TASKINFO structure pointed to by pTaskInfo.
FALSE is returned if the task specified by 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 1.61) 5/19/2011
276
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>
int main(void)
{
struct prot_settings settings;
VERSION versionInfo;
/* Disable the protocol on serial port 1 */
settings.type =
NO_PROTOCOL;
settings.station =
1;
settings.priority =
250;
settings.SFMessaging = FALSE;
request_resource(IO_SYSTEM);
set_protocol(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:
versionInfo.date);
fprintf(com1, " Copyright:
versionInfo.copyright);
%d\r\n",
%d\r\n",
%s\r\n",
%s\r\n",
}
Document (Version 1.61) 5/19/2011
277
Function Specifications
getWakeSource
Gets Conditions for Waking from Sleep Mode
Syntax
#include <ctools.h>
UINT32 getWakeSource(void);
Description
The getWakeSource function returns a bit mask of the active wake up sources.
Valid wake up sources are listed below.

WS_RTC_ALARM

WS_COUNTER_1_OVERFLOW

WS_COUNTER_2_OVERFLOW

WS_COUNTER_3_OVERFLOW

WS_LED_POWER_SWITCH

WS_DIN_1_CHANGE

WS_COM3_VISION
See Also
setPowerMode
Example
The following code fragment displays the enabled wake up sources.
unsigned enabled;
enabled = getWakeSource();
fputs("Enabled wake up sources:\r\n", com1);
if (enabled & WS_RTC_ALARM)
fputs(" Real Time Clock\r\n", com1);
if (enabled & WS_LED_POWER_SWITCH)
fputs(" LED Power Switch\r\n", com1);
if (enabled & WS_COUNTER_1_OVERFLOW)
fputs(" Counter 1 Overflow\r\n", com1);
if (enabled & WS_COUNTER_1_OVERFLOW)
fputs(" Counter 2 Overflow\r\n", com1);
if (enabled & WS_COUNTER_1_OVERFLOW)
fputs(" Counter 3 Overflow\r\n", com1);
Document (Version 1.61) 5/19/2011
278
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 returns 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
understood, but the function was deemed illegal.
Document (Version 1.61) 5/19/2011
279
Function Specifications

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_NOT_HANDLED must be returned by the function handler if the
function was not handled. If no installed handler can process the function
then an ILLEGAL_FUNCTION exception response will be sent.
Function Codes Used
The following function codes are currently used by the TeleBUS 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
71
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
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
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 must request and release the appropriate resources for proper
operation.
Document (Version 1.61) 5/19/2011
280
Function Specifications
The station address is not included in the message or response string. It will be
added to the response string before sending the reply.
The checksum is not included in the message or the 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 1.61) 5/19/2011
281
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 1.61) 5/19/2011
282
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.
The functions hartCommand0, hartCommand1, etc. are used to send commands
provided by the Network Layer.
Document (Version 1.61) 5/19/2011
283
Function Specifications
See Also
hartStatus, hartSetConfiguration, hartCommand0, hartCommand1
Document (Version 1.61) 5/19/2011
284
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 1.61) 5/19/2011
285
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 must be a static modular or global variable. A
primaryVariable should be declared for each HART I/O module in use. A local
variable or dynamically allocated variable may not be used because a late
command response received after the variable is freed will write data over the
freed variable space.
The function returns TRUE if the command was sent. The 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 the HART_VARIABLE structure not changed. Command 1 does
not return a variable code.
See Also
hartCommand2, hartStatus, hartSetConfiguration
Document (Version 1.61) 5/19/2011
286
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 must 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 1.61) 5/19/2011
287
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 must be static modular or global variables. An array of
variables should be declared for each HART I/O module in use. A local variable
or dynamically allocated variable may not be used because a late command
response received after the variable is freed will write data over the freed variable
space.
The variables array is updated when the response is received by the 5904
interface as follows.
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 1.61) 5/19/2011
288
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 1.61) 5/19/2011
289
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 1.61) 5/19/2011
290
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 must be static modular or global variables. An array of
variables should be declared for each HART I/O module in use. A local variable
or dynamically allocated variable may not be used because a late command
response received after the variable is freed will write data over the freed variable
space.
The variableCode array specifies which variables are to be read from the
transmitter. Consult the documentation for the transmitter for valid values.
The variables array is updated when the response is received by the 5904
interface as follows.
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 1.61) 5/19/2011
291
Function Specifications
The function returns immediately after the command is sent. The calling program
needs to wait for the response to be received. Use the hartStatus command to
read the status of the command.
The number of attempts and the number of preambles sent are set with the
hartSetConfiguration command.
The function requests four variables and expects four variables in the response.
See Also
hartCommand3, hartStatus, hartSetConfiguration
Document (Version 1.61) 5/19/2011
292
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
No valid response
received after all
attempts made
HR_NoModuleResponse
not used
HR_CommandPending
not used
HR_CommandSent
current attempt number
HR_Response
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
HR_NoResponse
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 1.61) 5/19/2011
293
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 1.61) 5/19/2011
294
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 1.61) 5/19/2011
295
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 1.61) 5/19/2011
296
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 1.61) 5/19/2011
297
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 1.61) 5/19/2011
298
Function Specifications
htonl
Syntax
#include <ctools.h>
unsigned long htonl
(
unsigned long longValue
);
Description
This function converts a long value from host byte order to network byte order.
Parameters
longValue
The value to convert
Returns
The converted value.
Document (Version 1.61) 5/19/2011
299
Function Specifications
htons
Syntax
#include <ctools.h>
unsigned short htons
(
unsigned short shortValue
);
Description
This function converts a short value from host byte order to network byte order.
Parameters
shortValue
The value to convert
Returns
The converted value.
Document (Version 1.61) 5/19/2011
300
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 1.61) 5/19/2011
301
Function Specifications
install_handler
Install Serial Port Handler
Syntax
#include <ctools.h>
void install_handler(FILE *stream, BOOLEAN (*function)(INT32,
INT32));
Description
The install_handler function installs a serial port character handler function. The
serial port driver calls this function each time it receives a character. If stream
does not point to a valid serial port the function has no effect.
function specifies the handler function, which takes two arguments. The first
argument is the port number. The second argument is the received character. If
function is NULL, the default handler for 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-1 program.
Example
See the Install Serial Port Handler Example in the Examples section.
Document (Version 1.61) 5/19/2011
302
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 1.61) 5/19/2011
303
Function Specifications
installDbaseHandler
Install User Defined Dbase Handler (IEC 61131-1 firmware only)
Syntax
#include <ctools.h>
void installDbaseHandler
(
BOOLEAN (* handler)
(
UINT16 address,
INT16 *value
)
)
Description
The installDbaseHandler function allows an extension to be defined for the
dbase() function.
If a handler is installed, it is called by the dbase function when one of the
following conditions apply:

There is no IEC 61131-1 application downloaded, or

There is no IEC 61131-1 variable assigned to the specified Modbus address.
The function installDbaseHandler has one parameter: a pointer to a function to
handle the dbase extensions. See the section Dbase Handler Function for a full
Description of the handler function and it‟s parameters. If the pointer is NULL, no
handler is installed.
The installed handler is always called with a Modbus address. Linear addresses
are converted to Modbus addresses before calling the handler. Use the
installSetdbaseHandler function to install a write access handler for the same
addresses handled by the dbase handler.
The C++ Tools functions dbase and setdbase are used by all protocols to access
Modbus or Linear registers.
Notes
Call this 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 and the
system will likely crash.
Document (Version 1.61) 5/19/2011
304
Function Specifications
installSetdbaseHandler
Install User Defined Setdbase Handler (IEC 61131-1 firmware only)
Syntax
#include <ctools.h>
void installSetdbaseHandler
(
BOOLEAN (* handler)
(
UINT16 address,
INT16
value
)
)
Description
The installSetdbaseHandler function allows an extension to be defined for the
setdbase() function.
If a handler is installed, it is called by the setdbase function when one of the
following conditions apply:

There is no IEC 61131-1 application downloaded, or

There is no IEC 61131-1 variable assigned to the specified Modbus address.
The function installSetdbaseHandler has one parameter: a pointer to a function
to handle the setdbase extensions. See the section Setdbase Handler Function
for a full Description of the 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
installDbaseHandler function to install a read access handler for the same
addresses handled by the setdbase handler.
The C++ Tools functions dbase and setdbase are used by all protocols to access
Modbus or Linear registers.
Notes
Call this function with the NULL pointer to remove the setdbase handler. This
needs to be done when the application program is ended with an exit handler.
Use the installExitHandler function to install the exit handler.
If the Setdbase handler is not removed within an exit handler, it will remain
installed and continue to operate until the controller power is cycled. Erasing the
C Program from the Initialize dialog will not remove the Setdbase handler. If the
handler is located in a RAM-based application and left installed while a different
C application is downloaded, the original handler will be corrupted and the
system will likely crash.
Document (Version 1.61) 5/19/2011
305
Function Specifications
See Also
setdbase, installDbaseHandler
Example
See Example for Setdbase Handler Function.
Document (Version 1.61) 5/19/2011
306
Function Specifications
installExitHandler
Install Handler Called when Task Ends
Syntax
#include <ctools.h>
BOOLEAN installExitHandler(UINT32 taskID, FUNCPTR function) );
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 or end_group function

the end_application function is executed and the function is an
APPLICATION type function

the program is stopped from the IEC 61131-1 or Telepace program and the
task is an APPLICATION type function

the program is erased by the IEC 61131-1 or Telepace program.
The exit handler function is not called if power to the controller is removed. In this
case all execution stops when power is removed. The application program starts
from the beginning when power is reapplied.
Do not call any RTOS functions from the exit handler.
Example
See the Example for startTimedEvent.
Document (Version 1.61) 5/19/2011
307
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(s) is called only if the message is
addressed to the station, and the message checksum is correct.
The function has one parameter: a pointer to a function to handle the messages.
See the section Handler Function for a full Description of the function and it‟s
parameters. The function has no return value.
Notes
This function is used to create a user-defined extension to the standard Modbus
protocol.
Call the removeModbusHandler function to remove a previously installed
handler. This needs to be done when the application program is ended with an
exit handler. Use the installExitHandler function to install the exit handler.
If the Modbus handler is not removed within an exit handler, it will remain
installed and continue to operate until the controller power is cycled. Changing
the protocol type or Erasing the C Program from IEC 61131-1 Initialize dialog will
not remove the Modbus handler. If the handler is located in a RAM-based
application and left enabled while a different C application is downloaded, the
original handler will be corrupted and the system will likely not work.
See Also
removeModbusHandler, Handler Function, installExitHandler
Document (Version 1.61) 5/19/2011
308
Function Specifications
installRTCHandler
Install User Defined Real-Time-Clock Handler
Syntax
#include <ctools.h>
void installRTCHandler(
void (* rtchandler)(TIME *now, TIME *newTime));
Description
The installRTCHandler function allows an application program to override
Modbus protocol and DNP protocol commands to set the real time clock. This
function specifies a function to be called when a Modbus or DNP message is
received for the station. The installed handler function is called only if the
message is to set the real time clock.
The function has one parameter: a pointer to a function to handle the messages.
See the section RTCHandler Function for a full Description of the function and its
parameters. If the pointer is NULL, no function is called for set the real time clock
commands, and the default method is used set the real time clock.
The function has no return value.
Notes
Call this function with the NULL pointer to disable processing of Set Real Time
Clock messages. This needs to be done when the application program is ended
with an exit handler. Use the installExitHandler function to install the exit handler.
If the RTC handler is not disabled within an exit handler, it will remain installed
and continue to operate until the controller power is cycled. Changing the
protocol type or Erasing the C Program from the Telepace Initialize dialog will not
remove the handler. If the handler is located in a RAM-based application and left
enabled while a different C application is downloaded, the original handler will be
corrupted and the system will likely not work.
See Also
RTCHandler Function, installExitHandler
Document (Version 1.61) 5/19/2011
309
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 *newTime
);
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 must not request or release the IO_SYSTEM resource.
See Also
installRTCHandler
Document (Version 1.61) 5/19/2011
310
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 1.61) 5/19/2011
311
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-1 program.
The IO_SYSTEM resource needs to be requested before calling this function.
Example
#include <ctools.h>
Document (Version 1.61) 5/19/2011
312
Function Specifications
int main(void)
{
/* Power Up Initialization */
request_resource(IO_SYSTEM);
ioDatabaseReset();
release_resource(IO_SYSTEM);
/* ... the rest of the program */
}
Document (Version 1.61) 5/19/2011
313
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 1.61) 5/19/2011
314
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 1.61) 5/19/2011
315
Function Specifications
ioRead4203DRInputs
Read 4203 DR Inputs
Syntax
#include <ctools.h>
BOOLEAN ioRead4203DRInputs(
UCHAR &dinData,
INT16 &ainData,
UINT32 (&cinData)[2]
)
Description
This function reads buffered data from the digital and analog input of the 4203
DR I/O. Buffered data are updated when an I/O request for the module is
processed.
dinData is a reference to a UCHAR variable. Digital data for the input is written to
this array. One bit in the array represents each input point.
ainData is a reference to a INT16 variables. Analog data are written to this array.
cinData is a reference to two UINT32 variables. Counter data is written to this
array.
The function returns FALSE if the data was read from the internal table;
otherwise TRUE is returned.
See Also
ioWrite4203DROutputs
Example
This program displays the values of the digital input and the analog input read
from the 4203 DR I/O.
#include <ctools.h>
#define
MY_EVENT
1
int main(void)
{
UCHAR
dinData;
INT16
ainData;
UINT32 cinData[2];
BOOLEAN
status;
IO_STATUS
io_status;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_4203DRInputs, 0))
{
Document (Version 1.61) 5/19/2011
316
Function Specifications
status = FALSE;
}
else
{
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
}
// read input data from last scan
status = ioRead4203DRInputs(dinData, ainData,
cinData);
// check status of last scan
if(status == FALSE)
{
// insert code to handle the failure here
}
else if (!ioStatus(MT_4203DRInputs, 0, &io_status))
{
// insert code to handle the failure here
}
else if (!io_status.commStatus)
{
// insert code to handle the failure here
}
else
{
// The last scan was successful so print the // data
fprintf(com2, "status = %u,\
Dins 0 = %X, Ain = %d\r\n", status, dinData,
ainData);
done = TRUE;
}
// sleep processor for 100ms
sleep_processor(100);
}
}
Document (Version 1.61) 5/19/2011
317
Function Specifications
ioRead4203DSInputs
Read 4203 DS Inputs
Syntax
#include <ctools.h>
BOOLEAN ioRead4203DSInputs(
UCHAR &dinData,
INT16 (&ainData)[3],
UINT32 (&cinData)[2]
)
Description
This function reads buffered data from the digital and analog inputs of the 4203
DS I/O. Buffered data are updated when an I/O request for the module is
processed.
dinData is a reference to a UCHAR variable. Digital data for the input is written to
this array. One bit in the array represents each input point.
ainData is a reference to an array of three INT16 variables. Analog data are
written to this array.
cinData is a reference to two UINT32 variables. Counter data is written to this
array.
The function returns FALSE if the data was read from the internal table;
otherwise TRUE is returned.
See Also
ioWrite4203DSOutputs
Example
This program displays the values of the digital input and the 3rd analog input
read from the 4203 DS I/O.
#include <ctools.h>
#define
MY_EVENT
1
int main(void)
{
UCHAR
dinData;
INT16
ainData[5];
UINT32 cinData[2];
IO_STATUS
io_status;
BOOLEAN
status;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_4203DSInputs, 0))
Document (Version 1.61) 5/19/2011
318
Function Specifications
{
status = FALSE;
}
else
{
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
}
// read input data from last scan
status = ioRead4203DSInputs(dinData, ainData,
cinData);
// check status of last scan
if(status == FALSE)
{
// insert code to handle the failure here
}
else if (!ioStatus(MT_4203DSInputs, 0, &io_status))
{
// insert code to handle the failure here
}
else if (!io_status.commStatus)
{
// insert code to handle the failure here
}
else
{
fprintf(com2, "status = %u,\
Dins 0 = %X, Ain 2 = %d\r\n",
status, dinData, ainData[2]);
done = TRUE;
}
// sleep processor for 100ms
sleep_processor(100);
}
}
Document (Version 1.61) 5/19/2011
319
Function Specifications
ioRead5210Inputs
Read SCADAPack 330 controller board inputs
Syntax
#include <ctools.h>
BOOLEAN ioRead5210Inputs(
UINT32 (&counterData)[3],
UCHAR &dinData
);
Description
This function reads buffered data from the digital and counter inputs of a
SCADAPack 330 controller board. Buffered data are updated when an I/O
request for the module is processed.
counterData is a reference to an array to receive the counter input values. Data
from three counter inputs is written to this variable.
dinData is a reference to a variable to receive the digital input values.

Bit 0 of this variable is written with the com3 (HMI) power status.

Bits 1 to 7 are not used.
The function returns TRUE as no I/O errors are possible.
See Also
ioRead5210Outputs
Example
This program displays the values of the 7 internal digital inputs and the single
physical digital input. The first counter input is displayed as well.
#include <ctools.h>
#include "nvMemory.h"
#define MY_EVENT
1
void main(void)
{
UCHAR
dinData;
UINT32 counterData[3];
IO_STATUS
io_status;
BOOLEAN
status;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_5210Inputs, 0))
{
status = FALSE;
Document (Version 1.61) 5/19/2011
320
Function Specifications
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
status = ioRead5210Inputs(counterData, dinData);
// check status of last scan
if (!ioStatus(MT_5210Inputs,0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
//print data
fprintf(com1, "status = %u,\
Dins 0 to 7 = %X, Counter 1 = %d\r\n",
status, dinData, counterData[0]);
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
321
Function Specifications
ioRead5210Outputs
Read SCADAPack 330 controller board outputs
Syntax
#include <ctools.h>
BOOLEAN ioRead5210Outputs(
UCHAR &doutData
);
Description
This function reads buffered data from the digital outputs of a SCADAPack 330
controller board. Buffered data are written with the ioWrite5210Outputs function.
doutData is a reference to a variable to receive the digital output values.

Bit 0 of this variable is written with the USB LED control.

Bit 1 of this variable is written with the com3 (HMI) power control.

Bits 2 to 7 are not used.
The function returns TRUE as no I/O errors are possible.
See Also
ioRead5210Inputs, ioWrite5210Outputs
Document (Version 1.61) 5/19/2011
322
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
Example
This program displays the values of the first 8 digital inputs.
#include <ctools.h>
#include "nvMemory.h"
#define
MY_EVENT
void main(void)
{
UCHAR
IO_STATUS
BOOLEAN
1
dinData[2];
io_status;
status;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_5414Inputs, 0))
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
status = ioRead5414Inputs(0, dinData);
Document (Version 1.61) 5/19/2011
323
Function Specifications
// check status of last scan
if (!ioStatus(MT_5414Inputs,0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
//print data
fprintf(com1, "status = %u,\
Dins 0 to 7 = %X\r\n",
status, dinData[0]);
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
324
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
Example
This Example reads the digital inputs on the 5415 I/O module
#include <ctools.h>
#include "nvMemory.h"
#define
MY_EVENT
void main(void)
{
UCHAR
IO_STATUS
BOOLEAN
1
dinData[1];
io_status;
status;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_5415Inputs, 0))
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
Document (Version 1.61) 5/19/2011
325
Function Specifications
wait_event(MY_EVENT);
// read input data from last scan
status = ioRead5415Inputs(0, dinData);
// check status of last scan
if (!ioStatus(MT_5415Inputs,0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
//print data
fprintf(com1, "status = %u,\
Dins 0 to 7 = %X\r\n",
status, dinData[0]);
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
326
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 1.61) 5/19/2011
327
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
1
2
3
4
5
6
7
8
9
10
Document (Version 1.61) 5/19/2011
328
Function Specifications
Point
Offset
Function
11
12
reserved for future use
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
int main(void)
{
UINT16 dinData;
float
ainData[4];
IO_STATUS
io_status;
BOOLEAN
status;
BOOLEAN
done;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_5505Inputs, 5))
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
Document (Version 1.61) 5/19/2011
329
Function Specifications
status = ioRead5505Inputs(5, dinData, ainData);
// check status of last scan
if (!ioStatus(MT_5505Inputs, 5, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// print data
if (!done)
{
fprintf(com1, "status = %u,\
Dins 0 to 15 = %X, Ain 3 = %f\r\n",
status, dinData, ainData[3]);
done = TRUE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
330
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>
int main(void)
{
UINT16 inputType[4];
Document (Version 1.61) 5/19/2011
331
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
if (!done)
{
fprintf(com1, "status = %u,\
inputType 0 = %d, inputFilter = %d\r\n", status, inputType[0],
inputFilter);
done = TRUE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
332
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
int main(void)
{
UCHAR
INT16
IO_STATUS
BOOLEAN
BOOLEAN
1
dinData;
ainData[8];
io_status;
status;
done;
// main loop
while (TRUE)
{
// add module scan to queue
Document (Version 1.61) 5/19/2011
333
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
if (!done)
{
fprintf(com1, "status = %u,\
Dins 0 to 7 = %X, Ain 4 = %d\r\n",
status, dinData, ainData[4]);
done = TRUE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
334
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 1.61) 5/19/2011
335
Function Specifications
Example
This program reads configuration data for the 5506 I/O module at address 5.
#include <ctools.h>
int main(void)
{
UINT16 inputType[8];
UINT16 inputFilter;
UINT16 scanFrequency;
BOOLEAN
status;
BOOLEAN
done;
// main loop
while (TRUE)
{
// read output data from I/O table
status = ioRead5506Outputs(5, inputType, inputFilter,
scanFrequency);
// print data
if (!done)
{
fprintf(com1, "status = %u,\
inputType 0 = %d, inputFilter = %d,\
scanFrequency = %d \r\n",
status, inputType[0],
inputFilter, scanFrequency);
done = TRUE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
336
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
int main(void)
{
UCHAR
INT16
IO_STATUS
BOOLEAN
BOOLEAN
1
dinData[5];
ainData[8];
io_status;
status;
done;
// main loop
while (TRUE)
{
// add module scan to queue
Document (Version 1.61) 5/19/2011
337
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
if (!done)
{
fprintf(com1, "status = %u,\
Dins 0 to 7 = %X, Ain 4 = %d\r\n",
status, dinData[0], ainData[4]);
done = TRUE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
338
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 1.61) 5/19/2011
339
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>
int main(void)
{
UCHAR
doutData[2];
INT16
aoutData[2];
UINT16 inputType[8];
UINT16 inputFilter;
UINT16 scanFrequency;
UINT16 outputType;
BOOLEAN
status;
BOOLEAN
done;
// main loop
while (TRUE)
{
// read output data from I/O table
status = ioRead5606Outputs(5, doutData, aoutData,
inputType, inputFilter, scanFrequency, outputType);
// print data
if (!done)
{
fprintf(com1, "status = %u,\
Douts 0 to 7 = %X, Aout 0 = %d\r\n",
status, doutData[0], aoutData[0]);
done = TRUE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
340
Function Specifications
ioRead5607Inputs
Read 5607 Inputs
Syntax
#include <ctools.h>
BOOLEAN ioRead5607Inputs(
UINT16 moduleAddress,
UCHAR (&dinData)[3],
INT16 (&ainData)[8]
)
Description
This function reads buffered data from the digital and analog inputs of a 5607 I/O
module. Buffered data are updated when an I/O request for the module is
processed.
moduleAddress is the address of the 5607 module. Valid values are 0 to 7.
dinData is a reference to an array of three UCHAR variables. Digital data for the
16 external and 8 internal inputs are written to this array. One bit in the array
represents each input point. The 8 internal inputs indicate if the corresponding
analog input value is over range.
ainData is a reference to an array of eight INT16 variables. Analog data are
written to this array.
The function returns FALSE if the module address is invalid; otherwise TRUE is
returned.
See Also
ioRead5607Outputs, ioWrite5607Outputs
Example
This program displays the values of the first 8 digital inputs and the 5th analog
input read from 5607 I/O at address 5.
#include <ctools.h>
#define
MY_EVENT
void main(void)
{
UCHAR
INT16
IO_STATUS
BOOLEAN
1
dinData[3];
ainData[8];
io_status;
status;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_5607Inputs, 5))
Document (Version 1.61) 5/19/2011
341
Function Specifications
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
status = ioRead5607Inputs(5, dinData, ainData);
// check status of last scan
if (!ioStatus(MT_5607Inputs, 5, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// print data
fprintf(com3, "status = %u,\
Dins 0 to 7 = %X, Ain 4 = %d\r\n",
status, dinData[0], ainData[4]);
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
342
Function Specifications
ioRead5607Outputs
Read 5607 Outputs
Syntax
#include <ctools.h>
BOOLEAN ioRead5607Outputs(
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 5607
I/O module. Buffered data are written using the ioWrite5607Outputs function.
moduleAddress is the address of the 5607 module. Valid values are 0 to 7.
doutData is a reference to an array of two UCHAR variables. Digital data for the
10 outputs are written to this array. One bit in the array represents each output
point.
aoutData is a reference to an array of two INT16 variables. Analog data for the
two analog outputs are written to this array.
inputType is a reference to an 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 1.61) 5/19/2011
343
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
ioRead5607Inputs, ioWrite5607Outputs
Example
This program reads output data from the I/O table for the 5607 digital outputs and
analog outputs at address 5.
#include <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 = ioRead5607Outputs(5, doutData, aoutData,
inputType, inputFilter, scanFrequency, outputType);
// print data
fprintf(com3, "status = %u,\
Douts 0 to 7 = %X, Aout 0 = %d\r\n",
status, doutData[0], aoutData[0]);
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
344
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 1.61) 5/19/2011
345
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 to an
array of eight INT16 variables. If the moduleAddress is valid, analog input data
are copied to the array. The valid range for moduleAddress is 0 to 15.
The function returns FALSE if the module address is invalid; otherwise TRUE is
returned.
Document (Version 1.61) 5/19/2011
346
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 1.61) 5/19/2011
347
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 1.61) 5/19/2011
348
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 needs to returns TRUE.
Document (Version 1.61) 5/19/2011
349
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 1.61) 5/19/2011
350
Function Specifications
ioReadCounterSP2
Read Data From the SCADAPack 350 Counter Inputs
Syntax
#include <ctools.h>
BOOLEAN ioReadCounterSP2 (UINT32 (&data)[3])
Description
This function reads buffered data from the SCADAPack 350 counter inputs.
Buffered data are updated when an I/O request for the module is processed.
The function has one parameter: a reference to an array of three UINT32
variables. The buffered data are copied to the array.
The maximum count is 4,294,967,295. Counters roll back to 0 when the
maximum count is exceeded.
The function returns TRUE.
Document (Version 1.61) 5/19/2011
351
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 1.61) 5/19/2011
352
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
int main(void)
{
UINT16 point;
UINT32 dinData;
/* request read from digital input module */
ioRequest(MT_Din32, 0);
/* wait for the read to complete */
ioNotification(IO_NOTIFICATION);
wait_event(IO_NOTIFICATION);
/* get the data read */
ioReadDin32(0, dinData);
/* Print module data */
fprintf(com1, "Point
Value");
for (point = 0; point < 32; point++)
{
fprintf(com1, "\n\r%d
", point);
Document (Version 1.61) 5/19/2011
353
Function Specifications
putchar(dinData & 0x0001 ? '1' :'0');
dinData >>= 1;
}
}
Document (Version 1.61) 5/19/2011
354
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 1.61) 5/19/2011
355
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 1.61) 5/19/2011
356
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
Document (Version 1.61) 5/19/2011
357
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 1.61) 5/19/2011
358
Function Specifications
ioReadSP2Inputs
Read SCADAPack 350 Inputs
Syntax
#include <ctools.h>
BOOLEAN ioReadSP2Inputs(
UCHAR (&dinData)[2],
INT16 (&ainData)[8]
)
Description
This function reads buffered data from the digital and analog inputs of the
SCADAPack 350 I/O. Buffered data are updated when an I/O request for the
module is processed.
dinData is a reference to an array of two UCHAR variables. Digital data for the 12
inputs are written to this array. One bit in the array represents each input point.
ainData is a reference to an array of eight INT16 variables. Analog data are
written to this array.
The function returns FALSE if the module address is invalid; otherwise TRUE is
returned.
See Also
ioReadSP2Outputs, ioWriteSP2Outputs
Example
This program displays the values of the first 8 digital inputs and the 5th analog
input read from the SCADAPack 350 I/O.
#include <ctools.h>
#define
MY_EVENT
int main(void)
{
UCHAR
INT16
IO_STATUS
BOOLEAN
BOOLEAN
BOOLEAN
1
dinData[2];
ainData[8];
io_status;
status;
done;
printNow;
// main loop
while (TRUE)
{
// add module scan to queue
if (!ioRequest(MT_SP2Inputs, 0))
{
status = FALSE;
}
Document (Version 1.61) 5/19/2011
359
Function Specifications
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
status = ioReadSP2Inputs(dinData, ainData);
// check status of last scan
if (!ioStatus(MT_SP2Inputs, 0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// print data when coil register 100 is selected
request_resource(IO_SYSTEM);
printNow = dbase(MODBUS, 100);
release_resource(IO_SYSTEM);
if (printNow)
{
if (!done)
{
fprintf(com1, "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 1.61) 5/19/2011
360
Function Specifications
ioReadSP2Outputs
Read SCADAPack 350 Outputs
Syntax
#include <ctools.h>
BOOLEAN ioReadSP2Outputs(
UCHAR (&doutData)[2],
INT16 (&aoutData)[2]
)
Description
This function reads buffered data from the digital and analog outputs of a
SCADAPack 350 I/O module. Buffered data are written using the
ioWriteSP2Outputs function.
doutData is a reference to an array of two UCHAR variables. Digital data for the
10 outputs are written to this array. One bit in the array represents each output
point.
aoutData is a reference to an array of two INT16 variables. Analog data for the
two analog outputs are written to this array.
The function returns TRUE.
See Also
ioReadSP2Inputs, ioWriteSP2Outputs
Example
This program reads output data from the I/O table for the SCADAPack 350 digital
outputs and analog outputs.
#include <ctools.h>
int main(void)
{
UCHAR
INT16
BOOLEAN
BOOLEAN
BOOLEAN
doutData[2];
aoutData[2];
status;
done;
printNow;
// main loop
while (TRUE)
{
// read output data from I/O table
status = ioReadSP2Outputs(doutData, aoutData);
// print data when coil register 100 is selected
request_resource(IO_SYSTEM);
printNow = dbase(MODBUS, 100);
Document (Version 1.61) 5/19/2011
361
Function Specifications
release_resource(IO_SYSTEM);
if (printNow)
{
if (!done)
{
fprintf(com1, "status = %u,\
Douts 0 to 7 = %X, Aout 0 = %d\r\n",
status, doutData[0], aoutData[0]);
done = TRUE;
}
}
else
{
done = FALSE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
362
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 1.61) 5/19/2011
363
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 1.61) 5/19/2011
364
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 1.61) 5/19/2011
365
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 1.61) 5/19/2011
366
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 1.61) 5/19/2011
367
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 1.61) 5/19/2011
368
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 1.61) 5/19/2011
369
Function Specifications
ioWrite4203DROutputs
Write 4203 DR Outputs
Syntax
#include <ctools.h>
BOOLEAN ioWrite4203DROutputs(
UCHAR &doutData,
INT16 &aoutData
)
Description
This function writes data to the I/O table for the digital output and analog output
of the 4203 DR I/O. Data is written to the module when an I/O request for the
module is processed.
doutData is a reference to a UCHAR variable. Digital data for the output is read
from this variable. One bit in the array represents each output point.
aoutData is a reference to a INT16 variable. Analog data for the analog output is
read from this variable.
The function returns TRUE if the supplied data was written to the I/O table.
FALSE is returned if the data could not be written to the I/O table.
See Also
ioRead4203DRInputs
Example
This program turns on the digital output and sets the analog output to full scale
on the 4203 DR.
#include <ctools.h>
#define
MY_EVENT
int main(void)
{
UCHAR
INT16
IO_STATUS
1
doutData;
aoutData;
io_status;
// main loop
while (TRUE)
{
// write data to output tables for next scan
doutData = 0x01;
aoutData = 32767;
ioWrite4203DROutputs(doutData, aoutData);
// add module scan to queue
if (!ioRequest(MT_4203DROutputs, 0))
Document (Version 1.61) 5/19/2011
370
Function Specifications
{
// insert code to handle the failure here
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// check status of last scan
if (!ioStatus(MT_4203DROutputs, 0, &io_status))
{
// insert code to handle the failure here
}
else if (!io_status.commStatus)
{
// insert code to handle the failure here
}
// release processor for 100ms
sleep_processor(100);
}
}
Document (Version 1.61) 5/19/2011
371
Function Specifications
ioWrite4203DSOutputs
Write 4203 DS Outputs
Syntax
#include <ctools.h>
BOOLEAN ioWrite4203DSOutputs(
UCHAR &doutData
)
Description
This function writes data to the I/O table for the digital outputs of the 4203 DS
I/O. Data is written to the module when an I/O request for the module is
processed.
doutData is a reference to a UCHAR variable. Digital data for the outputs is read
from this variable. One bit in the array represents each output point.
The function returns TRUE if the supplied data was written to the I/O table.
FALSE is returned if the data could not be written to the I/O table.
See Also
ioRead4203DSInputs
Example
This program turns on the digital outputs on the 4203 DS.
#include <ctools.h>
#define
MY_EVENT
int main(void)
{
UCHAR
IO_STATUS
1
doutData;
io_status;
// main loop
while (TRUE)
{
// write data to output tables for next scan
doutData = 0x03;
ioWrite4203DSOutputs(doutData);
// add module scan to queue
if (!ioRequest(MT_4203DSOutputs, 0))
{
// insert code to handle the failure here
}
// wait for scan to complete
ioNotification(MY_EVENT);
Document (Version 1.61) 5/19/2011
372
Function Specifications
wait_event(MY_EVENT);
// check status of last scan
if (!ioStatus(MT_4203DSOutputs, 0, &io_status))
{
// insert code to handle the failure here
}
else if (!io_status.commStatus)
{
// insert code to handle the failure here
}
// release processor for 100ms
sleep_processor(100);
}
}
Document (Version 1.61) 5/19/2011
373
Function Specifications
ioWrite5210Outputs
Write SCADAPack 330 controller board outputs
Syntax
#include <ctools.h>
BOOLEAN ioWrite5210Oututs(
UCHAR &doutData
);
Description
This function writes buffered data to the digital outputs of a SCADAPack 330
controller board. Data are written to the module when an I/O request for the
module is processed.
doutData is a reference to a variable holding the digital output values.

Bit 0 of this variable is written to the USB LED control.

Bit 1 of this variable is written to the com3 (HMI) power control.

Bits 2 to 7 are not used.
The function returns TRUE as no I/O errors are possible.
See Also
ioRead5210Outputs
Example
This Example turns on the USB STAT LED.
#include <ctools.h>
#include "nvMemory.h"
#define
MY_EVENT
void main(void)
{
UCHAR
IO_STATUS
BOOLEAN
1
doutData[1];
io_status;
status;
// main loop
while (TRUE)
{
// write data to output tables for next scan
doutData[0] = 0x01;
status = ioWrite5210Outputs(doutData[0]);
// add module scan to queue
Document (Version 1.61) 5/19/2011
374
Function Specifications
if (!ioRequest(MT_5210Outputs,0))
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
// check status of last scan
if (!ioStatus(MT_5210Outputs,0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
375
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 1.61) 5/19/2011
376
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
Example
This Example turns on all the digital outputs on the 5415 I/O module.
#include <ctools.h>
#include "nvMemory.h"
#define
MY_EVENT
void main(void)
{
UCHAR
IO_STATUS
BOOLEAN
1
doutData[2];
io_status;
status;
// main loop
while (TRUE)
{
// write data to output tables for next scan
doutData[0] = 0xFF;
doutData[1] = 0x0F;
status = ioWrite5415Outputs(0,doutData);
// add module scan to queue
if (!ioRequest(MT_5415Outputs,0))
{
Document (Version 1.61) 5/19/2011
377
Function Specifications
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// read input data from last scan
// check status of last scan
if (!ioStatus(MT_5415Outputs,0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
378
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
int main(void)
{
UINT16 inputType[4];
Document (Version 1.61) 5/19/2011
379
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 1.61) 5/19/2011
380
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 1.61) 5/19/2011
381
Function Specifications
#include <ctools.h>
#define
MY_EVENT
1
int 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 1.61) 5/19/2011
382
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 1.61) 5/19/2011
383
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
int main(void)
{
UCHAR
doutData[2];
INT16
aoutData[2];
UINT16 inputType[8];
UINT16 inputFilter;
UINT16 scanFrequency;
UINT16 outputType;
IO_STATUS
io_status;
BOOLEAN
status;
// main loop
while (TRUE)
{
// write data
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 1.61) 5/19/2011
384
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 1.61) 5/19/2011
385
Function Specifications
ioWrite5607Outputs
Write 5607 Outputs
Syntax
#include <ctools.h>
BOOLEAN ioWrite5607Outputs(
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 10 digital outputs and 2 analog
outputs of a 5607 I/O module. Data are written to the module when an I/O
request for the module is processed.
moduleAddress is the address of the 5607 module. Valid values are 0 to 7.
doutData is a reference to an array of two UCHAR variables. Digital data for the
10 outputs are read from this array. One bit in the array represents each output
point.
aoutData is a reference to an array of two INT16 variables. Analog data for the
two analog outputs are read from this array.
inputType is a reference to an array of eight UINT16 variables selecting the input
range for the corresponding analog input. Valid values are

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 1.61) 5/19/2011
386
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
ioRead5607Outputs, ioRead5607Inputs
Example
This program turns on all 10 digital outputs and sets the analog outputs to full
scale on the 5607 module at address 5.
#include <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 1.61) 5/19/2011
387
Function Specifications
status = ioWrite5607Outputs(5, doutData, aoutData,
inputType, inputFilter, scanFrequency, outputType);
// add module scan to queue
if (!ioRequest(MT_5607Outputs, 5))
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// check status of last scan
if (!ioStatus(MT_5607Outputs, 5, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
388
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 1.61) 5/19/2011
389
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>
int main(void)
{
INT16 dataArray[4];
/* set all output values to one-half scale */
dataArray[0] = 16384;
dataArray[1] = 16384;
dataArray[2] = 16384;
dataArray[3] = 16384;
/* Write data to analog output module at
module address 0 */
ioWriteAout4(0, dataArray);
ioRequest(MT_Aout4, 0);
}
Document (Version 1.61) 5/19/2011
390
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 returns TRUE.
Document (Version 1.61) 5/19/2011
391
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 1.61) 5/19/2011
392
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
Example
This program turns ON all 32 digital outputs of a 32-point Digital Output Module
at module address 0.
#include <ctools.h>
int main(void)
{
/* Write data to digital output module */
ioWriteDout32(0, 0xFFFFFFFF);
ioRequest(MT_Dout32, 0);
}
Document (Version 1.61) 5/19/2011
393
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 1.61) 5/19/2011
394
Function Specifications
ioWriteSP2Outputs
Write SCADAPack 350 Outputs
Syntax
#include <ctools.h>
BOOLEAN ioWriteSP2Outputs(
UCHAR (&doutData)[2],
INT16 (&aoutData)[2]
)
Description
This function writes data to the I/O table for the 10 digital outputs and 2 analog
outputs of the SCADAPack 350 I/O. Data are written to the module when an I/O
request for the module is processed.
doutData is a reference to an array of two UCHAR variables. Digital data for the
10 outputs are read from this array. One bit in the array represents each output
point.
aoutData is a reference to an array of two INT16 variables. Analog data for the
two analog outputs are read from this array.
The function returns TRUE.
See Also
ioReadSP2Outputs, ioReadSP2Inputs
Example
This program turns on all 10 digital outputs and sets the analog outputs to full
scale on the SCADAPack 350.
#include <ctools.h>
#define
MY_EVENT
int main(void)
{
UCHAR
INT16
IO_STATUS
BOOLEAN
1
doutData[2];
aoutData[2];
io_status;
status;
// main loop
while (TRUE)
{
// write data
doutData[0] =
doutData[1] =
aoutData[0] =
aoutData[1] =
to output tables for next scan
0xFF;
0x03;
32767;
32767;
status = ioWriteSP2Outputs(doutData, aoutData);
Document (Version 1.61) 5/19/2011
395
Function Specifications
// add module scan to queue
if (!ioRequest(MT_SP2Outputs, 0))
{
status = FALSE;
}
// wait for scan to complete
ioNotification(MY_EVENT);
wait_event(MY_EVENT);
// check status of last scan
if (!ioStatus(MT_SP2Outputs, 0, &io_status))
{
status = FALSE;
}
else if (!io_status.commStatus)
{
status = FALSE;
}
// release processor to other priority 1 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
396
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 1.61) 5/19/2011
397
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. Note that if a connection is allocated to master
messaging but is currently disconnected, it will still be listed in the number of
master connections.
Also, additional connections for store and forward translations will be included in
the summary. For Example, a master connection will be listed if a serial to
Ethernet store and forward translation is currently active.
Document (Version 1.61) 5/19/2011
398
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.
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 1.61) 5/19/2011
399
Function Specifications
ipReadFriendlyListControl
Get the status of the friendly IP list
Syntax
UCHAR ipReadFriendlyListControl(void);
Description
This function returns the status of friendly IP list control.
The function has no parameters.
The function returns TRUE if friendly IP list is enabled and FALSE otherwise.
See Also
ipWriteFriendlyListControl
Document (Version 1.61) 5/19/2011
400
Function Specifications
ipReadFriendlyIPListEntry
Read one entry in the friendly IP list
Syntax
BOOLEAN ipReadFriendlyIPListEntry(
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 1.61) 5/19/2011
401
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 1.61) 5/19/2011
402
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 1.61) 5/19/2011
403
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
ipReadFriendlyIPListEntry
Document (Version 1.61) 5/19/2011
404
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
Document (Version 1.61) 5/19/2011
405
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 1.61) 5/19/2011
406
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 ledPowerSwitch
Document (Version 1.61) 5/19/2011
407
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 1.61) 5/19/2011
408
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>
int 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 1.61) 5/19/2011
409
Function Specifications
listen
Syntax
#include <ctools.h>
int listen
(
int socketDescriptor,
int backLog
);
Description
To accept connections, a socket is first created with socket a backlog for
incoming connections is specified with listen and then the connections are
accepted with accept. The listen call applies only to sockets of type
SOCK_STREAM. The backLog parameter defines the maximum length the
queue of pending connections may grow to. If a connection request arrives with
the queue full, and the underlying protocol supports retransmission, the
connection request may be ignored so that retries may succeed. For AF_INET
sockets, the TCP will retry the connection. If the backlog is not cleared by the
time the TCP times out, connect will fail with ETIMEDOUT.
Parameters
socketDescriptor
backlog
the socket.
The socket descriptor to listen on.
The maximum number of outstanding connections allowed on
Returns
0
Success
-1
An error occurred.
listen can fail for the following reason:
EADDRINUSE The address is currently used by another socket.
EBADF
EOPNOTSUPP
listen.
Document (Version 1.61) 5/19/2011
The socket descriptor is invalid.
The socket is not of a type that supports the operation
410
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.

port 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 1.61) 5/19/2011
411
Function Specifications
set to MM_SENT if a master message is sent. It will be set to MM_RECEIVED
when the response to the message is received.
The command status will be set to MM_RSP_TIMEOUT if the response is not
received within 10 seconds. Sending a retry master message before this timeout
will abort the previous message. To use a timeout other than 10 seconds, use
the serialModbusMaster function.
The master_message function may be used at the same time on the same serial
port as a Telepace MSTR element or IEC 61131-1 master function block.
Notes
Refer to the communication protocol manual for more information.
The IO_SYSTEM resource needs to be requested before calling this function.
See Also
modbusSlaveID
Example
See the Example in the Example Programs chapter under the section Master
Message Example Using Modbus Protocol.
Document (Version 1.61) 5/19/2011
412
Function Specifications
memoryPoolUsage
Return amount of non-volatile memory in bytes
Syntax
UINT32 memoryPoolUsage(UINT16 taskGroup)
Description
The function has one parameter: The taskGroup to report the non-volatile
memory usage for the task group specified by taskGroup. A taskGroup of
ALL_TASK_GROUPS will report the total non-volatile memory allocation for all
tasks.
The function returns the amount of non-volatile memory allocated by the
specified task group, or 0 if the specified group was invalid.
See Also
allocateMemory, freeMemory, memoryPoolSize
Document (Version 1.61) 5/19/2011
413
Function Specifications
memoryPoolSize
Return the size of non-volatile memory pool in bytes.
Syntax
UINT32 memoryPoolSize(void)
Description
The function takes no input parameters and returns the size of the non-volatile
memory pool in bytes.
See Also
allocateMemory, freeMemory, memoryPoolUsage
Document (Version 1.61) 5/19/2011
414
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
master_message
Document (Version 1.61) 5/19/2011
415
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 must be in the range 1 to REPORT_SLAVE_ID_SIZE. If length
is too large only the first REPORT_SLAVE_ID_SIZE characters of the string will
be sent in response to the command.
Notes
The specified result will be sent each time that the protocol command is received,
until a new result is specified.
The function copies the data pointed to by string. string may be modified after the
function is called.
The result is cleared when the controller is reset. The application program needs
to initialize the salve ID string each time it is run.
Document (Version 1.61) 5/19/2011
416
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 needs to be aborted in the exit
handler. Otherwise, the reservation ID for the port remains valid. No other task or
Ladder Logic program may use modem functions on the port. Not calling
modemAbort or modemAbortAll in the task exit handler may result in the port
being unavailable to any programs until the controller is reset.
The modem connection or initialization is automatically terminated when IEC
61131-1 stops the C application and when the controller is rebooted.
Reservation IDs returned by the modemDial and modemInit functions on this port
are invalid after calling modemAbort.
See Also
modemAbortAll, modemDial,
Example
Refer to the Examples in the Functions Overview section.
Document (Version 1.61) 5/19/2011
417
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 must be aborted in the exit handler.
Otherwise, the reservation ID for the port remains valid. No other task or Ladder
Logic program may use modem functions on the port. Not calling modemAbort or
modemAbortAll in the task exit handler may result in the port being unavailable to
any programs until the controller is reset.
The modem connection or initialization is automatically terminated when IEC
61131-1 stops the C application and when the controller is rebooted.
This function will terminate all open dial-up connections or modem initializations
started by the C application - even those started by other tasks. The exit handler
can call this function instead of multiple calls to modemAbort if all the
connections or initializations were started from the same task.
Reservation IDs returned by the modemDial and modemInit functions are invalid
after calling modemAbort or modemAbortAll.
See Also
Example
This program installs an exit handler for the main task that terminates any dial-up
connections made by the task. This handler is not strictly necessary if IEC
61131-1 ends the main task. However, it demonstrates how to use the
modemAbortAll function and an exit handler for another task in a more complex
program.
#include <ctools.h>
Document (Version 1.61) 5/19/2011
418
Function Specifications
/* -------------------------------------------The shutdown function aborts any active
modem connections when the task is ended.
-------------------------------------------- */
void shutdown(void)
{
modemAbortAll();
}
int main(void)
{
TASKINFO taskStatus;
/* set up exit handler for this task */
getTaskInfo(0, &taskStatus);
installExitHandler(taskStatus.taskID,
(FUNCPTR)shutdown);
while(TRUE)
{
/* rest of main task here */
/* Allow other tasks to execute */
release_processor();
}
}
Document (Version 1.61) 5/19/2011
419
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 port sharing and multiple dialing attempts.
The ModemSetup structure specified by configuration defines the serial port,
dialing parameters, modem initialization string and the phone number to dial.
Refer to the Structures and Types section for a Description of the fields in the
ModemSetup structure.
id points to a reservation identifier for the serial port. The identifier provides that
no other modem control function can access the serial port. This parameter
needs to be supplied to the modemDialEnd and modemDialStatus functions.
The function returns an error code. DE_NoError indicates that the connect
operation has begun. Any other code indicates an error. Refer to the dialup.h
section for a complete Description of error codes.
Notes
The serial port type needs to be set to RS232_MODEM.
The modemDialStatus function returns the status of the connection attempt
initiated by modemDial.
The modemDialEnd function terminates the connection to the remote controller.
A pause of a few seconds is required between terminating a connection and
initiating a new call. This 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 the modem or the calling
application from permanently disabling outgoing calls.
The reservation identifier is valid until the call is terminated and another modem
function or an incoming call takes control of the port.
Document (Version 1.61) 5/19/2011
420
Function Specifications
To optimize performance, minimize the length of messages on com3. Examples
of recommended uses for com3 are for local operator display terminals, and for
programming and diagnostics using the IEC 61131-1 program.
Do not call this function in a task exit handler.
Example
Refer to the Examples in the Connecting with a Remote Controller Example
section.
Document (Version 1.61) 5/19/2011
421
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 must be set to RS232_MODEM.
A connection can be terminated by any of the following events. Once terminated
another modem function or incoming call can take control of the serial port.

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.
Do not call this function in a task exit handler. Use modemAbort instead.
Document (Version 1.61) 5/19/2011
422
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 must be set to RS232_MODEM.
The reservation identifier is valid until the call is terminated and another modem
function or an incoming call takes control of the port. The modemDialStatus
function will return a DE_NotInControl error code, if another dial function or
incoming call is now in control of the port.
Do not call this function in a task exit handler.
Document (Version 1.61) 5/19/2011
423
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 port sharing and multiple dialing attempts.
The ModemInit structure pointed to by configuration defines the serial port and
modem initialization string. Refer to the Structures and Types section for a
Description of the fields in the ModemInit structure.
The id variable is set to a reservation identifier for the serial port. The identifier
provides that no other modem control function can access the serial port. This
parameter needs to be supplied to the modemInitEnd and modemInitStatus
functions.
The function returns an error code. DE_NoError indicates that the initialize
operation has begun. Any other code indicates an error. Refer to the Structures
and Types section for a complete Description of error codes.
Notes
The serial port type must be set to RS232_MODEM.
The modemInitStatus function returns the status of the connection attempt
initiated by modemInit.
The 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-1 program.
Do not call this function in a task exit handler.
Document (Version 1.61) 5/19/2011
424
Function Specifications
Example
Refer to the Example in the Modem Initialization Example section.
Document (Version 1.61) 5/19/2011
425
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 must be set to RS232_MODEM.
Normally this function should be called once the modemInitStatus function
indicates the initialization is complete.
The reservation identifier is valid until the initialization is complete or terminated,
and another modem function or an incoming call takes control of the port. The
modemInitEnd function returns a DE_NotInControl error code, if another modem
function or incoming call is in control of the port.
Do not call this function in a task exit handler. Use modemAbort instead.
Document (Version 1.61) 5/19/2011
426
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 must be set to RS232_MODEM.
The port will remain in the DS_Calling state until modem initialization is complete
or fails. The application should wait until the state is not DS_Calling before calling
the modemInitEnd function.
The reservation identifier is valid until the initialization is complete or terminated,
and another modem function or an incoming call takes control of the port.
Do not call this function in a task exit handler.
Document (Version 1.61) 5/19/2011
427
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 must be set to RS232_MODEM.
The dial-up connection handler stops outgoing calls from using the serial port
when an incoming call is in progress and communication is active. If
communication stops for more than five minutes, then outgoing call requests are
allowed to end the incoming call. This keeps the modem or the calling application
from permanently disabling outgoing calls.
The function is used with programs that dial out through an external modem
using the modemDial function. It is not required where the modem is used for
dialing into the controller only.
Document (Version 1.61) 5/19/2011
428
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.
Document (Version 1.61) 5/19/2011
429
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.
Document (Version 1.61) 5/19/2011
430
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.
Document (Version 1.61) 5/19/2011
431
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 1.61) 5/19/2011
432
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. 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. 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);
Document (Version 1.61) 5/19/2011
433
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);
Document (Version 1.61) 5/19/2011
434
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.
Document (Version 1.61) 5/19/2011
435
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. 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 1.61) 5/19/2011
436
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.
Example
See Example for Master Message Example Using mTcpMasterMessage.
Document (Version 1.61) 5/19/2011
437
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.
Example
See the Example in the Example Programs chapter under the section
Master IP Message Example.
Document (Version 1.61) 5/19/2011
438
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 1.61) 5/19/2011
439
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 returns immediately. It is the mastering
task created in the background that services the IP connection.
The command status returned by this function is set to MM_SENT if a valid
master message was sent. Other values returned for the command status are
described for the enumeration type MODBUS_CMD_STATUS in the Structures
and Types section. Use the function mTcpMasterStatus to determine the
progress of the Modbus IP command and the slave response. The command
status will be set to MM_RECEIVED when the response to the message is
received.
Notes
Refer to the communication protocol manual for more information.
The IO_SYSTEM resource needs to be requested before calling this function.
Example
See the Example in the Example Programs chapter under the section Master IP
Message Example.
Document (Version 1.61) 5/19/2011
440
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 1.61) 5/19/2011
441
Function Specifications
Notes
The functions mTcpMasterDisconnect and mTcpMasterClose needs to be called
to disconnect and return this connection ID to the pool of available connections.
Even if the connection to the remote IP is disconnected, manually or
automatically after an idle timeout, the connection ID remains allocated until
mTcpMasterDisconnect is called to disconnect and end the mastering task, and
mTcpMasterClose is called to return the connection ID.
There are only 20 connections available for all Modbus IP master and slave
connections. Use the function ipGetConnectionSummary obtain the number of
master and slave connections that are currently active.
If the initial connection started by this function fails, the connection will be
attempted again if necessary each time mTcpMasterMessage is called.
See the function mTcpMasterMessage for a discussion of whether to allocate
one or several connections when polling multiple remote IP addresses.
Example
See Example for Master Message Example Using mTcpMasterMessage.
Document (Version 1.61) 5/19/2011
442
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.
Example
See Example for Master Message Example Using mTcpMasterMessage.
Document (Version 1.61) 5/19/2011
443
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.
Document (Version 1.61) 5/19/2011
444
Function Specifications
ntohl
Syntax
#include <ctools.h>
unsigned long ntohl
(
unsigned long longValue
);
Description
This function converts a long value from network byte order to host byte order.
Parameters
longValue
The value to convert
Returns
The converted value.
Document (Version 1.61) 5/19/2011
445
Function Specifications
ntohs
Syntax
#include <ctools.h>
unsigned short ntohs
(
unsigned short shortValue
);
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 1.61) 5/19/2011
446
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
Example
#include <ctools.h>
int main(void)
{
request_resource(IO_SYSTEM);
overrideDbase(MODBUS, 40001, 102);
overrideDbase(LINEAR, 302, 330);
Document (Version 1.61) 5/19/2011
447
Function Specifications
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
448
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.
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
int 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);
ioReadAin4(0, ainData);
// get initial process value from analog input
pidData.pv = ainData[0];
Document (Version 1.61) 5/19/2011
449
Function Specifications
// 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 254 tasks
release_processor();
}
}
Document (Version 1.61) 5/19/2011
450
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 must contain valid values for sp, pv,
and manualOutput before calling the function.
The function has no return value.
See Also
pidExecute
Example
See the Example for pidExecute.
Document (Version 1.61) 5/19/2011
451
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
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 1.61) 5/19/2011
452
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 always continues to execute.
Notes
Refer to the Real Time Operating System section for more information on events.
Valid events are numbered 0 to RTOS_EVENTS - 1. Any events defined in
primitiv.h are not valid events for use in an application program.
Example
This program is based on the Install Serial Port Handler Example.
#include <ctools.h>
#include "nvMemory.h"
#define CHAR_RECEIVED 11
void signal_serial(INT32 port, INT32 character);
int main(void)
{
INT32 character;
struct prot_settings protocolSettings;
//disable protocol
get_protocol(com2, &protocolSettings);
protocolSettings.type = NO_PROTOCOL;
request_resource(IO_SYSTEM);
set_protocol(com2, &protocolSettings);
release_resource(IO_SYSTEM);
// Enable character handler
install_handler(com2,
(BOOLEAN(*)(INT32,INT32))signal_serial);
while(TRUE)
{
if (poll_event(CHAR_RECEIVED))
{
character = fgetc(com2);
Document (Version 1.61) 5/19/2011
453
Function Specifications
if (character == EOF)
{
// clear overflow error flag to
// re-enable com1
clearerr(com1);
}
fputs(" character: ", com2);
fputc(character, com2);
fputs("\r\n", com2);
}
/* Allow other tasks to execute */
release_processor();
}
}
void signal_serial (INT32 port, INT32 character)
{
interrupt_signal_event(CHAR_RECEIVED);
}
Document (Version 1.61) 5/19/2011
454
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 always continues to execute.
Notes
Refer to the Real Time Operating System section for more information on
messages.
See Also
poll_event
Example
This task performs a function continuously, and processes received messages
(from higher priority tasks) when they are received.
#include <ctools.h>
void task(void)
{
envelope *letter;
while(TRUE)
{
letter=poll_message();
if (letter != NULL)
/* process the message now */
/* more code here */
}
}
Document (Version 1.61) 5/19/2011
455
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 always continues to execute.
Notes
Refer to the Real Time Operating System section for more information on
resources.
See Also
poll_event, poll_message
Document (Version 1.61) 5/19/2011
456
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 will return a value suitable for an array index, in increasing order of
external serial port numbers, if no error occurs.
If the stream is not recognized, SERIAL_PORTS is returned, to indicate an error.
See Also
portStream
Document (Version 1.61) 5/19/2011
457
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 1.61) 5/19/2011
458
Function Specifications
queryStack
Query Stack Space for Known Tasks
Syntax
#include <ctools.h>
void queryStack(UCHAR* filename);
Description
The queryStack function generates a csv file with the supplied filename. The csv
file contains the current stack condition of all known tasks. The file that is
created can be extracted through FTP or Telepace Studio‟s File Management
tool.
Notes
This function should be used infrequently as a debugging aid. It is also
recommended to be used during C++ application development to confirm that the
tasks created by the C++ application have sufficient stack space. Exercising all
code paths is recommended before calling this function to obtain the most useful
results.
Example
#include <ctools.h>
queryStack (“/d0/myStack.csv”);
Document (Version 1.61) 5/19/2011
459
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.
port specifies the serial port. If it is not valid the function has no effect.
mode specifies the queuing control. It may be DISABLE or ENABLE.
Notes
Queuing is often used with communication protocols that use character timing for
message framing. Its uses in an application program are limited.
Document (Version 1.61) 5/19/2011
460
Function Specifications
readBoolVariable
Read IEC 61131-1 Boolean Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the variable
value is written to the unsigned char value pointed to by value. If the variable is
not found or if the IEC 61131-1 Symbols Status is invalid, FALSE is returned and
the current value is left unchanged. The IEC 61131-1 Symbols Status is invalid if
the Application TIC code download and Application Symbols download are not
sharing the same symbols CRC checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the dbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
See Also
readIntVariable, readRealVariable
Example
This program displays the contents of the boolean variable named “Switch1”.
#include <ctools.h>
int main(void)
{
BOOLEAN
status;
UCHAR char value;
request_resource(IO_SYSTEM);
status = readBoolVariable("Switch1", &value);
release_resource(IO_SYSTEM);
Document (Version 1.61) 5/19/2011
461
Function Specifications
fprintf(com1,"status = %u, Switch1 = %d\r\n", status,
value);
}
Document (Version 1.61) 5/19/2011
462
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 1.61) 5/19/2011
463
Function Specifications
readInputVoltage
Read Input Voltage
Syntax
#include <ctools.h>
INT16 readInputVoltage (void);
Description
The readInputVoltage function returns the input supply voltage in millivolts. The
typical range is 9000 to 30000 mV.
Example
#include <ctools.h>
if (readInputVoltage() < 9000)
{
fprintf(com1, "The input supply voltage is low\r\n");
}
Document (Version 1.61) 5/19/2011
464
Function Specifications
readIntVariable
Read IEC 61131-1 Integer Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the variable
value is written to the signed long value pointed to by value. If the variable is not
found or if the IEC 61131-1 Symbols Status is invalid, FALSE is returned and the
current value is left unchanged. The IEC 61131-1 Symbols Status is invalid if the
Application TIC code download and Application Symbols download are not
sharing the same symbols CRC checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the dbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
See Also
readRealVariable
Example
This program displays the contents of the integer variable named “Temperature”.
#include <ctools.h>
int main(void)
{
BOOLEAN
status;
INT32 value;
request_resource(IO_SYSTEM);
status = readIntVariable("Temperature", &value);
release_resource(IO_SYSTEM);
Document (Version 1.61) 5/19/2011
465
Function Specifications
fprintf(com1,"status = %u, Temp = %ld\r\n", status, value);
}
Document (Version 1.61) 5/19/2011
466
Function Specifications
readMsgVariable
Read IEC 61131-1 Message Variable (IEC 61131-1 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-1 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-1 Symbols Status is invalid, FALSE is returned and the buffer is left
unchanged. The IEC 61131-1 Symbols Status is invalid if the Application TIC
code download and Application Symbols download are not sharing the same
symbols CRC checksum.
The pointer msg needs to point to a character string large enough to hold the
maximum length declared for the specified message variable plus two length
bytes and a null termination byte (i.e. max declared length + 3). IEC 61131-1
message variables have the following format:
Byte
Location
Description
0
Maximum length as declared in IEC 61131-1
Dictionary (1 to 255)
Current Length = number of bytes up to first
null byte in message data (0 to maximum
length)
First message data byte
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-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the dbase
function.
Document (Version 1.61) 5/19/2011
467
Function Specifications
The IO_SYSTEM system resource needs to be requested before calling this
function.
See Also
readIntVariable, readRealVariable
Example
This program displays the contents of the message variable named “msgData” of
maximum length 20.
#include <ctools.h>
int main(void)
{
BOOLEAN status;
UCHAR msg[23];
request_resource(IO_SYSTEM);
status = readMsgVariable("msgData", msg);
release_resource(IO_SYSTEM);
fprintf(com1,"status = %u, max length = %d, current length
= %d,
message = %s\r\n", status, msg[0], msg[1], msg + 2);
}
Document (Version 1.61) 5/19/2011
468
Function Specifications
readRealVariable
Read IEC 61131-1 Real Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the variable
value is written to the floating point value pointed to by value. If the variable is not
found or if the IEC 61131-1 Symbols Status is invalid, FALSE is returned and the
current value is left unchanged. The IEC 61131-1 Symbols Status is invalid if the
Application TIC code download and Application Symbols download are not
sharing the same symbols CRC checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the dbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
See Also
readIntVariable
Example
This program displays the contents of the real variable named “Flow”.
#include <ctools.h>
int main(void)
{
BOOLEAN
float
status;
value;
request_resource(IO_SYSTEM);
status = readRealVariable("Flow", &value);
release_resource(IO_SYSTEM);
Document (Version 1.61) 5/19/2011
469
Function Specifications
fprintf(com1,"status = %u, Flow = %f\r\n", status, value);
}
Document (Version 1.61) 5/19/2011
470
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>
int main(void)
{
UINT32 startTime, endTime;
startTime = readStopwatch();
/* operation to be timed */
endTime = readStopwatch();
fprintf(com1,"Execution time = %lu ms\r\n", endTime startTime);
}
Document (Version 1.61) 5/19/2011
471
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 1.61) 5/19/2011
472
Function Specifications
readTimerVariable
Read IEC 61131-1 Timer Variable (IEC 61131-1 firmware only)
Syntax
#include <ctools.h>
BOOLEAN readTimerVariable(UCHAR * varName, UINT32 * value)
Description
This function returns the current value in milliseconds of the specified timer
variable. The maximum value returned is 86399999 ms (or 24 hours). The
specified timer may be active or stopped.
The variable is specified by its name expressed as a character string. The name
is case insensitive (The IEC 61131-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the variable
value is written to the unsigned long value pointed to by value. If the variable is
not found or if the IEC 61131-1 Symbols Status is invalid, FALSE is returned and
the current value is left unchanged. The IEC 61131-1 Symbols Status is invalid if
the Application TIC code download and Application Symbols download are not
sharing the same symbols CRC checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the dbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
See Also
readIntVariable, readRealVariable
Example
This program displays the contents of the timer variable named “Time1”.
#include <ctools.h>
int main(void)
{
BOOLEAN status;
UINT32 value;
request_resource(IO_SYSTEM);
status = readTimerVariable("Time1", &value);
Document (Version 1.61) 5/19/2011
473
Function Specifications
release_resource(IO_SYSTEM);
fprintf(com1,"status = %u, Time1 = %lu\r\n", status,
value);
}
Document (Version 1.61) 5/19/2011
474
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
send_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();
fprintf(com1,"Message data %ld\r\n", msg->data);
deallocate_envelope(msg);
}
}
Document (Version 1.61) 5/19/2011
475
Function Specifications
recv
Syntax
#include <ctools.h>
int recv
(
int socketDescriptor,
char * bufferPtr,
int bufferLength,
int flags
);
Description
recv is used to receive messages from another socket. recv may be used only on
a connected socket (see connect, accept). socketDescriptor is a socket created
with socket or accept. The length of the message is returned. If a message is too
long to fit in the supplied buffer, excess bytes may be discarded depending on
the type of socket the message is received from (see socket). The length of the
message returned could also be smaller than bufferLength (this is not an error). If
no messages are available at the socket, the receive call waits for a message to
arrive, unless the socket is non-blocking, or the MSG_DONTWAIT flag is set in
the flags parameter, in which case -1 is returned with socket error being set to
EWOULDBLOCK.
Out-of-band data not in the stream (urgent data when the SO_OOBINLINE
option is not set (default)) (TCP protocol only).
A single out-of-band data byte is provided with the TCP protocol when the
SO_OOBINLINE option is not set. If an out-of-band data byte is present, recv
with the MSG_OOB flag not set will not read past the position of the out-of-band
data byte in a single recv request. That is, if there are 10 bytes from the current
read position until the out-of-band byte, and if we execute a recv specifying a
bufferLength of 20 bytes, and a flag value of 0, recv will only return 10 bytes. This
forced stopping is to allow us to determine when we are at the out-of-band byte
mark. When we are at the mark, recv with the MSG_OOB flag set can read the
out-of-band data byte. The user needs to use select in order to know when outof-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
the position of the out-of-band mark in a single recv request. The user needs to
use select in order to know when out-of-band data has arrived, or is arriving.
Document (Version 1.61) 5/19/2011
476
Function Specifications
select may be used to determine when more data arrives, or/and when out-ofband data arrives.
Parameters
socketDescriptor
The socket descriptor to receive data from.
bufferPtr
The buffer to put the received data into
bufferLength
The length of the buffer area that bufferPtr points to
flags
See below
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:
EBADF
The socket descriptor is invalid
ENOBUFS
There was insufficient user memory available to
complete the operation
EMSGSIZE
The socket requires that message be received
atomically, and bufferLength was too small
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
ESHUTDOWN
The remote socket has closed the connection, and there
is no more data to be received (TCP socket only)
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
ENOTCONN
Socket is not connected.
Document (Version 1.61) 5/19/2011
477
Function Specifications
recvfrom
Syntax
#include <ctools.h>
int recvfrom(
int socketDescriptor,
char * bufferPtr,
int bufferLength,
int flags,
struct sockaddr * fromPtr,
int * fromLengthPtr);
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.
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 1.61) 5/19/2011
478
Function Specifications
Returns
>0
Number of bytes actually received from the socket.
0
EOF
-1
An error occurred
recvfrom will fail if:
EBADF
The socket descriptor is invalid.
EINVAL
One of the parameters is invalid.
EMSGSIZE
The socket requires that message be received
atomically, and bufferLength was too small.
EPROTOTYPE
TCP protocol requires usage of recv, not
recvfrom.
ENOBUFS
There was insufficient user memory available to comp
lete the operation.
EWOULDBLOCK
The socket is marked as non-blocking and no data is
available to be read.
Document (Version 1.61) 5/19/2011
479
Function Specifications
registerBulkDevOperation
Register bulk device operation
Syntax
#include <ctools.h>
BOOLEAN registerBulkDevOperation(char* extDriveName);
Description
registerBulkDevOperation function registers that the removable bulk memory
device is about to be used for an operation. Registration is necessary prior to
using the device in case the device is un-mounted before the operation
completes. This provides that internal resources used for the bulk device are
correctly released. The unregisterBulkDevOperation should be called after the
operation is completed..
Parameters
extDriveName The mounted bulk device drive name, typically “/bd0”.
Returns
TRUE
Registration was successful;
FALSE
The drive name was invalid.
Notes
The registerBulkDevOperation and unregisterBulkDevOperation should only be
used with a dynamically mounted bulk device, such as a USB memory stick. The
unregisterBulkDevOperation needs to be called with the same device drive name
as the registerBulkDevOperation.
See Also
unregisterBulkDevOperation
Example
#include <ctools.h>
int main(void)
{
if (registerBulkDevOperation(“/bd0”) == FALSE)
{
printf("registerBulkDevOperation /bd0 failed.\r\n");
}
Copy(“/d0/logs/log1”, “/bd0/logs/log1”);
if (unregisterBulkDevOperation(“/bd0”) == FALSE)
{
Document (Version 1.61) 5/19/2011
480
Function Specifications
printf("unregisterBulkDevOperation /bd0
failed.\r\n");
}
}
Document (Version 1.61) 5/19/2011
481
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 using a time slicing mechanism. release_processor puts the task
explicitely at the end of the round-robin-queue.
Notes
Calling release_processor in all idle loops is not necessary anymore. In contrary,
it reduces the fair share of CPU time because the CPU is given up before the
end of the time slice. The function release_processor still makes sense if the
calling task does not have anything to do for the moment.
Release all resources in use by a task before releasing the processor.
Refer to the Real Time Operating System section for more information on tasks
and task scheduling.
See Also
request_resource
Document (Version 1.61) 5/19/2011
482
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
Example
See the Example for the request_resource function.
Document (Version 1.61) 5/19/2011
483
Function Specifications
removeModbusHandler
Removes a User Defined Modbus Handler
Syntax
#include <ctools.h>
BOOLEAN removeModbusHandler(
UINT16 (* handler)(UCHAR *, UINT16,
UCHAR *, UINT16 *)
);
Description
The removeModbusHandler function allows user-defined extensions to standard
Modbus protocol to be removed. This function specifies the previously installed
function that is to be removed.
This function returns TRUE if the specified handler was removed, and FALSE if
the specified handler is not present.
Notes
This function is used to remove a user-defined extension to the standard Modbus
protocol.
See Also
installModbusHandler
Document (Version 1.61) 5/19/2011
484
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 1.61) 5/19/2011
485
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
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 1.61) 5/19/2011
486
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 1.61) 5/19/2011
487
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 1.61) 5/19/2011
488
Function Specifications
route
Redirect Standard I/O Streams
Syntax
#include <ctools.h>
void route(UCHAR logical, UCHAR 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 by default. logical
specifies the stream to redirect. hardware specifies the hardware device which
will output the data. It may be one of 0 = com1, 1 = com2, or 2 = com3.
Notes
This function has a global effect, so all tasks need to agree on the routing.
Output streams need to be redirected to a device that supports output. Input
streams need to be redirected to a device that supports input.
The use of this function is strongly discouraged since tasks beyond the control of
the C Application may make use of the streams stdout, stdin, and stderr. This
may result in data being unexpectedly added or removed from these streams.
Example
This program segment will redirect all input, output and errors to the com2 serial
port.
#include <ctools.h>
route(STD_ERR, 1);
/* send errors to com2 */
route(STD_OUT, 1);
/* send output to com2 */
route(STD_IN, 1);
/* get input from com2 */
rresvport
Syntax
#include <ctools.h>
int rresvport
(
int * portToReservePtr
);
Document (Version 1.61) 5/19/2011
489
Function Specifications
Description
rresvport is used to create a TCP socket and bind a reserved port to the socket
starting with the port to reserve given by the user. The 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 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
getErrorCode(socketDescriptor).
rresvport will fail if:
EAGAIN
The TCP/IP stack could not find any port number
available between IPPORT_RESERVEDSTART and the
port number to reserve.
EINVAL
Bad parameter; pointer is null or port number to reserve
is less than IPPORT_RESERVEDSTART (600).
Document (Version 1.61) 5/19/2011
490
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 1.61) 5/19/2011
491
Function Specifications
runIOSystem
Run I/O System
Syntax
#include <ctools.h>
void 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.
This function should only be needed in the context of the startup function
appstart.
Document (Version 1.61) 5/19/2011
492
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 a ladder logic
program is loaded and running in the controller the interpreter sets the RUN LED
to ON. In this situation if the C application turns the RUN LED to OFF a conflict
occurs and the RUN LED will blink OFF and ON.
Example
#include <ctools.h>
int main(void)
{
runLed(LED_ON);
/* program is running */
/* ... the rest of the code */
}
Document (Version 1.61) 5/19/2011
493
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.
See Also
mTcpMasterMessage
Document (Version 1.61) 5/19/2011
494
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-1
firmware this is the IEC 61131-1 IEC 1131 run-time engine.
Calling the function with the argument state set to FALSE stops the run-time
engine task. Calling the function with state set to TRUE starts the task.
This function should only be needed in the context of the startup function
appstart.
Document (Version 1.61) 5/19/2011
495
Function Specifications
select
Syntax
#include <ctools.h>
int select
(
int numberSockets,
fd_set * readSocketsPtr,
fd_set * writeSocketsPtr,
fd_set * exceptionSocketsPtr,
struct timeval * timeOutPtr
);
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.
timeOutPtr
The pointer to a structure containing the length of time to
wait for an event before exiting.
Document (Version 1.61) 5/19/2011
496
Function Specifications
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
getErrorCode(socketDescriptor).
select will fail if:
EBADF
One of the socket descriptors is bad.
EINVAL
A component of the pointed-to time limit is outside the
acceptable range: tv_sec needs to be between 0 and
10^8, inclusive. tv_usec needs to be greater than or
equal to 0, and less than 10^6.
Document (Version 1.61) 5/19/2011
497
Function Specifications
send
Syntax
#include <ctools.h>
int send
(
int socketDescriptor,
char * bufferPtr,
int bufferLength,
int flags
);
Description
send is used to transmit a message to another transport end-point. send may be
used only when the socket is in a connected state. socketDescriptor is a socket
created with socket.
If the message is too long to pass atomically through the underlying protocol (non
TCP protocol), then the error EMSGSIZE is returned and the message is not
transmitted.
A return value of -1 indicates locally detected errors only. A positive return value
does not implicitly mean the message was delivered, but rather that it was sent.
Blocking socket send: if the socket does not have enough buffer space available
to hold the message being sent, send blocks.
Non blocking stream (TCP) socket send: if the socket does not have enough
buffer space available to hold the message being sent, the send call does not
block. It can send as much data from the message as can fit in the TCP buffer
and returns the length of the data sent. If none of the message data fits, then –1
is returned with socket error being set to EWOULDBLOCK.
Non blocking datagram socket send: if the socket does not have enough buffer
space available to hold the message being sent, no data is being sent and -1 is
returned with socket error being set to EWOULDBLOCK.
The select call may be used to determine when it is possible to send more data.
Sending Out-of-Band Data:
For Example, if you have remote login application, 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 1.61) 5/19/2011
498
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 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 actually sent on the socket
-1
An error occurred.
send will fail if:
EBADF
The socket descriptor is invalid.
ENOBUFS
There was insufficient user memory available to
complete the operation.
EHOSTUNREACH
Non-TCP socket only. No route to destination host.
EMSGSIZE
The socket requires that message to be sent atomically,
and the message was too long.
Document (Version 1.61) 5/19/2011
499
Function Specifications
EWOULDBLOCK
The socket is marked as non-blocking and the send
operation would block.
ENOTCONN
Socket is not connected.
ESHUTDOWN
User has issued a write shutdown (TCP socket only).
Document (Version 1.61) 5/19/2011
500
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
receive_message
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();
fprintf(com1,"Message data %ld\r\n", msg->data);
deallocate_envelope(msg);
}
}
int main(void)
{
envelope *msg;
unsigned tid;
/* message pointer */
/* task ID */
tid = create_task(showIt, 100, applicationGroup, 4);
msg = allocate_envelope();
msg->destination = tid;
msg->type
= MSG_DATA;
msg->data
= 1002;
Document (Version 1.61) 5/19/2011
501
Function Specifications
send_message(msg);
/* wait for ever so that main and other
APPLICATION tasks won’t end */
while(TRUE)
{
/* Allow other tasks to execute */
release_processor();
}
}
Document (Version 1.61) 5/19/2011
502
Function Specifications
sendto
Syntax
#include <trsocket.h>
int sendto
(
int socketDescriptor,
char * bufferPtr,
int bufferLength,
int flags,
const struct sockaddr * toPtr,
int toLength
);
Description
sendto is used to transmit a message to another transport end-point. sendto may
be used at any time (either in a connected or unconnected state), but not for a
TCP socket. socketDescriptor is a socket created with socket. The address of the
target is given by to with toLength specifying its size. If the message is too long
to pass atomically through the underlying protocol, then –1 is returned with the
socket error being set to EMSGSIZE, and the message is not transmitted.
A return value of -1 indicates locally detected errors only. A positive return value
does not implicitly mean the message was delivered, but rather that it was sent.
If the socket does not have enough buffer space available to hold the message
being sent, and is in blocking mode, sendto blocks. If it is in non-blocking mode
or the MSG_DONTWAIT flag has been set in the flags parameter, –1 is returned
with the socket error being set to EWOULDBLOCK. The select call may be used
to determine when it is possible to send more data.
Parameters
socketDescriptor
The socket descriptor to use to send data.
bufferPtr
The buffer to send.
bufferLength
The length of the buffer to send.
toPtr
The address to send the data to.
toLength
The length of the to area pointed to by toPtr.
flags
See below
The flags parameter is formed by ORing one or more of the following:
MSG_DONTWAIT
Don‟t wait for data send to complete, but rather return
immediately.
MSG_DONTROUTE
The SO_DONTROUTE option is turned on for the
duration of the operation. Only diagnostic or routing
programs use it.
Document (Version 1.61) 5/19/2011
503
Function Specifications
Returns
Value
Meaning
>=0
Number of bytes actually sent on the socket
-1
An error occurred
sendto will fail if:
EBADF
The socket descriptor is invalid.
ENOBUFS
There was insufficient user memory available to
complete the operation.
EHOSTUNREACH
No route to destination host.
EMSGSIZE
The socket requires that message be sent atomically,
and the message was too long.
EPROTOTYPE
TCP protocol requires usage of send not sendto.
EWOULDBLOCK
The socket is marked as non-blocking and the send
operation would block.
Document (Version 1.61) 5/19/2011
504
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-1 master function block.
Notes
Refer to the communication protocol manual for more information.
To optimize performance, minimize the length of messages on com3. Examples
of recommended uses for com3 are for local operator display terminals, and for
programming and diagnostics using the IEC 61131-1 program.
The IO_SYSTEM resource needs to be requested before calling this function.
Document (Version 1.61) 5/19/2011
505
Function Specifications
See Also
get_protocol_status, clear_protocol_status, master_message
Example
See the Example in the Example Programs chapter under the section Master
Message Example Using serialModbusMaster.
setABConfiguration
Document (Version 1.61) 5/19/2011
506
Function Specifications
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 1.61) 5/19/2011
507
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 1.61) 5/19/2011
508
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 needs to be set with valid values for the clock to operate
properly.
Notes
The IO_SYSTEM resource needs to be requested before calling this function.
See Also
getclock
Example
This function switches the clock to daylight savings time.
#include <ctools.h>
void daylight(void)
{
TIME now;
request_resource(IO_SYSTEM);
getclock(&now);
now.hour = now.hour + 1 % 24;
setclock(&now);
request_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
509
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
getClockAlarm
Document (Version 1.61) 5/19/2011
510
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>
int main(void)
{
request_resource(IO_SYSTEM);
setdbase(MODBUS, 40001, 102);
/* Turn ON the first 16 coils */
setdbase(LINEAR, START_COIL, 255);
/* Write to a 16 bit register */
setdbase(LINEAR, 3020, 240);
Document (Version 1.61) 5/19/2011
511
Function Specifications
/* Write to the 12th holding register */
setdbase(LINEAR, START_HOLDING, 330);
/* Write to the 12th holding register */
setdbase(LINEAR, START_HOLDING, 330);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
512
Function Specifications
Setdbase Handler Function
User Defined Setdbase Handler Function
The setdbase handler function is a user-defined function that handles writing to
Modbus addresses not assigned in the IEC 61131-1 Dictionary. The function can
have any name; setdbaseHandler is used in the Description below.
Syntax
#include <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-1 application downloaded, or

There is no IEC 61131-1 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 must be requested before calling setdbase, which
calls this handler. Requesting the IO_SYSTEM resource provides that only one
task may call the handler at a time. Therefore, the function does not have to be
re-entrant.
An array may be defined to store the current values for all Modbus addresses
handled by this function. See the section Data Storage if a non-initialized data
array is required.
See Also
installSetdbaseHandler
Document (Version 1.61) 5/19/2011
513
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 port. When state is SIGNAL_ON the DTR line is asserted.
When state is SIGNAL_OFF the DTR line is de-asserted.
Notes
The DTR line follows the normal RS232 voltage levels for asserted and 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 1.61) 5/19/2011
514
Function Specifications
setFtpServerState
Sets the state of the FTP server.
Syntax
#include <ctools.h>
BOOLEAN setFtpServerState(
UINT32 state
);
Parameters
state specifies the desired operational state of the FTP server. The following
values for state are defined:

0 = FTP server disabled

1 = FTP server enabled, anonymous login permitted

2 = FTP server enabled, username and password required
Description
The setFtpServerState function sets the state of the FTP server. TRUE is
returned if the specified state was set. FALSE is returned if the specified state
could not be set.
Notes
This function is only relevant for Ethernet enabled controllers.
See Also
getFtpServerState
Document (Version 1.61) 5/19/2011
515
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
clearRegAssignment
getForceFlag
getOutputsInStopMode
overrideDbase
Document (Version 1.61) 5/19/2011
516
Function Specifications
Example
This program clears the force flag for register 40001 and sets the force flags for
the 16 registers at linear address 302 (i.e. registers 10737 to 10752).
#include <ctools.h>
int main(void)
{
request_resource(IO_SYSTEM);
setForceFlag(MODBUS, 40001, 0);
setForceFlag(LINEAR, 302, 255);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
517
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, SCADAPack 32 System Manual, or
SCADAPack 350 System Manual for further information on the Status LED and
Status Output.
See Also
getIOErrorIndication
Document (Version 1.61) 5/19/2011
518
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>
int main(void)
{
unsigned holdDoutsOnStop;
unsigned holdAoutsOnStop;
getOutputsInStopMode( &holdDoutsOnStop, &holdAoutsOnStop);
holdAoutsOnStop = TRUE;
setOutputsInStopMode( holdDoutsOnStop, holdAoutsOnStop);
}
Document (Version 1.61) 5/19/2011
519
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. port needs to
specify one of com1, com2, or com3. settings references a serial port
configuration structure. Refer to the Description of the pconfig structure for an
explanation of the 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.
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 1.61) 5/19/2011
520
Function Specifications
request_resource(IO_SYSTEM);
set_port(com2, get_port(com1, &settings));
release_resource(IO_SYSTEM);
Document (Version 1.61) 5/19/2011
521
Function Specifications
setLoginCredentials
Sets login credentials for a service
Syntax
#include <ctools.h>
BOOLEAN setLoginCredentials(
UINT32 service,
UINT32 index,
UCHAR* username,
UCHAR* password
);
Parameters
service specifies the service for which the credentials are being set.
index specifies the index for the credentials. Indices are service specific.
username specifies the username to grant access to.
password specifies the password that is valid with the username.
Description
The setLoginCredentials function registers a username and password pair for the
specified service.
Valid services are:
0 = FTP. Maximum username and password length is 16 bytes. Only index 0 is
supported
The valid values of index are service specific. The username and password are
both NULL terminated strings with a service defined maximum length.
True is returned if the credentials were set. False is returned if the service
rejected the credentials, or if the service was unrecognized.
Notes
Duplicate usernames are supported.
See Also
getLoginCredentials, clearLoginCredentials
Document (Version 1.61) 5/19/2011
522
Function Specifications
setPowerMode
Set Current Power Mode
Syntax
#include <ctools.h>
BOOLEAN setPowerMode(UCHAR cpuPower, UCHAR lan, UCHAR usbHost);
Description
The setPowerMode function returns TRUE if the new settings were successfully
applied. The setPowerMode function allows for power savings to be realised by
controlling the power to the LAN port, changing the clock speed, and individually
controlling the host and peripheral USB power. The following table of macros
summarizes the choices available.
Macro
Meaning
PM_CPU_FULL
PM_CPU_REDUCED
PM_CPU_SLEEP
PM_LAN_ENABLED
PM_LAN_DISABLED
PM_USB_HOST_ENABLED
PM_USB_HOST_DISABLED
PM_NO_CHANGE
The CPU is set to run at full speed
The CPU is set to run at a reduced speed
The CPU is set to sleep mode
The LAN is enabled
The LAN is disabled
The USB host port is enabled
The USB host port is disabled
The current value will be used
TRUE is returned if the requested change was made, otherwise FALSE is
returned.
The application program may view the current power mode with the
getPowerMode function.
See Also
getPowerMode, setWakeSource, getWakeSource
Document (Version 1.61) 5/19/2011
523
Function Specifications
setProgramStatus
Set Program Status Flag
Syntax
#include <ctools.h>
void setProgramStatus(FUNCPTR entryPoint, UINT16 status);
Description
The setProgramStatus function sets the application program status flag. The
status flag is set to NEW_PROGRAM when a cold boot of the controller is
performed, or a program is downloaded to the controller from the program loader.
The parameter entryPoint should always be set to the function main.
Notes
There are three pre-defined values for the flag. However the application program
may make whatever use of the flag it sees fit.
NEW_PROGRAM
indicates the program is newly loaded.
PROGRAM_EXECUTED
indicates the program has been executed.
PROGRAM_NOT_LOADED
indicates that the requested program is not
loaded
See Also
getProgramStatus
Example
See Get Program Status Example.
Document (Version 1.61) 5/19/2011
524
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. port needs to specify one of
com1, com2 or com3. settings references a protocol configuration structure.
Refer to the Description of the prot_settings structure for an explanation of the
fields.
The set_protocol function returns TRUE if the settings were changed. It returns
FALSE if there is an error in the settings or if the protocol does not start.
The IO_SYSTEM resource needs to be requested before calling this function.
To save these settings with the controller settings in flash memory so that they
are loaded on controller reset, call flashSettingsSave as shown below.
request_resource(FLASH_MEMORY);
flashSettingsSave(CS_RUN);
release_resource(FLASH_MEMORY);
Notes
Setting the protocol type to NO_PROTOCOL ends the protocol task and frees
the stack resources allocated to it.
Add a call to modemNotification when writing a custom protocol.
See Also
get_protocol
Example
This code fragment changes the station number of the com2 protocol to 4.
#include <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 1.61) 5/19/2011
525
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: port is one of com1, com2, or com3; and
settings, a pointer to a PROTOCOL_SETTINGS structure. Refer to the
Description of the structure for an explanation of the parameters.
The function returns TRUE if the settings were changed. It returns FALSE if the
stream is not valid, or if the protocol does not start.
The 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.
Example
This code fragment sets protocol parameters for the com2 serial port.
#include <ctools.h>
PROTOCOL_SETTINGS settings;
settings.type
settings.station
settings.priority
settings.SFMessaging
settings.mode
Document (Version 1.61) 5/19/2011
=
=
=
=
=
MODBUS_RTU;
1234;
250;
FALSE;
AM_extended;
526
Function Specifications
request_resource(IO_SYSTEM);
setProtocolSettings(com2, &settings);
release_resource(IO_SYSTEM);
Document (Version 1.61) 5/19/2011
527
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:

port specifies the serial port. It is one of com1, com2 or com3.

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.
Example
This code fragment sets protocol parameters for the com2 serial port.
#include <ctools.h>
PROTOCOL_SETTINGS_EX settings;
settings.type =
Document (Version 1.61) 5/19/2011
MODBUS_RTU;
528
Function Specifications
settings.station =
settings.priority =
settings.SFMessaging =
settings.mode =
settings.enronEnabled =
settings.enronStation =
1;
250;
FALSE;
AM_standard;
TRUE;
4;
request_resource(IO_SYSTEM);
setProtocolSettingsEx(com2, &settings);
release_resource(IO_SYSTEM);
Document (Version 1.61) 5/19/2011
529
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 and with authentication.
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 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 1.61) 5/19/2011
530
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 in the Store and Forward Table are not needed to describe the
response path.
The IO_SYSTEM resource needs to be requested before calling this function.
To save the Store and Forward Table with the controller settings in flash memory
so that it is loaded on controller reset, call flashSettingsSave as shown below.
// save Store & 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, or com3
Modbus IP Interface:
e.g. Ethernet1
Serial Modbus Interface:
e.g. com1, com2, or com3
Serial Modbus Interface:
e.g. com1, com2, or com3
Serial Modbus Interface:
e.g. com1, com2, or com3
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
forwardIPAddress is needed to know where to connect so that the command can
be forwarded to its final destination.
Document (Version 1.61) 5/19/2011
531
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 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
Document (Version 1.61) 5/19/2011
532
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 stored even if invalid.
If the userName parameter is non-NULL then the Store and Forward entry will be
set to use authentication, with the user name set to the contents of the array
pointed to by userName and the password set to the contents of the array
pointed to by password. Both userName and password need to point to arrays of
16 characters. User names and passwords shorter than 16 characters should be
padded to 16 characters with spaces. If the userName parameter is NULL then
no authentication information will be stored with the Store and Forward entry.
The SF_TRANSLATION_EX structure supports a timeout and is described in the
Structures and Types section.
The function returns a SFTranslationStatus structure. It is described in the
Structures and Types section. The code field of the structure is set to one of the
following. If there is an error, the index field is set to the location of the translation
that is not valid.
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.
Document (Version 1.61) 5/19/2011
533
Function Specifications
Writing a translation with both stations set to station 65535 can clear a translation
in the table. Station 65535 is not a valid station.
The Modbus protocol type and communication parameters may differ between
serial ports. The store and forward messaging will translate the protocol
messages.
Translations describe the communication path of the master command: e.g. the
slave interface which receives the command and the forwarding interface to
forward the command. The response to the command is automatically returned
to master through the same communication path in reverse.
Additional entries in the Store and Forward Table are not needed to describe the
response path.
The IO_SYSTEM resource needs to be requested before calling this function.
To save the Store and Forward Table with the controller settings in flash memory
so that it is loaded on controller reset, call flashSettingsSave as shown below.
// save Store & 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, or com3
Modbus IP Interface:
e.g. Ethernet1
Serial Modbus Interface:
e.g. com1, com2, or com3
Serial Modbus Interface:
e.g. com1, com2, or com3
Serial Modbus Interface:
e.g. com1, com2, or com3
Modbus IP Network:
e.g. Modbus/TCP, Modbus RTU over UDP,
or Modbus ASCII over UDP
Modbus IP Interface:
Modbus IP Network:
e.g. Ethernet1
e.g. Modbus/TCP, Modbus RTU over UDP,
or Modbus ASCII over UDP
Modbus IP Network as Forwarding Interface
When forwarding to a TCP or UDP network, the protocol type is selected for the
forwardInterface in the SF_TRANSLATION_EX structure. The IP Stack
automatically determines the exact interface (e.g. Ethernet1) to use when it
searches the network for the 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
forwardIPAddress is needed to know where to connect so that the command can
be forwarded to its final destination.
Document (Version 1.61) 5/19/2011
534
Function Specifications
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_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 1.61) 5/19/2011
535
Function Specifications
setsockopt
Syntax
#include <ctools.h>
int setsockopt
(
int socketDescriptor,
int protocolLevel,
int optionName,
const char * optionValue,
int optionLength
);
Description
setsockopt is used manipulate options associated with a socket. Options may
exist at multiple protocol levels; they are always present at the uppermost
“socket” level. When manipulating socket options, the level at which the option
resides and the name of the option must be specified. To manipulate options at
the “socket” level, protocolLevel is specified as SOL_SOCKET. To manipulate
options at any other level, 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.
SO_REUSEADDR
Enable/disable local address reuse. Default 0 (disable).
Document (Version 1.61) 5/19/2011
536
Function Specifications
SO_RCVLOWAT
The low water mark for receiving data.
SO_SNDLOWAT
The low water mark for sending data.
SO_R CVBUF
Set buffer size for input. Default 8192 bytes.
SO_SNDBUF
Set buffer size for output. Default 8192 bytes.
SO_REUSEADDR indicates that the rules used in validating addresses supplied
in a bind call should allow reuse of local addresses. SO_KEEPALIVE enables the
periodic transmission of messages on a connected socket. If the connected party
fails to respond to these messages, the connection is considered broken.
SO_DONTROUTE indicates that outgoing messages should bypass the standard
routing facilities. Instead, messages are directed to the appropriate network
interface according to the network portion of the destination address.
SO_LINGER controls the action taken when unsent messages are queued on a
socket and a close on the socket is performed. If the socket promises reliable
delivery of data and SO_LINGER is set, the system will block the process on the
close of the socket attempt until it is able to transmit the data or decides it is
unable to deliver the information. A timeout period, termed the linger interval, is
specified in the setsockopt call when SO_LINGER is requested. If SO_LINGER
is disabled and a close on the socket is issued, the system will process the close
of the socket in a manner that allows the process to continue as quickly as
possible. The option SO_BROADCAST requests permission to send broadcast
datagrams on the socket. With protocols that support out-of-band data, the
SO_OOBINLINE option requests that out-of-band data be placed in the normal
data input queue as received; it will then be accessible with recv call without the
MSG_OOB flag.
SO_SNDBUF and SO_RCVBUF are options that adjust the normal buffer sizes
allocated for output and input buffers, respectively. The buffer size may be
increased for high-volume connections or may be decreased to limit the possible
backlog of incoming data. The Internet protocols place an absolute limit of 64
Kbytes on these values for UDP and TCP sockets (in the default mode of
operation).
The following options are recognized at the IP level:
IP_PROTOIP protocolLevel options
IP_TOS
IP type of service. Default 0.
IP_TTL
IP Time To Live in seconds. Default 64.
IP_MULTICAST_TTL
Change the default IP TTL for outgoing multicast
datagrams
IP_MULTICAST_IF
Specify a configured IP address that will uniquely identify
the outgoing interface for multicast datagrams sent on
this socket. A zero IP address parameter indicates that
we want to reset a previously set outgoing interface for
multicast packets sent on that socket
The following options are recognized at the TCP level.
IP_PROTOTCP
Document (Version 1.61) 5/19/2011
protocolLevel options
537
Function Specifications
TCP_MAXSEG
Sets the maximum TCP segment size sent on the
network. The TCP_MAXSEG value is the maximum
amount of data (including TCP options, but not the TCP
header) that can be sent per segment to the peer., i.e
the amount of user data sent per segment is the value
given by the TCP_MAXSEG option minus any enabled
TCP option (for example 12 bytes for a TCP time stamp
option) . The TCP_MAXSEG value can be decreased or
increased prior to a connection establishment, but it is
not recommended to set it to a value higher than the IP
MTU minus 40 bytes (for example 1460 bytes on
Ethernet), since this would cause fragmentation of TCP
segments. Setting the TCP_MAXSEG option will inhibit
the automactic computation of that value by the system
based on the IP MTU (which avoids fragmentation), and
will also inhibit Path Mtu Discovery. After the connection
has started, this value cannot be changed. The
TCP_MAXSEG value cannot be set below 64 bytes.
Default value is IP MTU minus 40 bytes.
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.
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
Document (Version 1.61) 5/19/2011
Option data
type
int
int
struct linger
Option
value
0 or 1
0 or 1
538
Function Specifications
ProtocolLevel
IP_PROTOIP
IP_PROTOTCP
Option Name
SO_OOBINLINE
SO_RCVBUF
SO_RCVLOWAT
SO_REUSEADDR
SO_SNDBUF
SO_SNDLOWAT
IP_TOS
IP_TTL
IP_MULTICAST_TTL
IP_MULTICAST_IF
TCP_MAXSEG
TCP_NODELAY
Option data
type
int
unsigned long
unsigned long
int
unsigned long
unsigned long
unsigned char
unsigned char
unsigned char
struct in_addr
int
int
Option
value
0 or 1
0 or 1
0 or 1
Returns
0
Successful set of option
-1
An error occurred
setsockopt will fail if:
EBADF
The socket descriptor is invalid
EINVAL
One of the parameters is invalid
ENOPROTOOPT
The option is unknown at the level indicated.
EPERM
Option cannot be set after the connection has been established.
ENETDOWN
Specified interface not configured yet
EADDRINUSE Multicast host group already added to the interface
ENOBUF
Not enough memory to add new multicast entry.
ENOENT
Attempted to delete a non-existent multicast entry on the
specified interface.
Document (Version 1.61) 5/19/2011
539
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 – all leading zeros are ignored. There
is a two second delay between repetitions.
The STAT LED is located on the top left hand corner of the controller board.
Bits 0, 1 and 2 of the status code are used by the controller firmware. Attempting
to control these bits will result in indeterminate operation.
See Also
getStatusBit
Document (Version 1.61) 5/19/2011
540
Function Specifications
setStatusMode
Set Source for Status LED
Syntax
#include <ctools.h>
void setStatusMode(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 1.61) 5/19/2011
541
Function Specifications
setWakeSource
Sets Conditions for Waking from Sleep Mode
Syntax
#include <ctools.h>
void setWakeSource(UINT32 enableMask);
Description
The setWakeSource routine enables and disables sources that will wake up the
processor. It enables all sources specified by enableMask. All other sources are
disabled.
Valid wake up sources are listed below. Multiple sources may be ORed together.

WS_NONE

WS_ALL

WS_RTC_ALARM

WS_COUNTER_1_OVERFLOW

WS_COUNTER_2_OVERFLOW

WS_COUNTER_3_OVERFLOW

WS_LED_POWER_SWITCH

WS_DIN_1_CHANGE

WS_COM3_VISION
Notes
Specifying WS_NONE as the wake up source will keep the controller from
waking, except by a power on reset.
See Also
getWakeSource, setPowerMode
Example
The code fragments below show how to enable and disable wake up sources.
/* Wake up on all sources */
setWakeSource(WS_ALL);
/* Enable wake up on real time clock only */
setWakeSource(WS_RTC_ALARM);
Document (Version 1.61) 5/19/2011
542
Function Specifications
shutdown
Syntax
#include <ctools.h>
int shutdown
(
int socketDescriptor,
int howToShutdown
);
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:
EBADF
The socket descriptor is invalid
EINVAL
One of the parameters is invalid
ENOPROTOOPT
Document (Version 1.61) 5/19/2011
The option is unknown at the level indicated.
543
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 32767 occurrences of an
event will be recorded. The current task is blocked if there is a higher priority task
waiting for the event.
Notes
Refer to the Real Time Operating System section for more information on events.
Valid events are numbered 0 to RTOS_EVENTS - 1. Any events defined in
ctools.h are not valid events for use in an application program.
This function can be called from application and interrupt code.
See Also
poll_event
Example
This program creates a task to wait for an event, then signals the event.
#include <ctools.h>
void task1(void)
{
while(TRUE)
{
wait_event(20);
fprintf(com1,"Event 20 occurred\r\n");
}
}
int main(void)
{
UINT32 startTime;
create_task(task1, 75, applicationGroup, 4);
while(TRUE)
{
/* body of main task loop */
Document (Version 1.61) 5/19/2011
544
Function Specifications
/* 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
task1 could be executed within main’s wait
loop */
startTime = readStopwatch();
while ((readStopwatch() – startTime) < 1000)
/* wait for 1 s */
{
/* Allow other tasks to execute */
release_processor();
}
signal_event(20);
}
}
Document (Version 1.61) 5/19/2011
545
Function Specifications
sleep_processor
Release Processor to other Tasks for a certain time
Syntax
#include <ctools.h>
void sleep_processor(UINT32 msTime);
Description
The sleep_processor function releases control of the CPU to other tasks for a
certain time. Other tasks of the same priority get a chance to run, or when no
such task is in a ready state lower priority tasks will run. This function is similar to
release_processor with the difference that the CPU is released for at least
msTime, which represents milliseconds. Tasks of the same priority run in a
round-robin fashion, as each releases the processor to the next.
Notes
The call sleep_processor(0) has the same effect as the call release_processor.
Internally the sleep time msTime will be converted into ticks. With a 60 Hz
system clock, the minimum wait time is 16.6 ms. Wait times will be rounded up to
the next tick value.
Refer to the Real Time Operating System section for more information on tasks
and task scheduling.
See Also
release_processor
Document (Version 1.61) 5/19/2011
546
Function Specifications
sleepMode
Suspend Controller Operation
Syntax
#include <ctools.h>
UINT16 sleepMode(void);
Description
The sleepMode function puts the controller into a sleep mode. Sleep mode
reduces the power consumption to a minimum by halting the microprocessor
clock. All programs halt until the controller resumes execution. All output points
turn off while the controller is in sleep mode.
The controller resumes execution under the conditions shown in the table below.
The application program may disable some wake up conditions. If a wake up
condition is disabled the controller will not resume execution when the condition
occurs. All wake up conditions will be enabled by default. Refer to the
Description of the setWakeSource function for details.
sleepMode returns the source that woke the controller from sleep.
See Also
getWakeSource, setWakeSource
Document (Version 1.61) 5/19/2011
547
Function Specifications
socket
Syntax
#include <ctools.h>
int socket
(
int family,
int type,
int protocol
);
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 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
socket should be performed. The communications protocols used to implement a
Document (Version 1.61) 5/19/2011
548
Function Specifications
SOCK_STREAM ensure that data is not lost or duplicated. If a piece of data (for
which the peer protocol has buffer space) cannot be successfully transmitted
within a reasonable length of time, then the connection is considered broken and
calls will indicate an error with (-1) return value and with ETIMEDOUT as the
specific socket error. The TCP protocols optionally keep sockets “warm” by
forcing transmissions roughly every two hours in the absence of other activity. An
error is then indicated if no response can be elicited on an otherwise idle
connection for an extended period (for instance 5 minutes). SOCK_DGRAM or
SOCK_RAW sockets allow 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
Type
Actual protocol
Protocol
PF_INET
SOCK_DGRAM
UDP
IPPROTO_UDP
PF_INET
SOCK_STREAM
TCP
IPPROTO_TCP
PF_INET
SOCK_RAW
IPPROTO_ICMP
ICMP
PF_INET
SOCK_RAW
IPRPTOTO_IGMP
IGMP.
Returns
New Socket Descriptor or –1 on error.
If an error occurred, the socket error can be retrieved by calling
getErrorCode(socketDescriptor).
socket will fail if:
EMFILE
No more sockets are available
ENOBUFS
There was insufficient user memory available to
complete the operation
EPROTONOSUPPORT The protocol type or the specified protocol is not
supported within this family.
Document (Version 1.61) 5/19/2011
549
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 1.61) 5/19/2011
550
Function Specifications
startup_task
Identify Start Up Task
Syntax
#include <ctools.h>
struct taskInfo_tag startup_task(void);
Description
The startup_task function returns the address of the system or application start
up task.
Notes
This function is used by the reset routine. It is normally not used in an application
program.
Document (Version 1.61) 5/19/2011
551
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 RTOS_EVENTS - 1. Any events defined in
primitiv.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 Start
Timed Event Example shows a simple method using the installExitHandler
function.
See Also
endTimedEvent
Document (Version 1.61) 5/19/2011
552
Function Specifications
sysSerialSetRxTimeout
Set Serial Idle Timeout Before Received Characters Signaled
Syntax
#include <ctools.h>
void sysSerialSetRxTimeout(UCHAR port, UCHAR timeout);
Description
The sysSerialSetRxTimeout function causes the operating system to report the
arrival of characters on the specified port after the specified number of 4-bit
timeout intervals.
A port value of 0 specifies com1, 1 specifies com2, and 2 specifies com3.
The timeout specifies the number of 4-bit time intervals that the serial receive line
needs to be idle for before reporting character arrival. Care needs to be
exercised as the character time will consist of a start bit, 7 or 8 data bits, an
optional parity bit, and a stop bit. The number of bits per byte needs to be
calculated for the serial port configuration that is being used. When the specified
timeout has elapsed the installed character hander for that port will be called for
each of the received characters.
Notes
This function is useful for message framing based on the receive line being idle
for a fixed minimum time between messages. The Example below shows a
simple method using the sysSerialSetRxTimeout function to control when serial
data is reported.
Example
This program specifies a timeout of 8 character times on com 1 five seconds
after the program starts, assuming that the port is setup for 8-N-1 operation.
#include <ctools.h>
#define COM1_INDEX
0
BOOLEAN dataToProcess[3] = {FALSE, FALSE, FALSE};
BOOLEAN informOfCharacterArrival(int arg, int c)
{
BOOLEAN retval;
UINT32 previousIntMask;
switch (arg)
{
case 0:
case 1:
case 2:
// Notify of the arrival
if (dataToProcess[arg] == FALSE)
{
Document (Version 1.61) 5/19/2011
553
Function Specifications
switch (arg)
{
case 0:
interrupt_signal_event(COM1_RCVR);
break;
case 1:
interrupt_signal_event(COM2_RCVR);
break;
case 2:
interrupt_signal_event(COM3_RCVR);
break;
default:
// Do nothing this case should be impossible
to each.
break;
}
// Prevent notifications from being generated until
the
// next level has looked at the data
dataToProcess[arg] = TRUE;
}
// We handled the character so return FALSE
retval = TRUE;
break;
default:
// We didn't handle the character so return TRUE
retval = TRUE;
break;
}
return retval;
}
int main(void)
{
UINT32 characterSize;
UCHAR timeoutInterval;
// install the serial character handler
install_handler(com1, informOfCharacterArrival);
// Calculate the character size:
// 1 start bit
// 8 data bits
// no parity bits
// 1 stop bit
characterSize = 1 + 8 + 1;
// Delay for 5 seconds
sleep_processor(5000);
Document (Version 1.61) 5/19/2011
554
Function Specifications
// Determine the number of timeout intervals needed
// The multiplication by 8 is due to 8 character times
// to delay. The division by 4 is because every value
// specifies 4 bit times.
timeoutInterval = characterSize * 8 / 4;
// Set COM1 to signal character arrival after
// 8 character times of silence
sysSerialSetRxTimeout(COM1_INDEX, timeoutInterval);
while(TRUE)
{
// Wait for the serial callback handler to report a
// message has been received
wait_event(COM1_RCVR);
// Reset the data to process flag so that we’ll
// be notified when the next message arrives
dataToProcess[COM1_INDEX] = FALSE;
// Read out data and process message here
…
}
}
See Also
install_handler
Document (Version 1.61) 5/19/2011
555
Function Specifications
unregisterBulkDevOperation
Un-register bulk device operation
Syntax
#include <ctools.h>
BOOLEAN unregisterBulkDevOperation(char* extDriveName);
Description
The unregisterBulkDevOperation function un-registers an operation on a bulk
memory device. It is used in conjunction with the registerBulkDevOperation to
ensure that internal resources used for the bulk device are correctly released if
the device is un-mounted in the middle of an operation.
Parameters
extDriveName The mounted bulk device drive name, typically “/bd0”.
Returns
TRUE
The un-register was successful;
FALSE
The drive name was invalid.
Notes
The registerBulkDevOperation and unregisterBulkDevOperation should only be
used with a dynamically mounted bulk device, such as a USB memory stick. The
unregisterBulkDevOperation needs to be called with the same device drive name
as the registerBulkDevOperation.
See Also
registerBulkDevOperation
Example
#include <ctools.h>
int main(void)
{
if (registerBulkDevOperation(“/bd0”) == FALSE)
{
printf("registerBulkDevOperation /bd0 failed.\r\n");
}
Copy(“/d0/logs/log1”, “/bd0/logs/log1”);
if (unregisterBulkDevOperation(“/bd0”) == FALSE)
{
printf("unregisterBulkDevOperation /bd0
failed.\r\n");
}
Document (Version 1.61) 5/19/2011
556
Function Specifications
}
Document (Version 1.61) 5/19/2011
557
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 RTOS_EVENTS - 1. Any events defined in
primitiv.h are not valid events for use in an application program.
Example
See the Example for the signal_event function.
Document (Version 1.61) 5/19/2011
558
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 1.61) 5/19/2011
559
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 1.61) 5/19/2011
560
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 needs to retrigger the watchdog timer at least every 0.5
seconds using the wd_pulse function, to avoid a controller reset.
Refer to the Functions Overview section for more information.
See Also
wd_enabled
Example
This program takes control of the watchdog timer for a critical section of code,
then returns it to the control of the operating system.
#include <ctools.h>
int main(void)
{
wd_manual();
wd_pulse();
/* ... code executing in less than 0.5 s */
wd_pulse();
/* ... code executing in less than 0.5 s */
wd_auto()
/* ... as much code as you wish */
}
Document (Version 1.61) 5/19/2011
561
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 avoid a
controller reset, if the wd_manual function has been executed.
Refer to the Functions Overview section for more information.
Example
See the Example for the wd_manual function
Document (Version 1.61) 5/19/2011
562
Function Specifications
writeBoolVariable
Write to IEC 61131-1 Boolean Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the specified
value is written to the variable. If the variable is not found or if the IEC 61131-1
Symbols Status is invalid, nothing is done and FALSE is returned. The IEC
61131-1 Symbols Status is invalid if the Application TIC code download and
Application Symbols download are not sharing the same symbols CRC
checksum.
TRUE is written when value is any non-zero value. FALSE is written when value
is 0.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the setdbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
Example
This program writes a TRUE state to the boolean variable named “Switch1”.
#include <ctools.h>
int main(void)
{
BOOLEAN
status;
request_resource(IO_SYSTEM);
status = writeBoolVariable("Switch1", TRUE);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
563
Function Specifications
writeIntVariable
Write to IEC 61131-1 Integer Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the specified
signed long value is written to the variable. If the variable is not found or if the
IEC 61131-1 Symbols Status is invalid, nothing is done and FALSE is returned.
The IEC 61131-1 Symbols Status is invalid if the Application TIC code download
and Application Symbols download are not sharing the same symbols CRC
checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name must be looked up in the IEC 61131-1 variable list each call,
the performance of the function may be slow for large numbers of variables. For
better performance, use the variable‟s network address and the setdbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
Example
This program writes the value 120,000 to the integer variable named
“Pressure1”.
#include <ctools.h>
int main(void)
{
BOOLEAN
status;
request_resource(IO_SYSTEM);
status = writeIntVariable("Pressure1", 120000);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
564
Function Specifications
writeRealVariable
Write to IEC 61131-1 Real Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the specified
floating-point value is written to the variable. If the variable is not found or if the
IEC 61131-1 Symbols Status is invalid, nothing is done and FALSE is returned.
The IEC 61131-1 Symbols Status is invalid if the Application TIC code download
and Application Symbols download are not sharing the same symbols CRC
checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the setdbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
Example
This program writes the value 25.607 to the real variable named “Flowrate”.
#include <ctools.h>
int main(void)
{
BOOLEAN
status;
request_resource(IO_SYSTEM);
status = writeRealVariable("Flowrate", 25.607);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
565
Function Specifications
writeMsgVariable
Write to IEC 61131-1 Message Variable (IEC 61131-1 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-1 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-1 Symbols Status is invalid, nothing is done and FALSE is returned. The
IEC 61131-1 Symbols Status is invalid if the Application TIC code download and
Application Symbols download are not sharing the same symbols CRC
checksum.
The pointer msg must point to a character string large enough to hold the
maximum length declared for the specified message variable plus two length
bytes and a null termination byte (i.e. max declared length + 3).
When writing to the message variable, all bytes are copied except the first byte
(max length byte) and the last byte (null termination byte). IEC 61131-1 message
variables have the following format:
Byte
Location
Description
0
Maximum length as declared in IEC 61131-1
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-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
Document (Version 1.61) 5/19/2011
566
Function Specifications
For better performance, use the variable‟s network address and the setdbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
Example
This program writes the message “Warning” to the message variable named
“TextData”. TextData has a maximum length of 10 bytes and a current length of 7
bytes.
#include <ctools.h>
int 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 1.61) 5/19/2011
567
Function Specifications
writeTimerVariable
Write to IEC 61131-1 Timer Variable (IEC 61131-1 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-1 Dictionary also treats variable names as
case insensitive). If the variable is found, TRUE is returned and the specified
unsigned long value is written to the variable. If the variable is not found or if the
IEC 61131-1 Symbols Status is invalid, nothing is done and FALSE is returned.
The IEC 61131-1 Symbols Status is invalid if the Application TIC code download
and Application Symbols download are not sharing the same symbols CRC
checksum.
Notes
This function requires the IEC 61131-1 Application Symbols to be downloaded to
the controller in addition to the Application TIC code. This function provides a
convenient method to access IEC 61131-1 variables by name; however, because
the variable name needs to be looked up in the IEC 61131-1 variable list each
call, the performance of the function may be slow for large numbers of variables.
For better performance, use the variable‟s network address and the setdbase
function.
The IO_SYSTEM system resource needs to be requested before calling this
function.
Example
This program writes the value 10000 ms to the timer variable named “Delay”.
#include <ctools.h>
int main(void)
{
BOOLEAN
status;
request_resource(IO_SYSTEM);
status = writeTimerVariable("Delay", 10000);
release_resource(IO_SYSTEM);
}
Document (Version 1.61) 5/19/2011
568
Function Specifications
xcopy
Copy a folder and all sub-folders
Syntax
#include <ctools.h>
STATUS xcopy(const char* source, const char* destination);
Description
The xcopy function copies all files in the specified source folder and sub-folders
to the location specified by destination.
If the xcopy operation failed then ERROR is returned. OK is returned if the xcopy
operation completed successfully.
The xcopy function used a significant amount of stack space. 2 extra stack
blocks are required for each layer of sub-directories that are to be copied.
Example
When copying myFolder at least 6 stack blocks will be needed due to the 3 levels
of folder structure.
\myFolder\ProjectA\Item1\
\myFolder\ProjectB\Item2\
\myFolder\ProjectC\Item1\
\myFolder\ProjectD\Item1\
See Also
copy, xdelete
Document (Version 1.61) 5/19/2011
569
Function Specifications
xdelete
Delete a folder and all sub-folder
Syntax
#include <ctools.h>
UINT16 xdelete(const char* source);
Description
The xdelete function deletes all files and folders in the specified source folder.
If the xdelete operation fails then ERROR is returned. OK is returned if the
xdelete operation completed successfully.
The xdelete function used a significant amount of stack space. 2 extra stack
blocks are required for each layer of sub-directories that are to be deleted.
Example
When deleting myFolder at least 6 stack blocks will be needed due to the 3 levels
of folder structure.
\myFolder\ProjectA\Item1\
\myFolder\ProjectB\Item2\
\myFolder\ProjectC\Item1\
\myFolder\ProjectD\Item1\
See Also
copy, xcopy
Document (Version 1.61) 5/19/2011
570
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.
Specifies 19200-baud port speed.
AD_THERMISTOR
ADDITIVE
AIN_END
AIN_START
AIO_BADCHAN
AIO_SUPPORTED
AIO_TIMEOUT
AO
AOUT_END
AOUT_START
applicationGroup
B
BASE_TYPE_MASK
BAUD110
BAUD115200
BAUD1200
BAUD150
BAUD19200
Document (Version 1.61) 5/19/2011
571
Macro Definitions
Macro
BAUD2400
BAUD300
BAUD38400
BAUD4800
BAUD57600
BAUD600
BAUD75
BAUD9600
BYTE_EOR
Definition
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.
System event: indicates activity on com3
receiver. The meaning depends on the
character handler installed.
Specifies number of 5000 counter input
channels
C
CLASS1_FLAG
CLASS2_FLAG
CLASS3_FLAG
CLOSED
COLD_BOOT
com1
COM1_RCVR
com2
COM2_RCVR
com3
COM3_RCVR
COUNTER_CHANNELS
Document (Version 1.61) 5/19/2011
572
Macro Definitions
Macro
COUNTER_END
COUNTER_START
COUNTER_SUPPORTED
CPU_CLOCK_RATE
CR
CRC_16
CRC_CCITT
Definition
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)
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
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.
DATA7
DATA8
DB
DB_BADSIZE
DB_BADTYPE
DB_OK
DCA_ADD
DCA_REMOVE
DCAT_C
DCAT_LOGIC1
DCAT_LOGIC2
DE_BadConfig
DE_BusyLine
DE_CallAborted
DE_CarrierLost
Document (Version 1.61) 5/19/2011
573
Macro Definitions
Macro
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
DYNAMIC_MEMORY
Definition
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
remote controller.
System resource: all memory allocation
functions such as malloc and alloc.
E
Macro
Definition
ENABLE
ER
EVEN
EX
Specifies flow control is enabled.
Variable name: error
Specifies even parity.
Variable name: automatic execution period
Document (Version 1.61) 5/19/2011
574
Macro Definitions
Macro
EXTENDED_DIN_END
EXTENDED_DIN_START
EXTENDED_DOUT_END
EXTENDED_DOUT_START
Definition
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
F
Macro
Definition
FOPEN_MAX
FORCE_MULTIPLE_COILS
FORCE_SINGLE_COIL
FULL
Redefinition of macro from stdio.h
Modbus function code
Modbus function code
Specifies full duplex.
Macro
Definition
GASFLOW
Gas Flow calculation firmware option
Macro
Definition
HALF
HT_4203
HT_5209
Specifies half duplex.
Specifies that 4203 hardware is persent
Specifies that 5209 hardware is persent
Macro
Definition
IO_SYSTEM
System resource for all I/O hardware
functions.
Macro
Definition
LAN_ENABLED
LAN_DISABLED
Enables LAN communication
Disables LAN communication, reducing
power consumption.
Specifies LED is to be turned off.
Specifies LED is to be turned on.
G
H
I
L
LED_OFF
LED_ON
Document (Version 1.61) 5/19/2011
575
Macro Definitions
Macro
LINEAR
LOAD_MULTIPLE_REGISTER
S
LOAD_SINGLE_REGISTER
LOW_POWER_MODE
Definition
Specifies linear database addressing.
Modbus function code
Macro
Definition
MAX_NUMBER_OF_FIELDS
The maximum number of fields in a data log
record.
The maximum number of data logs.
The maximum task priority.
Master message status: invalid database
address
Master message status: invalid function
code
Master message status: invalid message
length
Master message status: invalid slave station
address
Master message status: Modbus slave
returned an address exception.
Master message status: Modbus slave
returned a function exception.
Master message status: Modbus slave
returned a value exception.
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.
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.
Modbus function code
Reduces the operating speed of the
controller, reducing power consumption.
M
MAX_NUMBER_OF_LOGS
MAX_PRIORITY
MM_BAD_ADDRESS
MM_BAD_FUNCTION
MM_BAD_LENGTH
MM_BAD_SLAVE
MM_EXCEPTION_ADDRESS
MM_EXCEPTION_FUNCTION
MM_EXCEPTION_VALUE
MM_NO_MESSAGE
MM_PROTOCOL_NOT_SUPP
ORTED
MM_RECEIVED
MM_SENT
MODBUS
MODBUS_ASCII
MODBUS_PARSER
MODBUS_RTU
Document (Version 1.61) 5/19/2011
576
Macro Definitions
Macro
MODEM_CMD_MAX_LEN
MODEM_MSG
MSG_DATA
MSG_POINTER
MT_4203DRInputs
MT_4203DROutputs
MT_4203DSInputs
MT_4203DSOutputs
MT_5210Inputs
MT_5210Outputs
MT_5414Inputs
MT_5414Outputs
MT_5415Inputs
MT_5415Outputs
MT_5601Inputs
MT_5601Outputs
MT_5604Inputs
MT_5604Outputs
MT_5607Inputs
MT_5607Outputs
MT_5904Inputs
MT_5904Outputs
MT_Ain4
MT_Ain8
MT_Aout2
MT_Aout4
MT_Aout4_Checksum
MT_Counter4
MT_CounterSP2
MT_Din16
MT_Din32
MT_Din8
Document (Version 1.61) 5/19/2011
Definition
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.
4203 DR controller board inputs
4203 DR controller board outputs
4203 DS controller board inputs
4203 DS controller board outputs
SCADAPack 330 controller board inputs
SCADAPack 330 controller board outputs
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
5604 module analog and digital inputs
5604 module digital outputs
5607 module analog and digital inputs
5607 module analog and digital outputs
HART interface inputs
HART interface outputs
Four channel analog input module
Eight channel analog input module
Two channel analog output module
Four channel analog output module
Four channel analog output module with
checksum. This module type can only be
used with analog output modules with
checksum support.
Four channel counter input module
SCADAPack 350 controller board counter
inputs
Sixteen channel digital input module
Thirty two channel digital input module
Eight channel digital input module
577
Macro Definitions
Macro
MT_Dout16
MT_Dout32
MT_Dout8
MT_SP2Inputs
MT_SP2Outputs
Definition
Sixteen channel digital output module
Thirty two channel digital output module
Eight channel digital output module
SCADAPack 350 controller board inputs
SCADAPack 350 controller board outputs
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
Sets the controller to run a full operating
speed.
Specifies serial port type is not known.
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.
N
NONE
NORMAL
NORMAL_POWER_MODE
NOTYPE
NUMAB
NUMCOIL
NUMHOLDING
NUMINPUT
NUMLINEAR
NUMSTATUS
O
Macro
Definition
ODD
OPEN
Specifies odd parity.
Specifies switch is in open position
Macro
Definition
P
Document (Version 1.61) 5/19/2011
578
Macro Definitions
Macro
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
PM_CPU_FULL_CLOCK
PM_CPU_REDUCED_CLOCK
PM_CPU_SLEEP
PM_LAN_ENABLED
PM_LAN_DISABLED
PM_USB_PERIPHERAL_ENA
BLED
PM_USB_PERIPHERAL_DISA
BLED
PM_USB_HOST_ENABLED
PM_USB_HOST_DISABLED
PM_UNAVAILABLE
PM_NO_CHANGE
PROGRAM_EXECUTED
PROGRAM_NOT_LOADED
Definition
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
READ_HOLDING_REGISTER
READ_INPUT_REGISTER
READ_INPUT_STATUS
READSTATUS
REPORT_SLAVE_ID
RFC_MODBUS_RTU
Modbus function code
Modbus function code
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
Specifies serial port is an RS-232 port.
Specifies serial port is an RS-232 dial-up
Maximum length of the phone number string
The CPU is set to run at full speed
The CPU is set to run at a reduced speed
The CPU is set to sleep mode
The LAN is enabled
The LAN is disabled
The USB peripheral port is enabled
The USB peripheral port is disabled
The USB host port is enabled
The USB host port is disabled
The status of the device could not be read.
The current value will be used
Application program has been executed.
The requested application program is not
loaded.
R
RFC_NONE
RS232
RS232_MODEM
Document (Version 1.61) 5/19/2011
579
Macro Definitions
Macro
RS485_2WIRE
RS232_COLLISION_AVOIDAN
CE
RTOS_ENVELOPES
RTOS_EVENTS
RTOS_PRIORITIES
RTOS_RESOURCES
RTOS_TASKS
RUN
Definition
modem.
Specifies serial port is a 2 wire RS-485 port.
Specifies serial port is RS232 and uses CD
for collision avoidance.
Number of RTOS envelopes.
Number of RTOS events.
Number of RTOS task priorities.
Number of RTOS resource flags.
Number of RTOS tasks.
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
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
S
S_NORMAL
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
SF_VALID
SIGNAL_CTS
SIGNAL_CTS
SIGNAL_DCD
SIGNAL_DCD
SIGNAL_OFF
SIGNAL_OH
SIGNAL_OH
SIGNAL_ON
SIGNAL_RING
SIGNAL_RING
SIGNAL_VOICE
Document (Version 1.61) 5/19/2011
Number of entries in the store and forward
table
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
580
Macro Definitions
Macro
SIGNAL_VOICE
SLEEP_MODE_SUPPORTED
SMARTWIRE_5201_5202
STACK_SIZE
START_COIL
START_HOLDING
START_INPUT
START_STATUS
STARTUP_
APPLICATION
STARTUP_SYSTEM
STOP1
SYSTEM
Definition
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.
Specifies the system start up task.
Specifies 1 stop bit.
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
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
T_KELVIN
T_RANKINE
TELESAFE_6000_16EX
TELESAFE_MICRO_16
TFC_IGNORE_CTS
TFC_NONE
TIMER_BADINTERVAL
TIMER_BADTIMER
TIMER_MAX
TS_EXECUTING
TS_READY
TS_WAIT_
RESOURCE
Document (Version 1.61) 5/19/2011
581
Macro Definitions
Macro
TS_WAIT_ENVELOPE
TS_WAIT_EVENT
TS_WAIT_MESSAGE
Definition
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
V
Macro
Definition
VI_DATE_SIZE
Number of characters in version information
date field
Macro
Definition
WRITESTATUS
WS_NONE
WS_REAL_TIME_CLOCK
enum WriteStatus
Bit mask to disable all wake sources
Bit mask to enable real time clock as a
wake up source
Bit mask to enable interrupt input as wake
up source.
Bit mask to enable LED power switch as
wake up source
Bit mask to enable counter 1 overflow as a
wake up source
Bit mask to enable counter 2 overflow as a
wake up source
Bit mask to enable counter 3 overflow as a
wake up source
Bit mask to enable LED power switch as a
wake up source
Bit mask to enable DIN 1 change of state as
a wake up source
Bit mask to enable the SCADAPack Vision
on COM 3 as a wake up source
Bit mask to enable CDC signal on COM3 as
wake up source
Bit mask to enable digital input 0 as wake
up source
Bit mask to enable the SOLARPack 410
enable switch as wake up source
Bit mask to enable one second alarm as
W
WS_INTERUPT_INPUT
WS_LED_POWER_SWITCH
WS_COUNTER_1_OVERFLO
W
WS_COUNTER_2_OVERFLO
W
WS_COUNTER_3_OVERFLO
W
WS_LED_POWER_SWITCH
WS_DIN_1_CHANGE
WS_COM3_VISION
WS_COM3_DCD
WS_DIN0_CHANGE
WS_410_ENABLE_SWITCH
WS_ONE_SECOND_ALARM
Document (Version 1.61) 5/19/2011
582
Macro Definitions
Macro
WS_ALL
Document (Version 1.61) 5/19/2011
Definition
wake up source
Bit mask to enable all wake up sources
583
Structures and Types
Structures and Types
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.

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
CIF_Com2
CIF_Com3
Document (Version 1.61) 5/19/2011
= 1,
= 2,
= 3,
584
Structures and Types
CIF_Ethernet1
}
COM_INTERFACE;
= 100
COMM_ENDPOINT
The COMM_ENDPOINT structure defines a communication endpoint. If ethernet
based protocols are not used then the ipAddress, and portNumber fields should
be set to 0.
struct
{
COM_INTERFACE interface;
UINT32
stationAddress;
UINT32
ipAddress;
UINT16
portNumber;
UCHAR
protocol;
}
COMM_ENDPOINT;
CONNECTION_TYPE
The CONNECTION_TYPE enumerated type defines connection types supported
by the connection pool.
typedef enum ipConnection_t
{
CT_Unused = 0,
CT_Slave,
CT_MasterIEC 61131-1,
for an
// slave task connection
// master task connection created
IEC 61131-1
masterip FB
CT_MasterCApp,
for a
// master task connection created
C++
application
CT_MasterSF
for store
// master task connection created
and forward
}
CONNECTION_TYPE;
Only the connection type CT_MasterCApp may be used in C++ applications.
DATALOG_CONFIGURATION
The data log configuration structure holds the configuration of the data log. Each
record in a data log may hold up to eight fields. The typesOfFields[] entry in the
structure specifies the types of the fields. Not all the fields are used if fewer than
eight elements are declared in this array.
The amount of memory used for a record depends on the number of fields in the
record and the size of each field. Use the datalogRecordSize function to
determine the memory needed for each record.
Document (Version 1.61) 5/19/2011
585
Structures and Types
typedef struct datalogConfig_type
{
UINT16 records;
/* # of records */
UINT16 fields;
/* # of fields per record
*/
DATALOG_VARIABLE typesOfFields[MAX_NUMBER_OF_FIELDS];
}
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,
log */
DLS_BADCONFIG,
*/
}
DATALOG_STATUS;
/*
/*
/*
/*
data log created */
invalid log ID */
log already exists */
insufficient memory for
/* 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 bit unsigned integer
/* 16 bit signed integer
/* 32 bit unsigned integer
/* 32 bit signed integer
/* 32 bit floating point
/* 64 bit time */
/* 64 bit 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,
Document (Version 1.61) 5/19/2011
586
Structures and Types
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

DE_NoModem returns 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.

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
Document (Version 1.61) 5/19/2011
587
Structures and Types

DS_Calling returns the controller is making a connection to a remote
controller

DS_Connected returns the controller is connected to a remote controller

DS_Terminating returns the controller is ending a connection to a remote
controller.
dlogConfiguration Type
This structure defines the data log configuration. It is used with the dlogCreate
function.
typedef struct dlogConfiguration_type
{
UCHAR
configVersion;
BOOLEAN fileRingBuffer;
UINT32 bufferFlushInterval;
UINT32 bufferRecordSize;
UINT32 fileMode;
UINT32 numFiles;
UINT32 fileRecordSize;
UINT32 numRecordElements;
dlogRecordElement* recordList;
UINT32 securityToken;
UCHAR
description[255];
UCHAR logName[255];
} dlogConfiguration;

configVersion is the version of the configuration structure. Always set this to
1.

fileRingBuffer specifies if the oldest file is deleted when a new file would
exceed the maximum number of files. Set to TRUE to delete the oldest file.
Set to FALSE to stop writing to files and halt buffer flushing when the last file
is full.

bufferFlushInterval is the interval, in seconds, at which the data log server
will flush the buffer to file. Valid values are any value greater than 0.

bufferRecordSize is the number of records in the data log buffer.

fileMode selects where the data log files are stored. Valid values are
0=internal flash drive, 1=internal drive with auto copy to external drive,
2=internal drive with auto move to external drive, 3=external drive.

numFiles is the maximum number of log files. Valid values are any value
greater than 0.

fileRecordSize is the number of records in the each data log file. Valid values
are any value greater than 0.

numRecordElements is the number of elements in each record. Valid values
are any value greater than 0.
Document (Version 1.61) 5/19/2011
588
Structures and Types

recordList is a pointer to a list of record element definitions. See the
dlogRecordElement type for details.

securityToken is a security token that must be present on an inserted mass
storage device for these logs to be copied to that device. Set this to 0 to
disable the token.

description is a string describing the log. The description is included in the
header of the log files. The string has to be null-terminated.

logName is the name of the log. The log name is used to name the log files.
The string has to be null-terminated.
dlogCMITime Type
This structure represents the time stamps for data log records. Time is measured
as the number of days since January 1, 1997, and the number of centiseconds
since the start of the current day. The time in this format can be obtained using
the getClockTime function.
typedef struct
{
INT32 days;
INT32 centiseconds;
} dlogCMITime;

days is the number of days since January 1, 1997.

centiseconds is the number of hundredths of a second since the start of the
current day.
dlogMediaStatus Type
The dlogMediaStatus enumerated type indicates the status of the media used by
the configured data log. For non auto-transfer enabled data logs the states can
be either
typedef enum dlogMediaStatus_type {
DLOGS_MEDIA_PRESENT,
// media is present
DLOGS_MEDIA_NOT_PRESENT,// no external media present
DLOGS_MEDIA_EXT_FULL,
// external media is full
DLOGS_MEDIA_INT_FULL,
// internal media is full
DLOGS_MEDIA_ALL_FULL
// ext. and int. media full
} dlogMediaStatus;
dlogRecordElement Type
This structure defines a data log record. It provides on how an element in a
record can be packed into a log file.
typedef struct dlogRecordElement_type
{
UCHAR type;
UINT32 size;
UINT32 offset;
Document (Version 1.61) 5/19/2011
589
Structures and Types
} dlogRecordElement;

type is the type of field. Valid values are:
Type
Description
Size (bytes)
DLOG_UINT16
DLOG_INT16
DLOG_UINT32
DLOG_INT32
DLOG_FLOAT
16 bit unsigned integer
16 bit signed integer
32 bit unsigned integer
32 bit signed integer
single precision floating
point
time (see dlogCMITime
type)
double precision floating
point
16 byte fixed length string
32 byte fixed length string
64 byte fixed length string
128 byte fixed length string
192 byte fixed length string
255 byte fixed length string
custom types
2
2
4
4
4
DLOG_CMITIME
DLOG_DOUBLE
DLOG_STRING16
DLOG_STRING32
DLOG_STRING64
DLOG_STRING128
DLOG_STRING192
DLOG_STRING255
DLOG_FIRST_USER_TYPE
to
DLOG_LAST_USER_TYPE
8
8
16
32
64
128
192
255
type specific

size is the size, in bytes, of the element. The sizeof() function can be used to
determine this value.

offset is the offset, in bytes, of the first byte of the element from the start of
the record passed to the dlogWrite function.
Example
This is an example on how a record can be defined. It contains information on
how the structure can be packed into log files.
// User type definition: array of 10 UINT16 variables
typedef UINT16 userType[10];
// Structure used to copy one record into data log
typedef struct dataRecord
{
UINT16
value1;
INT32
value2;
double
value3;
float
value4;
Document (Version 1.61) 5/19/2011
590
Structures and Types
userType value5;
} dlogRecord;
// Variables for data log configuration
dlogConfiguration dLogConfig;
dlogRecordElement recordElement[5];
// define the
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
recordElement
data log records
[0].type = DLOG_UINT16;
[0].size = sizeof(UINT16);
[0].offset = offsetof(dlogRecord,
[1].type = DLOG_INT32;
[1].size = sizeof(INT32);
[1].offset = offsetof(dlogRecord,
[2].type = DLOG_DOUBLE;
[2].size = sizeof(double);
[2].offset = offsetof(dlogRecord,
[3].type = DLOG_FLOAT;
[3].size = sizeof(float);
[3].offset = offsetof(dlogRecord,
[4].type = DLOG_FIRST_USER_TYPE;
[4].size = sizeof(userType);
[4].offset = offsetof(dlogRecord,
value1);
value2);
value3);
value4);
value5);
// insert the record list into the data log configuration
dLogConfig.recordList = recordElement;
dlogStatus Type
The dlogStatus enumerated type indicates the status of a data log operation. The
specific meaning may vary according to the function returning the status.
typedef enum dlogStatus_type {
DLOGS_SUCCESS,
// operation was successful
DLOGS_FAILURE,
// operation failed
DLOGS_INPROGRESS, // operation in progress
DLOGS_EXISTS,
// data log exists
DLOGS_DIFFERENT, // data log configuration differs
DLOGS_INVALID,
// data log configuration invalid
DLOGS_NOMEMORY,
// failed due to lack of memory
DLOGS_BADID,
// data log ID is not valid
DLOGS_WRONGPARAM, // wrong parameter (except dlogID)
DLOGS_BUFFERFULL, // data log buffer is full
DLOGS_COMPLETE
// operation is complete
} dlogStatus;
dlogTransferStatus Type
The dlogTransferStatus enumerated type indicates the status of the current or
recent auto-transfer operation. The transfer status only makes sense for data
logs configured to perform autocopy or automove transfers when an external
USB media is inserted. The transfer status for data logs without auto-transfer
capabilities is defaulted to DLOGS_TRANSFER_DONE_ALL.
typedef enum dlogTransferStatus_type {
Document (Version 1.61) 5/19/2011
591
Structures and Types
DLOGS_TRANSFER_INPROGRESS,
// Auto transfer is not done or in progress
DLOGS_TRANSFER_DONE_ALL,
// Auto transfer is done with files transferred
DLOGS_TRANSFER_DONE_NO_WORK,
// Auto transfer is done with no files transferred
DLOGS_TRANSFER_DONE_INVALID_TOKEN
// Auto transfer is done because of invalid token
DLOGS_TRANSFER_NOT_USED
// Auto transfer not configured or not started
} dlogTransferStatus;
DNP_ADDRESS_MAP_TABLE
The dnpAddressMapTable type describes an entry in the DNP Address Mapping
Table.
typedef struct dnpAddressMapTable_type
{
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.
Document (Version 1.61) 5/19/2011
592
Structures and Types
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.

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;
Document (Version 1.61) 5/19/2011
593
Structures and Types
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;
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.
Document (Version 1.61) 5/19/2011
594
Structures and Types

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.

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;
Document (Version 1.61) 5/19/2011
595
Structures and Types
UINT16 AI16_startAddress;
CHAR
AI16_reportingMethod;
UINT16 AI16_bufferSize;
UINT16 AI32_number;
UINT16 AI32_startAddress;
CHAR
AI32_reportingMethod;
UINT16 AI32_bufferSize;
CHAR
AI32_wordOrder;
UINT16 AISF_number;
UINT16 AISF_startAddress;
CHAR
AISF_reportingMethod;
UINT16 AISF_bufferSize;
CHAR
AISF_wordOrder;
UINT16 AO16_number;
UINT16 AO16_startAddress;
UINT16 AO32_number;
UINT16 AO32_startAddress;
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 must come from this station.
Valid values are 0 to 65534.

rtuAddress is the address of the RTU. The master station must 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.
Document (Version 1.61) 5/19/2011
596
Structures and Types

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 must 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.

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.
Document (Version 1.61) 5/19/2011
597
Structures and Types

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)

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.
Document (Version 1.61) 5/19/2011
598
Structures and Types

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.

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;
Document (Version 1.61) 5/19/2011
599
Structures and Types
UINT16
INT16
UINT16
UINT16
UCHAR
UINT16
UINT16
UINT16
UINT16
UINT16
UCHAR
UINT16
UINT16
UINT16
UCHAR
UINT16
UCHAR
UINT16
UINT16
UCHAR
UINT16
UINT16
UINT16
UCHAR
UINT16
UCHAR
UINT16
UINT16
UCHAR
UINT16
UCHAR
UINT16
UINT16
UINT16
UINT16
UCHAR
UINT16
UINT16
UCHAR
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
UINT16
Document (Version 1.61) 5/19/2011
applicationTimeout;
timeSynchronization;
BI_number;
BI_startAddress;
BI_reportingMethod;
BI_soeBufferSize;
BO_number;
BO_startAddress;
CI16_number;
CI16_startAddress;
CI16_reportingMethod;
CI16_bufferSize;
CI32_number;
CI32_startAddress;
CI32_reportingMethod;
CI32_bufferSize;
CI32_wordOrder;
AI16_number;
AI16_startAddress;
AI16_reportingMethod;
AI16_bufferSize;
AI32_number;
AI32_startAddress;
AI32_reportingMethod;
AI32_bufferSize;
AI32_wordOrder;
AISF_number;
AISF_startAddress;
AISF_reportingMethod;
AISF_bufferSize;
AISF_wordOrder;
AO16_number;
AO16_startAddress;
AO32_number;
AO32_startAddress;
AO32_wordOrder;
AOSF_number;
AOSF_startAddress;
AOSF_wordOrder;
autoUnsolicitedClass1;
holdTimeClass1;
holdCountClass1;
autoUnsolicitedClass2;
holdTimeClass2;
holdCountClass2;
autoUnsolicitedClass3;
holdTimeClass3;
holdCountClass3;
enableUnsolicitedOnStartup;
sendUnsolicitedOnStartup;
level2Compliance;
masterAddressCount;
masterAddress[8];
maxEventsInResponse;
dialAttempts;
dialTimeout;
600
Structures and Types
UINT16 pauseTime;
UINT16 onlineInactivity;
UINT16 dialType;
Char
modemInitString[64];
} dnpConfigurationEx;

rtuAddress is the address of the RTU. The master station must 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 must 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.
Document (Version 1.61) 5/19/2011
601
Structures and Types

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.

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.
Document (Version 1.61) 5/19/2011
602
Structures and Types

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.

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.
Document (Version 1.61) 5/19/2011
603
Structures and Types

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).

MasterAddressCount is the number of master stations.

masterAddress[8] is the number of master station addresses.

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[64] 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.
Document (Version 1.61) 5/19/2011
604
Structures and Types
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;
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;
Document (Version 1.61) 5/19/2011
605
Structures and Types

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.

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,
AI16_POINT,
AI32_POINT,
AISF_POINT,
AILF_POINT,
CI16_POINT,
CI32_POINT,
BO_POINT,
AO16_POINT,
AO32_POINT,
AOSF_POINT,
AOLF_POINT
} DNP_POINT_TYPE;
Document (Version 1.61) 5/19/2011
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
/*
binary input */
16 bit analog input */
32 bit analog input */
short float analog input */
long float analog input */
16 bit counter output */
32 bit counter output */
binary output */
16 bit analog output */
32 bit analog output */
short float analog output */
long float analog output */
606
Structures and Types
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;
};

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;
//
UINT16 comPort;
//
UINT16 retries;
//
UINT16 timeout;
//
IP_ADDRESS ipAddress;
//
} dnpRoutingTableEx;
station address
com port interface
number of retries
timeout in milliseconds
IP address

address is the DNP station address of the destination station.

comPort specifies the communications port interface. Allowed values are :
1 = serial port com1
2 = serial port com2
3 = serial port com3
Document (Version 1.61) 5/19/2011
607
Structures and Types
103 = DNP over TCP, using LAN port
104 = DNP over UDP, using LAN port

retries is the number of times the data link layer will retry the message in the
event of a failure.

timeout is the timeout in milliseconds.
ipAddress is the IP address of the destination station.
DNP_RUNTIME_STATUS
The dnpRuntimeStatus type describes a structure for holding status information
about DNP event log buffers.
/* DNP Runtime Status */
typedef struct dnp_runtime_status
{
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.
Document (Version 1.61) 5/19/2011
608
Structures and Types
typedef struct envelope_type {
UINT32 source;
UINT32 destination;
UINT32 type;
UINT32 data;
}
envelope;
// sender task ID
// destination task ID
/ type of message
// the message data

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.

destination is the task ID of the task to receive the message. It must 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
{
Document (Version 1.61) 5/19/2011
609
Structures and Types
UCHAR manufacturerID;
UCHAR manufacturerDeviceType;
UCHAR preamblesRequested;
UCHAR commandRevision;
UCHAR transmitterRevision;
UCHAR softwareRevision;
UCHAR hardwareRevision;
UCHAR flags;
UINT32 deviceID;
}
HART_DEVICE;
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.
Document (Version 1.61) 5/19/2011
610
Structures and Types

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
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;
Document (Version 1.61) 5/19/2011
611
Structures and Types
UINT16 numberOfAttempts;
UINT16 ledPower;
}IO_CONFIG;

slaveAddress returns the I C address, 0 = slave mode disabled

dataRate returns the I/O bus data rate 0 = 100 kHz ;1 = 150 kHz; 2 = 200
kHz; 3 = 250 kHz; 4 = 300 kHz; 5 = 350 kHz; 6 = 400 kHz (default); 7 = 450
kHz;

numberOfAttempts returns the number of attempts, 1 to 4 (default = 1)

ledPower returns the led power state, 0 = off, 1 = on (default)
2
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;
UINT32 masterConnections;
UINT32 unusedConnections;
}
Document (Version 1.61) 5/19/2011
612
Structures and Types
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. The PPP
options are not supported on SCADAPack 350 or 4203 controllers.
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;
UINT32
serverIdleTimeout;
BOOLEAN
serverEnabled;
Document (Version 1.61) 5/19/2011
613
Structures and Types
}
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 350.
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 1.61) 5/19/2011
614
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-bit value in this array is
supported and contains IP address in form of 32-bit unsigned integer. For
example IP address 172.016.017.018 will be represented with following 32bit unsigned number:
172 + 16x256 + 17x256x256 + 18x256x256x256 = 303108268

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, and com3.

function specifies the Modbus function code. Refer to the communication
protocol manual for supported function codes.
Document (Version 1.61) 5/19/2011
615
Structures and Types

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.

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
= 0,
=
=
=
=
=
=
= 7,
// additional master command status codes
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
= 24,
MM_EXCEPTION_ADDRESS
= 25,
MM_EXCEPTION_VALUE
=
Document (Version 1.61) 5/19/2011
1,
2,
3,
4,
5,
6,
used for Modbus/TCP
= 8,
= 9,
10,
=
=
=
=
=
11,
12,
13,
14,
15,
16,
17,
18,
= 19,
= 20,
= 21,
22,
23,
26,
616
Structures and Types
MM_QUEUE_FULL
MM_STATIONS_ARE_EQUAL
= 28,
MM_EXCEPTION_DEVICE_FAILURE= 29,
MM_ EXCEPTION_DEVICE_BUSY = 30
= 27,
}
MODBUS_CMD_STATUS;

MM_SENT returns a valid command has been sent

MM_RECEIVED returns response was received.

MM_NO_MESSAGE returns no message was sent.

MM_BAD_FUNCTION returns invalid function code used

MM_BAD_SLAVE returns invalid slave station address used

MM_BAD_ADDRESS returns invalid database address used

MM_BAD_LENGTH returns invalid message length

MM_PROTOCOL_NOT_SUPPORTED returns selected protocol is not
supported.

MM_CONNECTING returns connecting to slave IP address.

MM_CONNECTED returns connected to slave IP address.

MM_CONNECT_TIMEOUT returns timeout while connecting to slave IP
address.

MM_SEND_ERROR returns TCP/IP error has occurred while sending
message.

MM_RSP_TIMEOUT returns timeout has occurred waiting for response.

MM_RSP_ERROR returns slave has closed connection; incorrect response;
or, incorrect response length.

MM_DISCONNECTING returns disconnecting from slave IP address is in
progress.

MM_DISCONNECTED returns connection to slave IP address is
disconnected.

MM_BAD_CONNECT_ID returns invalid connection ID.

MM_BAD_PROTOCOL_TYPE returns invalid protocol type.

MM_BAD_IP_ADDRESS 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-1 masterIP function block. It is not available
from the mTcpMasterStatus function.

MM_CONNECT_ERROR returns error while connecting to slave IP address.
Document (Version 1.61) 5/19/2011
617
Structures and Types

MM_NO_MORE_CONNECTIONS returns no more connections are
available.

MM_BAD_CONNECTION_TYPE returns invalid connection type used in
mTcpMasterMessage.

MM_EXCEPTION_FUNCTION
Returns master message status:
Modbus slave returned a function exception

MM_EXCEPTION_ADDRESS
Returns master message status:
Modbus slave returned an address exception

MM_EXCEPTION_VALUE Returns master message status: Modbus slave
returned a value exception

MM_QUEUE_FULL Returns master message status: Serial transmit queue is
full

MM_STATIONS_ARE_EQUAL Returns master message status: Master and
slave stations are equal. They must be different.
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];
};
Document (Version 1.61) 5/19/2011
618
Structures and Types

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.

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.
Document (Version 1.61) 5/19/2011
619
Structures and Types
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
{
UINT16
station;
UCHAR
addrMode;
BOOLEAN
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.
Document (Version 1.61) 5/19/2011
620
Structures and Types

enronStation is the station address for the Enron Modbus protocol. It is used
if enronEnabled is set to TRUE. Valid values are 1 to 255 for standard
addressing, and 1 to 65534 for extended addressing.
pconfig
The pconfig structure contains serial port settings.
struct pconfig {
UINT16 baud;
UINT16 duplex;
UINT16 parity;
UINT16 data_bits;
UINT16 stop_bits;
UINT16 flow_rx;
UINT16 flow_tx;
UINT16 type;
UINT16 timeout;
};

baud is the communication speed. It is one of the BAUD 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. The only supported selection
is the STOP1 macro.

flow_rx specifies flow control on the receiver. It is either the
RFC_MODBUS_RTU (=ENABLE), or RFC_NONE (=DISABLE). If the
Modbus RTU protocol is used, set flow_rx to RFC_MODBUS_RTU. For the
Modbus ASCII protocol or any other protocol, set flow_rx to RFC_NONE.

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, RS232_MODEM, or
RS485_2WIRE 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
{
Document (Version 1.61) 5/19/2011
621
Structures and Types
/* input values */
float pv;
float sp;
float gain;
float reset;
float rate;
float deadband;
float fullScale;
float zeroScale;
float manualOutput;
UINT32 period;
BOOLEAN autoMode;
/* calculation results */
float output;
BOOLEAN outOfDeadband;
/* historic data values */
float pvN1;
float pvN2;
float 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 1.61) 5/19/2011
622
Structures and Types
PROTOCOL_SETTINGS
The Extended Protocol Settings structure defines settings for a communication
protocol. This structure differs from the standard settings in that it allows
additional settings to be specified.
typedef struct protocolSettings_t
{
UCHAR type;
UINT16 station;
UCHAR priority;
UINT16 SFMessaging;
ADDRESS_MODE mode;
}
PROTOCOL_SETTINGS;

type is the protocol type. It may be one of NO_PROTOCOL, MODBUS_RTU,
or MODBUS_ASCII, AB_FULL_BCC, AB_FULL_CRC, AB_HALF_BCC,
DNP or AB_HALF_CRC macros. To set the remaining settings use the
function mTcpSetInterfaceEx.

station is the station address of the controller. Each serial port may have a
different address. The valid values are determined by the communication
protocol. This field is not used if the protocol type is NO_PROTOCOL.

priority is the task priority of the protocol task. This field is not used if the
protocol type is NO_PROTOCOL.

SFMessaging is the enable Store and Forward messaging control flag.

ADDRESS_MODE is the addressing mode, standard or extended.
PROTOCOL_SETTINGS_EX Type
This structure contains serial port protocol settings including Enron Modbus
support.
typedef struct 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 macros. To set the remaining settings use the
function mTcpSetInterfaceEx.
Document (Version 1.61) 5/19/2011
623
Structures and Types

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;
};

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 macros. To set the remaining settings use the function
mTcpSetInterfaceEx.

station is the station address of the controller. Each serial port may have a
different address. The valid values are determined by the communication
protocol. This field is not used if the protocol type is NO_PROTOCOL.

priority is the task priority of the protocol task. This field is not used if the
protocol type is NO_PROTOCOL.

SFMessaging is the enable Store and Forward messaging control flag.
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;
Document (Version 1.61) 5/19/2011
624
Structures and Types
UINT16
INT16
UINT16
UINT16
};
command;
task_id;
stored_messages;
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.
PORT_CHARACTERISTICS
The PORT_CHARACTERISTICS type is a structure that contains serial port
characteristics.
typedef struct portCharacteristics_tag {
UINT16 dataflow;
UINT16 buffering;
UINT16 protocol;
UINT32 options;
} PORT_CHARACTERISTICS;

dataflow is a bit mapped field describing the data flow options supported on
the serial port. ANDing can isolate the options with the
PC_FLOW_RX_RECEIVE_STOP, PC_FLOW_RX_XON_XOFF,
PC_FLOW_TX_IGNORE_CTS or PC_FLOW_TX_XON_XOFF macros.

buffering describes the buffering options supported. No buffering options are
currently supported.

protocol describes the protocol options supported. The macro,
PC_PROTOCOL_RTU_FRAMING is the only option supported.

options describes additional options supported. No additional options are
currently supported.
Document (Version 1.61) 5/19/2011
625
Structures and Types
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.

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
Document (Version 1.61) 5/19/2011
626
Structures and Types
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.
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;
//
type
UINT16
forwardStation;
station address
IP_ADDRESS
forwardIPAddress;
//
}
SF_TRANSLATION;

slave interface type
slave station address
forwarding interface
/ forwarding
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.
Document (Version 1.61) 5/19/2011
627
Structures and Types

slaveStation is the station address used in the slave command message.
Valid address range is: 0 to 255 in standard Modbus, 0 to 65534 in extended
Modbus. 65535 = entry cleared. This station address must be different from
the station address assigned to the 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 must 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;
//
type
UINT16
forwardStation;
station address
IP_ADDRESS
forwardIPAddress;
//
UINT16
timeout;
time-out
}
SF_TRANSLATION_EX;
slave interface type
slave station address
forwarding interface
// forwarding
forwarding IP address
//

slaveInterface is the communication interface which receives the slave
command message. Valid interface types are: 1 = com1, 2 = com2, 3 =
com3, 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 must 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, 100 = Modbus/TCP network, 101 = Modbus RTU over UDP
network, 102 = Modbus ASCII over UDP network.
Document (Version 1.61) 5/19/2011
628
Structures and Types

forwardStation is the station address of the remote slave device to forward
the command message to. Valid address range is: 0 to 255 in standard
Modbus, 0 to 65534 in extended Modbus. 65535 = entry cleared. This station
address must be different from the station address assigned to the
forwardInterface.

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.
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 of the task. This may be one of
TS_READY, TS_EXECUTING, TS_WAIT_ENVELOPE, TS_WAIT_EVENT,
TS_WAIT_MESSAGE, or TS_WAIT_RESOURCE macros.

requirement is used if the task is waiting for an event or resource. If the
status field is TS_WAIT_EVENT, then requirement indicates on which event
Document (Version 1.61) 5/19/2011
629
Structures and Types
it is waiting. If the status field is TS_WAIT_RESOURCE then requirement
indicates on which resource it is waiting.

error is the task error code. This is the same value as returned by the
check_error function.

type is the task type. It will be either SYSTEM or applicationGroup.
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 in the range 97 (for the year 1997) to 96 (for the
year 2096).

month is the current month. It is in the range 1 to 12.

day is the current day. It is in the range 1 to 31.

dayofweek is the current day of the week. It is in the range 1 to 7. The
application program defines the meaning of this field.

hour is the current hour. It is in the range 00 to 23.

minute is the current minute. It is in the range 00 to 59.

second is the current second. It is in the range 00 to 59.

hundredth is the current hundredth of a second. It is in the range 00 to 99.
Document (Version 1.61) 5/19/2011
630
Structures and Types
timer_info
The timer_info structure contains information about a timer.
struct timer_info {
UINT16 time;
UINT16 interval;
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 build;
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
Document (Version 1.61) 5/19/2011
631
Structures and Types
};
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 1.61) 5/19/2011
632
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 myshutdown function aborts any active
modem connections when the task is ended.
-------------------------------------------- */
void myshutdown(void)
{
modemAbort(com1);
}
int main(void)
{
struct ModemSetup dialSettings;
reserve_id portID;
enum DialError status;
enum DialState state;
struct pconfig portSettings;
TASKINFO taskStatus;
/* Configure serial port 1 */
portSettings.baud
= BAUD19200;
portSettings.duplex
= FULL;
portSettings.parity
= NONE;
portSettings.data_bits = DATA8;
portSettings.stop_bits = STOP1;
portSettings.flow_rx
= RFC_MODBUS_RTU;
portSettings.flow_tx
= TFC_NONE;
portSettings.type
= RS232_MODEM;
portSettings.timeout
= 600;
request_resource(IO_SYSTEM);
set_port(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 1.61) 5/19/2011
633
Example Programs
/* set up exit handler for this task */
getTaskInfo(0, &taskStatus);
installExitHandler(taskStatus.taskID, (FUNCPTR)
myshutdown);
/* 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.
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); }
}
Document (Version 1.61) 5/19/2011
634
Example Programs
void task2(void)
{
while(TRUE)
{ /* body of task 2 loop - event handler */
wait_event(TIME_TO_PRINT); fprintf(com1,"It's time for a coffee
break\r\n"); }
}
/* -------------------------------------------The myShutdown function stops the signalling
of TIME_TO_PRINT events when application is
stopped.
-------------------------------------------- */
void myShutdown(void)
{ endTimedEvent(TIME_TO_PRINT); }
int main(void)
{
TASKINFO taskStatus;
/* continuos processing task at priority 100 */
create_task(task1, 100, applicationGroup, 2);
/* event handler needs larger stack for printf function */
create_task(task2, 75, applicationGroup, 4);
/* set up task exit handler to stop
signalling of events when this task ends */
getTaskInfo(0, &taskStatus);
installExitHandler(taskStatus.taskID, (FUNCPTR) myShutdown);
/* start timed event to occur every 10 sec */
startTimedEvent(TIME_TO_PRINT, 100);
while(TRUE)
{ /* body of main task loop */ /* other processing code */ }
}
Document (Version 1.61) 5/19/2011
635
Example Programs
DataLog Example
******************************************************************
D I S C L A I M E R
This program is an example to demonstrate one or more programming
functions or
methods. This is not an application specific program and it is
presented as a
programming example only. Control Microsystems assumes no
liability for the
use or application of this example program or any portion
thereof.
SCADAPack 350 C++ Application Main
Program
Copyright (c) 2009, Control Microsystems Inc.
==================================================================
DESCRIPTION: The following program demonstrates how to configure
data log for
data logging into the external FLUSH memory. This
program is
doing the following:
- adding register assignment for SCADAPack 350;
- configure data for logging three values per record (date/time,
- AIN1 raw value and AIN1 scaled value 0 to 100) and then
creates the log;
- use DIN1 to suspend (DIN1 OFF) or resume (DIN1 ON) data loging
- toggling FORCE LED every second as indication that data
logging is active;
- loging data every 5 seconds;
-----------------------------------------------------------------HISTORY:
..................................................................
Date: 01/APR/09
Name: Goran Babic
Descr.: File/Example created.
*****************************************************************/
#include "ctools.h"
#include "nvMemory.h"
/* -------------------------------------------------------C++ Function Prototypes
-------------------------------------------------------- */
/* -------------------------------------------------------------C Function Prototypes
------------------------------------------------------------ */
extern "C"
{
Document (Version 1.61) 5/19/2011
636
Example Programs
// add prototypes here
}
typedef struct
dataRecord { dlogCMITime value1;
INT16
value2;
float
value3;
} dlogRecord;
/*****************************************************************
main
This routine is the main application loop.
*****************************************************************/
int main(void)
{
char
*statusString[] = { "SUCCESS",
"FAILURE",
"INPROGRESS",
"EXISTS",
"DIFFERENT",
"INVALID",
"NOMEMORY",
"BADID",
"WRONGPARAM",
"BUFFERFULL",
"NOTSTARTED",
"COMPLETE"
},
strLogDescription[] =
"Data Log to File Example",
strLogName[]
"AIN1 data log";
INT16
UINT32
dlogStatus
dlogRecordElement
TIME
BOOLEAN
Document (Version 1.61) 5/19/2011
=
rtcPreviousSecond = 0,
din1CurrentState = 0,
din1PreviousState = 0;
dlogIdNumber;
dlogStatusInfo;
recordFieldsDefinitions[3];
currentTime;
logData = TRUE;
637
Example Programs
dlogRecord
dlogConfiguration
flashMemoryRecord;
usbMemLogConfig;
/*===============================================*/
/* Add RTC and SP350 I/Os in register assignment */
/*===============================================*/
request_resource(IO_SYSTEM);
clearRegAssignment();
addRegAssignment(SCADAPack_2IO, 0, 1, 10001, 30001, 40001);
release_resource(IO_SYSTEM);
/*==========================*/
/* Delete all existing logs */
/*==========================*/
dlogStatusInfo = dlogDeleteAll();
//======================================================
// Data log configuration
//======================================================
// Config struct version # should be always set to 1
usbMemLogConfig.configVersion
= 1;
//
The oldest log file will be deleted when a new file
would exceed defined
// maximum number of files
when this parameter is set
to TRUE
usbMemLogConfig.fileRingBuffer
= TRUE;
// Interval in seconds after which server will flush buffer
to file
usbMemLogConfig.bufferFlushInterval = 10;
// Buffer size is number of records in the data log buffer
usbMemLogConfig.bufferRecordSize = 1000;
// External drive selected when set to 3.
usbMemLogConfig.fileMode
= 3;
// Maximum number of log files
usbMemLogConfig.numFiles
= 50;
// File size in number of records
usbMemLogConfig.fileRecordSize
= 1000;
// Number of elements/fields in each record
usbMemLogConfig.numRecordElements = 3;
// 1st field - Date and Time
recordFieldsDefinitions[0].type
= DLOG_CMITIME;
recordFieldsDefinitions[0].size
=
sizeof(dlogCMITime);
recordFieldsDefinitions[0].offset = offsetof(dlogRecord,
value1);
// 2nd field - 16-bit AIN raw value
recordFieldsDefinitions[1].type
= DLOG_INT16;
Document (Version 1.61) 5/19/2011
638
Example Programs
recordFieldsDefinitions[1].size
= sizeof(INT16);
recordFieldsDefinitions[1].offset = offsetof(dlogRecord,
value2);
// 3rd field - 32-bit floating point scaled value
recordFieldsDefinitions[2].type
= DLOG_FLOAT;
recordFieldsDefinitions[2].size
= sizeof(float);
recordFieldsDefinitions[2].offset = offsetof(dlogRecord,
value3);
// Pointer to array of record element definitions
usbMemLogConfig.recordList
=
recordFieldsDefinitions;
// Security token disabled when set to 0.
usbMemLogConfig.securityToken
= 0;
// Text description of log. Maximum 255 characters
memcpy( usbMemLogConfig.description,
strLogDescription,
strlen(strLogDescription)+1);
// The log name. Maximum 255 characters
memcpy( usbMemLogConfig.logName,
strLogName,
strlen(strLogName)+1);
//=======================================================
// Create the log
//=======================================================
dlogStatusInfo = dlogCreate(&usbMemLogConfig,
&dlogIdNumber);
while (TRUE)
{
//===================
// Read RTC and I/Os
//===================
request_resource(IO_SYSTEM);
databaseRead( MODBUS, 10001, &din1CurrentState);
getclock(&currentTime);
release_resource(IO_SYSTEM);
//=========================================================
// Turn on FORCE LED flashing and data logging if
DIN1 is turned ON
//=========================================================
if ( din1CurrentState )
{
if ((currentTime.second != rtcPreviousSecond))
{
rtcPreviousSecond = currentTime.second;
forceLed(!getForceLed());
}
// Log data every 5 seconds
if ( !(currentTime.second%5) )
{
Document (Version 1.61) 5/19/2011
639
Example Programs
if ( logData )
{
request_resource(IO_SYSTEM);
// Get RTC time stamp date/time
getClockTime(
&flashMemoryRecord.value1.days,
&flashMemoryRecord.value1.centiseconds);
// Read AIN1 raw value
databaseRead( MODBUS, 30001,
&flashMemoryRecord.value2);
release_resource(IO_SYSTEM);
// Scale AIN1 0-100%
flashMemoryRecord.value3 =
((float)flashMemoryRecord.value2 / 16384.0) * 100.0;
// Write date to log file
dlogStatusInfo = dlogWrite(
dlogIdNumber, (UCHAR *)(&flashMemoryRecord));
if ( dlogStatusInfo ==
DLOGS_BUFFERFULL )
{
dlogStatusInfo =
dlogFlush( dlogIdNumber );
dlogStatusInfo =
dlogWrite( dlogIdNumber, (UCHAR *)(&flashMemoryRecord));
}
logData = FALSE;
}
}
else
{
logData = TRUE;
}
}
else
{
// Turn off FORCE LED if DIN1 is OFF
forceLed(LED_OFF);
}
//===============================================
// Suspend (DIN1=OFF) or resume (DIN1=ON) loging
//===============================================
if ( din1CurrentState != din1PreviousState )
{
if ( din1CurrentState )
{
dlogStatusInfo = dlogResume(
dlogIdNumber );
}
else
{
dlogStatusInfo = dlogSuspend(
dlogIdNumber );
}
}
din1PreviousState = din1CurrentState;
Document (Version 1.61) 5/19/2011
640
Example Programs
}
}
DNP Configuration Example
/* --------------------------------------------------------------SCADAPack 350 C++ Application Main Program
Copyright 2001 - 2004, Control Microsystems Inc.
The following program demonstrates how to configure DNP for
operation
on com3 of the SCADAPack 350.
------------------------------------------------------------ */
#include <ctools.h>
/* -------------------------------------------------------------C++ Function Prototypes
------------------------------------------------------------ */
// add prototypes here
/* -----------------------------------------------------------C Function Prototypes
---------------------------------------------------------- */
extern "C"
{
// add prototypes here
}
UINT32 mainPriority = 100;
UINT32 mainStack = 4;
UINT32 applicationGroup = 0;
/* ---------------------------------------------------------main
This routine is the main application loop.
--------------------------------------------------------- */
int 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
dnpAnalogOutput
analogOutput;
// analog
output settings
dnpCounterInput
counterInput;
// conter
input settings
Document (Version 1.61) 5/19/2011
641
Example Programs
//-----------------------------------------------------------// Stop any protocol currently active on com port 3
//------------------------------------------------------------get_protocol(com3, &protocolSettings);
protocolSettings.type = NO_PROTOCOL;
set_protocol(com3, &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
=
configuration.BI_reportingMethod =
configuration.BI_soeBufferSize
=
configuration.BO_number
configuration.BO_startAddress
=
configuration.CI16_number
configuration.CI16_startAddress =
configuration.CI16_reportingMethod
REPORT_ALL_EVENTS;
configuration.CI16_bufferSize
=
configuration.CI32_number
configuration.CI32_startAddress =
configuration.CI32_reportingMethod
REPORT_ALL_EVENTS;
configuration.CI32_bufferSize
=
configuration.CI32_wordOrder
configuration.AI16_number
configuration.AI16_startAddress =
configuration.AI16_reportingMethod
REPORT_ALL_EVENTS;
configuration.AI16_bufferSize
=
configuration.AI32_number
configuration.AI32_startAddress =
configuration.AI32_reportingMethod
REPORT_ALL_EVENTS;
configuration.AI32_bufferSize
=
configuration.AI32_wordOrder
configuration.AISF_number
configuration.AISF_startAddress =
configuration.AISF_reportingMethod
REPORT_CHANGE_EVENTS;
configuration.AISF_bufferSize
=
configuration.AISF_wordOrder
Document (Version 1.61) 5/19/2011
0;
REPORT_ALL_EVENTS;
1000;
= 1051;
0;
= 50;
0;
=
0;
= 0;
100;
=
0;
= MSW_FIRST;
= 751;
0;
=
1000;
= 0;
100;
=
0;
= MSW_FIRST;
= 0;
200;
=
0;
= MSW_FIRST;
642
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 3
//-------------------------------------------------------get_protocol(com3, &protocolSettings);
protocolSettings.type = DNP;
set_protocol(com3, &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;
dnpSaveBIConfig(configuration.BI_startAddress +
index, &binaryInput);
}
//-------------------------------------------------------// Configure 16 Bit Analog Input Points
//--------------------------------------------------------for (index = 0; index < configuration.AI16_number; index++)
{
Document (Version 1.61) 5/19/2011
643
Example Programs
index,
index,
index,
index,
index,
index,
analogInput.modbusAddress = 30001 + index;
analogInput.eventClass = CLASS_2;
analogInput.deadband = 1;
dnpSaveAI16Config(configuration.AI16_startAddress +
&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 +
&analogInput);
}
//-------------------------------------------------------// Configure 16 Bit Analog Output Points
//--------------------------------------------------------for (index = 0; index < configuration.AO16_number; index++)
{
analogOutput.modbusAddress = 40001 + index;
dnpSaveAO16Config(configuration.AO16_startAddress +
&analogOutput);
}
//----------------------------------------------------// Configure 32 Bit Analog Output Points
//----------------------------------------------------for (index = 0; index < configuration.AO32_number; index++)
{
analogOutput.modbusAddress = 41001 + index * 2;
dnpSaveAO32Config(configuration.AO32_startAddress +
&analogOutput);
}
//-------------------------------------------------------// Configure 16 Bit Counter Input Points
//-------------------------------------------------------for (index = 0; index < configuration.CI16_number; index++)
{
counterInput.modbusAddress = 30001 + index;
counterInput.eventClass = CLASS_3;
counterInput.threshold = 1;
dnpSaveCI16Config(configuration.CI16_startAddress +
&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 +
&counterInput);
Document (Version 1.61) 5/19/2011
644
Example Programs
}
// main loop
while (TRUE)
{
// add remainder of program here
// release processor to other priority 254 tasks
release_processor();
}
}
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
#define ALARM_OUTPUT
#define SCAN_EVENT
41000
1026
0
int main( void )
{
if (getProgramStatus((FUNCPTR)main) == NEW_PROGRAM)
{
/* Set default alarm limit */
request_resource(IO_SYSTEM);
setdbase(MODBUS, HI_ALARM, 4000);
release_resource(IO_SYSTEM);
/* Use values in database from now on */
setProgramStatus((FUNCPTR)main, PROGRAM_EXECUTED);
}
while (TRUE)
{
INT16 ain[8];
// analog input module data
/* Scan ain module */
ioRequest(MT_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);
Document (Version 1.61) 5/19/2011
645
Example Programs
release_resource(IO_SYSTEM);
/* Allow other tasks to execute */
release_processor();
}
}
Get Task Status Example
The following program displays information about all valid tasks.
#include <string.h>
#include <ctools.h>
int main(void)
{
struct prot_settings settings;
TASKINFO taskStatus;
/* Disable the protocol on serial port 1 */
settings.type = NO_PROTOCOL;
settings.station = 1;
settings.priority = 250;
settings.SFMessaging = FALSE;
request_resource(IO_SYSTEM);
set_protocol(com1, &settings);
release_resource(IO_SYSTEM);
/* display information about current task */
if (getTaskInfo(0, &taskStatus))
{
/* show information for valid task */
fprintf(com1, "\r\n\r\nInformation about task
%d:\r\n", task);
fprintf(com1, "
Task ID:
0x%x\r\n",
taskStatus.taskID);
fprintf(com1, "
Current Priority:%d\r\n",
taskStatus.cPriority);
fprintf(com1, "
Normal Priority: %d\r\n",
taskStatus.priority);
fprintf(com1, "
Task Group:
%d\r\n",
taskStatus.taskGroup);
if (taskStatus.requirement == REQ_NO_WAIT)
{
fprintf(com1, "
Ready to run \r\n");
}
if (taskStatus.requirement & REQ_MQUEUE)
{
fprintf(com1, "
Waiting to receive a
message.\r\n");
}
if (taskStatus.requirement & REQ_RESOURCE)
{
fprintf(com1, "
Waiting for resource:
%d\r\n", taskStatus.requirement & REQ_MASK);
Document (Version 1.61) 5/19/2011
646
Example Programs
}
if (taskStatus.requirement & REQ_EVENT)
{
fprintf(com1, "
Waiting on event number:
%d\r\n", taskStatus.requirement & REQ_MASK);
}
fprintf(com1, "
Error:
%d\r\n",
taskStatus.error);
}
while (TRUE)
{
/* Allow other tasks to execute */
release_processor();
}
}
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
:014701B7
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
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 UINT16 myModbusHandler(
UCHAR * message,
UINT16
messageLength,
UCHAR * response,
UINT16 * responseLength
Document (Version 1.61) 5/19/2011
647
Example Programs
)
{
UCHAR * pMessage;
UCHAR * pResponse;
pMessage = message;
if (*pMessage == 71)
{
/* Action for command data */
pMessage++;
if (*pMessage == 0)
{
request_resource(IO_SYSTEM);
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;
}
else 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;
}
else
{
return FUNCTION_NOT_HANDLED;
}
}
Document (Version 1.61) 5/19/2011
648
Example Programs
else
{
return FUNCTION_NOT_HANDLED;
}
}
static void myshutdown(void)
{
removeModbusHandler(myModbusHandler);
}
/* ----------------------------------------------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.
-------------------------------------------- */
int main(void)
{
TASKINFO taskStatus;
protocol.
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(DIAG_protocolStatus,1,31000, 0, 0, 0);
/* Install Exit Handler */
getTaskInfo(0, &taskStatus);
installExitHandler(taskStatus.taskID, (FUNCPTR)
myshutdown);
/* Install Modbus Handler */
request_resource(IO_SYSTEM);
installModbusHandler(myModbusHandler);
Document (Version 1.61) 5/19/2011
649
Example Programs
release_resource(IO_SYSTEM);
while(TRUE)
{
release_processor();
}
}
Install Serial Port Handler Example
/* --------------------------------------------------------------SCADAPack 350 C++ Application Main Program
Copyright 2006, Control Microsystems Inc.
--------------------------------------------------------------*/
#include <ctools.h>
#include "nvMemory.h"
#define CHAR_RECEIVED 11
/* --------------------------------------------------------------C++ Function Prototypes
-------------------------------------------------------------*/
void signal_serial(INT32 port, INT32 character);
/* --------------------------------------------------------------C Function Prototypes
-------------------------------------------------------------*/
extern "C"
{
// add prototypes here
}
/* --------------------------------------------------------------main
This program displays all characters received
om com1 using an installed handler to signal
the reception of a character.
--------------------------------------------------------------*/
int main(void)
{
INT32 port = 1;
INT32 character;
struct prot_settings protocolSettings;
//disable Protocol
get_protocol(com2, &protocolSettings);
protocolSettings.type = NO_PROTOCOL;
Document (Version 1.61) 5/19/2011
650
Example Programs
request_resource(IO_SYSTEM);
set_protocol(com2, &protocolSettings);
release_resource(IO_SYSTEM);
// Enable character handler
install_handler(com2,
(BOOLEAN(*)(INT32,INT32))signal_serial);
//
Print each character as it is received
while (TRUE)
{
wait_event(CHAR_RECEIVED);
character = fgetc(com2);
if (character == EOF)
{
// clear overflow error flag to re-enable com1
clearerr(com1);
}
fputs("character: ", com2);
fputc(character, com2);
fputs("\r\n", com2);
// release processor to other priority 1 tasks
release_processor();
}
}
/* -------------------------------------------------------------signal_serial
This routine signals an event when a character
is received. If there is an error, the
character is ignored.
---------------------------------------------------------*/
void signal_serial (INT32 port, INT32 character)
{
interrupt_signal_event(CHAR_RECEIVED);
}
Install Clock Handler Example
/* -------------------------------------------This program demonstrates how to call a
function at a specific time of day.
-------------------------------------------- */
#include <ctools.h>
#define
ALARM_EVENT
20
/* -------------------------------------------This function signals an event when the alarm
occurs.
-------------------------------------------- */
Document (Version 1.61) 5/19/2011
651
Example Programs
void alarmHandler(void)
{
interrupt_signal_event( ALARM_EVENT );
}
/* -------------------------------------------This task processes alarms signaled by the
clock handler
-------------------------------------------- */
void processAlarms(void)
{
while(TRUE)
{
wait_event(ALARM_EVENT);
/* Reset the alarm for the next day */
request_resource(IO_SYSTEM);
resetClockAlarm();
release_resource(IO_SYSTEM);
fprintf(com1, "It’s quitting time!\r\n");
}
}
int main(void)
{
struct prot_settings settings;
ALARM_SETTING alarm;
/* Disable the protocol on serial port 1 */
settings.type = NO_PROTOCOL;
settings.station = 1;
settings.priority = 250;
settings.SFMessaging = FALSE;
request_resource(IO_SYSTEM);
set_protocol(com1, &settings);
release_resource(IO_SYSTEM);
/* Install clock handler function */
installClockHandler(alarmHandler);
/* Create task for processing alarm events */
create_task(processAlarms, 75, applicationGroup, 4);
/* Set real time clock alarm */
alarm.type
= AT_ABSOLUTE;
alarm.hour
= 16;
alarm.minute = 0;
alarm.second = 0;
request_resource(IO_SYSTEM);
setClockAlarm(alarm);
release_resource(IO_SYSTEM);
while(TRUE)
{
Document (Version 1.61) 5/19/2011
652
Example Programs
/* body of main task loop */
/* other processing code */
/* Allow other tasks to execute */
release_processor();
}
}
Install Database Handler Example
This program assumes that the pointer pAllocatedMem has been declared in
nvMemory.h.
/* ------------------------------------------------------------This is a sample IEC 61131-1 application for the
installDbaseHandler and installSetdbaseHandler functions.
This sample program demonstrates database handlers for the
Modbus registers:
1001
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-1
variable.
Note that these database access functions are used by C++
applications and by all protocols.
------------------------------------------------------------ */
#include <ctools.h>
#include <string.h>
#include “nvMemory.h”
#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.
Document (Version 1.61) 5/19/2011
653
Example Programs
------------------------------------------------------------ */
static BOOLEAN dbaseHandler(
UINT16 address,
/* Modbus register address */
INT16 *value
/* pointer to value at address */
)
{
struct myDatabase * pMyDatabase; // pointer to custom
database
pMyDatabase = (struct myDatabase *) pNvMemory>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 */
)
{
Document (Version 1.61) 5/19/2011
654
Example Programs
struct myDatabase * pMyDatabase; // pointer to custom
database
pMyDatabase = (struct myDatabase *) pNvMemory>pAllocatedMem;
if (pMyDatabase == NULL)
{
// database could not be allocated
return FALSE;
}
if ((address > 1000) && (address <= 1000 + SAMPLE_SIZE))
{
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;
}
Document (Version 1.61) 5/19/2011
655
Example Programs
}
/* -----------------------------------------------------------This is the exit handler.
------------------------------------------------------------ */
static void myshutdown(void)
{
/* remove database handlers */
installDbaseHandler(NULL);
installSetdbaseHandler(NULL);
}
/* -----------------------------------------------------------This routine initializes the custom database.
The database memory is allocated if application has just been
downloaded. The exit handler is installed and the database
handlers are installed.
------------------------------------------------------------ */
static void initializeDatabase(void)
{
TASKINFO taskStatus;
BOOLEAN status;
if (getProgramStatus((FUNCPTR)main) == 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 **)&(pNvMemory>pAllocatedMem), MEM_SIZE);
release_resource(DYNAMIC_MEMORY);
if (status == TRUE)
{
// set program status so memory is not reallocated
// until next program download
setProgramStatus((FUNCPTR)main,
PROGRAM_EXECUTED);
// zero-fill new custom database
memset(pNvMemory->pAllocatedMem, 0, MEM_SIZE);
}
else
{
// memory could not be allocated
pNvMemory->pAllocatedMem = NULL;
}
}
// install exit handler to remove the custom database
// if the application is stopped or erased
getTaskInfo(0, &taskStatus);
installExitHandler(taskStatus.taskID, (FUNCPTR)
myshutdown);
Document (Version 1.61) 5/19/2011
656
Example Programs
// install database handlers
installDbaseHandler(dbaseHandler);
installSetdbaseHandler(setdbaseHandler);
}
/* -----------------------------------------------------------This routine is the main program. The custom i/o database is
initialized. The database is then updated continuously with
I/O data in the main loop.
------------------------------------------------------------ */
int main(void)
{
UINT16 dinData;
// data from 16 Din points
INT16 ainData[8];
// data from 8 Ain points
UINT16 doutData = 0;
// data written to Dout points
UINT16 index;
// initialize custom i/o database
initializeDatabase();
// main loop
while (TRUE)
{
// write data to Output tables
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 database
for (index=0; index<16; index++)
{
if (dinData & 0x01)
{
setdbase(MODBUS, 11001 + index, 1);
}
else
Document (Version 1.61) 5/19/2011
657
Example Programs
{
setdbase(MODBUS, 11001 + index, 0);
}
dinData >>= 1;
}
// 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 254 tasks
release_processor();
}
}
Memory Allocation Example
This program allocates dynamic non-volatile memory only when the C++
Application is run the first time after downloading.
Refer to the section Non-Volatile Data Sections for instructions on declaring nonvolatile variables. This program assumes that the pointer pAllocatedMem has
been declared in nvMemory.h.
#include <ctools.h>
#include “nvMemory.h"
struct myTable
{
UINT32 data[100];
};
#define MEM_SIZE
(sizeof(struct myTable))
int main( void )
{
BOOLEAN status;
struct myTable * pTable;
status = TRUE;
if (getProgramStatus((FUNCPTR)main) == NEW_PROGRAM)
{
// Application has just been downloaded.
request_resource(DYNAMIC_MEMORY);
status = allocateMemory((void **)&(pNvMemory>pAllocatedMem), MEM_SIZE);
release_resource(DYNAMIC_MEMORY);
Document (Version 1.61) 5/19/2011
658
Example Programs
if (status == TRUE)
{
// set program status so memory is not reallocated
// until application is downloaded again
setProgramStatus((FUNCPTR)main,
PROGRAM_EXECUTED);
}
}
// use non-volatile memory for table structure
pTable = (struct myTable *) (pNvMemory->pAllocatedMem);
while (TRUE)
{
if (status == TRUE)
{
// pTable is used in remainder of program
// ...
}
else
{
// print error message
}
// Allow other tasks to execute
release_processor();
}
}
Master Message Example Using Modbus Protocol
This program sends a master message, on com2, using the Modbus protocol,
then waits for a response from the slave. The number of good and failed
messages is printed to com1.
/* -------------------------------------------poll.c
Polling program for Modbus slave.
-------------------------------------------- */
#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.
-------------------------------------------- */
Document (Version 1.61) 5/19/2011
659
Example Programs
void wait_for_response(UCHAR port, unsigned time)
{
UINT32 startTime;
struct prot_status status;
static unsigned long good, bad;
startTime = readStopwatch();
do {
/* Allow other tasks to execute */
release_processor();
status = get_protocol_status(port);
}
while ((readStopwatch() – startTime) < (100 * time) &&
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.
-------------------------------------------- */
int main(void)
{
struct prot_settings settings;
struct pconfig portset;
request_resource(IO_SYSTEM);
/* disable protocol on serial port 1 */
settings.type = NO_PROTOCOL;
settings.station = 1;
settings.priority = 250;
settings.SFMessaging = FALSE;
set_protocol(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 */
Document (Version 1.61) 5/19/2011
660
Example Programs
settings.type = MODBUS_ASCII;
settings.station = 2;
settings.priority = 250;
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);
/* 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();
}
}
Master Message Example Using serialModbusMaster
This program sends master messages on com2 demonstrating two methods
using the function serialModbusMaster.
/* -------------------------------------------SCADAPack 350 C++ Application Main Program
Copyright 2001 - 2004, Control Microsystems Inc.
-------------------------------------------- */
#include <ctools.h>
// function prototypes
Document (Version 1.61) 5/19/2011
661
Example Programs
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.
-------------------------------------------- */
UINT32 mainPriority = 100;
UINT32 mainStack = 4;
UINT32 applicationGroup = 0; int main(void)
{
MASTER_MESSAGE
message;
BOOLEAN
status;
UINT16
good, bad;
struct prot_settings settings;
struct pconfig portset;
request_resource(IO_SYSTEM);
// enable Modbus protocol on com2
settings.type = MODBUS_RTU;
settings.station = 1;
settings.priority = 250;
settings.SFMessaging = FALSE;
set_protocol(com2, &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, 100, applicationGroup, 4);
Document (Version 1.61) 5/19/2011
662
Example Programs
// define master message to read slave
// analog inputs
message.stream
= com2;
message.function
= 4;
message.slaveStation
= 2;
message.slaveRegister
= 30001;
message.masterRegister
= 40001;
message.length
= 8;
message.timeout
= 30;
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)
{
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
Document (Version 1.61) 5/19/2011
663
Example Programs
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
message.stream
= com2;
message.function
= 2;
message.slaveStation
= 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++;
}
}
// allow other tasks to execute
release_processor();
}
}
Document (Version 1.61) 5/19/2011
664
Example Programs
Master Message Example Using mTcpMasterMessage
This program sends master messages on the LAN interface using Modbus/TCP
protocol.
/* -------------------------------------------SCADAPack 350 C++ Application Main Program
Copyright 2001 - 2004, Control Microsystems Inc.
-------------------------------------------- */
#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.
-------------------------------------------- */
int 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 1.61) 5/19/2011
665
Example Programs
protocolType
= IPP_ModbusTcp;
appType
= CT_MasterCApp;
timeout
= 30;
// tenths of seconds
function
= 3;
// read holding registers
slaveStation
= 1;
slaveRegister
= 40155;
masterRegister
= 40001;
length
= 2;
// main loop
mode = MIP_OPEN_CONNECTION;
while (TRUE)
{
switch(mode)
{
case MIP_OPEN_CONNECTION:
{
// open a connection
status = mTcpMasterOpen(
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;
}
}
Document (Version 1.61) 5/19/2011
666
Example Programs
}
break;
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:
Document (Version 1.61) 5/19/2011
667
Example Programs
// response received
successfully; send next message
mode = MIP_SEND_MESSAGE;
break;
default:
// remaining status codes
are error codes
mode = MIP_DISCONNECT;
break;
}
}
}
break;
case MIP_DISCONNECT:
if (mTcpMasterDisconnect(connectID))
{
// disconnect is successfully started
mode = MIP_CLOSE;
}
break;
case MIP_CLOSE:
if (mTcpMasterClose(connectID))
{
// connection has been successfully
released
// open new connection and start again
mode = MIP_OPEN_CONNECTION;
}
break;
}
// release processor to other priority 254 tasks
release_processor();
}
}
Modem Initialization Example
The following code shows how to initialize a modem. Typically, the modem
initialization is used to prepare a modem to answer calls. The example sets up a
Hayes modem to answer incoming calls.
#include <ctools.h>
#include <string.h>
int main(void)
{
struct ModemInit initSettings;
reserve_id portID;
enum DialError status;
enum DialState state;
struct pconfig portSettings;
/* Configure serial port 1 */
Document (Version 1.61) 5/19/2011
668
Example Programs
portSettings.baud
= BAUD1200;
portSettings.duplex
= FULL;
portSettings.parity
= NONE;
portSettings.data_bits = DATA8;
portSettings.stop_bits = STOP1;
portSettings.flow_rx
= RFC_MODBUS_RTU;
portSettings.flow_tx
= TFC_NONE;
portSettings.type
= RS232_MODEM;
portSettings.timeout
= 600;
request_resource(IO_SYSTEM);
set_port(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);
}
}
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 need to be set with valid values for the
clock to operate properly.
#include <ctools.h>
int main(void)
{
TIME now;
/* Set to 12:01:00 on January 1, 1997 */
now.hour
now.minute
now.second
now.day
now.month
now.year
now.dayofweek
Document (Version 1.61) 5/19/2011
=
=
=
=
=
=
=
12;
1;
0;
1;
1;
97;
3;
/* set the time */
/* set the date */
/* day is Wed. */
669
Example Programs
request_resource(IO_SYSTEM);
setclock(&now);
getclock(&now);
/* read the clock
*/
release_resource(IO_SYSTEM);
/* Display current hour, minute and second */
fprintf(com1,"%2d/%2d/%2d", now.day, now.month,
now.year);
fprintf(com1,"%2d:%2d\r\n",now.hour, now.minute);
}
Start Timed Event Example
This program prints the time every 10 seconds.
#include <string.h>
#include <ctools.h>
#define TIME_TO_PRINT
15
/* -------------------------------------------The myshutdown function stops the signalling
of TIME_TO_PRINT events.
-------------------------------------------- */
void myshutdown(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.
-------------------------------------------- */
int main(void)
{
struct prot_settings settings;
struct clock now;
TASKINFO taskStatus;
/* Disable the protocol on serial port 1 */
settings.type = NO_PROTOCOL;
settings.station = 1;
settings.priority = 250;
settings.SFMessaging = FALSE;
request_resource(IO_SYSTEM);
set_protocol(com1, &settings);
release_resource(IO_SYSTEM);
/* set up task exit handler to stop
signalling of events when this task ends */
Document (Version 1.61) 5/19/2011
670
Example Programs
getTaskInfo(0, &taskStatus);
installExitHandler(taskStatus.taskID, (FUNCPTR)
myshutdown);
/* 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 1.61) 5/19/2011
671
Porting Existing C Tools Applications
Porting Existing C Tools Applications
Porting SCADAPack 32 C++ Applications to the SCADAPack 350 and 4203
Compiler Differences between Hitachi and GNU
The Hitachi compiler used with the SCADAPack 32 has the following difference
with GNU compiler used with the SCADAPack 350 and 4203:
The order of bit fields is reversed. Bit field ordering is not specified by the C
standard. It is left to the compiler maker. Existing programs using bit fields need
to be modified if the order of the bit fields affects the operation of the program. If
the bit fields are being used only for space efficiency the program does not need
rewriting.
Porting Existing C++ Tools Applications
Existing SCADAPack 32 C++ applications are highly compatible with the
SCADAPack 350 and 4203 C++ Tools. However changes are necessary. The
following guide describes the steps in porting an application.
Copy SCADAPack C++ Application Framework
Begin by making a copy of the SCADAPack C++ application framework using the
IEC 61131-1 sample application or the Telepace sample application. By default
the samples are installed at C:\Program Files\Control
Microsystems\CTools\Controller\Framework Applications. Make a copy of one of
the following directories:

C:\Program Files\Control Microsystems\CTools\Controller\Framework
Applications\Telepace

C:\Program Files\Control Microsystems\CTools\Controller\Framework
Applications\IEC 61131-1
Changes to appstart.cpp
Instead of appSettings.src used in SCADAPack 32 C++ applications, the new
appstart.cpp assigns the stack size as well as the main task priority. Task
priorities are discussed under changes to the function create_task. The heap size
is no longer configurable. The C++ application has access to the entire system
heap.
Open the sample appstart.cpp to review these application settings:
...
// Priority of the task main().
// Priority 100 is recommended for a continuously running task.
UINT32 mainPriority = 100;
Document (Version 1.61) 5/19/2011
672
Porting Existing C Tools Applications
// Stack space allocated to the task main().
// Note that at least 5 stack blocks are needed to call fprintf().
UINT32 mainStack = 5;
// Application group assigned to the task main().
// A unique value is assigned by the system to the applicationGroup
// for this application. Use this variable in calls to create_task()
// by this application.
UINT32 applicationGroup = 0;
...
A C++ application should not require any further modifications to appstart.cpp.
There are no longer function calls in appstart() for starting various drivers as
there were in the SCADAPack 32 version. These drivers are already running
when a C++ Application is executed. It is still possible to call these functions to
disable functionality. For example, runTarget(FALSE) may still be called from
appstart() or main() to stop the logic application.
Replace main.cpp
Replace the sample file main.cpp with the main.cpp from your SCADAPack 32
C++ Application. Edit your main.cpp and make the following changes:

In addition to the ctools.h header you need to include the header file
nvMemory.h.

The C++ Tools require main() to have the prototype: int main(void). Change
the syntax of main() so that it returns the data type int instead of void. Note
that the returned int value is not accessible to the user and so any value may
be returned or none at all.

Remove the function definition for abort(). This function is provided by the
operating system.

The call release_processor() in the main loop can be deleted. See section
Operating System Scheduling for details.
Add Remaining C and CPP Files
Copy any additional C, CPP or H files from your application to the copied sample
application directory.
Replace Partially Supported and Unsupported Functions
Existing programs may use some functions that are partially supported or
unsupported on the SCADAPack 350 4203 controllers. The program needs to be
changed to use the new functions of the SCADAPack 350 4203 controllers. For a
list of the functions affected refer to the sections Partially Supported C++ Tools
Functions,.
Document (Version 1.61) 5/19/2011
673
Porting Existing C Tools Applications
Build the Application
The SCADAPack C++ Tools use a command line to compile and link a C++
application. The sample application includes the command file build.bat to do
this. Please see the section Application Development for more details on editing
build.bat, command line options, and loading the application into the controller.
Test the Application
This step is specific to the application. It needs to be tested to confirm it operates
correctly on the SCADAPack controllers.

SCADAPack 32 controllers have higher performance than do SCADAPack
350 4203 controllers. Check that any I/O operations allow enough time for
field signals to change state. Some timing relationships in the existing
program may not be true in the new program, depending on how you have
implemented them. For example, a calculation done between two I/O
operations may execute slower and cause the second I/O operation to take
place later than you want.

Check that any periodic functions execute at the correct rate. If you've used
standard timing functions this should not be a problem. If you've used delay
loops then these will execute slower. You should replace them with standard
timing functions.
Partially Supported C++ Tools Functions
The following sections describe functions that are supported by the SCADAPack
32 C++ Tools but are only partially supported by the SCADAPack C++ Tools.
The following features are similar to existing SCADAPack 32 C++ Tools features
but require some source code modification.
Refer to these sections when porting existing SCADAPack 32 C++ Tools
Applications to the SCADAPack 350 4203 controllers.
Event Numbers for SCADAPack C++ Applications
The SCADAPack 350 4203 support up to 32 separate user-loaded C++
Applications. Event numbers 0 to 31 were made available to the SCADAPack 32
C++ application. This same event number range need to be shared on the
SCADAPack 350 4203 among the user-loaded C++ Applications.
The Realflo C++ Application uses events 20, 21, or 22. These events may not be
used by other C++ Applications when the Realflo C++ Application is loaded in the
SCADAPack 350 4203.
Stack used by fprintf Function
Tasks that call the function fprintf require at least 5 stack blocks. This function
required only 4 stack blocks when used in SCADAPack 32 C++ applications. As
a general rule, add 1 stack block to the amount used in a SCADAPack 32 C++
application.
Document (Version 1.61) 5/19/2011
674
Porting Existing C Tools Applications
Macro stdout is Disabled
The macro stdout is disabled in the SCADAPack C++ Tools. Instead use the
serial port macros: com1, com2, or com3. This means that the following functions
that use stdout do not work: printf, putc, getc. Use the replacement functions
listed below.
Function
Replaced with
printf
putc
getc
fprintf
fputc
fgetc
Task Creation Function
The task priorities have changed with the SCADAPack 350 and 4203. There are
now 255 priority levels, and the highest priority task has a priority of 0. Existing
calls to create_task will need to be modified to account for a lower number being
a higher priority.
The table below contains the recommended priority values to use when porting to
the SCADAPack 350 and 4203.
Priority Description
Equivalent Priority
Value for SCADAPack
350 and 4203
Priority Value for
SCADAPack 32
Higher Priority
25
50
75
100
4
3
2
1
Lower Priority
The argument used for application type in existing calls to create_task must be
replaced with the global variable applicationGroup. The operating system assigns
a unique value to applicationGroup when it is defined in appStart.cpp.
Please see the documentation for create_task in the Function Specifications
section for more details.
Controller I/O Functions
The following functions are no longer supported. The replacement function is
indicated for each. Each function is documented in the Function Specifications
section.
Function
Replaced with
interruptInput
interruptCounter
readCounter
readCounterInput
no replacement function
no replacement function
ioReadCounterSP2
no replacement function
Document (Version 1.61) 5/19/2011
675
Porting Existing C Tools Applications
ioReadDin5232
ioReadCounter5232
ioRead5601Inputs
ioRead5601Outputs
ioWrite5601Outputs
no replacement function
ioReadCounterSP2
ioReadSP2Inputs
ioReadSP2Outputs
ioWriteSP2Outputs
Exit Handler Function
The argument used to specify the exit handler function in existing calls to
installExitHandler must be cast to the type (FUNCPTR). Please see the
documentation for installExitHandler in the Function Specifications section for
more details.
Program Status Functions
The functions getProgramStatus and setProgramStatus have changed syntax.
To support multiple C++ applications, these functions now have an argument to
specify the application. The new syntax for these functions is documented in the
Function Specifications section.
Freeing Dynamic Memory
When a C++ Application is ended (e.g. by using the STOP button from the C/C++
Program Loader), memory allocated by using the malloc function is not freed
automatically. An exit handler must be installed to free allocated memory. Please
see the documentation for installExitHandler in the Function Specifications
section for more details.
Non-Volatile Data Sections
The SCADAPack 350 and 4203 have a different method for declaring static nonvolatile memory. There is still 8 kB of memory available but it needs to now be
shared with all user-loaded C++ applications. Non-volatile variable declarations
and their pragma statements need to be removed from each source file and
declared globally in the one file nvMemory.h. Include nvMemory.h in each source
file that uses non-volatile variables.
Please see the section Non-Volatile Memory for more details on editing
nvMemory.h and on using these variables in your source files.
Socket Functions
The following functions are no longer supported. The replacement function is
indicated for each.
Function
Replaced with
tfClose
tfGetSocketError
close
errnoGet
Modbus Handler Functions
Document (Version 1.61) 5/19/2011
676
Porting Existing C Tools Applications
The installModbusHandler is used to add user-defined extensions to the standard
Modbus protocol. To uninstall a Modbus handler in a SCADAPack 32 C++
application, the same function is called with the NULL pointer.
SCADAPack C++ applications support the installation of multiple Modbus
handlers. In order to remove a specific Modbus handler the new function
removeModbusHandler is used. Calling installModbusHandler with the NULL
pointer has no effect.
Unsupported C++ Tools Functions
The following sections describe functions that are supported by the SCADAPack
32 C++ Tools but are not supported by the SCADAPack C++ Tools.
Refer to these sections when porting existing C++ Tools Applications to the
SCADAPack 350 and 4203.
Timers
The following C++ Tools Timer functions are not supported. Use the functions
readStopwatch or startTimedEvent instead.
Function
interval
read_timer_info
runTimers
settimer
timer
Option Switch Function
The following C++ Tools function is not supported.
Function
optionSwitch
IP Functions
The following C++ Tools functions are not supported.
Function
readv
tfBcopy
tfBindNoCheck
tfBlockingState
tfBzero
tfDialerAddExpectSend
tfDialerAddSendExpect
tfFreeZeroCopyBuffer
Document (Version 1.61) 5/19/2011
677
Porting Existing C Tools Applications
Function
tfGetOobDataOffset
tfGetPppDnsIpAddress
tfGetPppPeerlpAddress
tfGetSendCompltBytes
tfGetWaitingBytes
tfGetZeroCopyBuffer
tfInetToAscii
tfIoctl
tfPingClose
tfPingGetStatistics
tfPingOpenStart
tfPppSetOption
tfRead
tfRegisterSocketCB
tfRegisterSocketCBParam
tfResetConnection
tfSendToInterface
tfSetPppPeerIpAddress
tfSetTreckOptions
tfSocketArrayWalk
tfUseDialer
tfWrite
tfZeroCopyRecv
tfZeroCopyRecvFrom
tfZeroCopySend
tfZeroCopySendTo
writev
PPP Functions
The following C++ Tools PPP functions are not supported.
Function
pppGetInterfaceHandle
pppReadSettings
pppReadUserTableEntry
pppReadUserTableSize
pppWriteSettings
pppWriteUserTableEntry
pppWriteUserTableSize
Document (Version 1.61) 5/19/2011
678
Porting Existing C Tools Applications
Porting SCADAPack C Applications to the SCADAPack 350 and 4203
Porting Existing C Tools Applications
Existing SCADAPack C applications are highly compatible with the SCADAPack
C++ Tools. However changes are necessary. The following guide describes the
steps in porting an application.
Copy SCADAPack C++ Application Framework
Begin by making a copy of the SCADAPack C++ application framework using the
IEC 61131-1 sample application or the Telepace sample application. By default
the samples are installed at C:\Program Files\Control
Microsystems\CTools\Controller\Framework Applications. Make a copy of one of
the following directories:

C:\Program Files\Control Microsystems\CTools\Controller\Framework
Applications\Telepace

C:\Program Files\Control Microsystems\CTools\Controller\Framework
Applications\IEC 61131-1
Changes to appstart.cpp
The new appstart.cpp assigns the stack size as well as the main task priority.
Task priorities are discussed under changes to the function create_task. The
heap size is no longer configurable. The C++ application has access to the entire
system heap.
Open the sample appstart.cpp to review these application settings:
...
// Priority of the task main().
// Priority 100 is recommended for a continuously running task.
UINT32 mainPriority = 100;
// Stack space allocated to the task main().
// Note that at least 5 stack blocks are needed to call fprintf().
UINT32 mainStack = 5;
// Application group assigned to the task main().
// A unique value is assigned by the system to the applicationGroup
// for this application. Use this variable in calls to create_task()
// by this application.
UINT32 applicationGroup = 0;
...
A C++ application should not require any further modifications to appstart.cpp.
Note that there are no longer function calls in appstart() for starting various
drivers as there were in the SCADAPack version. These drivers are already
running when a C++ Application is executed. It is still possible to call these
Document (Version 1.61) 5/19/2011
679
Porting Existing C Tools Applications
functions to disable functionality. For example, runTarget(FALSE) may still be
called from appstart() or main() to stop the logic application.
Add Existing Program Files to Framework

Copy all user-written *.C files from the SCADAPack application to the
framework directory created in the last section.

Copy user-written *.H files, if any, from the SCADAPack application to the
framework directory. Do NOT copy the SCADAPack ctools.h file or any other
C Tools header files (e.g. older SCADAPack C Tools headers such as
protocol.h). The new ctools.h is already in the framework directory.

For each user-written *.H file copied to the framework directory in step 2,
make sure that the following statements are included at the top of each
header file:
#ifdef __cplusplus
extern "C"
{
#endif
And also make sure that the following statements are included at
the bottom of each header file:
#ifdef __cplusplus
}
#endif

Edit the SCADAPack application file that contains the function main(). Open
this file and copy its contents beginning after the included headers and paste
this into the framework file main.cpp after the prototypes as shown below. If
there are additional headers included, copy these include statements to the
main.cpp file next.
/* ----------------------------------------------------------SCADAPack 350 and 4203 C++ Application Main Program
Copyright 2006, Control Microsystems Inc.
----------------------------------------------------------- */
#include <ctools.h>
#include "nvMemory.h"
/* ----------------------------------------------------------C++ Function Prototypes
----------------------------------------------------------- */
// add prototypes here
/* ----------------------------------------------------------C Function Prototypes
----------------------------------------------------------- */
extern "C"
{
// add prototypes here
}
Document (Version 1.61) 5/19/2011
680
Porting Existing C Tools Applications
Paste your code here

Delete the additional stub function main() at the end of the file main.cpp. The
C++ Tools require main() to have the prototype: int main(void). Change the
syntax of main() so that it returns the data type int instead of void. The
returned int value is not accessible to the user and so any value may be
returned or none at all.
Replace Older C Tools Headers with ctools.h
If the ported application used SCADAPack C Tools version 2.12 or older, the
program C files will likely have include statements with C Tools header files, such
as protocol.h, primitiv.h, etc. Replace all these C Tools include statements in all
program C files with just one include statement:
include <ctools.h>
Replace Partially Supported and Unsupported Functions
Existing programs may use some functions that are partially supported or
unsupported on the SCADAPack 350 and 4203 controllers. The program must be
changed to use the new functions. For a list of the functions affected refer to the
sections Partially Supported C Tools Functions.
Build the Application
The SCADAPack C++ Tools use a command line to compile and link a C++
application. The sample application includes the command file build.bat to do
this. Please see the section Application Development for more details on editing
build.bat, command line options, and loading the application into the controller.
Test the Application
This step is specific to the application. It must be tested to confirm it operates
correctly on the SCADAPack 350 and 4203 controllers. You also should pay
attention to the following.

SCADAPack 350 and 4203 controllers have higher performance than do
SCADAPack controllers. Check that any I/O operations allow enough time for
field signals to change state. Some timing relationships in the existing
program may not be true in the new program, depending on how you have
implemented them. For example, a calculation done between two I/O
operations may execute faster and cause the second I/O operation to take
place sooner than you want.

Check that any periodic functions execute at the correct rate. If you've used
standard timing functions this should not be a problem. If you've used delay
loops then these will execute faster. You should replace them with standard
timing functions.
Partially Supported C Tools Functions
The following sections describe functions that are supported by the Telepace C
Tools and IEC 61131-1 C Tools but are only partially supported by the
Document (Version 1.61) 5/19/2011
681
Porting Existing C Tools Applications
SCADAPack C++ Tools. The following features are similar to existing C Tools
features but require some source code modification.
Refer to these sections when porting existing SCADAPack C Tools Applications.
Event Numbers for SCADAPack C++ Applications
The SCADAPack 350 and 4203 support up to 32 separate user-loaded C++
Applications. Event numbers 0 to 31 were made available to the SCADAPack C
application. This same event number range needs to be shared on the
SCADAPack 350 and 4203 among the user-loaded C++ Applications.
The Realflo C++ Application uses events 20, 21, or 22. These events may not be
used by other C++ Applications when the Realflo C++ Application is loaded in the
SCADAPack 350 and 4203.
Stack used by fprintf Function
Tasks that call the function fprintf require at least 5 stack blocks. This function
required only 4 stack blocks when used in SCADAPack C applications. As a
general rule, add 1 stack block to the amount used in a SCADAPack application.
Macro stdout is Disabled
The macro stdout is disabled in the SCADAPack C++ Tools. Instead use the
serial port macros: com1, com2, or com3. This means that the following functions
that use stdout do not work: printf, putc, getc. Use the replacement functions
listed below.
Function
Replaced with
printf
putc
getc
fprintf
fputc
fgetc
Task Creation Function
The task priorities have changed with the SCADAPack 350 and 4203. There are
now 255 priority levels, and the highest priority task has a priority of 0. Existing
calls to create_task will need to be modified to account for a lower number being
a higher priority.
The table below contains the recommended priority values to use when porting.
Priority Description
Higher Priority
Lower Priority
Document (Version 1.61) 5/19/2011
Equivalent Priority
Value for SCADAPack
350 and 4203
25
50
75
100
Priority Value for
SCADAPack
4
3
2
1
682
Porting Existing C Tools Applications
The argument used for application type in existing calls to create_task needs to
be replaced with the global variable applicationGroup. The operating system
assigns a unique value to applicationGroup when it is defined in appStart.cpp.
Please see the documentation for create_task in the Function Specifications
section for more details.
Exit Handler Function
The argument used to specify the exit handler function in existing calls to
installExitHandler must be cast to the type (FUNCPTR). Please see the
documentation for installExitHandler in the Function Specifications section for
more details.
Program Status Functions
The functions getProgramStatus and setProgramStatus have changed syntax.
To support multiple C++ applications, these functions now have an argument to
specify the application. The new syntax for these functions is documented in the
Function Specifications section.
Freeing Dynamic Memory
When a C++ Application is ended (e.g. by using the STOP button from the C/C++
Program Loader), memory allocated by using the malloc function is not freed
automatically. An exit handler must be installed to free allocated memory. Please
see the documentation for installExitHandler in the Function Specifications
section for more details.
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 350 and 4203.
SCADAPack C++ Tools applications can make variables non-volatile by locating
them in SRAM. There is 8 KB of SRAM available for static application variables.
If this is not enough, up to 1 MB of SRAM is available for dynamic non-volatile
memory allocation. See the function allocateMemory.
To create a non-volatile section, refer to the section Non-Volatile Memory
(nvMemory.h).
I/O System Functions
The SCADAPack 350, SCADAPack 4203 and SCADAPack 32 use a different I/O
system architecture than the SCADAPack. I/O operations can be performed in
parallel with application program execution. This improves the performance of
IEC 61131-1 and Telepace applications, and can have similar impact on user
applications.
In the new architecture, I/O requests are added to a queue. Requests are read
from the queue and processed by separate I/O controller hardware. Data are
stored in I/O arrays that can be read and written by the application program. The
Document (Version 1.61) 5/19/2011
683
Porting Existing C Tools Applications
application program can also synchronize with the I/O controller to determine
when a set of I/O requests is complete.
Existing application programs need to be rewritten to use the new I/O system
functions.
Most I/O System functions are C++ functions. In order to call C++ functions from
a source file, the source file must be a *.CPP file. If an existing *.C file must be
renamed to a *.CPP file.
The following is a list of the I/O System functions. Each function is documented in
the Function Specifications section.
C++




Function
ioSetConfiguration
ioGetConfiguration
ioVersion
ioNotification
ioSystemReset
ioRequest
ioStatus
ioReadAin4

ioReadAin8

ioReadAout2

ioReadAout4

ioReadCounter4

ioReadCounterSP2

ioReadDin16

ioReadDin8

ioReadDout16

ioReadDout8

ioReadSP2Inputs

ioReadSP2Outputs

ioWriteAout2
Document (Version 1.61) 5/19/2011
Description
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
Read buffered data for 2 point
analog output module
Read buffered data for 4 point
analog output module
Read buffered data from 4 point
counter input module
Read buffered data from
SCADAPack 350 counters
Read buffered data from 16 point
digital input module
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
SCADAPack 350 inputs
Read buffered data for SCADAPack
350 outputs
Write buffered data for 2 point
684
Porting Existing C Tools Applications
C++
Function

ioWriteAout4
ioWriteDout16
ioWriteDout8
ioWriteSP2Outputs
Description
analog output module
Write buffered data for 4 point
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 SCADAPack
350 outputs
Controller I/O Functions
The following functions are no longer supported. The replacement function is
indicated for each.
Function
Replaced with
interruptInput
interruptCounter
readCounter
readCounterInput
readInternalAD
ioReset
ioRefresh
ioReadDin5232
ioReadCounter5232
ioRead5601Inputs
ioRead5601Outputs
ioWrite5601Outputs
no replacement function
no replacement function
ioReadCounterSP2
no replacement function
readBattery, readThermistor
ioSystemReset
functions in the ioWrite group
no replacement function
ioReadCounterSP2
ioReadSP2Inputs
ioReadSP2Outputs
ioWriteSP2Outputs
IEC 61131-1 I/O Functions
The I/O System functions are used in place of the following IEC 61131-1 C++
Tools I/O functions which are no longer supported.
Function
Replaced with
isaRead4Ain
isaRead8Ain
isaRead4Counter
isaRead8Din
isaRead16Din
isaRead5601Inputs
isaWrite2Aout
isaWrite4Aout
ioReadAin4
ioReadAin8
ioReadCounter4
ioReadDin8
ioReadDin16
ioReadSP2Inputs
ioWriteAout2
ioWriteAout4
Document (Version 1.61) 5/19/2011
685
Porting Existing C Tools Applications
Function
isaWrite8Dout
isaWrite16Dout
isaWrite5601Outputs
Replaced with
ioWriteDout8
ioWriteDout16
ioWriteSP2Outputs
Backwards Compatibility I/O Functions
The following I/O related functions were available in the original release of the
Telepace C++ Tools. They were supported for backward compatibility in later
versions of the Telepace C++ Tools, but did not allow access to all I/O modules.
They are no longer compatible with the I/O system architecture.
These functions are replaced with equivalent I/O system functions. The new
functions provide access to all I/O modules.
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
C++ Tools with the following difference. Instead of executing the required I/O
operation immediately before returning from the function, the I/O operation is
added to the I/O System queue as an I/O request and is performed by the I/O
System architecture in parallel with application program execution.
Notification of the completion of an I/O request may be obtained using the
ioNotification function.
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 need to be modified
to call the new function and to convert any timing constants to milliseconds.
The C Tools function setjiffy is not supported. Elapsed time from a particular
point can be measured by saving the time at the start of the interval, rather than
setting the clock to zero.
Document (Version 1.61) 5/19/2011
686
Porting Existing C Tools Applications
Real Time Clock Functions
The getclock function has a new syntax. A clock structure is no longer returned
by the function. Instead a pointer to a clock structure is passed as an argument.
The getclock function is documented in the Function Specifications section.
Get Task Information Function
The getTaskInfo function has a new syntax. A TASKINFO structure is no longer
returned by the function. Instead a pointer to a TASKINFO structure is passed as
an argument and a status flag is returned. The getTaskInfo function is
documented in the Function Specifications section.
EEPROM/Flash Memory Functions
SCADAPack 350 and 4203 controllers use flash memory instead of EEPROM to
store controller settings. The following functions are no longer supported. The
replacement function is indicated for each.
Function
Replaced with
load
save
flashSettingsLoad
flashSettingsSave
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;
};
Document (Version 1.61) 5/19/2011
687
Porting Existing C Tools Applications
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; // slave interface type
UINT16
slaveStation;
// slave station address
COM_INTERFACE
forwardInterface;
// forwarding interface
UINT16
forwardStation; // forwarding station address
IP_ADDRESS
forwardIPAddress;
type
// forwarding IP address
}
SF_TRANSLATION;
The following table explains how to correct existing programs that use the older
structure. The new SF_TRANSLATION structure is documented following this
table.
Item to be replaced
Replacement
struct SFTranslation
The new structure has the macro name
SF_TRANSLATION.
Set slaveInterface field = portA + 1
(1 = com1, 2 = com2, 3 = com3, 100 =
Ethernet1)
Set forwardInterface field = portB + 1
(1 = com1, 2 = com2, 3 = com3, 100 =
Ethernet1)
slaveStation field
forwardStation field
portA field
portB field
stationA field
stationB 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.
Document (Version 1.61) 5/19/2011
688
Porting Existing C Tools Applications
Serial Port Configuration Functions
portConfiguration
The C Tools function portConfiguration returned a pointer to the port
configuration table for com1 and com2 only. These functions are no longer
supported.
Use the functions get_port and set_port in place of portConfiguration.
Default Settings for Com1 and Com2
The default settings for Com1 and Com2 have changed. All serial ports of the
SCADAPack 350 and 4203 have the same default settings and the same range
of available settings. This change is most notable in the default setting for Rx
Flow control as described below.
The documentation for the structure pconfig has been updated below to reflect
these changes.
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 350 and 4203 must have Rx Flow Control set to
RFC_MODBUS_RTU (or ENABLE) when the Modbus RTU protocol is used. Rx
Flow Control must be set to RFC_NONE (or DISABLE) when the Modbus ASCII
or any other protocol is used.
Rx and Tx Flow Control requirements are now the same for all serial ports of the
SCADAPack 350 and 4203.
New Flow Control MACROS
To help clarify the type of Flow Control feature provided when ENABLE or
DISABLE is specified, four new macros have been defined:
RFC_MODBUS_RTU may be used in place of ENABLE. Both have the value 1.
RFC_NONE may be used in place of DISABLE. Both have the value 0.
TFC_IGNORE_CTS may be used in place of ENABLE. Both have the value 1.
TFC_NONE may be used in place of DISABLE. Both have the value 0.
Timeout Setting Not Supported
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.
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.
Document (Version 1.61) 5/19/2011
689
Porting Existing C Tools Applications
A main application task or an additional application task can be made to wait on
a periodic event before executing a set of actions. If the actions are completed
before the next periodic event has been signaled, the task is blocked while
waiting for the event. This blocked state allows the processor to execute other
application or system tasks while it 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.
Modbus Handler Functions
The installModbusHandler is used to add user-defined extensions to the standard
Modbus protocol. To uninstall a Modbus handler in a SCADAPack C application,
the same function is called with the NULL pointer.
SCADAPack 350 and 4203 C++ applications support the installation of multiple
Modbus handlers. In order to remove a specific Modbus handler the new function
removeModbusHandler is used. Calling installModbusHandler with the NULL
pointer has no effect.
Unsupported C Tools Functions
The following sections describe functions that are supported by the Telepace C
Tools and IEC 61131-1 C Tools but are not supported by the SCADAPack C++
Tools.
Refer to these sections when porting existing SCADAPack C Tools Applications.
Document (Version 1.61) 5/19/2011
690
Porting Existing C Tools Applications
Application Checksum Function
A checksum is no longer used for the C++ application. The C Tools function
applicationChecksum is not supported.
Backwards Compatibility Functions
These functions were supported in previous C Tools for backwards compatibility,
however they were stubs. The following C Tools functions are not supported.
Function
setSFMapping
getSFMapping
Boot Type Functions
These functions are not useful to C++ Applications. The following C Tools
functions are not supported.
Function
setBootType
getBootType
I/O Bus Communication Functions
The SCADAPack 350 and 4203 I/O System does not support these C Tools
2
functions. 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
Timers
The following C++ Tools Timer functions are not supported. Use the functions
readStopwatch or startTimedEvent instead.
Function
interval
read_timer_info
Document (Version 1.61) 5/19/2011
691
Porting Existing C Tools Applications
settimer
timer
Document (Version 1.61) 5/19/2011
692
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