Script

Configuration Scripting

Key name	Input	Meaning
Serverscript cycle time	Default value: 500	Script cycle time in milliseconds
Clientscript cycle time	Default value: 200	Script cycle time in milliseconds
Number of incorrect script runs	Default value: 10	This defines the number of times the script is run with hard errors
Copy structures	Default value: yes	Defines, if structures will be copied when allocating
Sharing pocess variables after running the script	Default value: no	After running the scripht, the registered process variables will be deallocated.
Always release process variables after data management	Default value: no	After calling the data management functions, the registered process variables will be deallocated.

Tasks of the plug-in script

PROCON-WEB allows scripts to be edited parallel to the running visualization.These formulas are not a substitute for control, but mainly cover the following tasks:

• Support of the visualization by preparing process data (e.g., generating summarized status information)

• Supplementary-controlled processing of complex functions (e.g., data acquisition, alarms, screen changes, calculations)

• Simulation of processes by changing internal parameters

• Plausibility checks over several dependent setpoints

• Time-controlled processing of functions

• Call up your own high-level language programs

Release 6.8 differentiates between server and client scripting.As the name suggests, scripts can now be sent directly to run on a client. They run in a WebWorker and are thus encapsulated by the actual WebRuntime. In contrast to Server scripts, client scripts are written in TypeScript.

Clientscripting

General

• The scripts are written in TypeScript ES6 Module.

• In the scripts you have access on the tags like with dynamic expressions.

• You can write the value of the variable directly

• Functions have to be exported whenever you want to use them outside of the actual script. (e.g. integration into another script-file, assign a script function to a button, or append of a cyclic image script)

• In the transfer parameters of the exported functions are the allowed types exclusively number, string or boolean.

• Union types and overloads are allowed. These are then individually selectably resolved.

• The calling of browser specific APIs (e.g fetch, setTimeout) as well asthe manipulation of DOM-elements with Clientscripting is not allowed.

• Import of other scripts is with relative paths possible.

Creating a Clientscript

With the right mouse button in the context menu of the project tree, a new client script will be created.

The following are some pointers on how to create a client scripts.However, since it is a standardized language, it is recommended to provide additional information or parts of code using a Internet research.

Create a function

To create a function, you can use the following syntax:

function nameofthefunction(par1,par2,…) { //code } Important: If you want to use this function outside of the script (e.g. assign to a Button), then the keyword export must be completed.

export function nameDerFunktion(par1,par2,…) { //code

Create variables

The special thing about Typescript is, that you don’t necessarily have to use a data type. Typescript does this on its own. If you want to declare variables or constantswithin a script, you can do this with the following syntax:

Creation within a function (local)

export function myFunction() {

//Declaration of constants const VARIABLESTRING : string = “This is a string”; const VARIABLENUM : number = 123; const VARIABLEBOOL : boolean = true;

//Declaration of variables let variableString : string = “Das ist String”; let variableNum : number = 123; let variableBool : boolean = true;

} Creating outside of a funtion (global):

Create variables

One-line comment with: // Multi-line comment with: /* */

Comment on area: highlight the area and then: SHIFT +ALT + A

export function myFunction() {

This is a one-line comment.

This is a multi-line comment.

Assignment of the script function to objects (e.g. button)

Creation and integration of a CS function, e.g. for button differenceswhen calling functions with different types

• Code example for union types: With selection of functions etc

• demonstrate transfer parameters

Import from other scripts

Here it is important, that the relative path starts always with:„./“(Skript and is in the same folder or further down

Picture-Scripts

It is also possible to call a script function cyclically. In contrast for server scripting, a function and not a script must be specified here In the future, the When functions from the same script are called cyclically, and also when the image open/close event the script function is used in the Always open the image before the first cyclic pass and the Close event always after the last run. Are used in the open/close event functions are called in other scripts, so the order of execution has not been ensured. If an image is opened and closed again immediately afterwards it can happen that there is no cyclical run.

When it comes to functions, you can now execute client script functionality as an actionbe determined. Here, the script, the function and the parameters be specified.

Converter from Pascal to TypeScript

In the designer there is the possibility to convert old Pascal code to TypeScriptThis can be done via the context menu in the tree for a server script.

If the script has been successfully converted, it will open afterwards.If an error occurs during the conversion, a message is displayedHere you have to check whether the server script can be translated at all. The original script will not be deleted.

There is no automatic assignment of the converted script to images or image elements (e.g. button). Has a script that shall be converted dependencies, then these must also be converted manuallyOnce converted, the functionality of the scripts must be checked. This is necessary because not all language constructs of a server script can be copied into a client script. The converter always tries to find the best solution here.

After converting, the script may still have errors. This then has to be fixed manually. Has been a function of the ServerSkrpt API that does not exist in the client script, or the converter not supported, then a dummy method that throws an error on Placed at the beginning of the script. Here you can use the functionality re-implemented or the script has to be rebuilt in such a way that the Function is no longer required.

The converter is designed to translate server scripts that are already in place in existing projects. He doesn’t carry out any verificationby whether the server script is valid at all. In the event of an invalid server script, the conversion may failor or an invalid Client script will be generated.

Client Script V0 Api

The first API (V0) is now availabel in the Clientscripting. The APIis related to the function in the Serverscripting.

The syntax for calling differs from the one used in the serverscripts.

Furthermore, the API is located under the namespace “pweb.v0.scripting”. Tocall a userLogin, “pweb.v0.scripting.login(username, password)”. Before each API call the changed tags will be written to the web runtime.An API call always returns a promise, which starts with “await” needs to be maintained. While using await on the response an API function is maintained, a different script may run. If the answer of that API function comes back, the tags from the Read WebRuntime are read again. IntelliSense can be used for syntax.

• fillImageView

• specialFunction

• addLogbookEntry

• setLanguage

• getLanguage

• openNewBrowserWindow

• openNewBrowserTab

• changePicture

• openPicture

• closePicture

• printPicture

• changeAllPictures

• fillPictureArea

• login

• logout

• createUser

• deleteUser

• setUserPassword

• getUserGroup

• addUserToGroup

• removeUserFromGroup

• getUserInfo

• setUserInfo

Undo/Redo The editor includes its own UndoRedo stack which is not synchronized with the designer’s. So if you change in a clientscript a script, there is no entry for undo/redo in the Designer. An exception to this are actions that affect other areas in the designer. Currently, these are the following:

• Rename tag/process variable (via F2 in the CS-Editor)

• Rename already exported functions (via F2 in the CS-Editor)

Note

If there are errors (no warnings!) in a script, it can be that warnings cannot be displayed because the Compiler can’t correctly determine if it’s displaying a warning or not. A blank line within a while loop is defined as Warning detected, an invalid string is not.

Runtime

At runtime, all tags that are in a script (including imported ones) can be requested on the TagServer. A script is only executed, when a first read from the TagServer (not from the controller) is started.

If the same script (doesn’t have to be the same function) is started multiple times, is will be ensured, that the scripts will be executed in the correct order. For different scripts that isn´t ensured.

System alarms

Numbers	Text	Meaning
9500100	WebRuntime: Clientscript couldn´t be loaded - check browser version	Error within export or browser version
9500101	WebRuntime: Clientscriptfunction was not found	Function does not exists
9500102	WebRuntime: Unhandled error in the clientscript	Error in the try-catch block
9500103	WebRuntime: Invalid access on tags in the clientscript	Access on not existing tag

Security note

Because client scripts don’t run on the server, but in the browser, it can theoretically - just like any other JavaScript code that isrunning in the browser - be manipulated.

Debugging

The scripts can be “debugged” by the browser via the normal debuggerIn the future, the The scripts are located under the “clientsScripts” and there under the URL “clientscript://”. Here are source maps for the scripts so that the original Typescript code can be displayed and not the translated JavaScript code.

It is recommended to debug in the options of the Chrome/Edge Debuggerfrom the ClientScriptRuntime.js. To this end, the ClientScriptRuntime.js file at custom exclusion rules should be added.

Serverscripting

Structure of the scripts in the project

There are three different types of script execution under PROCON-WEB:

• Tasks that are processed cyclically during runtime (e.g., global script).

• Image-specific scripts that are processed cyclically at the time the image is displayed

• Scripts that click on buttons or events, for example: opening or closing picturesAll scripts are stored in the project database and edited in the designer.

Processing of the events

Before the scripts are processed, the script server checks for which scripts in the tasks the condition is true and then processes them cyclically. The cycle time tells us when the script will be executed next. Please note that the scripts are executed as little as possible and as often as necessary based on the cycle times. The lower the cycle time is set, the more often the script is executed.

In PROCON-WEB, the scripts can now be assigned to buttons and images as independent scripts.

Creating and compiling the scripts

The designer automatically creates the global script and a cyclic task with 100 ms when creating a new project. Image-oriented scripts are now normal scripts that are assigned to the image via the image class. The scripts can be used in tasks, in pictures as picture scripts or when opening / closing pictures.All scripts available in the project can be selected in the project tree in the plug-in script.

Alle im Projekt vorhandenen Skripts sind im Projektbaum im PlugIn Skript wählbar.

Important

Script names must begin with a letter and cannot contain any special characters other than the underscore ‘_’.

Important

Picture-oriented scripts of not visible pictures will also be executed.

To assign a script as a picture-oriented script to a picture, the corresponding script is selected via the picture’s class dialog.

Scripts on pictures (cyclic picture-oriented script) are processed in the following situations:

• Open picture (via button for example)

• Switch an opened picture invisible

• Switch a picture area invisible in which the picture is embedded

• Empty a picture area invisible in which the picture is embedded

In case of the picture-closing event, picture-oriented scripts are not processed

Create tasks

Tasks can be used to execute scripts in the ScriptServer cyclically or event controlled.When creating a new project, the designer automatically creates a global task that is to process the global script cyclically with 100ms.

A task requires a name, optionally a description, and a script that this task is to execute.You can also define whether the task should run cyclically, or event driven.

Important

The minimum cycle time of a task is 100 ms

The parameterisation of the event-controlled tasks takes place in the same way as in the picture montage.

Since the scripts are client-related, they are each written in the context of the Executed on the corresponding clients. This means using local variables are the variables of the respective client, the logged-in users, the corresponding client user, etc.

The scripts run per client, so if there are several registered clients also use the scripts accordingly for EACH Client running.

Client Start

The task condition “Client Start” executes the stored script if a client logs on to the system for the first time. The script is opened when the Clients and then runs once in the background. The client does not wait for the script to finish at startup. At a long-running client Start Script can be used by the client before the script has been completely processed.

Should the client only allow certain actions AFTER the script has been terminated, this must be done, for example, by setting a Process variables at the end of the script, which the client then refers tocan react accordingly.

Client Cycle

The task condition “Client Cycle” executes the stored script cyclically for each logged in client. The script is created in a similar way to global cyclic scripts always replay after the interval timetriggered. If the script runs longer than the interval time, it becomes direct is then triggered again. There is only one script running per client at a timeat a time, i.e. the next script call will be executed until the end of the previously delayed or ignored the call directly if the identicalScript is currently running.

Startup and shutdown events

In addition to the tasks mentioned above, tasks for the system start and system stop can also be defined.This means that scripts can now be executed when starting runtime (more precisely when starting the script server) and when exiting runtime.

Several startup and shutdown scripts can be defined; these are then processed in sequence.

Startup scripts every time the server transitions to running.

Shutdown scripts every time when transitioning from running to break.

Important

The startup script can be used for initialization tasks, for example.

This can replace the old pattern in the global script:

PROGRAM
BEGIN
     Init()
     while(1) do …
END

The content of Init () can now be defined as a stand-alone script and used as a startup script.

Important

The shutdown script is executed when the service is shut down.

The SystemServer ensures that the dependent function servers (TagServer, DataServer, AlertServer) are still running. But now the web server may have already been shut down and no clients are logged on to the system. Client-related script functions (open picture, …) can therefore fail.

Syntax serverscripts

Overview

A separate language was defined, which is based on the PASCAL syntax. The language allows block formation, control structures, loops, and functions for a modular structure of the program.

All instructions are line-oriented to dispense with terminator symbols for instructions. The line length is set to 255 characters. Comments are possible anywhere in the source code. Function values do not have to be specified when the function is called, even if the called function requires a value.

The language includes the basic arithmetic operations of addition, subtraction, division, multiplication, integer division and remainder. Likewise, the comparison operators =, <> or! =, <=,> =,>, <.

The language includes the binary operations NOT, AND, OR, XOR, SHL, SHR.

The language allows a local definition of variables of the simple types Boolean, Integer, Real, String.

The language has a standard set of functions for easy integration of user functions.

The language allows the specification of constants of the types Boolean, Integer, Real, String.

The compiler differentiates between upper and lower case.

The language knows all process values of a project as variables of the type Boolean, Real and String (note one-dimensional fields).

The language allows a maximum of 5 block nesting.

The language allows a maximum of 5 levels of brackets.

The language does not allow function definitions in functions.

The language does not allow semaphores (formulas cannot be synchronized).

The following table explains the order of precedence of the operators.

Rang	Operator
	not
	*, /, div, mod, and, shl, shr
	+, -, or, xor
	=, <, >, <>, <=, >=

Operators of higher precedence are executed first. If operators have the same rank, the execution is carried out from left to right. For example, “*” is executed before “div”, not is executed before “*” and “div”.

Important

Division of constants without “.” Are interpreted as integer values.In other words, with a division you have to work with decimal places, e.g. test = 15.00 / 3.00 instead of test = 15/3

Keywords	Meaning
StackSize	Stack size in bytes (max. 10000; default setting: = 4096)
program	Start of program
import	Imports another script
Import ..as ..	Imports another script with an alias name
private	Functions and variables defined with “private” cannot be imported
.	Dot operator to access functions and variables of imported scripts
const	Definition of constants Example: const Name = 100 (the name must be unique in the project, ie no names identical with variables).
var	Variable definition (always comes after the constant definition
boolean	Data type logical variable
Integer	Data type integer variable
real	Data type numeric variable
text	Data type file variable
string	Data type text variable
begin	Start of block
if..then..else	Control structure condition
for..to..do	Loop with incrementation (index only integer) (run variable of type: integer)
for..downto..do	Loop with decrementing (index only integer) (run variable of type: integer)
while..do	Loop with condition (run variable of type: Integer)
not, and, or
xor, shl, shr	Binary operations (e.g. numvar: = numvar1 shl 2)
mod, div	Integer operations
end	End of block
function	Start of function
exit	Jumps out of the current function

Syntax description

Important

Keywords are fixed terms and must not be used for constants or variables in formula code.

Terminal symbols
+, -, *, /	Basic arithmetic
(, )	Bracketing (5 bracket levels)
(*, *)	Short name
<, >, <=, >=,<>, =	Comparison mode
: =	allocation
[]	Field indexing
.	Decimal point
’	String with max. 31 characters
$	Hex-Symbol
:	Var-Trenner
,	Identifier

Language elements

Meta symbols
<T>	T not terminal symbol
{}	optimal value repetition
[]	optimal
Buchstabe	A..Z
Hex digit	0..9
Hex digit	Hex digit

Numerical values
Hex digit	$ <Hex digit> {<hex digit>}
Integer	[+ || -] <digit> {<digit>}
Real value	[+ || -]<digit> {<digit>}. <digit> {<digit>}
Identifier	<Letter> {<number || Letter>}
Field identifier	<Identifier> “[” <identifier || Integer || Hex digit> “]”
Variable identifier	<identifier> || <Field identifier>
Function identifier	<identifier>
Constant declaration	<identifier> = <hex digit|| Integer || Real value
Result type	boolean
Variable declaration	<Variable identifier> {“,” <variable identifier>}: <result type>
Comment	(* <Text> *)
Stack size	STACK <hex number` || Integer>
Number of lines	LINES <hex dgit|| Integer>
program	program <Block>
Block	[<Import declaration part>][<Constant declaration part>]|||[<Variable declaration part>][<Function declaration part>]<Command part>
Command part	Begin <Statement block> end
Const. Declaration part	const <Constant declaration> {<Constant declaration>}
Variable declaration part	var <Variable declaration> {<Variable declaration>}
Function declaration part	<Function head> <Function block>
Functional head	function identifier> [“(” <parameter list> “)”]: <result type>
Parameter list	<Variable declaration>|| var <variable declaration> {, <parameter list>
Function block	<Constant declaration part>] [<Variable declaration part>]<Function command part>
Function command part	Begin <Statement block>||<Function identifier>: = <expression>end
factor	<Variable identifier> || <constant identifier> || (<expression>) || <factor> || not <factor> || <Function call> || <external function>
Term	<factor> {(. || / || div || mod || and || shl || shr) <factor>}
Function call	<Variable identifier>: =] <function identifier> [(<function parameter>)]

Note

The size of the variable pool (bytes) in a function must not exceed the stack size (default setting = 1024).The function parameters can also be of the ‘String’ data type.

Function parameters	<Expression || Variable identifier> {, <function parameter>}
simple expression	<Term> { (+ || - || or || xor) <Term>}
Expression	<simple expression> {(<||> || <= ||> = || <> || =) <simple expression>
Instruction	<Compound statement> || <conditional statement> || <Repeat statement> || <assignment> || <Function call>
Statement block	<instruction> || <Statement block>
Compound instruction	Begin <instruction> {<instruction>} end
conditional statement	if <expression> then <instruction> [else <instruction>]
Repeat instruction	<while statement> || <for statement>
while statement	while <expression> do <instruction>
for statement	for <variable identifier>: = <expression> to || downto <expression> do <instruction>
allocation	<Variable identifier>: = <expression>

General rules and instructions

Error handling

Im Skript Editor des Designers kann man in der Fehlerliste erkennen, ob es sich um eine Warnung oder um einen Fehler handelt. Dies funktioniert für Client- und Serverskripte. Wird ein gelbes “!”” angezeigt handelt es sich um eine Warnung. Bei einem Roten X um einen Fehler. Existieren Skripte mit Fehler kann nicht mehr exportiert werden. Bei Warnungen kann weiterhin exportiert werden. Es werden Fehler immer vor Warnungen angezeigt. Dies kann dazu führen, dass Warnungen nicht angezeigt werden, wenn direkt davor ein Fehler ist.

Subroutine call

With the help of event-local variables, process values can be transferred to a subroutine and the result returned to the main program.

(* 2 values are transferred to the “fnMinMax” subroutine in order to compare them. The result of the
function is returned to the main program using the function variable result1 or result2.
– Call by value –
The variables Pvar1, Pvar2, Pvar3 and minmax_bit are globally defined process variables. *)

Program
  var Param1, Param2, Ergebnis1, Ergebnis2: integer

function fnMinMax(wert1 : integer, wert2 : integer, var result1, result2 : integer) : integer
begin
   if wert1 > wert2 then
   begin
     result1:=wert1
     result2:=wert2
   end
   else
   begin
      result2 := wert1
      result1 := wert2
   end
   (*Assign function own return value*)
   fnMinMax := (wert1+wert2) / 2
end

(* Main program *)
begin
   if minmax_bit = 1 then
   begin
      minmax_bit :=0

      (* Copy process variables to local transfer variables *)
      Param1 := Pvar1
      Param2 := Pvar2
      (* Function call with function parameters *)
      Pvar3:= fnMinMax(Param1, Param2, Ergebnis1, Ergebnis2)

      (* Copy local result variables to process variables *)
      Pvar1 := Ergebnis1
      Pvar2 := Ergebnis2
   end
end

Note

The content of a string variable cannot be passed to a function. In this case the pointer to the string variable must be transferred, i.e., a change in the function has a direct effect on the string variable itself -> Call by reference.

Constant and variable transfer parameters in the format “string”

The programming language in PROCON-WEB requires transfer parameters of the “String” type in many functions. These transfer parameters can be both variable and constant. Variable parameters are local or global text variables, constant parameters are texts in single quotation marks (‘xx’)

(* The CopyFiles function copies one or more files from a source directory to a target directory. The
source should be constant, the target should be defined via a variable.  *)

PROGRAM
var ziel[20] : string
var return : integer
begin
   ziel := 'c:\tmp\project.pcs'
   return := CopyFiles('C:\PCSPRJCT\Project.pcs', ziel)
end

Note

The text variable “target” is defined locally, i.e. only valid in this function. You could also use a globally defined text variable (from the text variable editor of the picture assembly) and change it interactively, for example in a process picture.

Transiente variables

Transiente variables can now be declared, the value of which is reset to the default value after each “script run”.

This was the new keyword transient var introduced. This allows variables to be defined whose value is reset to the default after each script run.

In contrast, “normal” variables retain their value between script calls.The variable is reset in the following cases:

Event-oriented script (Global or client-specific): Before every single run of the script

Cyclic image script: When the picture opens. The variable then retains the value while the picture remains open. It is reset when it is closed and reopened

Cyclic global script: When the script is started initially (when the project starts) The variable then retains the value during the project runtime until the project is ended. In other words, for global cyclic scripts, a volatile variable behaves like a normal variable, so it makes no difference whether volatile is used or not

PROGRAM

var normalVar : integer
transient var volVar : integer

BEGIN
  normVar := normVar + 1
  volVar := volVar + 1
END

Script import functionality

In PROCON-WEB there is now the possibility to reference and use functions and global variables from other script files. Four new keywords have been added for this purpose.

Keywords
import	Imports another script
Import ..as ..	Imports another script with an alias name
private	Functions and variables defined with “private” cannot be imported
.	Dot operator to access functions and variables of imported scripts

Note

The import statement imports another script either by name or an alias

Important

The import statement MUST come directly after PROGRAM.

import <SKRIPTNAME>

import <SKRIPTNAME> as <ALIASNAME>

To hide certain variables and functions in the imported script, you can use the keyword private can only be defined for use within the script.

private var <VARIABLENNAME>

private function <FUNCTIONNAME>( … )

The use of the script names results in new restrictions for the script names:

• Script names must be unique

• Script names must not have the same name as process variables

• Script names cannot be named like functions or variables within the script

• Script names may only contain letters (A… Z || a … z || _) or numbers (0..9), no other special characters or umlauts

Otherwise, this leads to compiler errors

PROGRAM

var ExportVar : integer
private var TestVar : integer

function ExportFnc(input : integer) : integer
BEGIN
  ExportVar := input
  ExportFnc := input + 1
END

private function TestFnc() : integer
BEGIN

END

BEGIN

END

(* And here is a program that uses this script: *)
PROGRAM

import LibrarySkript as Lib

var testVar2,testVar3 : integer

BEGIN
  testVar2 := Lib.ExportFnc(3)
  testVar3 := Lib.ExportVar
END

The script is addressed via the alias “Lib”, the declared variable TestVar and the function TestFnc () can NOT be used for the script, because they are declared private.The ExportVar variable and the ExportFnc () function can, however, be used.

break and continue

There are now the two keywords break and continue, which can be used in loops.

Keywords
continue	Cancels the current loop pass and continues with the next pass
break	breaks off the complete loop

PROGRAM

var incr : integer

BEGIN
  for incr := 0 to 30 do
  begin
    if (incr = 10) then
    break
       else if (incr = 20) then
       continue

      DefaultNumericVariable := incr
  end
END

Division by 0

If a division by 0 is carried out in a script, the script is aborted with the system alarm 996611 (ScriptServer: Division by zero in script% s).

The script exits at the point where the error occurred, and the rest of the script’s code is no longer executed. The exchange of process variables, which normally takes place at the end of a script, does NOT take place either, i.e., the normally assigned and modified process variables of the script are retained at their value before the script is executed.

Exceptions are function calls that lead to process variable changes when they are called: Delay (), WriteToProcess (), Alert () and DBSend () / DBRecieve (), SetValue () and SetTagProperty ().

If these functions are called in the script BEFORE division by zero, the process variable exchange takes place correctly at this point. Any variable assignment after one of the above functions and subsequent division by zero will of course not be carried out.

PROGRAM
var zeroValue : Integer
BEGIN
    TestPvar := 1 (*TestPvar is global variable *)
    Delay(10) (* TestPvar is now 1 *)

    TestPvar := 2
    WriteToProcess(1) (* TestPvar is now 2 *)

    zeroValue := 0
    TestPvar := 10 / zeroValue (*DIVISION BY ZERO!!! Skript is aborted here*)

    (*The following code is NEVER executed*)
    WriteToProcess(1)
    TestPvar := 3
    WriteToProcess(1) (*TestPvar is still 2*)
END

Function description

The functions described below are firmly integrated functions that provide some of the services of the runtime system. Within the individual functions, it is defined whether this is also available in the IoT variant or only in SCADA.

Alphabetische Übersicht

Abs	Calculation of the absolute amount
AbsToTime	Conversion of time
AddPicture	Add a picture
Alert / AlertAsync	Setting, acknowledging and resetting alarms
Alert / AlertAsync	Setting, acknowledging and resetting alarms
Append	Open an existing text file to append
AppendString	Function to append a number to a string and another string that can be used as a separator for concatenation
Arccos	Arccosine of an angle
Arcsin	Arc sine of an angle
Arctan	Arc tangent of an angle
Arctan2	Arctangent with two parameters of an angle
Assign	Assigning a text file to a file variable
AssignUnsafe	Assigning a text file to a file variable
BackCopyFiles	Copying files asynchronously in the background
CalculateDIN8743	Function to start the evaluation
CalculateStatistic	Function to start the evaluation
ChangeAllPictures	Function for changing all pictures
ChangePicture	Function for changing the image
ChangeProject	Changes the current project
Close	Closing a text file
ClosePicture	Cloase an image
CompareFiles	Function for comparing two files for size or time stamp
CopyFiles	Copy a text file
Cos	Cosine of an angle
Cosh	Hyperbolic cosine of an angle
CreateDir	Creation of directories
CreateUser	Create User
DateAdd	Function for adding specific time periods to the absolute system time.
DateToAbs	Function for converting a date in string format to an absolute value
DateToString	Function for converting dates and times to a string
DateStringAdd	Function for adding specific time periods to the absolute system time.
DBCloseODBC	Close the connection to the ODBC driver
DBCopy	Function for copying a data record from a database.
DBCopyIndex	Function for copying a data record from one database to another database using the index data record.
DBDelete	Function for deleting a data record from a database.
DBDeleteIndex	Deleting records from the database using the record index
DBFetchTabODBC	Load data record from selected quantity
DBFieldCount	The number of fields in a data record
DBFieldType	Define type of the data field”
DBFindRecord	Function for searching for a data record with a certain name in a database.
DBGetDataODBC	Read data elements from ODBC buffer
DBGetErrorODBC	Get error texts for the last ODBC error
DBGetInfoDataODBC	Determine the structure of a data element in the selected table
DBGetInfoTabODBC	Determine the number of selected data records and data elements
DBGetStampODBC	Read time stamp from ODBC buffer
DBNotifyDataChanged	Function to inform all clients (grids) about a change in the transferred data management.
DBOpenODBC	Establish a connection to the ODBC driver
DBOpenODBCConnection	Connect to an ODBC data source
DBProcedureODBC	Execute an ODBC procedure
DBPutDataODBC	Change data elements from ODBC buffer
DBPutStampODBC	Write time stamp from ODBC buffer
DBReceive / DBSyncReceive / DBReceiveIndex	Receive data records from the process for writing to the database
DBReceive / DBSyncReceive / DBReceiveIndex	Receive data records from the process for writing to the database using the data record index
DBRecipeChangeState	Change the status of a recipe
DBRecipeChangeStateIndex	Change the status of a recipe via the state index
DBRecipeChangeVersion	Change the version of a recipe
DBRecipeChangeVersionIndex	Change the version of a recipe
DBRecipeChangeName	hange the name of a recipe
DBRecipeChangeNameIndex	Change the name of a recipe via the name index
DBRecordName	Read the name of a record from the database; Number of records in the database
DBSend / DBSyncSend / DBSendIndex	Sending records from the database into the process
DBSend / DBSyncSend / DBSendIndex	Sending records from the process for writing to the database using the data record index
DBSendSQLODBC	Send the SQL statement to the ODBC driver
DBReceive / DBSyncReceive / DBReceiveIndex	Empfang von Datensätzen aus dem Prozess in Datenbank mit Anforderung der akt. Treiber-Werte durch das VisuCompact
DeleteFiles	Deleting files
DeleteTree	Deleting directories
DeleteUser	Delete User
DVExportView	Export of data from a data recorder view
ExistFile	Function to check whether a file exists or not
Exp	Exponential function e ^ x
FillImageView	Deletes an ImageView and refills it
FillPictureArea	Deletes the pictures of a PictureArea and refills them
GetIniString	Returns a string from an INI file
GetDefaultPrinterByIndex	Reads the default printer (transfer of the index)
GetDefaultPrinterByName	Reads the default printer (transfer of the name)
GetLanguage	Function for inquiring about the current operating language
GetPrinterCount	Reads the number of printers from the system
GetPrinterName	Reads the name of a printer
GetSubString	Returns a substring from a source string
GetTagProperty	Reading the current value of a tag property
GetUserGroup	Read out user group
GetUserInfo	Read out user information
GetValue	Reading out the content of a variable
IsNumeric	Function to query whether an expression can be evaluated as a number
Length	Finding the length of a string
Ln	10er logarithm
Log	10er logarithm
LogEventString	Function for writing a string in the logbook
Login	Log-in user
Logout	Log-out user
MoveFiles	Moving files, directories
NewPicture	Add new picture or change picture
OpenBrowser	Open a url
OpenPicture	Open an image
Pos	Finding a string in a string
Pow	Power function x ^ y
PrintPicture	Print an image
Random	Create a random number
Randomize	Initialization of the random generator
Read	Assigning a text file to a file variable
ReadLine	Reads a line from a file and switches the file position pointer to the next line
ReadFromProcess	Function for reading the process variables used in the script
Reset	Öffnen einer Text-Datei zu einer Dateivariablen
Rewrite	Open a text file to a file variable
SetDefaultPrinterByIndex	Sets the default printer (transfer of the index)
SetDefaultPrinterByName	Sets the default printer (transfer of the name)
SetIniString	Sets a string in an INI file
SetLanguage	Set a new language
SetTagProperty	Setting the current value of a tag property
SetUserGroup	Add / delete user to user group
SetUserInfo	Set user information
SetUserPassword	Set password
SetValue	Copy the content of a variable to another one
Sin	Sine of an angle
Sinh	Hyperbolic sine of an angle
SpecAlert	Function to open the re-specifying dialogue
Special	Triggering special functions
Sqrt	Square root
StatisticClose	Function for releasing the allocated memory
Str	Convert a number to a string
StringEndsWith	Function to query whether the beginning of this string instance matches the specified string
StringFormat	Function for formatting an integer / real that is formatted according to the instructions in a string format expression
StringIndexOf	Function returns the zero-based index of the first occurrence of a specified Unicode character or Unicode string
StringInsert	Function to insert a string at the specified index position
StringToLower	Function for converting a string to lower case
StringRemove	Function to remove a specified number of characters from the current string
StringReplace	Function for replacing a Unicode character or a string in a character string
StringRegExIsMatch	Function to proof, if an expression is in a certain string
StringStartsWith	Function to query whether the beginning of this string instance matches the specified string
StringTemplate	Function for inserting values into a character string
StringToInt	Function for converting a string into an integer
StringToReal	Function for converting a string into a number with decimal places
StringTrim	Removes all named positions (left, right or both sides) where the letter to be removed occurs in a string
StringToUpper	Function for converting a string to upper case
Tan	Tangent of an angle
Tanh	Hyperbolic tangent of an angle
Time	Read system date and time
TimespanToString (onlySCADA)	Function to convert milliseconds to seconds, hours, and minutes
TimeToAbs	Conversion of time
TimeUtcToLocal	Convert UTC to local time
TimeLocalToUtc	Converting the local time into UTC time
Val	Convert a string to a number
ValidPath	Checks whether the specified file path exists
WinExec	Starting a program
Write	Writing data to a text file to a file variable
WriteToProcess	Function for writing the process variables used in the script

Function groups

• Fault processing functions

• File processing / directory functions (only SCADA)

• Data management functions

• Chart-/datalogger funtions (only SCADA)

• Functions for recipe management

• functions of the ODBC interface

• String processing functions

• Math functions

• Trigonometric functions

• Time & date functions

• User management functions

• Image processing functions

• Process variable functions

• Special functions

• External function call / program start

• Other functions

• DIN 8743 functions

Fault processing functions

Fault processing functions
Alert / AlertAsync	Setting, acknowledging and resetting alarms
SpecAlert	Function to open the re-specifying dialogue

File processing / directory functions

File processing / directory functions
Append	Open an existing text file to append data
Assign	Assigning a text file to a file variable
AssignUnsafe	Assigning a text file to a file variable
BackCopyFiles	Copying files asynchronously in the background
Close	Closing a text file
CopyFiles	Copy a text file
CompareFiles	Function for comparing two files for size or time stamp
CreateDir	Creation of directories
DeleteFiles	Deleting files
DeleteTree	Deleting directories
ExistFile	Function to check whether a file exists or not
GetIniString	Returns a string from an INI file
MoveFiles	Moving files, directories
Read	Assigning a text file to a file variable
ReadLine	Reads a line from a file and switches the file position pointer to the next line
Reset	Öffnen einer Text-Datei zu einer Dateivariablen
Rewrite	Open a text file to a file variable
SetIniString	Sets a string in an INI file
ValidPath	Checks whether the specified file path exists
Write	Writing data to a text file to a file variable

Data management functions

Data management functions
DBAccessValue	Define type of the data field”
DBCopy	Function for copying a data record from a database.
DBCopyIndex	Function for copying a data record from one database to another databaseusing the index data record.
DBDelete	Function for deleting a data record from a database.
DBDeleteIndex	Index of the data set in the database 0..max-1 data sets.
DBFieldCount	The number of fields in a data record
DBFieldType	Name of a data record from the database”
DBFindRecord	Function for searching for a data record with a certain name in a database.
DBReceive / DBSyncReceive / DBReceiveIndex	Receive data records from the process for writing to the database
DBReceive / DBSyncReceive / DBReceiveIndex	Receive data records from the process for writing to the database using the data record index
DBRecordName	Read a name of a data record from the database”
DBSend / DBSyncSend / DBSendIndex	Sending records from the database into the process
DBSend / DBSyncSend / DBSendIndex	Sending records from the process for writing to the database using the data record index
DBReceive / DBSyncReceive / DBReceiveIndex	Receipt of data records from the process into the database with request of the current values by the VisuCompact from the driver
DBSend / DBSyncSend / DBSendIndex	Sending records from the database into the process
DBNotifyDataChanged	Function to inform all clients (grids) about a change in the transferred data management.

Chart function

Chart-/data logger functions
DVExportView	Export of data from a data recorder view

Functions for recipe management

Functions for recipe management
DBRecipeChangeState	Change the status of a recipe
DBRecipeChangeStateIndex	Change the status of a recipe
DBRecipeChangeVersion	Change the version of a recipe
DBRecipeChangeVersionIndex	Change the version of a recipe
DBRecipeChangeName	hange the name of a recipe
DBRecipeChangeNameIndex	hange the name of a recipe

Functions for the ODBC interface

Functions of the ODBC interface
DBOpenODBC	Establish a connection to the ODBC driver
DBOpenODBCConnection	Connect to an ODBC data source
DBCloseODBC	Close the connection to the ODBC driver
DBSendSQLODBC	Send the SQL statement to the ODBC driver
DBProcedureODBC	Execute an ODBC procedure
DBFetchTabODBC	Load data record from selected quantity
DBGetDataODBC	Read data elements from ODBC buffer
DBPutDataODBC	Change data elements from ODBC buffer
DBGetStampODBC	Read time stamp from ODBC buffer
DBPutStampODBC	Write time stamp from ODBC buffer
DBGetInfoTabODBC	Determine the number of selected data records and data elements
DBGetInfoDataODBC	Determine the structure of a data element in the selected table
DBGetErrorODBC	Get error texts for the last ODBC error

String processing functions

String processing functions
AppendString	Function to append a number to a string and another string that can be used as a separator for concatenation
DateToStr	Change of date and time Time information in a string
GetSubString	Returns a substring from a source string
IsNumeric	Function to query whether an expression can be evaluated as a number
Length	Finding the length of a string
Pos	Finding a string in a string
Str	Convert a number to a string
StringEndsWith	Function to query whether the end of this string instance matches the specified string
StringFormat	Function for formatting an integer / real that is formatted according to the instructions in a string format expression
StringIndexOf	Function returns the zero-based index of the first occurrence of a specified Unicode character or Unicode string
StringInsert	Function to insert a string at the specified index position in the current string
StringToLower	Function for converting a string to lower case
StringRemove	Function to remove a specified number of characters from the current string
StringReplace	Function for replacing a Unicode character or a string in a character string
StringRegExIsMatch	Function to proof, if an expression is in a certain string
StringStartsWith	Function to query whether the beginning of this string instance matches the specified string
StringTemplate	Function for inserting values into a character string
StringToInt	Function for converting a string into an integer
StringToReal	Function for converting a string into a number with decimal places
StringTrim	Removes all named positions (left, right or both sides) where the letter to be removed occurs in a string
StringToUpper	Function for converting a string to upper case
Val	Convert a string to a number

Math functions

Math functions
Exp	Exponential function e ^ x
Ln	10er logarithm
Log	10er logarithm
Pow	Power function x ^ y
Sqrt	Square root
Abs	Calculation of the absolute amount

Trigonometric functions

Trigonometric functions
Cos	Cosine of an angle
Sin	Sine of an angle
Tan	Tangent of an angle
Arccos	Arccosine of an angle
Arcsin	Arc sine of an angle
Arctan	Arc tangent of an angle
Arctan2	Arctangent with two parameters of an angle
Cosh	Hyperbolic cosine of an angle
Sinh	Hyperbolic sine of an angle
Tanh	Hyperbolic tangent of an angle

Time & date functions

Time & date functions
AbsToTime	Conversion of seconds into date and time
TimeToAbs	Conversion of date and time in seconds
Time	Read system date and time
TimeUtcToLocal	Convert UTC to local time
TimeLocalToUtc	Converting the local time into UTC time
DateAdd	Function for adding specific time periods to the absolute system time
DateStringAdd	Function for adding specific time periods to the absolute system time
DateToString	Function for converting dates and times to a string
DateToAbs	Function for converting a date in string format to an absolute value
TimespanToString (onlySCADA)	Function for converting milliseconds to seconds, hours and minutes

User management functions

User management functions
Login	Log-in user
Logout	Log-out user
CreateUser	Create User
DeleteUser	Delete User
SetUserPassword	Set password
GetUserGroup	Read out user group
SetUserGroup	Add / delete user to user group
GetUserInfo	Read out user information
SetUserInfo	Set user information

Image processing functions

Image processing functions
AddPicture	Add a picture
ChangePicture	Function for changing the image
NewPicture	Add new picture or change picture
OpenPicture	Open an image
ClosePicture	Cloase an image
PrintPicture	Print an image
ChangeAllPictures	Function for changing all pictures
FillImageView	Deletes an ImageView and refills it
FillPictureArea	Deletes the pictures of a PictureArea and refills them

Process variable functions

Process variable functions
GetTagProperty	Reading the current value of a tag property
ReadFromProcess	Function for reading the process variables used in the script
SetTagProperty	Setting the current value of a tag property
WriteToProcess	Function for writing the process variables used in the script
GetValue	Reading out the content of a variable
SetValue	Copy the content of a variable to another one

Special functions

Special functions
Special	Triggering special functions

External function call / program start

External function call / program start
WinExec	Starting a program

Other functions

Other functions
Delay	Delays the script to be executed
LogEventString	Function for writing a string in the logbook
SetLanguage	Set a new language
Random	Create a random number
Randomize	Initialization of the random generator
ChangeProject	Changes the current project
GetLanguage	Function for inquiring about the current operating language
OpenBrowser	Open a url

DIN 8743 functions

DIN 8743 functions
CalculateDIN8743	Function to start the evaluation
CalculateStatistic	Function to start the evaluation
StatisticClose	Function for releasing the allocated memory

Printer handling functions

Printer handling functions
GetPrinterCount	Reads the number of printers from the system
GetPrinterName	Reads the name of a printer
GetDefaultPrinterByIndex	Reads the default printer (transfer of the index)
GetDefaultPrinterByName	Reads the default printer (transfer of the name)
SetDefaultPrinterByIndex	Sets the default printer (transfer of the index)
SetDefaultPrinterByName	Sets the default printer (transfer of the name)

Fault processing functions (only SCADA)

Alert / AlertAsync

The “Alert” or “AlertAsync” function is used to set, quitt and reset faults. There is no longer any difference between the two functions. Scripts are always processed from starktionsdefinitiont to finish without interruption. A user is only sent when quitting or commenting an alert. With setting an alert, that is not possible.

Important

Before being called, the functions write the process variables of the script to the process, since dynamic text portions of alarms may have changed and reads back the process variables again after calling.

Important

In the client / server system, an immediate reset of a previously triggered alarm cannot be implemented due to the networked systems

Function definition: Alert(set_reset, number : integer) : integer

AlertAsync (set_reset, number : integer) : integer

Parameter:
set_reset	Index for action
	0 = reset all faults
	1 = set specified fault
	2 = reset specified fault
	3 = acknowledge all faults
	4 = acknowledge specified fault
Number	Number of the fault to reset / set
Return values:
-1	If function was carried out successfully
0	If function was carried out successfully

with index for action 1, 2 or 4 the return value (executed for alarm action)is the same as the corresponding alarm instance ID

Example

PROGRAM

(*-----------------------------------------------*)
(* Macro for triggering alarm 100 via a constant *)
(*-----------------------------------------------*)
function macro_02:integer
begin
    Alert(1,100)
end

(*-----------------------------------------------*)
(* Macro for resetting an alarm via process var. *)
(*-----------------------------------------------*)
function macro_03 :integer
var hilfsvar : integer
begin
    hilfsvar := Prozessvariable1
    Alert(2,hilfsvar)
End

BEGIN
END

Important

With index “0” for the action, all existing project and system alarms are checked and reset, therefore time-consuming!

SpecAlert

Function to open the re-specification dialog. Optionally filtered by unit

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: SpecAlert(Unit: string) : integer

Parameter:
Unit	Name of the unit to be filtered by
Return values:
0	if the dialogue was opened
< 0	if the dialogue cannot be opened

Example

PROGRAM

FUNCTION DoAlertSpec(unit : string) : integer
BEGIN
    DoAlertSpec := SpecAlert(unit)
END

BEGIN
    DoAlertSpec('')
    DoAlertSpec('Maschine1.Unit1')
END

File processing / directory functions (only SCADA)

Append

Function to open an existing text file to append further data. Append opens the file that was previously linked to the text file variable by Assign and puts the current position within this file at the end. If the file does not exist, it will be created beforehand. The following write actions therefore append new data.

Function definition:

Append(File : Text) : integer

Parameter:
Name	Name of the file to be opened
Return values:
0	if file cannot be opened
< 0	if file cannot be opened

Example

PROGRAM
var datei1 : text, error : integer

function WriteFile:integer
(* Opens file TEXTDAT.TXT and writes temperature switch-off value = value *)
var i:integer

begin
    error := Assign(datei1,'C:\TMP\TEXTDAT.TXT')
    (* Connect the file to a file variable *)
    if (error >= 0) then
    begin
        error := Append(datei1)
        (* Open the existing file for attachment *)
        if (error >= 0) then
        begin
            error := Write(datei1, Temperaturabschaltwert:30,
                        Prozessvariable1:5:0)
            (* Write constant string and process value *)
            error := Close(datei1)
            (* Close opened file *)
        end
    end

    WriteFile := 0
    logi1 := 0
end

begin
    if (logi1 = 1) then WriteFile
end

Assign

Function for assigning a text file to a file variable.Assign assigns the file specified by name to the file variable “File”. All further operations with File refer to this file until File is assigned to another external file by calling Assign again.

Function definition: Assign(File : Text, Name : string) : integer

Parameter:
File	File variable for further file access
Name	Name of the file to be opened
Return values:
0	if file cannot be opened
<0	if file could not be allocate

Example

PROGRAM
var datei1 : text, error : integer

function WriteFile:integer
(* Opens file TEXTDAT.TXT and writes temperature switch-off value = value *)
var i:integer
begin
    error := Assign(datei1,'C:\TMP\TEXTDAT.TXT')
    (* Connect the file to a file variable *)
    if (error >= 0) then
    begin
        error := Append(datei1)
        (* Write constant string and process value *)
        if (error >= 0) then
        begin
            error := Write(datei1, Temperaturabschaltwert:30,
                        Prozessvariable1:5:0)
            (* Konstanten String und Prozesswert schreiben *)
            error := Close(datei1)
            (* Close opened file *)
        end
    end
    WriteFile := 0
    logi1 := 0
end

begin
    if (logi1 = 1) then WriteFile
end

Note

Up to max. 20 assign commands can be made.

AssignUnsafe

The file access functions that begin with Assign are too slow. The reason for this is, that the file is closed after each ReadLine and opened again the next time. A file with many thousands of lines of text needs a long time to be read.AssignUnsafe keeps the file open until the file is explicitly closed with a Close command.

AssignUnsafe hält die Datei so lange geöffnet, bis die Datei explizit per Close-Befehl geschlossen wird.

Important

The calibration engineer must ensure that the file is closed. Simultaneous write access to a file is no longer possible, as is the case with Assign.

AssignUnsafe works in the same way as Assign.

Note

Increasing the “Const Lines” can lead to a significantly higher performance than using AssignUnsafe.

Function definition: AssignUnsafe(File : Text, Name : string) : integer

Parameter:
File	File variable for further file access
Name	Name of the file to be opened
Return values:
0	if file cannot be opened
<0	if file could not be allocate

BackCopyFiles

Function to copy files in the background. At the time of the call, all specified files are recorded and copied step by step. If the file currently to be copied changes, it is copied again until a complete copy has been made without changes. If the file has not been copied after n attempts to copy it, it is skipped.

The copy function runs in parallel in the background and must be checked by means of status queries. The copy function can only be used once in the project at the same time. The use of wildcards is possible. The size of the sub-blocks to be transferred is determined via the menu item Configuration, [GLOBAL] CopyBufferSize.

Function definition: BackCopyFiles (Source, Destination : string, Command : integer) : integer

Parameter:
Source	Source filenames with wildcards
Destination	Target file names with wildcards
Command	Command parameters
	0 = copy files
	1 = query copy status
	2 = query error code
	3 = cancel copy action
Return values:
	The function value has two meanings depending on the command
Command 0, 1, 3
0	last copy function ended correctly
1	Copy function not active
2	Copy function active
-1	a bug in copy function
Command 2
0	no errors in copy function, but in event code parameters
<>0	defined error code

Example

PROGRAM
(*------------------------------------------------------*)
(*  Function for outputting the error code if within
    the background copying an error occurred            *)
(*------------------------------------------------------*)
function look_error:integer
begin
    Fehlercode := BackCopyFiles(ap_copy,ap_copy_ziel,2)
    (* Output of the error code *)
End

(*------------------------------------------------------*)
(*  function CopyAlarmsToServer: Copies the
    Alarm file "APTT ????. DBF". For DD the date of
    the previous day used. First is in function
    checked whether the BackCopy command is still
    active. Then the copying is initiated, monitored
    and, finally, is repeatedly checked whether the
    command is available again. The function is
    called cyclically from the main program.            *)
(*------------------------------------------------------*)
function CopyAlarmeZumServer : integer
begin
    CopyAlarmeZumServer := 0
    if Schritt = 0 then
    begin
        Rueckgabe := BackCopyFiles(ap_copy,ap_copy_ziel,1)
        (* Test function active? *)
        if Rueckgabe = -1 then
        begin
            look_error()
            Schritt := 0 (* Function inactive *)
            CopyAlarmeZumServer := 1
            Alert(1,9903)
            KeinServer:=1
        end
        if Rueckgabe = 1 then
        begin
            Schritt := 1 (* Function inactive *)
        end
    end
    else
    begin
        if Schritt = 1 then
        begin
            Rueckgabe := BackCopyFiles(ap_copy,ap_copy_ziel,0)
            (* Copy alarms -> Server *)
            if Rueckgabe = -1 then
            begin
                look_error()
                Schritt := 0 (* Function inactive *)
                CopyAlarmeZumServer := 1
                if (Fehlercode <> 2) then
                begin
                    Alert(1,9903)
                    KeinServer:=1 (* Display "No server" *)
                end
            end
            else
            begin
                Schritt := 2
            end
        end
        else
        begin
            if Schritt = 2 then
            begin
                Rueckgabe := BackCopyFiles(ap_copy,ap_copy_ziel,1)
                (* Test function active? *)
                if Rueckgabe = -1 then
                begin
                    look_error()
                    Schritt := 0 (* Function inactive *)
                    CopyAlarmeZumServer := 1
                    if (Fehlercode <> 2) then
                    begin
                        Alert(1,9903)
                        KeinServer:=1 (* Display "No server" *)
                    end
                end
                else
                begin
                    Schritt := 2
                end
            end
            else
            begin
                if Schritt = 2 then
                begin
                    Rueckgabe :=
                        BackCopyFiles(ap_copy,ap_copy_ziel,1)
                    (* Test function active? *)
                    if Rueckgabe = -1 then
                    begin
                        look_error()
                        Schritt := 0 (* Function inactive *)
                        CopyAlarmeZumServer := 1
                        Alert(1,9903)
                        KeinServer:=1
                    end
                    if Rueckgabe = 0 then
                    (* Copy is complete *)
                    begin
                        Schritt := 3
                    end
                end
                else
                begin
                    if Schritt = 3 then
                        begin
                        Rueckgabe :=
                            BackCopyFiles(ap_copy,ap_copy_ziel,1)
                        (* Test function active? *)
                        if Rueckgabe = -1 then
                        begin
                            look_error()
                            Schritt := 0 (* Function inactive *)
                            CopyAlarmeZumServer := 1
                            Alert(1,9903)
                            KeinServer:=1
                        end
                        if Rueckgabe = 1 then
                        begin
                            Schritt := 0 (* Function inactive *)
                            CopyAlarmeZumServer := 1
                        Alert(2,9903)
                    end
                end
            end
        end
    end
end

BEGIN
    CopyAlarmeZumServer()
END

Close

Function to close a text file.The file previously opened with Reset, Rewrite or Append is brought up to date, ie data that has not yet been written is written.

Function definition: Close(File : Text) : integer

Parameter:
File	File variable for further file access
Return values:
0	if the file was closed
<0	if the file was not closed

Example

Program

var datei1 : text
    error : integer

function WriteFile:integer
(* Opens file TEXTDAT.TXT and writes temperature switch-off value = value *)
var i:integer
begin
    error := Assign(datei1,'C:\TMP\TEXTDAT.TXT')
    (* Connect the file to a file variable *)
    if (error >= 0) then
    begin
        error := Append(datei1)
        (* Open the existing file for attachment *)
        if (error >= 0) then
        begin
            error := Write(datei1, Temperaturabschaltwert:30,
                        Prozessvariable1:5:0)
            (* Write constant string and process value *)
            error := Close(datei1)
            (* Close opened file *)
        end
    end
    WriteFile := 0
    logi1 := 0
end

begin
    if (logi1 = 1) then
        WriteFile
end

Note

The connection between the file tag and the file assigned with Assign is not broken.

CopyFiles

Function for copying files

Function definition: CopyFiles(SourceName, DestName : string) : integer

Parameter:
SourceName	Name of the source file (s) with wildcards “*“ and “?“
DestName	Name of the destination file (s) with wildcards “*“ and “?“
Return values:
>= 0	Number of files copie
-1	General error

Example

Program

var ret1 : integer

(*-------------------------------------------------*)
(* Macro to copy all files from directory A to B   *)
(*-------------------------------------------------*)
function macro_06:integer
begin
    ret1 := CopyFiles('C:\BAT\*.*','C:\BAT_SAVE\*.*')
end

(*-------------------------------------------------*)
(* Macro for copying source files to target files  *)
(*-------------------------------------------------*)
function macro_08:integer
begin
    ret1 := CopyFiles(quelle, ziel)
end

begin
end

Note

The source and target directories must exist. When copying large amounts of data, please note that no other actions can take place at this point.

CompareFiles

Function for comparing two files for size or time stamp

Function definition: CompareFiles(StrFile1, StrFile2 : string, Mode : integer, Delta : real) : integer

Parameter:
StrFile1	File name with complete path
StrFile2	File name with complete path
Mode	Comparison mode
	file size comparison
	Time comparison of the creation time stamp
	Time comparison of the change time stamp
	3 = Time comparison of the last time stamp of access (only NTFS)
Delta	Delta window for time comparisons in msec
Return values:
-3	invalid mode specification
-2	StrFile2 does not exist
-1	StrFile1 does not exist
0	both the same
1	StrFile1 smaller or older StrFile2
2	StrFile1 larger or younger StrFile2

Example

(* Extract from a function that compares source and target and brings both up to date *)

Program
var return : integer

begin
    return := CompareFiles(Quelle,Ziel,0,0.0) (* Compare source and target file size *)
    if return = 0 then (* Source and target the same -> end comparison and copying *)
    begin
        QgleichZ[i] := 1
        Alert(1,2089) (* Message SF = TF -> end comparison *)
        Alert(2,2089)
    end
    else
    if return = -1 then (* SF not available *)
    begin
        return := ExistFile(Ziel) (* SF not there, TF there? *)
        if return = 0 then (* TF is there -> adjustment *)
        begin
            Alert(1,2096) (* SF missing TF there -> adjustment *)
            Alert(2,2096)
            return := CopyFiles(Ziel,Quelle)
            if return < 0 then
            begin
            Alert(1,2069) (* Error during data synchronization *)
            Alert(2,2069)
            end
        end
        else
        begin
            Alert(1,2087) (* Message SF not available *)
            Alert(2,2087)
        end
    end

            Alert(1,2087) (* Message SF not available *)
            Alert(2,2087)
        end
    end
    else
    if return = -2 then (* Target does not exist *)
    begin
        Alert(1,2091) (* Message TF not available *)
        Alert(2,2091)
        return := CopyFiles(Quelle,Ziel)
        if return < 0 then
        begin
            Alert(1,2069) (* Error during data synchronization *)
            Alert(2,2069)
        end
    end
    else
    if return = 1  then (* Compare file there but S < T -> T -> S *)
    begin
        Alert(1,2097) (* Compare message SF <TF -> *)
        Alert(2,2097)
        return := CopyFiles(Ziel,Quelle)
        if return < 0 then
        begin
            Alert(1,2069) (* Error during data synchronization *)
            Alert(2,2069)
        end
    end
    if return = 2  then (* File there but S> T -> synchronize S -> T *)
    begin
        Alert(1,2090) (* Message SF> TF -> compare *)
        Alert(2,2090)
        return := CopyFiles(Quelle,Ziel)
        if return < 0 then
        begin
            Alert(1,2069) (* Error during data synchronization *)
            Alert(2,2069)
        end
    end
    if return = 2  then (* File there but S> T -> synchronize S -> T *)
    begin
        Alert(1,2090) (* Message SF> TF -> compare *)
        Alert(2,2090)
        return := CopyFiles(Quelle,Ziel)
        if return < 0 then
        begin
            Alert(1,2069) (* Error during data synchronization *)
            Alert(2,2069)
        end
    end
end

CreateDir

Function for creating directories.

Function definition: CreateDir(Name : string) : integer

Parameter:
Name	Name of the directory to be created
Return values:
0	If function was carried out successfully
< 0	If function was carried out successfully

Example

PROGRAM

(*----------------------------------*)
(* Macro to create a file directory *)
(*----------------------------------*)
function macro_11:integer
var error,
    error1 :integer

begin
    error := CreateDir('C:\PROJECT')
    error1 := CreateDir('C:\PROJECT\DATEN')
    if ((error < 0) or (error1 < 0)) then
    begin
        Alert(1,100) (* Alarm: Directory cannot *)
        Alert(2,100) (* be opened *)
    end
end

begin
end

Important

If only one directory is to be created or a directory is to be appended to an existing path, then the command must only be executed once. If, on the other hand, you want to create a more detailed path, the command must be executed several times in a row (see example).

DeleteFiles

Function to delete files.

Function definition: DeleteFiles(Name : string) : integer

Parameter:
Name	Name of the file (s) to be deleted with wildcards ”*” and ”?”
Return values:
> 0	Number of files deleted
< 0	when deletion has errors
-1	if no file found to delete
-2	if file no longer found when deleting
-3	if path does not match (source or target)
-4	if file cannot be opened
-5	if no access rights|
	further errors not documented

Example

Program

(*-----------------------------------------------------*)
(*  Delete all ASCII protocols
    The files are as follows in the directory
    C: \ DATEN \ *. * stored: PROTttmm.TXT
    This macro is started by the user                  *)
(*-----------------------------------------------------*)
function macro_12:integer
var error :integer
begin
    error := DeleteFiles('C:\DATEN\PROT????.TXT')
    if (error < 0) then
    begin
        Alert(1,10) (* Error occurred while deleting *)
        Alert(2,10)
    end
end

begin
end

DeleteTree

Function for deleting directories and their content as well as all subdirectories and their content.

Function definition: DeleteTree(Name : string) : integer

Parameter:
Name	Name of the directory tree to be deleted
Return values:
0	If function was carried out successfully
< 0	If function was carried out successfully

Example

Program

(*----------------------------------------------------------*)
(*  Delete the data directory with all
    subdirectories and their content                        *)
(*----------------------------------------------------------*)
function macro_13:integer
var ret1 : integer

begin
    ret1 := DeleteTree('C:\DATEN')
    (*  "ret1" is a process tag which shows the operator a
        status message                                      *)
end

begin
end

ExistFile

Function to check whether a file exists or not

Function definition: ExistFile(StrName : string) : integer

Parameter:
StrName	File name with complete path
Return values:
-3	Drive or UNC-Name not found
-2	path not found
-1	File does not exist
0	file available

Example

PROGRAM

VAR return : integer

BEGIN
    return := ExistFile(Ziel)
    if return = 0 then
    begin
        Alert(1, 2096)
        Alert(2, 2096)
END

GetIniString

Function for reading a string from an INI file.

Function definition: GetIniString(Filename, Section, Key, Default, ReturnString : string) : integer

Parameter:
Filename	File name of the ini file with file extension and directory.If no directory is specified, the file is searched for in the project directory. (Directory with file name max. 256 characters
Section	Section in the file (1 to max. 256 characters); Specification of the section without brackets
Key	Key in the file (1 to max. 256 characters)
Default	ReturnString is set to the default if ReturnString cannot be determined.
ReturnString	ad string
Return values:
0	Function carried out without errors
-1	Directory or file not found
-6	Section not set
-7	Key not set

Example

PROGRAM

VAR return : integer

BEGIN
    if GetIniStringStart then
    begin
        return :=  GetIniString(Filename, Section, Key,
                    Default, ReturnString)
        GetIniStringStart := 0
    end
END

MoveFiles

Function for moving files and directorie.

Function definition: MoveFiles(SourceName, DestName : string) : intege

Parameter:
SourceName	Name of the source file (s) with wildcards “*“ and “?“
DestName	Name of the destination file (s) with wildcards “*“ and “?“
Return values:
> = 0	Number of moved files, directories
-1	General error

Example

PROGRAM

VAR return : integer

BEGIN
    if StartMoveFiles then
    begin
        StartMoveFiles := 0
        return := MoveFiles(QuellDatei, ZielDatei)
    end
END

Important

You cannot move directories from one drive to another. This is not supported by the Windows API!The contents of the directories can, however, be moved!

Note

The source and target directories must exist. When moving large amounts of data, make sure that no other actions can take place at this moment.

Read

Function for reading data from a text file. The “Assign” function is used to assign a text file to a file variable. After opening the file with the “Reset” function, the content of the file can be read line by line, i.e., each “Read” command reads one line and then switches the position indicator to the next line. If you want to read from the beginning of the text file again, it must be closed and reopened. The content of a line is precisely determined by the field width and the decimal places.

Function definition: Read(File : Text, v1 [,v2,….,vn]) : integer

Parameter:
File	File tag for file access
v1..vn	Tags of the data to be read, max. 10 pieces
	Example: Value11 := 10
	Read(File, Wert11 : 6 : 3) somit gilt allgemein
	v1 = tag [: field width [: decimal place]]
Return values:
0	if all of the file was read
<0	if nothing of the file was read

Example

Program

var datei1 : text
var error, ausführung_ok :integer

begin
    ausführung_ok := -1 (* Execution control *)
    error := Assign(datei1,'c:\pcsprjct\dde_test\proto.txt')
    if (error >= 0) then
    begin
        error := Reset(datei1)
        if (error >= 0) then
        begin
            error := Read(datei1,Vorgabe_real:10:2,Vorgabe_int:10,
                Vorgabe_string:10,Vorgabe_bool:10)
            if (error >= 0) then
            begin
                error := Close(datei1)
                if (error >= 0) then
                begin
                    ausführung_ok := 0
                end
            end
        end
    end
    if (ausführung_ok < 0) then
    begin
        Alert(1,22) (* Alarm: data cannot be read *)
        Alert(2,22)
    end
end

ReadLine

Reads a line from a file and switches the file position pointer to the next line.

Function definition: ReadLine(File : Text, ReturnString : string) : integer

Important

The file tag File must first be assigned the file name of a file using the Assign command (see example)!

Parameter:
File	File tag for file access
ReturnString	Ermittelte Zeile
Return values:
0	Function carried out without errors
1	End of file reached
-5	Reading not possible

Note

No check whether ReturnString is too short! Please ensure that the ReturnString is sufficiently large.

Example

Program

var file : Text var error : Integer

BEGIN
    if ReadLineStart then
    begin
        error :=Assign(file,‘C::raw-latex:`\TMP`:raw-latex:`\Test`.TXT’)
        if (error >= 0) then
        begin
            error := ReadLine(file, ReturnString) error := Close(file)
        end
        ReadLineStart := 0
    end
END

Reset

Function to open a text file for a file variable. The file is only opened for reading and is positioned at the beginning of the file when it is opened.

Function definition: Reset(File : Text) : integer

Parameter:
File	File variable for further file access
Return values:
0	if file cannot be opened
<0	if file cannot be opened

Example

FUNCTION ReadOutputFileValue:integer

var datei:Text
var line:string

BEGIN
        ReadOutputFileValue :=  0

        if (Assign(datei, PFAD) < 0) then
            exit;

        if (Reset(datei) < 0) then
            exit;

        if (ReadLine(datei, line) < 0) then
            exit;

        Close(outputFTPFileText)
END

Rewrite

Function for opening or creating a text file for a file variable. If the specified file exists, it is completely deleted and recreated. Rewrite creates a file with the name selected in Assign.

Function definition: Rewrite(File : Text) : integer

Parameter:
File	File variable for further file access
Return values:
0	if file cannot be opened
< 0	if file cannot be opened

Example

Program

var datei2 : text
var error, ausführung_ok :integer

begin
    ausführung_ok := -1 (* Execution control *)
    error := Assign(datei2, 'c:\pcsprjct\dde_test\proto.txt')
    if (error >= 0) then
    begin
        error := Rewrite(datei2)
        if (error >= 0) then
        begin
            error := Write(datei2, Vorgabe_real:10:2,
                        Vorgabe_int:10:0, Vorgabe_string:10,
                        Vorgabe_bool:10)
            if (error >= 0) then
            begin
                error := Close(datei2)
                if (error >= 0) then
                begin
                    ausführung_ok := 0
                end
            end
    end
    end
    if (ausführung_ok < 0) then
        begin
        Alert(1,23) (* Alarm: write data error *)
        Alert(2,23)
    end
end

SetIniString

Function for writing a string to an INI file

Funktionsdefinition: SetIniString(Filename, Section, Key, StringWert : string) : integer

Parameter:
Filename	File name of the ini file with file extension and directory.If no directory is specified, the file is searched for in the project directory. If the file does not exist, a new one is created (directory with file name max. 256 characters
Section	Section in the file. If the section does not exist, it is created automatically (1 to max. 256 characters)
Key	Key in the file. If the key is not available, it will be created automatically (1 to max. 256 characters)
StringWert	String that is to be set
Return values:
0	Function carried out without errors
-1	Directory not found
-2	Drive not found
-3	String cannot be determined
-4	Section not correct
-5	Key not correct

Example

PROGRAM

VAR return : integer

BEGIN
    if SetIniStringStart then
    begin
        return := SetIniString(Filename, Section, Key, StringWert)
        SetIniStringStart :=0
    end
END

ValidPath

Function to check whether a file path is valid or not.

Function definition: ValidPath(StrName : string) : integer

Parameter:
StrName	Path specification
Return values:
0	if path is valid
< 0	if path is not valid

Example

PROGRAM

VAR return : integer

BEGIN
    return := ValidPath(Pfad)
END

Write

Function for writing data in a text file to a file tag.

Function definition: Write(File : Text, v1 [,v2,….,vn]) : integer

Parameter:
File	File variable for further file access
v1..vn	Tags of the data to be written with format specification max. 10 pieces
	Example: Value11 := 10
	Write(File, Wert11 : 6 : 3) results in writing ” 10.000” to the file
	thus generally v1 = expression [: field width [: decimal places]]
Return values:
0	when everything has been written to the file
<0	when nothing could be written to the file

Example

Program

var datei2 : text
var error, ausführung_ok :integer

begin
    ausführung_ok := -1 (* Execution control *)
    error := Assign(datei2, 'c:\pcsprjct\dde_test\proto.txt')
    if (error >= 0) then
    begin
        error := Append(datei2)
        if (error >= 0) then
        begin
            error := Write(datei2, Vorgabe_real:10:2,
                    Vorgabe_int:10:0, Vorgabe_string:10,
                    Vorgabe_bool:10)
            if (error >= 0) then
            begin
                error := Close(datei2)
                if (error >= 0) then
                begin
                    ausführung_ok := 0
                end
            end
        end
    end
    if (ausführung_ok < 0) then
    begin
        Alert(1,23) (* Alarm: write data error *)
        Alert(2,23)
    end
End

Datamanagement functions

Many of the functions described in the following section are also available asf special functions (see further below in this chapter) and on function keys (see data management in the Data chapter)

DBAccessValue

This function is used to have read or write access to individual fields of a data record. This means that individual components of a data record can be processed in a targeted manner without affecting the entire data record.

Two indices are specified for the selection of the data field. Record addresses the index of the data record in the database and Index addresses the number of the field within the data record. If you think of such a database as a table, record corresponds to the row and index to the column of the table.

To be able to use this function sensibly, the type of the affected field must be determined with the function DBFieldType. Depending on the field type, a corresponding buffer must be specified when calling, in which the data can be stored when reading or fetched when writing. With this function, fields of the type CURVEx can neither be read nor written.

With this function it should also be noted that the six standard fields are excluded from write access (see DBFieldType and DBFieldCount).

Function definition: DBAccessValue(DataMgmt: string, Record, Index, Access:integer, Buffer : undef) : integer

Parameter:
DataMgmt	Name of the database or data management
Record	Number of the data record (note the standard columns!)
Index	Position of the field in the data record
Index = 0	database column: ‘ID’
Index = 1	database column: ‘Name’
Index = 2	database column: ‘CreatedOn’
Index = 3	atabase column: ‘CreatedBy’”
Index = 4	database column: ‘CreatedOn’
Index = 5	database column: ‘ChangedBy’
Index = 6	database column: ‘Checksum’
Index = 7	database column: ‘First tag column’
Access	Access type (1 = write, 2 = read)
Buffer	Buffer for the value of the field to be read or written; this buffer must correspond to the field type (real variable for logical and numerical process variables, string for string variable; see also command: DBFieldTyp)
Return values:
>= 0	Field element determined
-1	General parameterisation error
-3	Database is defective
-4	insufficient main memory
-5	Record or index unknown

Important

Standard columns are variable in data management depending on the header selection. With “Standard” there are 7 default columns (6 with ODBC), with order 21, with “Recipe” there are 17 and with “No header (user-defined)” there are none that must be added.

Example

PROGRAM

function fktDBAccessValue(DataMgmt : string, Record, Index : integer, Buffer : string) : integer

var result : integer
var Access : integer

begin
    Access := 2 (* Access reading *)
    restitution := DBAccessValue(DataMgmt, Record, Index, Access, Buffer)
    fktDBAccessValue := result
end

BEGIN
END

DBCopy

Function for copying data records from a database into a new database with the same structure and name in another directory or drive.If the database is available in the target directory, the data record is placed in front of the existing one or the existing data record is replaced.

Function definition: DBCopy(DataMgmt, DataRecord, Path: string, Flag: boolean) : integer

Parameter:
DataMgmt	Name of the database or data management
DataRecord	Name of the dataset
Path	Path for export or import (database name not required here)
Flag	flag for export or import of the data set
	Export = 1 and Import = 0
Return values:
0	if the function was carried out successfully
<> 0	if an error occurred in function

Example

PROGRAM

function fktDBCopy(DataMgmt, DataRecord, Path : string, Flag : boolean) : integer

begin
    fktDBCopy := DBCopy(DataMgmt, DataRecord, Path, Flag)
end

BEGIN
END

DBCopyIndex

Function for copying a data record from a database into the same database in another directory or drive.The data record is specified via its position in the database.

Function definition: DBCopyIndex(DataMgmt, Path : string, Index : integer, Append, Flag : Boolean) : integer

Parameter:
DataMgmt	Name of the database or data management
Path	Path of the database into which the data record is to be copied.
Index	Index of the data record in the source database 0..max-1 data records.
Append	Flag for data record append in target database
	1 = Append (the index position is not taken into account, but appended to the next index)
	0 = note index position (index will be overwritten; it must exist in the target database!)
ExportImport	Flag for export or import of the data set
	Export == 1 and Import == 0
Return values:
0	if the function was carried out successfully
<> 0	if an error occurred in function
-1	general parameterisation error

Example

PROGRAM

function fktDBCopyIndex(DataMgmt, Path : string, Index : integer, DoAppend, Flag : boolean) : integer

begin
    fktDBCopyIndex := DBCopyIndex(DataMgmt, Path, Index, DoAppend, Flag)
end

BEGIN
END

DBDelete

Function for deleting a data record from a database.

Function definition: DBDelete(DataMgmt, DataRecord: string) : integer

Parameter:
DataMgmt	Name of the database or data management
DataRecord	Name of the dataset
Return values:
0	if the function was carried out successfully
<> 0	if an error occurred in function
-1	general parameterisation error

Example

PROGRAM

function fktDBDelete(DataMgmt, DataRecord : string) : integer

begin
    fktDBDelete := DBDelete(DataMgmt, DataRecord)
end

BEGIN
END

DBDeleteIndex

Function for deleting a data record from a database. The data record is specified via its position in the database. (The first record in the database has the number zero)

Function definition: DBDeleteIndex(DataMgmt: string, Index : integer) : integer

Parameter:
DataMgmt	Name of the database or data management
Index	Index of the data set in the database 0..max-1 data sets.
Return values:
0	if the function was carried out successfully
<> 0	if an error occurred in function
-1	general parameterisation error
Function value + 100	System alarm number

Example

PROGRAM

function fktDBDeleteIndex(DataMgmt : string, Index : integer) : integer

begin
    fktDeleteIndex := DBDeleteIndex(DataMgmt, Index)
end

BEGIN
END

DBFieldCount

This function returns the number of fields in the data record of a database. The number also includes the six fields that are automatically assigned to each data record (name of the data record, creation date, creation time, change date, change time, user name of the change).

For example, if a data type only consisted of an element defined by the user, the function value in this case would be 7.

Function definition: DBFieldCount (Type: string) : integer

Parameter:
DataMgmt	Name of the database or data management
Return values:
> 0	The number of fields in a data record
-1	general parameterisation error
-2	Data record not in the database
-3	Database is defective
-4	not enough main memory to run

Example

PROGRAM

function fktDBFieldCount(DataMgmt : string) : integer

begin
    fktDBFieldCount := DBFieldCount(DataMgmt)
end


BEGIN
END

DBFieldType

This function can be used to determine the types of the individual fields to be able to access the values of the fields.This function also considers the six fields that are automatically assigned to each data record (name of the data record, creation date, creation time, change date, change time, username of the change).

The first six fields of each data type are therefore permanently assigned:

Fieldname	Meaning	Type
NAME	Name of the dataset	with max. 31 characters ended with 0
CDATE	Creation date	Date string in the format DD.MM.YYYY
CTIME	Creation time	Time string in the format DD.MM.YYYY
UPDATE	last modification date	Date string in the format DD.MM.YYYY
UPTIME	last modification time	Time string in the format DD.MM.YYYY
USER	Username of the last change	String with max. 31 characters

If the DBFieldType function can be executed successfully, it returns the name in the parameter name and the type of the specified field in Ftype.The fields created by the user can have the types listed in the following table (x in field names stands for a column index).

Fieldname	Meaning
BOOLx	logical process tag
REALx	numeric process tag
STRx	tring variables
CURVEx	Transiente variables

Function definition: DBFieldType(DataMgmt: string, Index:integer, Name: string, Ftype:integer) : integer

Parameter:
DataMgmt	Name of the database or data management
Index	Position of the field in the data record
Name	Buffer for field name
Ftype	Typkennung des Feldes mit
	$0001 = Datensatzname
	$0002 = Creation date
	$0003 = Creation time
	$0004 = last modification date
	$0005 = last modification time
	$0006 = User name
	$0007 = Text variable
	$0008 = Transient variable
	$0101 = logical process tag
	$1001 = logical process tag
Return values:
>= 0	Field element determined
-1	general parameterisation error
-3	Database is defective
-4	not enough main memory to run
-5	Index does not exist

Example

PROGRAM

function fktDBFieldType(DataMgmt : string, Index : integer, Name : string, Ftype : integer) : integer
begin
    fktDBFieldType := DBFieldType(DataMgmt, Index, Name, Ftype)
    Global_Name    := Name
    Global_Ftype   := Ftype
end

BEGIN
END

DBFindRecord

This function searches the specified database for the data record with the desired name.If the data record is found in the database, the return value supplies the ID (index) of the data record.

Function definition: DBFindRecord(DataMgmt, DataRecord: string) : integer

Parameter:
DataMgmt	Name of the database or data management
DataRecord	Name of the dataset
Return values:
>= 0	if the function was executed successfully, the function value corresponds to the position of the data record
< 0	if an error has occurred in function
-1	General parameterisation error, no data record found
-3	Database is defective
-4	not enough main memory to run

Example

PROGRAM

function fktDBFindRecord(DataMgmt, DataRecord : string) : integer
begin
    fktDBFindRecord := DBFindRecord(DataMgmt, DataRecord)
end

BEGIN
END

DBReceive / DBSyncReceive / DBReceiveIndex

Process variables that have been specified in the data management are written as data records to the database (hard disk) by the DataServer. The script server sends the variables modified in the script to the data server for processing. This reads the variables from the process and writes the values to the database. For processing, the script then continues via the script server.

The functions DBReceive and DBSyncReceive work identically. Also, the function DBReceiveIndex, but here instead of the name, the index of the data record is used.

Function definition: DBReceive(DataMgmt, DataRecord: string) : integer

Parameter:
DataMgmt	Name of the database or data management
DataRecord	Name of the datarecord
Return values:
0	if the function was carried out successfully
<> 0	if an error occurred in function
-1	if parameterisation error

Example

PROGRAM

function fktDBReceive(DataMgmt, DataRecord : string) : integer
begin
    fktDBReceive := DBReceive(DataMgmt, DataRecord)
end

BEGIN
END

DBRecordName

This function reads the name of the data record in the specified database that is in the position parameterised with “Record”.If the data record is available, the data record name is returned in StrName. In this case, the function value corresponds to the data record number, otherwise it is less than zero. If the value -1 is specified as the data record number, this function returns the number of data records in the database as a function value and no data record name in StrName

Function definition: DBRecordName (DataMgmt: string, Record : integer, DataRecord : string) : integer

Parameter:
DataMgmt	Name of the database or data management
Record	Number of the data record (if this value is -1 it indicates the number of data records)
DataRecord	Name of the dataset
Return values:
>= 0	if the function was executed successfully, the function value corresponds to the position of the data record
< 0	if an error occurred in function
-1	general parameterisation error
-3	Database is defective
-4	not enough main memory to run
-5	Record not known

Example

PROGRAM

function fktDBRecordName(DataMgmt, DataRecord : string, Index : integer) : integer

var result : integer

begin
    result := DBRecordName(DataMgmt, Index, DataRecord)
    fktDBRecordName := result
end

BEGIN
END

DBSend / DBSyncSend / DBSendIndex

Function for sending data records, which were previously defined in the data management, from the database to the process.

Process variables that have been specified in the data management are written as data records to the database (hard disk) by the DataServer. The script server sends the variables modified in the script to the data server for processing. This reads the variables from the process and writes the values to the database. For processing, the script then continues via the script server, which reads in the modified variables again before continuing to work.

The functions DBSend and DBSyncSend work identically. Also the function DBSendIndex, but instead of the name, the index of the data record is used.

Function definition: DBSend(DataMgmt, DataRecord:string) : integer

Parameter:
DataMgmt	Name of the database or data management
DataRecord	Name of the datarecord
Return values:
0	if the function was carried out successfully
<> 0	if an error occurred in function
-1	General parameterisation error

Example

PROGRAM

function fktDBSend(DataMgmt, DataRecord : string) : integer

begin
    fktDBSend := DBSend(DataMgmt, DataRecord)
end

BEGIN
END

DBNotifyDataChanged

Function to inform all clients (grids) about a change in the transferred data management.

Function definition: DBNotifyDataChanged(StrType : string) : integer

Parameter:
StrType	Name of the data type
Return values:
0	if the function was carried out successfully

After calling up, all data grids that are currently displaying data from the specified data management system are updated by reloading the focused data. However, the selection and scroll position are retained. Return value 0 if executed without errors. Less than 0 if an error occurred during execution. If there is no data management with the specified name, nothing is updated and 0 is returned.

Example

PROGRAM

function fktDBNotifyDataChanged(DataMgmt : string) : integer

begin
    fktDBNotifyDataChanged := DBNotifyDataChanged(DataMgmt)
end

BEGIN
END

Important

The new data grid is updated automatically if data records are manipulated, added or deleted via data management functions (e.g. DBReceive). If data management is manipulated from outside or via ODBC, the grid does not notice this.

Chart-/datalogger funtions (only SCADA)

DVExportView

This function is used to export the data of a data recorder view related to batch or date.The export takes place on the machine on which the DataServer is running, either to a directory specified by the project or by call parameters.

Funvtion definition: DVExportView(ViewName : string, ChargeName : string, StartTime : real, EndTime : real, FilePath : string)

Parameter:
ViewName	Name of the data recorder view
ChargeName	Name of the batch
StartTime	Optional: start time in seconds since 01/01/1970;With -1 the start time is not evaluated
EndTime	Optional: end time in seconds since 01/01/1970;With -1 the eend time is not evaluated
FilePath	Name of the file or path in which the export is to be saved
Return values:
>=0	Amoutn of exported data sets if the function was carried out successfully
-1	general parameterisation error
-2	Invalid data recorder view name
-3	Data recorder for batch not found
-4	No batch or data found
-5	Start time invalid
-6	End time invalid

Example

PROGRAM

BEGIN
    IF DoExport = 1 THEN
    BEGIN
        DoExport := 0

        retValue := DVExportView('Diag2_Drehzahl', 'Charge01',
                        TimeToAbs(16, 11, 2016, 6, 0, 0),
                        TimeToAbs(16, 11, 2016, 6, 0, 0),
                        'D:\TEMP\Export1.csv')

        retValue := DVExportView('Diag2_Drehzahl', 'Charge02',
                        -1, -1,
                        'D:\TEMP\Export1.csv')
    END
END

Important

Depending on the number of data records, the export can take a certain amount of time!

Functions recipe management

With the new recipe management in the PROCON-WEB DataServer, new functions for recipe management have also been added to the PROCON-WEB scripting.

When using the recipe management functions, the state model of the recipe management must be observed, which is briefly outlined here:

Important

Version and name can only be changed in the “Draft” status of a recipe.

DBRecipeChangeState

This function can be used to change the status of a recipe. Depending on the current status of the recipe, only certain subsequent statuses can be set.

Possible recipe status:

• Draft = 1,

• Released = 2,

• Deleted = 4,

• Locked = 8,

• InUse = 16

Function definition: DBRecipeChangeState(StrType, StrName : string, State : integer) : integer

Parameter:
StrType	Name of the recipe data type
StrName	Name of a data record from the database”
State	New status of a recipe
Return values:
0	if the function was carried out successfully
-1	Type not found
-2	Type is not a recipe type
-3	Status change not allowed (wrong state)
-4	unknown state
-5	Datarecord not found

Example

PROGRAM

function setRecipeStateDraft(StrType, StrName : string) : integer
var State: integer

begin
    State := 1
    setRecipeStateDraft := DBRecipeChangeState(StrType, StrName, State)
end


function setRecipeStateLocked(StrType, StrName : string) : integer
var State: integer

begin
    State := 8
    setRecipeStateLocked := DBRecipeChangeState(StrType, StrName, State)
end


BEGIN
END

DBRecipeChangeStateIndex

This function can be used to change the status of a recipe. Depending on the current status of the recipe, only certain subsequent statuses can be set.

Possible recipe status:

• Draft = 1,

• Released = 2,

• Deleted = 4,

• Locked = 8,

• InUse = 16

Function definition: DBRecipeChangeStateIndex(StrType : string, Index : integer, State : integer) : integer

Parameter:
StrType	Name of the recipe data type
Index	Index of the data set in the database
State	New status of a recipe
Return values:
0	if the function was carried out successfully
-1	Type not found
-2	Type is not a recipe type
-3	Status change not allowed (wrong state)
-4	unknown state
-5	Datarecord not found

Example

PROGRAM

function setRecipeStateDraft(StrType : string, Index : integer) : integer
var State: integer

begin
    State := 1
    setRecipeStateDraft := DBRecipeChangeStateIndex(StrType, Index, State)
end


function setRecipeStateLocked(StrType : string, Index : integer) : integer
var State: integer

begin
    State := 8
    setRecipeStateLocked := DBRecipeChangeStateIndex(StrType, Index, State)
end


BEGIN
END

DBRecipeChangeVersion

Functions for changing the recipe version. The recipe version can only be increased by the specified delta.The parameter versionpart indicates which part of the version is increased.

Possible version elements (structure of the version number is: Major.Minor.Build):

• Build = 0

• Minor = 1

• Major = 2

Function definition: DBRecipeChangeVersion(StrType, StrName : string, Versionpart, Delta : integer) : integer

Parameter:
StrType	Name of the recipe data type
StrName	Name of a data record from the database”
Versionpart	Part of the version number, that should be increased
Delta	“Value by which the version number is incremented
Return values:
0	if the function was carried out successfully
-1	Type not found
-2	Type is not a recipe type
-3	Version already exists
-4	Version already exists
-5	Datarecord not found

Example

PROGRAM
(*  To increase the main version of a recipe from version 1.0.3 to 2.0.3,
    Major (2) must be increased by a delta of 1:                          *)

var result : integer
var StrType, StrName : string

BEGIN
    result := DBRecipeChangeVersion(StrType, StrName, 2, 1)
    if result < 0 then
    begin
        Alert(1,4711)
    end
END

DBRecipeChangeVersionIndex

Functions for changing the recipe version. The recipe version can only be increased by the specified delta.The parameter versionpart indicates which part of the version is increased.

Possible version elements (structure of the version number is: Major.Minor.Build):

• Build = 0

• Minor = 1

• Major = 2

Function definition: DBRecipeChangeVersionIndex(StrType : string, Index, versionpart, delta : integer): integer

Parameter:
StrType	Name of the recipe data type
Index	Index of the data set in the database
Versionpart	Part of the version number, that should be increased
Delta	“Value by which the version number is incremented
Return values:
0	if the function was carried out successfully
-1	Type not found
-2	Type is not a recipe type
-3	Version already exists
-4	Version already exists
-5	Datarecord not found

Example

PROGRAM
(*  To increase the main version of a recipe from version 1.0.3 to 2.0.3,
    Major (2) must be increased by a delta of 1:                          *)

var result, Index : integer
var StrType : string
BEGIN
    result := DBRecipeChangeVersionIndex(StrType, Index, 2, 1)
    if result < 0 then
    begin
        Alert(1,4711)
    end
END

DBRecipeChangeName

Functions for changing the recipe name.

Function definition: DBRecipeChangeName(StrType, StrName, Name : string) : integer

Parameter:
StrType	Name of the recipe data type
StrName	Name of a data record from the database”
Name	New name of a recipe
Return values:
0	if the function was carried out successfully
-1	Type not found
-2	Type is not a recipe type
-5	Datarecord not found

Example

PROGRAM

var result : integer
var StrType, StrName : string

BEGIN
    result := DBRecipeChangeName(StrType, StrName, 'Neuer Name')
    if result < 0 then
    begin
        Alert(1,4711)
    end
END

DBRecipeChangeNameIndex

Functions for changing the recipe name.

Function definition: DBRecipeChangeNameIndex(StrType : string, Index : integer, Name : string) : integer

Parameter:
StrType	Name of the recipe data type
Index	Index of the data set in the database
Name	New name of a recipe
Return values:
0	if the function was carried out successfully
-1	Type not found
-2	Type is not a recipe type
-5	Datarecord not found

Example

PROGRAM

var result, Index : integer
var StrType : string

BEGIN
    result := DBRecipeChangeNameIndex(StrType, Index, 'Neuer Name')
    if result < 0 then
    begin
        Alert(1,4711)
    end
END

functions of the ODBC interface

The Open Database Connectivity interface extends the scope of the PROCON-WEB formulas to include the possibility of accessing internal and external databases. It is not the format of the database, or the file formats used in the database that is decisive, but the availability of an ODBC driver.

To be able to use this interface in the formulas, ODBC itself must first be installed in the operating system (system control). If an external database is to be addressed, this must also be correctly installed. During the ODBC installation, the drivers that are to be used in the PROCON-WEB formulas must be set up. To use the internal databases, for example, a dBase driver must be defined. Setting up an ODBC driver includes assigning the target database and assigning access names and passwords.

The performance and the range of functions of the ODBC interface depend on the ODBC driver used. When using the formulas for the ODBC interface, the scope of performance of the driver used must therefore be checked against the corresponding documentation.

However, the functional principle of the ODBC interface is generally based on the same mechanisms. First, the connection to the ODBC driver must be established (DBOpenODBC function). The name that was assigned during the driver installation is used for this. If this was carried out successfully, a so-called handle is supplied for this connection, via which all further actions are addressed. A maximum of twenty such connections can be used at the same time.

On an open connection, a selection (“Select statement”) is then carried out on the database using an SQL statement (DBSendSQLODBC). This instruction is used to select a subset (“table”) from the database or the entire database from the database connection established via the driver. A string is used for the selection, in which the type of selection is described with a given SQL grammar.

In addition to the selection with the SQL command SELECT, data records can also be inserted or deleted directly in the database with the SQL commands INSERT and DELETE.

The different ODBC drivers allow the SQL grammar to be used in different expansion stages. However, they at least support the minimal grammar.

The table generated by the selection is then the starting point for further operations. Information, read and write functions can be carried out on it (DBFetchTabODBC, DBGetDataODBC, DBPutDataODBC, DBGetErrorODBC, DBGetInfoTabODBC, DBGetInfoDataODBC). Depending on the type of ODBC driver, there is also the option of executing ODBC procedures (DBProcedureODBC). ODBC procedures can contain complete SQL sequences and simplify standardised or stereotypical actions on databases considerably.

If the connection to the ODBC driver is no longer required, it must be closed again (DBCloseODBC). For security reasons, the ODBC interface has been implemented in the formulas in such a way that the connection to the ODBC driver and thus to the database is automatically closed when the executed event code is terminated. This affects, for example, ODBC activities in a picture event code.

DBOpenODBC

This function establishes the connection to the ODBC driver. It must be executed as the first function, because if the execution is successful, the handle is returned as a database key, which can then be used as a parameter when the other ODBC functions are called.

With this function, the required ODBC driver is parameterised using its name. If user names and passwords were assigned when this driver was set up, these must also be entered when opening the connection. A maximum of 20 ODBC connections can be open at the same time.

Function definition: DBOpenODBC (ODBCDriver, User, Password : string) : integer

Parameter:
ODBCDriver	Name of the ODBC-driver (max. 255 characters)
User	Name of the user (max. 255 characters)
Password	Password of the user (max. 255 characters)
Return values:
0..19	Key on database for further database access
-1	no more free handle
-2	Lack of memory
-3	Error from ODBC driver

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBOpenODBCConnection

This function is used to establish the connection to an ODBC data source. The ODBC data source must be defined beforehand in the designer.

This must be carried out as the first function, because if the execution is successful, the handle is returned as a database key, which can then be used as a parameter when the other ODBC functions are called.

With this function, the required ODBC data source is parameterized via its name. A maximum of 20 ODBC connections can be open at the same time.

Function definition: DBOpenODBCConnection (ConnectionName : string) : integer

Parameter:
ConnectionName	Name of the ODBC data source defined in the designer (max. 255 characters)
Return values:
0..19	Key on database for further database access
-1	no more free handle
-2	Lack of memory
-3	Error from ODBC driver
-4	ODBC data source not found

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBCConnection('SQL_ODBC')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBCloseODBC

The connection to the specified ODBC driver is closed.

This function should always be carried out when a connection is no longer required. This frees up occupied resources. If this function is not called the Runtime closes the connections when the affected event code is exited automatically.

The connection is parameterised via the connection handle.

Function definition: DBCloseODBC (ODBCHandle : integer) : integer

Parameter:
ODBCHandle	Connection handle to the ODBC driver (0. 19)
Return values:
0	Function carried out successfully
-1	Incorrect database access key

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBSendSQLODBC

This function executes an SQL statement on an open connection.

SQL SELECT statement: It must be called before the actual access functions to the database table can be used. All other ODBC functions are then carried out on the data selected using this instruction.

SQL INSERT and SQL DELETE statement: These instructions insert or delete records in the database.

The connection to the ODBC driver must be open. The specified SQL string must comply with the SQL grammar of the connected ODBC driver.

Function definition: DBSendSQLODBC (ODBCHandle : integer, SQL : string) : integer

Parameter:
ODBCHandle	Connection handle to the ODBC driver (0. 19)
SQL	“SQL-instruction with max. 400 characters
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBProcedureODBC

This function is used to execute an ODBC procedure. The prerequisite for this is that, on the one hand, the connection to the driver has been established and, on the other hand, the ODBC driver concerned supports this option at all.

The procedure must also be created in the database under the specified name. For more information on this topic, see the documentation for the ODBC database server.

Function definition: DBProcedureODBC (ODBCHandle : integer, Proc : string) : integer

Parameter:
ODBCHandle	Connection handle to the ODBC driver (0. 19)
Proc	Name of the procedure to be performed (max. 255 characters)
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver
-6	the database cannot execute any procedures

Example

PROGRAM

(*-------------------------------------------------------------*)
(* ODBC example for executing a database procedure             *)
(*-------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer (*----- function return value -----------*)
var handle: (*----- connection handle -------------*)

begin
(*----- Open the connection to the ODBC driver named ACC -*)
    handle := DBOpenODBC('ACC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBProcedureODBC(handle,'Del_all')

(*----- Error handling -------------------------------------- *)
        if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
            ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBFetchTabODBC

This function loads a data record from the selected quantity into an internal buffer. There it is then available for further processing. The data record is selected via the “Pos” parameter. Positioning is always relative to the previous actions or directly to the beginning or end of the selected data records.

With the table-oriented model of the selected data set, this function prepares a row of the table for processing.The connection to the ODBC driver must be open.

Function definition: DBFetchTabODBC (ODBCHandle, Pos : integer) : integer

Parameter:
ODBCHandle	Connection handle to the ODBC driver (0 … 19)
Pos	Position of the data record in the selected set; only the following information is allowed:
	0 = next record in the table
	1 = previous data record
	2 = first data record
	3 = last record
	While 0 is allowed for all ODBC drivers, the other values only apply to some.
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver
-4	no more data available

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBGetDataODBC

If a data record is loaded into the internal processing buffer with the DBFetchTabODBC function, the data elements of this data record can be read with this function. The element (column) within the data record is selected with Pos.

The value of the selected column is made available in the specified buffer. The buffer must correspond to the type of the entry. Therefore, the type must first be determined with the DBGetInfoDataODBC function. The DBGetDataODBC function can be used on elements of the type string, logical or numeric.The connection to the ODBC driver must be open.

Function definition: DBGetDataODBC (ODBCHandle, Pos : integer, Buffer : undef) : integer

Parameter:
ODBC-Handle	Connection handle to the ODBC driver (0. 19)
Pos	Number of the desired element (column number)
Buffer	Buffer for the transfer of the element content; it must match the type of the element(see DBGetInfoDataODBC)
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver
-4	no more data available
-5	wrong data types

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBPutDataODBC

With this function elements of a data record can be changed. The data record to be processed must first be loaded into the internal buffer using the DBFetchTabODBC function. The element of the data record, i.e. the column, is addressed with the parameter Pos.

The value for the selected column must be provided in the specified buffer. The buffer must correspond to the type of the entry. Therefore, the type must first be determined with the DBGetInfoDataODBC function. The DBPutDataODBC function can be used on elements of the type string, logical or numeric.

Important

The DBPutDataODBC command does not work for databases in Excel format

The connection to the ODBC driver must be open.

Function definition: DBPutDataODBC (ODBCHandle, Pos : integer, Buffer : undef) : integer

Parameter:
ODBC-Handle	Connection handle to the ODBC driver (0. 19)
Pos	Number of the desired element (column number)
Buffer	Buffer for transferring the element content; it must match the type of the element (see DBGetInfoDataODBC)
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver
-4	no more data available
-5	wrong data types

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBGetStampODBC

If a data record is loaded into the internal processing buffer with the DBFetchTabODBC function, this function can be used to read a data element of this data record which is of the “date stamp” type. The element (column) within the data record is selected with Pos.

Since the “date stamp” type consists of six individual values, six tag specifications are required for the transfer of the values. The DBGetInfoDataODBC function can be used to determine whether a data element is of this type.The connection to the ODBC driver must be open.

The connection to the ODBC driver must be open.

Function definition: DBGetStampODBC (ODBCHandle, Pos, Hour, Min, Sec, Day, Month, Year : integer) : integer

Parameter:
ODBC-Handle	Connection handle to the ODBC driver (0. 19)
Pos	Number of the desired element (column number)
Hour	Buffer for hourly value
Min	Buffer for minute value
Sec	Buffer for second value
Day	Buffer for dayly value
Month	Buffer for monthly value
Year	Buffer for yearly value
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver
-4	no more data available

Example

PROGRAM

(*----------------------------------------------------------------------*)
(* ODBC example for reading out the creationdate from the yoghurt table *)
(* and transferred to the update date of the strawberry data set        *)
(*----------------------------------------------------------------------*)
function ODBC_BSP : integer

var ret :integer        (*-- function return value --*)
var act :integer        (*-- connection handle ------*)
var hour :integer       (*-- Hour -------------------*)
var min :integer        (*-- minute -----------------*)
var sec :integer        (*-- second -----------------*)
var mon :integer        (*-- month ------------------*)
var day :integer        (*-- Day --------------------*)
var year :integer       (*-- Year -------------------*)
var sp_typ :integer     (*-- column type ------------*)
var rinse :integer      (*-- column length ----------*)
var sp_name     :string     (*-- column name ------------*)


begin
(*-- Open the connection to the ODBC driver with the name SQL_ODBC --*)
    handle := DBOpenODBC('SQL_ODBC', '', '')
    if (handle >= 0) then
    begin
(*-- loading the first line from the table --*)
        ret := DBFetchTabODBC(handle, 0)
        if(ret = 0) then
        begin
(*-- Determine the column type of the 2nd column --*)
            ret := DBGetInfoDataODBC(handle, 2, sp_name, sp_typ, sp_len)
            if(ret = 0) AND (sp_typ = 4) then
            begin
(*-- Enter the date from the second column (CDATE) in the variables --*)
                ret := DBGetStampODBC(handle, 2, hour, min, sec, day,
                        mon, year)
                if(ret = 0) then
                begin
(*-- Date transferred to fourth column (UPDATE) of the table --*)
                ret := DBPutStampODBC(handle, 4, hour, min, sec,
                        day, mon, year)
                end
            end
        end
    end

(*-- Error handling --------------------------------------*)
    if(ret = -3) then
    begin
(*-- Get driver error information ----------------------*)
        ret := DBGetErrorODBC(mess, status)
    end
(*-- Enable ODBC driver connection ----------------------*)
    ret := DBCloseODBC(handle)
end

BEGIN
    ODBC_BSP
END

DBPutStampODBC

This function can be used to overwrite a date entry in a data record element. To do this, the data record must be loaded into the internal processing buffer with the DBFetchTabODBC function. The element (column) within the data record is selected with Pos.

Since the “date stamp” type has six individual values, six parameters are required for the transfer of the values. The DBGetInfoDataODBC function can be used to determine whether a data element is of this type.The connection to the ODBC driver must be open.

Function definition: DBPutStampODBC (ODBCHandle, Pos, Hour, Min, Sec, Day, Month, Year : integer) : integer

Parameter:
ODBCHandle	Connection handle to the ODBC driver (0 … 19)
Pos	Number of the desired element (column number)
Hour	Hourly value
Min	Minute value
Sec	Second value
Day	Dayly value
Month	Monthly value
Year	Yearly value
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver
-4	no more data available
-5	wrong data types

Example

PROGRAM

(*----------------------------------------------------------------------*)
(* ODBC example for reading out the creationdate from the yoghurt table *)
(* and transferred to the update date of the strawberry data set        *)
(*----------------------------------------------------------------------*)
function ODBC_BSP : integer

var ret :integer        (*-- function return value --*)
var act :integer        (*-- connection handle ------*)
var hour :integer       (*-- Hour -------------------*)
var min :integer        (*-- minute -----------------*)
var sec :integer        (*-- second -----------------*)
var mon :integer        (*-- month ------------------*)
var day :integer        (*-- Day --------------------*)
var year :integer       (*-- Year -------------------*)
var sp_typ :integer     (*-- column type ------------*)
var rinse :integer      (*-- column length ----------*)
var sp_name     :string     (*-- column name ------------*)


begin
(*-- Open the connection to the ODBC driver with the name SQL_ODBC --*)
    handle := DBOpenODBC('SQL_ODBC', '', '')
    if (handle >= 0) then
    begin
(*-- loading the first line from the table --*)
        ret := DBFetchTabODBC(handle, 0)
        if(ret = 0) then
        begin
(*-- Determine the column type of the 2nd column --*)
            ret := DBGetInfoDataODBC(handle, 2, sp_name, sp_typ, sp_len)
            if(ret = 0) AND (sp_typ = 4) then
            begin
(*-- Enter the date from the second column (CDATE) in the variables --*)
                ret := DBGetStampODBC(handle, 2, hour, min, sec, day,
                        mon, year)
                if(ret = 0) then
                begin
(*-- Date transferred to fourth column (UPDATE) of the table --*)
                ret := DBPutStampODBC(handle, 4, hour, min, sec,
                        day, mon, year)
                end
            end
        end
    end

(*-- Error handling --------------------------------------*)
    if(ret = -3) then
    begin
(*-- Get driver error information ----------------------*)
        ret := DBGetErrorODBC(mess, status)
    end
(*-- Enable ODBC driver connection ----------------------*)
    ret := DBCloseODBC(handle)
end

BEGIN
    ODBC_BSP
END

DBGetInfoTabODBC

With this function you can get information about the number of rows and columns, i.e. the number of data records and data elements. This function is applied to the table selected with the DBSendSQLODBC function.The connection to the ODBC driver must have been opened and the selection made.

Note

After this function has been executed, the fetch position of the DBFetchTabODBC () function is back at the beginning of the table

Function definition: DBGetInfoTabODBC (ODBCHandle, Rec, Col : integer) : integer

Parameter:
ODBC-Handle	Connection handle to the ODBC driver (0 … 19)
Rec	Buffer for transferring the number of lines (data sets or records)
Col	Buffer for taking over the number of columns (number of data elements in a data set or record)
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBGetInfoDataODBC

This function provides information about the type and length of a column in the selected table. The structure of a data record element is described here. The information obtained in this way is necessary to be able to ultimately read or write access to the individual elements of the data records, since type-conform parameters must be specified for the access functions.

The connection to the ODBC driver must have been opened and the selection made.

Function definition: DBGetInfoDataODBC (ODBCHandle, Pos: integer, name: string, len: integer): integer

Parameter:
ODBC-Handle	Connection handle to the ODBC driver (0 … 19)
Pos	Column index of the desired data element (starts with 1)
Column name	Name of the database column
Type	Buffer for adopting the column type
1 =	1 = Varbinary (checksum of PROCON-WEB standard columns)
2 =	Boolean element
3 =	Numeric element
4 =	date stamp
5 =	String
Len	Buffer for taking over the column width
Return values:
0	Function carried out successfully
-1	Incorrect database access key
-3	Error from ODBC driver

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

DBGetErrorODBC

If one of the ODBC functions has reported the value -3 as a function value, i.e. an error from the ODBC driver, the associated error text can be fetched from the ODBC driver with this function. A buffer for a message and a status text must be specified. The texts can be up to 255 characters long, ie the buffers must be created to the appropriate size.

Function definition: DBGetErrorODBC (Message, State:string) : integer

Parameter:
Message	Buffer for message text (255 characters)
State	Buffer for state text (255 characters)
Return values:
0	Function carried out successfully
-1	String buffer not available

Example

PROGRAM

(*---------------------------------------------------------------*)
(* ODBC example for reading out the 7th value from table yoghurt *)
(* for the strawberry data set and setting the 8th value so      *)
(*---------------------------------------------------------------*)
function ODBC_BSP:integer

var ret:integer    (*----- function return value ----------------*)
var handle:integer (*----- connection handle --------------------*)
var rec:integer    (*----- number of rows in the table ----------*)
var col:integer    (*----- number of columns in the table -------*)

begin
(*----- Open the connection to the ODBC driver with the name SQL_ODBC -*)
    handle := DBOpenODBC('SQL_ODBC','','')
    if (handle >= 0) then
    begin
(*----- select table with one line and two columns -*)
        ret := DBSendSQLODBC(handle, 'SELECT REAL7, REAL8 from joghurt
                            where NAME = ''Erdbeer''')
        if(ret = 0) then
        begin
(*----- Load the first line from the table ----------------*)
            ret := DBFetchTabODBC(handle, 0)
            if(ret = 0) then
            begin
(*----- Determine number of rows and columns in the table ------- *)
                ret := DBGetInfoTabODBC(handle, rec, col)
                if(ret = 0) then
                begin
(*----- Read the value of the first column (REAL7) into the variable value *)
                    ret := DBGetDataODBC(handle, 1, wert)
                    if(ret = 0) then
                    begin
(*----- Enter the tag value in the second column (REAL8) of the table *)
                        ret := DBPutDataODBC(handle, 2, wert)
                    end
                end
            end
        end

(*----- Error handling --------------------------------------*)
                if(ret = -3) then
        begin
(*----- Get driver error information ----------------------*)
            ret := DBGetErrorODBC(mess, status)
        end
(*----- Enable ODBC driver connection ----------------------*)
        ret := DBCloseODBC(handle)
    end
end

BEGIN
    ODBC_BSP
END

String handling functions

Handling of text tags (strings) in the event code.

PROCON-WEB differentiates between two types of text tags, the event-local (variable type: string) and the global text tags from the image assembly.

Local text tags have a limited range of validity, for example only in the macro file, in the global event or in the respective picture formula (Pictevent).

Global text tags, on the other hand, as the name suggests, are valid everywhere in the project.

In addition to event functions (Length, Pos, Str and Val, see below in this chapter), text tags can be edited in the following way:

Editing of individual letters of a global text tag: If a process tag field is assigned to a text tag (see chapter Dynamizing text), each letter can be edited individually in the formula interpreter. The field element “0” contains the ASCII value of the first letter, the field element “n-1” the ASCII value of the last letter. The “0” must be in the “nth” field element as the end of the string identifier.

Example

(*--------------------------------------------------------------------------------------*)
(*  The current date is to be written in a text variable in the format "ddmmyyyy".
    A process tag field "Date field []" is assigned to the text tag.
    The following calculation is based on the ASCII table. The numbers in
    the ASCII table begin with 48 (decimal “0”) and end with 57 (decimal 9).
    Each decimal number (eg day = 23) must be broken down into individual
    characters (2 and 3) and converted to ASCII (+ ASCII value of "0").                 *)
(*--------------------------------------------------------------------------------------*)

function Datumskonvertierer() : integer
var Tag, Monat, Jahr, Jahrhilf: integer

begin
    Tag   := Time(0)  (* Read out the day in an auxiliary tag *)
    Monat := Time(1)  (* Read out the month in an auxiliary tag *)
    Jahr  := Time(2)  (* Read out the year in an auxiliary tag *)

    (* ASCII value calculation for day *)
    Datumfeld[0] := 48 + Tag div 10
    Datumfeld[1] := 48 + Tag mod 10

(* ASCII value calculation for month *)
    Datumfeld[2] := 48 + Monat div 10
    Datumfeld[3] := 48 + Monat mod 10
    Datumfeld[4] := 48 + Jahr div 1000     (* 1. ASCII value for year             *)
    Jahrhilf     := Jahr mod 1000          (* Remainder of the integer division   *)
    Datumfeld[5] := 48 + Jahrhilf div 100  (* 2. ASCII value for year             *)
    Jahrhilf     := Jahrhilf mod 100       (* Remainder of the integer division   *)
    Datumfeld[6] := 48 + Jahrhilf div 10   (* 3. ASCII value for year             *)
    Datumfeld[7] := 48 + Jahrhilf mod 10   (* 4. ASCII value for year             *)
    Datumfeld[8] := 0                      (* Terminate string with zero          *)
end

Note

The creation of a process tag field is described in the chapter “Process point definition” (field size (#) described.

Editing of individual letters of a local text tag: Local text tags can also be edited letter by letter using ASCII values. The first tag element contains the ASCII value of the first, the penultimate tag element the ASCII value of the last letter. In the last tag element, the “0” must be the end of string identifier.

Example

(*--------------------------------------------------------------*)
(*  The word "DATA" should be written in a text tag
    The following calculation is based on the ASCII table. The
    capital letters in the ASCII table begin with 65 (“A”) and
    end with 90 (“Z”).                                          *)
(*--------------------------------------------------------------*)

function AsciiTest():integer
var Testvar[20]:string
begin
    Testvar[0]:=68
    Testvar[1]:=65
    Testvar[2]:=84
    Testvar[3]:=69
    Testvar[4]:=78
    Testvar[5]:=0
    (* copy to a global tag for display in the picture  *)
    Global_Testvar := Testvar
end

Copy of local or global text tags: Textvar2 + Textvar3

Compare the content of two text tags: if Textvar1= Textvar2 then …

Concatenation of local or global text tags: Textvar2 + Textvar3

Write constant text in a local or global text tag: Textvar2: = ‘This is a constant text’Textvar1: = ‘constant part A’ + Textvar2 + ‘constant part B’

Note

“Text tags and process tags must differ in their name. The same applies to local and global text tags

AppendString

Function to append a number to a string and another string that can be used as a separator for concatenation

Function definition: AppendString(v1 : real, Mode1, Mode2 : integer, StrSeparator, StrDest : string) : integer

Parameter:
v1	Tag of the data to be written with format specification, up to 20 places
	v1 = tag [: field width [: decimal place]]
Mode1	0 = with spaces (depending on the format specification)
	1 = with zeros in front of the decimal point (depending on the format specification)
Mode2	0 = decimal places from the format specification
	1 = decimal places from the process tag declaration
StrSeparator	Constant or variable string that can be used as a separator for concatenation
StrDest	String to which the data is appended
Return values:
0	Data attached
-1	Parameter error
-2	too many characters in the string

Note

A maximum of 4095 characters are allowed in a string. For global text tags, the maximum number of characters is 255 characters.

Example

PROGRAM

(* The content of the tag v1 should be appended to the string tag "StrDest": *)
function fktAppendTest: integer

var v1 : real
var Mode1, Mode2 : integer
var StrSeparator, StrDest : string

begin
    Mode1 := 1
    Mode2 := 1
    StrSeparator := ','
    fktAppendTest := AppendString(v1:5:2, Mode1, Mode2, StrSeparator,
                    StrDest)
end

BEGIN
    fktAppendTest
END

DateToStr

Function for converting date and time information into a string.The conversion is specified by a format string.

The function converts the transferred value of the Time () function taking into account the daylight-saving time offset and the time zone offset. For example, if the function is given a value from the Time (8) function, the current time is obtained as a string. A string is obtained as UTC time via the Time (12) parameter.

Function definition: DateToStr(InputSec : real, Format, Destination : string) : integer

Parameter:
InputSec	Process variable with absolute seconds value (Time (8) or Time(12))
Format	String variable for time formatting The following format characters are defined:
	h = hours
	m = minutes
	s seconds
	d = day
	m= month
	y = year
Destination	String in which the output is written
Return values:
:-	:-
0	String created
-1	Parameter error

Important

The Time () and DateToStr () functions work with second values.

In contrast to this, the system variable “$ Current.UTCTime” and the number field display with the format “Date / Time” work with millisecond values. If necessary, a conversion must be made here.

Format identifiers that only consist of one character must be expanded with a preceding space (example: “f” -> “f”).

Example

PROGRAM

(* Target string must be a global variable!                     *)
(* Function cannot return a string!                             *)
(* Example for formatting 11:00:10 on 03/01/98              *)
(* Content: date format         Content: data record name       *)
(* hh / mm / ss DD.MM.YY    11/00/10 03/01/98           *)
(* hh: mm: ss DMYYYY            11:00:10 1.3.1998               *)


function fktDateToStr(InputSec : real, Format : string) : integer
begin
    fktDateToStr:= DateToStr(InputSec, Format, Global_Destination)
end

BEGIN
    fktDateToStr(Input, Format)
END

Note

The format string can also be used without a separator (eg:, /). This is useful for file names with a date (e.g., file X01031998).

GetSubString

The function returns a substring from a source string. It extracts the substring from a start address and ends the substring as soon as the transferred separator has been found.

If the separator is not found, the return value is -2 and the substring is returned with the source string from the start address to the end of the string.

If an invalid parameter is passed or the start address is outside the source string, the substring is not touched.

If a value is already contained in the variable when the function is called, it is retained after the function.

Function definition: GetSubString(Quell, Sub, Separator : string, Start : integer) : integer

Parameter:
Source	Source string from which the substring is extracted
Sub	Variable in witch the the substring is written into
Separator	Separator where the substring ends
Start	Starting position at which, the substring begins
Return values:
>= 0	Position of the found seperator
-1	Parameter error
-2	Separator not found
-3	Start address is outside the source string

Example

PROGRAM

function fktGetSubString(Source, Sub : string, Start : integer) : integer

var StrSeparator : string

begin
    StrSeparator := ','
    fktGetSubString := GetSubString(Source, Sub, StrSeparator, Start)
end

BEGIN
    fktGetSubString(Source, Sub, 2)
END

Length

Function for determining the length of a string.

Function definition: Length(Source : string) : integer

Parameter:
Source	Name of the source string
Return values:
>= 0	Number of signs
<0	if error

Example

PROGRAM

function fktLength(Input : string) : integer
begin
    fktLength := Length(Input)
end

BEGIN
    fktLength(Source)
END

Pos

Function to search for a string in a string.

Function definition: Pos(Sub, Source : string) : integer

Parameter:
Sub	Name of the string to be searched for
Source	Name of the string to be searched for
Return values:
>= 0	Position of the substring in a string
<0	f not found

Example

PROGRAM

function fktPos(Sub, Source : string) : integer
begin
    fktPos := Pos(Sub, Source)
end

BEGIN
    fktPos(Sub, Source)
END

Str

Function for converting a number into a string. The format can be commited as well.

Function definition: Str(Source : real, Destination : string) : integer

Parameter:
Source	Variable of the data to be written with format specification, up to max. The following applies in general:
Source = variable [: field width [: decimal places]]
Destination	Name of the target string
Return values:
>= 0	when converted
<0	if not converted

Important

The field width only specifies the minimum width, i.e., if the number to be converted is larger than the minimum field width, the entire number will still be converted into a string!Example: Field width 1 decimal place 1 number to be converted 22

Ist die Feldbreite größer als die Zahl, wird String am Anfang mit 0 aufgefüllt Bei Feldbreite 3 wird aus 22 ein String „022“ Damit auf String wieder gleicher Wert kommt kann alternativ der Befehl AppendString mit Mode1=0 verwendet werden.

Example

PROGRAM

(* Target string must be a global variable! *)
(* Function cannot return a string!         *)

begin
    time:=Time(8)
    Str(time:10:2, varTimeStamp)
end

Val

Convert a string to a number in the integer variable transferred as “Interrupt”, VAL saved the position of the character in “Source” at which the conversion was aborted in PROCON-WIN. Today the “Interupt” parameter is ignored during execution but must be specified in the function!

Val automatically skips leading spaces. If a string contains the following character combination ‘12.13’, the value 12.13 is assigned to the process variable.

Important

The string to be converted may only contain numbers, periods or commas! If it contains other characters, the function is not executed.The interrupt parameter must be specified but it is not evaluated!

Alternatively, the functions StringToInt or StringToReal be used

Function definition: Val(Source : string, Value : real, Interrupt : integer) : integer

Parameter:
Source	Name of the source string
Value	Name of the num. variable for value
Interrupt	Conversion information (is not evaluated)
Return values:
	none, but variable code shows the conversion status
> = 0	when converted
< 0	if not converted

Example

PROGRAM

(* Function gives the index of the position in the "Interrupt" variable, *)
(* at which the function was interrupted again.                          *)

function fktVal(Source : string) : integer

var Value : real
var Interrupt: integer

begin
    Val(Source, Value, Interrupt)
    fktVal := Value
end

BEGIN
    fktVal(Source)
END

StringToUpper

Function for converting a string to upper case.

Function definition: StringToUpper(var string:text) : integer

Parameter:
StrSrc	Variable to be converted
Return values:
0	when converted
<0	if not converted

Example

PROGRAM

function ToUpper(Source : string) : integer

var Error : integer
begin
Error := StringToUpper(Source)
end

BEGIN
ToUpper('text')
END

(* -->   Source := 'TEXT' *)

StringToLower

Function for converting a string to lower case

Function definition: StringToLower(var string:text) : integer

Parameter:
StrSrc	Variable to be converted
Return values:
0	when converted
<0	if not converted

Example

PROGRAM

function ToLower(Source : string) : integer

var Error : integer
begin
Error := StringToLower(Source)
end

BEGIN
ToLower('TEXT')
END

(* -->   Source := 'text' *)

StringTrim

Removes all named positions (left, right or both sides) where the letter to be removed occurs in a string.

Function definition: StringTrim(var string: strSrc, integer: type, string(char):v1…vn) : integer

Parameter:
StrSrc	String on which the trim command is to be used
Type	Type of trimming (1 = left, 2 = right, 3 = left and right)
V1…n	One or more characters to be removed
Return values:
-3	TrimType was not found
-2	List of characters to be removed is incorrect
-1	Unhandled error
0	If function was carried out successfully

Example

PROGRAM

function Trim(Source : string, Type : integer, V1,V2 : string) : integer

var Error : integer
begin
Error := StringTrim(Source, Type, V1, V2)
end

BEGIN
Trim('AACCABCCAAB', 1, 'A', 'B')
END

(* -->   Source := 'CCABCCAAB' *)

StringTemplate

Function for inserting values into a character string

Function definition: StringTemplate(var string: strSrc (string,integer,real, Boolean:v1…vn) : integer

Parameter:
StrSrc	String to be formatted
V1…n	One or more characters to be inserte
Return values:
-2	Format ist not correct (not available in IoT
-1	Unhandled error
0	If function was carried out successfully

Example

PROGRAM

function Template(Source : string, V1,V2 : string) : integer

var Error : integer
begin
Error := StringTemplate(Source, V1, V2)
end

BEGIN
Template('Temperature in room {0} is {1} degrees', V1, V2)
END

(* -->   Source := 'Temperature in room Support is 50 degrees' *)

StringReplace

Function for replacing a Unicode character or a string in a character string

Function definition: StringReplace(var string: strSrc real, Boolean:v1…vn) : integer

Parameter:
StrSrc	String in which the Unicode characters are to be replaced
OldValue	The character or string to be replaced
NewValue	The replacing character or string
Return values:
-1	Unhandled error
0	If function was carried out successfully

Example

PROGRAM

    function Replace(Source : string, OldValue,NewValue : string) : integer

var Error : integer
begin
Error := StringReplace(Source, OldValue, NewValue)
end

BEGIN
Replace('How are you!', '!', '?')
END

(* -->   Source := 'How are you?' *)

StringToInt

Function for converting a string into an integer

Function definition: StringToInt(string: strSrc, var integer:intDest) : integer

Parameter:
StrSrc	Name of the source string
IntDest	Name of the target intege
Return values:
-1	Picture change not possible
0	If function was carried out successfully

Example

PROGRAM

function ToInt(Source : string, Dest : integer) : integer

var Error : integer
begin
Error := StringToInt(Source, Dest)
end

BEGIN
ToInt('5', Dest)
END

(* -->   Dest := 5 *)

StringToReal

Function for converting a string into a number with decimal places. Representation only possible with a point and no comma, as this corresponds to the international standard

Function definition: StringToReals(string: strSrc, var integer:realDest) : integer

Parameter:
StrSrc	Name of the source string
RealDest	Name of the target rea
Return values:
-1	Picture change not possible
0	If function was carried out successfully

Example

PROGRAM

function ToReal(Source : string, Dest : real) : integer

var Error : integer
begin
Error := StringToReal(Source, Dest)
end

BEGIN
ToInt('5.55', Dest)
END

(* -->   Dest := 5.55 *)

IsNumeric

Function to query whether an expression can be evaluated as a number.

Function definition: IsNumeric(string: strSrc) : integer

Parameter:
StrSrc	Name of the source string
Return values:
-1	Is no real or integer
0	If function was carried out successfully

Example

PROGRAM

function IsNumVar(Source : string) : integer

var Error : integer
begin
Error := IsNumeric(Source)
end

BEGIN
IsNumVar('5')
END

(* -->   Error := 0 *)

StringFormat

Function for formatting an integer / real that is formatted according to the instructions in a string format expression

Function definition: StringFormat(string: strSrc, string format, [var]destString) : integer

Parameter:
Source	Integer / Real to be formatted
Format	A valid format string expression
DestString	Name of the target string
Return values:
-3	Format is not correct
-2	Is no integer oder real
-1	Unhandled error
0	If function was carried out successfully

Example

PROGRAM

function Format(Source : integer, Format,DestString : string) : integer

var Error : integer
begin
Error := StringFormat(Source, Format, DestString)
end

BEGIN
Format(1000000, '{0:n}', DestString)
END

(* -->   DestString := '1,000,000.00' *)

StringRegExIsMatch

Function to query whether the regular expression finds a match in the specified input string

Function definition: StringRegExIsMatch(string: strSrc, string pattern) : integer

Parameter:
StrSrc	The string to search for a match
Pattern	The regular expression pattern to match
Return values:
-3	A regular expression parsing error occurred (not present in IoT)
-2	Timeout (not available in IoT
-1	When the regular expression does not find a match
0	When the regular expression finds a match

Example

PROGRAM

function RegExIsMatch(Source,Pattern : string) : integer

var Error : integer
begin
Error := StringRegExIsMatch(Source, Pattern)
end

BEGIN
RegExIsMatch('hello', 'l{2}')
END

(* --> Error := 0 *)

StringIndexOf

Function returns the zero-based index of the first occurrence of a specified Unicode character or Unicode string

Function definition: StringIndexOf(string: strSrc, string pattern) : integer

Parameter:
StrSrc	The string to search in
Pattern	The string to searc
Return values:
-1	The string to search for was not found
>0	Function returns the zero-based index of the first occurrence

Example

PROGRAM

function IndexOf(Source,SeekStr : string) : integer

var Error : integer
begin
Error := StringIndexOf(Source, SeekStr)
end

BEGIN
IndexOf('PROCON-WEB', 'C')
END

(* -->   Error := 3 *)

StringStartsWith

Function to query whether the beginning of this string instance matches the specified string

Function definition: StringStartsWith(string: strSrc, string comString) : integer

Parameter:
StrSrc	The string to search in
ComString	The string to compare
Return values:
-1	String does not start with the string to be compared
0	String starts with the string to be compared

Example

PROGRAM

function StartsWith(Source,ComStr : string) : integer

var Error : integer
begin
Error := StringStartsWith(Source, ComStr)
end

BEGIN
StartWith('PROCON-WEB', 'PROCON')
END

(* --> Error := 0 *)

StringEndsWith

Function to query whether the end of this string instance matches the specified string

Function definition: StringEndsWith(string: strSrc, string comString) : integer

Parameter:
StrSrc	The string to search in
ComString	The string to compare
Return values:
-1	String does not end with the string to be compared
0	String ends with the string to be compared

Example

PROGRAM

function EndsWith(Source,ComStr : string) : integer

var Error : integer
begin
Error := StringEndsWith(Source, ComStr)
end

BEGIN
EndsWith('PROCON-WEB', '-WEB')
END

(* -->   Error := 0 *)

StringInsert

Function to insert a string at the specified index position in the current string

Function definition: StringInsert(string: strSrc, integer:startIndex, string:insertValue) : integer

Parameter:
StrSrc	The string to search in
startIndex	The string to compare
insertValue	The value to insert
Return values:
-2	Starting index is too high or too little
-1	Unhandled error
0	If function was carried out successfully

Example

PROGRAM

function Insert(Source : string, StartIndex : integer, InsertVal : string) : integer

var Error : integer
begin
Error := StringInsert(Source, StartIndex, InsertVal)
end

BEGIN
Insert('PROCONWEB', 6, '-')
END

(* -->   Source := 'PROCON-WEB' *)

StringRemove

Function to remove a specified number of characters from the current string

Function definition: StringRemove(string: strSrc, integer:position, integer:count) : integer

Parameter:
StrSrc	Name of the source string
Position	Position of the deletion (1 = left, 2 = right, 3 = left and right)
Count	Number of characters to be deleted
Return values:
-3	Position was not found
-2	Count not correct
-1	Unhandled error
0	If function was carried out successfully

Example

PROGRAM

function Remove(Source : string, StartIndex,Count : integer) : integer

var Error : integer
begin
Error := StringRemove(Source, StartIndex, Count)
end

BEGIN
Remove('PROCON-WEB 6.4', 2, 4)
END

(* -->   Source := 'PROCON-WEB' *)

Math and calculation functions

Sqrt

Function to calculate the square root

Function definition: Sqrt(Value : real) : real

Parameter:
Value	Value from which the square root is drawn
Return values:
Function value	Square root

Example

PROGRAM

function fktSqrt(Value : real) : integer
begin
    fktSqrt := Sqrt(Value)
end

BEGIN
    fktSqrt(Source)
END

Ln

Function for calculating the natural logarithm

Function definition: Ln(Value : real) : real

Parameter:
Value	Value to be logarithmised
Return values:
Function value	Logarithm of the value

Example

PROGRAM

function fktLn(Value : real) : integer
begin
    fktLn := Ln(Value)
end

BEGIN
    fktLn(Source)
END

Exp

Function to calculate the power e ^ x

Function definition: Exp(Value : real) : real

Parameter:
	Value to be raised to the power
Return values:
Function value	natural power of the value

Example

PROGRAM

function fktExp(Value : real) : integer
begin
    fktExp := Exp(Value)
end

BEGIN
    fktExp(Source)
END

Log

Function to calculate the 10th logarithm

Function definition: Log(Value : real) : real

Parameter:
Value	Value to be logarithmised
Return values:
Function value	10er logarithm of the value

Example

PROGRAM

function fktLog(Value : real) : integer
begin
    fktLog := Log(Value)
end

BEGIN
    fktLog(Source)
END

Pow

Function to calculate a power x ^ y

Function definition: Pow(XValue, YValue : real) : real

Parameter:
XValue	Basis for potentiation
YValue	Exponent for potentiation
Return values:
Function value	Value for potentiation

Example

PROGRAM

function fktPow(XValue, YValue : real) : integer
begin
    fktPow := Pow(XValue, YValue)
end

BEGIN
    fktPow(XValue, YValue)
END

Abs

Function for calculating the absolute value. The absolute value function assigns its absolute value to every real number

Function definition: Abs(Value : real) : real

Parameter:
Value	Value for the amount function
Return values:
Function value	Real value

Example

PROGRAM

function fktAbs(Value : real) : integer
begin
    fktAbs := Abs(Value)
end

BEGIN
    fktAbs(Source)
END

Trigonometrical function

Sin

Function for calculating the sine value from an angle value

Function definition: Sin(Value : real) : real

Parameter:
Value	Angle value in rad between 0 and 2 PI
Return values:
Function value	Sine value

Example

PROGRAM

function fktSin(Value : real) : integer
begin
    fktSin := Sin(Value)
end

BEGIN
    fktSin(Source)
END

Cos

Function for calculating the cosine value from an angle value

Funktionsdefinition: Cos(Value : real) : real

Parameter:
Value	Angle value in rad between 0 and 2 PI
Return values:
Function value	Cosine value

Example

PROGRAM

function fktCos(Value : real) : integer
begin
    fktCos := Cos(Value)
end

BEGIN
    fktCos(Source)
END

Tan

Function for calculating the tangent value from an angle value

Function definition: Tan(Value : real) : real

Parameter:
Value	Angle value in rad between -PI / 2 and PI / 2
Return values:
Function value	Tangent value

Example

PROGRAM

function fktTan(Value : real) : integer
begin
    fktTan := Tan(Value)
end

BEGIN
    fktTan(Source)
END

Arcsin

Function for calculating the arc sine value from an angle value

Function definition: Arcsin(Value : real) : real

Parameter:
Value	Value between -1 and 1
Return values:
Function value	Arc sine value

Example

PROGRAM

function fktArcsin(Value : real) : integer
begin
    fktArcsin := Arcsin(Value)
end

BEGIN
    fktArcsin(Source)
END

Arccos

Function for calculating the arccosine value from an angle value

Function definition: Arccos(Value : real) : real

Parameter:
Value	Value between -1 and 1
Return values:
Function value	Arccosine value

Example

PROGRAM

function fktArccos(Value : real) : integer
begin
    fktArccos:= Arccos(Value)
end

BEGIN
    fktArccos(Source)
END

Arctan

Function for calculating the arctangal value from an angle value

Function definition: Arctan(Value : real) : real

Parameter:
Value	between -infinite and + infinite
Return values:
Function value	Arc tangent value

Example

PROGRAM

function fktArctan(Value : real) : integer
begin
    fktArctan := Arctan(Value)
end

BEGIN
    fktArctan(Source)
END

Arctan2

Function for calculating the arctangle value with two parameters.In contrast to the Arctan, it can observe the signs of both parameters and thus determine the quadrant of the result.

Function definition: Arctan(Value1, Value2 : real) : real

Parameter:
Value1	between -infinite and + infinite
Value2	between -infinite and + infinite
Return values:
Function value	Arc tangent 2 value

Example

PROGRAM

function fktArctan2(Value1, Value2 : real) : integer
begin
    fktArctan2 := Arctan2(Value1, Value2)
end

BEGIN
    fktArctan2(Source1, Source2)
END

Sinh

Function for calculating the hyperbolic sine value from an angle value.

Function definition: Sinh(Value : real) : real

Parameter:
Value	Real numbers
Return values:
Function value	Hyperbolic sine value

Example

PROGRAM

function fktSinh(Value : real) : integer
begin
    fktSinh := Sinh(Value)
end

BEGIN
    fktSinh(Source)
END

Cosh

Function for calculating the hyperbolic cosine value from an angle value

Function definition: Cosh(Value : real) : real

Parameter:
Value	Real numbers
Return values:
Function value	Hyperbolic cosine value

Example

PROGRAM

function fktCosh(Value : real) : integer
begin
    fktCosh := Cosh(Value)
end

BEGIN
    fktCosh(Source)
END

Tanh

Function for calculating the hyperbolic tangent value from an angle value.

Function definition: Cosh(Value : real) : real

Parameter:
Value	Real numbers
Return values:
Function value	Hyperbolic tangent value

Example

PROGRAM

function fktTanh(Value : real) : integer
begin
    fktTanh := Tanh(Value)
end

BEGIN
    fktTanh(Source)
END

Time & date functions

The following formatting works only in SCADA Systems.

Format specifier	Description	Examples
“ d”	The day of the month, from 1 to 31	2009-06-01T13:45:30 -> 1
		2009-06-15T13:45:30 -> 15
“dd”	The day of the month, from 1 to 31	2009-06-01T13:45:30 -> 01
		2009-06-15T13:45:30 -> 15
“ddd”	The abbreviated name of the day of the week	2009-06-15T13:45:30 -> Mon.
“dddd”	The full name of the day of the week	2009-06-15T13:45:30 -> Monday
“ f”	The tenths of a second in a date and time value	2009-06-15T13:45:30.6170000 -> 6
		2009-06-15T13:45:30.05 -> 0
“ff”	The hundredth of a second in a date and time value	2009-06-15T13:45:30.6170000 -> 61
		2009-06-15T13:45:30.0500000 -> 00
“fff”	The milliseconds in a date and time value	6/15/2009 13:45:30.617 -> 617
		6/15/2009 13:45:30.0005 -> 000
“ffff”	The ten-thousandths of a second in a date and time value	2009-06-15T13:45:30.6175000 -> 6175
		2009-06-15T13:45:30.0000500 -> 0000
“fffff”	The hundred thousandths of a second in a date and time value	009-06-15T13:45:30.6175400 -> 61754
		6/15/2009 13:45:30.000005 -> 00000
“ffffff”	The millionth of a second in a date and time value	2009-06-15T13:45:30.6175420 -> 617542
		2009-06-15T13:45:30.0000005 -> 000000
“fffffff”	The ten millionth of a second in a date and time value	2009-06-15T13:45:30.6175425 -> 6175425
		2009-06-15T13:45:30.0001150 -> 0001150
“ F”	If not equal to zero, the tenths of a second in a date and time value	2009-06-15T13:45:30.6170000 -> 6
		2009-06-15T13:45:30.0500000 -> (no output)
“FF”	If not equal to 0 (zero), the hundredths of a second in a date and time value	2009-06-15T13:45:30.6170000 -> 61
		2009-06-15T13:45:30.0500000 -> (no output)
“FFF”	If nonzero, the milliseconds in a date and time value.	2009-06-15T13:45:30.6170000 -> 617
		2009-06-15T13:45:30.0500000 -> (no output)
“FFFF”	If non-zero, the ten-thousandths of a second in a date and time value	2009-06-15T13:45:30.5275000 -> 5275
		2009-06-15T13:45:30.0500000 -> (no output)
“FFFFF”	If nonzero, the hundred thousandths of a second in a date and time value	2009-06-15T13:45:30.6175400 -> 61754
		2009-06-15T13:45:30.0500000 -> (no output)
“FFFFFF”	If not zero, the millionth of a second in a date and time value	2009-06-15T13:45:30.6175420 -> 617542
		2009-06-15T13:45:30.0500000 -> (no output)
“FFFFFFF”	If not equal to zero, the ten millionths of a second in a date and time value	2009-06-15T13:45:30.6175425 -> 6175425
		2009-06-15T13:45:30.0001150 -> 000115
“ g”, “gg”	The period	2009-06-15T13:45:30.6170000 -> A.D.
“ h”	The hour, from 1 to 12 (12-hour format)	2009-06-15T01:45:30 -> 1
		2009-06-15T13:45:30 -> 1
“hh”	The hour, from 01 to 12 (12-hour format)	2009-06-15T01:45:30 -> 01
		2009-06-15T13:45:30 -> 01
“ H”	The hour, from 0 to 24 (24-hour format)	2009-06-15T01:45:30 -> 1
		2009-06-15T13:45:30 -> 13
“HH”	The hour, from 00 to 23 (24-hour format)	2009-06-15T01:45:30 -> 01
		2009-06-15T13:45:30 -> 13
“ K”	Time zone information	With DateTime values
		2009-06-15T13:45:30, type not specified ->
		2009-06-15T13:45:30, UTC time zone -> Z
		2009-06-15T13:45:30, local time zone -> -07:00 (depends on the local computer settings)
		WithDateTimeOffset()Values:
		2009-06-15T01:45:30-07:00 –> -07:00
		2009-06-15T08:45:30+00:00 –> +00:00
“ m”	The minute, from 0 to 59	2009-06-15T01:09:30 -> 9
		2009-06-15T13:29:30 -> 29
“mm”	The minute, from 00 to 59	2009-06-15T01:09:30 -> 09
		2009-06-15T01:45:30 -> 45
“M”	The month from 1 to 12	2009-06-15T13:45:30 -> 6
“MM”	The month from 01 to 12	2009-06-15T13:45:30 -> 06
“MMM”	The abbreviated name of the month	2009-06-15T13:45:30 -> Jun
“MMMM”	The full name of the month	2009-06-15T13:45:30 -> June
“ s”	The second, from 0 to 59	2009-06-15T13:45:09 -> 9
“ss”	he second, from 00 to 59”	2009-06-15T13:45:09 -> 09
“ t”	The first character of the AM / PM identifier	2009-06-15T13:45:30 -> P (en-US)
“tt”	The AM / PM qualifier	2009-06-15T13:45:30 -> PM
“ y”	The year, from 0 to 99	0001-01-01T00:00:00 -> 1
		0900-01-01T00:00:00 -> 0
		1900-01-01T00:00:00 -> 0
		2009-06-15T13:45:30 -> 9
		2019-06-15T13:45:30 -> 19
“yy”	The year, from 00 to 99	0001-01-01T00:00:00 -> 01
		0900-01-01T00:00:00 -> 00<
		1900-01-01T00:00:00 -> 00
		2019-06-15T13:45:30 -> 19
“yyy”	The year, with a minimum of three digits	0001-01-01T00:00:00 -> 001
		0900-01-01T00:00:00 -> 900
		1900-01-01T00:00:00 -> 1900
		2009-06-15T13:45:30 -> 2009
“yyyy”	The year as a four-digit number	0001-01-01T00:00:00 -> 0001
		0900-01-01T00:00:00 -> 0900
		1900-01-01T00:00:00 -> 1900
		2009-06-15T13:45:30 -> 2009
“yyyyy”	The year as a five-digit number	0001-01-01T00:00:00 -> 00001
		2009-06-15T13:45:30 -> 02009
“ z”	Offset from UTC in hours, without leading zeros	2009-06-15T13:45:30-07:00 -> -7
“zz”	Offset from UTC in hours, with a leading zero for a single-digit value	2009-06-15T13:45:30-07:00 -> -07
“zzz”	Offset from UTC in hours and minutes	2009-06-15T13:45:30-07:00 -> -07:00
“ :”	The time separator	2009-06-15T13:45:30 -> : (en-US)
		2009-06-15T13:45:30 -> .(it-IT)
		2009-06-15T13:45:30 -> : (ja-JP)
“ /”	The date separator	2009-06-15T13:45:30 -> / (en-US)
		2009-06-15T13:45:30 -> - (ar-DZ)
		2009-06-15T13:45:30 -> .(tr-TR)
“Zeichenfolge”	Literal string separator	2009-06-15T13:45:30 (“arr:” h:m t) -> arr: 1:45 P
%	Defines the next character as a user-defined format specifier	2009-06-15T13:45:30 (%h) -> 1
	The escape character	2009-06-15T13:45:30 (h h) -> 1 h
Any other sign	The character is copied unchanged into the result string	2009-06-15T01:45:30 (arr hh:mm t) -> arr 01:45 A

Please note, that Embedded Systems uses different formatting than SCADA. The following formatting works in Embedded Systems:

Formatter	Description
%a	The abbreviated weekday name of the locale
%A	The abbreviated weekday name of the locale
%b	The locale’s full weekday name
%B	The locale’s full weekday name
%c	The locale’s date and time representation. The modified command %c produces the locale’s alternate date and time representation
%C	The year divided by 100 using floored division. If the result is a single decimal digit, it is prefixed with O. The modified command %OC produces the locale’s alternative representation of the century.
%d	The day of month as a decimal number. If the result is a single decimal digit, it is prefixed with O. The modified command %Od produces the locale’s alternative representation.
%D	Equivalent to %m/%d/%y
%e	The day of month as a decimal number. If the result is a single decimal digit, it is prefixed with a space. The modified command %Oe produces the locale’s alternative representation.
%F	Equivalent to %Y-%m-%d
%g	The last two decimal digits of the ISO week-based year. If the result is a single digit it is prefixed by 0.
%G	The ISO week-based year as a decimal number. If the result is less than four digits it is left-padded with 0 to four digits.
%h	Equivalent to %b
%H	The hour (24-hour clock) as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command %OH produces the locale’s alternative representation
%I	The hour (12-hour clock) as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command %OI produces the locale’s alternative representation.
%j	The day of the year as a decimal number. Jan 1 is 001. If the result is less than three digits, it is left-padded with 0 to three digits.
%m	The month as a decimal number. Jan is 01. If the result is a single digit, it is prefixed with 0. The modified command %Om produces the locale’s alternative representation.
%M	The minute as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command %OM produces the locale’s alternative representation.
%n	A newline character
%p	The locale’s equivalent of the AM/PM designations associated with a 12-hour clock.
%r	The locale’s 12-hour clock time
%R	Equivalent to %H:%M
%S	Seconds as a decimal number. If the number of seconds is less than 10, the result is prefixed with 0. If the precision of the input can not be exactly represented with seconds, then the format is a decimal floating point number with a fixed format and a precision matching that of the precision of the input (or to a microseconds pwjhljrecision if the conversion to floating point decimal seconds can not be made within 18 fractional digits). The character for the decimal point is localized according to the locale. The modified command %OS produces the locale’s alternative representation.
%t	A horizontal-tab character
%T	Equivalent to %H:%M:%S
%u	The ISO weekday as a decimal number (1-7), where Monday is 1. The modified command %Ou produces the locale’s alternative representation
%U	The week number of the year as a decimal number. The first Sunday of the year is the first day of week 01. Days of the same year prior to that are in week 00. If the result is a single digit, it is prefixed with 0. The modified command %OU produces the locale’s alternative representation.
%V	The ISO week-based week number as a decimal number. If the result is a single digit, it is prefixed with 0. The modified command %OV produces the locale’s alternative representation.
%w	The weekday as a decimal number (0-6), where Sunday is 0. The modified command %Ow produces the locale’s alternative representation.
%W	The week number of the year as a decimal number. The first Monday of the year is the first day of week 01. Days of the same year prior to that are in week 00. If the result is a single digit, it is prefixed with 0. The modified command %OW produces the locale’s alternative representation.
%x	The locale’s date representation. The modified command %Ex produces the locale’s alternate date representation.
%X	The locale’s time representation. The modified command %Ex produces the locale’s alternate time representation.
%y	The last two decimal digits of the year. If the result is a single digit it is prefixed by 0.
%Y	The year as a decimal number. If the result is less than four digits it is left-padded with 0 to four digits.
%z	The offset from UTC in the ISO 8601 format. For example -0430 refers to 4 hours 30 minutes behind UTC. If the offset is zero, +0000 is used. The modified commands %Ez and %Oz insert a : between the hours and minutes: -04:30.
%Z	The time zone abbreviation
%%	A % character

Examples of embedded systems formatting:

Formatter	Result
%H:%M:%S %d.%m.%Y	14:20:30.00000000 23.07.2021
%H:%M:%OS %d.%m.%Y	14:20:30 23.07.2021
%I:%M:%OS %d.%m.%Y %p	02:30:39 28.07.2021 PM
%FT%H:%M	2021-07-23T14:20
%c	Wed Jul 28 14:31:48 2021
%A %B %Y	Wednesday July 2021
%T %Z	14:36:38.000000000 UTC

AbsToTime

Function for determining the date and time information from an absolute system time since 1.1.1970.” The output format is the same as the input format, means that if milliseconds are entered, they will also be marked with , if they are not recorded when entered, the output value only in seconds

Function definition: AbsToTime(AbsTime : real, Day, Month, Year, Hour, Minute, Second, Millisecond : integer) : integer

Parameter:
AbsTime	Absolute system time in seconds since 1.1.1970
Day	Day Variable that receives the day of the month 1..31 as a value
Month	Day Variable that receives the day of the year 1..12 as a value
Year	Day Variable that receives the year 1970..2038 as a value
Hour	Variable that receives the hour of the day 0..23 as a value
Minute	ariable that receives the minute of the hour 0..59 as a value”
Second	Variable that receives the second of the minute 0..59 as a value
Millisecond	Variable that receives the millisecond of the second 0..999 as a value
Return values:
>= 0	if ok
< 0	Incorrect parameterisation

Example

PROGRAM

function fktAbsToTime(AbsTime : real) : integer

var Day, Month, Year, Hour, Minute, Second, Millisecond : integer

begin
    AbsToTime(AbsTime, Day, Month, Year, Hour, Minute, Second, Millisecond)
    (* copy to global variables *)
    Global_Day    := Day
    Global_Month  := Month
    Global_Year   := Year
    Global_Hour   := Hour
    Global_Minute := Minute
    Global_Second := Second
        Global_Millisecond := Millisecond
end

BEGIN
    fktAbsToTime(Source)
END

TimeToAbs

Function to determine the system time in seconds since 1.1.1970.

Function definition: TimeToAbs(Day, Month, Year, Hour, Minute, Second, Millisecond : integer) : real

Parameter:
Day	Day of month 1..31
Month	Month of the year 1..12
Year	Year 1970..2038
Hour	Hour of the day 0..23
Minute	Minute of the hour 0..59
Second	Second of the minute 0..59
Millisecond	Millisecond of the second 0..999
Return values:
>= 0	if no error occurs, it returns the time value
< 0	Incorrect parameterisation

Example

PROGRAM

function fktTimeToAbs() : integer

var Day, Month, Year, Hour, Minute, Second, Millisecond : integer

begin
    Day     := Time(0)
    Month   := Time(1)
    Year    := Time(2)
    Hour    := Time(5)
    Minute  := Time(6)
    Second  := Time(7)
    Milllisecon := Time(8)

    fktTimeToAbs := TimeToAbs(Day, Month, Year, Hour, Minute, Second, Millisecond)
end

BEGIN
    fktTimeToAbs()
END

Time

Function for reading out the current system time in individual components

Function definition: Time(Index : integer) : integer

Parameter:
Index		Index of the time entry	Area
	0	Day	1..31
	1	month	1..12
	2	year	1970…
	3	Day of the week 0 = Sunday	0..6
	4	Day of the year	1..365
	5	Hour of the day	0..23
	6	Minute of the hour	0..59
	7	Second of the minute	0..59
	8	Time in seconds since 1970	0..2^31
	9	Milliseconds	0..999
	10	Time in seconds since 1970 with daylight saving time offset without time zone offset	0..2^31
	11	Time in seconds since 1970 with time zone offset without daylight saving time offset	0..2^31
	12	Time in seconds since 1970 without time zone offset and daylight-saving time offset (supplies UTC time)	0..2^31

Return values:
-1	if index is not valid
otherwise	the value of the time entry

Example

PROGRAM

function fktTime() : integer

var Day, Month, Year, Day_W, Day_Y : integer
var Hour, Minute, Second, Second1970, Millisecond : integer

begin
    Day          := Time(0)
    Month        := Time(1)
    Year         := Time(2)
    Day_W        := Time(3)
    Day_Y        := Time(4)
    Hour         := Time(5)
    Minute       := Time(6)
    Second       := Time(7)
    Second1970   := Time(8)
    Millisecond  := Time(9)
end

BEGIN
    fktTime()
END

TimeUtcToLocal

Converts the absolute time from UTC time to local time. Assumes that the specified time is UTC.

Function definition: TimeUTCToLocal(Var integer : absTime)

Parameter:
AbsTime	Absolute system time in seconds since 1.1.1970
Return values:
-1	if index is not valid
0	if the function was carried out successfully

Example

PROGRAM

function fktTimeUtcToLocal(AbsTime : integer) : integer

(*
AbsTime: 957503105005
AbsTimereturn: 957510305005
2 hours shift
*)

var Error :integer
begin
        Error := TimeUtcToLocal(AbsTime)
end
BEGIN
        fktTimeUtcToLocal(Source)
END

TimeLocalToUtc

Converts the absolute time from local time to UTC time. Assumes the given time is local

Function definition: TimeLocalToUtc(Var integer : absTime)

Parameter:
AbsTime	Absolute system time in seconds since 1.1.1970
Return values:
-1	if index is not valid
0	if the function was carried out successfully

Example

PROGRAM

function fktTimeLocalToUtc(AbsTime : integer) : integer

(*
AbsTime: 957503105005
AbsTime return: 957495905005
2 hours shift
*)

var Error :integer
begin
        Error := TimeLocalToUtc(AbsTime)
end
BEGIN
        fktTimeLocalToUtc(Source)
END

DateAdd

Function for adding specific time periods to the absolute system time.

Function definition: DateAdd(Var integer AbsTime, integer Version, integer Addition)

Parameter:
AbsTime	Absolute system time in seconds since 1.1.1970
Version	Numerical differentiation of the type of addition
0	Milliseconds
1	Seconds
2	Minutes
3	Hours
4	Days
5	months
6	years
Addition	Numerical amount which is added
Return values:
-2	wrong version
-1	Incorrect parameterisation
0	if the function was carried out successfully

Example

PROGRAM

function fktDateAdd(Milliseconds : real) : integer

(*
AbsTime: 957503105005
Version:5 (month)
Addition:5
Date return:970722305005
*)

var Error :integer
begin
        Error := DateAdd(AbsTime, Version, Addition)
end
BEGIN
        fktDateToString(Source,  Version, Addition)
END

DateStringAdd

Function for adding specific time periods to the absolute system time.

Function definition: DateStringAdd(Var string: Date,string : Format, integer Version, integer Addition)

Parameter:
Date	Date which is taken as the basis
Version	Numerical differentiation of the type of addition
0	Milliseconds
1	Seconds
2	Minutes
3	Hours
4	Days
5	months
6	years
Addition	Numerical amount which is added
Return values:
-3	Wrong format
-2	wrong version
-1	Incorrect parameterisation
0	if the function was carried out successfully

Example

PROGRAM

function fktDateStringAdd(Milliseconds : real) : integer

(*
Date: 05.05.2000 05:05:05:0050
Format:MM.dd.yyyy HH:mm:ss:ffff
Version:5 (month)
Addition:5
Date return:10.05.2000 05:05:05:0050
*)

var Error :integer
begin
        Error := DateStringAdd(Date, Format, Version, Addition)
end
BEGIN
        fktDateToString(Source, Format, Version, Addition)
END

DateToString

Function for converting date and time information into a string. Exact on 1 second

Function definition: DateToString(integer: AbsTime,string : Format, Var string: Date)

Parameter:
AbsTime	Absolute system time in seconds since 1.1.1970
Format	Format of the date string
Date	Formatted date
Format	Parameter DateTime
Return values:
-3	Wrong format
-2	Date is too big (not available in IoT
-1	Incorrect parameterisation
0	if the function was carried out successfully

Example

PROGRAM

PROGRAM

function fktDateToString(Milliseconds : real) : integer

(*
Abstime: 957503105005
Format:MM.dd.yyyy HH:mm:ss:ffff
Datestring:05.05.2000 05:05:05:0050
*)

var Error :integer
begin
        Error := DateToString(Abstime, Format, Datestring)
end
BEGIN
        fktDateToString(Source)
END

DateToAbs

Function for converting a date in string format to an absolute value

Function definition: DateToAbs(string: Date,string : Format, Var integer: AbsTime)

Parameter:
Date	Formatted date
Format	Format of the date string
AbsTime	Absolute system time in seconds since 1.1.1970
Format	Parameter DateTime
Return values:
-2	Wrong format
-1	Incorrect parameterisation
0	if the function was carried out successfully

Example

PROGRAM

function fktDateToString(Milliseconds : real) : integer

(*
Datestring: 05.05.2000 05:05:05:0050
Format:MM.dd.yyyy HH:mm:ss:ffff
AbsTime:957503105005
*)

var Error :integer
begin
        Error := DateToAbs(Datestring, Format, AbsTime)
end
BEGIN
        fktDateToString(Source)
END

TimespanToString (onlySCADA)

Function to convert milliseconds to seconds, hours, and minutes

Function definition: TimespanToString(integer: Milliseconds, string: Format, Var string: Timespan)

Parameter:
Milliseconds	Milliseconds to convert
Format	Format string of the time span
Timespan	Time span as a string
Return values:
-3	Wrong format
-2	The date is too big
-1	Incorrect parameterisation
0	if the function was carried out successfully

Example

PROGRAM

function fktTimespanToString(Milliseconds : real) : integer

(*
Milliseconds: 1535486000
= 17 days, 18 hours, 31 minutes, 26 seconds
Format:dd\.hh\:mm\:ss
Resultstring:17.18:31:26
*)

var Error :integer
begin
        Error := TimespanToString(Milliseconds, Format, Resultstring)
end
BEGIN
        fktTimespanToString(Source)
END

User management functions (only SCADA)

Login

Function for logging in (registering) a user

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: Login(User, Password : string) : integer

Parameter:
User	Name of the user
Password	Password of the user
Return values:
1	Login successful, new password required the next time you log in
0	if the function was carried out successfully
-1	Access denied
-2	Unknown user / password
-3	Incorrect password entry, account will be blocked if you enter the wrong password again
-4	Account gesperrt
-5	Account blocked

Example

PROGRAM

function loginMeister(passWD : string) : integer

begin
    loginMeister := Login('Meister', passWD)
end

BEGIN
    loginMeister('MstPss')
END

Logout

Function for logging out the current user.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: Logout() : integer

Return values:
0	if the function was carried out successfully
-1	if no logout is possible

Example

PROGRAM

function loginOut() : integer

begin
    loginOut:= Logout()
end

BEGIN
    loginOut()
END

The following functions for user management are now also available:

• SetUserPassword

• CreateUser

• DeleteUser

• SetUserGroup

• GetUserGroup

• SetUserInfo

• GetUserInfo

Important

It is important to note that the functions are ALWAYS carried out in the respective context of the executing user, therefore the functions currently only work in the context of a client,

ie they can be executed e.g. by button clicks or image scripts within a client in the context of the logged on user but NOT as global tasks, as there is no user in the server context with whom the user management could request permission to process the functio

Important

Example: There are 2 clients in the system:

Client1, user “admin” logged on. It is in the “Administrators” user group, which has the right to create users (system rights-> user management -> (5) create new users)

Client2, user “guest” logged on. He is in the “Guests” user group, which does NOT have the right.If Client1 executes the CreateUser () function, a new user is created if this was not yet available and noError (0) is returned as the result

If Client2 executes the CreateUser () function, NO new user is created because the user “guest” does not have the right to do so and permissionDenied (-1) is returned as an error. This would also happen if a global task executed the function because there is no valid user for verification.

All functions return the same return values that are returned directly from PROCONWEB’s user administration. Of course, some error codes only exist in special contexts, but these are all possible error codes that can occur with the functions.

With every error code <> noError (0) the desired functionality was NOT executed.Like the other system functions, all functions return 0 if they have been processed successfully, otherwise one of the following error codes is returned:

Error code	Return value	Description
noError	0	Function carried out successfully
permissionDenied	-1	No permission to perform the function
unkno wnUserOrWrongPassword	-2	Unknown user or wrong password
wrong PasswordAccountClosed	-3	Wrong User password, account was deactivated
accountClosed	-4	Account is deactivated
passwordExpired	-5	password is expired
nameAlreadyUsed	-6	The name is already in use
invalidUserInfo	-7	Invalid user info
changeUserDenied	-8	No permission to modify the user
password PolicyNotRespected	-9	The password policies were not adhered to
passwordAlreadyUsed	-10	The password has already been used
groupUnknown	-11	Unknown user group
group AssignmentNotAllowed	-12	Group assignment is not permitted
deleteUserNotAllowed	-13	Deleting the user is not allowed
deleteUser NotAvailable	-14	The user to be deleted does not exist
deleteUserNotPossible	-15	It is not possible to delete the user
duplicateIdentCode	-16	The IdentCode already exists
languageNotAvailable	-17	The requested language does not exist
unknown	-99	Unknown error in user management

CreateUser

With this function a user can be created with the passed password. Further attributes of the user can only be set after a user has been created using the SetUserInfo () function

The right (5) User administration -> Create new user is required for this function

If the function is carried out successfully, the logbook entry 10000004 New user is created.

Function definition: CreateUser(Username: string, Password: string) : integer

Parameter:
Username	Username for the new user
Password	Initial password for the new user
Return values:
0	if the function was carried out successfully
	Or one of the general errors in user administration (see table above)

Example

function CreateTestUser() : boolean
begin
    CreateUser('Test', 'Pw1*')
end

DeleteUser

With this function a user can be deleted.The right (2) User administration -> Change user is required for this functionIf the function is executed successfully, the logbook entry 10000005 user is deleted and create

Function definition: DeleteUser(Username: string) : integer

Parameter:
Username	Username for the user to be deleted
Return values:
0	if the function was carried out successfully
	Or one of the general errors in user administration (see table above)

Example

function DeleteTestUser() : boolean
begin
    DeleteUser('Test')
end

SetUserPassword

This function can be used to set a new password for a user. If password guidelines are defined, the password to be set must correspond to the password guidelines

The right (3) User administration -> Change password of other users is required for this functionIf the function is carried out successfully, the logbook entry 10000007 password is changed, generated

Since the function is intended to change the password of another user, the password is set independently of the password history.

Function definition: SetUserPassword(Username: string, Password: string) : integer

Parameter:
Username	Username for which the password should be set
Password	New password for the new user
Return values:
0	if the function was carried out successfully
	Or one of the general errors in user administration (see table above)

Example

function ChangePassword() : boolean
begin
    Return := SetUserPassword('Admin', 'Admin1*')
end

GetUserGroup

This function can be used to check whether a user is assigned to a user group or not.

Important

ATTENTION: To be able to use the function in the sense of a Boolean query, the return values have been changed:A 1 is returned if the user belongs to the user group, 0 if not. In the event of an error, one of the error codes

Function definition: GetUserGroup(Username: string, Groupname: string, CountryCode: string) : integer

Parameter:
Username	Username of the user who should be checked whether he is assigned to a group
Groupname	Name of the user group
CountryCode	Country code of the group name
	(e.g., 049 for German, or the value of the system variable __CurrentLanguage)
Return values:
0	if the user does not belong to the group
1	If the user belongs to the group
	Or one of the general errors in user administration (see table above)

Example

function Benutzer1Group() : boolean
var i : integer
begin
    i := GetUserGroup('Benutzer1', 'Administrators', __CurrentLanguage)

    if (i = 1) then
        IsUserAdmin := 1
    else
        IsUserAdmin := 0
end

SetUserGroup

With this function a user can be assigned to a user group (mode = 1) or removed from it (mode = 2).

The right (6) User administration -> Assign foreign group is required for this functionIf the function is carried out successfully, the logbook entry 10000006 User was changed is generated

Function definition: SetUserGroup(Username: string, Groupname: string, Modus : integer, CountryCode: string) : integer

Parameter:
Username	Username of the user to be assigned to a group
Groupname	Name of the user group
Modus	Mode 1: Assign users to a grou
	Mode 2: Remove users from a group
CountryCode	Country code of the group name
	(e.g., 049 for German, or the value of the system variable __CurrentLanguage)
Return values:
0	if the function was carried out successfully
	Or one of the general errors in user administration (see table above)

Example

function Benutzer1NotAdmin() : boolean
begin
    SetUserGroup('Benutzer1', 'Administrators', 2, __CurrentLanguage)
end

GetUserInfo

With this function, an attribute of a user can be read out and written to a process variable.The following attributes can be read out and if the attribute is not marked as “readonly” it can also be changed with the SetUserInfo () function. The following attribute IDs are available:

ID	Description	Variable type
0	Name of the user	string
1	ID of the user, internal only, readonly	string
2	Full name of the user	string
3	description of the user, multilingual	string
4	Time of last login, readonly	Numeric (milliseconds since 1970)
5	Status (1 = active, 2 = inactive)	numerically
6	Password aging active	bool
7	Password must be changed the next time you log in	bool
8	Identcode for token authentication	string
9	Identcode active (can be used for login)	bool
10	NotificationType (for notifiaction)	numerically
11	Email address of the user	string
12	Telephone number of the user	string
13	Mobile phone number of the user	string
14	Flag whether the user is an LDAP user	bool
15	Default language of the user	string
16	With Identcode, show login anyway	bool

The description of the user is multilingual; if it is to be set for several languages, the function must be called several times, each with the corresponding country code as a parameter

The country code must be entered as text as the default language of the user, e.g. 049 for German or 044 for English. The country code is configured in the designer when selecting the language.

The following types are available for setting the NotificationType (see Notification):

NotificationType	Description
4	Voice
28	CityCall
44	SMS GSM
66	Voice ISDN
85	CityCall ISDN
10000	Email WithNumerInSubject
10001	Email
20000	Sipgate SMS

Function definition: GetUserInfo(Username: string, InfoId: integer, var variable: undef, CountryCode: string) : integer

Parameter:
Username	Username of the user whose info is to be read
InfoID	ID of the attribute (see table above)
Variable	Process variable of the appropriate type (string, num, bool)
CountryCode	Country code of the group name
	(e.g., 049 for German, or the value of the system variable __CurrentLanguage)
	Different values are only supplied for the InfoID for the description
Return values:
0	if the function was carried out successfully
	Or one of the general errors in user administration (see table above)

Example

function AdminInfoAnfordern() : boolean
begin
    GetUserInfo('Admin', 0, Benutzername, __CurrentLanguage)
    GetUserInfo('Admin', 1, BenutzerID, __CurrentLanguage)
    GetUserInfo('Admin', 2, BenutzernameFull, __CurrentLanguage)
    GetUserInfo('Admin', 3, BenutzerBeschreibung, __CurrentLanguage)
    GetUserInfo('Admin', 4, BenutzerLetzterLogin, __CurrentLanguage)
    GetUserInfo('Admin', 5, BenutzerStatus, __CurrentLanguage)
    GetUserInfo('Admin', 6, PasswortalterungAktiv, __CurrentLanguage)
    GetUserInfo('Admin', 7, PasswortWechsel, __CurrentLanguage)
    GetUserInfo('Admin', 8, BenutzerIdentcodeToken, __CurrentLanguage)
    GetUserInfo('Admin', 9, BenutzerIdentcodeAktiv, __CurrentLanguage)
    GetUserInfo('Admin', 10, BenutzerNotificationTyp, __CurrentLanguage)
    GetUserInfo('Admin', 11, BenutzerEmail, __CurrentLanguage)
    GetUserInfo('Admin', 12, BenutzerTel, __CurrentLanguage)
    GetUserInfo('Admin', 13, BenutzerMobiltel, __CurrentLanguage)
    GetUserInfo('Admin', 14, BenutzerLDAP, __CurrentLanguage)
    GetUserInfo('Admin', 15, BenutzerDefaultsprache, __CurrentLanguage)
    GetUserInfo('Admin', 16, BenutzerIdentcodeLogin, __CurrentLanguage)
end

SetUserInfo

This function can be used to change an attribute of a recipe.

The attributes listed for the GetUserInfo () function can be set if they are not marked as “readonly”. Attempting to write a readonly attribute leads to error 7 - invalid user infoThe right (2) User administration -> Change user is required for this function

If the function is carried out successfully, the logbook entry 10000006 User was changed is generated

Function definition: SetUserInfo(Username: string, InfoId: integer, variable: undef, CountryCode: string) : integer

Parameter:
Username	Username of the user whose info is to be written
InfoID	ID of the attribute (see table Attributes of the GetUserInfo function)
Variable	Process variable of the appropriate type (string, num, bool)
CountryCode	Country code of the group name
	(e.g., 049 for German, or the value of the system variable __CurrentLanguage)
	Different values are only supplied for the InfoID for the description
Return values:
0	if the function was carried out successfully
	Or one of the general errors in user administration (see table above)

Example

function AdminInfoSetzen() : boolean
begin
    SetUserInfo('Admin', 0, Benutzername, __CurrentLanguage)
    SetUserInfo('Admin', 2, BenutzernameFull, __CurrentLanguage)
    SetUserInfo('Admin', 3, BenutzerBeschreibung, __CurrentLanguage)
    SetUserInfo('Admin', 5, BenutzerStatus, __CurrentLanguage)
    SetUserInfo('Admin', 6, PasswortalterungAktiv, __CurrentLanguage)
    SetUserInfo('Admin', 7, PasswortWechsel, __CurrentLanguage)
    SetUserInfo('Admin', 8, BenutzerIdentcodeToken, __CurrentLanguage)
    SetUserInfo('Admin', 9, BenutzerIdentcodeAktiv, __CurrentLanguage)
    SetUserInfo('Admin', 10, BenutzerNotificationTyp, __CurrentLanguage)
    SetUserInfo('Admin', 11, BenutzerEmail, __CurrentLanguage)
    SetUserInfo('Admin', 12, BenutzerTel, __CurrentLanguage)
    SetUserInfo('Admin', 13, BenutzerMobiltel, __CurrentLanguage)
    SetUserInfo('Admin', 15, BenutzerDefaultsprache, __CurrentLanguage)
    SetUserInfo('Admin', 16, BenutzerIdentcodeLogin, __CurrentLanguage)
end

Image processing function

If the image processing functions are called by a client (image or control events), the corresponding image processing functions are only executed for this client. If the functions are executed in global scripting (global tasks), the image processing functions are executed for ALL currently logged on clients. For example, system-wide messages can be displayed on all clients

For images with image-related scripts (cycle script), this is processed in the following cases:

• When opening the image, e.g. via a button

• For the open image, set this to “invisible”

• When opening a picture in a picture areas and set this to “invisible”

When closing and emptying an image area, the script is not processedThis also applies to the previous functions that can now be run again.

Important

All functions currently always return the value 0!

AddPicture

Function for adding a process picture at a certain position and with a defined size on the screen.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Important

AddPicture unterstützt ab der Version 6.8 nur den 2. Parameter (Number) sowie den 3. und 4. optionalen Paremeter (XPos und YPos)

Function definition: AddPicture(Picture, Number, XPos, YPos, Width, Height, Flags: integer): integer

Parameter:
Picture	Number of the picture from which to add
Number	Number of the picture to be added
XPos, YPos	position of the picture (left upper corner) on the screen if the process picture
	position of the picture (left upper corner) in the father window if child picture
Return values:
0	if the function was carried out successfully
-1	if parameterisation error
-2	if added image does not exist
-3	if user level is too low

Example

PROGRAM

function AddMyPicture: integer

var vaterbild, kindbild, xpos, ypos, breite, höhe, flag: integer
var Error : integer
begin
    vaterbild := Vater
    kindbild := Kind
    xpos := XPOS
    ypos := YPOS
    breite := Breite
    höhe := Höhe
    flag := 3

    Error := AddPicture(vaterbild, kindbild, xpos, ypos, breite, höhe, flag)
end

BEGIN
    AddMyPicture()
END

ChangePicture

Function for changing to another process picture.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: ChangePicture(PictNumberOld, PictNumberNew : integer): integer

Parameter:
PictNumberOld	Image number of the image to be switched from, image number from 0 to 65520
PictNumberNew	Number of the picture to be switched to; Picture number from 0 to 65520
XPos, YPos	position of the picture (left upper corner) on the screen if the process picture
	position of the picture (left upper corner) in the father window if child picture
Return values:
0	if the function was carried out successfully
-1	Picture change not possible
-3	The picture number of the picture to be switched from is invalid

Example

PROGRAM

var pictnumberOld, pictnumberNew : integer
var Error : integer

BEGIN
    if BildWechsel then
    begin
        BildWechsel:=0
        pictnumberOld := 0
        pictnumberNew :=10
        Error := ChangePicture(pictnumberOld, pictnumberNew)
    end
END

NewPicture

Function for adding a process picture or function for changing to another process picture.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: NewPicture(Function, PictNumber : integer): integer

Parameter:
Function	0 = adding a new picture
	1 = Function for changing all pictures
PictNumber	Number of the picture to be added
	The picture number from 0 to 65520
XPos, YPos	position of the picture (left upper corner) on
	the screen, if the process picture, position of the picture (left upper corner)
	in the father window if child picture
Return values:
0	if the function was carried out successfully
-1	if window was not found
-2	if function is not correct
-3	if picture number is not correct

Example

PROGRAM

var mode, pictnumber : integer
var Error : integer

BEGIN
    if NeuesBild then
    begin
        NeuesBild := 0
        pictnumber :=10
        mode := 1
        Error := NewPicture(mode, pictnumber)
        If Error <> 0 then
        begin
            Alert(1,400) (* Error executing the function *)
            Alert(2,400)
        end
    end
END

OpenPicture

This function can be used to open a picture based on the picture name or the picture number. The parameter is always a string but can contain either the picture name or the picture number as a string.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: OpenPicture(PictureNameOrNumber : string): integer

Parameter:
PictureNameOrNumber	Name or number of the picture as a string
Return values:
0	If function was carried out successfully
-1	Image could not be loaded (image not found / available)
-2	Picture is already opened
-3	Calling up the picture is already in progress and was called up again

Example

PROGRAM

var Error : integer

Function OpenMyPicture(pict : string) : integer

var Error : integer

Begin
    Error := OpenPicture(pict)
    If Error <> 0 then
    begin
        Alert(1,400) (* Error executing the function *)
        Alert(2,400)
    end

    OpenMyPicture := Error
End

BEGIN
    (* Open picture by name *)
    Error := OpenMyPicture('Uebersicht')

    If Error <> 0 then
    begin
        (* Open picture by number *)
        Error := OpenMyPicture('0004')
    END

    If Error <> 0 then
    begin
        (* Open picture by number *)
        Error := OpenMyPicture('4')
    END
END

ClosePicture

This function can be used to close a picture based on the picture name or the picture number. The parameter is always a string but can contain either the picture name or the picture number as a string.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: ClosePicture(PictureNameOrNumber : string): integer

Parameter:
PictureNameOrNumber	Name or number of the picture as a string
Return values:
0	if the function was carried out successfully
-1	Image could not be closed (image not found / available)

Example

PROGRAM

var Error : integer

Function CloseMyPicture(pict : string) : integer

var Error : integer

Begin
    Error := ClosePicture(pict)
    If Error <> 0 then
    begin
        Alert(1,400) (* Error executing the function *)
        Alert(2,400)
    end

    CloseMyPicture := Error
End

BEGIN
    (* Close picture by name *)
    Error := CloseMyPicture('Uebersicht')

    If Error <> 0 then
    begin
        (* Close picture by number *)
        Error := CloseMyPicture('0004')
    END

    If Error <> 0 then
    begin
        (* Close picture by number *)
        Error := CloseMyPicture('4')
    END
END

PrintPicture

This function can be used to print an image based on the image name or number. The parameter is always a string but can contain either the picture name or the picture number as a string.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: PrintPicture(PictureNameOrNumber : string): integer

Parameter:
PictureNameOrNumber	Name or number of the picture as a string
Return values:
0	if the function was carried out successfully

Example

PROGRAM

var Error : integer

Function PrintMyPicture(pict : string) : integer

Begin
    Error := PrintPicture(pict)
    If Error <> 0 then
    begin
        Alert(1,400) (* Error executing the function *)
        Alert(2,400)
    end

    PrintMyPicture := Error
End

BEGIN
    (* Close picture by name *)
    Error := PrintMyPicture('Uebersicht')

    If Error <> 0 then
    begin
        (* Close picture by number *)
        Error := PrintMyPicture('0004')
    END

    If Error <> 0 then
    begin
        (* Close picture by number *)
        Error := PrintMyPicture('4')
    END
END

ChangeAllPictures

This function closes all visible images and opens the new image. The parameter is always a string but can contain either the picture name or the picture number as a string.

Important

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: ChangeAllPictures(PictureNameOrNumber : string): integer

Parameter:
PictureNameOrNumber	Name or number of the picture as a string
Return values:
0	if the function was carried out successfully

Example

PROGRAM

var Error : integer

Function ChangeMyPicture(pict : string) : integer

var Error : integer

Begin
    Error := ChangeAllPictures(pict)
    If Error <> 0 then
    begin
        Alert(1,400) (* Error executing the function *)
        Alert(2,400)
    end

    ChangeMyPicture := Error
End

BEGIN
    (* Print picture by name *)
    Error := ChangeMyPicture('Uebersicht')

    If Error <> 0 then
    begin
        (* Print picture by number *)
        Error := ChangeMyPicture('0004')
    END

    If Error <> 0 then
    begin
        (* Print picture by number *)
        Error := ChangeMyPicture('4')
    END
END

FillPictureArea

This command deletes the content of a PictureArea and refills it with the specified images.

Important

This command only works for registered clients, i.e., in a local script!This command will Not work in a script that is executed at system start, since the web server does not yet accept any client requests!However, the command may Not be called cyclically, as this leads to a high system load!

Funktionsdefinition: FillPictureArea(PictureAreaId, PictureList : string): integer

Parameter:
PictureAreaId	Name of the PictureArea instance in the picture
PictureList	List of image names with which the area should be filled. The names must be separated by semicolons
Return values:
0	if the function was carried out successfully
-1	Image area with the given name was not found
-2	Several image areas with the same name have been found
-3	An error occurred while loading / assigning the images (image not found / available)

Example

PROGRAM

BEGIN
    FillPictureArea('P_Area', 'Bild1;Bild2;Bild3')
END

FillImageView

Deletes an ImageView, refills it with the specified graphics and displays the graphic with the corresponding index.The image file must be stored in the WebVisu directory of the project directory. Alternatively, transfer the files from outside to the WebVisu directory with a startup scriptto be copied in.

Important

This command only works for registered clients, ie in a local script!This command will Not work in a script that is executed at system start, since the web server does not yet accept any client requests!The instance of the ImageView must be unique within the project!

Function definition: FillImageView(ImageViewId, ImageList : string, Index : integer): integer

Parameter:
ImageViewId	Name of the ImageView instance in the picture
ImageList	List of graphic names with which the area should be filled. The names must be separated by semicolons
Index	Index of the graphic to be displayed. The index is based on 0 and must be between 0 and the number of transferred graphics - 1
Return values:
0	if the function was carried out successfully

Example

PROGRAM

BEGIN
    FillImageView('ImageView1', 'Bitmap1; Bitmap2; Bitmap3', 0)
END

Process variable functions

ReadFromProcess

With this function, the process variables used in the script are currently read from the TagServer.The sync parameter can be used to define whether reading is synchronous or asynchronous. With synchronous reading, the script waits until all values have been read and then continues processing.

Attention

A synchronous reading can be very time-consuming as the process variables are synchronized up to the controller

Important

ReadFromProcess should only be used in exceptional cases, since the ScriptServer already reads at the beginning of a script and unnecessary reading of process variables should be avoided for performance reasons for all context switches to other servers (data management, alarming, …).

Function definition: ReadFromProcess(Sync: integer) : integer

Parameter:
Sync	1: reads the values from the process synchronously, ie the script waits to process until all values have been returned1: reads the values from the process synchronously, ie the script waits to process until all values have been returned
	<> 1: reads the values asynchronously, ie reading the values is triggered, but the script processing continues without waiting until the values have actually been read
Return values:
1	if the function was successfully completed

Example

PROGRAM

FUNCTION Nochmal: integer

var p : integer

begin
    for p:=21 downto 0 do
    begin
        (* Read values from the process *)
        ReadFromProcess(1)
        while XY_Feld[p] > 0 do
            XY_Feld[p] := XY_Feld[p] - 1
        (* Values are now written to the process immediately *)
        WriteToProcess(1)
    end
end

BEGIN
    Nochmal()
END

WriteToProcess

With this function, the process variables used in the script are currently written to the TagServer.The sync parameter can be used to define whether reading is synchronous or asynchronous. With synchronous writing, the script waits until all values have been written and then continues processing.

Attention

Synchronous writing can be very time-consuming since the process variables are synchronised up to the controller.

Important

WriteToProcess should only be used in exceptional cases, since the ScriptServer is already writing at the end of a script and unnecessary writing of process variables should be avoided for performance reasons for all context switches to other servers (data management, alarming, …).

Function definition: WriteToProcess(Sync: integer) : integer

Parameter:
Sync	1: writes the values synchronously with the process, ie the script waits to process until all values have been written
	<> 1: writes the values asynchronously, ie the writing of the values is triggered, but the script processing continues without waiting until the values have actually been written
Return values:
1	if the function was successfully completed

Example

PROGRAM

FUNCTION Nochmal: integer

var p : integer

begin
    for p:=21 downto 0 do
    begin
        while XY_Feld[p] > 0 do
            XY_Feld[p] := XY_Feld[p] - 1
        (* Values are now written to the process immediately *)
        WriteToProcess(1)
    end
end

BEGIN
    Nochmal()
END

GetTagProperty

The new tag properties can be read or written with the two script functions GetTagProperty and SetTagProperty. The functions can also be used to describe the properties Min, Max, MinSPS, MaxSPS and the number of decimal places for numerical values.

Attention

If process variables are used exclusively in scripting via the dynamicfunctions GetValue (), SetValue ()GetTagProperty () and SetTagProperty () and NOWHERE else in the project, they will be recognized by the designer as not referenced, since access to these functions is dynamic works at runtime via the name and NOT via a fixed reference.

This can be seen when all references of the process variable are displayed, and these are then empty and thus the variable is not exported for the runtime.This leads to the return value -2 at runtime for the functions mentioned above.

The following TagProperties can be addressed via their ID:

Name	ID	Note
Min	200	Type numeric, only valid for numeric process variables
Max	201	Type numeric, only valid for numeric process variables
MinExt	202	Type numeric, only valid for numeric process variables
MaxExt	203	Type numeric, only valid for numeric process variables
DecimalPlaces	205	Type numeric, only valid for numeric process variables
Num1	500	Type numeric
Num2	510	Type numeric
Num3	520	Type numeric
Num4	530	Type numeric
Bool1	540	Type logical
Bool2	550	Type logical
String1	560	Type text
String2	570	Type text

The following additional TagProperties can be READONLY addressed via their ID:

Name	ID	Note
Name	1	Type text
ID	2	Type numeric
Size	3	Type numeric, array length or string length, otherwise 1
DriverID	4	Type numeric, number of the driver
DefaultValue	5	Type numerical, logical or text, depending on the process variable
Access	6	Type numeric, 1 = write, 2 = read, 3 = readwrite
External Access	7	Type numeric, 0 = none, 1 = write, 2 = read, 3 = readwrite, if access is via OPC UA server
Type	8	Type numeric, 1 = logical, 2 = numeric, 3 = text
Driver parameters	9	Type text
Driver connection	10	Type numeric, for connection-oriented drivers
Display name	11	Type text, name in the currently set language
Display comment	12	Type text, comment in the currently set language
UnitName	13	Type text, name of the unit
Unit	14	Type text, unit in the currently set language
Unit description	15	Type text, description of the unit in the currently set language
Comment	16	Type text, configuration comment

Function definition: GetTagProperty(TagName: string, PropertyId: integer, Value: var undef) : integer

Parameter:
TagName	Name of the process variable
PropertyId	Id / Number of the property
Value	Value of the property
	boolean for logical properties
	real for logical properties
	string for text properties
	Only real variables, not instances, may be used
Return values:
0	if the function was carried out successfully
-1	General error
-2	invalid process variable
-3	invalid property

Example

PROGRAM

Var TagMin, TagMax : Integer
Var BooProp1 : Integer

BEGIN
    (* read the min / max value of the variable 'NumVar01' *)
    GetTagProperty('NumVar01', 200, TagMin)
    GetTagProperty('NumVar01', 201,  TagMax)

    (* read the tag property 'Num1' of the variable 'BooVar01' *)
    GetTagProperty('BooVar01', 500, BooProp1)
END

SetTagProperty

The new tag properties can be read or written with the two script functions GetTagProperty and SetTagProperty. The functions can also be used to describe the properties Min, Max, MinSPS, MaxSPS and the number of decimal places for numerical values.

For the parameters of the tag properties see function GetTagProperty.

Important

When setting a range property (Min, Max, MinExt, MaxExt, DecimalPlaces) of a numeric variable, the current variable value can be adjusted. Furthermore, when changing e.g. the maxvalue of arrays, all tags are adjusted to the new max value. If this should only happen for one element, the index must be specified.

Attention

If process variables are used exclusively in scripting via the dynamicfunctions GetValue (), SetValue ()GetTagProperty () and SetTagProperty () and NOWHERE else in the project, they will be recognized by the designer as not referenced, since access to these functions is dynamic works at runtime via the name and NOT via a fixed reference.

This can be seen when all references of the process variable are displayed, and these are then empty and thus the variable is not exported for the runtime.This leads to the return value -2 at runtime for the functions mentioned above.

Function definition: SetTagProperty(TagName: string, PropertyId: integer, Value: var undef) : integer

Parameter:
TagName	Name of the process variable
PropertyId	Id / Number of the property
Value	Value of the property
	boolean for logical properties
	real for logical properties
	string for text properties
	Only real variables, not instances, may be used
Return values:
0	if the function was carried out successfully
-1	invalid process variable
-2	invalid property

Example

PROGRAM

BEGIN
    (* set the min / max value of the variable 'NumVar01' *)
    SetTagProperty('NumVar01', 200, -1000)
    SetTagProperty('NumVar01', 201,  1000)

    (* set the tag property 'Num1' of the variable 'BooVar01' *)
    SetTagProperty('BooVar01', 500, 99)
END

GetValue

Function for querying variable values using the variable name, which can also be assembled dynamically.If the variable is NOT in the current requirements list, it is automatically transferred to the requirements list for the period of execution.

Array elements can be queried using the complete specification including the array index, e.g. ‘TestNumArr [3]’ asks the 4th Element of the ‘TestNumArr’ array.

Attention

If process variables are used exclusively in scripting via the dynamicfunctions GetValue (), SetValue ()GetTagProperty () and SetTagProperty () and NOWHERE else in the project, they will be recognized by the designer as not referenced, since access to these functions is dynamic works at runtime via the name and NOT via a fixed reference.

This can be seen when all references of the process variable are displayed, and these are then empty and thus the variable is not exported for the runtime.This leads to the return value -2 at runtime for the functions mentioned above.

Function definition: GetValue (TagName: string, Mode: integer, VarNameResult: undef) : integer

Parameter:
TagName	Name of the variable to be queried
	Numerical, logical process variable or text variable as string constant or variable
Mode	0 The function is processed asynchronously, the current value is returned
	1 The function is processed synchronously, ie with driver variables there is a wait until a fetsch-cycle has been processed
VarNameResult	Value of the variable to be queried
	Only real variables, not instances, may be used
Return values:
0	if the function was carried out successfully
-1	Parameter error
-2	Process variable not found

Example

PROGRAM

var mode : integer

BEGIN
    if GetValueNow then
    begin
        GetValueNow :=0
        mode := 0
        GetValue('VarTest', mode, WertVarTest)
    end
END

Important

The TagServer reads the value of the variable directly from the process.If the variable was previously used in the script, the value is normally not yet available in the process, unless, for example, a WriteToProcess () was carried out

Example

BEGIN
    (*-- The variable "myVar" in the process has the value 1 --*)

    (*-- in the script: --*)

    myVar:= 3
    GetValue(‚myVar‘, 0, myVarValue)

    (*-- -> myVarValue has the value 1 --*)


    myVar:=3
    WriteToProcess()
    GetValue(‚myVar‘, 0, myVarValue)

    (*-- -> myVarValue has the value 3 --*)
END

SetValue

Function for setting a variable value via the variable name, which can also be assembled dynamically.If the variable is NOT in the current requirements list, it is automatically transferred to the requirements list for the period of execution.

Array elements can be queried using the complete specification including the array index, e.g. ‘TestNumArr [3]’ asks the 4th Element of the ‘TestNumArr’ array.

Attention

If process variables are used exclusively in scripting via the dynamicfunctions GetValue (), SetValue ()GetTagProperty () and SetTagProperty () and NOWHERE else in the project, they will be recognized by the designer as not referenced, since access to these functions is dynamic works at runtime via the name and NOT via a fixed reference.

This can be seen when all references of the process variable are displayed, and these are then empty and thus the variable is not exported for the runtime.This leads to the return value -2 at runtime for the functions mentioned above.

Function definition: SetValue(TagName: string, Mode: integer, VarNameResult: undef) : integer

Parameter:
TagName	Name of the variable to be queried
	Numerical, logical process variable or text variable as string constant or variable
Mode	0 The function is processed asynchronously, the current value is returned
	1 The function is processed synchronously, ie with driver variables there is a wait until a fetch cycle has been processed
VarNameResult	Value of the variable to be queried
	Only real variables, not instances, may be used
Return values:
0	if the function was carried out successfully
-1	Parameter error
-2	Process variable not found

Example

PROGRAM

var mode : integer

BEGIN
    if SetValueNow then
    begin
        SetValueNow :=0
        mode := 0 (* ohne Verzögerung *)
        SetValue('VarTest', mode, VarWertNeu)
    end
END

Other functions (only SCADA)

Special

Funktion zum Auslösen von Sonderfunktionen aus dem Eventcode heraus. Es sind die Sonderfunktionen möglich welche auch auf Symbolen und Buttons möglich sind.

Attention

This command only works for registered clients, ie in a local script!This command will not work in a script that is executed when the system is started, since the web server is not yet accepting any client requests!

Function definition: Special(Picture, number : integer) : integer

Parameter:
Picture	Nummer des Bildes mit der die Funktion aufgerufen wird
Number	Number of the special functions
Return values
0	If function was carried out successfully

Example

PROGRAM

var BildNummer : integer

Function UserMgm(mode : integer) : integer

var BildNummer : integer
Begin
    BildNummer := Picture(0)
    if (mode = 1) then
    begin
        (* Benutzer anmelden *)
        Special(BildNummer, 203)
    end

    if (mode = 2) then
    begin
        (* Benutzer abmelden *)
        Special(BildNummer, 205)
    end
End

BEGIN
    UserMgm(1)
END

External function call / programme start (only SCADA)

WinExec

Function to run another Windows program from the event code.When using this function, it must be ensured that the program to be executed can actually be started by the operating system. It must either be in the current working directory or in one of the Windows search paths. In addition, the Windows resources must be sufficient when the program starts.

Attention

Since the command line parameters for the program call are separated with spaces, no path specifications with spaces are supported.

Attention

The program is executed in the user context of the PROCON-WEB service, which is usually the local system account. No programs with a user interface should therefore be called that require user interaction.

Function definition: WinExec(CommandLine: string) : integer

Parameter:
CommandLine	Command line for the program call including the start parameters
Return values:
0	if ok
< 0	if error
-1	Parameter not definied
-2	System resources insufficient to execute the command
-3	EXE file is in wrong format
-4	file not found
-5	path not found
-6	undefined error

Example

PROGRAM

function fktOpenFile(File: string) : integer

begin
    (* the program Notepad is used for editing       *)
    (* started with the desired file                 *)
    WinExec ('C:\Windows\System32\NOTEPAD.EXE ' + File)
end

BEGIN
    fktOpenFile('info.txt')
END

Other functions (only SCADA)

Delay

With this function, the script to be executed can be delayed by the transferred number of milliseconds. The script stops executing for the specified time and continues with the script when the time has elapsed.

Before the script is stopped, all process variables modified by the script are written to the tag server. Before the script continues, the current process tag management is read by the tag server. This means that the process image for the script can have changed while the script is stopped.

Since process communication normally only takes place at the beginning and end of a script, process variables can also be exchanged at a defined point in the script. The process communication can of course represent a performance overhead, for example when using the function within a loop.

Function definition: Delay(Milliseconds : integer) : integer

Parameter:
Milliseconds	Time in milliseconds by which the script is delayed
Return values:
0	if the function was carried out successfully

Example

PROGRAM

FUNCTION Nochmal: integer

var p : integer

begin
    for p:=21 downto 0 do
    begin
        while XY_Feld[p] > 0 do
            XY_Feld[p] := XY_Feld[p] - 1
        (* Values are now immediately written to the process *)
        Delay(0)
    end
end

BEGIN
    Nochmal()
END

LogEventString

Function for writing a string in the logbook

Function definition: LogEventString(var StrSrc: string) : integer

Parameter:
StrSrc	Name of the string (max. 255 characters)
Return values:
>= 0	if written
< 0	if not writtten

Example

PROGRAM

BEGIN
    LogEventString('Erster Eintrag in Logbuch')
    LogEventString('Zweiter Eintrag in Logbuch')
END

SetLanguage

Function for setting the current operating language.

Special feature: Setting the operating language leads to a new image structure. A picture event (picture formula) is ended and restarted after the command!

Important

This command only works for registered clients, i.e. in a local script!This command will Not work in a script that is executed at system start, since the web server does not yet accept any client requests!

Function definition: SetLanguage(Country : string) : integer

Parameter:
Country	Country code of the new operating language
	(z.B. 044 für England)
Return values:
0	if the function was successfully completed
-1	Parameter error
-2	Sprachkennung nicht vorhanden in Projekt

Example

PROGRAM

(* The identifier of the national language is in the "Country code" variable *)
(* to switch to                                                              *)

FUNCTION SetLang: INTEGER

BEGIN
    SetLanguage(Landeskennung)
END

BEGIN
    SetLang()
END

Random

Function for creating a random number.The random number generator is initialised with the “Randomize” function. If the random number generator is not initialised, the “Random” function always generates the same sequence of random numbers after the program has started

Function definition:** Random(Range : integer) : integer

Parameter:
Range	Range specification for the random number 0 <= Result < Range
Return values:
Random number	0 <= result range

Example

PROGRAM

function CheckCondition() :integer

var hilfsvar, i :integer

begin
    hilfsvar := Zufall_oben
    Zufall_ist := Random(hilfsvar)
    for i := 0 to 3 do
    begin
        if (Zufall_ist = Vorgabe[i]) then
        begin
            Alert(1,645)    (* Alert: Browse *)
            Alert(2,645)
        end
    end
end

(*------------------------------------------------------------*)
(* So that the same number combination does not always appear *)
(* the function Randomize must be called once                 *)
(*------------------------------------------------------------*)
function Init() :integer
begin
    Randomize()
End

BEGIN
    Init()
    CheckCondition()
END

Note

For example, if you want to generate a random number between 70 and 80, you have to generate a random number between 0 and 10 and add an offset of 70.

Randomize

Function to initialize the random number generator.If the random number generator is not initialized, the Random function always generates the same sequence of random numbers after the program has started.

Function definition: Randomize() : integer

Note

See also random; Only has to be started once after the project has started (e.g. during initialization).

ChangeProject

Function for changing the current project, the runtime is restarted with the new project.

Function definition: ChangeProject(ProjectName: string) : integer

Parameter:
ProjectName	Name of the project to be started
Return values:
0	if the function was carried out successfully
< 0	In case of error

Example

PROGRAM

BEGIN
    ChangeProject('MesseDemo')
END

GetLanguage

Function for inquiring about the current operating language.

Function definition: GetLanguage(var SprachIdentifikation, Kurzbezeichnung, Laenderkennung : string) : integer

Parameter:
Language identification	ID of the language, e.g., “de” for German, “en” for English as selected in the designer
Short name	Short description of the language as given in the designer
Country code	Country code of the current operating language
Return values:
0	if the function was carried out successfully
-1	Parameter error

Example

FUNCTION makro4005 : INTEGER

var Name,
    Shortcut,
    Country : string

BEGIN
    makro4005 := GetLanguage(Name, Shortcut, Country)
END

(*  The variables then have the following content, for example:
        Name:           de
            Shortcut:   D.
            Country:    049
*)

OpenBrowser

Function to open the transferred URL in a new browser tab or a new browser window. The reason for this is that certain pages such as Google cannot be displayed in iFrames - as is used by the WebBrowser control.

Important

This command only works for registered clients, i.e. in a local script!This command will Not work in a script that is executed at system start, since the web server does not yet accept any client requests!

Function definition: OpenBrowser(Url : string, tab : integer) : integer

Parameter:
URL	URL to be called
Tab	0 = new browser window 1 = new tab
Country code	Country code of the current operating language
Return values:
0	if the function was carried out successfully
-1	parameterisation error (tab <0 or tab> 1)

Example

PROGRAM

BEGIN
    OpenBrowser('http://www.google.de/', 1)
END

DIN 8743 funktions (only SCADA)

CalculateDIN8743

See also chapter machine times

Function definition CalculateDIN8743(int Aktion, string Auftrag, string AuftragID, string Unitname, real Start, real Ende, real Modus, real Gutteile, real Schlechtteile)

Parameter	Meaning
Action 0	start of calculation
1	termination of calculation
2	progress query of calculation
3	status query of calculation

The following parameters are only evaluated with action 0 (start of calculation):

Order: name of the order (user-defined text to identify the calculation)

OrderID: ID of the order (user-defined text to identify the calculation)

Unit name unique name of the unit to be calculated (e.g. ‘Plant structure. Plant.Linie1.Unit1’)

Start: start time of the evaluation in seconds since 1970

End: end time of the evaluation in seconds since 1970

Mode: DIN calculation mode0 = absolute time (end-start) as the basis for calculation1 = machine working time tW as the basis for calculation

The last two parameters can be used to overwrite the number of good or bad parts from the logger table.Values> = 0 overwrite or replace the values determined from the logger table.

Good parts: number of good parts within the calculation period

Bad parts: number of bad parts within the calculation period

Return values for action status query:	Meaning
-1	Error
0	OK or done
1	Calculation is running
2	Calculation canceled

Return values for action progress query:**	Meaning
-1	Error or calculation aborted
0 – 100	Progress information

Other return values:	Meaning
-2	unknown unit name
-3	wrong calculation time parameters start and end
-4	a calculation is currently being carried out
-5	nternal calculation error (wrong parameters in the unit definition, etc.)
-6	AlertService is blocked at the moment (e.g. online project update)

CalculateStatistic

See also chapter machine times

Function definition CalculateStatistic(int Aktion, string Auftrag, string AuftragID, string Länderkennung, real Start, real Ende)

Parameter	Meaning
Action 0	start of calculation
1	termination of calculation
2	progress query of calculation
3	status query of calculation

The following parameters are only evaluated with action 0 (start of calculation):

Order: name of the order (user-defined text to identify the calculation)

OrderID: ID of the order (user-defined text to identify the calculation)

Country code: udesired language of the alarm texts in the results table (e.g. en-EN)

Start: start time of the evaluation in seconds since 1970

End: end time of the evaluation in seconds since 1970

Return values for action status query:	Meaning
-1	Error
0	OK or done
1	Calculation is running
2	Calculation canceled

Return values for action progress query:**	Meaning
-1	Error or calculation aborted
0 – 100	Progress information

Other return values:	Meaning
-3	wrong calculation time parameters start and end
-4	a calculation is currently being carried out
-5	nternal calculation error (wrong parameters in the unit definition, etc.)
-6	AlertService is blocked at the moment (e.g. online project update)

StatisticClose

Not implemented anymore

Printer handling

Important

The script functions for printer handling are ALWAYS executed on the server, so they always refer to the printer on the server system.

GetPrinterCount

With this function the number of printers can be read out from the system.

Function definition: GetPrinterCount() : integer

Return values	Meaning
0	if the function was carried out successfully
-1	Printers cannot be read out

Example

PROGRAM

BEGIN
    DruckerListe := ''
    DruckerCount := GetPrinterCount()
    for i:= 0 to DruckerCount - 1 do
    begin
        GetPrinterName(i, printer)
        if (i = 0) then DruckerListe := printer
        else DruckerListe := DruckerListe + ';' + printer
    end

    GetDefaultPrinterByIndex(DruckerIndex);
    GetDefaultPrinterByName(SelectedDrucker)
END

GetPrinterName

Reads out the name of a printer, the index must be between 0 and GetPrinterCount () - 1.

Function definition: GetPrinterName(integer: index, name : var type string) : integer

Parameter	Meaning
index	Index of the printer (must be between 0 and GetPrinterCount () - 1)
name	Name of the printer
Return values:	Meaning
0	if the function was carried out successfully
-1	Printer was not found

Example

PROGRAM

BEGIN
    DruckerListe := ''
    DruckerCount := GetPrinterCount()
    for i:= 0 to DruckerCount - 1 do
    begin
        GetPrinterName(i, printer)
        if (i = 0) then DruckerListe := printer
        else DruckerListe := DruckerListe + ';' + printer
    end

    GetDefaultPrinterByIndex(DruckerIndex);
    GetDefaultPrinterByName(SelectedDrucker)
END

GetDefaultPrinterByIndex

Reads out the default printer

Function definition: GetDefaultPrinterByIndex(var integer: index) : integer

Parameter	Meaning
index	Index of the printer
Return values:	Meaning
0	if the function was carried out successfully
-1	Printer was not found

Example

PROGRAM

BEGIN
    DruckerListe := ''
    DruckerCount := GetPrinterCount()
    for i:= 0 to DruckerCount - 1 do
    begin
        GetPrinterName(i, printer)
        if (i = 0) then DruckerListe := printer
        else DruckerListe := DruckerListe + ';' + printer
    end

    GetDefaultPrinterByIndex(DruckerIndex);
    GetDefaultPrinterByName(SelectedDrucker)
END

GetDefaultPrinterByName

Reads out the default printer

Function definition: GetDefaultPrinterByName(var string: name) : integer

Parameter	Meaning
index	Index of the printer
Return values:	Meaning
0	if the function was carried out successfully
-1	Printer was not found

Example

PROGRAM

BEGIN
    DruckerListe := ''
    DruckerCount := GetPrinterCount()
    for i:= 0 to DruckerCount - 1 do
    begin
        GetPrinterName(i, printer)
        if (i = 0) then DruckerListe := printer
        else DruckerListe := DruckerListe + ';' + printer
    end

    GetDefaultPrinterByIndex(DruckerIndex);
    GetDefaultPrinterByName(SelectedDrucker)
END

SetDefaultPrinterByIndex

Changes the default printer

Function definition: SetDefaultPrinterByIndex(integer: index) : integer

Parameter	Meaning
index	Index of the printer (must be between 0 and GetPrinterCount () - 1)
Return values:	Meaning
0	if the function was carried out successfully
-1	Printer was not found

Example

PROGRAM

BEGIN
    SetDefaultPrinterByName(DruckerIndex)
END

SetDefaultPrinterByName

Changes the default printer

Funktionsdefinition: SetDefaultPrinterByName(string: name) : integer

Parameter	Meaning
index	Index of the printer (must be between 0 and GetPrinterCount () - 1)
Return values:	Meaning
0	if the function was carried out successfully
-1	Default printer could not be set

Example

PROGRAM

BEGIN
    SetDefaultPrinterByName(SelectedDrucker)
END

Structure functions

Copy structures

Structures are treated throughout scripting like C# reference. This means that when structures are copied, a reference is assigned, but not the values themselves. This can be enabled in the script configuration.

When writing to tag structures, copying must always be done via a script function. If this does not happen, a system alarm is triggered to indicate this.

CopyStruct

Copies all elements of the source structure and their substructure to the target structure. The length is not changed by default but can be adjusted via the parameter “overrideLength”.

Function definition: CopyStruct(target: struct, source: struct, [overrideLength]:boolean) : integer

Parameter	Meaning
target	Name of the target structure
source	Name of the source structure
overrideLength	Determines whether array length is preserved
Return values:	Meaning
0	if the function was carried out successfully
-1	if target and source structure have different types

GetStructValue

Function for querying structure values via the name of the structure instance, which can also be assembled dynamically. Subtrees can also be accessed if they are specified with a period. It is also possible to query on arrays as a whole or individual elements of them.

Function definition: GetStructValue(structName: string, mode: integer, structValue: struct)

Parameter	Meaning
structName	Name of the structure to be queried
mode 0	Function is processed asynchronously, the currently current value is returned
mode 1	Function is processed synchronously, i.e., driver variables are waited until a Fetsch cycle has been processed
structValue	Value of the structure to be queried
Return values:	Meaning
0	if the function was carried out successfully
-1	if target and source structure have different types
-2	if no variable is found due to the optimized process variable export

Example

(*Triangle
string Name
real[3]  Colors
Point   Anchor
Point[3] Vertices
ChildTriangle   First
ChildTriangle[3] All

ChildTriangle
string Name
real[3]  Colors
Point   Anchor
Point[3] Vertices

Point
integer X
integer Y
*)

    PROGRAM

    BEGIN
    GetStructValue(„Tri“, 0, localTriVar)
    GetStructValue(„TriArray[0]“, 0, localTriVar)
    GetStructValue(„TriArray“, 0, localTriVarAsArray)
    GetStructValue(„Tri.First.Point“, 0, localPointVar)
    END

SetStructValue

Function to write structure values via the name of the structure instance, which can also be assembled dynamically. Subtrees can also be accessed if they are specified with a period. Arrays as a whole or individual elements of them can also be queried. The length of the array cannot be changed.

Function definition: SetStructValue(structName: string, mode: integer, structResult: struct)

Parameter	Meaning
structName	Name of the structure to be queried
mode 0	Function is processed asynchronously, the currently current value is returned
mode 1	Function is processed synchronously, i.e., driver variables are waited until a Fetsch cycle has been processed
structResult	Value of the structures to be written to
Return values:	Meaning
0	if the function was carried out successfully
-1	if target and source structure have different types
-2	if no variable is found due to the optimized process variable export

Example

(*Triangle
string Name
real[3]  Colors
Point   Anchor
Point[3] Vertices
ChildTriangle   First
ChildTriangle[3] All

ChildTriangle
string Name
real[3]  Colors
Point   Anchor
Point[3] Vertices

Point
integer X
integer Y
*)

    PROGRAM

    BEGIN
    SetStructValue(„Tri“, 0, localTriVar)
    SetStructValue(„TriArray[0]“, 0, localTriVar)
    SetStructValue(„TriArray“, 0, localTriVarAsArray)
    SetStructValue(„Tri.First.Point“, 0, localPointVar)
    END

GetStructInstances

Function to ask for the nameof all instances of a structure, which can also be assembled dynamically. The length of the passed array is automatically adjusted.

Function definition:

GetStructInstances(structTypeName: string, instances: array of string): integer

Parameter	Meaning
structTypeName	Name of the structure to be queried
mode 0	Function is processed asynchronously, the currently current value is returned
mode 1	Function is processed synchronously, i.e., driver variables are waited until a Fetsch cycle has been processed
structValue	Value of the structure to be queried
Return values:	Meaning
0	if the function was carried out successfully
-1	if the structure could not be found

Dynamic structures

For scripts that are started from a client and not, for example, automatically when the Visu starts, dynamic structures can be accessed with “DynStruct.`<StructClassName>`”. This works for AOs with structure assignment and for images opened by an AO with structure. if a structure is used for which no matching instance can be determined at run time the structure is set to a new empty instance before the script is executed.For scripts that are started from a client and not, for example, automatically when the Visu starts, dynamic structures can be accessed with “DynStruct.`<StructClassName>`”. This works for AOs with structure assignment and for images opened by an AO with structure. if a structure is used for which no matching instance can be determined at run time the structure is set to a new empty instance before the script is executed.

Script-Debugger

General

The script component of the PROCON-WEB Designer has been expanded to include the functionality of a debugger. The debugger can debug individual scripts in a simulation session, or it is possible to connect to a local script server (attach) in order to debug its live process flow.The functions of the script debugger can be accessed via the script toolbar when the script to be debugged is opened in the designer:

The following functions are available for starting a debug session:

Toggle breakpoint (F9): This can be used to set or delete a breakpoint at the current code position (position in the script where the input cursor is positioned). If there is no breakpoint at this point, one is set; if a breakpoint already exists, it is deleted.

Breakpoints can be set or removed before a debug session as well as during a debug session.It should be noted, however, that starting a debug session without previously set breakpoints can result in the scripts being processed before a breakpoint is set and the breakpoint is therefore not reached.

Start simulation (F6): Starts a debug session within a script simulation process.

A simulation environment is started in the background that processes each script once. In this simulation there is no runtime connection to server components. All special script functions are treated as if their processing would return the result 1 (S_OK).

Attach ScriptServer (Ctrl-F6): Starts a debug session in which the debugger connects to the actually running script server in a local runtime environment.

With this function, the scripts currently running live in runtime can be debugged. In this scenario, some exceptions must be observed that can have a fundamental influence on the runtime system!

Important

With live coupling, all the tags modified in the debugger (process tags or local script tags) are written directly to the script server of the runtime system and can thus influence the process and the execution of the scripts!

Important

Long debugging sessions in a breakpoint can lead to timeouts within the runtime system in the case of a live connection, so that, for example, client scripts are not executed correctly at this time or server communications are aborted due to the timeouts and not restarted.

Important

Since the debugger directly intervenes in the process of the script server with live coupling, it can remain in a state after the end of a debug session that does not ensure that the scripts continue to run correctly. To be on the safe side, the ScriptServer should therefore be restarted after a ScriptServer debug session.

The following functions are available during a debug session:

Continue simulation (F6): If the session is in a breakpoint, processing can be continued with F6. This works both for simulation sessions and for live sessions against the script server. Here the function Continue Simulation (F6) and Continue ScriptServer (CTRL-F6) are identical.

Continue ScriptServer (CTRL-F6): See “Continue Simulation (F6).

Step In (F11): Only available if the debug session is in a breakpoint.Jumps to the next line of script. If this is a function call, a branch is made to this function, otherwise Step In behaves like Step Over (F10).

Step over (F10): Only available if the debug session is in a breakpoint. Jumps to the next line of script.

Step out (CTRL-F11): Only available if the debug session is in a breakpoint.Jumps from the current function to the one above. If the current line of code is in the main function (PROGRAM), Step Out behaves like Step Over (F10)

Toggle breakpoint (F9): Same functionality as before the start of a debug session (see above)

Stop (Shift-F6): Ends the debug session. If a simulation session was started, it is ended. If a live script server session has been started, an attempt is made to detach the debugger from the script server so that the script server continues to run normally. However, this cannot be 100% guaranteed in all situations (see above)

Breakpoints

Any number of breakpoints can be set in any script. These are displayed in a list in the lower area of the script editor of the designer.

Breakpoints are displayed as red circles in the editor and the line is highlighted in red.

Breakpoints can be activated / deactivated with F9 or with a mouse click in the script editor in which the red circles are displayed.

Watchlist

During a debug session, the variables used (process variables and local variables) of the script in which the debug session is currently located are displayed. The values of the variables can be changed accordingly for test purposes

Note

Variable values can only be displayed if the debug session is in a breakpoint.

Background informationen

Here is some background information that may help you better understand the sequence of debug sessions and the behavior of the debugger

• The PROCON-WEB script, the syntax of which is based on the PASCAL programming language, is converted by the PROCON-WEB Designer into C # .NET code and compiled into a .NET assembly when a project is exported. This Dll (GTI.ProjectSpecificSkripts.dll) is then loaded by the ScriptServer in the runtime and the code of this Dll is executed directly as .NET code.

• The debugger functionality that is now used is the same technology as a “normal” debugger on a Windows machine. When debugging, the currently executed C # .NET code is always “mapped” to the most suitable PROCON-WEB script program line. Since the PASCAL-like function-oriented code differs significantly from the object-oriented .NET C # code, in certain cases it can mean, that the line of code cannot be clearly identified.

• The use of normal debug technology in a debug session can cause the problems listed above, especially when attaching to a script server that is currently running. Therefore, live debugging is a very delicate matter, especially in a production runtime system, where you must reckon with restarting the runtime system after the debug session has ended.

• To determine which session triggers a debug call, a few participants can be defined in the script configuration for which a breakpoint is triggered during debugging.

The entry must be made in the ServerConfigs.xml in the runtime directory in the line

<special key ="DebugSessions" value ="localhost;ScriptServer"/>

Possible entries:

Attendees	Description
Localhost	The locoalhost client
ScriptServer	ScriptServer-Session for global tasks
ScriptServer-TaskName	ScriptServer session for a special task
Nondedicated	Not dedicated clients
	ATTENTION: this will trigger ALL non-dedicated clients the breakpoint
Participant name	The name of a taught client (not case sensitive)

Use .Net DLL in scripts (only SCADA)

General

CLR classes can now also be imported into PROCON-WEB scripts. An assembly written in a .NET language (eg C #) must be selected within the designer. After the assembly has been made known, any namespace of this assembly can be imported into a script. All supported classes can then be used in the script.

The method signature is decisive for the usability of a CLR method in a script. This must meet some restrictions. Only public and static methods are supported. In addition, the types of the parameters and the return type can only be script-compatible types.Generic methods, ref / out parameters, or overloaded methods are not supported.

Valid (C #) return types	Valid (C #) parameter types
bool	int
float	double
bool[]	int[]
float[]	double[]
Void	string[]

If structures are to be transferred to a CLR method, the dynamic keyword in C # can be used or the dll “GTI.ProjectSpecific.Skripts.Types.dll” generated by the designer can be used, which generates the corresponding interfaces for all tag structures.

program
import Testassembly
var x, y : integer
begin
y := 3
x := MyClass.MyStaticFuncWithInteger(y)
end

Project tree

There is the entry in the script area (.Net Dll) in the project tree.

Views

The display of the dlls (and pdb files) contained in the project is divided into two areas

The dlls are listed in a grid on the left. Creating, editing etc. works exactly as known from the area of file management. The methods with parameters and return values that can be called are displayed on the right. To do this, you have to select the desired DLL in the left area.

All files required for the script are now exported in the project directory to the “ScriptDllsDesigner” subfolder.

Method

The .NET Dll “GTI.SampleDotNet” is integrated into a project as an example. More information can be requested by our support via E-Mail <support@gti.de>

The DLL provides an exemplary order class (OrderHandling) which is intended to simulate a link to an external order management system.

It provides functions for generating an OrderID, an order name and a function that a suitable PROCON-WEB TagStruktur instance takes over and returns initialized in a type-safe manner.The example structure looks like this:

It was a folder structure defined with the elements:ID (Num)Desiredpiece (Num)Actualpiece (Num)Name (string)Comment (string)

And an instance called “OrderInst” was created for the structure

The project is then compiled and created, which creates the file: “GTI.ProjectSpecific.Skripts.Types.dll” in the project subfolder ScriptDllsDesigner.

This Dll is referenced in the exemplary .NET Dll (Visual Studio 2015, C # Class Library, .NET Framework 4):

Die Klasse OrderHandling bietet u.a. die folgende Schnittstelle (TagStrukturen werden immer als Referenz übergeben und können in der Methode modifiziert werden).

// type safe GetOrder Function
public static void GetOrder(GTI.ProjectSpecificSkripts.IOrder order)
{
order.ID = GetNewOrderId();
order.Name = GetProduct();
order.SollStueck = GetStueckzahl();
order.Comment = "Generated by GTI.SampleDotNet.dll C# Code";
}

This Dll is now registered in the Designer under .NET Dlls:

A transferred order is thus initialized and returned.The associated Pascal script with which the OrderInst instance is initialized looks like this:

PROGRAM
import GTI.SampleDotNet (\* .NET Namespace of the used class \*)
BEGIN
(\* OrderHandling is the name of the class
InitOrder() is the public static method of the class
OrderInst is the Tag-Structur-Instanz \*)
OrderHandling.InitOrder( OrderInst )
END

The script is triggered in the project via a button and initializes the job.