XTC
Data Interface

 © TARCUS GmbH

PROCONTROL P


Process Operator Station
POS30


Version: 5.3
As per July 2004



 
ABB TARCUS
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

 




Introduction

This document describes the XTC data interface of the PROCONTROL P process operator station POS30. It is primarily intended for users of this interface, i.e. engineers designing applications for data transmission to and from the POS30.

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:






System Architecture

The XTC interface is implemented in the form of a client server architecture: An XTD server process (XTC daemon) for the POS30 data interface is installed on the POS30 server in addition to the POS30 software. This process governs the controlled and secure access of one or several external applications (clients) to the POS30 database. Architecture When using the XTC, one POS30 server (for redundant configurations: two servers) should be reserved to be used as a data interface. This means, the POS30 functions for process control and monitoring (OMS) should not be run on this server.

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.






Installation and licensing

XTC is available, along with the POS30 software (R4.0-0 and higher) on a CD-ROM. For the user, the installation procedure is the same as for the POS30 standard installation. All of the XTC components are added automatically after a successful POS30 software installation. The XTC, however, is activated only after the function has been enabled by ABB personnel using a valid license code.






Functions

In the following, all of the functions of the XTC interface are described briefly. Detailed descriptions of the syntax of all the calls and responses are given further below, including examples in Visual Basic.

Requesting of
hierarchy data
Requesting of
tag lists

Reading of current and
historical values

 
Reading of
changed values
Writing of values
Process control
in external systems

 
Monitoring
the connections
Requesting of information
about the POS30 system



Requesting of hierarchy data





Requesting the tag lists





Reading current and historical values

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:





Reading changed values

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.





Writing values

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.).





Process operation in external systems

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:

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.





Monitoring the connections

A client can logon its connection for monitoring using the command WatchMe.

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".





Requesting information about the POS30 system

The following information on the POS30 server can be called up:






Creating a client application

Establishing and using
a client server
connection

Basic structure
of a command and
of a return string

 
Requesting of
hierarchy data
Requesting of
tag lists
Reading of current and
historical values
Reading of
changed values
Writing of values
Process control
in external systems

 
Monitoring
the connections
Requesting of
information
about the POS30 system



Establishing and using a client-server connection

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





Basic structure of a command and a return string

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:





Requesting of hierarchy data

  1. Segment of current server

    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


  2. List of all views of the segment

    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


  3. List of all views

    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"


  4. List of all areas of a views

    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"


  5. List of all areas

    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"


  6. List of all function groups of an area

    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"


  7. List of all function groups

    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"


  8. List of all loops of a function group

    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"

  9. List of all loops

    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*"

  10. Loop data

    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"

  11. Loop data (extended return value)

    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,...

    Type specific elements of the return value:

    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"


  12. List of all signals of a loop

    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"


  13. List of all signals of a loop (extended return value)

    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"


  14. List of all steps of a sequential group control

    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"





Requesting tag lists

  1. List of all the signals

    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*"


  2. List of all the signals (extended return value)

    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*"


  3. List of all the analog signals from the analog value memory of the delta archive

    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


  4. List of all the analog signals from the analog value memory for process control

    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





Reading current and historical values

  1. Reading a current signal value

    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:


    Example:
    Request current value of "KKS 1" tag:

    GetVal "KKS 1"


  2. Reading a current signal value with a return value similar to Stream

    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:


    Example:
    Request current value of "KKS 1" tag:

    GetValStream "KKS 1"


  3. Reading entries in the POS30 SOE list

    1. Reading a message of the POS30 SOE list starting from a certain position

      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:

      • Number of messages = 0 means that the next message that will occur will be delivered with the priority selected.

      • Number of messages > 0 means that, starting with the latest message, this number of messages will be positioned back in the SOE list and that the list will be searched for the first message with the respective selection criterion starting from that position. If such a message is found, it will be delivered.

      Example:
      Go back 30 messages and find the next prio1 message:

      GetSOE 30 1 0 0 0


    2. Reading messages from the POS30 SOE list from a particular time range

      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:

      1. with start time and end time
      2. with start time and a time range in seconds.

      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"


    3. Request information on the POS30 SOE list

      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


    4. Reading the latest messages out of the POS30 SOE list

      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


    5. Reading the oldest messages out of the POS30 SOE list

      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


    6. Reading the messages following a certain message of the POS30 SOE list

      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


    7. Reading the messages preceding a certain message of the POS30 SOE list

      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


  4. Reading from the analog value memory for process control

    1. Reading the history of an analog signal from the analog value memory for process control

      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,;
       
      (start date: format = DD.MM.YYYY
      start time: format = HH:MM:SS
      buffer: 1 : values come from the 1-sec buffer
                16 : values come from the 16-sec buffer)

      Example:
      Request the averages for "KKS 1" (one value per second):

      GetHistory "KKS 1" avg "28.09.1998 17:00:00" 15*60


  5. Reading from the delta archive

    1. Reading the history of an analog signal from the delta archive

      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"


    2. Reading information on an analog signal from the delta archive

      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


    3. Reading values of an analog signal from the delta archive

      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


    4. Reading values of a counter signal from the delta archive

      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


  6. Reading from the binary archive

    1. Reading the history of a binary signal or a checkback signal from the binary archive

      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"


    2. Reading information of an binary signal or a checkback signal from the binary archive

      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


    3. Reading values of an binary signal or a checkback signal from the binary archive

      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





Reading changed values

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.

changed values

  1. Starting the reading of changed 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


  2. Ending the reading of changed values

    The process MIC stops the entering of changed values into the message buffer.

    Request command: StreamStop
    Parameters: - none -
    Return value: OK or error message


  3. Requesting the current values of all the signals

    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


  4. Requesting the current values of all signals and starting the reading of the changed values

    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


  5. Specifying selection criteria for StreamRead setzen

    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,;


  6. Reading changed values

    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:





Writing values

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





Process operation in external systems

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
  • ;n;value1; ... ;value n;
  • OK or other text
  • ;n+1;value1; ... ;value n;<m operating instructions>;
  • ;2;<text>;<m operating instructions>;

<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:





Monitoring the connections

  1. Initialization of monitoring the connections

    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


  2. Logon/Logoff a signal

    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





Requesting information via the POS30 system

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






Testing the interface

The XTC data interface can be tested directly by using "telnet":

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.






Error messages

Please note:






Info messages when reading changed values

The following info messages are entered into the stream message buffer after a StreamStart:

Further info messages: