C functions
Ready-made functions called from C scripts: tag, object, screen, system, DLL equivalents, file and C library. Unsupported function groups.
How functions are provided
Most functions are provided by #include "apdefap.h" (the template of new C scripts begins with this line). The full signature and an example of each function are in the Reference panel in the code area; the search box searches all functions. This topic summarizes the groups and the behavior rules.
Tag functions
The name consists of parts: Get (read) or Set (write) + Tag + data type + optional suffix. The first parameter is the tag name (Tag Tag_Name; a constant text or a char array is passed).
| Tag type | Function family | Return / value |
|---|---|---|
| Bool | GetTagBit, SetTagBit | 1 or 0 |
| Byte, USInt | GetTagByte, SetTagByte | 0 – 255 |
| SInt | GetTagSByte, SetTagSByte | −128 – 127 |
| Word, UInt | GetTagWord, SetTagWord | 16 bit unsigned |
| Int | GetTagSWord, SetTagSWord | 16 bit signed |
| DWord, UDInt | GetTagDWord, SetTagDWord | 32 bit unsigned |
| DInt | GetTagSDWord, SetTagSDWord | 32 bit signed |
| Real | GetTagFloat, SetTagFloat | float |
| LReal | GetTagDouble, SetTagDouble | double (a safe choice for a numeric tag of unknown type) |
| String | GetTagChar, SetTagChar | char*; the returned text is valid until the function ends; if it is to be kept, copy it with strcpy |
| DateTime | GetTagDateTime, SetTagDateTime | SYSTEMTIME |
| Raw byte | GetTagRaw, SetTagRaw | — |
- Suffixes: the function with the
…Waitsuffix and the one without give the same result (a read returns the current value, a write waits until the value has been sent).…State(…, &durum)returns the state code together with the value, and…StateQC(…, &durum, &kalite)returns the state and quality codes (in read functions only). In write functions,…Statereturns the state of the write. - State code: 0 good;
0x0001no connection;0x0080value not read yet;0x0200address error;0x0400no such tag. Quality: 192 good, 84 value is outside the tag's lower / upper limit. - Multiple tags:
GetTagMultiWait,SetTagMultiWait(and the…MultiState…variants), theGetTagValue/SetTagValuefamily. - Increase / decrease:
IncreaseTag,DecreaseTag; bit operationsSetBit,ResetBit,InvertBit. - A non-existent tag does not raise an error: the function returns
FALSE/0and writes a line to Diagnostics (Bool tag 1 / 0).
Object functions
The first parameter is the name of the screen, the second is the name of the object. In code that runs from an event, lpszPictureName gives the screen of the event and lpszObjectName the object of the event; for an object on another screen, the screen name is written. Colors are a single number (0x00BBGGRR: red + 256 × green + 65536 × blue).
| Group | Functions |
|---|---|
| General property | GetPropBOOL / SetPropBOOL, GetPropChar / SetPropChar, GetPropDouble / SetPropDouble, GetPropWord / SetPropWord: the property name is given as text |
| Property-specific | Get / Set + Visible, BackColor, ForeColor, BorderColor, Text, Left, Top, Width, Height, OutputValueDouble, OutputValueChar, FillingIndex, Operation, FontBold, FontSize, FlashBackColor, PictureName, Pressed, Process, Min, Max and others (GetInputValueDouble, GetLayer are read-only) |
| Focus and tag link | Set_Focus, Get_Focus, GetLinkedVariable, GetLink, SetLink (a link change is valid for the duration of the session) |
A nonexistent screen or object, a property without a mapping and a value of the wrong type do not raise an error: the function returns FALSE / 0 / empty text and a diagnostics line is written (the same text only once). The value written is valid for the duration of the session; it is not written to the project.
Screen, language, user, system
| Group | Functions |
|---|---|
| Screen | OpenPicture, OpenHomePicture, OpenPrevPicture, StorePicture, OpenStoredPicture, OpenScreeninPopup, ClosePopup, GetLocalPicture, GetParentPicture, GetParentPictureWindow; with the TIA names ActivateScreen, ActivateStartScreen, ActivatePreviousScreen |
| Language | GetLanguage, SetLanguage, SetLanguageByName ("tr", "en", "de"), InquireLanguage. The language must be defined in the project. |
| User | ShowLogonDialog, Logoff, PASSCheckLevelPermission (no DLL declaration is required) |
| Diagnostics | printf, TraceText, TraceTime: the lines are written to the script diagnostics list and the event log |
| Program and computer | GetComputername, DeactivateRTProject, StopRuntime, ConvertLocalTimeToUTC, ConvertUTCToLocalTime, ProgramExecute (program permission; completion is not awaited; if the return value is greater than 31, the launch succeeded) |
| Action memory | SysMalloc, SysFree: the memory is released automatically when the action finishes |
| Recipe (user archive) | ua… functions: uaConnect, uaQueryArchive, uaArchiveOpen / Close, MoveFirst / Next …, GetFieldValue…, SetFieldValue…, Update, Insert, Delete, ReadTagValues, WriteTagValues. The archive is the recipe with the same name. There are no configuration functions and no import / export. |
DLL equivalents
No real DLL is loaded; the counterparts of the following functions are built into Live and are declared between the lines #pragma code("dll adı") / #pragma code(). #include "PWRT_api.h" brings in the UseAdmin declarations ready-made.
| DLL | Functions |
|---|---|
| UseAdmin.dll | PWRTLogin, PWRTLogout, PWRTGetCurrentUser, PWRTGetLoginPriority, PWRTCheckPermission, PWRTSilentLogin |
| kernel32.dll | Sleep, GetTickCount, GetLocalTime, GetSystemTime, GetComputerNameA, WinExec |
| user32.dll | MessageBoxA (buttons 1 OK, 2 Cancel, 6 Yes, 7 No) |
| shell32.dll | ShellExecuteA |
| PDLRTAPI.DLL | PDLRTAllowSetForegroundWindow, PDLRTSetScreenKeyboardMode (nothing to do; returns TRUE) |
Files and the C library
- File (File access permission):
fopen,fclose,fprintf,fputs,fgets,fgetc,fread,fwrite,feof,fflush,fseek(only on a file opened for reading),remove,rename… Text mode only; when writing,\n→\r\nis converted, and when reading,\r\n→\n. - Text:
strlen,strcpy,strncpy,strcat,strcmp,strchr,strstr,strtok,sprintf,sscanf,atoi,atof,strtol,strtod,toupper,isdigit… - Math:
fabs,sqrt,pow,floor,ceil,fmod,sin,cos,tan,atan,atan2,exp,log,log10,abs,rand,srand. - Memory:
memset,memcpy,memmove,memcmp,malloc,free. - Time:
time,localtime,strftime,mktime,difftime,clock.
Unsupported functions
The following groups are defined (the code compiles) but do nothing when called: a line is written to diagnostics and FALSE / 0 is returned. The Studio Problems list (F7) warns about them in advance.
- Alarm functions (
AXC_OnBtn…,AcknowledgeMessage…) - Table and curve window functions (
Tlg…) and legacy functions - Report jobs (
ReportJob,RPTJobPreview,RPTJobPrint) - User archive configuration and import / export functions (
uaAddArchive,uaArchiveExport…) Get…/Set…functions with no corresponding object property (e.g.GetBackColor2)fscanf,freopen,tmpfile,tmpnam,fgetpos,fsetpos,getchar,gets,scanf,vfprintfOpenNextPicture: no forward screen history is kept; returns 0
Limitations and points to note
- If a DLL function that is not in the list is called, the script stops with a clear error; Studio warns at compile time.
FillDiagnoseInTagsis defined for compatibility and has no effect.- File and program functions do not work while the permission is off; Studio warns about a call whose permission is off in advance.