|
4. Appendix |
|
Poses++ Syntax Overview
Distribution functions
Animation functions
Layout and Animation command syntax
Poses++ Client API
Command line options and parameters
Hardware and Software Environment
Contact & Copyright
| 4.1. Poses++ Syntax Overview | 
|
The syntax survey is given in an extended Backus-Naur form. Terminal symbols are represented in bold type font and non terminal symbols are represented with an italic type font. A syntax rule has the following form:
NonTerminalSymbol: syntactic construction
alternativ syntactic construction
...
Optional parts of syntactic constrcution are enclosed in a pair of [] brackets. Repeatedly usable parts of syntatctic constructions are enclosed in a pair of {} brackets. Comments follow the C++ syntax conventions.
Poses++ programs can be written in a free format. Blanks, tabs, new-line characters and comments are ignored unless they serve for separation of designators, constants or keywords. Additionally Poses++ supports also the precompiler directives adopted from C/C++.
SourceFileContext:
[ ImportStatment ] [ GlobalDeclarationList ]
ImportStatement:
import ImportFile [ { , ImportFile } ] ; // import source1, "source 2";
ImportFile:
FileNameBody // a file name body like an identifier
"FileNameBody" // a file name body with spaces, leading digits, ...
GlobalDeclarationList:
GlobalDeclaration
GlobalDeclarationList GlobalDeclaration
GlobalDeclaration:
TypeDeclaration
CFunctionPrototype // subset of C/C++ declartions for function prototypes
TypeDeclaration:
CTypeDeclaration // subset of C/C++ declartions for data types
PredicateTypeDeclaration
ModuleDeclaration
Identifier:
CharacterSequence // leading letter, followed by digits or underscore
ModuleDeclaration:
ModuleType [ ModuleDeclaratorList ] ; // module Name { ... };
ModuleDeclaratorList:
ModuleDeclarator
ModuleDeclaratorList , ModuleDeclarator
ModuleDeclarator:
ModuleName [ ( ModuleConstructorList ) ]
ModuleConstructorList:
ModuleConstructorAssignment
ModuleConstructorList , ModuleConstructorAssignment
ModuleConstructorAssignment:
ParameterName = ParameterName
PredicateName = PredicateName
ModuleInstanceName = ModuleInstanceName
ModuleType:
[module] ModuleTypeName [ ModuleDefinition ]
ModuleTypeName:
Identifier
ModuleDefinition:
{ ModuleMemberList }
ModuleMemberList:
CDeclaration
ModuleMemberDeclaration [ModuleMemberList]
AccessSpecifier : [ModuleMemberList]
AccessSpecifier:
private
public
ModuleMemberDeclaration:
ModuleDeclaration
ParameterDeclaration
PredicateDeclaration
MatchVariableDeclaration
TransitionDeclaration
ParameterDeclaration:
CDeclaration // subset of C/C++ declartions for data member including initial assignments
PredicateDeclaration:
PredicateType PredicateDeclaratorList ; // buffer<int,2> P1, P2(3), P3 << 1;
PredicateDeclaratorList:
PredicateDeclarator
PredicateDeclartorList , PredicateDeclarator
PredicateDeclarator:
PredicateName [ PredicateConstructor ] [ InitArcExpression ]
PredicateName:
Identifier
PredicateConstructor:
( PredicateCapacity )
PredicateTypeDeclaration:
typedef PredicateType Identifier ; // typedef ram<int> TRamInt;
PredicateType:
place [ < PredicateCapacity > ]
PredicateAccessSpecifier < CType [ , PredicateCapacity ] >
PrecicateAccessSpecifier:
buffer
ram
fifo
lifo
fiforam
liforam
PredicateCapacity:
CExpression // subset of C/C++ expressions
TransitionDeclaration:
trans TransitionName [ ( TransitionConstructorList ) ] { TransitionBody }
TransitionName:
Identifier
TransitionConstructorList:
TransitionConstructorAssignment
TransitionConstructorList , TransitionConstructorAssignment
TransitionConstructorAssignment:
TransitionProperty = CExpression
TransitionProperty:
priority
parallel
firetime
life
TransitionBody:
[ [ MatchVariableDeclaration ] { ArcDeclaration } ] [ TransitionAction ]
TransitionAction:
action { CCode } // CCode contains variable declaration and statements including if/else
ArcDeclaration:
PredicateName ArcExpression ; // P >> card(4),x,cond(x>5);
InitArcExpression:
<< Token [ { , Token } ] ;
ArcExpression:
{ InputArcExpression }
{ TestArcExpression }
{ SearchArcExpression }
{ InhibitorArcExpression }
{ OutputArcExpression }
InputArcExpression:
>> [ CardExpression , ] MatchExpression [ , ConditionExpression ] [ , TimeExpression ]
TestArcExpression:
?> [ CardExpression , ] MatchExpression [ , ConditionExpression ]
SearchArcExpression:
?? [ CardExpression , ] MatchExpression [ , ConditionExpression ]
InhibitorArcExpression:
!! [ CardExpression , ] MatchExpression [ , ConditionExpression ]
OutputArcExpression:
<< [ CardExpression , ] Token [ , TimeExpression ]
CardExpression:
card ( CExpression )
MatchExpression:
CExpression
$
_
MatchVariableName
StructuredMatchExpression
StructuredMatchExpression:
{ MatchSubExpression [ , MatchSubExpression ] }
MatchSubExpression:
CExpression
_
MatchVariableName
StructuredMatchExpression
ConditionExpression:
cond ( CExpression )
TimeExpression:
time ( TimeTerm ) // TimeTerm is any term based on the predefined data type time
Token:
SimpleToken
StructuredToken
SimpleToken:
CExpression
$
MatchVariableName
StructuredToken:
{ TokenPart [ , TokenPart ] }
TokenPart:
CExpression
MatchVariableName
StructuredToken
MatchVariableDeclaration:
match MatchVariableName [ { , MatchVariableName } ] ;
MatchVariableName:
Identifier
| 4.2. Distribution functions |
|
Poses++ supports the following functions of distribution. You must include the header file posdistr.h to use these functions:
#include "posdistr.h"
unsigned Pos_Equal (unsigned minValue , unsigned maxValue); // equal distribution between minValue and maxValue unsigned Pos_Normal (unsigned aV, unsigned sD); // normal distribution parametrized by the average value aV and the // standard deviation sD unsigned Pos_LogNormal (unsigned aV, unsigned sD); // logatithmic normal distribution parametrized by the average value aV // and the standard deviation sD unsigned Pos_Exponential (unsigned eV); // exponential distribution parametrized by the expected value eX unsigned Pos_Gamma (unsigned eX, unsigned eC); // gamma distribution parametrized by the expected value eX and // the expected coefficient eC unsigned Pos_Poisson (unsigned eX); // poisson distribution parametrized by the expected value eX. // Pos_Exponential(EX) == Pos_Gamma(EX,1)
| 4.3. Animation functions |
|
Poses++ supports the following functions of animation. You must include the
header file posanim.h to use these functions:
#include "posanim.h" Pos_AnimShow (string Tag, int Show); // Show (Show = 1) or hide (Show = 0) all objects in tag Tag. Pos_AnimCoords (string Tag, float x1, float y1, float x2, float y2); // Set for all objects in tag Tag new values for the coordinates // x1, y1 and x2, y2. Pos_AnimAngle (string Tag, float a); // Set for all objects in tag Tag the new angle a relating to z axis. Pos_AnimAngle (string Tag, float a, float x, float y); // Set for all objects in tag Tag the new angle a relating to z axis // and reference the point x, y. Pos_AnimPos (string Tag, float x, float y, float z); // Set the position of all objects in tag Tag to the point x, y, z. Pos_AnimMove (string Tag, float x, float y, float z); // Move all objects in tag Tag relativ by direction x, y, z. Pos_AnimRotate (string Tag, float a); // Rotate all objects in tag Tag on the the angle a // relating to the z axis. Pos_AnimRotate (string Tag, float a, float x, float y); // Rotate all objects in tag Tag on the angle a relating to // the z axis and the reference point x, y. Pos_AnimScale (string Tag, float x, float y); // Scale up or scale down all objects in tag Tag // for the factors x and y. Pos_AnimScale (string Tag, float x, float y, float px, float py); // Scale up or scale down all objects in tag Tag for the dimension // x, y starting from the origin point px, py. Pos_AnimEdge (string Tag, float r, float g, float b); // Set for all objects in tag Tag the new edge color in // RGB format. Pos_AnimFace (string Tag, float r, float g, float b); // Set for all objects in tag Tag the new face color in // RGB format. Pos_AnimWidth (string Tag, unsigned int Width); // Set for all objects in tag Tag the new line width to Width. Pos_AnimChangeText (string Tag, string Text); // Set for all objects in tag Tag the new text Text. Pos_AnimCmd (string Cmd); // Send the common animation command Cmd // (see also: animation command syntax).
| 4.4. Layout and animation command syntax |
|
Poses++ animation layouts and Poses++ animation commands sent from a simulation server use the following syntax definition:
GlobalCmd : connect host port user password
| stop [step]
| play [step]
| limit [count]
| timewarp [info | value]
| minpos
| mintime
| maxpos
| maxtime
| mode [event | time]
| world Tag (Option)
| camera Tag (Option)
| delete (Tag | Item)
| remote ...
| synchron ["0" | "1"]
WorldCmd : line x1 y1 x2 y2 {xn yn} {Option}
| poly x1 y1 x2 y2 {xn yn} {Option}
| line x1 y1 x2 y2 {Option}
| oval x1 y1 x2 y2 {Option}
| bezier x1 y1 cx1 cy1 cx2 cy2 x2 y2 {xn yn ...} {Option}
| arc x1 y1 x2 y2 a1 a2 {Option}
| text {Option}
| bitmap {Option}
| tag {Option}
| object File Tag {Option}
| type Item
| delete (Tag | Item)
| show (Tag | Item) ["0" | "1"]
| pos (Tag | Item) [x y z]
| move (Tag | Item) [x y z]
| scale (Tag | Item) sx sy [x y]
| angle (Tag | Item) [a [x y]]
| rotate (Tag | Item) [a [x y]]
| edge (Tag | Item) [r g b]
| face (Tag | Item) [r g b]
| width (Tag | Item) [w]
| linestyle (Tag | Item) [LineStyle]
| anchor (Tag | Item) [Anchor]
| coords (Tag | Item) [x1 y1 ... xn yn]
| sector (Tag | Item) [a1 a2]
| bind (Tag | Item) Event [Binding]
| config (Tag | Item) {Option}
| tags Item [Tags]
| items Tag [Items]
| version
| load File
| save File
| update ["0" | "1"]
| all ["tags"]
| enclosed x1 y1 x2 y2
| overlapping x1 y1 x2 y2
| background [r g b]
| foreground [r g b]
| set [Any]
CameraCmd : pos [x y z]
| move [x y z]
| scale [sx sy]
| zoom [zx zy]
| face [r g b]
| anchor [Anchor]
| coords
| bind Event [Binding]
| config {Option}
| world [WorldName]
| scroll [sx sy]
| set [Any]
| window [x1 y1 x2 y2]
| fps [value] // frames per second
Option : -type
| -show ["0" | "1"]
| -pos [x y z]
| -move [x y z]
| -scale sx sy [px py]
| -angle [x y z]
| -rotate [x y z]
| -edge [r g b]
| -face [r g b]
| -width [w]
| -linestyle [LineStyle]
| -anchor [Anchor]
| -coords [x1 y1 ... xn yn]
| -sector [a1 a2]
| -bind Event [Binding]
| -tags [Tags]
| -items [Items]
| -text [Text]
| -font [Font]
| -point [Point]
| -bitmap [Bitmap]
Tags : [+ | -] {Tag}
Items : [+ | -] {Item}
Anchor : {center | left | right | top | bottom}
LineStyle : {solid | dash | dot | dashdot | dashdotdot}
Event : <Idle>
| <Key>
| <MouseMove>
| <LeftButtonUp>
| <LeftButtonDown>
| <LeftButtonDblClk>
| <RightButtonUp>
| <RightButtonDown>
| <RightButtonDblClk>
Key : " " | ... | "~"
| Back
| Tab
| Return
| Escape
| Prior
| Next
| End
| Home
| Left
| Up
Binding : ["+"] BindingCode
BindingVar : %c # CameraName
| %i # Item
| %k # Key
| %w # WorldName
| %x # Mouse-X-Pos
| %y # Mouse-Y-Pos
All animations commands from the simulation server are world commands.
| 4.5. Poses++ Client API |
|
Poses++ components communicate via network using UDP und TCP/IP:
Representation of the Poses++ communication principle
On top of these basic network protocol the implemented communication is based on ASCII commands and answers using TCL as interpreter language. A Poses++ Client uses two kinds of connections:
|
connections to Poses++ daemons and Poses++ shells after a successful login |
|
connection to a Poses++ server tasks |
With the following sequence a client establishs the necessary connections:
| 1. | Detect the machines in a network which actually run a Poses++ daemon with a broadcast to port 1501. All machines with an active Poses++ daemon will answer with theire host name. |
| 2. | Connect a daemon on either the local or a remote machine with a TCP/IP connection to port 1501. On this connection the Poses++ daemon commands are valid. |
| 3. | Login at the daemon connection with the command login account password. Now the Poses++ shell commands are valid on this connection. The shell offers possibilities to build the model code and also to start Poses++ server tasks. Starting a server will answer with the TCP/IP port number the server accuired. |
| 4. | Ask the shell to build the necessary model binary files. |
| 5. | Ask the shell for the running Poses++ server tasks on this machine or use the port number from the server start to establish a TCP/IP connection to the Poses++ server you want to connect. On such a connection the Poses++ server commands are valid. |
| 6. | Connect the Poses++ server to run and observe simulation experiments. |
| 7./8. | Start animation player as a second simulation client which will connect the same simulation server immediately. |
To help you avoiding detailed effort implementing the network communication all necessary
communication routines are implmented in the Poses++ Client API. This is a library
(posclient.dll / libposclient.so) as part of our distribution. You will find it in the
respective binary directory of your Poses++ installation (f.i. .../Poses++ 1.7/bin/x86/Linux).
To use this library in C/C++ you will find a header posclient.h in the include
directory: .../Poses++ 1.7/inc. For developers using Borland's Delphi a
corresponding C to Pascal wrapper unit posclient.pas you will find in: .../Poses++ 1.7/lib.
If requested a Kylix unit should be not a serious problem.
Based on these client tools a client command interpreter (posconsole.exe / posconsole) is also
available in the binary directory of your Poses++ installation. For the commands to handle the
communication please refer to the header a header file posclient.h.
Communication principle
All communication between Poses++ components is string based and follows the TCL
syntax definitions from John K. Ousterhut. Synchronous commands are sent as string
and will receive an answer immediately. Every command will be additionaly receipted
by a constant string either POS_OK or POS_ERROR. The answer result string matches
also the TCP syntax definition. For unexpected (asynchronous) messages the client must
answer to the sending server with a POS_OK unconditionaly. Forgeting this can force
the server waiting for this receipt unlimited. For meanings of errors, warnings and
messages look into an appended table. The simulation server will communicate only
if the client is logged on via Login. A failed login the server will answer by
ejecting the connection - the client will receive a raw socket hangup.
Using the Poses++ Client API the socket communcation including the handling of
the answer result and the constant state strings POS_OK and POS_ERROR will be handled
by this interface itself. You will get the success indication from return values of
the called interface function (for details see: posclient.h).
| 4.5.1. Poses++ console (posconsole / posconsole.exe) |
|
Poses++ console is an application based on the tools belonging to the Poses++ client API. It is a TCL interpreter offering all client API calls as additional TCL commands. It gets the commands from stdin awaiting a newline delimited complete command and hands it over to the evaluter. The evalution results will be "send" to stdout. All commands listed below all also directly accessible via C-call functions declared in posclient.h. These functions are linkable implemented in the shared library libposclient.so or posclient.dll. For every compiler specific posclient.dll an import library is additionally included. So you can either implement your client software based on linked software or on scripts. Because we prefere to use Delphi for front end software development a Delphi command wrapper unit PosClient.pas is included.
| Command | encode string |
| Semantic | encode has the same behaviour like the dstring command of the Poses++ shell. |
| Answer | |
| Example |
| Command | listcodes |
| Semantic | listcode lists the valid error, warning and message entries of the whole Poses++ system. Each entry of this list contains an internally used code number, an identifier and an interpretation string. This command is more a documentation feature than a command. |
| Answer | All registered codes as list. |
| Example |
... {215 POS_CM_NOT_IMPLEMENTED {Server : not implemented yet}} {221 POS_CM_NOT_LOGGED_IN {Server : you are not logged in yet}} ... |
| Command | regcode code [interpretation] |
| Semantic | regcode try to register a new error or message code & interpretation combination. |
| Answer | "1" if successful "0" otherwise |
| Example | regcode MY_OWN_ERROR "my own error: %1" will answer "1" where %1 will be replaced on interpretation with an actual string value for the place holder "%1". |
| Command | code2txt code [arguments] |
| Semantic | the error identifier will be searched and if found the interpretation string will be filled by the given arguments. |
| Answer | a string with the exchanges place holders. |
| Example | code2txt MY_OWN_ERROR abc will produce "my own error: abc" if registered like above. |
| Command | idle |
| Semantic | idle performs idle tasks like receiving and dispatching asynchronous events and so on. Please call idle or Pos_Idle() from a central point of your application if no more user driven events are pending and continue calling idle or Pos_Idle() until it answers TRUE (1) for "idle - nothing to do anymore". |
| Answer | TRUE: "1" for "idle - nothing to do anymore" otherwise FALSE "0". |
| Example |
| Command | hostname |
| Semantic | hostname will reply the name of the host posconsole is running on. |
| Answer | |
| Example |
| Command | username |
| Semantic | username will reply the name of the current user acount posconsole is running in. |
| Answer | |
| Example |
| Command | name2addr host_name |
| Semantic | name2addr will reply an ip address for the given host name. |
| Answer | |
| Example | name2addr merkur could produce "192.168.1.10". |
| Command | addr2name |
| Semantic | addr2name will reply a host name for the given ip address. |
| Answer | addr2name 192.168.1.10 could produce "merkur" |
| Example |
| Command | long2addr unsigned_long_integer |
| Semantic | long2addr will reply an ip address for the given binary representation. |
| Answer | |
| Example | long2addr 16777343 would produce "127.0.0.1". |
| Command | addr2long |
| Semantic | addr2long will reply an integer value representation for the given ip address. |
| Answer | addr2long 192.168.1.10 would produce "167880896" |
| Example |
| Command | ipaddrs |
| Semantic | ipaddrs will reply the count of found ip addresses of installed network adapters. |
| Answer | With one real adapter and one loopback interface ipaddrs will reply "2" |
| Example |
| Command | ipaddr index |
| Semantic | ipaddr will reply the ip of the adapter referenced by index. To get the maximum valid index use ipaddrs. |
| Answer | With one loopback interface ipaddr 0 can reply "127.0.0.1" |
| Example |
| Command | ipmask index |
| Semantic | ipmask will reply the ip network mask of the adapter referenced by index. To get the maximum valid index use ipaddrs. |
| Answer | With one loopback interface ipmask 0 can reply "255.0.0.0" |
| Example |
| Command | findipaddr ip_address |
| Semantic | findipaddr will search the installed adapters without the loopback interface for the requested ip_address and will reply "1" if found otherwise "0". |
| Answer | findipaddr 192.168.1.10 can reply "1" if one adapter is setup to this ip address. |
| Example |
| Command | macaddrs |
| Semantic | macaddrs will reply the count of found mac addresses of installed network adapters. |
| Answer | With one real adapter macaddrs will reply "1" |
| Example |
| Command | macaddr index |
| Semantic | macaddr will reply the mac address of the adapter referenced by index. To get the maximum valid index use macaddrs. |
| Answer | With one real interface macaddr 0 will reply a typical mac address string. |
| Example |
| Command | broadcast message_string port [timeout_milliseconds] |
| Semantic | broadcast sends message_string as broadcast to port into the local network and awaits for timeout_milliseconds replied answers. These answers will be collected in a list of tupels with the repliers ip address and the replied string. |
| Answer | The answer is a list. Every list entry is a tupel with ip_address and answer_string. |
| Example | broadcast hello 1501 generated in my environment an answer list of "{192.168.1.9 spion} {192.168.1.10 merkur}" |
| Command | profiling [boolean_value] |
| Semantic | profiling will request or set the state of transition profiling to analyse and optimize models. |
| Answer | The answer is a boolean value. |
| Example |
| Command | daemons [timeout_seconds] |
| Semantic | daemons inspects the local network and reports about all running Poses++ daemons. Without the timeout parameter a default value will be used. |
| Answer | The answer is a list. Every list entry is a tupel with ip_address and host_name. |
| Example | daemons produced in my environment "{192.168.1.9 spion} {192.168.1.10 merkur}" |
| Command | connections |
| Semantic | connections will report a list of the active socket connections. |
| Answer | a list of integer values representing the connections |
| Example |
| Command | connect host_or_ip_address port [timeout_seconds] |
| Semantic | connect will try to establish a TCP/IP connection to the given host and port. In result you will receive an integer value as handle useful for the following communication commands. |
| Answer | an positive integer connection handle or "0" if the connection could not be established. |
| Example | connect spion 1501 120 will try to connect a Poses++ daemon listening at port 1501 on the machine with the name spion. For this command I got a "76" on my notebook. |
| Command | timeout connection_handle [timeout_seconds] |
| Semantic | timeout will try to change or only to reply the timeout settings of a given connection. |
| Answer | the timeout setting of the requested connection as integer. |
| Example |
| Command | disconnect connection_handle |
| Semantic | disconnect destroys the connection with the given handle. |
| Answer | "1" if successful and "0" otherwise |
| Example |
| Command | active connection_handle |
| Semantic | active asks whether a connection is still active or not. |
| Answer | "1" if the connection is still active and "0" otherwise |
| Example |
| Command | send connection_handle string |
| Semantic | send will send the given string to the other side represented by the connection handle. The C-implementation offers a raw send function too. This could be used to transfer binary data. |
| Answer | "1" if successful and "0" otherwise |
| Example |
| Command | receive connection_handle |
| Semantic | receive waits blocking on the connection until a timeout occures to receive a string. |
| Answer | The answer is the received string. |
| Example |
| Command | command connection_handle command_string_with_arguments |
| Semantic | command sends the given argument following the connection handle to the connection refered by the handle. After this it awaits an answer as reply. So you can treat this command as a combination of send and receive. |
| Answer | The answer is the received string. |
| Example |
| Command | incmd connection_handle |
| Semantic | incmd will reply a boolean answer to indicate either a command is actually in progress or not. |
| Answer | The answer is a boolean value as string. |
| Example |
| Command | mirror connection_handle path_name mask_list [tcl_callback_proc] |
| Semantic | mirror is a complex command to ensure that the server side will have an updated mirror of the client project files before compiling a model. All files in path_name and its subdirectories will be mirrored to the server side if the filename matches to one of the entries of mask_list. If a tcl_callback_proc is given it will be called after every copied file. |
| Answer | The answer is a boolean value as string. |
| Example |
| Command | lastcmd |
| Semantic | lastcmd will reply the last called command. |
| Answer | The answer is a command string. |
| Example |
| Command | timevalid time_string [timeunit] |
| Semantic | timevalid will reply a boolean answer if the given time_string is valid in conjunction with the optional timeunit. |
| Answer | The answer is a boolean value. |
| Example |
| Command | timeformat time_string [timeunit] |
| Semantic | timeformat will reply a formated simulation time representation if the given time_string is valid in conjunction with the optional timeunit. |
| Answer | The answer is a string with a formated time. |
| Example |
| Command | pertimeformat value [timeunit] |
| Semantic | pertimeformat will reply a formated value per time representation for the given value in conjunction with the optional timeunit. |
| Answer | The answer is a formated string. |
| Example |
| Command | trace [integer_value] |
| Semantic | trace asks for the client trace level represented by an integer value greater or equal. Zero means the lowest trace level. With the optional parameter the action trace level will be changed and replied afterwards. Trace informations will be stored as ascii messages in .../var directory f.i. as posclient.log and/or posconsole.log. |
| Answer | A integer value greater or equal zero representing the actual trace level |
| Example | For the lowest trace level a 0 will be replied. |
| Command | version [all] |
| Semantic | version will reply a string indicating the major.minor release of the client interface. With the optional parameter all more detailes will be replied in form of major.minor.patchlevel date copyright. |
| Answer | The answer is a formated string. |
| Example | version all will produce an answer like: 1.7.5 09/07/2006 {copyright 1996..2006, GPC mbH all rights reserved} |
| Command |
licence [alive] licence info licence info category licence info properties licence info licensee licence info mac licence info name licence info primary |
| Semantic | licence is an information command to be able to request details about licence entries. The answers will be generated be the locally running licence daemon posppld. |
| Answer |
|
| Example |
| Command | onevent connection_handle event_key [tcl_command [leading_command_arguments]] |
| Semantic |
In some cases the Poses++ server will send
informations asynchronously. To catch such messages representing errors, warnings und mere messages you can set an onevent reaction. connect_handle identifies the connection for the event catcher to be registered. key identifies the leading string of an asynchronously received information and tcl_command is a string matching a registered tcl command to be called. |
| Answer | |
| Example |
onevent 5 Event EventHandler will try to perform the following
tcl call (similar to the C-callback) when the event
"Event message POS_CM_MODEL_CLOSED" occures: "EventHandler {Event message POS_CM_MODEL_CLOSED}". A bit more useful would be onevent 5 Event {EventHandler 5}. This event handler would be called with: "EventHandler 5 {Event message POS_CM_MODEL_CLOSED}" and so the catching procedure has the responsible connection handle as additional information. If tcl_command was not specified an already registered event would be cleared. |
| 4.5.2. Poses++ daemon (posppd / posppd.exe) |
|
The Poses++ daemon is a small application making a machine available as
Poses++ server machine. The first started daemon opens a TCP/IP listening
end point on port 1501. This is the port where client connections will be accepted.
Accepting a new connection the daemon will fork itself into a mirrored task dealing
with this new connection only so different deamon connections can not effect each
other directly. After a login at the connection of this child deaemon
process the daemon will morph into a Poses++ shell offering a wider range
of commands and variables.
The central daemon acts additionally as a small central data base (f.i. to keep
a list of actually running Poses++ server tasks). For this it uses the TCP/IP and
the UDP port 1502 for internal purposes.
Under MS-Windows you will see a task bar icon on the desktop identifying a running
daemon.
The Poses++ daemon is not a TCL interpreter even if the command interface
seems to be identical.
| Command | version |
| Semantic | A client asks for the version f.i. to avoid conflicts with it's own version |
| Answer | A string indicating the major.minor release of the connected daemon |
| Example | 1.7 |
| Command | login account password |
| Semantic | A client try to login. After a susccessful login the daemon hands the actual connection over to a Poses++ shell. |
| Answer | - |
| 4.5.3. Poses++ shell (possh / possh.exe) |
|
A Poses++ shell is a TCL-interpreter with additional commands like listed below. Just started the Poses++ shell loads the TCL-script possh.tcl from the directory .../Poses++ 1.7/etc. There you can find additional commands implemented in script form. The Poses++ shell is an interface to handle different operating systems transparently. The Poses++ shell commands are available on a TCP/IP connection to a Poses++ daemon after a successful login.
The following commands are additionnal build in commands besides the common TCL command set:
| Command | execute executable [argument_list] |
| Semantic | if not to avoid you can necessarily call execute instead of tcl's original exec for the execution of a binary. The first argument ist the binary file. The stdout from the executed program will be caught into the result of the command. |
| Answer | the result of the system command as string. |
| Example |
| Command | invoke executable [argument_list] |
| Semantic | also: if not avoidable you can not avoid you can necessarily call invoke instead of tcl's original exec for the execution of a binary. The first argument ist the binary file. This command routes the stdout from the executed program. |
| Answer | - |
| Example |
| Command | is83fs path_or_file_name |
| Semantic | checks the filesystem of the path given as argument for 8.3 filename behaviour. |
| Answer | 1 if a 8.3 filesystem was detected, 0 otherwise |
| Example |
| Command | hardware |
| Semantic | ask for the hardware the Poses++ shell is running on. |
| Answer | x86 or x86_64 for an Intel x86 processor or compatible, alpha for an Alpha processor (former on DEC-Workstations), sparc for a Sparc cpu. |
| Example |
| Command | osname |
| Semantic | ask for the operating system the Poses++ shell is running on. |
| Answer | Linux for Linux, win32 for one of the Microsoft Windows operating systems, OSF1 for an OSF1 on an Alpha workstation and SunOS for SunOS or Solaris on a Sparc workstation. |
| Example |
| Command | usrname |
| Semantic | ask for the account or the user name the Poses++ shell is running under. |
| Answer | the login name as string. |
| Example |
| Command | hostname |
| Semantic | ask for name (host name) of the machines the Poses++ shell is running on. |
| Answer | the machines name as string. |
| Example |
| Command | newlinetxt string_arguments |
| Semantic | converts all DOS end of line sequences (0x0D0A) in the given arguments into UNIX like "\n" eol chars. |
| Answer | the given arguments with converted newline chars as one string |
| Example |
| Command | writeln string |
| Semantic | The TCL-command puts stdout ... will not be successful on all operating systems supported by Poses++. Especially MS-Windows 95 and 98 have no behaviour to inherit stdout to child processes. Thats why writeln offers the possibility to write out its arguments. |
| Answer | - |
| Example |
| Command | writeln_str string |
| Semantic | acts similar as writeln converting the arguments via dstring before. |
| Answer | |
| Example |
| Command | filename file_name_parts |
| Semantic | this command treats the given arguments as "space" separated parts of a filename and convets them to a formal valid filename using slashes as deviders. |
| Answer | the converted filename as string |
| Example | filename c:\abc\ will convert to c:/abc |
| Command | quoted string |
| Semantic | this command will frame the given arguments in quotas containing the arguments space spearated. A call with one argument only will do the same if the argument by itself contains dividing spaces. |
| Answer | the collected arguments as one string |
| Example | quoted a b c will produce "a b c" but quoted {a b c} will produce "a b c" too. |
| Command | path operation [arguments] |
| Semantic |
This is a command dealing with lists of file paths. The dividing chars are ':'
under UNIX and otherwise ';'. The char ':' is used under UNIX to separate paths
in environment variables and the char ';' is not part of path names under MS-Windows. The second argument is one of the sub commands split path_list, append path_list new_element, append_sys path_list new_element, exist path_list and valid path_list. |
| Answer |
path split will divide the given arguments by the system specific dividing
char and will answer with a TCL-conform list of the contained path elements. path append will extend the given list by the new element using the dividing char. path append_sys will extend the given list by the new element using the dividing char. But the new element is converted to a correct path string valid on the current operating system before. path exist counts the really existing paths from the given list and will answer with an integer result. path valid will answer with a path list as a string containing only those paths from the given argument which would be counted by path exist. |
| Example |
assuming the Poses++ shell is running under a MS-Windows system: path split {c:/ba;d:/cda} will answer "c:/ba d:/cba". path append c:/ba d:/cda will answer "c:/ba;d:/cda". path append_sys c:/ba d:/cda will answer "c:\ba;d:\cda". path exist {c:/windows;c:/temp;c:/___} will typicaly answer "2" because c:\windows and c:\temp mostly exist unlike c:\___ . And on the same system path valid {c:/windows;c:/temp;c:/___} would answer "c:/windows;c:/temp". |
| Command | which file_name |
| Semantic |
show full path of commands: which progname ... like the UNIX command the PATH environment variable will be searched. All arguments after progname will be treated additionaly as paths to be searched. |
| Answer | the full path name of the program if found |
| Example |
assuming running under Linux: which gcc could answer "/usr/bin/gcc". |
| Command | uname [options] |
| Semantic |
like the UNIX command uname prints certain system information. Without option, same as -s.
|
| Answer | the answer is identical to the answer of the corresponding UNIX command. Under MS-Windows the operating system will reply win32. |
| Example |
my Dell Inspiron 8000 with MS-Windows ME answered: win32 MERKUR 4.90 73010104 i586 intel to uname -a |
| Command | searchreg mainkey key subkey |
| Semantic | searchreg mainkey key subkey searches the MS-Windows Registry for a matching entry. mainkey is valid with one of the values: HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS. key and subkey are strings matching the registries hierarchy. |
| Answer | A found entry or the result of the Windows-API call RegQueryValueEx(...) as string. |
| Example |
searchreg HKEY_LOCAL_MACHINE SOFTWARE\Microsoft\VisualStudio\6.0\Setup VsCommonDir answered on my machine: "C:\Programme\Microsoft Visual Studio\Common" |
| Command | ctime |
| Semantic | ctime generates the string output from the C-library call ctime(...). |
| Answer | a string with actual date and time. |
| Example | ctime produces f.i. "Tue Oct 22 21:24:31 2002" |
| Command | mkdir new_path_name |
| Semantic | mkdir creates similarily to UNIX a new leaf in the path hirarchy according the given argument. |
| Answer | the answer is an error if the branch of the leaf of the given path hirarchy does not exist. |
| Example |
| Command | makepath new_path_name |
| Semantic | makepath also creates a new directory. But additionally to mkdir it creates a missing branch directory first. |
| Answer | |
| Example |
| Command | unlink path_or_file_name |
| Semantic | unlink deletes a file or a directory given in the first argument. It acts similar to the C-library call unlink(...). |
| Answer | |
| Example |
| Command |
cp source_file_name destination_path_or_file_name copy source_file_name destination_path_or_file_name |
| Semantic | cp or copy will copy a file to a destination file or path similar to the cp command in a UNIX shell or the copy command in a DOS-box. |
| Answer | |
| Example |
| Command | listdir [directory] [-verbose] [-join] |
| Semantic | listdir will generate a list of files and directories contained in the requested directory. If no directory was requested the contents of the current directory will be listed as answer. In case of option -verbose or just -v for each entry found in the directory will be answered not only the single file name but a tupel of three parts: {name type access}. In this case name is the file name type is the type of this file as a short string with the letters f for simple file d for a directory and l for a link and access is also a short string with the letters r for readable w for writable and x for executable. With the option -join or just -j you can set the delimiter string for the list of file name and the tupels. |
| Answer | The answer is a list. |
| Example |
listdir will answer in a Poses++ root directory: . .. licence.txt readme.txt html lib bin inc etc examples changes.txt var listdir -v called in a fat32 file system will answer: {. d rwx} {.. d rwx} {licence.txt f rwx} {readme.txt f rwx} {html d rwx} {lib d rwx} {bin d rwx} {inc d rwx} {etc d rwx} {examples d rwx} {changes.txt f rwx} {var d rwx} |
| Command | dirname path_or_file_name |
| Semantic | dirname processes the given argument as path or file name and extracts its parent directory. |
| Answer | the answer is the parent directory as string. |
| Example | dirname a/b/c will answer a/b. |
| Command | ishostaddr host_addr |
| Semantic | ishostaddr checks whether the argument is a valid ip address of the local system or not. |
| Answer | "1" if the ip addres belongs to an available interface. "0" otherwise. The local host address 127.0.0.1 will produce "0". |
| Example |
| Command | daemon command |
| Semantic | daemon routes the given argument as command to the Poses++ daemon running on the same machine. |
| Answer an answer is the answer of the daemon. | |
| Example | "daemon version" answers like the version command of the daemon. |
| Command | getserver |
| Semantic | This command is routed to the daemon. see: getserver |
| Command | version |
| Semantic | This command is routed to the daemon. see: version |
| Command | trace [integer_value] |
| Semantic | trace asks for the shells trace level represented by an integer value greater or equal. Zero means the lowest trace level. With the optional parameter the action trace level will be changed and replied afterwards. Trace informations will be stored as ascii messages in .../var directory f.i. as possh.log. |
| Command | pospp |
| Semantic |
pospp [-verbose]
[-port listen_port_number]
[-logfile logfile_name]
[-alias server_alias_name]
[-send_socket_to caller_udp_port]
[-user user_name]
starts a new Poses++ server task. This server task will avoid output to standard out with option -verbose. It will establish a listening socket port at -port listen_port_number or at a free port number to accept incoming TCP/IP connections. If requested with -logfile logfile_name it will create this logfile to log all client communication. The option -alias server_alias_name referes to the details of the daemon command getserver. With option -send_socket_to caller_udp_port the new Poses++ server will send its listening port as string via an UDP packet to the caller_udp_port at the same machine. -user user_name specifies the user account name the Poses++ server should be running under. The server will fail if it can detect another user name from the systems API. |
| Answer | the answer is the port number of the established listening socket port as string. |
| Example |
| Command | mirrorfile clientDir fileName fileSize ... |
| Semantic | This command allows to transfer a binary file from a client to the server system. Depending from the project directory and the file name the server decides the path the files mirror at server side. fileSize is the size of bytes to be transfered. This is the command part completed by a UNIX newline. After this delimiting character the command expects the byte stream for the file. |
| Answer | |
| Example |
| Command | type ascii_file_name |
| Semantic | This command produces the contents of the given file as result. |
| Answer | The contents of the file as string. |
| Example |
| Command | faccess path_name |
| Semantic | faccess examines the creation time in seconds a file created in the given directory would have. |
| Answer | the seconds as string |
| Example | faccess c:/windows produced on my machine: 1035626476. |
| Command | flock filename/descriptor read/write TRUE/FALSE |
| Semantic |
flock can set or reset file locks. It distinguishs read and write
locks. A file locked by a read lock is locked for reading only. It can be locked by
other read locks but never by a write lock. A file locked by a write
lock can't be locked neither by another read nor by another write lock. It
is locked exclusively. The command is implemented using the C-library call fcntl(...) under UNIX. Under Windows the lock functionality is implemented using the call sopen(...) parametrized by the flags SH_DENYWR, O_RD_ONLY, O_RDWR | O_APPEND. To set a lock you have to specify the name of the file to be locked, the kind of lock and TRUE. You will get back an integer descriptor which you should use later to reset the lock with flock descriptor read/write FALSE. The Poses++ shell and the Poses++ server use flock internally to avoid conflicts during the generation of model binary files which are already loaded into memory by a running simulation server. |
| Answer | The answer is an integer handle. "-1" will be the answer if the function failed. |
| Example | My system under Linux answered to flock /etc/hosts read TRUE with "3". With flock 3 read FALSE I cleared the lock. |
The following commands are implemented in the TCL script file possh.tcl.
For details please study the script source which is placed in .../Poses++ 1.7/etc directory of
your installation:
| Command | serverProjectDir |
| Semantic | serverProjectDir replies the directory name in the .../Poses++ 1.7/var path of the installation where the Poses++ server side will hold mirror files and binaries. If force is set the directory will be created if not yet existent. |
| Command | modelLibrary |
| Semantic | modelLibrary replies the name and the full path of the binary model code the Poses++ server side would create on build. The second and the third part of the answer are integer values to be interpreted as boolean ones. The second indicates whether the model library file already exists or not and the third indicates an uptodate state of this library file. If not uptodate it should be rebuild next because of corresponding source files were changed since last model library build time. |
| Command | needMirror |
| Semantic | needMirror checks the necessity to mirror files between client and server side. It is not necessary to mirror files if the server side can detect direct access to the clients file system. This detection takes different mount structures of local and/or remote file systems for both sides in consideration. |
| Command | prepareMirror |
| Semantic | prepareMirror lists every file name from the entries in fileRecords which should be mirrored to become upto date at server side. |
| Command | build |
| Semantic | build or make the model shared binary code. This is the shared library (*.so) or a DLL (*.dll) which full path name would be replied by the command modelLibrary. This command uses the selected C++ compiler internally. |
| Command | install |
| Semantic | install checks and stores all necessary information about the selected C++ compiler. This for a posshrc file will be stored in the .../Poses++ 1.7/var/user directory. The name of the file is completed by a .hostname.hardware.osname extension specifying clearly the system this file is valid for. This file name principle allows different setup files for different machines or operating systems in the same installation hierarchy. The setup file contains all informations as TCL commands. |
| Command | setup |
| Semantic | setup loads the informations about the C++ compiler stored by install. |
Not as a command but as arrays poses, globals and the variable CC you can get various detailed informations from the shell.
| 4.5.4. Poses++ server (pospp / pospp.exe) |
|
A Poses++ server is the task performing the calculation for a simulation experiment.
On one machine can run as much different Poses++ server tasks as you want. Each of
them will communicate over another TCP/IP port which will be typically acquired from free
available ports during the servers the tart up phase of the server A simulation server will
be invoked by the Poses++ shell.
A client can connect a Poses++ server via a TCP/IP socket to a port which
the client can inspect by a getserver request. The
Poses++ server activates a new and so independent TCL-interpreter for each
connected client. The following commands are available on this interface:
| Command | login user_name password |
| Semantic | login try to authenticate the connection for the specified user_name with the given password. Without successful authentication the most commands will not be acepted. After the third failed login retry the server will destroy the client connection. |
| Answer | |
| Example |
| Command | logout |
| Semantic | logout initiates the destruction of the client connection. |
| Answer | |
| Example |
| Command | exit |
| Semantic | exit has the same behaviour like logout. |
| Answer | |
| Example |
| Command | trace [integer_value] |
| Semantic | trace asks for the actual server trace level represented by an integer value greater or equal. Zero means the lowest trace level. With the optional parameter the action trace level will be changed and replied afterwards. Trace informations will be stored as ascii messages in .../var directory f.i. as pospp.log. |
| Answer | The trace level as an integer value. |
| Example |
trace will be answered with: 0. trace 3 will be answered with: 3 and
the amount of trace informations stored in the corresponding log file will increase
rapidly. |
| Command | version |
| Semantic | version asks for the server version string. |
| Answer | The version as a string description. The leading characters: "Poses++ server - version " will not change in later releases to enable a formal version number scan. |
| Example |
version will be answered with: "Poses++ server - version 1.5 p2 - copyright (c) GPC mbH (Germany), 1996..2003" when the server is of version 1.5 and has reached the second patch level. |
| Command | listdir [directory] [-verbose] [-join] |
| Semantic | listdir will generate a list of files and directories contained in the requested directory. If no directory was requested the contents of the current directory will be listed as answer. In case of option -verbose or just -v for each entry found in the directory will be answered not only the single file name but a tupel of three parts: {name type access}. In this case name is the file name type is the type of this file as a short string with the letters f for simple file d for a directory and l for a link and access is also a short string with the letters r for readable w for writable and x for executable. With the option -join or just -j you can set the delimiter string for the list of file name and the tupels. |
| Answer | The answer is a list. |
| Example |
listdir will answer in a Poses++ root directory: . .. licence.txt readme.txt html lib bin inc etc examples changes.txt var listdir -v called in a fat32 file system will answer: {. d rwx} {.. d rwx} {licence.txt f rwx} {readme.txt f rwx} {html d rwx} {lib d rwx} {bin d rwx} {inc d rwx} {etc d rwx} {examples d rwx} {changes.txt f rwx} {var d rwx} |
| Command | status |
| Semantic | status asks the server to inform about its actual situation. It will answer with the same details like on an asynchronous "Event status ..." message. For details see: Poses++ server events. |
| Answer | The status as a short string. |
| Example |
| Command | link_code library_file_name |
| Semantic | link_code asks the simulation server to link the given file as shared code dynamically against itself. This will be done internally by the API-call LoadLibrary under Windows and via dlopen unter Unix. During this load step the specific registration function in the shared code will register classes and functions to the server so it is able to deal with binary model code afterwards. |
| Answer | |
| Example |
| Command | linked_code |
| Semantic | linked_code asks the server to generate a report about all dynamically linked shared model code files. |
| Answer | The answer is a list of all file names of the shared libraries linked dynamically against the simulation server in result of the command link_code. |
| Example |
| Command | unlink_code [library_file_name] |
| Semantic | The simulation server will check any dependencies of its loaded symbols from the specified library file. If no dependendies are detected the server will release the loaded shared code. If not parameter is given the server will try this behaviour with all loaded libraries. |
| Answer | |
| Example |
| Command |
open_stream file file_path openmode open_stream socket host_name port |
||||||||||||
| Semantic |
open_stream can open a file stream at server side. openmode is one of the following short strings with the listed meaning:
|
||||||||||||
| Answer | The answer is an integer stream handle useful as parameter for the following stream commands. | ||||||||||||
| Example |
| Command | read_stream stream_handle [maximum_bytes] |
| Semantic | read_stream will read from an already opened stream refered by the stream_handle. If maximum_bytes is specified it will never read more characters. The next call to read_stream will continue on this point. |
| Answer | The answer is a string filled with the read characters. |
| Example |
| Command | write_stream stream_handle string |
| Semantic | write_stream will try to write the given string to an already opened stream refered by stream_handle. Poses++ uses the write_stream and read_stream command internally f.i. for storing and reloading simulation states to file and backward. |
| Answer | |
| Example |
| Command | close_stream stream_handle |
| Semantic | close_stream will close an already opened stream refered by stream_handle. |
| Answer | |
| Example |
| Command | timeunit [system] | ||||||||||||||||||
| Semantic | timeunit asks the server for the time unit the simulation time tics are based on or in case of an additional system option the time unit of the system time. | ||||||||||||||||||
| Answer |
The answer can be one of the following short strings:
|
||||||||||||||||||
| Example |
| Command | randomstart [integer_value] |
| Semantic | randomstart will set the random start value to integer_value if the parameter was supplied and no simulation activities happened upto this time. |
| Answer | The answer is the valid random start value of the simulation server. If you set this value in a next experiment with the same model you can force the same random behaviour. |
| Example |
| Command | information |
| Semantic |
this command allows to request information about data types, instances and other stuff too.
|
| Answer |
|
| Example |
| Command | model |
| Semantic | model requests the name of the top module called model. To get informations about its member either inspect the type informations or request details with getmodules, getplaces and gettransitions |
| Answer | |
| Example |
| Command | getplaces module_instance_handle | module_full_name | module_type [handles | names | both] |
| Semantic | The command getplaces will reply a list of place (or predicate) names contained in the specified module. If you refered an existing module instance you can complete the command with an optional parameter of handles, names or both. With handles you will receive a list of the correspondig instance handles instead of the names. With names you will get the names what is the default behaviour. With both you will get a tupel for each entry with name and handle of the place. |
| Answer | |
| Example |
getplaces airport.TaxiWay1 both: {Input 7} {Output 13} |
| Command | gettransitions module_instance_handle | module_full_name | module_type [handles | names | both] |
| Semantic | The command gettransitions acts similar to getplaces but will reply transition related informations instead. |
| Answer | |
| Example |
| Command | getmodules module_instance_handle | module_full_name | module_type [names | types | handles | owner] |
| Semantic | The command getmodules will reply a list for all module instance members included in the module instance or module type specified as command parameter. For each of these member entries you will get {member_name member_type boolean_value}. The boolean value is "0" if the module is not owner of this member. This means such a member is overloaded by module construction and so a reference to another member in another module instance. In case of using the optional parameters names, types, handles and owner the answer will be constructed as a list of tupels of a modules name, its data type and its instance handle and the handle of the owner sorted by the request order. order. |
| Answer | |
| Example |
| Command | getparameters module_instance_handle | module_full_name | module_type [names | types | both] |
| Semantic | The command getparameters will reply a list of all parameter members in the specified modules. Parameters are all ordinary members not being modules, places or transitions. With the optional parameter types you can request to get only a list of the data types of the parameters. With the parameter both you will request a tupel of instance name and instance type of every parameter member. |
| Answer | |
| Example |
getparameters airport.TaxiWay1 both: {RollTime time} |
| Command | parameter module_instance_handle | module_path | parameter_path [new_value_string] |
| Semantic | parameter is a request to get the actual value of a parameter or to change this value with new_value_string as new settings. With module_instance_handle and module_path all parameters inside the module structure can be requested and will be answered as one structured result string. |
| Answer | |
| Example |
| Command | simtime new_time |
| Semantic | simtime requests the actual simulation time. |
| Answer | The simulation time is an integer representing the amount of time tics happen for the model up to now. The meaning of one tic depends on the valid timeunit. If a new time value is specified and this value is later than the simulation time the time can be increased. Please handle this behaviour carefuly. Such a time jump will effect you statistical results. Already pending events for times inbetween will fire too late. |
| Example |
| Command | systime |
| Semantic | Beginning with Poses++ 1.7 systime will reply the elapsed time in micro seconds since start of the requested Poses++ server. Before it was the system time of the running operating system in micro seconds since 00:00:00 UTC 01/01/1970 and so in risk of overlows. |
| Answer | |
| Example |
| Command | sysdate |
| Semantic | sysdate will answer the actually reached time of the running operating system in a string fromat. |
| Answer | |
| Example |
sysdate answered: Sat Nov 09 14:28:04 2002 |
| Command | timewarp [new_value] |
| Semantic | timewarp reports a factor used to compress or to stretch the simulation time progress in relation to the real time. 0 means run the experiment as fast as possible. Between 0 and 1 means run in "quick-motion". 1 means run the experiment in real time. All over 1 means an experiment speed in "slow-motion". A given new value will be set before and will effect a running experiment immediately. |
| Answer | |
| Example |
| Command |
gethistory place | trans | arc handle_or_instance_path [from_time to_time] [attribute] gethistory place | trans | arc handle_or_instance_path average delta_time [from_time to_time] gethistory place | trans | arc handle_or_instance_path difference delta_time [from_time to_time] |
| Semantic |
gethistory will report a history sequence stored for the specified instance. The first form of the command will accept an attribute. In this case the time dependent changing attribute values will be reported instead of the default token or fire counts. The command variants with average and difference will report calculated curves. |
| Answer |
If the instance is a place the sequence will be:
time_value_1 token_count_1 ... time_value_n token_count_n. If the instance is a trans or an arc the sequence will be: time_value_1 parallel_fire_count_1 ... time_value_n parallel_fire_count_n. |
| Example |
gethistory place airport.RunWay.RunWay reported : 366 1 376 0 446 1 490 0 540 1 564 0 |
| Command | capacity handle_or_instance_path [new_value] |
| Semantic | capacity reports the actual place (or also: predicate) capacity of the specified instance. If a new value is given the simulator will try to change the capacity first. This could fail if the given capcacity is lower than necessary. The capacity in minimum necessary depends from the actual token count and from already pending data flow events. |
| Answer | The answer for capacity is an integer value. |
| Example |
| Command | tokencount handle_or_instance_path |
| Semantic | tokencount will report the actually contained amount of tokens in a predicate. |
| Answer | The answer is an integer value. |
| Example |
| Command | priority handle_or_instance_path [new_value] |
| Semantic | priority reports the actual priority of the specified transition instance. If a new value is given the priority will be changed first. A priority value is a signed integer value. A lower value means a lower priority. The default priority of a transition without any specifications is 0. |
| Answer | |
| Example |
| Command | parallel handle_or_instance_path [new_value] |
| Semantic | parallel reports the actual maximum parallel fire count allowed for the specified transition instance. If a new value is given the parallel will be changed first. A parallel value is an unsigned integer value greater 0. |
| Answer | |
| Example |
| Command | life handle_or_instance_path [new_value] |
| Semantic | A transition with life equal to 0 will never fire independent from the data situation arround. The new value is of a boolean type. |
| Answer | |
| Example |
| Command | future |
| Semantic | future will report all pending events from the event list. |
| Answer |
The answer is a list of all events. Every entry is leaded by a spedifier defining the kind of event:
|
| Example |
{DATAPUTFLOW 592 airport.Animation.Steps airport.Animation.DoOneStep.Arc1 1 {{Airplan9 {} RB 1 35 21 {0 -17.14286 0 0}}}} This data flow event will happen at 592 tics. It will put 1 token into airport.Animation.Steps. This event was generated by the arc airport.Animation.DoOneStep.Arc1. |
| Command |
eventmask message | time | status [boolean_value] eventmask protocol alias_string protocol_handle cause_list instance_handle_list [break] eventmask protocol alias_string_list boolean_value eventmask animation alias_string boolean_value |
| Semantic | With eventmask the asynchronous events the client wants to receive can be specified. The events which can occure are described in Poses++ server events. In case a cause for an event has to be specified look at getcauses for details: |
| Answer |
|
| Example |
| Command |
onevent [level update_level] cause_list tcl_script onevent [level update_level] cause_list [place | trans | arc] instance_handle_or_path_list tcl_script onevent event_handle_list [[[place | trans | arc] instance_handle_or_path_list] boolean_value] onevent event_handle_list [[place | trans | arc] instance_handle_or_path_list] trigger onevent event_handle_list tcl_script [boolean_value] onevent event_handle_list delete |
| Semantic |
With onevent a client can specify script reactions to asynchronous events.
The events which can occure are described in Poses++ server
events. With level update_level can be specified down to which
updatelevel the event will be invoked. Default level is the same
like default for updatelevel. An event specified with level N will
not be triggered in case of updatelevel is set less N.
In case a cause for an event has to be specified look at
getcauses for details. During the script evaluation invoked by an event
additional global tcl variables are available:
|
| Answer |
|
| Example |
| Command | protocol place | trans | arc attribute_list |
| Semantic | With protocol a list of attributes can be specified to use the integer handle replied in the command eventmask for asynchronous reactions. Valid attributes can be requested via the command getattributes. |
| Answer The answer is an unique integer handle. | |
| Example |
| Command |
attributes [module | place | trans | arc] instance_handle_list attribute_list [cause] attributes [module | place | trans | arc] instance_handle_list protocol_handle [cause] attributes [module | place | trans | arc] instance_handle_list attribute_list value_list |
| Semantic | With attributes a list of actual values of instances attributes can be requested. To get all valid attributes you can use the command getattributes. In case of refering a protocol handle the list of attributes has to be registered by the command protocol before. Foreach single instance from instance_handle_list an attribute value list will be replied. With the optional parameter cause attributes can be called as reaction to an internal event handler to allow the reply of the actual cause for this occuring event. The call case when attribute_list is followed by a value_list offers the possibility to change the actual value of an attribute expected it is not read only. |
| Answer | For the attribute request cases the answer ist a list of attribute values. There is no answer in case of setting new attribute values. |
| Example |
| Command | contents handle_or_instance_path [first_token_index [last_token_index]] |
| Semantic | contents will reply the data of the tokens in a predicate. With first_token_index (the very first token is at index = 0) and last_token_index you can specify a range of tokens you want to have. |
| Answer | The answer is a list of token data entries. |
| Example |
| Command | setcontents handle_or_instance_path new_contents |
| Semantic | setcontents will exchange the contents of the specified predicate against the given new data. The format of the data has to be the same like contents would report afterwards. |
| Answer | |
| Example |
| Command | enummode names | value | both |
| Semantic | enummode changes the style when enum data will be reported. In case of both the enumerator name and its value will be reported as tupel. |
| Answer | |
| Example |
| Command | getcauses place | trans | arc | all |
| Semantic |
getcauses is a report function which lists the valid event cause strings.
|
| Answer | |
| Example |
| Command | getattributes module | place | trans | arc [hint] [filter] [readonly] [history] |
| Semantic | getattributes lists valid attribute strings. With hint a short explanation will be added. With filter the name of the prefered data value filter will be added. With readonly you will get an additional boolean value for this attribute. So an entry can contain {attribute_name attribute_hint attribute_filter attribute_readonly}. With history you will get only those attributes which you can specify in a gethistory command. |
| Answer | |
| Example |
| Command | handle full_instance_name [full_instance_name_list] |
| Semantic | handle will reply an integer handle as an unique representation of each of the requested instances. A full instance name is a path from the top module called model down to the instance itself with '.' as divider. |
| Answer | The instance handle as integer or a list of integer handles. |
| Example |
Assuming the top model is named airport and it contains a sub module RunWay: handle airport.RunWay could reply 3 |
| Command | instance module | place | trans | arc instance_handle [instance_handle_list] |
| Semantic | instance will reply a full name for each of the requested instance handles. The kind of instance you mean has to be specified by module | place | trans | arc. |
| Answer | The full instance name or a list of full instance names. |
| Example |
Assuming the top model is named airport and it contains a sub module RunWay: handle airport.RunWay answered 3 then instance module 3 will answer airport.RunWay |
| Command | licenceinfo [all] |
| Semantic | licenceinfo will report the licencee information as string. With all you will get more details. |
| Answer | |
| Example |
| Command | profileinfo |
| Semantic | profileinfo will report a list of string tupels in form of property value which will inform you about model size and performance details. |
| Answer | |
| Example |
| Command | runmode |
| Semantic | runmode asks the server for the mode it is running in. |
| Answer |
The answers can be:
|
| Example |
| Command | timeout [new_timeout_seconds] |
| Semantic | timeout request the valid timeout value in seconds for the server to client communication. If new_timeout_seconds is given this value will be set first. |
| Answer | The answer is an integer value for the count of timeout seconds. |
| Example |
| Command | createmodel module_type |
| Semantic | To begin any experiment operations you will need a model. After loading the shared model code via link_code you can make one of the loaded module types the model you want to investigate. In result you will get an appropriate answer to model. |
| Answer | |
| Example |
| Command | closemodel |
| Semantic | closemodel will destroy the loaded model. After this the server can load a new model via createmodel. |
| Answer | |
| Example |
| Command | closeserver |
| Semantic | closeserver will stop any calculation. All resources will be released and the server task will destroy itself immediately. |
| Answer | |
| Example |
| Command | savestate stream_handle | file_path |
| Semantic | savestate will save the actual state of the model persistent to the given stream. If not a stream handle but a file path is given savestate will try to open a stream internaly. |
| Answer | |
| Example |
| Command | loadstate stream_handle | file_path |
| Semantic | loadstate will load the persistent saved information from a stream or a file. The command will check at first whether the loaded shared code matches the persistent image or not. In some cases it will force problems if you start or continue to run a loaded experiment because user specific C code data is not handled save up to now. But in every case you are able to analyse a reached model situation later via reloading the saved state. |
| Answer | |
| Example |
| Command | fire handle_or_instance_path |
| Semantic | fire asks the server to fire a specific transition just now. Please be careful - this will change the sequence of the experiments automatic behaviour. |
| Answer | |
| Example |
| Command | concession handles| names | both | handle_or_instance_path_list |
| Semantic | concession will generate a list with one entry for each transition acually able to fire. With handles you will get this as list of handles unlike names which forces the generation of a list of full transition names. With both you can get both the name and the handle. If you specify a list of transition handles instead (all means all transitions) you will get a list of boolean values - one value for each transition from you list. The boolean value represents the actual concession of the transition. |
| Answer | |
| Example |
| Command |
run run to simtime time_value run for simtime time_value run to systime time_value run for systime time_value run for eventcount count_value run for transcount count_value run for timestep time_value |
| Semantic | run starts the experiment on the server side running. With the variants of the run command you can specify the stop condition as specified in runmode. A running simulation server will reply a status RUN. |
| Answer | |
| Example |
| Command | stop |
| Semantic | With the stop command a running experiment will pause. A stopped simulation server will reply a status READY. |
| Answer | |
| Example |
| Command | break |
| Semantic |
With the break command a running experiment will pause. A simulation server stopped by break will reply a status BREAK. This command works similar to wait because the command continue will function afterwards. |
| Answer | |
| Example |
| Command | wait |
| Semantic |
With the wait command a running experiment will pause. But a following command continue will continue to run the experiment keeping the last runmode. |
| Answer | |
| Example |
| Command | continue |
| Semantic | With this command you can continue to run the experiment keeping the last runmode. This for the experiment had to be stopped by wait or break. |
| Answer | |
| Example |
| Command |
statistic place | trans | arc handle_or_instance_path_list [boolean_value] statistic place | trans | arc list boolean_value |
| Semantic | statistic controls for which instances of the model statistical data will be calculated and collected. By default for all transitions and predicates the statistic switch is set to on unlike arc which start with statistic switched off. |
| Answer |
With "statistic place | trans | arc handle_or_instance_path_list [boolean_value]"
you can get the actual statistic status for a list of model instances or you can switch all together according the
given boolean_value. For the list you can either use names or handles. Instead of a long list you can use
all with the meaning of all instances of the same kind. With "statistic place | trans | arc list boolean_value" you will get a list of instance handles of the specified kind with their statistic switch equal to boolean_value. |
| Example |
| Command |
history place | trans | arc handle_or_instance_path_list [boolean_value] history place | trans | arc list boolean_value |
| Semantic | history controls for which instances of the model historical data will be collected. Each history entry is a tupel {time_value count_value}. For predicates the token count and for transitions the parallel fire count will be stored. Much other attributes can be calculated on this base. |
| Answer |
With "history place | trans | arc handle_or_instance_path_list [boolean_value]"
you can get the actual history status for a list of model instances or you can switch all together according the
given boolean_value. For the list you can either use names or handles. Instead of a long list you can use
all with the meaning of all instances of the same kind. With "history place | trans | arc list boolean_value" you will get a list of instance handles of the specified kind with their history switch equal to boolean_value. |
| Example |
| Command | deltoken handle_or_instance_path token_index [token_delete_count] |
| Semantic | deltoken will destroy token from a predicate similar to an input arc. The first token in a precicates token list has index 0. If you specify a token_delete_count the server will try to delete so much tokens as specified beginning with the token placed on token_index. Events with the cause PlaceTokenExit will be generated if requested. |
| Answer | |
| Example |
| Command |
puttoken handle_or_instance_path token_string [token_put_count [token_insert_index]] puttoken -default handle_or_instance_path [token_put_count [token_insert_index]] |
| Semantic | puttoken will add one or more tokens to a predicate similar to an output arc. Beside the token data in token_string you can specify an amount with token_put_count and additionally a token_insert_index where the amount of tokens will be filled in. If you use the option -default instead of defined token data the new token will set with default values (0 and/or emtpy strings or characters). |
| Answer | |
| Example |
| Command | changetoken handle_or_instance_path token_string token_change_index [token_change_count] |
| Semantic | With changetoken you can alter the actual value of a specific token. No model arc is able to do the same. If you specify token_change_count the server will try to change the data of so much token as you requested. |
| Answer | |
| Example |
| Command | shifttoken handle_or_instance_path from_index to_index |
| Semantic | With shifttoken you can change the position of a specific token in the token list of a predicate. The first token has an index 0. |
| Answer | |
| Example |
| Command | tokentype handle_or_instance_path_or | module_type.member_name |
| Semantic | With tokentype you can get the type name of the tokens contained in the specified predicate. You can either request an instance or a module type for such an information. |
| Answer | |
| Example |
| Command | animation [boolean_value] |
| Semantic | animation will reply the switch controling whether the animation commands will be collected at server side or not. If a boolean_value is given as parameter this mode will be changed first. If you switch off the collection of animation commands the actual collection will be released immediately. |
| Answer | |
| Example |
| Command | resetmodel |
| Semantic | The command resetmodel will stop a running experiment and will force the model to get into its initial state just as after createmodel. |
| Answer | |
| Example |
| Command |
update update boolean_value |
| Semantic |
update will change the amount of asynchronous events the client will receive. The
most of those events the client has to receipt. And so the simulation server has to wait for
such receiptions. On this background update is a command to reach a maximum number
crunching speed at server side without the need to logout from a running server. |
| Answer |
update without parametes will report the actual set update mode. With update boolean_value you can change the update mode. |
| Example |
| Command |
updatelevel updatelevel integer_value |
| Semantic |
updatelevel can change the amount of asynchronous events the client will receive. The
most of those events the client has to receipt. And so the simulation server has to wait for
such receiptions. On this background updatelevel is a command to reach a maximum number
crunching speed at server side without the need to logout from a running server. The default verbose
level 2 will also be reached by update 1. The silent level 1 on other hand is
reachable with update 0 |
| Answer |
updatelevel without parametes will report the actual set update level. With updatelevel integer_value you can change the update level. |
| Example |
| Command | profiling [boolean_value] |
| Semantic | profiling is an internal state. Switched on the simulation enginge will collect detailed time consumption informations for every transition. |
| Answer | |
| Example |
| Command | broadcast [string_arguments] |
| Semantic | broadcast will send the string_arguments to all clients actually connected to the simulation server. |
| Answer | |
| Example |
| Command | reply [string_arguments] |
| Semantic | reply will send back the string_arguments to the calling client. And so this command is usefull in asynchronous reaction scripts. |
| Answer | |
| Example |
Poses++ server events (asynchronous messages from the simulation server to its clients)
In some cases the Poses++ server sends information to its clients asynchronously.
These are requested but also unexpected server reactions. Requested by the client are
events like Event status status_identifier and Event time time_counter.
status_identifier can be one of:
| 4.6. Command line options and parameter |
|
| 4.6.1. Poses++ daemon (posppd / posppd.exe) |
|
| Options | -t integer_value | this option allows to set the trace level to increase or decrease details and amount of trace information filled into the corresponding log file .../Poses++ 1.7/var/posppd.log |
| -c | this option starts the daemon with child behaviour in relation to the root daemon and so this option is used only internally when the root daemon start childs accepting new client connections | |
| -no_authentication | disables the authentication functions and so the daemon will accept an existing user account without checking its password | |
| -no_socket_inheritance | according to Microsoft: "Under Windows NT and Windows 2000, socket handles are inheritable by default. This feature is often used by a process that wants to spawn a child process and have the child process interact with the remote application on the other end of the connection.". That's why the interacting processes of posppd.exe, posppld.exe and possh.exe use this feature in all win32 environments besides Win95, Win98 and WinME for which a multi theaded routing mechanism with less data throughput is implemented. But unfortunately the socket handle inheritance can behave faulty due to bugs in possibly installed LSP software. In this case you will find stdin/stdout error traces in the log-file of the Poses++ Daemon. As a work around you can switch with -no_socket_inheritance to the behaviour implemented for Win95 and descendants. |
| 4.6.2. Poses++ licence daemon (posppld / posppld.exe) |
|
| licence server host_or_ip | if the Poses++ daemon has no licences in its own authority because the file poses.lic is not existent or is not readable or an existent poses.lic is not prepared for the local machine (f.i. mac address did not match) the licence daemon will try to work as slave daemon connecting the specified ip address to find there a master daemon. A licence daemon without licences and without a specified licence server will try to find another machine in the local area network via a broadcast mechanism. |
| licence trust host_or_ip | network netmask | if the Poses++ daemon has licence authority it will accept by default request connections from slave daemonss from the local area network (broadcast area f.i in a "home" network: 192.168.1.0/255.255.255.0). If additional slave ip addresses or networks should be allowed to connect and so to request licences such trust rules have to be specified. |
| 4.6.3. Poses++ shell (possh / possh.exe) |
|
| 4.6.4. Poses++ compiler (posppc / posppc.exe) |
|
| Options | -b build_filename | this option tell the compiler to produce a build file after compilation. A build file is a short tcl script which collects the necessary build information in tcl variables. This script is usefull to write a tcl based compile & build process like implemented in Poses++ shell which will write the build file to the same directory where the code files *.cod will be stored in. |
| -c code_path | this option tell the compiler a directory where the generated *.cod files should be stored in. | |
| -d | if this option is switch on (default off) the compiler will generate specific debug support (not yet implemented). | |
| -i include_path | with this option a directory can added to the list of directories the compiler will use searching include files. | |
| -l lib_path | with this option a directory can added to the list of directories the compiler will use searching library source files. | |
| -m make_filename |
this option tell the compiler to produce a make file after compilation.
This make file will contain the list of object code files and formal
make file rules to be included in another make file frame which have to define
the necessary makros before:$(MODUL_OBJ_PATH)$(DIR_SLASH)global$(OBJ_EXT): $(MODUL_COD_PATH)$(DIR_SLASH)global$(COD_EXT) $(STD_DEP) $(COMPILE_MODUL) |
|
| -s | this option forces the compiler in a silent mode where only the necessary minimum of information will be reported during the compilation process. | |
| -a | this option switches on all possible compiling information (default is off). If switched on the compiler output will be increased so that every line every include and so on will reported usefull to implement a client dialog showing the compiler progress in detail (default is off). | |
| -t | this option switches an "interactive" behaviour of the compiler on (default is off). This option is usefull for a a frontend development environment with automated watched source code editing. | |
| -u user_source_file | with this option a C/C++ source file can be added to the list of user source files. The Poses++ compiler will not read them but will include information about it in the requested make or build file. | |
| -o | this option switches optimization algorithms on (default: off). | |
| -w / -w- | switched on with -w (which is default) the compiler will produce warning messages of various reasons. Switched of with -w- no warnings will be thrown. |
| 4.6.5. Poses++ server (pospp / pospp.exe) |
|
| Options | -p port_number | this option allows to install the connection listening service for of the Poses++ sever on the specified port if not yet in use. If no port is specified the server will select any free port for this listening service and so more than one server can be activated simultaneously. |
| -t integer_value | this option allows to set the trace level to increase the details and volume of trace information filled into the corresponding log file .../Poses++ 1.7/var/pospp.log | |
| -a alias_string | this option sets any string as an alias. | |
| -c cppid_string | this option sets the cppid which the caller expects and which the server should compare against its binary build parameters. | |
| -s port_number | this option forces the Poses++ server after initialization to send its listening port number via UDP to the given port number and is so a short way for the caller to get back the port of the Poses++ server after start. Another way is to ask the Poses++ daemon via getserver. | |
| -u username | this option allow to specify which user account should be expected. |
| 4.6.6. Poses++ console (posconsole / posconsole.exe) |
|
| 4.7. Hardware and Software Environment |
|
Simulation server
Client applications
| 4.8. Contact & Copyright |
|
|
Poses++ is a product of GPC Gesellschaft für Prozeßautomation & Consulting mbH
copyright © 1996..2009 GPC mbH.
All rights reserved.
Poses++ is free software with licence thresholds. Please refer licence.txt. In case you want to follow the development history you can read details in changes.txt.
Other brand and product names are trademarks or registered trademarks of their respective holders.
|
|
