citect database

8/12/2019 Citect Database

1/51

Citect Pty Ltd

3 Fitzsimmons Lane

Gordon NSW 2072

Australia

www.citect.com

Version5.5

Transferring DataPrinters, Databases, Files and Other

Applications)


2/51

DISCLAIMERCitectPty.Limitedmakesnorepresentationsorwarrantieswithrespecttothismanualand,tothemaximumextentpermittedbylaw,expresslylimitsitsliabilityforbreachofanywarrantythatmaybeimpliedtothereplacementofthismanualwithanother.Further,CitectPty.Limitedreservesthe

righttorevisethispublicationatanytimewithoutincurringanobligationtonotifyanypersonoftherevision.

COPYRIGHTCopyright2003CitectPtyLimited.Allrightsreserved.

TRADEMARKSCitectPtyLimitedhasmadeeveryefforttosupplytrademarkinformationaboutcompanynames,productsandservicesmentionedinthismanual.Trademarksshownbelowwerederivedfromvarioussources.

CitectSCADA,CitectHMI/SCADA,CitectFacilitiesandCitectSCADABatchareregisiteredtrademarksofCitectPty.Limited.

IBM,IBMPCandIBMPCATareregisteredtrademerksofInternatrionalBusinessMachineCorporation.

MS-DOS,Windows,Windows98,Windows2000,WindowsXPandExcelaretrademarksofMicrosoftCorporation.

dBaseisatrademarkofBorlandInc.

GeneralNotice:

Someproductnamesusedinthismanualareusedforidentificationpurposesonlyandmaybetrademarksoftheirrespectivecompanies.

October2003EditionforCitectSCADAVersion5.5

ManualRevision1.0

TransferringData(Printers,Databases,FilesandOtherApplications) 2


3/51

UsingDevices(Printers,Databases&Files)

ADeviceisautilitythattransfershigh-leveldata(suchasareport,commandlogoralarmlog)betweenCitectHMI/SCADAandotherelements(suchasaprinter,database,RTFfile,orASCIIfile)inyourCitectHMI/SCADAsystem.DevicesaresimilartoI/ODevicesinthattheybothallowCitectHMI/SCADAtoexchangedatawithothercomponentsinyourcontrolandmonitoringsystem.

I/O Device

Citect exchanges plant-floordata with an I/O Device

Inputs Outputsfrom field devices to field devices

Citect

(using a communications

Citect exchanges high-level data using a Device

Device

Inputfrom a

database or

Outputto a printerdatabase or

ASCII file ASCII/RTF file

cable)

YoucanuseDevicesforavarietyofpurposes,forexample,tosendtheoutputofareporttoaprinter,orwritedatatoadatabase.

Citect

Printer

DatabaseDevice

Device

AlarmLog

ShiftReport

UsingaDevice,youcanwritedatato:

RTFfiles

ASCIIfiles

dBASEdatabases

SQLdatabases(throughODBC-compliantdrivers)



4/51

Printers(connectedtoyourCitectHMI/SCADAcomputerornetwork)

YoucanconfigureanynumberofDevices,however,aDeviceisacommonresource.Youcan,forexample,configureasingleDevicethatsendstheoutputofallyourCitectHMI/SCADAreportstoaprinter(whentheyarerequested).

Citect

All reports can usethe same Device

DevicePrinter

RejectReport

ShiftReport

Product

Report

Using Groups of DevicesYoucanaddflexibilitytoyoursystembyusingagroupofDevices.AgroupofDevicesallowsyoutoexportthesamedatatotwo(ormore)locations.

Citect

A group of Devices allows you to export

data to several devices at the same time

Device 1

Printer

ASCII Fi le

RejectReport

ShiftReport

ProductReport

Device 2

Device 3

GROUPOF

DEVICES



5/51

Using Devices to Read DataUsingaDevice(andCicodefunctions),youcanalsoreaddatafrom:

ASCIIfiles

dBASEdatabases

SQLdatabases

Citect

dBaseDatabase

SQLDatabase

With a Device, you can read

and write data to a database

Device

Device

NOTE Whenyoureadfromagroupofdevices,dataisonlyreadfromthefirstdeviceinthegroup.



6/51

ConfiguringDevices

To configure a device:1. FromtheSystemmenuselectDevices

2. CompletetheDevicesform.UsetheHelpbuttonformoreinformationaboutthefields.

3. PresstheAddbuttontoappendarecordyouhavecreated,ortheReplacebuttonifyouhavemodifiedarecord.

Devices PropertiesDeviceshavethefollowingproperties:

Name (16 Chars.)Thenameofthedevice.Thedevicenamecanbethenameofagroupofdevices,oralabelforadevice.

Format (120 Chars.)Specifieshowthedataisformattedinthedevice.TheformatisdeterminedbythetypeofDevice,andthedatathatissenttothedevice.

Ifyouareloggingalarmsorcommandmessages,youmustspecifyaformat,ornodataiswrittentothedevice.

NOTE Thelogdeviceforacommandisspecifiedwhereverthecommandisdefined.ThelogdeviceforanalarmisspecifiedattheAlarmCategoriesform.

Whenproducingreports,theformatisignored.(Theformatdefinedforthereportisusedtowritethereporttothedevice.)

Header (120 Chars.)Additionalinformationforthedevice:

Printer DevicesTheheaderisprintedoneachpage.Anewpageiscreatedeachtimetheformlengthisreached.The[Device]FormLengthparameterisusedtosettheformlength.

ASCII File DevicesDonotusethisproperty.

dBASE Database Devices



7/51

Containsthefieldnameusedtoindexthedatabase,forexample:

Header {Name}

NOTE IndexKeyfieldsmustnotexceed100characters.SQL Database DevicesTheconnectionstringfortheparticulardatabasetype.NOTE CitectHMI/SCADAdatabasedevicesonlysupportSTRINGdatatypes.Ifyouuse

anotherdatabaseeditortomodifyyourdatabase,youmustensurethatallfieldsareinstringformat.

File Name (64 Chars.)Thefilenameofthedevice.

Printer DevicesTheprinterportorUNCname,forexample:

File Name LPT1:

File Name COM2:

File Name \\PrintServer\BubbleJet1

Whenyouspecifyaprinterport,youmustincludethecolon(:),otherwiseCitectHMI/SCADAtriestowritetoafile(Device)withanamesimilartotheprinterport(i.e.LPT1orCOM2).

NOTE WhenusingaUNCnameinWindows95,theprintermustbeinthePrinterssectionoftheControlPanel.

ASCII File Devices and dBASE Database DevicesThenameoftheactivefile,forexample:

File Name ALARMLOG.TXT

File Name [DATA]:ALARMLOG.TXT

Thispropertyisoptional.Ifyoudonotspecifyafilename,File Namedefaultsto\CITECT\BIN\-ontheharddiskwhereyouinstalledCitectHMI/SCADA.isthefirsteightcharactersoftheDeviceName.Ifyouusethisproperty,ensurethatnootherdeviceshavethesamefirsteightcharactersintheDeviceName.

SQL Database DevicesThedatabasetable,forexample:

File Name LOGFILE

File Name REPTBL

Type (16 Chars.)Thetypeofdevice:

Device Type DeviceDescription

ASCII_DEV ASCIIfile*



8/51

Device Type DeviceDescription

PRINTER_DEV Printer

dBASE_DEV dBASEfile

SQL_DEV SQLdatabase

*WhendefiningRTFreportproperties,anASCIIdevicewouldbeselectedifthereportwastobesavedasafile.

Thispropertyisoptional.Ifyoudonotspecifyatype,thedeviceTypeisASCII_DEVunless:Thefilenameisaprinterdevice(LPT1:toLPT4:orCOM1:toCOM4:oraUNCname),whereTypeisPRINTER_DEV,orThefilenameextensionis.DBF,whereType isdBASE_DEV.

No. Files (4 Chars.)Thenumberofhistoryfiles.

Bydefault,CitectHMI/SCADAcreatesasingledatafileforeachdevice.(Thisdatafileiscalledor,dependingwhetherthedeviceisanASCIIdevice

ordatabasedevice.)Thenumberofhistoryfilesyouspecifyhereareinadditiontothedatafile.

IMPORTANT: Ifyoudonotwanthistoryfilescreated,youmustenter0(zero)here,andsetthe[Device]CreateHistoryFilesparameterto0,otherwise,10historyfileswillbecreatedasadefault.Youmustalsoensurethatthedatafileisofafixedsize.(Ifthedataaccumulates,thefileeventuallyfillstheharddisk.)

Ifyouspecify-1thedataisappendedtotheendofonefile.

Ifyouareloggingalarm,keyboardcommands,orreportstothedevice,youshouldspecifythenumberoffilestobecreated,andthetimeofeachfile.

See Also:UsingDeviceHistoryFiles

Time (32 Chars.)Thetimeofdaytosynchronisethebeginningofthehistoryfile,inhh:mm:ss(hours:minutes:seconds).

Ifyouacceptedthedefaultnumberofhistoryfilesabove,andyouspecifyatimeandperiod,10historyfileswillbecreated.

Ifyoudonotspecifyatime,thefileissynchronisedat0:00:00(i.e.midnight).

IfyouomitboththeTime andthePeriod,additionalhistoryfileswillstillbecreated(withthedefaulttimeandperiod).Ifyoudon'twanthistoryfilestobecreated,youmustsetthe[Device]CreateHistoryFilesparameterto0(zero).


Period (32 Chars.)Theperiodofthehistoryfile,inhh:mm:ss(hours:minutes:seconds).Alternativelyyoucan:

Specifyaweeklyperiodbyenteringthedayoftheweekonwhichtostartthehistoryfile,e.g.Monday,Tuesday,Wednesday,etc.

Specifyamonthlyperiodbyenteringthedayofthemonthonwhichtostartthehistoryfile,e.g.1st,2nd,3rd,4th,5th,etc.

Specifyayearlyperiodbyenteringthedayandmonthonwhichtostartthehistoryfile,e.g.1stJanuary,25thFebruary,etc.Thedayandmonthmustbeseparatedbyaspace.

Ifyouacceptedthedefaultnumberofhistoryfilesabove,andyouspecifyatimeandperiod,

10historyfileswillbecreated.Ifyoudonotspecifyaperiod,theperioddefaultstoSunday(weekly).



9/51

IfyouomitboththeTime andthePeriod,additionalhistoryfileswillstillbecreated(withthedefaulttimeandperiod).Ifyoudon'twanthistoryfilestobecreated,youmustsetthe[Device]CreateHistoryFilesparameterto0(zero).


Comment (48 Chars.)Anyusefulcomment.



10/51


11/51

Theformatspecifiesthestructure(fieldnamesandfieldwidths)ofthedatabase.Theformathasthefollowingsyntax:

{, }Youmustusebraces{}toencloseeachfield,forexample:

Format {Tag,8}{Name,32}

Inthiscase,thedatabaseiscreatedwithtwodatabasefields-Tag,with8characters,andName,with32characters.Thesizeofeachdatabasefieldisdeterminedbythewidthyouspecifyintheformat.(Justificationcharacterareignored.)Alldatabasefieldsarecharacter(string)fieldtypes.

Youcandefineyourownfields(aswellasthestandardCitectHMI/SCADAfields)forthedatabasedevice,forexample:

Format {Name,16}{Water,8}{Sugar,8}{Flour,8}{Salt,8}{Yeast,8}{Milk,8}

Thisdatabasedevicehasthefollowingstructure:

Name Water Sugar Flour Salt Yeast Milk

NOTES 1)Donotleaveanyspacesbetweeneachfielddefinitionorattheendoftheformatstring,orCitectHMI/SCADAcreatesextrafieldsforeachspace(inthedevice).2)Youshouldnotspecifyafieldnamelongerthan10characters,orCitectHMI/SCADAtruncatesthenameto10characters(ThedBASEfileformatlimitsallfieldnamestoamaximumof10characters.)

Inthisexample,thedatabaseiscreatedwithsevendatabasefields.ToaccesstheabovedBASEdevice,useaCicodefunctionsimilartothefollowing:

hDev = DevOpen("Recipe");DevFind(hDev, "Name", "Bread");PLC_Water = DevGetField(hDev, "Water");PLC_Sugar = DevGetField(hDev, "Sugar");. . .. . .DevClose(hDev);

dBASE DevicesIfthedatabasedoesnotexist,itiscreatedwiththespecifiedformat.Ifyoudonotspecifyaformat,andifthefilenamespecifiesanexistingdBASEfile,CitectHMI/SCADAusestheexistingfieldsinthedatabase.

SQL DevicesYoumustcreatetheSQLdatabasebyanexternalapplicationbeforeitcanbeused.

NOTE IfyoueditadBASEorSQLdevicerecord(inanexistingproject),theassociatedphysicaldeviceisnotedited.Forexample,ifthedeviceisadBASEtypedeviceandyouaddanextrafieldinthedevice,theextrafieldisnotaddedtoexistingdatabase

files(whenyourunCitectHMI/SCADA).Newfilesarecreatedwiththeeditedfields.Ifyouwanttokeeptheexistingdevicedatabasedata,youmustmanuallycopythedata.



12/51

(UsedBASE,Excelorsomeotherdatabasetool.)Ifyoudon'tneedtokeeptheexistingdata,deletetheexistingdatabasefiles.ThenexttimeCitectHMI/SCADAtriestoopenthedevice,itcreatesthedatabasewiththerequiredchanges.

Using a Database DeviceYoucanaccessadeviceusingCicodefunctions.

Opening the DeviceBeforeyoucanuseadevice,youmustopenit.Youcanopenseveraldevicesatthesametime.TheDevOpen()functionreturnsanintegerhandletoidentifyeachdevice,asinthefollowingexample:

INT hRecipe;

hRecipe = DevOpen("Recipe");

Writing dBASE Records using a CitectHMI/SCADA Database DeviceTowritedatatoadatabasedevice,youmustfirstappendarecordtotheendofthedevice,thenadddatatothefieldsoftherecord.ForadBASEdatabase,theDevAppend()functionappendstherecord,andtheDevSetField()functionwritesdatatoafield.Thefollowingfunctionwritesareciperecordtoadevice:

FUNCTIONWriteRecipeData(INT hDevice, STRING sName, INT Water, INT Sugar, INT Flour, INT Salt, INT Yeast, INT Milk)

DevAppend(hDevice);DevSetField(hDevice, "NAME", sName);

DevSetField(hDevice, "WATER", IntToStr(Water));DevSetField(hDevice, "SUGAR", IntToStr(Sugar));DevSetField(hDevice, "FLOUR", IntToStr(Flour));DevSetField(hDevice, "SALT", IntToStr(Salt));DevSetField(hDevice, "YEAST", IntToStr(Yeast));DevSetField(hDevice, "MILK", IntToStr(Milk));

END

Writing SQL Records using a CitectHMI/SCADA Database DeviceTouseanSQLdeviceinCitectHMI/SCADA,youcannotusealltheCicodeDevicefunctions-youcanonlyusethefollowingfunctions:

DevOpen(),DevClose(),DevGetField(),DevFind(),DevWrite(),DevNext(),DevSeek(),DevAppend(),DevWrite(),DevZap(),DevControl()

TowriteCitectHMI/SCADAdatatoanSQLdatabase,youcanusetheDevWrite()function,butyoumustaddanewrecordandwritetoallfieldsinthenewrecord.Nodataiswrittentothedatabaseifyoudonotwritetoallfields.

Forexample:FUNCTIONWriteRecipeData(INT hDevice, STRING sName, INT Water, INT Sugar, INT Flour, INT Salt, INT Yeast, INT Milk)

DevWrite(hDevice, sName);DevWrite(hDevice, Water);

DevWrite(hDevice, Sugar);DevWrite(hDevice, Flour);



13/51

DevWrite(hDevice, Salt);DevWrite(hDevice, Yeast);DevWrite(hDevice, Milk);

END

ThefollowingfunctionsarenotcompatiblewiththeSQLdevicesandshouldnotbeusedwithaSQLdevices:

DevFlush(),DevPrev(),DevSize(),DevRecNo(),DevDelete(),DevRead(),DevSetField()

Locating and Reading Database Records using a CitectHMI/SCADA Database DeviceToreaddatafromadBASEorSQLdatabasedevice,usetheDevFind()functiontolocatetherecord,andthentheDevGetField()functiontoreadeachfield:

FUNCTIONGetRecipe(STRING sName)

INT hDev;

hDev = DevOpen("Recipe");IF hDev >= 0 THEN

IF DevFind(hDev, sName, "NAME") = 0 THENPLC_Water = DevGetField(hDev, "WATER");PLC_Sugar = DevGetField(hDev, "SUGAR");PLC_Flour = DevGetField(hDev, "FLOUR");PLC_Salt = DevGetField(hDev, "SALT");PLC_Yeast = DevGetField(hDev, "YEAST");PLC_Milk = DevGetField(hDev, "MILK");

ELSEDspError("Cannot Find Recipe " + sName);

ENDDevClose(hDev);

ELSE

DspError("Cannot open recipe database");ENDEND

Deleting Records using a CitectHMI/SCADA Database DeviceYoucandeletedBASErecordswiththeDevDelete()function.ThefollowingCicodefunctiondeletesallrecordsfromadBASEdevice:

FUNCTION DeleteRecords(INT hDev)

WHILE NOT DevEOF(hDev) DODevDelete(hDev);

DevNext(hDev);END

END

TodeleteallrecordsfromadBASEdatabase,usetheDevZap()function:FUNCTION DeleteRecords(INT hDev)

DevZap(hDev);END

NOTE TodeleterecordsfromanSQLdatabase,youmustusetheCicodeSQLfunctions,discussedinUsingSQL.



14/51

Closing a CitectHMI/SCADA Database DeviceWhenyouhavefinishedwithadevice,youshouldcloseittofreeCicodesystemresources.TheDevClose()functionclosesthedevice:

DevClose(hRecipe);

To define a group of devices:1. FromtheSystemmenuselectGroups2. CompletetheGroupsform.UsetheHelpbuttonformoreinformationaboutthefields.3. PresstheAddbuttontoappendarecordyouhavecreated,ortheReplacebuttonifyouhave

modifiedarecord.



15/51

UsingDeviceHistoryFiles

Citectusesasystemofrotationalhistoryfilestostorehistoricaldata.Thismakeslongtermstorageofloggeddataeasiertoorganiseandmoreaccessible.Tousethissystem,youmustspecifyhowmanydevicehistoryfilesyouwanttokeep.Forexample,ifyouwanttokeep10historyfiles,theywouldbesavedrotationallyasillustratedbelow:

TXTFilename

3. At Midnight thefollowing Sunday,Citect renames.001 to.002, and.TXT to.001. Itthen creates a new.TXT.

1. When Citectbegins logging,data is written to afile called.TXT or.DBF(depending on thetype of device).

2. At Midnight thefollowing Sunday,Citect renames.TXT to.001, andcreates a new.TXT.

4. After week 10, thefirst file is overwritten(week 11 in the firstcycle).

3Filename

1Filename

6Filename

5Filename

7Filename

8Filename

9Filename

1Filename

2Filename

4Filename

Notethe10historyfilesareinadditiontothedefaultdatafilethatissavedforalldevices.

Bydefault,CitectHMI/SCADAuses10files(ifhistoryfilesarespecified).Youcanchangethedefaultbyspecifyingthenumberoffilestouse,forexample:

No. Files 20

CommentCitectHMI/SCADA uses twenty files forthe data

Themaximumnumberoffilesyoucanspecifyis999.

Youcanalsospecifytheperiodbetweenfiles,i.e.whenanewhistoryfileisused,forexample:

Period 1:00:00

CommentUse a new file each hour

Period 6:00:00

CommentUse a new file every six hours



16/51

Period 72:00:00

CommentUse a new file every three days

Period Monday

CommentUse a new file each week beginning onMonday

Period 15th

CommentUse a new file every month beginning onthe 15th of each month

Period 25th June

Comment Use a new file every year beginning onthe 25th of June

NOTE Forbestsystemperformance,youshouldspecifyaperiodofatleastoneweek.Youcanalsospecifythetimeofdaytosynchronisethebeginningofthehistoryfile,forexample:

Time 6:00:00

CommentSynchronise the file at 6:00 am

Time 12:00:00

CommentSynchronise the file at 12:00 midday

Time 18:30:00

CommentSynchronise the file at 6:30 pm

Thefirstfiledoesnotactuallybeginatthistime-thefirstfilebeginswhenyoustartyourruntimesystem.Thetimeandperiodtogetherdeterminewhennewhistoryfilesarecreated,forexample:

Time 6:00:00

Period Monday

Intheaboveexample,CitectHMI/SCADAcreatesanewfileeachMondayat6:00am.Ifyoustartyourruntimesystemat7:30amonSunday,yourfirstfileonlycontains22.5hoursofdata.Ifyouleaveyoursystemrunning,subsequentfilesstarteachMondayat6:00am,andcontainonefullweekofdata.

Archiving DataIfyouwanttoarchiveyourdataforlongtermstorage,youmustbackupthehistoryfilesbeforetheyareoverwritten.UsetheWindowsFileManagerfromtheMainprogramgrouptocheckfilecreation

dates(ofthehistoryfiles)andtobackupfiles.RefertoyourWindowsdocumentationforafulldescriptionoftheFileManager.



17/51

CommandFields

Youcanuseanyofthefollowingfields(orcombinationoffields)toformatacommandloggingdevice:

Field Name Descript ion

{UserName,n} Thenameoftheuser(UserName)whowasloggedonwhenthecommandwasissued.

{FullName,n} Thefullnameoftheuser(FullName)whowasloggedonwhenthecommandwasissued.

{Time,n} Thetime(inshortformat)whenthecommandwasissued(hh:mm).

{TimeLong,n} Thetime(inlongformat)whenthecommandwasissued(hh:mm:ss).

{Date,n} Thedate(inshortformat)whenthecommandwasissued(dd:mm:yy).

{DateLong,n} Thedate(inlongformat)whenthecommandwasissued(daymonthyear).

{DateExt,n} Thedate(inextendedformat)whenthecommandwasissued(dd:mm:yyyy).

{Page,n} Thepagethatwasdisplayedwhenthecommandwasissued.

{MsgLog,n} ThemessagesentastheMessageLogproperty(ofthecommandrecord).

Youcanusethefollowingfields(inthecommandfield)forKeyboardcommands only:{Arg1,n} Thefirstkeyboardcommandargument(ifany).

{Arg2,n} Thesecondkeyboardcommandargument(ifany).

... {Arg8,n} Theeighthkeyboardcommandargument(ifany).

{Native_MsgLog,n} ThenativelanguageversionofthemessagesentastheMessageLogproperty(ofthecommandrecord).

Wherenspecifiesthedisplayfieldsize.

Forexample,youcouldhaveaDeviceconfiguredasfollows:

Name KeyLog

Format{Date,9}{MsgLog,27}{Arg1,3}by{FullName,11}

Thenakeyboardcommand(object,page,orsystem)couldbecreatedwiththefollowingconfiguration:

Log Device KeyLog

Key Sequence### ENTER

Log MessageDensity setpoint changed to

Resultinginanoutputofthefollowingkind:"01/01/99Densitysetpointchangedto123byHenryChang".



18/51

AboutPrintManagement

TheWindowsprintermanagementhasbeendesignedforpage-basedprinters,e.g.laserprintersandsharednetworkprinters.Theprinterdriverdoesnotprintanythingontheprinteruntiltheentirepageiscomplete-itthenprintsthepage.Thisisthepreferredprintingmethod(whenprintersaresharedonanetwork),becauseitpreventsconflictofdatawhenmorethanoneoperatorusesthe

printfacilityatthesametime.

However,thismethodisnotappropriatewhenyouareloggingalarmsorkeyboardcommands.Ifyousendalarmloggingtothistypeofprinter,CitectHMI/SCADAflushesthedatatotheprinterwhenthecurrentpageisfull,orwhenthe[DEVICE]FlushTimeparameterhasbeenexceeded(itdefaultsto10seconds).If,forexample,youhaveonealarmoccurringeachminute,eachalarmisprintedonanewpage(becausethedefaultflushtimeislessthanthealarmfrequency).

YoucanbypasstheWindowsprintmanagementbywritingtheoutputtoafile.SetthedevicetypetoASCII_DEVandspecifythefilenameasLPT1.DOS,LPT2.DOSorLPT3.DOS(dependingontheporttowhichyourprinterisconnected).Theprintermustbeeitheronalocalport,oracapturednetworkprinter.Whenyoulogtothisdevice,thedataisprintedimmediatelyontheprinterwithnoextraformfeeds.

Forcorrectloggingoperation,youshouldreserveoneprintertobeyourloggingprinter.Thisprintershouldbealocalprinter-notonthenetworkserver.Youcanthensendanyothernon-loggingprintouts,(e.g.reports)toasharednetworkorlocalprinter.



19/51

ExchangingDatawithOtherApplications

YoucantransferdatabetweenCitectHMI/SCADAandawiderangeofsoftwareapplicationsforstorage,analysis,andpostprocessing,ortocontrolandtuneyourCitectHMI/SCADAsystem.

CitectHMI/SCADAprovidesthefollowingmethodsforexchangingdatadirectlywithother

applications: Dynamic Data Exchange(DDE),whereCitectHMI/SCADAcanactasa:

-DDE Serverprovidingtagvaluestorequestingclients,or-DDE Clienttorequestdatafromotherapplications.

Open Database Connectivity(ODBC),whereCitectHMI/SCADAfunctionsasanODBCserver,allowingotherapplicationstoreadCitectHMI/SCADAvariablesdirectly.

Byusingacommonexternal database,whereCitectHMI/SCADAandotherapplicationsusethesamedatabasetostoreandshareinformation.

NOTE: CitectHMI/SCADAalsosupportsimportingandlinkingvariabletagdatafromexternaldatabases.SeeLinking,Importing,andExportingTags.



20/51

UsingDDE(DynamicDataExchange)

MicrosoftWindowsDDEallowsthecontinuousandautomaticexchangeofdatabetweendifferentWindowsapplicationsonthesamemachinewithouttheneedforanyuserintervention.Forexample,yourcompany'sProductiongroupmightuseaspreadsheetapplicationtographicallyrepresentplant-floordata(productoutput).Thiscouldbedynamicallyupdatedwiththelatestlive

datausingDDEtoreadvaluesdirectlyfromCitectHMI/SCADA.

WindowsDDEusestheDDEprotocoltosendmessagesbetweenapplicationsthatsharedata.

DynamicDataExchangeoccursbetweenaDDE Clientapplication(whichrequeststhedataorservice)andaDDE Serverapplication(whichprovidesthedataorservice).TheDDEClientstartstheexchangebyestablishingaconversationwiththeDDEServer,andrequestingdataorservices.TheDDEServerrespondstotheserequestsbyprovidingthedataorservicestotheDDEClient.TheDDEClientterminatestheconversationwhenitnolongerneedstheDDEServer'sdataorservices.

NOTE: AstheDDEprotocolisnotdesignedforhigh-speeddatatransfer,theuseofDDEisonlyappropriatewhendatacommunicationspeedisnotcritical.

ForinformationaboutDDEconversations,seeDDEConversationsandSyntax.

ToestablishaDDEconversationbetweenapplicationsonthesamecomputer,seeSettingupDDEconversations.

ToestablishDDEconversationsbetweenapplicationsrunningondifferentcomputersoverthesamenetwork,seeNetworkDDE.

ToestablishDDEConversationswiththeCitectHMI/SCADAtagdatabasedirectly,seeConnectingtotheCitectHMI/SCADAtagdatabaseusingDDE.

IMPORTANT:WhenreadingorwritingtoCitectHMI/SCADAtagsusingDDE,youmayunknowinglyaddtoyourCitectHMI/SCADALicencepointcount.Oncethistallyreachesacertainlimit,CitectHMI/SCADAwillnolongerfunctioncorrectly.ThereforewhenaccessingtagsviaDDE,it'simportanttoremainawareofhowmanypointsyouhaveused.ForfurtherinformationseeCitectHMI/SCADALicencePointCount.

DDE Conversations and Client SyntaxTwoapplicationsparticipatinginDynamicDataExchangearesaidtobeengagedinaDDEconversation.TheapplicationthatinitiatestheconversationistheDDE Client,andtheapplicationthatrespondstotheDDEClientistheDDE Server.AnapplicationcanhaveseveralDDEconversationsrunningatthesametime.TheapplicationcanbetheDDEClientinsomeconversations(requestingdataorservices),andtheDDEServer(thedata/serviceprovider)inothers.EachrequestorresponseinaDDEconversation specifiesthedataorservicetobesentorreceived.

NOTE: ADDEconversationissometimesreferredtoasachannel oralink.ThesyntaxsentbytheDDEClientwhenittriestoestablishaDDEconversationwiththeDDEServer,consistsofthreeparts:

thenameoftheapplicationtoretrievethedatafrom;

thefileortopicnamewhichcontainsthedatatoberetrieved;



21/51

andthecellrange,value,field,ordataitemthat'sbeingrequested.

Thesearecombinedintheformat:

| where:

identifiestheDDEServerapplication.|(pipecharacter)separatestheDDEServerapplicationnamefromtheDDETopicNamewithnospacesbetweenthem.

identifiesthecontextofthedata.ForDDEServersthatoperateonfile-baseddocuments,DDEtopicnamesaretypicallyfilenames.ForotherDDEServers,theyareotherDDEapplication-specificstrings.

(exclamationcharacter)separatestheDDETopicNamefromtheDDEDataitemnamewithnospaces.

isastringthatidentifiesthedataitemthataDDEServercanpasstoaDDEClientduringaDDEtransaction.Insomeinstances,theDDEDataitemnameisoptional.RefertotheDDEapplicationdocumentationforparticulars.

NOTE: IntheDDEClientsyntaxstructureexampleabove,everyplaceholdershowninsidearrowbrackets()shouldbereplacedwiththeactualnameoftheitemthatitdescribes.Thearrowbracketsandtheplaceholderwordstheycontainshouldnotbeincludedinthestatement,andareshownhereonlyforyourinformation.

AstheDDEprotocolwasdesignedinanerabeforelongfilenames,DDEonlysupportstheuseofshort(8character)filenames.Toovercomethislimitation,enclosethethreepartsoftheDDEsyntaxwithinsinglequotesrespectively.Forexample:

Citect| Variable!'Process Variable 1'

ThisinstructsDDEtotreatthecharacterswithinthequotesasstrings,thuspermittingthemtocontainlongfilenames,thespacecharacter(),thepipecharacter(|),theexclamationorbangcharacter(),oranyothernonalphanumericcharacter.

Setting up DDE ConversationsTheDDEprotocolitselfdoesnotsupportthelaunchofapplications,soboththeDDEClientapplicationandtheDDEServerapplicationmustalreadyberunningbeforeanyDDEconversationscanoccur(unlessthecallingapplicationiscodedtodetectandlaunchtheDDEServerapplicationwhenrequired).

AtthebeginningofaDDEconversation,aDDEClientrequeststheservicesofaDDEServerusingDDEClientsyntax(whichcontainstheDDEServerapplicationname,topicorfilename,andthedataitemnameintherequest).ForDDEClientsyntaxdetails,seeDDEConversationsandClientSyntax.

Toset-upanapplicationasaDDEClient,thatis,torequestdatafromaDDEServerapplication,youneedtouseappropriatevaluesintheDDEClientsyntaxasfollows:

DDE Server application nameTheDDEServernameisusuallytheDDEServerapplicationname,e.g.theDDEServernameforCitectHMI/SCADAis"Citect",theDDEServernameforMicrosoftExcelis"Excel",theDDEServernameforMicrosoftWordis"WinWord",andtheDDEServernameforMicrosoftAccessis"MSAccess".MostDDEServersrespondtoonlyonename.



22/51

DDE Topic nameTheDDETopicnameforCitectHMI/SCADAiseither"Data"(ifyouusetheCicodeDDEfunctions)or"Variable"(ifyouuseCitectHMI/SCADAastheDDEServerandwishtoaccessthevariabletagdatabasedirectly).TheDDETopicnameforMicrosoftExcelisthenameoftheworksheet(whichmayalsoincludetheworkbooknameenclosedinsquarebrackets).TheDDETopicnameforMicrosoftWordisthedocumentname.TheDDETopicnameforMicrosoftAccessistheDatabasenameandTablename,QuerynameoranSQLstringasdetailedinthefollowingnote:

NOTE: TheproperDDEClientsyntaxoftheDDETopicnamesectionforaccessingaMicrosoftAccessdatabaseisconstructedfromthefollowingstructure: "; TABLE ".TheplaceholderisforthenameoftheAccessdatabasefilefollowedbyasemicolon(;).Itmaybenecessarytoincludethefilepath,howeverthismaynotbethecase(i.e.ifitisknownthatAccesswillberunningwiththetargetfileopen).The.MDBsuffixisoptional(as.MDBisthedefaultsuffixforAccessdatabases),unlessthefullpathwasincluded.

TheTABLE isthecommandstringtoinstructAccesswhichtabledatayouintendtoconversewith.DDEalsosupportstheuseofQUERY orSQL inplaceofTABLE .Theuseofthesemi-colon(;)afterthe''placeholder,andtheuseofUPPERCASEforthe'TABLE','QUERY',and'SQL'commandsintheDDEstringsyntaxarerequired.Thewholesectionmustbeenclosedinquotes( ").SeeReadingDatafromanAccessTablewithDDEandWritingDatatoanAccessTablewithDDE.

DDE Data item name

TheDDEDataitemnameforCitectHMI/SCADAdependsupontheDDETopicnamebeingused.Whenusing'Variable'astheDDETopicnametoaccessthevariabletagdatabasedirectly,theDDEDataitemnameistheCitectHMI/SCADAvariabletagname.Whenusing'Data'astheDDETopicnametoaccessavaluepostedusingtheCicodeDDEPost()function,theDDEDataitemnameisthepostedname.

TheDDEDataitemnameforMicrosoftExcelisthecellrangeinRownumberColumnnumberformat(e.g.R1C1).TheDDEDataitemnameforMicrosoftWordisabookmarkname.TheDDEDataitemnameforMicrosoftAccessisdependantuponwhichtopicnamewasused.SeetheMicrosoftAccessHelpfordetails.

NOTE: TheseCitectHMI/SCADADDEhelptopicsandexampleswereoriginallywrittenforWindows3.xxandsubsequentlyupdatedforOffice95onWindows95.Microsofthas

sinceintroducedsecuritymeasureswithOffice2000andlaterversionswhich,bydefault,blockOfficeapplicationsfrombeingDDEClients.Forsecuritydetails,seeUsingDDEwithMicrosoftOfficeApplications.

CitectHMI/SCADAcanperformasbothaDDEServerandasaDDEClientasrequired.TosetupCitectHMI/SCADAtouseDDE,seeExchangingCitectHMI/SCADADataThroughDDE.

CitectHMI/SCADAcomeswithanExcelworkbookfilewhichcontainsmacrostohelpyouinsertcorrectDDEClientsyntaxlinksfromyourCitectHMI/SCADAruntimeprojecttagdatabasedirectlyintoanExcelworksheet.SeeUsingthe'CitectTags'Excelmacros.



23/51

CitectHMI/SCADA DDE Function TypesTherearetwoclassesofDDEfunctionsinCicode,theoriginalDDEfunctionsandthelaterDDEhfunctions.

DDE FunctionsTheoriginalCicodeDDEfunctionsdonotreturnaDDEChannelNumberandweredesignedtoinsulatetheuserfromtheneedtomanageDDEChannels.TheDDERead(),DDEPost(),DDEWrite(),andDDEExec()functionseachperformasingleexchangeofdata.EachofthesefunctionsstartsaDDEconversationwiththeexternalapplication,sendsorreceivesthedata(orcommand),andendstheconversation-allinoneoperation.

DDEh FunctionsTheCicodeDDEhfunctionswereintroducedtoaffordmorecontroloverDDEcommunications,especiallyforNetworkDDEandforcircumstanceswhereitisnecessarytoexplicitlyterminateandre-initiateaDDEChannel(afterdeletingrowsfromatableforexample).

TheDDEhandle(DDEh...)functionsreturnahandletotheconversation-aDDEchannelnumber.

NOTE: YoushouldusetheDDEhhandlefunctionsforNetworkDDE,andforAccessDDE.

Exchanging CitectHMI/SCADA data through DDECitectHMI/SCADAruntimecanexchangedataasaDDEServeroraDDEClient.

CitectHMI/SCADAbehavesasaDDE Serverwhenprovidingotherapplicationswithaccesstoitsdata.WhenactingasaDDEServer,CitectHMI/SCADAruntimecan:

provideDDEaccesstothecompletevariabletagdatabaseautomaticallywithnofurthersetuprequired provideaccesstoselectedvariablevaluesbypostingselectCitectHMI/SCADAdatausing

DDE

CitectHMI/SCADAbehavesasaDDE Clientwhenrequestingotherapplicationstoprovideaccesstotheirdata.WhenactingasaDDEClient,CitectHMI/SCADAruntimecan:

readdatadirectlyfromanotherapplication

writedatadirectlytoanotherapplication

NOTE: YoucanalsoexecutecommandsinanotherapplicationfromCitectHMI/SCADAwiththeDDEExec()function.Similarly,youcanrunCicodefunctionsfromanother

applicationbypassingthefunctionsthroughthatapplication'sDDEExecutecommand.

Connecting to the CitectHMI/SCADA tag database using DDECitectHMI/SCADAruntimebehavesasaDDEServerandautomaticallyprovidesDDEaccesstothecompletevariabletagdatabasewithnofurthersetuprequired.

TocreateDDElinkstotheCitectHMI/SCADAvariabletags,usetheDDEClientsyntax.Forsyntaxdetails,seeDDEConversationsandClientSyntax.

IntheDDEClientcall,theDDEApplicationnamemustbe"Citect",theDDETopicnamemustbe

"Variable",andtheDDEDataitemnamemustbetheCitectHMI/SCADAtagname.



24/51

Forinstance,thePV1tagvaluecanbeaccessedfromacellinExcelcontainingthefollowingformula:

=Citect| Variable!PV1

IftheCitectHMI/SCADAvariabletagnamecontainsspacesornonalphanumericcharacters,the

DDEdataitemsectionoftheDDEClientcallsyntaxmustbeenclosedwithinsinglequotes.Forexample:=Citect| Variable!'Process Variable 1'

CitectHMI/SCADAruntimeandtheDDEClientapplication(e.g.Excel)mustbothberunningonthesamecomputer.ForinformationaboutDDEconversations,seeDDEConversationsandSyntax.

ToestablishaDDEconversationbetweenapplicationsonthesamecomputer,seeSettingupDDEconversations.

ToestablishDDEconversationsbetweenapplicationsrunningondifferentcomputersoverthe

samenetwork,seeNetworkDDE.

Posting select CitectHMI/SCADA data using DDEYoumayhaveatagnamingconventionwhichisnotDDEcompatible,orforwhateverreasonisinnappropriateforuseinaDDEcall.CitectHMI/SCADAprovidestheabilitytopublishspecifictagsunderdifferentnamesinDDE.ThisinvolvesusingtheDDEpostfunction.

TomakeselectedCitectHMI/SCADAvariablevaluesortheresultsofcalculationsavailabletoexternalDDEClientapplicationscurrentlyrunningonthesamecomputer,usetheCicodeDDEPost()functiontohaveCitectHMI/SCADAruntimebehaveasaDDEServer.

Thisconversationisone-way,whichallowsanexternalDDEClientapplication(likeExcel,Word,etc.)toreadthevaluefromCitectHMI/SCADAusingDDE.TheClientapplicationcannotchangethisvalueinCitectHMI/SCADA.

Youcanusethisfunctiontopresentdataunderadifferentnamethanitssource.Forinstance,thefollowingexamplepresentsthevalueofvariabletagPV1as"Process1".

ThefollowingCicodeexamplepoststhevalueofvariablePV1usingDDE:DDEPost("Process1", PV1)

Onceposted,thisvaluecanbeaccessed,forexample,fromacellinExcelcontainingthefollowingformula:

=Citec t| Data!Process1

orfromafieldinMicrosoftWordcontainingthefollowingfunction:{DDEAuto C itect Data Process1 }

NOTES: 1) Thenameofthepostedvalue(e.g.Process1)mustnotexceed8charactersorcontainspacesifyouwanttolinktoitviaaMicrosoftWordDDEfield.MicrosoftExcel,however,acceptslongdataitemnamesifenclosedwithinsinglequotes(e.g. 'Process

Variable1').



25/51

2) YoumustuseDataastheDDETopicnamewhenaccessingpostedvalues.SeeSettingupDDEconversations.

ThismethodofDDEconnectionrequiresthatbothCitectHMI/SCADAruntimeandtheDDEClientapplication(e.g.ExcelorWord)arerunningonthesamecomputeratthesametime.OncetheDDEconnectionhasbeenmade,theDDEClientwouldnormallydisplaytheupdatedvalueoftheCitectHMI/SCADADDEpostingassoonasitbecomesavailable,usuallywithinmillisecondsofthe

post.

Unfortunately,thispostingmethodofDDElinkingissubjecttobreakagewheneverCitectHMI/SCADAruntimeisclosed,evenifCitectHMI/SCADAruntimeissubsequentlyrestarted.TheDDEClientapplicationmaynotdetectthebreak,asupdatestothedataintheDDEClient(e.g.Excel)onlyoccuraftereachpostbytheDDEServer(CitectHMI/SCADAruntime).Ifnofurtherpostsoccur,andinthisscenariononewill(astheDDElinkisbroken),theDDEClientapplicationreceivesnoupdate,andsubsequentlymaydisplaydatawhichcouldbeoutofdate.ThisbrokenstatewillremainuntiltheDDElinkintheDDEClientapplicationisrefreshedortheDDEClientapplicationisrestarted.

Writing Values to a DDE ApplicationTowriteaCitectHMI/SCADAvariablevaluedirectlytoanexternalDDEServerapplicationcurrentlyrunningonthesamecomputerasCitectHMI/SCADA,usetheCicodeDDEWrite()function.

Forexample,writingdatafromCitectHMI/SCADAtoaMicrosoftOfficeApplication(usingCitectHMI/SCADAastheDDEClientandtheOfficeapplicationastheDDEServer),couldbedoneusingthefollowingCicodeDDEWrite()functionexamples:

! Write PV1 to Excel! Assumes the existence of Sheet1DDEWrite("Excel", "Sheet1", "R1C1", PV1);

! Write PV1 to Word! Assumes the existence of TestDDE.doc already loaded in Word! containing the bookmark named TagPV1DDEWrite("Word", "TestDDE", "TagPV1", PV1);

! Note that Access does not support direct DDE writes.

ThisDDEfunctionisone-way,sotoupdatethetagvalueintheremoteDDEServerapplication,thisfunctionwillneedtobecalledeverytimethevalueofthisCitectHMI/SCADAvariablechanges.

WritingdirectlytoaDDEServerassumesapriorknowledgeoftheDDEServer.Intheaboveexample,thespreadsheetordocumentmustexistandExcelorWord(asappropriate)mustberunningfortheDDEcommunicationtobesuccessful.

NOTES: 1)InsteadofusingtheonceonlyDDEWrite(),youcouldusethemultipleuseDDEhandlefunctionDDEhPoke()..2)Ensurethatremoterequestsareenabledintheotherapplication.Forexample,inExcel,youmustensuretheIgnore Remote Requestscheckboxiscleared(thedefaultsetting).InExcel4,usetheOptions|Workspacecommand,orinExcel5andlater,useTools|Options|General.3)TheHighsecuritysetting(ifselected)onMicrosoftOffice2000andlaterversionsdoesnotappeartoaffecttheuseofremoteDDEClientrequestswiththoseOfficeapplications.SeeUsingDDEwithMicrosoftOfficeApplications.



26/51

Reading Values from a DDE ApplicationToreadavalueintoaCitectHMI/SCADAvariabledirectlyfromanexternalDDEServerapplicationcurrentlyrunningonthesamecomputerasCitectHMI/SCADA,usetheCicodeDDERead()function.Forexample:

PV1 = DDERead("Excel", "[Book1]Sheet1", R1C1);

ThedatafromRow1,Column1onSheet1ofBook1inExcelisreadandstoredintheCitectHMI/SCADAvariable"PV1".ThisDDEfunctionisone-way,andwillneedtobecalledwheneverthevalueneedstobeupdatedinCitectHMI/SCADA.

ReadingfromaDDEServerassumesapriorknowledgeoftheDDEServer.Intheaboveexample,Excelmustberunningandtheappropriatelynamedspreadsheetmustexist.TheCitectHMI/SCADAvariablePV1mustalsohavebeenpreviouslydeclared.

NOTES: 1)InsteadofusingtheonceonlyDDERead(),youcouldusethemultipleuseDDEhandlefunctionDDEhRequest().

2)Ensurethatremoterequestsareenabledintheotherapplication.Forexample,inExcel,youmustensuretheIgnore Remote Requestscheckboxiscleared(thedefaultsetting).InExcel4,usetheOptions|Workspacecommand,orinExcel5andlater,useTools|Options|General.3)TheHighsecuritysetting(ifselected)onMicrosoftOffice2000andlaterversionsdoesnotappeartoaffecttheuseofremoteDDEClientrequestswiththoseOfficeapplications.SeeUsingDDEwithMicrosoftOfficeApplications.

Using DDE with Microsoft Office applicationsMicrosofthasintroducedsecuritymeasureswithOffice2000andlaterversionswhich,bydefault,blockOfficeapplicationsfrombeingDDEClients.SeeMicrosoftOfficeSecurity.

MicrosoftOfficeapplicationsappeartosupportvaryingdegreesoflongfilenameswithDDE.SeeLongFileNamesinDDE.

ToenableDDEremoterequestsinMicrosoftExcel,youmustensuretheIgnore Remote Requestscheckboxiscleared(thedefaultsetting).InExcel4,usetheOptions|Workspacecommand,orinExcel5andlater,useTools|Options|General.Long File Names in DDEAccordingtoMSDNKnowledgeBasearticleQ109397, DDEdoesnotsupportlongfilenames,soDOSaliasnamesmustbeusedfordirectoryandfilenameslongerthaneightcharacters(i.e.C:\mydocu~1\file.mdb).

DifferentMicrosoftOfficeapplicationsdifferintheirsupportfortheuseoflongfilenameswhenusedasDDEClients.Forinstance,MicrosoftWorddoesnotappeartosupporttheuseofDDEdataitemnameswhichexceed8characters,whilstMicrosoftExcelhowever,acceptslongdataitemnamesifenclosedwithinsinglequotes.SeepostingselectCitectHMI/SCADAdatausingDDEforanexample.

Microsoft Office SecurityIntheinterestsofdatasecurity,MicrosoftOffice2000andlaterversionshavetheirsecuritysettings

settohighbydefault.TovieworchangeyoursecuritylevelinExcelorWord,ontheToolsmenu,pointtoMacro,clickSecurity,andclicktheSecurity Leveltab.



27/51


28/51

NetworkDDE

NetworkDDEisaversionoftheDDEprotocolforuseacrossanetwork.ForinformationaboutDDE,seeUsingDDE(DynamicDataExchange).FordetailsaboutsettingupCitectHMI/SCADAtouseDDE,seeExchangingCitectHMI/SCADADataThroughDDE.

JustliketheestablishmentofaDDEconversationbetweenapplicationsrunningonthesamecomputer,anetworkDDEconversationusesthesameDDEprotocol,however,sharesdatabetweenapplicationsrunningonseparatecomputersconnectedtoacommonnetwork.

NetworkDDEisaWindowsServiceusedtoinitiateandmaintainthenetworkconnections,security,andsharedfilespaceneededforusingDDEoveranetwork,andmustberunningonbothcomputersatthesametime.Forstartupdetails,seeStartingNetworkDDEServices.

ANetwork DDE Trusted Share mustbemanuallycreatedfortheNetworkDDEServerapplicationontheNetworkDDEServerapplicationmachine.ThisinstructstheNetworkDDEService(ontheDDEServerapplicationmachine),astowhichapplicationandtopictoconnectwith.ItisthissharenamewhichtheNetworkDDEClientapplicationcansubsequentlycommunicatewith.Fordetails,seeSetting-upNetworkDDEShares.

TheNetworkDDEClientstartstheNetworkDDEconversationbyconnectingtotheNetworkDDEShareontheNetworkDDEServercomputer.Fordetails,seeUsingNetworkDDE.

Starting Network DDE ServicesForNetworkDDEtofunction,NetDDE.EXEmustbeinstalledandrunningonbothmachinesbeforeattemptingtoconductaNetworkDDEconversation.NetDDE.exeisaWindowsServicesystemfileshippedwithallversionsofWindowsfrom(andincluding)WindowsForWorkGroups(WFWG)Version3.11,andisusedtocommunicatetheshareddynamicdataexchangeusedbyNetworkDDE.NetDDE.EXEhasnographicaluserinterface(itrunsasabackgroundWindowsservice).

MicrosoftdisabledtheautomaticstartupoftheNetworkDDEServicesinallWindowsOperatingSystemsshippedafterversion3.1,sothereforewithWFWG,WIN9x,WindowsNT,andlaterversions,itisnecessarytoinitiatetheautomaticactivationofNetworkDDEServices,ormanuallyrunNetDDE.EXEonbothmachinesbeforeattemptingconnection.

To manually start Network DDE services: OntheWindowsStartmenu,clickStart|Run,typein"netdde"(withoutthequotes)andpress

theEnterkey.Dosoonbothmachines.

To automatically start the Network DDE Services on machine startup: WithWFWGandWindows9xsystems,storeashortcuttoNetDDE.EXE(locatedinthe

Windowsdirectory)intheWindowsStartupfolder.

WithWindowsNTbasedsystems(NT4,WIN2000,andlater),usetheWindowsServicesManager(selectStart |Control Panel |Administrative Tools |Services)tosettheNetwork DDEservicefromManualtoAutomatic.Todoso,right-clickontheserviceandselectPropertiesfromthepop-upmenu.OntheGeneraltabselectAutomaticfromthedrop-downlistoftheStartup typefield.ClickOK.Closeallwindowsandrestartthemachine.

To verify that the NetDDE Services are running: TheWindowsTaskManagerlistsNetDDE.exewhenrunning.ToviewtheWindowsTask

Manager,pressCTRL+ALT+DEL.WIN9xsystemsdisplayNetDDE.exeintheapplicationslist,



29/51

whilstNTbasedsystems(NT4,WIN2000,andlater)displayitontheProcessestab. InWindowsNTbasedsystems,theServiceAdministrativeToolsalsoliststhestatusof

NetworkDDEandNetworkDDEDSDM.ToviewtheWindowsServicesManager,selectStart|Settings|Control Panel |Administrative Tools |Services.

NOTE: IfyouareusingonlytheMicrosoftClientServiceforNetWareNetworks,theNWIPX/SPX/NetBIOScompatibleprotocolmustbeenabledforNetDDE.exetoload.

Known NetDDE Configuration ProblemsMicrosofthasidentifiedconfigurationproblemswithparticularversionsofNetDDErunningunderparticularWindowsOperatingSystems.IfyouarehavingdifficultiescommunicatingusingNetDDE,thefollowinglistedMicrosoftDeveloperNetwork(MSDN)knowledgebasearticlesmayassisttoresolvetheproblem.

Q231337 - Netdde.exe Does Not Relay WM_DDE_TERMINATE to Remote ClientsApplies to:MicrosoftWindowsNTServerversion4.0,TerminalServerEdition

NTServerversions4.0SP4,4.0SP5

NTWorkstationversions4.0SP4,4.0SP5

NTServer,EnterpriseEditionversions4.0SP4,4.0SP5

Description:CausestheclienttoneverreceiveWM_DDE_TERMINATE,withtheundesirableeffectofleavingchildwindowsorphaned.

Fix:ResolvedinWindowsNTServerversion4.0ServicePack6,andTerminalServerEditionServicePack6.

Q244056 - Netdde.exe Stops Responding When Used from a ServiceApplies to:AllversionsofNT4.

Description:TheNetdde.exeservicemaydeadlockwhenusedtocommunicatebetweenaWindowsNTserviceandaninteractiveapplicationonthesamemachine.

Fix:AhotfixisavailablefromMicrosoftProductSupportServices.

Q272485 - NetDDE Client Is Unable to Connect to NetDDE Server on First AttemptApplies to:MicrosoftWindows2000Professional,Server,andAdvancedServer

Description:Itmayappeartoconnectsuccessfully,andDdeConnectdoesnotfail.However,whenyoutrytogetorputdata,theremaybenoresponsefromtheserver.

Fix:ResolvedinWindows2000ServicePack2.

Q290701 - Heap Damage in Netdde.exeApplies to :MicrosoftWindows2000Professional,Server,andAdvancedServer.

Description:AraceconditionoccurringintheNetDDEterminationroutinecancausememoryheap



30/51

damagetooccurinNetDDE.exe.

Fix:ResolvedinWindows2000ServicePack2.

To test that Network DDE is operational between two machines on the same networkMicrosoftWindowsshipswithanetworkDDEapplicationcalledChat.Itisinstalledtothesystem32folderonWindowsNTbasedsystems.

1. OntheWindowsStartmenu,clickStart|Run,typein"winchat"(withoutthequotes)andpresstheEnterkey.Dosoonbothmachines.

2. Ononemachine,selecttheChatmenuConversation|Dialorclickthedialbutton.TheSelectComputerdialogwilldisplay.3. Selecttheothercomputerfromthelist,andclickOK.Chatwillattempttoestablishanetwork

DDEconversationbetweenthecomputers.

NOTE: IfChatisnotalreadyrunningontheothercomputer,ittimes-outandstatesthattheothercomputerdidn'tanswer.Ifhowever,theothercomputerisalreadyrunningChat,

itwillkeepdiallinguntilanswered.4. Ontheothermachine,(whilstitisbeingdialled),selecttheChatmenuConversation|Answer

orclicktheanswerbutton.TypeinamessageanditwilldisplayintheChatwindowontheothermachine.Theconversationwillcontinueuntileithermachinehangsup.

OnceaChatconversationisestablished,itprovesthatbothmachinesareproperlyset-upandcapableofhandlingnetworkDDEconversations.YoucanviewthesharepropertiesforChat$byusingtheDDEShares.exeapplicationasdescribedinSetting-upNetworkDDEShares.

Youdon'thavetorunChattouseNetworkDDEwithCitectHMI/SCADA.ThisNetworkDDEtesttopicusesChatonlyasanexampletoproveNetworkDDEfunctionalitybetweentwomachines.OnceyouhaveestablishedthatNetworkDDEisfunctional,closetheChatwindows,createtheNetwork DDE Trusted Share foryourNetworkDDEServerapplication,andconnecttotheshareusingNetworkDDE.SeeHowtoconnecttoaNetworkDDEsharedapplication.

Setting-up Network DDE SharesTobeabletocreateaDDElinkoveranetwork,thecomputerservingastheNetworkDDEServermustbesetuptoprovideaNetworkDDE SharetoestablishanetworkDDEChannel.

NOTE: Youdon'thavetocreateaDDEShareifyouareattemptingtouseDDEbetweenapplicationsrunningonthesamemachine.YouonlyhavetocreateaDDEShareifyouintendtouseDDEbetweentwoseparateapplicationsrunningondifferent

machines.ThenyouonlyhavetocreatetheDDEShareonthemachinethatcontainstheapplicationwhichwillbetheDDEServer.

TheWindowsDDESHARE.EXEutilityenablesuserstomanageDDEshares.The32-bitversionisshippedwithallMicrosoftNTbasedoperatingsystems(NTx,Windows2000,WindowsXP,andlater),locatedintheWINNT\System32sub-directory.

NOTE: For16-bitbasedsystemslikeWindows95,Windows98,WindowsMe,andWindowsForWorkgroups,(accordingtoMSDNKnowledgeBasearticleQ181946)theoriginal16-bitNetworkDDEShareManagerversion,(alsonamedDDEShare.exe)canbefoundintheMicrosoftWindowsforWorkgroupsResourceKit.Asthisfileprovedmostdifficulttolocate,andforyourconvenience,acopyisalsoavailablefromtheCitectwebsitetoolbox:www.citect.com\login



31/51


32/51

variabletagdatabaseforsuitableDDElinking,usetheword"Variable"astheDDEShareTopicname.

NOTE: Thetrailingdollarsign($)isrequiredaspartoftheDDEsharenamesyntax.

To create a DDE Share1. OntheDDESharesdialog,clickthe'Add a Share'button.TheDDE Shares Propertiesdialog

displays.Completethefieldsexactlyasdisplayedbelow:

{bmlDDESharePropertiesDialog.bmp}

2. ClickthePermissionsbutton.TheDDE Share Name Permissionsdialogdisplays.

Read and Linkisthedefaultpermissionsetting.ShouldyouwishtowritedatatotheDDEShareapplication,youshouldchangethepermissiontoFull Control.

3. ClickOKtosavethePermission,andreturntotheDDE Shares Propertiesdialog.4. ClickOKtosavetheShare,andreturntotheDDE Sharesdialog.



33/51

DDE Trusted SharesWhenanetworkDDEClientuserconnectstoanetworkDDESharefromaremotecomputer,NetworkDDEacceptstherequestonlyifboth:

theuserwhocreatedthesharehasgrantedtrustedstatustotheshare,and

theuserwhocreatedtheshareiscurrentlyloggedontotheservercomputer.

TolinktotheCitectHMI/SCADAtagdatabase,andpermitwriteactionsfromanexternalapplicationusingNetworkDDE,theDDEClientcomputermustbegrantedappropriateTrustedstatus.

To create a Trusted ShareOntheDDESharesdialog,highlightthenew'Citect$'shareentry,andclicktheTrust Sharebutton.ThisdisplaystheTrustedSharePropertiesdialog:

CheckInitiate to Application Enableasillustratedabove,toallownewconnectionstotheDDEshare.

ClickOK.



34/51

To view the Trusted SharesIntheDDESHAREutilitydouble-clickontherighticon(withthetick)tolaunchtheDDETrustedSharesdialog.

TheDDETrustedSharesdialogliststheDDEsharesthataretrustedinthecurrentuser'scontext.YoucanviewandmodifytrustedsharepropertiesandremoveDDEsharesfromthelistoftrustedshares.

Oncesetupiscompleted,theDDEShareutilitywindowcanbeclosed.

Using Network DDEMicrosoftNetworkDDEServicemustberunningonbothcomputerstocommunicateusingNetworkDDE.Forstartupdetails,seeStartingNetworkDDEServices.

BeforeaNetworkDDEClientcanestablishaDDEconversationwithaNetworkDDEServer

application,theNetworkDDEServerapplicationcomputermustalreadyhavesetupaNetwork DDEShare.Fordetails,seeSetting-upNetworkDDEShares.NOTE: YoucannotconnectusingNetworkDDEtoasharedapplicationonthesamemachine.

YoucanonlyconnectusingNetworkDDEtoasharedapplicationonanothermachine(whichmustalsobeonthesamenetwork).

ToconnecttoaNetworkDDEsharedapplication,youuseanalteredversionoftheDDEsyntax,whichreplacesthe""with"\NDDE$"andreplacesthe""withtheNetworkDDEServerShare"",andcontinuestousethe""asnormal.

Atfirstglance,thereappearstobenowaytospecifytheDDEApplicationorTopicnamesinthe

NetworkDDEsyntaxcall,andindeed,thatisthecase.However,theDDEApplicationandTopicnamesaredefinedintheDDEServerSharesettings.So,whentheNetworkDDEServermachinereceivesthecall(fromtheNetworkDDEClient)containingtheSharename,itknowswhichapplicationandtopictoconnectwith.SeeHowtoconnecttoaNetworkDDEsharedapplication.

Ifyou'rehavingtroublesettingupaNetworkDDEconversationbetweentwocomputersconnectedtothesamenetwork,itmayassistyoutoexamineaworkingexample.SeeHowtotestthatNetworkDDEisoperationalbetweentwomachinesonthesamenetwork.

To connect to a Network DDE shared applicationThenetworkDDEClientspecifiestheremoteDDEServerShareinthenormalDDEClientsyntaxbyreplacingtheDDEApplicationnameandDDETopicnamewiththeDDEServerComputernameandDDEServerSharenameinthecall.ForDDEClientsyntaxdetails,seeDDEConversationsandClientSyntax.

WithNetworkDDEClientsyntax,theDDEApplicationnameisreplacedwiththefollowingstringenclosedinsinglequotes:

'\\\NDDE$'where""isthenameofthecomputerrunningtheDDEServerapplication,and"NDDE$"notifiesWindowsontheremotecomputerthatthecallingDDEClientwishestoestablishaNetworkDDEchannel.YoucannotomittheNDDE$string,oritwon'twork.

TheDDETopicnameisreplacedwiththefollowingstringalsoenclosedinsinglequotes:



35/51


36/51

UsinganexternalDatabase

YoucanstoreandupdateruntimedatafromyourplantfloorinadatabaseexternaltoCitectHMI/SCADA.YoucanalsouseCitectHMI/SCADAtosendinformationfromthedatabase(suchasarecipe)toI/ODevicesinyourplant.

Byusinganexternalapplicationtoreadandwritethesamedatabaserecords,youcaneffectivelyinterfacetoanexternalapplicationthrough,forexample,arelationaldatabase.

CitectHMI/SCADAsupportstwotypesofdatabases:

dBASEdatabasefiles

SQLdatabases

dBASE DatabasesThedBASEfileformathasbecomeanindustrystandardfordatastorage,andCitectHMI/SCADA

supportsthestandarddBASEformat.Youcanuseanydatabaseeditor(thatsupportsdBASEIIIfiles)tocreateadatabase,andtoreadandwritedatabaserecords.

Toconnecttoadatabase,youmustdefineaCitectHMI/SCADADevice.Devicesspecifytheformatandlocationofthedatabase,forexample:

Name Recipe


Header Name

FileName [DATA]:RECIPE.DBF

Type dBASE_DEV

Comment RecipeDevice(dBASEfile)

SQL DatabasesSQL(StructuredQueryLanguage)alsohasbecomeanindustrystandard.SQLisacommandlanguagethatallowsyoutodefine,manipulate,andcontroldatainSQLdatabases-andinotherrelationaldatabases.MostdatabaseserverssupportSQL.

ByusingSQL,youhavedirectaccesstodatabaseserversonotherplatforms,suchascomputers,mini-computers,andmainframecomputers.

YoucanusetheCitectHMI/SCADADevicefunctionstosetuptheformatandlocationsofeachofyourSQLdatabases.Alternatively,usetheSQLfunctionsfordirectcontroloverSQLtransactions.

YoumustdefineaCitectHMI/SCADADevicetospecifytheformatandlocationofthedatabase,forexample:

Name Recipe

IntheFormatfield,specifythefieldnamesintheSQLdatabase,forexample:




37/51

TheHeaderisthedatabaseconnectionstringforODBCconnection,forexample:

Header DSN=ORACLEDATABASE

EnterthedatabasetablenameintheFileNamefield:

FileName RECIPE

Type SQL_DEVComment RecipeDevice(SQL)



38/51

UsingSQL(StructuredQueryLanguage)

YoucanuseSQLfunctionsfordirectaccesstoanSQLdatabase,insteadofaccessingthedatabaseasaDevice.Usingdirectdatabaseaccesscanprovidegreaterflexibility.TheSQLfunctionsprovideaccesstoSQLdatabasesthroughanyODBC-compatibledatabasedriver,e.g.MSAccess,FoxPro,Paradox,etc.

Connecting to an SQL DatabaseBeforeyoucanuseSQLcommands,youmustconnecttotheSQLdatabasesystem.TheSQLConnectfunctionprovidesthisaccess.YoumustcallthisfunctionbeforeanyotherSQLfunctions.Ithastheformat:

SQLConnect(sConnect);WheresConnectistheconnectionstring,forexample:

INT hSQL;hSQL = SQLConnect("DSN=DBASE_FILES;DB=C:\ ODBC\ EMP;LCK=NONE;CS=ANSI");! Connect to a dBASE Compatible Database File.

INT hSQL;hSQL = SQLConnect("DSN=EXCEL_FILE;DB=C:\ ODBC\ EMP;FS=10");! Connect to an Excel File.

INT hSQL;hSQL = SQLConnect("DSN=ORACLE_TABLES;SRVR=X:ACCTS;UID=SCOTT;PWD=TIGER");! Connect to an Orac le Database.

NOTE: Somelongerlinesintheabovecodeexamplemayhavewrappedtothenextlineduetopagemarginwidthlimitationswhenviewedintheonlinehelporprintedmanual.Cicodedoesnotsupportcodewrittenovermorethanonelineandhasnolinecontinuationcharacter.Cicodedoesusethesemicolonastheendoflinecharacter.Ifyoucopytheseexamplesintoyourproject,youmustreassembleanylinesthathavebeenwrappedandplacethembackontotheonelineinyourcode.

RefertothedocumentationthataccompaniedyourSQLserverforfurtherinformationaboutconnectingtoanSQLdatabase.

Executing SQL CommandsSQLisapowerfulcommandlanguagethatallowsyoutomanipulatedatainanon-proceduralmanner;youspecifyanoperationintermsofwhatistobedone,nothowtodoit.SQLcommandsallowyouto:

Createtablesinthedatabase

Storeinformationintables

Selectexactlytheinformationyouneedfromyourdatabase

Makechangestoyourdataandtothestructureofatable

Combineandcalculatedata

TheSQLExec()functionexecutesanySQLcommandthatyourSQLserversupports.Forexample,tocreateadatabasetable,youwouldexecutetheSQL"CREATETABLE"command:



39/51

SQLExec (hSQL, "CREATE TABLE rec ipe ('Name' CHAR(16), 'Water' CHAR(8), 'Sugar' CHAR(8), 'Flour'CHAR(8), 'Salt' CHAR(8), 'Yeast' CHAR(8), 'Milk' CHAR(8))");

NOTE: Somelongerlinesintheabovecodeexamplemayhavewrappedtothenextlineduetopagemarginwidthlimitationswhenviewedintheonlinehelporprintedmanual.Cicodedoesnotsupportcodewrittenovermorethanonelineandhasnoline

continuationcharacter.Cicodedoesusethesemicolonastheendoflinecharacter.Ifyoucopytheseexamplesintoyourproject,youmustreassembleanylinesthathavebeenwrappedandplacethembackontotheonelineinyourcode.

Toaddrecordsintothedatabasetable,usethe"INSERTINTO"command.Thecommandhasthefollowingsyntax:

INSERT INTO [(, . . .)] VALUES(, . . .)Thiscommandaddsthevaluesforeachfieldinthetable,forexample:

SQLExec(hSQL, "INSERT INTO rec ipe VALUES ('Bread', '10', '5', '7', '1', '1', '2')");

NOTE: Columnnamesareoptional,howeverifyouomitcolumn(field)names,thevaluesareinsertedintothefieldsinthesameorderasthevalues.

ToreaddatafromanSQLdatabase,usetheSQL"SELECT"command.Youcanusethe"SELECT"commandtoreadanentiresetofrecords,orarow,fromthetable.YoucanthenusetheSQLGetField()functiontoreadthedataineachfield,forexample:

SQLExec(hSQL, "SELECT * FROM recipe WHERE NAME = 'Bread'");If SQLNext(hSQL) = 0 Then

PLC_Water = SQLGetField(hSQL, "WATER");PLC_Sugar = SQLGetField(hSQL, "SUGAR");PLC_Flour = SQLGetField(hSQL, "FLOUR");

PLC_Salt = SQLGetField(hSQL, "SALT");PLC_Yeast = SQLGetField(hSQL, "YEAST");PLC_Milk = SQLGetField(hSQL, "MILK");

END


Todeletedatabaserecords,usetheSQL"DELETE"command.Thecommandhasthefollowingsyntax:

DELETE FROM [WHERE]Thiscommanddeletesvaluesfromthetable,forexample:

SQLExec(hSQL, "DELETE FROM recipe WHERE NAME = 'Bread'");

NOTE: SQLisapowerfuldatabaselanguagethatisbeyondthescopeofthisdocumentation.ForfulldetailsofusingSQL,seethedocumentationforyourSQLdatabaseapplication.



40/51

Using a TransactionYoucanuseadatabasetransactionformoresophisticateddatabaseoperations.AdatabasetransactionallowsyoutoexecuteaseriesofSQLcommandsandtheneithercommitthechangestothedatabase,or'rollback'(cancel)thechanges,forexample:

SQLBeginTran(hSQL); ! Begin the transactionSQLExec(hSQL, "UPDATE recipe SET water = '12' WHERE NAME = 'Bread'");SQLExec(hSQL, "UPDATE recipe SET milk = '1' WHERE NAME = 'Bread'");IF . . . THEN

SQLCommit(hSQL); ! Commit the transactionELSE

SQLRollBack(hSQL);! Cancel the transactionEND

NOTE: ChecktheODBC-compatibilitylevelofyourdatabasedriverifyoucannotusetransactions.

Expressing Dates and Times in SQL

NOTE: AlldatereferencesinanexternaldatabaseshouldbebasedontheGregorianCalendar,orthedatabasetablesmustbeexportedtotextfilesbeforeuseinCitectHMI/SCADA.DatesinMicrosoftAccessDatabasetablesexportedastextfilesarealwaysstoredasGregorianvalues.

ThewayinwhichSQLdatesareexpresseddependsupontheparticulardatabasesystem.WithdBase,younormallyspecifyadateinbraces,forexample{02/18/95}.ForOracle,usetheformat:to_date(02/18/95,MM/DD/YY).OtherODBCdriversmayrequireanotherformat-acommonODBCformatis:YYYY-MM-DD.

Database independent date-time syntaxFordatabaseindependence,youcanusethefollowingsyntaxfordatesandtimes:

[YYYY-MM-DD HH:MM:SS.FFFFFF]where:

(thefirstcharacteraftertheopeningsquarebracket)mustbeeither: d Date, t Time,or dt DateandTime.

WhetheryouarespecifyingaDate,Time,orDateandTime,youmustprovidethefull26characterstring,forexample:

[d1995-02-18 00:00:00.000000]

RefertothedocumentationthataccompaniedyourSQLServerforfurtherinformationaboutSQLcommands.



41/51

UsingODBCDrivers

CitectHMI/SCADAsupportstheOpenDataBaseConnectivity(ODBC)standard.ManymanufacturersofdatabasepackagesnowalsosupplyanODBCdatabasedriverfortheirsoftware.AswellasthesethereareindependentpartiesmanufacturingODBCdatabasedriversforawidevarietyofdatabases.OnesuchsupplierisIntersolvQ+EwiththeirDataDirectODBCPack.Drivers

fromthispackagewillgivefullbackwardcompatibilitytothedriversusedinCitectv2.0.Inmostcases,however,anyODBCdriverforyourdatabasewillwork.

YoumustinstallandsetupupyourODBCdriverfromtheWindowsControlPanel.Followtheprocedurebelow:

1. OpentheWindowsControlPanel.

2. ClickontheODBCicontostarttheODBCsetuputility(ifyoudonotalreadyhaveanODBCiconinyourcontrolpanel,youmightneedtoinstalltheicon.SeethedocumentationprovidedwithyourODBCdriver).

3. ClickontheAddbuttontosetupaDataSource.NOTE: IfyourODBCdriverisnotincludedinthelistofInstalledODBCDrivers,returntotheODBCsetuputilityandinstallyourdriver(selecttheDrivers...button).

4. FromtheAdd Data Sourcedialogbox,selectyourODBCdriver.TheSetupdialogisdisplayed.5. EntertheDataSourceNameofthedriverthatyouusedpreviously.Forexample,ifyouhad

usedSQLinCitectv2.0withadBaseIIIdatabase,thenyourconnectionstringwouldhavebeen"DRV=QEDBF".Toavoidchangingtheconnectionstringsthroughoutyourproject,youshoulduseaDataSourceNameofQEDBF.

6. RunyourCitectHMI/SCADAproject.

SomeCicodeSQLfunctionswillnotworkifyourODBCdriverhaslimitedfunctionality.Thisproblemisrare,andinmostcasesaffectsonlytheabilitytousetransactionswiththeSQLBeginTran(),SQLCommit(),andSQLRollBack()functions.IfyouareusingtheIntersolvQ+EODBCdrivers,youshouldnothaveanyproblems-thesedriversarefullybackward-compatiblewithdriversusedwithCitectVersion2.0.

YoumightneedtochangethedatasourceintheControlPaneleachtimeyouswitchfromusingoneODBC-compatibledrivertoanother,e.g.fromadBASEfiletoanAccessdatabase.ClickontheODBCiconandselectfromthelistofavailabledatasources.(Refertothedocumentationsuppliedwithyourdriverformoreinformation.)

NOTES: 1)ForfullcompatibilitywiththeCicodeSQLfunctions,theODBCdrivershouldprovideaminimumoffunctions.Forexample,ifyourdriverdoesnotsupporttheODBCfunctionSQLTransact,youcannotusetheCicodefunctionsSQLBeginTran(),SQLCommit(),andSQLRollback().

2)CitectusedQ+Edriversinversions2.xxandearlier.Anyfunctionsyoumighthavecreatedintheseearlyversionsarefullybackward-compatible.Q+EdriversarenowODBC-compliant,soyouneedtoupgradeyouroldQ+EdatabasedrivertoaQ+EODBCdatabasedriver.

The ODBC Driver ExplainedCitectHMI/SCADAconnectsdirectlytotheMicrosoftAccessODBCdriver,whichallowsapplicationstoaccessinformationstoredinMDB(MicrosoftAccessDatabase)fileswithoutactuallyrunningMicrosoftAccess.(MicrosoftAccessusesthe"JetEngine"DLLtoaccessinformationstoredinMDBfiles.)

ODBCnormallyimpliesheavyuseofSQLstatementstomanipulatedata.SQLstatementscan



