XTC Data Interface © TARCUS GmbH |
PROCONTROL P Process Operator Station POS30 |
Version: 5.3 As per July 2004 | |
ABB Utility Automation GmbH | TARCUS GmbH |
Introduction |
System Architecture |
Installation and licensing | Functions |
Creating a client application |
Testing the interface |
Error messages |
Info messages when reading changed values |
Prerequisites for the use of this interface are basic knowledge of the PROCONTROL P control system and the POS30 process operator station.
The XTC data interface supplements the POS30 functions, OMS (Operation and Monitoring Services) and IMS (Information Management Services), by providing the possibility to easily access all of the current and historical information available in the POS30 database by using a TCP/IP connection. Furthermore, XTC enables the transfer of information from other computer systems, using TCP/IP, to the POS30 station.
Process operations and operator interventions in the PROCONTROL system, which are both supported by the OMS functions of the POS30 station, cannot be performed via XTC.
New functions and improvements in version 5.3:
New functions and improvements in version 5.2:
Improvements in version 5.1:
New functions and improvements in version 5.0:
New functions and improvements in version 4.9:
New functions and improvements in version 4.8:
New functions and improvements of version 4.7:
New functions and improvements of version 4.6:
New functions and improvements of version 4.5 (July 2000):
New functions and improvements of version 4.5:
New functions and improvements of version 4.4:
New functions and improvements of version 4.3:
New functions and improvements of version 4.2:
New functions and improvements of version 4.1:
New functions of version 4.0:
In principle, the XTC can also be operated in parallel with the other POS30 functions. However, this mode of operation is not to be recommended if maximum system availability at an unrestricted processing speed is required.
Since the XTC server daemon "XTD" is a "normal daemon" under Digital UNIX, theoretically any number of client applications may log in and practically use this data interface at the same time. Within the XTC, however, all of the job instructions are processed one after the other, in the same order as they are coming in. This increases (as in any multi-user system) the reaction time of the system, depending on how many clients are accessing the interface at the time.
When the XTC function "Read changed values" (Stream functionality) is used, however, multi-client operation is not recommended. In this case it is better that only one client application requests changed values from the POS30 XTC server in order to ensure that all of the changed values of this client are being read.
With the use of the TCP/IP transmission protocol, XTC is suitable for multi-purpose operation, i.e. it can virtually be used from any computer system. The only prerequisite for this type of operation is that a socket connection for TCP/IP can be set up.
To provide for more clarity as to the contents of the data exchange, the communication between client and XTC daemon uses the ASCII format. Only readable strings are being exchanged. This also provides for platform-independent compatibility of the data contents.
A typical XTC application operates in the following order:
In order to simplify the use of XTC on PCs running MS Windows even more, an OLE/ActiveX Automation is available in the form of a Dynamic Link Library (DLL). This library includes the following functions:
OPEN | Establishes a Windows socket connection using TCP/IP |
EXECUTE | Excecutes a data transfer (reading or writing) |
CLOSE | Closes (terminates) the connection again |
This component allows to easily integrate XTC into any OLE/ActiveX enabled applications using VBA (Excel), Visual Basic, Visual C++, etc.
This operating mode allows the user to access all the relevant information in the POS30 database. Current and historical data of any signals can be sampled once, cyclically, or intermittently.
The following functions are available:
The POS30 XTC can also be used as a multi-purpose coupling to PROCONTROL which can be used for "listening-in" on (monitor) all the changed values. In this case, all of the signals available in the POS30 are monitored for changes, processed (analog/counter: physical values; step number: number 0-99: binary/checkback signals: 0 or 1), and are sent to the client application via a buffer. The commands listed in the following are available for handling this functionality. Details of the implementation are described under Creating a client application.
Often users would like to make counter readings or analog and binary information from outside the PROCONTROL system available via the XTC as well. Therefore, a write function for writing values into the POS30 database has been provided. For this purpose, the respective analog or binary measuring circuits need to be defined with the help of the engineering tools of the POS30 (MKS or EDS). Those measuring circuits are not assigned a PROCONTROL source address, of course, but the writing client application references this information with the associated signal tag name.
The following functions are available:
Like the
"real" PROCONTROL measuring values, these values will be
stored in the POS30 database as well. Therefore, it is also possible to
apply all of the POS30 functions (representation in the form of standard
and mimic displays, trend displays, calculations, archiving, etc.).
The POS30 XTC can be used for coupling an external / third-party control system to the POS30. Each external system is connected to the POS30 via a PC operating as a client of the XTC data interface. The process operations and interventions supported by the OMS functions of the POS30 can then be performed, from the POS30 station, to control external systems.
The configured signal address of the operating signal indicates whether an operation instruction from the POS30 is to be sent to an external system or to the PROCONTROL system:
System: | 1 .. 3 |
Station: | 0 |
Module: | any value within the permissible range |
Register: | any value within the permissible range |
The PCs determine whether an operating instruction is intended for a external system that is connected via a certain PC client.
For every operating instruction supported by the POS30, an ASCII operating instruction text is defined.
The operating instructions from the POS30 to the external system are sent as a "knapsack" along with every return value of any XTC command and can be evaluated by the requesting PC client.
The new XTC command "PollData" is defined for sampling operating
instructions independent of XTC commands.
If the ICMP protocol, which is necessary for PING, is active on the client it is supervised via PING by the XTC server. If the client is not reachable via PING twice in a row the connection will be aborted. Waiting time in PING is about 10 seconds.
If the ICMP protocol is not active on the client or the server specific configuration file XTD_NOPING is available on the XTC server, the client is not supervised via PING.
Using the new command "WatchSignal <signal> 1" the user can determine that a signal will be set to status "disturbed" if the current connection is closed or aborted.
This commitment can be turned off using "WatchSignal <signal> 0".
A signal can be supervised only if the client has sent the command
"WatchMe <clientname>" before.
<clientname> can be any string.
Up to 5 clients can be supervised. At the end of the connection only those signals are set
to status "disturbed" which have previously been set by this client using
"WatchSignal <signal> 1".
The following information on the POS30 server can be called up:
For creating a client application, e.g. in Visual Basic or C++, the ActiveX (OLE) Automation "channel" is available as a DLL (Dynamic Link Library). This DLL must be referenced in the application. It allows the user to create a "channel" object providing methods (functions) which are suitable for managing the connection to the POS30 XTC server and for requesting data.
The following methods are available:
open: | |
---|---|
Description: | Establishes connection to the POS30 XTC server |
Parameters: | Name of the POS30 XTC server Port number (2000; fixed setting on the POS30 XTC server) |
Return: | "OK" or plaintext error message |
exec: | |
---|---|
Description: | Sends command to the POS30 XTC server |
Parameters: | Command in the form of an ASCII string (cf. description of commands below) |
Return: | Response from the POS30 XTC server in the
form of an ASCII string (value list or "OK" or plaintext error message) |
VB example:
' Create a channel object Set Channel = CreateObject("Channel.Channel") ' Establish connection to the POS30 XTC server Result = Channel.Open("<POS30 XTC server name>", 2000) ' Request tag list (using filter criterion "*") Result = Channel.Exec("GetSigList " & "*") |
close: | |
---|---|
Description: | Terminates (closes) the connection to the POS30 XTC server. |
Parameters: | - None - |
Return: | "OK" or plaintext error message |
VB example:
' Terminate connection to the POS30 XTC server Result = Channel.Close |
Command:
A command is an ASCII string and consists of a command name (such as "GetSigList") and possibly one or several parameters seperated by space characters. If a parameter includes a space character, it needs to be enclosed in single quotation marks or curly brackets.
Examples:
GetSigList 01* GetSigList "01 HFE*" GetSigList {01 HFE*} |
Return:
The return string is an ASCII string and delivers the values in the form of a list. The basic list structure is as follows:
Example:
";3;value1;value2;value3;" |
The first character in the string indicates the character that is used to separate the individual list elements at this level. As a separator, any character may be used which is not being used in the values themselves (semicolon ";" in the example above). The first list element is a number indicating how many list elements will follow. This number is again followed by the separator, then by the individual data elements, each one separated by the separator.
An element of the list may also be a list. This second list is given another separator. The example shows a nesting list where the separator at level 1 is a semicolon ";", but a comma "," in the lower-level list:
Example:
";3;,2,value11,value12,;,2,value21,value22,;,2,value31,value32,;" |
Special cases:
Request command: | GetSegment | |
Parameters: | - none - | |
Return value: | ;3;segment tag;segment description;segment number; |
This function doesn't need any parameter. Informations concerning the segment are provided whose standard configuration data are available on the current server.
If no segment is available on the current server ";0;" is provided as return value.
Example:
Request segment data: GetSegment |
Request command: | GetViewsOfSegment | |
Parameter: | segment tag (optional) | |
Return value: | ;n;view1;view2;...;view n; (in the order of the views's position in the segment) | |
view: | ,5,position,tagname,description,status,view number, |
Basically the function doesn't need any parameter. If a segment tag is given as parameter it will be checked if it is the segment currently available on the server.
If no segment is available on the current server or if no views are allocated to the segment or if the segment tagname which is given as parameter is not the currently available segment ";0;" is provided as return value.
Example:
Request views of current segment: GetViewsOfSegment |
Request command: | GetViewList | |
Parameter: | Filter criterion | (leading "*" stand for single characters, a following "*" stands for all of the following characters) |
Return value: | ;n;KKS1;KKS2;...;KKSn; (in alphabetical order) |
This function can be used without parameters. In that case, all of the views of the POS30 database will be delivered.
When using the function with a parameter, all those views of the POS30 database will be delivered that pass the specified filter criterion.
The tags in the return list may be of different length, as the space characters at the end of the strings are cut off. A tag always ends with a character not equal a space character.
Example:
Request list of views (with filter criterion "SICHT1"): GetViewList "SICHT1" |
Request command: | GetAreasOfView | |
Parameter: | view tagname | |
Return value: | ;n;area1;area2;...;area n; (in the order of the area's position in the view) | |
area: | ,4,position,tagname,description,status, |
The function needs a view tagname as parameter.
If the given view tagname is not available in the POS30 database ";0;" is provided as return value.
Example:
Request areas of view "SICHT1": GetAreasOfView "SICHT1" |
Request command: | GetAreaList | |
Parameter: | Filter criterion | (leading "*" stand for single characters, a following "*" stands for all of the following characters) |
Return value: | ;n;KKS1;KKS2;...;KKSn; (in alphabetical order ) |
This function can be used without parameters. In that case, all of the areas of the POS30 database will be delivered.
When using the function with a parameter, all those areas of the POS30 database will be delivered that pass the specified filter criterion.
The tags in the return list may be of different length, as the space characters at the end of the strings are cut off. A tag always ends with a character not equal a space character.
Example:
Request area list (with filter criterion "RAUCH"): GetAreaList "RAUCHG" |
Request command: | GetFunctionGrpsOfArea | |
Parameter: | area tagname | |
Return value: | ;n;FG1;FG2;...;FG n; (in the order of the function group's position in the area) | |
FG: | ,4,position,tagname,description,status, |
The function needs an area tagname as parameter.
If the given area tagname is not available in the POS30 database ";0;" is provided as return value.
Example:
Request function groups of area "RAUCHGAS": GetFunctionGrpsOfArea "RAUCHGAS" |
Request command: | GetFunctionGrpList | |
Parameter: | Filter criterion | (leading "*" stand for single characters, a following "*" stands for all of the following characters) |
Return value: | ;n;KKS1;KKS2;...;KKSn; (in alphabetical order) |
This function can be used without parameters. In that case, all of the function groups of the POS30 database will be delivered.
When using the function with a parameter, all those function groups of the POS30 database will be delivered that pass the specified filter criterion.
The tags in the return list may be of different length, as the space characters at the end of the strings are cut off. A tag always ends with a character not equal a space character.
Example:
Request function group list (with filter criterion "10HFE"): GetFunctionGrpList "10HFE" |
Request command: | GetLoopsOfFunctionGrp | |
Parameter: | function group tagname | |
Return value: | ;n;loop1;loop2;...;loop n; (in the order of the loop's position in the function group) | |
loop: | ,4,position,tagname,description,status, |
The function needs a function group tagname as parameter.
If the given function group tagname is not available in the POS30 database ";0;" is provided as return value.
Example:
Request loops of function group "10HFE10EA": GetLoopsOfFunctionGrp "10HFE10EA" |
Request command: | GetLoopList | |
Parameter: | Filter criterion | (leading "*" stand for single characters, a following "*" stands for all of the following characters) |
loop type | ( [ amk | ark | bmk | esk | gsa | hst | ken | prk | vwk | zmk | fba | all ] for [ analog measuring loops | analog control loops | binary measuring loops | single control loops | group sequential control loops | manual control station | characteristics | profiles | preselection loops | counter loops | loading margins | all loop types ] ) | |
Return value: | ;n;KKS1;KKS2;...;KKSn; (in alphabetical sorder) |
This function can be used without parameters. In that case, all of the loops of the POS30 database will be delivered.
When using the function with a parameter, all those loops of the POS30 database will be delivered that pass the specified filter criterion.
If the second parameter (loop type) is indicated, the first parameter (filter criterion) must be specified as well (at least * or "" or {} ). The return list then contains those loops that pass the filter criterion and are of the specified loop type.
The tags in the return list may be of different length, as the space characters at the end of the strings are cut off. A tag always ends with a character not equal a space character.
Example:
Request loop list (with filter criterion "**HNA*"): GetLoopList "**HNA*" |
Request command: | GetLoop | |
Parameter: | loop tag | loop tag list | |
Return value: | ;3;loop type;description;status; (for one loop tag) | |
or: | ;n;loop 1;loop 2; ... ; loop n; (for a loop tag list) | |
loop: | ,3,loop type,description,status, | |
status: | "OK" or combination of ANST_QUIT_1,ANST_QUIT_2,..., ANST_UNQUIT_1,ANST_UNQUIT_2,..., NANST_UNQUIT_1,NANST_UNQUIT_2,... |
If a loop tag list is specified, the return value for each loop
tagname includes a return list in the specified order, also for those loops that
were not found in the POS30 database. In this case (only for loop tag list) loop means
loop: | ,1,NoVal, |
Example:
Request data of loop "KKS 1": GetLoop "KKS 1" |
Request command: | GetLoopExt | |
Parameter: | loop tag | loop tag list | |
Return value: | ;n;loop type;description;status;<type specific>; (for one loop tag) | |
or: | ;n;loop 1;loop 2; ... ; loop n; (for a loop tag list) | |
loop: | ,m,loop type,description,status,<type specific>; | |
status: | "OK" or combination of ANST_QUIT_1,ANST_QUIT_2,..., ANST_UNQUIT_1,ANST_UNQUIT_2,..., NANST_UNQUIT_1,NANST_UNQUIT_2,... |
Element 1: | precision |
Element 1: | precision |
Element 2: | factor |
Element 3: | counter loop 8 (0 = no, 1 = yes) |
Element 1: | precision |
Element 2: | controller structure (EINSCHL, FUEHR, FOLGE, OHNE_SOLL) |
Element 3: | master/slave controller signal tag name 1 |
Element 4: | master/slave controller signal tag name 2 |
Element 5: | master/slave controller signal tag name 3 |
Element 6: | type of controller (P, PI, PID) |
Element 7: | safety position (AUF, ZU, FEHLT) |
Element 8: | controller output (INKR, PROP, O_PA) |
Element 9: | controller gain KP |
Element 10: | reset time TN |
Element 11: | derivative action time TV |
Element 12: | delay time T1 |
Element 13: | upper output limitation |
Element 14: | lower output limitation |
Element 15: | setpoint upper limit |
Element 16: | setpoint lower limit |
Element 1: | precision |
Element 2: | type of drive (ASE, AS, ASS) |
Element 3: | ASS with self-holding (0 = no, 1 = yes) |
Element 1: | precision |
Element 2: | setpoint upper limit |
Element 3: | setpoint lower limit |
Element 1: | selector function (1,2,3,4) |
Element 2: | number of the available units |
Element 3: | number of the additional units |
Element 4: | number of the standby units |
Element 5: | signal tag name of unit 1 |
Element 6: | status text of unit 1 |
Element 7: | signal tag name of unit 2 |
Element 8: | status text of unit 2 |
Element 9: | signal tag name of unit 3 |
Element 10: | status text of unit 3 |
Element 11: | signal tag name of unit 4 |
Element 12: | status text of unit 4 |
Element 1: | group control version STOP (0 = no, 1 = yes) |
Element 2: | number of the last step of the ON program |
Element 3: | number of the last step of the OFF program |
If a loop tag list is specified, the return value for each loop
tagname includes a return list in the specified order, also for those loops that
were not found in the POS30 database. In this case (only for loop tag list) loop means
loop: | ,1,NoVal, |
Example:
Request extended data of loop "KKS 1": GetLoopExt "KKS 1" |
Request command: | GetSignalsOfLoop | |
Parameter: | loop tag name | |
Return value: | ;n;Signal1;Signal2;...;Signal n; | |
Signal: |
,6,sigpos,signalKKS,description,unit,abmin,abmax, (analog signals) ,10,sigpos,signalKKS,description,limit value,unit,ZusText0,ZusText1, active state,limit value type,prio, (binary signals) | |
sigpos: | ANX, ANY, RMW, ... | |
limit value type: | HIGH/LOW |
The function needs a loop tagname as parameter.
If the given loop tagname is not available in the POS30 database ";0;" is provided as return value.
Example:
Request signals of loop "10HFE10EA100 XQ50": GetSignalsOfLoop "10HFE10EA100 XQ50" |
Request command: | GetSignalsOfLoopExt | |
Parameter: | loop tag name | |
Return value: | ;n;Signal1;Signal2;...;Signal n; | |
Signal: | ,10,sigpos,signalKKS,description,unit,beginning of display range, end of display range,P14 address,beginning of measuring range,end of measuring range, configured data type, (analog signals) ,16,sigpos,signalKKS,description,limit value,unit,ZusText0,ZusText1, active state,limit value type,prio,P14 address,bit number,configured data type, explanation,logic combination,step number, (binary signals) | |
sigpos: | ANX, ANY, RMW, ... | |
limit value type: | HIGH/LOW |
The function needs a loop tagname as parameter.
If the given loop tagname is not available in the POS30 database ";0;" is provided as return value.
Example:
Request signals of loop "10HFE10EA100 XQ50": GetSignalsOfLoopExt "10HFE10EA100 XQ50" |
Request command: | GetStepsOfGsa | |
Parameter: | loop tag name | |
Return value: | ;n;step1;step2;...;step n; | |
step: | ,5,number,description,alternative step,monitoring time,waiting time, |
The function needs a loop tagname as parameter.
Example:
Request list of all steps of loop "HFE33 EA100": GetStepsOfGsa "HFE33 EA100" |
Request command: | GetSigList | |
Parameters: | Filter criterion | (leading "*" stand for single characters, a following "*" stands for all of the following characters) |
Signal type | ( [ ana | bin | calc | cnt | step | rm | bed ] für [ analog signals | binary signals | calculated values | counter values | steps | checkback signals | operating signals ] ) | |
Return value: | ;n;KKS1;KKS2;...;KKSn; (in alphabetical order) |
This function can be used without parameters. In that case, all of the signals of the POS30 database will be delivered.
When using the function with the first parameter only, all those signals of the POS30 database will be delivered that pass the specified filter criterion.
If the second parameter (signal type) is indicated, the first parameter (filter criterion) must be specified as well (at least * or "" or {} ). The return list then contains those signals that pass the filter criterion and are of the specified signal type.
The tags in the return list may be of different length, as the space characters at the end of the strings are cut off. A tag always ends with a character not equal a space character.
Example:
Request tag list (using filter criterion "**HNA*"): GetSigList "**HNA*" |
Request command: | GetSigListExt | |
Parameters: | - as for "GetSigList" - | |
Return value: | ;n;,2,KKS1,sigtyp1,;,2,KKS2,sigtyp2,;...;,2,KKSn,sigtypn,; (in alphabatical order based on KKS tag name) |
This function differs from "GetSigList" in that the return value consists of individual lists for each signal, containing signal tag name and signal type.
Example:
Request tag list incl. signal type (using filter criterion
"**HNA*"): GetSigListExt "**HNA*" |
Request command: | GetDeltaSigList | |
Parameters: | Filter criterion | (optional; leading "*" stand for single characters, a following "*" stands for all the following characters) |
Return value: | ;n;,2,KKS1,SW1,;,2,KKS2,SW2,;...;,2,KKSn,SWn,; (in alphabatical order based on KKS tag name; SW = threshold with which the signal is archived) |
Example:
Request tags of all the analog signals in the delta archive: GetDeltaSigList |
Request command: | GetHistorySigList | |
Parameters: | Filter criterion | (optional; leading "*" stand for single characters, a following "*" stands for all of the following characters) |
Return value: | ;n;,2,KKS1,CA11,;,4,KKS2,CA21,CA22,CA23,;...;,3,KKSn,CAn1,CAn2,; (in alphabatical order based on KKS tag name; CA = compression algorithm used for archiving the signal: [ avg | min | max ] ) |
The individual lists for each KKS tag nesting in the return list may be of different lengths, since a signal can enter the analog value memory for process control after having undergone up to three compression algorithms.
Example:
Request tags of all the analog signals for process control: GetHistorySigList |
Request command: | GetVal | |
Parameters: | Signal tag | signal tag list | |
Return value: | ;n;<type specific>; (for one signal tag; the elements of the type-specific return list are separated by ";") | |
or: | ;m;,n1,<typspec1>,;,n2,<typspec2>,;.....;,nm,<typspecm>,; (for a signal tag list; the elements of the type-specific return list are separated by ",") |
If a signal tag name list is specified, the return value for each signal tag name includes a type-specific return list (also for those signals that were not found in the POS30 database) in the specified order.
Type specific return lists:
Number of list elements: | 8 |
Element 1: | type (= a) |
Element 2: | - blank - |
Element 3: | physical value |
Element 4: | status |
Element 5: | unit |
Element 6: | beginning of measuring range |
Element 7: | end of measuring range |
Element 8: | designation |
Number of list elements: | 6 |
Element 1: | type (= b) |
Element 2: | P14 telegram (e.g. 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0) |
sequence: bit15, bit14, ... , bit0 | |
bits are separated by space characters | |
Element 3: | current value of the bit |
Element 4: | status |
Element 5: | status text |
Element 6: | designation |
Number of list elements: | 5 |
Element 1: | type (= n) |
Element 2: | - blank - |
Element 3: | step number |
Element 4: | status |
Element 5: | designation |
Number of list elements: | 6 |
Element 1: | type (= z) |
Element 2: | - blank - |
Element 3: | counter value |
Element 4: | status |
Element 5: | unit |
Element 6: | designation |
Number of list elements: | 5 |
Element 1: | type (= c) |
Element 2: | - blank - |
Element 3: | physical value |
Element 4: | status |
Element 5: | designation |
Number of list elements: | 6 |
Element 1: | type (= r) |
Element 2: | P14 telegram (e.g. 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0) |
sequence: bit15, bit14, ... , bit0 | |
bits are separated by space characters | |
Element 3: | value of bit 5 (EO) |
Element 4: | status |
Element 5: | status text |
(bit5 = 1 -> text for status 1, bit4 = 1 -> text for status 0) | |
Element 6: | designation |
Number of list elements: | 1 |
Element 1: | "NoVal" |
Request current value of "KKS 1" tag: GetVal "KKS 1" |
Request command: | GetValStream | |
Parameters: | Signal tag | Signal tag list | |
Return value: | ;n;<type specific>; (for one signal tag; the elements of the type-specific return list are separated by ";") | |
or: | ;m;,n1,<typespec1>,;,n2,<typespec2>,;.....;,nm,<typespecm>,; (for a signal tag list; the elements of the type-specific return list are separated by ",") |
The formats of the return values' elements correspond to those of StreamRead. The signal type is indicated in upper case letters if the signal is disturbed.
If a signal tag name list is specified, the return value for each signal tag name includes a type-specific return list (also for those signals that were not found in the POS30 database) in the specified order.
Type specific return lists:
Number of list elements: | 4 |
Element 1: | Type (= a resp. A, if disturbed) |
Element 2: | Signal tag name |
Element 3: | physical value using float format "1.23456789+e01" |
Element 4: | time stamp using format "YYMMDDHHMMSSMMM" |
Number of list elements: | 4 |
Element 1: | Type (= b resp. B, if disturbed) |
Element 2: | Signal tag name |
Element 3: | the bit's current value (0 or 1) |
Element 4: | time stamp using format "YYMMDDHHMMSSMMM" |
Number of list elements: | 4 |
Element 1: | Type (= n resp. N, if disturbed) |
Element 2: | Signal tag name |
Element 3: | step number |
Element 4: | time stamp using format "YYMMDDHHMMSSMMM" |
Number of list elements: | 4 |
Element 1: | Type (= z resp. Z, if disturbed) |
Element 2: | Signal tag name |
Element 3: | counter value |
Element 4: | time stamp using format "YYMMDDHHMMSSMMM" |
Number of list elements: | 4 |
Element 1: | Type (= c resp. C, if disturbed) |
Element 2: | Signal tag name |
Element 3: | physical value using float format "1.23456789+e01" |
Element 4: | time stamp using format "YYMMDDHHMMSSMMM" |
If the server specific configuration file STREAM_RM_R exists the return value is delivered with type "r/R", otherwise with type "x/X".
Number of list elements: | 4 |
Element 1: | Type (= r resp. R, if disturbed) |
Element 2: | Signal tag name |
Element 3: | Bit 5 and bit 4 as a bit pattern (e.g. "10") |
Element 4: | time stamp using format "YYMMDDHHMMSSMMM" |
Number of list elements: | 7 |
Element 1: | Type (= x resp. X, if disturbed) |
Element 2: | Signal tag name |
Element 3: | Data type as a 2-digit decimal value |
Element 4: | current value as a 4-digit hexadecimal value |
Element 5: | Type of the old value (= x resp. X, if disturbed) |
Element 6: | old value as a 4-digit hexadecimal value |
Element 7: | time stamp using format "YYMMDDHHMMSSMMM" |
Number of list elements: | 2 |
Element 1: | "NoVal" |
Element 2: | Signal tag name |
Request current value of "KKS 1" tag: GetValStream "KKS 1" |
Request command: | GetSOE |
Parameters: | Number of messages Prio1 (0/1) Prio2 (0/1) Prio3 (0/1) Maintenance message (0/1) |
Return value: | ;1;one SOE line; |
Attention: Only one message will be delivered !
Explanatory notes to the parameters:
Go back 30 messages and find the next prio1 message: GetSOE 30 1 0 0 0 |
Request command: | GetSOESince | |
Parameters: | Start time | (using format: "DD-MON-YYYY HH:MM:SS.HH") |
End time | (using format: "DD-MON-YYYY HH:MM:SS.HH" or number of seconds). | |
Selection list | (optional) | |
Return value: | ;n;message1;...;message n; |
This function can be called in two different ways:
As an option, a selection list may be specified. This list contains one or several of the following strings: "prio1", "prio2", "prio3" or "maint". If no selection list has been specified, GetSOESince delivers all of the messages of the specified time range.
The format of a message in the list is as follows:
,6,<Symbol>,<Event>,<Time stamp>,<Ident.>,<Designation>,<Status>,
<Symbol>: | "+" | incoming message |
"-" | outgoing message | |
" " | incoming/outgoing criterion not applicable
| |
<Event>: | "1", "2", "3" | Prio 1 to Prio 3 |
"0" | control condition | |
"S" | disturbance message | |
"P" | POS message | |
"B" | operating message | |
"w" | maintenance message | |
" " | status message
| |
<time stamp>: | DD-MON-YYYY HH:MM:SS.HH The format of the time stamp is identical with the format of the time specified as start and end time.
| |
<Ident.>: | Signal tag name | |
<Designation>: | Signal designation | |
<Status text>: | Status text |
Example:
Request all prio 1 and prio 2 messages as of 14-OCT-1998 11:15:00.00 which have occurred in the following 30 seconds: GetSOESince "14-OCT-1998 11:15:00.00" 30 "prio1 prio2" |
Request command: | GetSOEInfo | |
Parameters: | Requested information: currently "times" only | |
Return value: | ;2;start time;end time; |
"GetSOEInfo times" delivers the time stamp of the oldest and the latest message in the SOE list. The format of the time stamps is "TT-MON-JJJJ HH:MM:SS.HH".
Example:
Request time stamp of the oldest and the latest message from the SOE list: GetSOEInfo times |
Request command: | GetSOENewest | |
Parameters: | Number of messages "n" to be read (Integer) | |
Selection mask (optional) | ||
Return value: | ;n;message1;...;message n; |
"GetSOENewest" delivers the "n" latest messages of
the POS30 SOE list.
Optionally a selection mask can be specified. The content of this mask will be
described later.
If no selection mask is specified GetSOENewest will deliver the latest messages
without restriction.
The format of a message in the list is as follows:
,7,<Message Id>,<Symbol>,<Event>,<Time stamp>,<KKS>,<Designation>,<Status>,
<Message Id>: | Identification number of the message for further use in "GetSOEPrevious" and "GetSOENext". |
Example:
Request the 5 latest messages: GetSOENewest 5 |
Request command: | GetSOEOldest | |
Parameters: | Number of messages "n" to be read (Integer) | |
Selection mask (optional) | ||
Return value: | ;n;message1;...;message n; |
"GetSOEOldest" delivers "n" oldest messages
of the POS30 SOE list.
Optionally a selection mask can be specified. The content of this mask is
the same as for GetSOENewest.
If no selection mask is specified
GetSOEOldest will deliver the oldest messages without restriction.
The format of a message in the list corresponds to that of GetSOENewest.
Example:
Request the 5 oldest messages: GetSOEOldest 5 |
Request command: | GetSOENext | |
Parameters: | Number of messages "n" to be read (Integer) | |
Message Id | ||
Selection mask (optional) | ||
Return value: | ;n;message1;...;message n; |
<Message Id>: | Identification number of a message from "GetSOENewest" and "GetSOEOldest". |
"GetSOENext" delivers at most "n" messages of the
POS30 SOE list which are available after the message identified by
<Meldungs-Id>. If there are less than "n" messages
available, only those are delivered.
Optionally a selection mask can be specified. The content of this mask is
the same as for GetSOENewest.
If no selection mask is specified
GetSOEOldest will deliver the messages without restriction.
The format of a message in the list corresponds to that of GetSOENewest.
Example:
Request 5 messages following the message 3742_3: GetSOENext 5 3742_3 |
Request command: | GetSOEPrevious | |
Parameters: | Number of messages "n" to be read (Integer) | |
Message Id | ||
Selection mask (optional) | ||
Return value: | ;n;message1;...;message n; |
<Message Id>: | Identification number of a message from "GetSOENewest" and "GetSOEOldest". |
"GetSOEPrevious" delivers at most "n" messages of the
POS30 SOE list which are available preceding the message identified by
<Meldungs-Id>. If there are less than "n" messages
available, only those are delivered.
Optionally a selection mask can be specified. The content of this mask is
the same as for GetSOENewest.
If no selection mask is specified
GetSOEOldest will deliver the messages without restriction.
The format of a message in the list corresponds to that of GetSOENewest.
Example:
Request 5 messages preceding message 3742_3: GetSOEPrevious 5 3742_3 |
Request command: | GetHistory | ||||||||
Parameters: | Signal tag name compression algorithm (avg/min/max) Start time (Format = "DD.MM.YYYY HH:MM:SS") Number of values | ||||||||
Return value: | ;2;,3,start date,start time,buffer;,n,value1,value2,...,valuen,; | ||||||||
|
Example:
Request the averages for "KKS 1" (one value per second): GetHistory "KKS 1" avg "28.09.1998 17:00:00" 15*60 |
Request command: | GetDeltaHistory |
Parameters: | Signal tag name start time (format = "DD.MM.YYYY HH:MM:SS") end time (format = "DD.MM.YYYY HH:MM:SS") |
Return value: | ;n;,4,time1,value1,status1,quality1,;...;,4,timen,valuen,statusn,qualityn,; (time: format = YYMMDDHHMMSSMMM value: format = physical value in the form of a float value status: format = 0 (OK) or 1 (disturbed) quality: = 0 (Value is reliable: there has been no breakdown of POS30 process data recording; if signal is a counter it hasn't been modified manually), = 2 (There has been at least one breakdown of POS30 process data recording before the current value) = 3 (just as 2; but it is an operating time counter and the aggregat was in the same state before and after the breakdown of POS30 process data recording) = 4 (just as 2; but it is an operating time counter and the aggregat was in a different state before and after the breakdown of POS30 process data recording) = 5 (signal is a counter whose counter value has been modified manually, that means the current value is lower than the previous value). ) |
Example:
Request the values for the "KKS 1" tag of 28.09.1998 from 10.00 a.m. until 5.00 p.m.: GetDeltaHistory "KKS 1" "28.09.1998 10:00:00" "28.09.1998 17:00:00" |
Request command: | GetDeltaInfo |
Parameters: | Signal tag name Type of the requested information; currently "times" only |
Return value: | ;n;,3,DT1,starttime1,endtime1,;...;,3,DTn,starttime n,endtime n,; (DT = storage medium: "MO" or "Disk" start time: format = DD.MM.YYYY HH:MM:SS end time: format = DD.MM.YYYY HH:MM:SS) |
This function delivers the time ranges of the archive data on MO and/or hard disk for one signal. The format of the start and end times in the return list corresponds to the format of the input parameter start and end times for the GetDeltaHistory function.
Example:
Request archive times for the "KKS 1" tag: GetDeltaInfo "KKS 1" times |
Request command: | GetDeltaValue |
Parameters: | Signal tag name Compression algorithm (MIN | MAX | AVG | INT | TMIN | TMAX) Start time (format = "DD.MM.YYYY HH:MM:SS") End time (format = "DD.MM.YYYY HH:MM:SS" or <intervall>) |
optional: | Interval (format = <interval>) (<interval> : format = m<unit> <unit> = sec | min | hour | day | week | month | year example: 15min) |
Return value: | ;n;,4,time1,value1,status1,quality1,;...;,4,timen,valuen,statusn,qualityn,; (time: format = YYMMDDHHMMSSMMM value: format = physical value in the form of a float value status: format = 0 (all values within the interval are OK) or = 1 (at least one value within the interval is disturbed) quality: = 0 (Value is reliable: there has been no breakdown of POS30 process data recording; data is completely available or an appropriate time (configurable as cache time QUALITY_TIME) has passed since the last occurence of the signal, respectively), = 1 (Value is not reliable because data is not completely available for the requested interval) = 2 (Value is not reliable because there has been at least one breakdown of POS30 process data recording in the requested interval). ) |
This function delivers values with the specified compression algorithm from the delta archive for a signal. The number of the values delivered depends on how well the interval indicated for the interval parameter fits into the time period from start time until end time.
The times delivered in the return value correspond to the end time
of the respective interval.
Exception: For functions "TMIN" and
"TMAX" the delivered times correspond to the time when the minimum
or maximum value occured.
If no value has been specified for the
interval parameter, the complete time range from start time until end
time is used as the interval. Only one time/value pair will be delivered.
Example:
Request averages for the "KKS 1" tag of 28.09.1998 from 10.00 a.m. until 5.00 p.m. at 15-minute intervals: GetDeltaValue "KKS 1" avg "28.09.1998 10:00:00" "28.09.1998 17:00:00" 15min |
Request command: | GetCounterValue |
Parameters: | Signal tag name Function (REL | ABS) Start time (format = "DD.MM.YYYY HH:MM:SS") End time (format = "DD.MM.YYYY HH:MM:SS" or <interval>) |
optional: | Interval (format = <interval>) (<interval> : format = m<unit> <unit> = sec | min | hour | day | week | month | year example: 15min) |
Return value: | ;n;,4,,time1,value1,status1,quality1,;...;,4,timen,valuen,statusn,qualityn,; (time: format = YYMMDDHHMMSSMMM value: format = physical value in the form of a float value status: format = 0 (all values within the interval are OK) or = 1 (at least one value within the interval is disturbed) quality: = 0 (Value is reliable: there has been no breakdown of POS30 process data recording; data is completely available or an appropriate time (configurable as cache time QUALITY_TIME) has passed since the last occurence of the signal, respectively; counter hasn't been modified manually), = 1 (Value is not reliable because data is not completely available for the requested interval) = 2 (Value is not reliable because there has been at least one breakdown of POS30 process data recording in the requested interval) = 3 (just as 2; but it is an operating time counter and the aggregat was in the same state before and after the breakdown of POS30 process data recording, so for operating time calculation it is assumed that the state of the aggregat has uninterruptedly been the same) = 4 (just as 2; but it is an operating time counter and the aggregat was in a different state before and after the breakdown of POS30 process data recording, so for operating time calculation it is assumed that the state of the aggregat has changed immediately at the end of the breakdown) = 5 (counter value has been modified manually, that means a value was used during calculation of the interval value which is lower than the previous value.) ) |
This function delivers, for a particular signal, values from the delta archive that have the specified function. The number of values delivered depends on how well the interval indicated for the interval parameter fits into the time period from start time until end time.
The "function" parameter defines whether the counter value pending at the end of the time interval ( = ABS) or the counter value difference ( = REL) between beginning and end of the time interval is to be delivered for the counter signal.
The times delivered with the return value correspond to the end time of the respective interval. If no value has been specified for the interval parameter, the complete time range from start time until end time is used as the interval. Only one time/value pair is delivered.
Example:
Request absolute values for the "KKS 1" tag of 28.09.1998 from 10.00 a.m. until 5.00 p.m. for 15-minute intervals: GetCounterValue "KKS 1" ABS "28.09.1998 10:00:00" "28.09.1998 17:00:00" 15min |
Request Command: | GetBinHistory |
Parameters: | Signal tag name Start time (Format = "DD.MM.YYYY HH:MM:SS") Ende time (Format = "DD.MM.YYYY HH:MM:SS") |
Return value: | ;n;,4,time1,value1,status1,quality1,;...;,4,timen,valuen,statusn,qualityn,; (time: Format = YYMMDDHHMMSSMMM value: Format for type "binary" = 0|1, for type "RM" = telegram value as integer, status: Format = 0 (OK) or 1 (disturbed) ) quality: = 0 (Value is reliable: there has been no breakdown of POS30 process data recording), = 2 (There has been at least one breakdown of POS30 process data recording before the current value) |
Example:
Request the values for the "KKS 1" tag of 28.09.1998 from 10.00 a.m. until 5.00 p.m.: GetBinHistory "KKS 1" "28.09.1998 10:00:00" "28.09.1998 17:00:00" |
Request command: | GetBinInfo |
Parameters: | Signal tag name Type of the requested information; currently "times" only |
Return value: | ;n;,3,DT1,starttime1,endtime1,;...;,3,DTn,starttimet n,endtime n,; (DT = Device: "MO" or "Disk" start time: format = DD.MM.YYYY HH:MM:SS end time: format = DD.MM.YYYY HH:MM:SS) |
This function delivers the time ranges of the archive data on MO and/or hard disk for one signal. The format of the start and end times in the return list corresponds to the format of the input parameter start and end times for the GetBinHistory function.
Example:
Request archive times for the "KKS 1" tag: GetBinInfo "KKS 1" times |
Request command: | GetBinValue |
Parameters: | Signal tag name Start time (format = "DD.MM.YYYY HH:MM:SS") End time (format = "DD.MM.YYYY HH:MM:SS" or <intervall>) |
optional: | Interval (Format = <interval>) (<interval> : Format = m<unit> <unit> = sec | min | hour | day | week | month | year example: 15min) |
Return value: | ;n;,4,,time1,value1,status1,quality1,;...;,4,timen,valuen,statusn,qualityn,; (time: format = YYMMDDHHMMSSMMM value: format for type "binary" = 0 (if 0 in the whole interval) = 1 (if 1 in the whole interval) = ? (if value is not clear in the interval) for type "checkback telegram" = telegram value as integer (if one same value in interval) = ? (if value is not clear in the interval) status: format = 0 (all values in interval are OK) or = 1 (at least one value in interval is disturbed) quality: = 0 (Value is reliable: there has been no breakdown of POS30 process data recording; data is completely available for the requested interval), = 1 (Value is not reliable because data is not completely available for the requested interval) = 2 (Value is not reliable because there has been at least one breakdown of POS30 process data recording in the requested interval). ) |
This function delivers values for a signal from the binary archive. The number of the values delivered depends on how well the interval indicated for the interval parameter fits into the time period from start time until end time.
The times delivered in the return value correspond to the end time of the respective interval. If no value has been specified for the interval parameter, the complete time range from start time until end time is used as the interval. Only one time/value pair will be delivered.
Example:
Request values for the "KKS 1" tag of 28.09.1998 from 10.00 a.m. until 5.00 p.m. at 15-minute intervals: GetBinValue "KKS 1" "28.09.1998 10:00:00" "28.09.1998 17:00:00" 15min |
A process MIC is running on the POS30 XTC server, which receives and processes all of the telegrams coming in from the PROCONTROL system. This process supports a table containing all the current signal values.
As soon as the reading of changed values is started, the process MIC starts entering all of the changed values it receives into a message buffer. Previously the message buffer is emptied. The "block" and "nonblock" parameters can be used to control how the process is to respond in case the message buffer overflows and no more new messages can be entered:
"block": MIC waits until the buffer can accept messages again.
"nonblock": MIC continues to process. The messages are lost, since they cannot be entered into the buffer. The signal table, however, is still being updated.
The "nonblock" mode is to be recommended for cases where the POS30 server is not exclusively being used for the XTC data interface, but also as a "normal" POS30 server, i.e. for process control and display functions. If, in this mode, the message buffer is not read fast enough by the client, intermediate values can be lost.
In the "block" mode, values cannot be lost, under normal circumstances. If, however, the message buffer has not been read by the client for a long period of time (i.e. the process MIC is in a waiting status over an extended time), the receive buffer, that is used by the POS30 server to receive the changed values from PROCONTROL, fills up (buffer size = 22.000 changed values). The TS50 coupling module sends no further changed values to the POS30 server in that case. As soon as the message buffer is read again, and space is available again, the TS50 coupling module sends the current values for all of the signals. Thus the process values are up-to-date, but some intermediate values have been lost.
Request command: | StreamStart |
Parameters: | block | nonblock |
Return value: | OK or error message |
The process MIC stops the entering of changed values into the message buffer.
Request command: | StreamStop |
Parameters: | - none - |
Return value: | OK or error message |
The process MIC writes all the current values from the signal table into the message buffer.
Request command: | StreamRequestSnapshot |
Parameters: | - none - |
Return value: | OK or error message |
The process MIC writes all the current values from the signal table into the message buffer and then starts entering all the changed values that occur into the message buffer. The "block" / "nonblock" parameter has the same function as for StreamStart.
Request command: | StreamStartWithSnapshot |
Parameters: | block | nonblock |
Return value: | OK or error message |
Selection criteria are specified which limit the number of signals delivered by StreamRead.
Hint: If a selection is active the number of elements in a
snapshot between "[" and "]" may be smaller than
alleged in
"[ <number-of-items>".
StreamRead <number> may deliver less than
<number> messages.
Request command: | StreamSelect |
Parameters: | Selection type (pattern | list | all | info ) |
string pattern (for pattern) | signal tag name list (for list) | - (for all/info) | |
Return value: | OK, current specification or error message |
Selection type: | pattern | StreamRead delivers the values of those tag names which match the specified string pattern (* and ? are allowed). |
list | StreamRead delivers the values of those tag names which are contained in the specified signal tag name list. | |
all | StreamRead delivers the values of all tag names (this is the default specification at StreamStart). | |
info | The current specifications are delivered, e.g. ;2;all;,1,*,; ;2;pattern;,1,A PATTERN CONTAINING * AND ?,; ;2;list;,7,THIS,IS,A,LIST,WITH,7,ELEMENTS,; |
If no parameter has been specified, all of those changed values are delivered that are present in the message buffer. Thus the message buffer is emptied completely.
As an option, the user can specify how many messages are maximally to be read from the buffer. The other changed values are maintained in the message buffer.
The changed values are delivered in the form of a list.
Request command: | StreamRead |
Parameters: | (optional: maximum number of changed values) |
Return value: | for snapshot list: ;[n;signal value1;...;signal value n;]; or for changed value list: ;signal value1;...;signal value n;; |
The delivered list differs from the return lists described before: | |
Snapshot list: | ;[n;signal value1;...;signal value n;]; |
The snapshot list starts with a separator and a "["-character (left bracket), followed by the number of list elements, then by the signal values, each separated by the separator. The last signal value is followed by a separator and "]" (right bracket). | |
Changed value list: | ;signal value1;...;signal value n;; |
In the case of the changed value list, there is no number of list elements indicated at the beginning of the list. The list starts with the separator, followed by the signal values separated from each other by the separator. The list ends with two separators. | |
If no changed values have been detected since the last StreamRead, the changed value list merely contains two separators: ";;". |
A signal value is a list which consists of "type,KKS,value,time stamp". The format used for the value depends on the type of signal:
For checkback telegrams, there is now a detailed type "x" available whose signal value is also a list consisting of
"current type,KKS,data type,current value,old type,old value,time stamp". The data type uses two digits, the current value and old value are four-digit hexadecimal values:
The type is indicated in upper case letters ("A", "B", "N", "Z", &wquot;C", "R", "X") when the signal is disturbed.
The time stamp is indicated in the "YYMMDDHHMMSSMMM" format.
Furthermore, error or info messages may appear in this list:
Write Commands: | SetSignalPhysical (writes the physical analog value with 12 bit precision) SetSignalPhysicalExact (writes the physical analog value with float precision) SetSignalPercent (writes the percentage analog value) SetSignalBinary (writes the binary value) SetSignalRM (writes the checkback telegram) SetSignalNumber (writes the counter value) SetSignalBit (writes particular bit of a checkback telegram, other bits unmodified) SetSignalStep (sets step of group sequential control) |
Parameters: | Signal tag name [bit number] (only for SetSignalBit) value time stamp with DST specification (optional) disturbed bit specification (optional) initial data transmission (optional) |
Return value: | OK or error message |
Parameter value:
Parameter time stamp:
Parameter disturbed bit specification:
Parameter initial data transmission:
Example:
Set value of the "KKS 1" tag to 23.4 (physical): SetSignalPhysical "KKS 1" 23.4 |
Commands: | PollData and all of the request and write commands described in this document (except for commands of the stream functionality) |
Parameters: | for PollData: - none - Other commands: cf. respective description |
Return value: |
No operating instructions found | Operating instructions found | |
PollData | ;0; | ;1;<m operating instructions>; |
Other commands |
|
|
<m operating instructions> is a list which is structured as follows:
Example of a return value for a "SetSignal...." write command:
Operating instruction texts for operations possible from the POS30:
Request command: | WatchMe | |
Parameter: | clientname | |
Return value: | OK |
"clientname" is the quite arbitrary name of the XTC client application.
All the signals which will be registered after this command using "WatchSignal <signal> 1" will be set to status "disturbed" in the POS30 when the current connection is closed.
Up to 5 clients can be supervised.
Example:
Start monitoring the connection of client1: WatchMe client1 |
Request command: | WatchSignal | |
Parameter: | signal tagname | |
value [0/1] | ||
Return value: | OK |
The signal will be set to status "disturbed" in the POS30 and inserted to POS30
Sequence of Events when the current client connection is aborted or closed (value = 1) or
this behaviour is turned off (value = 0), respectively.
A signal can be supervised only if the client has previously sent the command
"WatchMe <clientname>".
Example:
Logon signal "SIGNALKKS1" for supervision: WatchSignal "SIGNALKKS1" 1 |
The following information can be called up:
Request command: | GetInfo |
Parameters: | "version" or "pbsVersion" or "startTime" or "currentTime" or "license <licence type> (license type is "xb", "xd" or "xe") or "stdActTime" or "currentTime2" |
Return value: | String with requested information |
telnet> open localhost 2000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
GetSigList
;n;KKS1;KKS2;...;KKSn;
^]
telnet> quit
In place of "localhost" a computer name can be entered to indicate a computer that can be reached via a TCP/IP connection.
After the connection has been established, every XTC command can be executed. The return value is a string of arbitrary length that is terminated by a newline character (Ascii 10). Within the string, only printable characters will appear.
The connection can be terminated by pressing and holding down the control key and typing in ']' (right bracket.
Please note: