External In/Output Functions

Name

Purpose

Argument

Return value

Example

callEbsScriptServer

Call of a DLL defined by the user in the scope of the ATL interface, normally to open a dialog for entering the parameters.

1: STRING:
DLL-Name.Methode

2: any type:
1. Argument

3: any type:
2. Argument

4: Procedure
Callback procedure called by the DLL

BOOLEAN: true: o.k.
false: Error

callEbsScriptServer( "CoalSelection.Input", strCoalNameField, r2, procInit );

callUserDll

Simple call of the User DLL without additional arguments

1: INTEGER: Program ID within the User DLL

INTEGER,
as set by the user DLL

callUserDll(2);

callUserDllArgs

Call of the user DLL with three additional arguments

1:INTEGER: Program ID within the User DLL

2:INTEGER

3:REAL

4:STRING

INTEGER,
as set by the user DLL

callUserDll(1, 3, 7.5, "d:\\temp\\out.txt"); 

eposReadAverage FromArchive

like "ReadAverageFrom Archive", but using dynamic arrays

1: REAL: Start time for the averaging

2: REAL: End time for the averaging

3: array of PointFilter:

4: BOOLEAN: see "ReadAverageFromArchive"
 

INTEGER:

eposReadAverage FromArchiveForOneId

like "ReadAverageFrom ArchiveForOneId", but using dynamic arrays

1: INTEGER:
ID of the archive

2: REAL: Start time for the averaging

3: REAL: End time for the averaging

4: array of PointFilter:

5: BOOLEAN:  see "ReadAverageFromArchive"
 

INTEGER:

eposReadAverage Trend

like "ReadAverageTrend", but using dynamic arrays

1: STRING
Name of the data point

2: REAL: Start time for the whole trend

3: REAL: End time for the whole trend

4: REAL: Interval for the averaging (time step)

5: array of PointFilter:

6: array of ValueAtTime
 

INTEGER:

eposReadTrend FromArchive

like "ReadTrendFrom Archive", but using dynamic arrays

1: STRING
Name of the data point

2: REAL: Start time for the whole trend

3: REAL: End time for the whole trend

4: array of ValueAtTime

INTEGER:

getEposArchiveId

Retrieves the EposArchive Id that is configured for the considered data point

1:EBSCLASS: Ebsilon object under consideration

INTEGER: EposArchive Id

id:=getEposArchiveId (TestDP_S1.MEASM);

getSRxInfo

Retrieves the configuration data that are stored in Ebsilon for the specified point (SRx-Tag, SRx-Archive, read and write flag)

1:EBSCLASS: Ebsilon object (data point) under consideration

2:BOOLEAN:
true: data point is configured for reading
false: data point is not configured for reading

3:BOOLEAN:
true: data point is configured for writing
false: data point is not configured for writing

4:STRING: SRx tag for the data point

5:strArchives: SRx archives  

BOOLEAN:
true: o.k.
false: error

ePoint:=Test_DP009.RESULT;

bOk:=getSRxInfo (ePoint, bRead, bWrite, strTag, strArchives);

playSound

Playing a .wave file e.g. for announcing the instructions

1:STRING:
Path of the sound file or name of the sound system

2:BOOLEAN:
true: synchronous (execution of EbsScript is continued only after the playing has ended)
false (default setting, EbsScript is continued during the playing)

3:BOOLEAN:
true: Playing is repeated permanently (till the next playSound call with a blank path)
false (default setting): play once

4:BOOLEAN:
true: 1. argument is always interpreted as file name
false (default setting): 1. argument can be a file or a system sound

BOOLEAN:
true: all OK
false: error

playSound ("C:\\Temp\\Hallo.wav");

readAverageFrom Archive

With this function, a data set determined over a period of time can be loaded from the EposArchive.

While averaging, it is also possible to use filters. For each filter, the name of the point, the lower limit, the upper limit, the maximum relative deviation from the previous point of time and a filter ID are to be specified. Through the Filter-ID the AND- or ORB-connections can be realized: all filters with the same ID are connected with OR, filters with different ID are connected with AND.

In the example, an hourly mean value is modelled for the generator power BAA20CE003A.MEASM and the calculation status @model.iStatus. Only those data sets are taken for the averaging, in which the calculation status is <= 6 and the generator power is higher than 90 MW and the generator power has not changed by more than 3% in the last 5 minutes.

1: REAL: Start time for the averaging

2: REAL: End time of the averaging

3: INTEGER: Number of filter criteria

4: STRING: Field with the names of the filter values

5: REAL: Field with the permissible lower limits

6: REAL: Field with the permissible upper limits

7: REAL: Field with the maximum permissible deviations from the previous data set

8: INTEGER: Field with the Filter-IDs (see left)

9: BOOLEAN:
true=before reading, all measurement points are set to "empty". If measurement points are missing in the archive, they will remain empty.
false=meaurement points are not set to "empty". If measurement points are missing in the archive, they will have their previous values.

INTEGER: Number of the data sets taken for averaging

var

    rStartTime:real;

    rStopTime:real;

    nFilterSize:integer;

    arstrFilterPointNameArray:array[0..3] of string;

    arrFilterLowLimitArray:array[0..3] of real;

    arrFilterHighLimitArray:array[0..3] of real;

    arrFilterDeviationArray:array[0..3] of real;

    arnFilterIdArray:array[0..3] of integer;

    nRet:integer;

begin

    rStartTime:=convertTime ("25.04.2003 08:00");

    rStopTime:=convertTime ("25.04.2003 09:00");

    nFilterSize:=2;

    arstrFilterPointNameArray[0]:= "@model.iStatus";

    arrFilterLowLimitArray[0]:=0;

    arrFilterHighLimitArray[0]:=6;

    arrFilterDeviationArray[0]:=-1;

    arnFilterIdArray[0]:=1;

    arstrFilterPointNameArray[1]:=

                                "BAA20CE003A.MEASM";

    arrFilterLowLimitArray[1]:=90000;

    arrFilterHighLimitArray[1]:=-1;

    arrFilterDeviationArray[1]:=0.03;

    arnFilterIdArray[1]:=2;

    nRet:=readAverageFromArchive (rStartTime,

                 rStopTime, nFilterSize,

                 arstrFilterPointNameArray,

                 arrFilterLowLimitArray,

                 arrFilterHighLimitArray,

                 arrFilterDeviationArray,

                 arnFilterIdArray );

    print ("readAverageFromArchive returns ",nRet,"\n");

    print ("BAA20CE003A.MEASM = ",

             BAA20CE003A.MEASM,

           " @model.iStatus = ",@model.iStatus,"\n");

end.

readAverageFrom ArchiveForOneId

Like readAverageFromArchive, while archiving several time values, only the data from one time value are read.

1: INTEGER
ID of the archive

2-10 correspond to the arguments 1-9 of readAverageFromArchive

INTEGER: Number of data sets take for the averaging

nRet:=readAverageFromArchiveForOneId (9999,  rStartTime, rStopTime, nFilterSize,                 arstrFilterPointNameArray,                 arrFilterLowLimitArray,                 arrFilterHighLimitArray,                 arrFilterDeviationArray, arnFilterIdArray );

readAverageTrend

This function retrieves the filtered and time-determined values determined within specified time period for a data point. The interval for the averaging must be specified. The filter criteria are specified as for the function readAverageFromArchive. While averaging, points not matching the criteria are ignored. The time stamp (respectively the mean of the interval) and the values are entered in arrays, which must be created before in EbsScript.

Example: determination of the hourly mean values of the measurement point PAB12CT001 on 15.11.2003 between 8:00 and 16:00 o'clock, whereby only those values are to be included in the averaging, for which the calculation was successful (@model.iStatus < 7) and the plant was in operation (BAA20CE003A > 90000) and stationary (BAA20CE003A not more than 3% variation to the previous data set) .

1: STRING
Name of the data point

2: REAL: Start time for the whole trend

3: REAL: End time for the whole trend

4: REAL: Interval for the averaging (time step)

5: INTEGER: Number of filter criteria

6: STRING: Field with the names of filter quantities

7: REAL: Field with the permissible lower limits

8: REAL: Field with the permissible upper limits

9: REAL: Field with the maximum permissible deviations to the previous data set.

10: INTEGER: Field with the Filter IDs (see above)

11: INTEGER: Size of the fields provided for the results

12: REAL (Result): Field with the time for the trend points

13: REAL (Result): Field with the values for the results

INTEGER: Number of trend points found. When the number exceeds the size of the result array, the remaining points are discarded.

var
strPointName:string;
rStartTime,rStopTime,rTimeStep:real;
nFilterSize:integer;
arstrFilterPointNameArray:array[0..3] of string;
arrFilterLowLimitArray:array[0..3] of real;
arrFilterHighLimitArray:array[0..3] of real;
arrFilterDeviationArray:array[0..3] of real;
arnFilterIdArray:array[0..3] of integer;
nArraySize:integer;
arrTime:array[1..100] of real;
arrValue:array[1..100] of real;
i,nRet,nCount:integer;
begin
strPointName:="PAB12CT001.MEASM";
rStartTime:=convertTime ("15.11.2003 08:00");
rStopTime:=convertTime ("15.11.2003 16:00");
rTimeStep:=1.0/24.0; // 1 Hour
nFilterSize:=2;
arstrFilterPointNameArray[0]:= "@model.iStatus";
arrFilterLowLimitArray[0]:=0;
arrFilterHighLimitArray[0]:=6;
arrFilterDeviationArray[0]:=-1;
arnFilterIdArray[0]:=1;
arstrFilterPointNameArray[1]:=
                "BAA20CE003A.MEASM";
arrFilterLowLimitArray[1]:=90000;
arrFilterHighLimitArray[1]:=-1;
arrFilterDeviationArray[1]:=0.03;
arnFilterIdArray[1]:=2;
nArraySize:=100;
nRet:=readAverageTrend (strPointName,
  rStartTime, rStopTime, rTimeStep, nFilterSize,
  arstrFilterPointNameArray,
  arrFilterLowLimitArray,   
  arrFilterHighLimitArray, arrFilterDeviationArray,
  arnFilterIdArray, nArraySize, arrTime,
  arrValue);
print ("nRet = ",nRet,"\n");
nCount:=min(nRet, nArraySize);
for i:=1 to nCount do
begin
    print (i," time ",arrTime[i]," value ",
            arrValue[i],"\n");
end;
end.

readDatasetFromSRx

Loads a complete dataset from the SRx data server for a specified time into the model

1: REAL : time stamp

2: STRING: SRxArchive

3: STRING: SRxHost

4: STRING: SRxPort

BOOLEAN:
true: o.k.
false: error

rTime:=convertTime ("26.01.2006 10:15:00");
readDatasetFromSRx (rTime, "V", "localhost", "8001");

readFromExcelFile

This function enables the direct reading of the specified cells from an Excel file.

1: STRING: Path of the Excel file

2: INTEGER: Number of the sheet of the Excel file to be read

3: STRING: Range of the Excel file to be read

4: STRING: Field for the read data

5: INTEGER: Size of the field for the read data

BOOLEAN:
true: all OK
false: Error

bOk:=readFromExcelFile( strFullExcelPath, 1, "A4:J26", arstrResults, iSize);

readFromExcelFileNew

This function enables the direct reading of the specified cells from an Excel file using dynamic arrays.

1: STRING: Path of the Excel file

2: INTEGER: Number of the sheet of the Excel file to be read

3: STRING: Range of the Excel file to be read

4: STRING: dyn. Field for the read data

5: INTEGER: Size of the field for the read data

BOOLEAN:
true: all OK
false: Error

var
  ar:array of string;
begin
  if (readFromExcelFileNew("D:\\temp\\test.xls", 1,
     "B2:C3", ar)) then
  begin
    println ("ar ",length(ar)," ",ar[0]);
  end;
end;

readInpFile

Reads a file with measured values. This can be a text file or an Excel file. In case of an Excel file, the formatting instructions are necessary in the first row.

1: STRING: Path name of the input file

2: BOOLEAN:
true=before reading, all measurement points are set to "empty". If measurement points are missing in the archive, they will remain empty.
false=meaurement points are not set to "empty". If measurement points are missing in the archive, they will have their previous values.

If no name is entered, a dialog box appears for selecting a file.

BOOLEAN:
true: OK
false: Error

readInpFile ("D:\\temp\\Block750.inp”);

readKeyFromSRx

enables a direct access to the data saved in SRx, without having to create and configuring the corresponding objects in the EBSILON-model.

1: STRING: SRxKeyName

2: REAL: Time

3: var real: Value

4: STRING: Unit
(Standard = "-")

5: STRING: SRxArchive (Standard = "")

6: STRING: SRxHost (Standard = "")

7: STRING: SRxPort (Standard = "")

BOOLEAN:
true: OK
false: Error

readKeyFromSRx("TestKey", 123, returnvalue, "-", "", "", "" );

readLineFromFile

This EbsScript function reads a row from a text file.

The function is implemented in such a way that upon every read access, the file is reopened, the row is searched and the file is then closed again.

In the example, the first row of the file test.txt is read and displayed.

1: STRING: Path name of the file to be read.

2: STRING(Result): read text line

3: INTEGER: Number of the line to be read

4: encoding:textEncodingEnum = textEncodingASCII: How to encode the characters (ASCII, UTF8, UTF16 (LE))

BOOLEAN:
true: OK
false: Error

var
b:boolean;
s:string;
begin
b:=readLineFromFile( "c:\\temp\\test.txt", s, 1 );
print (b," ",s,"\n");
end;

1: STRING: Path name of the file to be read.

2: ARRAR OF STRING(Result): read text lines

3: INTEGER: Number of the first line to be read

4: INTEGER: Number of the last line to be read (-1: until the end)

5: encoding:textEncodingEnum = textEncodingASCII: How to encode the characters (ASCII, UTF8, UTF16 (LE))

BOOLEAN:
true: OK
false: Error

readPointFromSRx

Retrieves the value of a single data point for a specified time stamp from SRx.

1: EBSCLASS: object to be read

2: REAL: time stamp

3: STRING: SRxArchive

4: STRING: SRxHost

5: STRING: SRxPort

REAL:
returned value of data point

rTime:=convertTime ("26.01.2006 11:15:00");
rVal:=readPointFromSRx(TestDP_S1.MEASM, rTime, "V", "localhost", "8001");

readTrendFrom Archive

This function allows to read a trend for a data point from EposArchive. Contrary to readAverageTrend, there is no averaging or filtering.

1: STRING
Name of the data point

2: REAL: start time for the total trend

3: REAL: end time for the total trend

4: INTEGER: size of the supplied arrays for the results

5: REAL (result): array with the times for the trend points

6: REAL (result): array with the values for the trend points

INTEGER: number of found trend points. If this number increases the size of the specified array, the remaining points are not considered

nRet:=readTrendFromArchive (strPointName,
rStartTime, rStopTime, nArraySize, arrTime,
arrValue);

readUserExcel

Reads component specification values from the specified Excel file. The layout of the file must be defined according to the rules of the User Excel Interface.

1: STRING: Path name of the input file

BOOLEAN:
true: OK
false: Error

readUserExcel ("D:\\temp\\Block750_Data.xls”);

readUserExcel Formatted

Like readUserExcel, but with the specification of a formatting string directly to the User Excel Interface. The Excel file then no longer needs to contain any formatting specifications. The syntax of the formatting string corresponds to the formatting line. In addition, the keyword "EbsClear" is also available, which deletes all measured values before reading.

1: STRING: Path name of the input file

2: STRING: Format string with the keywords EbsNames, EbsProfiles, EbsUnits (optional), EbsClear (optional). The sequence must be maintained.

BOOLEAN:
true: OK
false: Error

readUserExcelFormatted ("D:\\temp\\Block750_Data.xls”, "EbsNames Col A EbsProfiles Col B to F EbsUnits Col G");

removeSRxInfo

deletes the SRx info that are stored at the Ebsilon objects. It is possible to select the entries to be removed either by their Ebsilon names or by their SRx tag.

1: ebsclass: Ebsilon objects from which the SRx info shall be removed. If this argument is an empty ebsclass variable, all SRx info are deleted, as long as this is not prohibited by the arguments 2 and 3.

2: STRING: SRx tag for the object from which the SRx info shall be deleted. If this arguments is an empty string, all SRx info are deleted, as long as this is not prohibited by the arguments 1 and 3.

3: STRING: name (characteristic letter) of the SRx archive which shall be considered by the removal. Only those SRx info are deleted that consider the specified archive.

INTEGER:

begin

    if (removeSRxInfo(Measuring_point, "", "5" )) then  begin

        println ("removeSRxInfo successful");

    end;
end.

or:

var e:ebsobject;
begin

    if (removeSRxInfo(e, "TagM2", "5" )) then   begin

        println ("removeSRxInfo successful");

    end;
end.

setArchive

This function allows to switch between different EposArchive servers. After specify server name and port with this function , all subsequent requests are sent to this server (until the setting is changed by the next calling of setArchive)

1:STRING: name of the computer, where the EposArchive to be used is running

2:STRING: service name (port) of the EposArchive to be used

-

setEposArchive ("Einhausen", "EposArchive");

setSRxInfo

This function modifies the configuration data that are stored in Ebsilon for the specified point (SRx-Tag, SRx-Archive, read and write flag)

1:EBSCLASS: Ebsilon object (data point) under consideration

2:BOOLEAN:
true: data point shall be configured for reading
false: data point shall not be configured for reading

3:BOOLEAN:
true: data point shall be configured for writing
false: data point shall not be configured for writing

4:STRING: SRx tag for the data point

5:strArchives: SRx archives to be used

6:BOOLEAN:
true: data set is not checked for duplicate tags
false: data set is checked for duplicate tags

BOOLEAN:
true: OK
false: Error

bOk:=setSRxInfo (ePoint, bRead, bWrite, strTag, strArchives,bNoCheckForDuplicateTags);

shellExecute

Executing an external program

(The optional parameters are forwarded only to the Windows function ::ShellExecuteEx. For details, please see the Microsoft documentation)

1: STRING: Path name of the program

2: STRING: Parameter line (default value:"")

3: BOOLEAN: Flag, whether the execution is to be done synchronously (default value: false)

4: STRING: Working directory for program execution (default value:"", i.e. the current directory)

5: INTEGER: Display flag nShow  (default value:10)

6: STRING: Operation lpVerb (default value: "")

BOOLEAN:
true: OK.
false: Error

shellExecute("notepad");

writeDatasetToSRx

Transfers a complete dataset to the SRx data server with the specified time stamp.

1: REAL: time stamp

2: STRING: SRxArchive

3: STRING: SRxHost

4: STRING: SRxPort

BOOLEAN:
true: OK.
false: Error

rTime:=convertTime ("26.01.2006 10:15:00");
writeDatasetToSRx (rTime, "V", "localhost", "8001");

writeKeyToSRx

enables a direct access to the data saved in SRx, without having to create and configuring the corresponding objects in the EBSILON-model.

1: STRING: SRxKeyName

2:REAL: Time

3:REAL: Value

4:STRING: Unit
(Standard = "-")

5:STRING: SRxArchive
(Standard = "")

6:STRING: SRxHost
(Standard = "")

7:STRING: SRxPort
(Standard = "")

BOOLEAN:
true: write successful
false: write failed

writeKeyToSRx("TestKey", 123, 512, "-", "", "", "");

writePointToSRx

Writes a single value to a specified time stamp in the SRx data server.

1: EBSCLASS: object to be written

2: REAL: time stamp

3: REAL: value

4: STRING: SRxArchive

5: STRING: SRxHost

6: STRING: SRxPort

BOOLEAN:
true: OK.
false: Error

rTime:=convertTime ("26.01.2006 11:15:00");
rVal:=writePointToSRx(TestDP_S1.MEASM, rTime, 50.8, "V", "localhost", "8001");

writeToArchive

This function writes a record in the EposArchive.

1: INTEGER: Id of the archive, in which the record is to be written

2: REAL: point of time

BOOLEAN:
true: OK
false: error

bOk:=writeToExcelFile( strFullExcelPath, 1, "A4:J26", arstrValues, iSize);

writeToExcelFile

This function is used to write to the specified cells of an Excel file.

1: STRING: path of the Excel file

2: INTEGER: number of the sheet within the Excel file

3: STRING: range of the Excel sheet

4: STRING: array with the data to be transferred

5: INTEGER: size of the array with the data

BOOLEAN:
true: OK.
false: Error

bOk:=writeToExcelFile( strFullExcelPath, 1, "A4:J26", arstrValues, iSize);

writeToExcelFileNew

This function is used to write to the specified cells of an Excel file using dynamic arrays.

1: STRING: path of the Excel file

2: INTEGER: number of the sheet within the Excel file

3: STRING: range of the Excel sheet

4: STRING-ARRAY: array with the data to be transferred

BOOLEAN:
true: OK.
false: Error

var
  ar:array of string;
  i:integer;
begin
  setLength (ar, 100);
  for i:=0 to 99 do
  begin
    ar[i]:=printToString ("Test",i);
  end;
  if (writeToExcelFileNew("D:\\temp\\test.xls", 1,
      "D11:G35", ar)) then
  begin
    println ("write successfully");
  end;
end;

writeToFile

Enables the output of texts in a file, alternatively in a new file or in an already existing file.

1: STRING: Path name of the file to be written

2: STRING: Text to be entered

3: BOOLEAN:
true: Text is appended at the end, if the file already exists
false: File written from the beginning

4: encoding:textEncodingEnum = textEncodingASCII: How to encode the characters (ASCII, UTF8, UTF16 (LE))

BOOLEAN:
true: OK
false: Error

writeToFile("c:\\temp\\Result.log","Calculation successful",true);

writeUserExcel

Writes the specification and the result values in an Excel file according to a template file.

1: STRING: Path name of the Excel template file, which defines the layout to be used.

2: STRING: Path name of the Excel file, in which the report is to be written

BOOLEAN:
true: OK
false: Error

writeUserExcel ("D:\\temp\\Block750.inp”, "EbsNames Col A EbsProfiles Col B to F EbsUnits Col G");

writeUserExcel Formatted

Like writeUserExcel, but with the specification of a formatting string directly to the User Excel Interface. The Excel file then no longer needs to contain any formatting specifications. The syntax of the formatting string corresponds to the formatting line.

1: STRING: Path name of the Excel file, in which the report is to be written

2: STRING: Format string with the key words EbsNames, EbsProfiles, EbsUnits (optional). The sequence must be maintained.

BOOLEAN:
true: OK
false: Error

writeValFile

Writes the validation report in the specified file. This is always a text file, regardless of the extension.

1: STRING: Path name of the text file to be created

BOOLEAN:
true: OK
false: Error

writeValFile ("D:\\temp\\Block750.val”);