42/51

becomequitecomplexandverbose.ToimplementtheminCicodetheyoftenhavetobebrokenintochunkssothatthemaximumstringlengthforCicodevariablesisnotexceeded.

WithAccess,itispossibletocallqueriesthathavebeendefinedinAccesssothattheSQLstatementsbecomequitesimpleandstraightforward.TheAccesstables&queriescanbeusedtoimplementRELATIONSHIPSandJOINS,toSORT&SELECTonlythoserows(records)andreturnonlythosecolumns(fields)ofparticularinterestatthetime.

DevelopingqueriesinAccessalsohasanadvantagethattheresultingRecordsetscanbeviewedinAccesstomakesuretheycontainthedatathatisexpected.ThequeriescanincorporateSQLFunctions(suchasBETWEEN&AND).

TheJetEnginecanalsocallupontheVBAExpressionService.ThismeansthatmanynonANSIfunctionscanalsobeused(bothinSQLstatementsandAccessQueryDefinitions)providedthereisnoneedtomigratetoanonAccesssystematalaterdate.RefertoVBAFunctionsReferenceintheAccessorExcelhelpsystem(onlythosefunctionswith(VBA)afterthemandareappropriatetoanSQLenvironment,arelikelytoworkinanSQLstatement).

Setting up ODBCTouseODBC,theAccessODBCDrivermustbeinstalled.ThiscanbeobtainedfromMicrosoftandisincludedwithMicrosoftOffice.Itisimportanttousethethe32bitdriversforWindows95/WindowsNTCitect4.x.Theinstallationprogramme(egforMicrosoftOffice)willcopythenecessarydriversandtheJetEngineDLLintotheappropriateWindowsdirectorieswhentheappropriateDataAccess/ODBCoptionsareselected.

WiththeDriverinstalledonthePCtheODBCIconcanbeselectedfromtheControlPanelandaDataServiceNamesetupforthedesiredMDB.ThisisusedintheDSN=partoftheconnectstring.

TheJetEngineDLLisquitelarge(1MB)andaproblemcanariseiftheWindowsVirtualMemoryManager(VMM)swapsitoutofmemory.ThenexttimeanSQLisexecutedtherewillbeshort

delaywhiletheDLLisloadedbackintomemory.ToforcetheVMMtokeeptheDLLinmemory,designasimpledummytablewithonlyonerecordandonefieldandsetupaCicodetaskthatfrequently(sayevery10-15seconds)callsaSELECTquerybasedonlyonthedummytable.ThishasnosignificanteffectonCPUloadandkeepstheDLLinmemory.

Getting the Correct Syntax with ODBCTheODBCsyntaxforSQLsvariesfromtheAccesssyntaxinsomeways.AgoodwaytogetthesyntaxcorrectandviewtheresultingRecordsetistousethequerydesignerinMicrosoft QuerythencopytheSQLtextfromitintoCicode.BecauseMSQueryusesODBC,anysyntaxthatworksinitwillworkwhencalledviaODBCfromCicode.MSQuerycanalsobeusedtoconfirmthattheDSN

iscorrect.

MSQuerytendstocreateSQLtextthatispossiblymorecomplexthanabsolutelynecessary.InparticularitalwaysincludesthepathwiththefilenamewhichisnotnecessarybecausethepathisalreadydefinedintheDSNentry.Itisconsideredbadpracticetohardcodefilepaths.MSQueryalsotendstoprefixallcolumn(field)nameswiththetablenamestoavoidanychanceofambiguity.AgainthisisnotalwaysnecessaryanditisdesirabletokeeptheSQLtextasbriefaspossibleinyourcode.

TheSQLstatementtextgeneratedbythequerydesignercanbepastedintoExecuteSQLwindow(undertheFilemenuofMSQuery),anysurplustextremovedandtheSQLstatementtesteduntilthesimplestsyntaxthatworkscanbefound.ThereisprovisiontosavetheSQLtextifrequired.ThefinalversionoftheSQLstatementcanbeusedwithconfidenceinCicode.



43/51

Programming style with ODBCMostofthesamplecodeinthefollowingtopicsdonotincludeerrorcheckingandreporting: ReadingDatafromanAccessTablewithODBCWritingDatatoanAccessTablewithODBCDeletingRowsfromanAccessTablewithODBCCallingActionQuerieswithODBCParameterQueriesusingODBCThishasbeendonetokeeptheexamplesassimpleaspossible.Errorcheckingis(however)essentialforODBCcode.ConsiderationshouldbegiventoimplementingmostofthecomplexityofqueriesinAccessQueryDefinitionswheretheyareeasiertodesignandtheresultsareeasilyviewed.AWHEREclausecanbeusedwhencallingthequerytoselectonlythedesiredrowsatruntime.Wheretableshavemanycolumns(fields),theAccessQueryDefinitionscanbeusedtorestrictanyparticularcalltoviewonlythefieldsofinterest.

ItishelpfultobuildtheSQLtestupintostrings.FirstlytheODBCfunctioncallsbecomesimpler.SecondlythestringscanbepassedtoTraceMsg()tomakedebuggingsimpler.

RememberthattheJetEnginerunsonthesamePCasCitectHMI/SCADAandthatcomplexqueriesreturninglargeRecordsetscanhaveanadverseimpactonCPUandmemoryresources.Potentialproblemscanbeavoidedbycarefultable,queryandrelationshipdesign.

IfthereisaneedtoexecutethequeriesonaRemote Computer,thecodecansetuponaReportServeroranEventServer.ThisisespeciallyrelevantifthecodeistobetriggeredbyaneventinaPLC.IfthecodeistobetriggeredbyaUserataDisplayStation,andthequeryisconsideredtooCPUintensive,theDisplayStationcanbeusedtosetthePLCbitthatcallstocodeorcalltheReportusingtheCicodeReport()function.AnotherpossibilityistousetheCicodeMsgRPC()functiontocallaCicodefunction(withparameters,ifnecessary)onaremotecomputer.AllofthesealternativesrequireCitectHMI/SCADAtoberunningontheremotecomputer.

Comparing DDE with ODBCEachhasitsadvantagesanddisadvantages.IngeneralDDEissuitableforsimplerequirementsbutODBCshouldbegivenseriousthoughtifthelimitationsofDDEbecometoorestrictive.

DDEAdvantages

1. NoneedtosetupaDataServiceName(DSN),however,aDDEShareNameisrequiredforNetworkDDE.

2. CancallAccessMacros&Functions.

DDEDisadvantages

1. RecordsetswithrowsthatexceedthemaximumCicodestringlengthcannotbereaddirectly.2. Rows(records)arereturnedtostringvariablewithTABcharactersbetweencolumns.The

usermustparsethestringinCicodetoobtainthecolumn(field)values.

3. SQLscannotperformActions(suchasINSERT,UPDATEorDELETE).

4. DDEClientandServerapplicationsmustbothberunningatthesametime.

ODBCAdvantages

1. MSAccessdoesnothavetoberunning.ODBCusestheJETEngineDLLonthesamePC.ThisanadvantageinmanywaysbutcanconsumeexcessivePCresourcesifnotmanagedproperly.

2. LargeSQLstatementscanbebrokenintochunks.

3. SQLGetFieldmakeseasiertogetdatafromfields(columns).ThereisnoneedtoparsethedatainCicode.



44/51

4. Canhandlelargenumbersoffields(columns)intheRecordset.

5. SQLscanperformActions(suchasINSERT,UPDATEorDELETE).

ODBCDisadvantages

1. RequiresthataDataServiceName(DSN)besetup.

TheJETEngineDLLcannotbedirectlycalledonaremotePC,(ReportsorMsgRPC()canbeusedhowever,torunSQLstatementsonaRemoteComputerwhichmustberunningCitectHMI/SCADA).

ODBC CompatibilityBelowarelistedtherequiredandoptionalODBCfunctionsthatyourdatabasedrivershouldsupport.

Essential FunctionsTheCitectHMI/SCADASQLdevicesandCicodefunctionsonlyworkifthedatabasedriversupports

thefollowingODBCfunctions:

Level 0 Compliance Level 1 Compliance

SQLAllocConnect SQLColumns

SQLAllocEnv SQLDriverConnect

SQLAllocStmt SQLGetData

SQLBindCol SQLGetFunctions

SQLColAttributes SQLGetInfo

SQLDescribeCol SQLGetTypeInfo

SQLDosconnect SQLParamData

SQLError SQLPutData

SQLExecDirect SQLSetConnectOptionSQLExecute SQLSetStmtOption

SQLFetch

SQLFreeStmt

SQLGetCursorName

SQLNumResultCols

SQLPrepare

SQLRowCount

SQLSetParam

Optional FunctionsCitectHMI/SCADASQLdevicesandCicodefunctionsalsousethefollowingODBCfunctions,buttheyarenotessentialforoperation.Ifthesefunctionsareabsentinadriver,yougetalossoffunctionalityintheoperationofSQLdevicesandCicodefunctions.

Level 0 ComplianceSQLTransact Ifthedriverdoesnotsupportthis

function,theCicodefunctionsSQLBeginTran(),SQLCommit(),andSQLRollBack()arenotsupported.

Level 1 ComplianceSQLSpecial CitectHMI/SCADAusesthisfunctionif



45/51

Columns itisavailable.Thereisnolossoffunctionalityotherwise.

SQLTables (noeffectonCitectHMI/SCADA)

Level 2 ComplianceSQLDataSources

Thedriverdoesnotneedtosupportthisfunction.ItisprovidedbyODBC.

SQLExtendedFetch

Withoutthisfunction,CitectHMI/SCADAcannottakeadvantageofthenativedatabasesabilitytofetchrecordsatrandom.

SQLSetScrollOptions

Withoutthisfunction,CitectHMI/SCADAcannottakeadvantageofthenativedatabasesabilitytofetchrecordsatrandom.

SQLMoreResults

(noeffectonCitectHMI/SCADA)

SQLNativeSql (noeffectonCitectHMI/SCADA)

SQLProcedureColumns

(noeffectonCitectHMI/SCADA)

Using CitectHMI/SCADA as an ODBC ServerTheODBCserversupportallowsCitectHMI/SCADAtofunctionasanSQLdatabaseserver.Thiswillallow3rdpartyapplicationswhichsupportODBCtoaccessdatadirectlyfromCitectHMI/SCADA.ThismeansthatuserscanhavedirectaccesstodatainCitectHMI/SCADAwithouthavingtodevelopCicodeorreportstoexportthedata.

Currently,theCitectHMI/SCADAODBCserverallowsvariabletagstobeaccessed.Thetableforthevariabletagsisnamed'TAGS'andtheformatisasfollows.

NAME Variabletagname readonly

VALUE Thecurrentruntimevalue read/write

NOTES: 1)CitectHMI/SCADAcanonlyfunctionasadatabaseserveratruntime.2)UsingtagsthroughODBCatruntimecanstilladdtoyourCitectHMI/SCADALicencepointcount.Oncethistallyreachesacertainlimit,CitectHMI/SCADAwillnolonger

functioncorrectly.ThereforewhenaccessingtagsviatheODBCserver,it'simportanttokeepawareofhowmanypointsyouhaveused.ForfurtherinformationseeCitectHMI/SCADALicencePointCount.

How to setup the CitectHMI/SCADA ODBC ServerNOTE: YoumusthaveTCP/IPinstalledonyourcomputerfirst.SeetheInstallingand

ConfiguringTCP/IPsectionofthehelp.

1. FromtheWindowsStartmenuselectSettings |Control Panel.2. DoubleclickontheODBCicon.

3. ClicktheAddbuttonontheUser DSNtab.



46/51

NOTE: IfyouselecttheothertabsyouwillseethattheCitectHMI/SCADAODBCdriverhasbeenautomaticallyinstalled.

4. SelecttheCitect DriverfromthelistandclicktheFinishbutton.5. Enter"Citect"intheData Sourcefield.Ifyoudonotwanttousethisname,makesurethename

youdouseisoneword.

6. EntertheComputerNameintheHostfield.TheComputerNameisspecifiedintheNetworksectionoftheControlPanel.

7. PresstheOKbuttontosaveyournewdatasource.

How to access the CitectHMI/SCADA ODBC server using MS Query (V2.00)AllODBCcapableapplicationshavedifferentwaysofconstructingqueriesforaccessingCitectHMI/SCADAtags.TheexampleinstructionsforusingMSQuery,givenhere,areprovidedtoshowasimpleimplementation.YouwillfindthatMSExcelandMSAccessfollowthesamemethod.

1. YoumustfirstmakesurethatyouhaveMSQueryinstalledonyourcomputer.ItisdeliveredaspartofMSOffice.

2. SetuptheCitectHMI/SCADAODBCserverforWindowsNTorWindows95.

3. RunCitectHMI/SCADA.

4. RunMSQuery.

5. FromtheFilemenu(inMSQuery)selectNew Query.6. SelecttheCitectHMI/SCADADataSourceName(DSN)fromtheAvailableDataSourceslist.

ClicktheUsebutton.7. SelecttheTagstable.ClicktheAddbuttonandthentheClosebutton.8. YoucannowrunaquerytoextracttheTagdatafromCitectHMI/SCADA.Thesimplestwayto

seethisisbydoubleclickingonNamesandTags.

How to access the CitectHMI/SCADA ODBC server using MS Query (V8.00)UnlikeVersion2.00,UserDSNsarenotusedbyVersion8.00.InsteaditusesFileDSNswhichbydefaultarestoredintheProgramFiles\CommonFiles\ODBC\DataSourcefolder.FileDSN'sarenotstoredintheWindowsregistry,theyaretextfilesgiventhe.DSNextension.Whenyouconnecttoanexistingdatasource,onlytheavailableFileDSNsthatarestoredonthatPCaredisplayed.MSQueryV8.00doesnotdisplayUserorSystemDSNs.ThesimplestsolutionistocreateaFileDSNthatpointstoaUserDSN.

TocreateaFileDSNthatpointstoaUserDSN,dothefollowing:1. Useatexteditor,e.g.Notepad,andcreateafilecontainingthefollowingtwolines:

[ODBC]DSN=

whereisthenameofanexistingUserDSNthatyouhavecreatedviatheODBCiconintheControlPanel.

2. ClickSaveAsontheFilemenuandtypeanamethatincludesa.DSNfileextension.Forexample,"Citect_File.dsn"isavalidname.Includethequotationmarkstoensurethatthe.DSNfilenameextensionisaddedcorrectly.SaveittothedefaultFileDSNdirectorylistedabove,thenitwillappearintheDSNlistboxwithoutneedingtogoBrowsing.

3. OpentheODBCManagerfromtheControlPanelandensureyoucanseeyournewlycreated

File.DSN.



47/51

4. OpentheODBCManagerfromtheControlPanelandensureyouhavecreatedaUserDSNcalled.Forexample:SelectCitectDriverandClickFinishbutton;Enter"Citect"intheDataSourcefield(ie);EnterComputerNameintheHostfield.

Now,whenyourunMSQuery,youshouldbeabletoselectyourFileDSNfromthelist.

Reading Data from an Access Table with ODBCASELECTquerycanbeusedtoreaddatafromanAccesstableortocallanAccessquery.Aqueryispreferredoveratableiftherearemanymorecolumnsinthetablethanarerequiredatthetime,ifthedataneedstobesortedorifthereisarequirementtorelateorjoinanumberoftables.TheCicoderequiredisasfollows:

Function SQLTest

INT hSQL, iResult;

hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID_C ;PWD=YourPWD");IF hSQL -1 Then

iResult = SQLExec (hSQL, "SELECT * FROM qryRecipes WHERE Recipe Between '3000' And'6000'");

IF iResult = 0 ThenWHILE SQLNext(hSQL) = 0 DO

TraceMsg(">" + SQLGetField(hSQL, "Rec ipe") + "" +SQLGetField(hSQL,"Flour") + "" +SQLGetField(hSQL, "Water") + "" +SQLGetField(hSQL, "Cocoa") + "


48/51

iResult = SQLExec(hSQL, "INSERT INTO tblRecipes (Rec ipe, Flour, Water, Cocoa) VALUES('X1234', 2, 3, 4)" );

SQLDisconnect(hSQL);END

END


ToavoidhavingtodealwithSQLstatements,thestandardCicodeDeviceFunctionscanbeusedtoappendrecordstoanAccesstable.FirstlyconfigureanSQLDevice.Ifthetablehasalotoffieldsthatdonotneedtobewrittento,defineonlythosefieldsthatarerequiredinthedevicedefinition(thiskeepsthedevicedefinitionassimpleaspossibleandreducesthenumberofDevWriteinstructions).DevOpen,DevWriteandDevClosecanthenbeusedtoaddrecordstothetable.

CitectHMI/SCADAwillacceptsuccessiveDevWritesuntiltheyequalthenumberoffieldsinthedevicedefinitionatwhichtimeitwillconstructanSQLINSERTstatement.TheDevWritesmustcontaindataforfieldsinthesameorderasthedevicedefinition.ItisbesttodoaDevOpenfollowedimmediatelybysuccessiveDevWritesforasmanyrecordsasarerequiredthenaDevClosetoavoidtheriskofthedatabeingoutofcontext.

Editing Data with ODBCToeditdatainanAccesstabletheremustbeaunique(usuallyprimary)keytoidentifytherow(record)tobechanged.ThisistobeabletoprovideaWHEREclausethatwillapplyonlytothatrowinanSQLUPDATE.

Toeditdata,readthedatainthenormalway,keepingtrackoftheuniquekey.AnychangedvaluescanlaterbewrittentothesamerowusinganUPDATEquerywithaWHEREclause.

Function SQLUpdate

INT hSQL, iResult;

hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID;PWD=YourPWD");IF hSQL -1 TheniResult = SQLExec(hSQL, "UPDATE tblRec ipes SET Flour = 20, Water = 30,Coc oa = 40 WHERE Rec ipe

= 'X1234'");SQLDisconnect(hSQL);END

END

NOTE: TheODBC/SQLenvironmentdoesnotprovidethefacilitytoeditthe"CurrentRecord".ThereisinfactNOCurrentrecord.ForthisreasonDevAppendandDevSetFieldcannotbeusedtoaddormodifyrecords.

Somelongerlinesintheabovecodeexamplemayhavewrappedtothenextlineduetopagemarginwidthlimitationswhenviewedintheonlinehelporprintedmanual.Cicodedoesnotsupportcodewrittenovermorethanonelineandhasnolinecontinuationcharacter.Cicodedoesusethesemicolonastheendoflinecharacter.Ifyoucopytheseexamplesintoyourproject,youmustreassembleanylinesthathavebeenwrappedandplacethembackontotheonelineinyourcode.



49/51

Deleting Rows from an Access Table with ODBCTheDELETEkeywordisusedinconjunctionwithaWHEREclausetodeletetherequiredroworrows.IftheWHEREclauseisnotbasedonaPrimaryKey,morethanonerecordmaybedeleted.

Function SQLDelete

INT hSQL, iResult;

hSQL = SQLConnect("DSN=ODBCTest;UID=YourUID_C ;PWD=YourPWD");IF hSQL -1 Then

iResult = SQLExec(hSQL, "DELETE FROM tblRec ipes WHERE Rec ipe = 'X1234'");SQLDisconnect(hSQL);

ENDEND

NOTE: Somelongerlinesintheabovecodeexamplemayhavewrappedtothenextlineduetopagemarginwidthlimitationswhenviewedintheonlinehelporprintedmanual.Cicodedoesnotsupportcodewrittenovermorethanonelineandhasnoline

continuationcharacter.Cicodedoesusethesemicolonastheendoflinecharacter.Ifyoucopytheseexamplesintoyourproject,youmustreassembleanylinesthathavebeenwrappedandplacethembackontotheonelineinyourcode.

Calling Action Queries with ODBCAccessACTIONqueriescannotbecalledinaSELECTquerysuchas:

"SELECT * FROM qdeDeleteRec ipe"

TocallanAccessACTIONviaODBC,usetheCallstatementinSQLExec:"{Call qdeDeleteRecipe}"

NOTE: Notethatthestatementmustbeenclosedin{curly}braces.TheCallstatementcanbeusedtoCallSELECTqueries,theresultingRecordsetbeingaccessibleinthenormalway.

See Also:UsingODBCDrivers

Parameter Queries using ODBCManyODBCServerswillacceptPARAMETERSinaCallstatementsothatPARAMETERScanbedefinedinaQueryDefinitionontheServerandtheirvaluessuppliedbyODBCClientsatruntime.Unfortunately,theAccessJetEngineusesParameterMarkerswhicharenotsupportedinthestandardCallstatement.Themethodoutlinedherecanbeusedasawork-around.

ForeachquerythatrequiresPARAMETERS,designaargumentstablewiththesamenameasthequerybutwithadifferentprefix.Forexample,ifthequeryisqryParamTest,theTABLEcouldbecalledargParamTest.

TheTABLEshouldhave,say,fivefieldscalledParam1,Param2,Param3,Param4,Param5.



50/51

ThistableshouldbeaddedtotheAccessQueryDefinitionforqryParamTest.Whenthishasbeendone,thefieldnamescanbeusedasPARAMETERSanywhereintheQueryDefinition.

AsimpleCicodefunctioncanbewrittentowhichthequeryname(withouttheprefix)andPARAMETERSarepassed.Thefunctioninserts"arg"infrontofthequerynameandexecutesaDELETEfromtheTABLE(tobesurethatitisempty)andthenperformsandINSERTtoleavethetablecontainingONERECORDwiththedesiredPARAMETERSintheappropriatefields.ThefunctionthenprefixesthequeryNamewith"qry"andCallsthequery.

Function SQLCall(INT hSQL, STRING sQueryName, STRING sArg1 = " ", STRING sArg2 = " ", STRING sArg3 = " ",STRING sArg4 = " ", STRING sArg5 = " ")

STRING sTable, sQuery;

sTable = "arg" + sQueryName;sQuery = "qry" +sQueryName;

SQLExec(hSQL, "DELETE FROM " + sTable);SQLExec(hSQL, "INSERT INTO " + sTable + " (Param1, Param2, Pa ram3, Pa ram4, Param5) VALUES ('" +

sArg1 + "', '" + sArg2 + "', '" + sArg3 + "', '" + sArg4 + "', '" + sArg5 + "')");SQLExec(hSQL, "{Call " + sQuery + "}");

END

CallingtheFunctionfromCicodeisthenassimpleas:

SQLCall(hSQL, "ParamTest", "2000", "4000");

NOTE: ThedefaultparametersforSQLCallmustbeSPACESif"AllowZeroLength"is"No"intheAccesstableDefinitionsforfieldsParam1,Param2etc.

Somelongerlinesintheabovecodeexamplemayhavewrappedtothenextlineduetopagemarginwidthlimitationswhenviewedintheonlinehelporprintedmanual.Cicodedoesnotsupportcodewrittenovermorethanonelineandhasnolinecontinuationcharacter.Cicodedoesusethesemicolonastheendoflinecharacter.Ifyoucopytheseexamplesintoyourproject,youmustreassembleanylinesthathavebeenwrappedandplacethembackontotheonelineinyourcode.

ThefunctioncanbeusedtocallmanydifferentPARAMETERqueries.



51/51

Anadvantageofthiswork-aroundisthat,evenafterCitectHMI/SCADAhasbeenshutdown,thequerycanbecalledfromAccessand,becausethePARAMETERSarestillstoredintheargumentstable,theresultingRecordsetcanbeviewedinAccess.

NOTE: Anothermethodistodesignqueriesthatperformanyrequiredjoins,sortingandfieldselectionthecallthemusingaWHEREclausetoselectthedesiredrows(records).

Access and Cicode Date/Time Conversions

NOTE: AlldatereferencesinanexternaldatabaseshouldbebasedontheGregorianCalendar.

AccessandCicodehavedifferentDate/Timevariablesdatatypes.Therearethreewaystoconvertbetweenthetwo:

Convert to real numbersInbothCicodeandAccessitispossibletoequaterealnumberstoData/Timevariables.Theconversionbetweenthetwosystemsisasfollows:-

AccessTime = 25568.66667 + (CicodeTime/86400);Citec tTime = 86400*(AccessTime - 25568.66667);

Convert to stringsTheDataand/orTimeareconvertedtoandfromtextstringsusingthestandardconversionfunctionsavailableineachenvironment.

Use the #Date/Time# SQL syntaxTheJetEnginewillconvertandDatesandTimestringsenclosedin#markers.ThisdatebeveryusefulinaWHEREclause:

SELECT * FROM qryMyQuery WHERE 'Date' BETWEEN #3/20/96# AND #3/27/96#

NOTE: TheAmericanDateformatisalwaysusedinthiscase,theJetEngineDLLignoresthelocalDateandTimesettingsassetinWindowsControlPanel.

citect database

Documents